Зависимости чартов / Конфигурация / Helm / Документация продвинутого уровня

Сабчарт — это helm-чарт, который включён в текущий чарт в качестве зависимости. werf позволяет использование сабчартов тем же способом как helm. Чарт может включать произвольное количество зависимых сабчартов. Использование проекта werf в качестве сабчарта в другом проекте werf на данный момент не поддерживается.

Сабчарты располагаются в директории .helm/charts/SUBCHART_DIR. Каждый сабчарт в директории SUBCHART_DIR сам по себе является чартом и имеет схожую файловую структуру (каждый сабчарт может в свою очередь также содержать сабчарт).

Во время процесса деплоя werf рендерит, создает и отслеживает все ресурсы всех сабчартов.

Включение сабчарта для проекта

Определим зависимость redis для нашего werf чарта с помощью файла .helm/Chart.yaml:
```
 # .helm/Chart.yaml
 apiVersion: v2
 dependencies:
   - name: redis
     version: "12.7.4"
     repository: "https://charts.bitnami.com/bitnami"
```
ЗАМЕЧАНИЕ. Необязательно определять полный Chart.yaml с именем и версией как для стандартного helm-чарта. werf генерирует имя чарта и версию на основе директивы project из файла werf.yaml. См. больше информации в статье про чарты.
Далее требуется сгенерировать .helm/Chart.lock с помощью команды werf helm dependency update.
```
 werf helm dependency update .helm
```
Данная команда создаст .helm/Chart.lock и скачает все зависимости в директорию .helm/charts.
Файл .helm/Chart.lock следует коммитнуть в git репозиторий, а директорию .helm/charts можно добавить в .gitignore.

Позднее, во время процесса деплоя (командой werf converge или werf bundle apply) или рендеринга шаблонов (командой werf render), werf автоматически скачает все зависимости указанные в lock-файле .helm/Chart.lock.

ЗАМЕЧАНИЕ. Файл .helm/Chart.lock должен быть коммитнут в git репозиторий, больше информации в статье про гитерминизм.

Конфигурация зависимостей

Опишем формат зависимостей в файле .helm/Chart.yaml.

name — имя чарта, которое должно совпадать с именем (параметр name) в файле Chart.yaml соответствующего чарта — зависимости.
version — версия чарта согласно схеме семантического версионирования, либо диапазон версий.
repository — URL репозитория чартов. Helm ожидает, что добавив /index.yaml к URL, он получит список чартов репозитория. Значение repository может быть псевдонимом, который в этом случае должен начинаться с префикса alias: или @.

Файл .helm/Chart.lock содержит точные версии прямых зависимостей, версии зависимостей прямых зависимостей и т.д.

Для работы с файлом зависимостей существуют команды werf helm dependency, которые упрощают синхронизацию между желаемыми зависимостями и фактическими зависимостями, указанными в папке чарта:

werf helm dependency list — проверка зависимостей и их статуса.
werf helm dependency update — обновление папки .helm/charts согласно содержимому файла .helm/Chart.yaml.
werf helm dependency build — обновление .helm/charts согласно содержимому файла .helm/Chart.lock.

Все репозитории чартов, используемые в .helm/Chart.yaml, должны быть настроены в системе. Для работы с репозиториями чартов можно использовать команды werf helm repo:

werf helm repo add — добавление репозитория чартов.
werf helm repo index.
werf helm repo list — вывод списка существующих репозиториев чартов.
werf helm repo remove — удаление репозитория чартов.
werf helm repo update — обновление локального индекса репозиториев чартов.

werf совместим с настройками Helm, поэтому по умолчанию команды werf helm dependency и werf helm repo используют настройки из папки конфигурации Helm в домашней папке пользователя, — ~/.helm. Вы можете указать другую папку с помощью параметра --helm-home. Если у вас нет папки ~/.helm в домашней папке, либо вы хотите создать другую, то вы можете использовать команду werf helm repo init для инициализации необходимых настроек и конфигурации репозитория чартов по умолчанию.

Передача values в сабчарты

Чтобы передать данные из родительского чарта в сабчарт mysubchart необходимо определить следующие values в родительском чарте:

mysubchart:
  key1:
    key2:
    - key3: value

В сабчарте mysubchart эти данные можно использовать с помощью обращения к соответствующим параметрам без указания ключа mysubchart:

{{ .Values.key1.key2[0].key3 }}

Данные, определенные глобально в ключе верхнего уровня global, также доступны в сабчартах:

global:
  database:
    mysql:
      user: user
      password: password

Обращаться к ним необходимо как обычно:

{{ .Values.global.database.mysql.user }}

В сабчарте mysubchart будут доступны только данные ключей mysubchart и global.

ЗАМЕЧАНИЕ Файлы secret-values.yaml сабчартов не будут использоваться во время процесса деплоя, несмотря на то, что данные секретов из главного чарта и данные переданные через параметр --secret-values будут доступны через массив .Values как обычно.

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

Если вы хотите передать values, доступные только в родительском чарте, в сабчарты, то вам поможет директива export-values, которая имитирует (с небольшими отличиями) поведение import-values, только вместо передачи values из сабчарта в родительский чарт она делает обратное: передает values в сабчарт из родительского чарта. Пример использования:

# .helm/Chart.yaml
apiVersion: v2
dependencies:
  - name: backend
    version: 1.0.0
    export-values:
    - parent: werf.image.backend
      child: backend.image

Таким образом мы передадим в сабчарт всё, что доступно в .Values.werf.image.backend родительского чарта. В нашем случае это будет строка с репозиторием, именем и тегом образа backend, описанного в werf.yaml, который может выглядеть так: example.org/backend/<имя_тега>. В сабчарте эта строка станет доступна через .Values.backend.image:

# .helm/charts/backend/app.yaml
...
spec:
  template:
    spec:
      containers:
      - name: backend
        image: {{ .Values.backend.image }}  # Ожидаемый результат: `image: example.org/backend:<имя_тега>`

В отличие от YAML-якорей export-values будет работать с динамически выставляемыми values (сервисные данные werf), с переданными через командную строку values (--set и пр.) и с секретными values.

Также доступна альтернативная укороченная форма export-values, которая работает только для словарей (maps):

    export-values:
    - "someMap"

Это будет эквивалентно следующей полной форме export-values:

    export-values:
    - parent: exports.somemap
      child: .

Так в корень values сабчарта будут экспортированы все ключи, найденные в словаре .Values.exports.somemap.

Устаревшие файлы requirements.yaml и requirements.lock

Устаревший формат описания зависимостей через файлы .helm/requirements.yaml и .helm/requirements.lock тоже поддерживается werf. Однако рекомендуется переходить на .helm/Chart.yaml и .helm/Chart.lock.