Werf-специфика чарта

Что нужно знать перед уроком

M4 урок 1 — стандартная структура Helm-чарта (Chart.yaml/values.yaml/templates//crds/). Здесь — что добавляет werf сверху, и почему структура Application-пакета (уже видели в M5 уроке 1 как анонс) отличается от ванильного Helm-чарта именно этими директориями.

Теория

.helm/secret/ и .helm/secret-values.yaml — то, чего нет в ванильном Helm

vikunja/
├── Chart.yaml
├── values.yaml
├── .helm/
│   ├── secret-values.yaml    # зашифрованные значения (аналог values.yaml, но encrypted)
│   ├── secret/                # зашифрованные произвольные файлы (сертификаты, крупные конфиги)
│   │   └── tls-cert.pem
│   └── crds/                  # werf-специфичная альтернативная директория для CRD (в дополнение к vanilla crds/)
└── templates/

Ванильный Helm не имеет встроенного механизма шифрования значений/файлов внутри самого чарта — секреты обычно передаются извне (--set-file, внешние Secret-провайдеры, sealed-secrets и подобные надстройки). Nelm/werf добавляет собственный слой: .helm/secret-values.yaml — файл, структурно аналогичный values.yaml, но зашифрованный отдельным ключом (NELM_SECRET_KEY), расшифровываемый в памяти во время рендера шаблонов, никогда не попадающий на диск в открытом виде вне момента редактирования. .helm/secret/ — та же идея, но для произвольных файлов (не отдельных значений) — сертификатов, приватных ключей, крупных конфигурационных файлов, которые неудобно хранить как одно значение в YAML.

Доступ к секретам из шаблонов

1
2
3

# .helm/secret-values.yaml (зашифрован, содержимое показано в расшифрованном виде для понимания)
database:
  password: "supersecretpassword"

1
2
3
4
5
6
7

# templates/secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: {{ .Release.Name }}-db-credentials
stringData:
  password: {{ .Values.database.password }}   # обратите внимание: .Values, а не отдельный объект — секреты из secret-values.yaml мержатся в общий .Values

1
2
3

# templates/configmap.yaml — для крупного файла из .helm/secret/
data:
  tls-cert.pem: { { werf_secret_file "tls-cert.pem" | b64enc } }

Ключевое отличие в доступе: значения из secret-values.yaml становятся частью того же самого .Values объекта, что и обычный values.yaml (они мержатся в единое дерево значений) — с точки зрения шаблона {{ .Values.database.password }} не отличается синтаксически от обычного значения. Файлы из .helm/secret/, напротив, требуют отдельной шаблонной функции werf_secret_file (детальный разбор всех шаблонных функций — M7 урок 7), т.к. это не одно значение, а целый файл, который нужно явно встроить и обычно закодировать (b64enc) для полей типа data в Secret/ConfigMap.

.helm/crds/ vs vanilla crds/

Помимо стандартной директории crds/ из ванильного Helm (M4 урок 1), werf-чарты используют собственную .helm/crds/ как альтернативное расположение — исторически возникшее из werf-специфичного пайплайна деплоя до стандартизации crds/ в самом Helm. Для Application-пакетов курса эта директория не актуальна вообще (Application не объявляет CRD, M5 урок 5) — упоминается здесь только для полноты общего Helm/werf-контекста, который вы неизбежно встретите при чтении документации Module (даже не разрабатывая их).

Частые ошибки и подводные камни

• Хранить пароли/токены прямо в обычном values.yaml вместо .helm/secret-values.yaml. Обычный values.yaml — открытый текст, попадающий в Git-историю в читаемом виде; для реальных секретов нужен именно зашифрованный файл.
• Путать секреты сборки werf (secrets: в werf.yaml, M3 урок 6) с секретами деплоя (.helm/secret-values.yaml/.helm/secret/). Это две принципиально разные категории по времени жизни: build-time секреты существуют только во время сборки образа, deploy-time секреты — во время рендера/применения чарта; они решают разные задачи и никак не связаны технически.
• Забыть, что расшифровка происходит только в памяти на этапе Render. Расшифрованное значение никогда не должно записываться на диск в открытом виде вручную (например, через dump_debug в продакшен-логах) — иначе смысл шифрования теряется.

Практика в кластере

Практики в кластере пока нет — фокус на структуре чарта, первая реальная установка — с M4 урока 5.

Практика разработки

1. Создайте ключ шифрования и зашифрованный файл значений для пароля БД Vikunja:

1
2
3
4
5
6

export NELM_SECRET_KEY="$(nelm chart secret key create)"
echo "Сохраните NELM_SECRET_KEY в защищённом хранилище CI — без него секреты нельзя расшифровать"
nelm chart secret values-file edit .helm/secret-values.yaml
# в открывшемся редакторе впишите:
# database:
#   password: "vikunja-demo-password"

2. Убедитесь, что файл на диске зашифрован (не читается как обычный YAML):

1

cat .helm/secret-values.yaml   # должен быть нечитаемый зашифрованный вывод

3. Добавьте templates/secret.yaml, использующий значение из зашифрованного файла, и отрендерите с явной передачей ключа:

1
2
3
4
5
6

apiVersion: v1
kind: Secret
metadata:
  name: {{ .Release.Name }}-db-credentials
stringData:
  password: {{ .Values.database.password | quote }}

1

nelm chart render . -r vikunja-demo

Убедитесь, что в отрендеренном выводе пароль появляется в открытом виде (это ожидаемо — рендер расшифровывает в памяти именно для формирования финального манифеста, который затем применяется в кластер уже как обычный Secret).

Шпаргалка команд урока

1
2
3
4

nelm chart secret key create
nelm chart secret values-file edit <path>
nelm chart secret values-file encrypt/decrypt <path>
nelm chart secret file edit/encrypt/decrypt <path>

Полная шпаргалка Nelm: 📋 nelm , будет пополняться в M4/M7.

Вопросы для самопроверки

Рекомендуемая литература

Официальная документация

• Deckhouse — Nelm-аннотации для Application

Статьи и блоги

• Вышла werf 2.0: новый движок развёртывания Nelm — Flant на Habr.
• Представляем werf 1.0 stable: GitOps и Helm — Flant на Habr.
• GitLab + K8s + Werf — Habr.

Книги

• Matt Butcher, Matt Farina, Josh Dolitsky. Learning Helm. 2019. ISBN 978-1492036781.

Связанные материалы

• Предыдущий урок: M4.01 — Анатомия Helm-чарта.
• Следующий урок: M4.03 — Почему Helm 3 сменили на Nelm.
• Полный разбор шаблонных функций секретов: M7 урок 7.

✓ Урок пройден — все вопросы самопроверки отвечены верно