helmwave_projects

Вариант организации множества проектов

Быстрый старт

Требования

Helmwave версии не ниже 0.32.0
SOPS и age — нужны только для работы с секретами (см. Secrets)

1. Настройка окружения

Корневой файл .env уже содержит необходимые для helmwave переменные:

HELMWAVE_AUTO_YML=true
HELMWAVE_TPL=helmwave.yml.tpl
HELMWAVE_TEMPLATER=gomplate
HELMWAVE_LOG_LEVEL=info
HELMWAVE_LOG_FORMAT=text
HELMWAVE_LOG_COLOR=true
HELMWAVE_AUTO_BUILD=true

Helmwave подхватывает его автоматически, поэтому шаблон helmwave.yml.tpl будет сгенерирован в helmwave.yml перед сборкой плана.

2. Создание проекта

Проекты располагаются в каталоге projects/<имя-проекта> и должны содержать файл helmwave.yml со списком релизов:

mkdir -p projects/exampleproject

# projects/exampleproject/helmwave.yml
---
- name: nginx
  chart:
    name: oci://registry-1.docker.io/bitnamicharts/nginx
    version: 22.4.3

Chart-репозитории и OCI-registries описываются отдельно в каталогах repositories/ и registries/ — например, registries/bitnami.yml уже содержит registry-1.docker.io, поэтому OCI-чарты Bitnami можно подключать сразу.

3. Значения релиза

Файл значений должен называться так же, как релиз (name: в helmwave.yml), и лежать в projects/<проект>/values/:

# projects/exampleproject/values/nginx.yml
clusterDomain: example.local

Подробнее — в разделе Файлы значений.

4. Сборка и применение

helmwave build --yml   # сгенерировать helmwave.yml и план из шаблона
helmwave up             # применить план к кластеру

Готовый пример такого проекта уже есть в projects/exampleproject.

Дальнейшие шаги

Секреты релиза — раздел Secrets
Переопределение значений по окружениям/namespace — раздел Переопределение значений
Включение/отключение проектов через projects.yml — раздел Отключение или включение проекта
Скрипты на этапах деплоя — раздел Lifecycle

Шаблонизация

Как шаблонизатор по умолчанию используется gomplate

Разделители по умолчанию: [[ ]]

Secrets

Секреты хранятся в зашифрованном SOPS-виде в каталоге проекта:

projects/<имя-проекта>/secrets/<имя-релиза>.yml

Например, секреты релиза nginx проекта exampleproject должны находиться в projects/exampleproject/secrets/nginx.yml. Имя файла обязано совпадать с полем name релиза. Если файла нет, он не добавляется в релиз.

При helmwave build файл автоматически обрабатывается встроенным renderer sops. Расшифрованную копию рядом с исходным файлом создавать не требуется: открытые значения попадают только во внутренний каталог плана .helmwave/, который исключен из Git.

Настройка SOPS

Для работы необходимы Helmwave версии не ниже 0.32.0, SOPS и age.

1. Создание ключа

Сгенерируйте приватный age-ключ в корне репозитория и получите из него публичный recipient:

age-keygen -o .sops-age-key.txt
age-keygen -y -o .sops-age-recipient.txt .sops-age-key.txt
chmod 600 .sops-age-key.txt

Приватный .sops-age-key.txt позволяет расшифровывать секреты, поэтому его нельзя добавлять в Git. Публичный recipient не является секретом. Получить его для следующего шага можно командой:

age-keygen -y .sops-age-key.txt

2. Правила шифрования

Создайте в корне репозитория файл .sops.yaml и вставьте в него публичный recipient вместо <AGE_RECIPIENT>:

creation_rules:
  - path_regex: ^projects/[^/]+/secrets/.*\.ya?ml$
    age: <AGE_RECIPIENT>

Файл .sops.yaml нужно хранить в Git. Он сообщает SOPS, что YAML-файлы в каталогах projects/<проект>/secrets/ необходимо шифровать указанным публичным ключом.

3. Подключение приватного ключа

Добавьте путь к ключу в корневой .env:

SOPS_AGE_KEY_FILE=.sops-age-key.txt

