Provision
—— XP

Практика: чарт стенда

практика~50 минут+650 XP

Стенд описан девятью файлами в ~/infra/k8s/base. Имя provision-app встречается в них больше десяти раз, а пространство имён прописано в каждом. Сейчас ты превратишь этот каталог в чарт: будешь переносить файлы по одному и заменять повторяющееся на подстановки.

Начнём с чарта из одного ConfigMap, скопированного как есть, и после каждого шага будем собирать чарт и смотреть, что получилось. Писать с нуля почти ничего не придётся — это и есть обычная работа: чарт собирают из уже работающих описаний. В кластер в этой практике ты не пойдёшь вообще: всё проверяется локально.

Шаг 1. Каркас

Helm умеет создать заготовку чарта с правильной раскладкой. Заведи для чартов каталог в репозитории.

ubuntu@stand:~$
mkdir -p ~/infra/helm
ubuntu@stand:~$
cd ~/infra/helm
ubuntu@stand:~$
helm create provision
ubuntu@stand:~$
Creating provision

Загляни в каркас.

ubuntu@stand:~$
ls provision
ubuntu@stand:~$
Chart.yaml  charts  templates  values.yaml

Ровно три обязательные части из урока и пустой каталог charts для зависимостей. В templates Helm положил заготовки — универсальный Deployment, сервис, Ingress и ещё несколько. Они полезны как пример, но чужой код в своём чарте — источник сюрпризов, поэтому шаблоны будут свои. Удали заготовки; флаг -r удаляет и вложенный каталог с тестами.

