О чартах

Чарты в werf – это Helm-чарты с некоторыми дополнительными возможностями. А Helm-чарты – это распространяемые пакеты с Helm-шаблонами, values-файлами и некоторыми метаданными. Из чартов формируются конечные Kubernetes-манифесты для дальнейшего развертывания.

Создание нового чарта

При развертывании c werf converge или публикации c werf bundle publish используется чарт, лежащий в директории .helm в корне Git-репозитория. Этот чарт называется основным. Директорию основного чарта можно изменить директивой deploy.helmChartDir файла werf.yaml.

Для обычного чарта требуется создание файла Chart.yaml и указание в нём имени и версии чарта:

# Chart.yaml:
apiVersion: v2
name: mychart
version: 1.2.3

А вот для основного чарта это не обязательно, т. к. при отсутствии файла Chart.yaml или отсутствии в нём имени или версии чарта будет использована следующая конфигурация:

# .helm/Chart.yaml:
apiVersion: v2
name: <имя проекта werf>
version: 1.0.0

Если такая конфигурация основного чарта вас не устраивает, то создайте файл .helm/Chart.yaml самостоятельно и переопределите вышеупомянутые директивы.

В случае, если ваш чарт будет содержать только именованные шаблоны для использования в других чартах, добавьте в Chart.yaml директиву type: library:

# Chart.yaml:
type: library

Если ваш чарт совместим только с частью версий Kubernetes, то ограничьте версии кластера Kubernetes, в которые чарт можно развернуть, директивой kubeVersion, например:

# Chart.yaml:
kubeVersion: "~1.20.3"

При желании можно добавить следующие информационные директивы:

# Chart.yaml:
appVersion: "1.0"
deprecated: false
icon: https://example.org/mychart-icon.svg
description: This is My Chart
home: https://example.org
sources:
  - https://github.com/my/chart
keywords:
  - apps
annotations:
  anyAdditionalInfo: here
maintainters:
  - name: John Doe
    email: john@example.org
    url: https://john.example.org

Полученный чарт уже можно развернуть или опубликовать, хотя в таком виде от него мало пользы. Теперь вам понадобится, по меньшей мере, либо добавить шаблоны в директорию templates, либо подключить зависимые чарты.

Добавление файлов в чарт

По мере необходимости добавьте в чарт шаблоны, параметры, зависимые чарты и прочее. Содержимое основного чарта может выглядеть так:

.helm/
  charts/
    dependent-chart/
      # ...
  templates/
    deployment.yaml
    _helpers.tpl
    NOTES.txt
  crds/
    crd.yaml
  secret/                   # Только в werf
    some-secret-file
  values.yaml
  values.schema.json
  secret-values.yaml        # Только в werf
  Chart.yaml
  Chart.lock
  README.md
  LICENSE
  .helmignore