Helmwave загружает .env автоматически. SOPS CLI этого не делает, поэтому перед ручной работой с секретами переменные нужно экспортировать:

set -a
source .env
set +a

В CI приватный ключ следует передавать через защищенный секрет в SOPS_AGE_KEY либо создавать файл вне рабочей копии и указывать его через SOPS_AGE_KEY_FILE.

4. Создание секрета

Создайте каталог и откройте новый файл через SOPS:

mkdir -p projects/exampleproject/secrets
sops projects/exampleproject/secrets/nginx.yml

После сохранения файл будет зашифрован. Существующий открытый YAML-файл можно зашифровать на месте:

sops encrypt --in-place projects/exampleproject/secrets/nginx.yml

Проверьте состояние файла и возможность его расшифровать:

sops filestatus projects/exampleproject/secrets/nginx.yml
sops decrypt projects/exampleproject/secrets/nginx.yml >/dev/null

После настройки Helmwave расшифрует секрет во время сборки плана:

helmwave build --yml

Если ключ отсутствует или файл не является корректным SOPS-документом, сборка плана завершится ошибкой и незашифрованные значения не будут применены.

Файлы значений

Файл значения формируются динамически на основе предоставленных файлов или секретов. Для того, чтобы в релиз передался файл значения, необходимо назвать его именем релиза.

Например: Файл helmwave.yml выглядит таким образом:

---
- name: minio
  chart:
    name: oci://..//minio
    version: 4.0.32

То для передачи в этот релиз значений, файл необходимо назвать именем релиза, указанным в name:, и добавить расширение .yml. Файл значений для примера будет называться minio.yml. Допустим, мы создали один файл значений и один секрет. Тогда файлы значений будут переданы в релиз в таком виде:

values:
  - projects/minio/values/minio.yml
  - projects/minio/secrets/minio.yml

Если значений много, то можно создать директорию, содержащую название релиза, и описать значения в нескольких файлах:

values:
  - projects/minio/values/minio/buckets.yml
  - projects/minio/values/minio/users.yml
  - projects/minio/values/minio/minio.yml
  - projects/minio/secrets/minio.yml

Если доступна директория с названием релиза и файл с названием релиза и расширением .yml, то добавлены будут только файлы из директории.

Генератор проверяет, существует ли файл secrets/ИМЯ-РЕЛИЗА.yml, и в случае его отсутствия не добавляет его в план. Если файл существует, он должен быть зашифрован SOPS.

Дополнительные файлы значений можно указать в helmwave.yml, передав values: — они будут добавлены к текущим файлам значений и идти первыми в списке:

- name: minio
  chart:
    name: oci://.../minio
    version: 4.0.32
  values:
    - src: projects/minio/extra_values.yml

Переопределение значений

Есть возможность переопределить значения для определенного кластера и namespace.

Для этого необходимо определить переменную окружения HELMWAVE_ENV_NAME. После этого helmwave будет генерировать следующий список файлов значений:

values:
  # базовый слой значений
  - projects/minio/values/minio.yml
  - src: projects/minio/secrets/minio.yml
    renderer: sops
  # слой переопределения значений
  - projects/minio/values/override/$ENV_NAME/$NAMESPACE/minio.yml

Где $ENV_NAME — это значение переменной окружения, а $NAMESPACE — это namespace, куда будет происходить развертывание чарта.

Зависимости от других релизов

По умолчанию все релизы, которые устанавливаются в основной namespace, имеют зависимость от bootstrap-ns. bootstrap-ns и релизы, которые ставятся не в основной namespace, имеют зависимость от bootstrap-cluster. Это поведение отключает переменная окружения HELMWAVE_BOOTSTRAP_ENABLED.

Дополнительные зависимости можно прописать в helmwave.yaml через объявление depends_on следующим образом:

- name: stickers-bot
  chart:
    name: oci://.../stickers-bot
    version: 1.1.2
  depends_on:
    - apigwv2

Отключение авто зависимостей для релиза

Для отключения авто зависимостей для конкретного релиза необходимо объявить auto_depedns_enabled со значением false.

- name: stickers-bot
  chart:
    name: oci://.../stickers-bot
    version: 1.1.2
  auto_depedns_enabled: false

Namespace