ubuntu@stand:~$
rm -r provision/templates/*

Шаг 2. Паспорт и пустые значения

Открой nano provision/Chart.yaml, удали всё и набери короткий паспорт.

provision/Chart.yaml
apiVersion: v2
name: provision
description: Учебный стенд курса
type: application
version: 0.1.0
appVersion: "1.0.0"

version — версия самого чарта, appVersion — версия приложения внутри, тег образа, который ты импортировал в кластер. Пригодится в шаге 9. Теперь открой nano provision/values.yaml и удали из него всё: значения будем добавлять по одному, когда они понадобятся.

Шаг 3. Один файл как есть

Дальше работаем внутри каталога чарта: так команды короче.

ubuntu@stand:~$
cd provision

Перенеси в чарт первый файл стенда — ConfigMap, ничего в нём не меняя.

ubuntu@stand:~$
cp ~/infra/k8s/base/10-configmap.yaml templates/

Сразу две проверки. helm lint ищет ошибки в чарте, точка — чарт в текущем каталоге.

ubuntu@stand:~$
helm lint .
ubuntu@stand:~$
==> Linting .
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed

[INFO] про иконку — совет, а не ошибка. Строки [ERROR] назовут файл и строку, где сломалось. helm template собирает чарт и печатает то, что ушло бы в кластер; первое слово после команды — имя релиза.

ubuntu@stand:~$
helm template provision .
ubuntu@stand:~$
---
# Source: provision/templates/10-configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: provision-config
  namespace: provision
data:
  LOG_LEVEL: info
  DB_HOST: provision-db
  ...

Чарт из одного файла уже работает: Helm отдал файл ровно таким, какой он есть. Теперь начнём заменять зашитое.

Шаг 4. Убрать пространство имён

Пространство имён задают при установке, флагом -n, и Helm сам кладёт объекты туда. Жёстко прописанное namespace: provision этому мешает: поставишь чарт в другое пространство — объект всё равно уедет в provision. Удали строку. sed с флагом -i правит файл на месте, а команда /шаблон/d удаляет строки, где шаблон нашёлся.

ubuntu@stand:~$
sed -i '/namespace: provision/d' templates/10-configmap.yaml

Эту же команду повторишь для каждого следующего файла.

Шаг 5. Имя из релиза

Один чарт можно поставить дважды — например, для двух сред в одном кластере. Тогда имена объектов не должны совпадать. Собери чарт под другим именем релиза и посмотри на имя ConfigMap.

ubuntu@stand:~$
helm template test . | grep name:
ubuntu@stand:~$
  name: provision-config

Релиз test, а имя прежнее — второй релиз затёр бы ConfigMap первого. Открой nano templates/10-configmap.yaml и замени имя на подстановку.

templates/10-configmap.yaml, имя
  name: {{ .Release.Name }}-config

Двойные фигурные скобки — место подстановки, .Release.Name — имя релиза, которое ты указываешь в команде.

ubuntu@stand:~$
helm template test . | grep name:
ubuntu@stand:~$
  name: test-config

Шаг 6. Первое значение

Уровень журнала приложения — то, что в разных средах разное. Вынесем его в значения. Допиши в values.yaml:

values.yaml
config:
  logLevel: info

А в ConfigMap замени строку LOG_LEVEL.

templates/10-configmap.yaml, LOG_LEVEL
  LOG_LEVEL: {{ .Values.config.logLevel | quote }}

.Values.config.logLevel — путь к значению в values.yaml. | quote берёт его в кавычки. Зачем — видно на значении, которое YAML поймёт не как строку. Флаг --set подменяет значение прямо в команде. Имя релиза здесь не важно, и его можно не писать — Helm подставит release-name.

ubuntu@stand:~$
helm template . --set config.logLevel=true | grep LOG
ubuntu@stand:~$
  LOG_LEVEL: "true"

Без | quote здесь вышло бы LOG_LEVEL: true — логическое значение, а не строка, и кластер отверг бы такой ConfigMap: все его значения обязаны быть строками. С quote любое значение доезжает строкой.

Шаг 7. Deployment

Второй файл — Deployment. Скопируй его и убери пространство имён той же командой sed, что в шаге 4.

ubuntu@stand:~$
cp ~/infra/k8s/base/30-deployment.yaml templates/

Число копий — тоже значение. Допиши в начало values.yaml:

values.yaml, в начало
replicaCount: 3

В 30-deployment.yaml три замены: число копий, имя Deployment и имя ConfigMap в блоке envFrom.

templates/30-deployment.yaml, три строки
  name: {{ .Release.Name }}-{{ .Chart.Name }}
  replicas: {{ .Values.replicaCount }}
                name: {{ .Release.Name }}-config

Меняй только значения после двоеточия — отступы у строк в файле уже правильные, а YAML не прощает ни одного лишнего пробела. .Chart.Name — имя чарта из паспорта.

Флаг -A4 у grep показывает ещё четыре строки после найденной.

ubuntu@stand:~$
helm template provision . | grep -A4 'kind: Deployment'
ubuntu@stand:~$
kind: Deployment
metadata:
  name: provision-provision
spec:
  replicas: 3

Имя provision-provision выглядит странно, но так и задумано: релиз provision чарта provision. Поставишь релиз test — будет test-provision.

Шаг 8. Имя и метки — в одном месте

Запись {{ .Release.Name }}-{{ .Chart.Name }} понадобится сервису, базе, миграции и входу — пять копий одной строки. А в Deployment ещё остались зашитые метки app: provision-app. Общее выносят в именованные шаблоны — файл _helpers.tpl. Подчёркивание в начале имени говорит Helm: это не объект для кластера, а заготовки. Создай nano templates/_helpers.tpl.

templates/_helpers.tpl
{{- define "provision.fullname" -}}
{{ .Release.Name }}-{{ .Chart.Name }}
{{- end }}

{{- define "provision.selectorLabels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

Первый собирает полное имя объектов, второй — метки, по которым Deployment и сервис найдут поды. Ключи app.kubernetes.io/… — общепринятые имена меток, их понимают и Helm, и панели вроде k9s. Дефисы в {{- и -}} убирают лишние переносы строк вокруг.

В 30-deployment.yaml замени имя и обе пары меток — в selector и в шаблоне пода.

templates/30-deployment.yaml, начало
  name: {{ include "provision.fullname" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "provision.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "provision.selectorLabels" . | nindent 8 }}

include вставляет именованный шаблон, точка после имени передаёт ему все данные чарта. nindent 6 вставляет метки с переносом и отступом в шесть пробелов — ровно на уровень matchLabels. Без nindent метки встанут без отступа, и helm lint ответит так:

ubuntu@stand:~$
[ERROR] templates/30-deployment.yaml: unable to parse YAML: error converting YAML to JSON: yaml: line 11: mapping values are not allowed in this context

Посмотри на собранный Deployment.

ubuntu@stand:~$
helm template provision . | grep -A8 'kind: Deployment'
ubuntu@stand:~$
kind: Deployment
metadata:
  name: provision-provision
spec:
  replicas: 3
  selector:
    matchLabels:
      app.kubernetes.io/name: provision
      app.kubernetes.io/instance: provision

Селекторные метки после первой установки не меняют: поле selector у Deployment неизменяемо, и обновление упадёт с ошибкой field is immutable. Поэтому в них только имя и релиз — никакой версии.

Шаг 9. Образ и секрет

В Deployment остались образ и имя секрета. Допиши в values.yaml:

values.yaml
image:
  repository: localhost:5000/provision/app
  tag: ""          # пусто — взять appVersion

existingSecret: provision-secrets

Пароля здесь нет и не будет: значения лежат в git. existingSecret — только имя секрета, который создаётся отдельно, как в прошлом разделе. В Deployment замени строку image и имя секрета в secretKeyRef.

templates/30-deployment.yaml, образ
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
templates/30-deployment.yaml, секрет
                  name: {{ .Values.existingSecret }}

| default .Chart.AppVersion значит: если тег пуст, взять appVersion из паспорта. Кавычки вокруг значения обязательны: без них YAML споткнётся о двоеточие и фигурные скобки.

ubuntu@stand:~$
helm template provision . | grep image:
ubuntu@stand:~$
          image: "localhost:5000/provision/app:1.0.0"
ubuntu@stand:~$
helm template . --set image.tag=1.1.0 | grep image:
ubuntu@stand:~$
          image: "localhost:5000/provision/app:1.1.0"

Тег из паспорта по умолчанию, и любой другой — одним значением, без правки шаблона. Так конвейер CI будет выкатывать новую версию.

Шаг 10. Сервис

Дальше файлы пойдут быстрее: схема одна. Скопируй сервис и убери пространство имён.

ubuntu@stand:~$
cp ~/infra/k8s/base/31-service.yaml templates/

В 31-service.yaml замени имя и селектор.

templates/31-service.yaml
  name: {{ include "provision.fullname" . }}
spec:
  selector:
    {{- include "provision.selectorLabels" . | nindent 4 }}
ubuntu@stand:~$
helm template provision . | grep kind:
ubuntu@stand:~$
kind: ConfigMap
kind: Service
kind: Deployment

Шаг 11. База

Размер диска базы — в значения.

values.yaml
database:
  storage: 1Gi

Скопируй 20-database.yaml и убери пространство имён. Правок в нём больше, чем в других: объектов два. Имена сервиса, StatefulSet и serviceName — {{ include "provision.fullname" . }}-db. Метки app: provision-db — в селекторе сервиса, в matchLabels и в метках шаблона пода — замени парой:

templates/20-database.yaml, вместо app: provision-db
app.kubernetes.io/name: provision-db
app.kubernetes.io/instance: {{ .Release.Name }}

Пара меток вместо одной нужна для второй установки чарта: у базы каждого релиза будет своё instance, и сервис одного релиза не увидит базу другого. Отступ у каждой строки — как у метки, которую она заменяет. В блоке env два имени ConfigMap станут {{ .Release.Name }}-config, имя секрета — {{ .Values.existingSecret }}, а в конце файла размер диска:

templates/20-database.yaml, конец
            storage: {{ .Values.database.storage }}

Адрес базы приложение берёт из ConfigMap, и он тоже зависит от релиза. В 10-configmap.yaml замени строку DB_HOST.

templates/10-configmap.yaml, DB_HOST
  DB_HOST: {{ include "provision.fullname" . }}-db
ubuntu@stand:~$
helm template provision . | grep -e kind: -e DB_HOST
ubuntu@stand:~$
kind: ConfigMap
  DB_HOST: provision-provision-db
kind: Service
kind: Service
kind: Deployment
kind: StatefulSet

Шаг 12. Миграция

Скопируй 25-migrate.yaml, убери пространство имён и сделай те же замены, что в Deployment: имя Job — {{ include "provision.fullname" . }}-migrate, строка image — как в шаге 9, имена ConfigMap и секрета — тоже. Всё, что совпадало с именем стенда, становится подстановкой.

ubuntu@stand:~$
helm template provision . | grep kind:
ubuntu@stand:~$
kind: ConfigMap
kind: Service
kind: Service
kind: Deployment
kind: StatefulSet
kind: Job

Шаг 13. Вход с выключателем

Вход нужен не везде: в среде без внешнего адреса он лишний. Пусть выключается значением. Допиши в values.yaml:

values.yaml
ingress:
  enabled: true
  host: stand.provision.internal

Скопируй 40-middleware.yaml и 41-ingress.yaml и убери из обоих пространство имён. Добавь первой строкой каждого файла условие, а последней — его конец.

первая и последняя строки обоих файлов
{{- if .Values.ingress.enabled }}
...
{{- end }}

Условие охватывает весь файл, включая apiVersion: стоит оно в середине — и при выключенном входе Helm соберёт обрывок описания. Внутри 41-ingress.yaml замени имя объекта и имя сервиса на {{ include "provision.fullname" . }}, а имя сайта — на {{ .Values.ingress.host }}. Аннотация ссылается на обработчик по имени вместе с пространством имён:

templates/41-ingress.yaml, аннотация
    traefik.ingress.kubernetes.io/router.middlewares: {{ .Release.Namespace }}-{{ include "provision.fullname" . }}-strip-api@kubernetescrd

В 40-middleware.yaml замени name: strip-api на name: {{ include "provision.fullname" . }}-strip-api — имя должно совпасть с аннотацией.

ubuntu@stand:~$
helm template provision . | grep kind:
ubuntu@stand:~$
kind: ConfigMap
kind: Service
kind: Service
kind: Deployment
kind: StatefulSet
kind: Job
kind: Ingress
kind: Middleware

Весь стенд, кроме пространства имён и секрета. Порядок Helm выбирает сам — по типам объектов, а не по номерам файлов: настройки раньше нагрузок. Проверь выключатель.

ubuntu@stand:~$
helm template . --set ingress.enabled=false | grep kind:
ubuntu@stand:~$
kind: ConfigMap
kind: Service
kind: Service
kind: Deployment
kind: StatefulSet
kind: Job

Ни Ingress, ни Middleware — оба файла выключились целиком.

Шаг 14. Подпись настроек

Помнишь ловушку из прошлого раздела: поменял ConfigMap — а поды работают со старыми настройками, пока их не пересоздашь руками. Чарт её не лечит. Собери чарт в файл, поменяй в values.yaml уровень журнала с info на debug, собери во второй файл и сравни. Знак > пишет вывод команды в файл, программа diff печатает различия двух файлов.

ubuntu@stand:~$
helm template provision . > a.yaml
ubuntu@stand:~$
helm template provision . > b.yaml
ubuntu@stand:~$
diff a.yaml b.yaml
ubuntu@stand:~$
8c8
<   LOG_LEVEL: "info"
---
>   LOG_LEVEL: "debug"

Поменялась одна строка, в ConfigMap. Шаблон пода у Deployment одинаковый — и он ничего не пересоздаст. Лекарство — подпись настроек. Допиши в 30-deployment.yaml под метками шаблона пода, на одном уровне с labels:

templates/30-deployment.yaml, после labels шаблона пода
      annotations:
        checksum/config: {{ include (print $.Template.BasePath "/10-configmap.yaml") . | sha256sum }}

Helm собирает ConfigMap, считает от него хеш sha256sum и кладёт в аннотацию пода. Верни info, повтори три команды выше, снова поставив debug между ними.

ubuntu@stand:~$
8c8
<   LOG_LEVEL: "info"
---
>   LOG_LEVEL: "debug"
59c59
<         checksum/config: 63be3c1531eb99ccc86743b4de40c98fcc0cc13dd5c9609eae32b5b5f92078e3
---
>         checksum/config: 1726fc9e3cac100f8b73dcf8569e40f5f3d886449a7156d411e111a31a6a1ece

Поменялись настройки — поменялся хеш, а значит и шаблон пода, и Deployment пересоздаст поды сам. Верни в values.yaml значение info и удали временные файлы: rm a.yaml b.yaml.

Шаг 15. Итоговая проверка

Чарт готов. Проверь его целиком, как это сделает команда сдачи.

ubuntu@stand:~$
helm lint .
ubuntu@stand:~$
1 chart(s) linted, 0 chart(s) failed
ubuntu@stand:~$
helm template provision . | grep -e checksum -e image:
ubuntu@stand:~$
        checksum/config: 63be3c1531eb99ccc86743b4de40c98fcc0cc13dd5c9609eae32b5b5f92078e3
          image: "localhost:5000/provision/app:1.0.0"
          image: postgres:17-alpine
          image: "localhost:5000/provision/app:1.0.0"

Подпись в шаблоне пода, тег из appVersion и у приложения, и у миграции. Если вместо этого Helm упал с nil pointer, в шаблоне опечатка в пути к значению — сверь его с values.yaml.

Что дальше

Чарт собирается и проверен без кластера. В следующем уроке — что происходит при установке, обновлении и откате релиза, а потом ты поставишь стенд чартом.

Практика 02+650 XP

Превратить каталог описаний в чарт с параметрами и проверять собранный результат командами helm lint и helm template, не трогая кластер.

  • Чарт проходит проверку
  • В чарте весь стенд
  • Подпись настроек на месте
  • Образ собирается из значений
Команда сдачи — выполни на своей машине
команда
cd ~/infra/helm; helm lint ./provision; helm template provision ./provision | grep -E 'kind:|checksum|image:'

Нашёл ошибку или непонятное место? Наведи на абзац — слева появится «+», нажми и напиши, что не так. Замечание увидит автор курса.Нашёл ошибку или непонятное место? Нажми «+» справа от заголовка раздела и напиши, что не так. Замечание увидит автор курса.