Подробнее:

  • charts/* — зависимые чарты, чьи Helm-шаблоны/values-файлы используются для формирования манифестов наравне с Helm-шаблонами/values-файлами родительского чарта;

  • templates/*.yaml — Helm-шаблоны, из которых формируются Kubernetes-манифесты;

  • templates/*.tpl — файлы с Helm-шаблонами для использования в других Helm-шаблонах. Результат шаблонизации этих файлов игнорируется;

  • templates/NOTES.txt — werf отображает содержимое этого файла в терминале в конце каждого удачного развертывания;

  • crds/*.yaml — Custom Resource Definitions, которые развертываются до развертывания манифестов в templates;

  • secret/* — (только в werf) зашифрованные файлы, расшифрованное содержимое которых можно подставлять в Helm-шаблоны;

  • values.yaml — файлы с декларативной конфигурацией для использования в Helm-шаблонах. Конфигурация в них может переопределяться переменными окружения, аргументами командной строки или другими values-файлами;

  • values.schema.json — JSON-схема для валидации values.yaml;

  • secret-values.yaml — (только в werf) зашифрованный файл с декларативной конфигурацией, аналогичный values.yaml. Его расшифрованное содержимое объединяется с values.yaml во время формирования манифестов;

  • Chart.yaml — основная конфигурация и метаданные чарта;

  • Chart.lock — lock-файл, защищающий от нежелательного изменения/обновления зависимых чартов;

  • README.md — документация чарта;

  • LICENSE — лицензия чарта;

  • .helmignore — список файлов в директории чарта, которые не нужно включать в чарт при его публикации.

Подключение дополнительных чартов

Подключение зависимых локальных чартов

Подключить зависимые локальные чарты можно, положив их в директорию charts родительского чарта. В таком случае манифесты сформируются и для родительского, и для зависимых чартов, после чего объединятся вместе для дальнейшего развертывания. Дополнительная конфигурации не обязательна.

Пример содержимого основного чарта, имеющего локальные зависимые чарты:

.helm/
  charts/
    postgresql/
      templates/
        postgresql.yaml
      Chart.yaml
    redis/
      templates/
        redis.yaml
      Chart.yaml
  templates/
    backend.yaml

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

Если локальному зависимому чарту требуется дополнительная конфигурация, то в файле Chart.yaml родительского чарта укажите имя зависимого чарта без указания dependencies[].repository и добавьте интересующие директивы таким образом:

# .helm/Chart.yaml:
apiVersion: v2
dependencies:
- name: redis
  condition: redis.enabled

При необходимости подключить локальный чарт не из директории charts, а из другого места, используйте директиву dependencies[].repository так:

# .helm/Chart.yaml:
apiVersion: v2
dependencies:
- name: redis
  repository: file://../redis

Подключение зависимых чартов из репозитория

Подключить дополнительные чарты из OCI/HTTP-репозитория можно, указав их как зависимые в директиве dependencies файла Chart.yaml родительского чарта. В таком случае манифесты сформируются и для родительского, и для зависимых чартов, после чего объединятся вместе для дальнейшего развертывания.

Пример конфигурации чарта из репозитория, зависимого от основного чарта:

# .helm/Chart.yaml:
apiVersion: v2
dependencies:
- name: database
  version: "~1.2.3"
  repository: https://example.com/charts

После каждого добавления/обновления удалённых зависимых чартов или изменения их конфигурации требуется:

  1. (Если используется приватный OCI или HTTP-репозиторий c зависимым чартом) Добавить OCI или HTTP-репозиторий вручную с werf helm repo add, указав нужные опции для доступа к репозиторию.

  2. Вызвать werf helm dependency update, который обновит Chart.lock.

  3. Закоммитить обновлённые Chart.yaml и Chart.lock в Git.

Также при использовании чартов из репозитория рекомендуется добавить .helm/charts/**.tgz в .gitignore.

Указание имени подключаемого чарта

В директиве dependencies[].name родительского чарта указывается оригинальное имя зависимого чарта, установленное его разработчиком, например:

# .helm/Chart.yaml:
apiVersion: v2
dependencies:
- name: backend

Если нужно подключить несколько зависимых чартов с одинаковым именем или подключить один и тот же зависимый чарт несколько раз, то используйте директиву dependencies[].alias родительского чарта, чтобы поменять имена подключаемых чартов, например:

# .helm/Chart.yaml:
apiVersion: v2
dependencies:
- name: backend
  alias: main-backend
- name: backend
  alias: secondary-backend

Указание версии подключаемого чарта

Ограничить подходящие версии зависимого чарта, из которых будет выбрана наиболее свежая, можно директивой dependencies[].version родительского чарта, например:

# .helm/Chart.yaml:
apiVersion: v2
dependencies:
- name: backend
  version: "~1.2.3"

Результат: будет использована самая свежая версия 1.2.x, но как минимум 1.2.3.

Указание источника подключаемого чарта

Указать путь к источнику чартов, в котором можно найти указанный зависимый чарт, можно директивой dependencies[].repository родительского чарта, например:

# .helm/Chart.yaml:
apiVersion: v2
dependencies:
- name: mychart
  repository: oci://example.org/myrepo

Результат: будет использован чарт mychart из OCI-репозитория example.org/myrepo.

Включение/отключение зависимых чартов

По умолчанию все зависимые чарты включены. Для произвольного включения/отключения зависимых чартов можно использовать директиву dependencies[].condition родительского чарта, например:

# .helm/Chart.yaml:
apiVersion: v2
dependencies:
- name: backend
  condition: backend.enabled

Результат: зависимый чарт backend будет включен, только если параметр $.Values.backend.enabled имеет значение true (по умолчанию — true).

Также можно использовать директиву dependencies[].tags родительского чарта для включения/отключения целых групп зависимых чартов сразу, например:

# .helm/Chart.yaml:
dependencies:
- name: backend
  tags: ["app"]
- name: frontend
  tags: ["app"]

Результат: зависимые чарты backend и frontend будут включены, только если параметр $.Values.tags.app имеет значение true (по умолчанию — true).