Namespace формируется следующим образом. Есть значение по умолчанию defaults. Глобально его можно заменить через переменную окружения HELMWAVE_DEFAULT_NAMESPACE. Либо задать для конкретного релиза namespace: в helmwave.yml.

Тэги

Описание нюансов работы тэгов в helmwave

К каждому релизу автоматически добавляется два тэга:

Имя релиза helm. name: в helmwave.yml
Имя проекта. Название директории.

Можно добавить дополнительный тег через:

tags:
    - new-tag

Например:

К релизу nginx, который находится в проекте exampleproject, будет добавлено два тэга:

nginx
exampleproject

Отключение или включение проекта

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

Пример

Отключение для окружения

Отключаем nginx для всех окружений и разрешаем только для окружения с именем cluster. Выключение имеет больший приоритет, чем включение:

envs:
  all:
    projects:
      disabled:
        nginx:
  cluster:
    projects:
      enabled:
        nginx:

Включение для определенного типа развертывания

Включаем развертывание dmz-proxy только при типе развертывания dmz в кластерном окружении.

По умолчанию все проекты разрешены. Ключ .policy отвечает за изменение этой политики.

Если присвоить ему значение disabled, то все проекты, которые явно не разрешены, будут запрещены:

envs:
  all:
    projects:
      disabled:
        dmz-proxy:
  cluster:
    projects:
      enabled:
        dmz-proxy:
deployment_types:
  all:
    projects:
      disabled:
        dmz-proxy:
  dmz:
    policy: disabled
    projects:
      enabled:
        dmz-proxy:

Ключевые слова

all

Отключает проект для всех окружений.

default

Отключает/включает проект для окружения по умолчанию

Lifecycle

Скрипты, которые будут выполняться на одном из этапов построения и применения helmwave.

Глобальный

Корневая директория lifecycle для глобальных этапов.

Проектный

Для этого просто необходимо положить скрипт в директорию имя_релиза/этап:

nginx
├── helmwave.yml
├── lifecycle
│   └── nginx
│       └── pre_up
│           └── example.sh
└── values
    └── nginx.yml

В данном примере скрипт example.sh выполнится на этапе pre_up. В директории может быть несколько скриптов. Очередность исполнения зависит от сортировки по имени.

Этапы

pre_up

post_up

pre_build

post_build

pre_down

post_down

pre_rollback

post_rollback

Пользовательский слой

Для store реализован пользовательский слой, позволяющий пользователям переопределять значения пользователей.

Например:

Для переопределения значения, расположенного в файле ./store/dlp.yml, значения переменной tourniquetEnabled:

dlpEnabled: false

в пользовательском слое необходимо создать файл /data/helmwave/store/dlp.yml с содержимым:

dlpEnabled: true

Переменные окружения

С переменными окружения, которые доступны в helmwave, можно ознакомиться тут

Переменные окружения, которые используются в helmwave.yml.tpl:

HELMWAVE_USE_LOCAL_REPO_CACHE

При наличии этой переменной helmwave будет использовать скаченные helm'ом в кэш чарты. Необходима для применения изменений у заказчика, когда не доступны наши репозитории.

HELMWAVE_WAIT_DISABLED

Отключает все ожидания. Используется в момент обновления инсталляции.

HELMWAVE_DEFAULT_NAMESPACE

Значение по умолчанию: defaults

Переопределяет namespace по умолчанию.

HELMWAVE_ENV_NAME

Переменная окружения, которая задает имя кластера в файлах значений.

HELMWAVE_DEPLOYMENT_TYPE

Значение по умолчанию: default

Переменная окружения, которая задает тип установки.

HELMWAVE_LIFECYCLES_ENABLED

Значение по умолчанию: true

Включить или отключить lifecycle. По умолчанию включено.

HELMWAVE_LIFECYCLES_ALLOW_FAILURE

Значение по умолчанию: false

Разрешает lifecycle скриптам завершиться с ошибкой. По умолчанию выключено.

HELMWAVE_BOOTSTRAP_ENABLED

Значение по умолчанию: false

При включенном состоянии во все релизы проставляется зависимость чарт bootstrap-cluster и bootstrap-ns для всех, которые ставятся в namespace по умолчанию.