HelmWave v0.5.0 – GitOps для твоего Kubernetes

Helm, как и Docker стал де-факто стандартом в индустрии. Когда мы обсуждаем Kubernetes (52%). И новость, что Docker is deprecated вызвало волну обсуждений в сообществе. Настолько все привыкли к Docker.

Для Docker есть замечательный по своей простоте docker-compose, в котором мы можем декларативно описать, что мы хотим от Docker.

Для Kubernetes набор yaml-tpl файлов упаковывается в архив. И затем этот архив называется Helm-чартом. Но как это часто бывает приложение не может быть описано лишь одним Helm чартом. Требуется как-то управлять/композить/настраивать/шаблонизировать такие сеты.

Одним из подходов по управлению является Umbrella Chart. Это helm chart который объединяет в себе все другие чарты.

Очевидные минусы данного решения:

• Требуется поддерживать дополнительный чарт
• Новый слой согласования имен values переменных.
• Umbrella-chart это все тот же чарт, поэтому о шаблонизации values и декларативном разделении на контуры (Окружения) не может быть и речи.
• Когда обновляется саб-чарт, нужно идти в umbrella и обновлять еще версию umbrella чарта.

Helmwave возник, как инструмент для декларативного описания всех чартов в одном yaml.
Этот пост покажет как можно решить основные проблемы (use-cases) с помощью helmwave.

Что такое HelmWave?

• Это бинарь, который устанавливает helm release из helmwave.yml.
• Кладешь helmwave.yml в git и применяешь его через CI.
• Можно шаблонизировать все c помощью (Go template), начиная от helmwave.yml до values.
• Helmwave понимает какие helm-repositories ему понадобятся для деплоя. И вытесняет лишние.

Порядок комманд

graph TD;     Start(helmwave.yml.tpl) --render--> helmwave.yml;     helmwave.yml --planfile--> .helmwave;     .helmwave --sync--> Finish(Releases have been deployed!)

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

helmwave.yml.tpl имеет следующий вид

project: my-project version: 0.5.0  repositories:   - name: bitnami     url: https://charts.bitnami.com/bitnami  .options: &options   install: true   namespace: my-namespace  releases:   - name: redis-a     chart: bitnami/redis     options:       <<: *options    - name: redis-b     chart: bitnami/redis     options:       <<: *options

$ helmwave deploy

Поздравляю, вы задеплоили с помощью helmwave!

$ helm list -n my-namespace NAME       NAMESPACE       REVISION     STATUS      CHART             APP VERSION redis-a    my-namespace    1            deployed    redis-11.2.3      6.0.9       redis-b    my-namespace    1            deployed    redis-11.2.3      6.0.9    $ k get po -n my-namespace                                                                                                                          NAME               READY   STATUS    RESTARTS   AGE redis-a-master-0   1/1     Running   0          64s redis-a-slave-0    1/1     Running   0          31s redis-a-slave-1    1/1     Running   0          62s redis-b-master-0   1/1     Running   0          59s redis-b-slave-0    1/1     Running   0          32s redis-b-slave-1    1/1     Running   0          51s

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

$ helmwave help

• $HELMWAVE_TPL_FILE – отвечает за путь к входному файлу для шаблонизации (helmwave.yml.tpl).
• $HELMWAVE_FILE – указывает путь выходного файла после операции шаблонизации (helmwave.yml).
• $HELMWAVE_PLAN_DIR – указывает путь к папке, в которой хранится или будет хранится план (.helmwave/).
• $HELMWAVE_TAGS – массив строк, на основании которого будет проводится планирование.
• $HELMWAVE_PARALLEL – включает/выключает многопоточность (рекомендуется включать).
• $HELMWAVE_LOG_FORMAT – позволяет выбрать один из предустановленных форматов вывода.
• $HELMWAVE_LOG_LEVEL – позволяет управлять детализацией вывода.
• $HELMWAVE_LOG_COLOR – включает/выключает цвета для вывода.

Use-Cases

Примеры будут производиться, опираясь на gitlab-ci. Но это не помешает вам встроить helmwave в любой другой CI-инструмент.

Чем ниже, тем сложнее будут примеры.

Git tag –> Docker tag

Допустим вы написали какой-то helm чарт для нашего приложения. Его values.yaml по умолчанию имеет вид:

image:   repository: registry.gitlab.local/example/app   tag: master

Необходимо чтобы image.tag брался из переменной CI

Приступим, создадим 2 файла.

. ├── helmwave.yml.tpl └── values.yml

helmwave.yml.tpl

project: my-project # Имя проекта version: 0.5.0 # Версия helmwave  releases:   - name: my-release     chart: my-chart-repo/my-app     values:       - values.yml     options:       install: true       namespace: my-namespace

values.yml

image:   tag: {{ env "CI_COMMIT_TAG" }}

Git commit —> PodAnnotations

Требуется чтобы deployment обновлялся только если у нас есть новый коммит.

deployment имеет примерно этот вид:

    ...     metadata:         {{- with .Values.podAnnotations }}         annotations:           {{- toYaml . | nindent 8 }}         {{- end }}     ...

Поэтому мы можем легко расширить предыдущий пример values.yml

image:   tag: {{ requiredEnv "CI_COMMIT_TAG" }}  podAnnotations:     gitCommit: {{ requiredEnv "CI_COMMIT_SHORT_SHA" | quote }}

Контуры, окружения, environments

Структура каталога

. ├── helmwave.yml.tpl └── values     ├── _.yml     ├── prod.yml     └── stage.yml

helmwave.yml.tpl

project: my-project   version: 0.5.0    releases:     - name: my-release       chart: my-chart-repo/my-app       values:         # Default         - values/_.yml         # For specific ENVIRONMENT         - values/{{ env "CI_ENVIRONMENT_NAME" }}.yml       options:         install: true         namespace: {{ env "CI_ENVIRONMENT_NAME" }}

values/_.yml – Будет запускаться для любого окружения

image:   tag: {{ requiredEnv "CI_COMMIT_TAG" }}  podAnnotations:     gitCommit: {{ requiredEnv "CI_COMMIT_SHORT_SHA" | quote }}

values/prod.yml – Будет запускаться только для prod

replicaCount: 6

values/stage.yml – Будет запускаться только для stage

replicaCount: 2

Используем внешний yaml и .Release.Store

Store это просто хранилище, которое можно задавать в helmwave.yml и передавать дальше в шаблонизацию values.

Допустим мы хотим связать путь к секрету в vault и путь к проекту в gitlab или вы хотите переопределять путь к image.repository. Это можно удобно сделать через Store.

. ├── helmwave.yml.tpl ├── values │   └── _.yml └── vars     └── my-list.yaml 

values/_.yml

vault: secret/{{ .Release.Store.path  }}/{{ requiredEnv "CI_ENVIRONMENT_NAME"  }}  image:   repository: {{ env "CI_REGISTRY" | default "localhost:5000" }}/{{ .Release.Store.path }}

Добавим произвольный yaml файл.

vars/my-list.yaml

releases:   - name: adm-api     path: main/product/adm/api   - name: api     path: main/product/api

helmwave.yml.tpl

project: my-project version: 0.5.0  .options: &options   install: true   wait: true   timeout: 5m  releases:   {{- with readFile "vars/my-list.yaml" | fromYaml | get "releases" }}   {{- range $v := . }}   - name: {{ $v | get "name" }}     chart: my-project/{{ $v | get "name" }}     options:       <<: *options     store:       path: {{ $v | get "path" }} # Set .Release.Store.path     tags:       - {{ $v | get "name" }}       - my     values:         # Default         - values/_.yml         # For specific ENVIRONMENT         - values/{{ env "CI_ENVIRONMENT_NAME" }}.yml   {{ end }}   {{- end }} 

Запускаем!

$ CI_ENVIRONMENT_NAME=stage helmwave planfile

Появится helmwave.yml и папка .helmwave

$ tree .helmwave .helmwave ├── planfile └── values     ├── _.yml.adm-api@.plan     └── _.yml.api@.plan  $ cat .helmwave/values/_.yml.api@.plan                             vault: secret/main/product/api/stage                                                                 image:   repository: localhost:5000/main/product/api  $ cat .helmwave/values/_.yml.adm-api@.plan                                   vault: secret/main/product/adm/api/stage  image:   repository: localhost:5000/main/product/adm/api 

helmwave.yml

project: my-project version: 0.5.0  .options: &options   install: true   wait: true   timeout: 5m  releases:   - name: adm-api     chart: my/adm-api     options:       <<: *options     store:       path: main/product/adm/api     tags:       - adm-api       - my     values:         # Default         - values/_.yml         # For specific ENVIRONMENT         - values/stage.yml    - name: api     chart: my/api     options:       <<: *options     store:       path: main/product/api     tags:       - api       - my     values:         # Default         - values/_.yml         # For specific ENVIRONMENT         - values/stage.yml 

Отделяем продукты от инфраструктуры

Структура проекта

Создадим в папке values 2 папки

• product – здесь будут values для продуктов
• infrastructure – здесь будет инфарструктурные values

values/infrastructure

• adminer – веб морда для подключения к базе, полезна в основном только в dev-контурах
• postgresql – база данных
• ns-ready – здесь LimitRange, ResourcseQuota, Secrets, NetworkPolicy, etc
• rabbitmq – общая шина между chat и api

values/product
Приложение состоит из 3 микросервисов

• api
• chat
• frontend

И еще нам понадобятся 2 отдельных файла описывающие массив product и массив infrastructure.

Структура проекта:

. ├── helmwave.yml.tpl ├── values │   ├── infrastructure │   │   ├── adminer │   │   │   ├── _.yml │   │   │   ├── dev.yml │   │   │   └── stage.yml │   │   ├── ns-ready │   │   │   └── _.yml │   │   ├── postgresql │   │   │   ├── _.yml │   │   │   └── dev.yml │   │   └── rabbitmq │   │       ├── _.yml │   │       ├── dev.yml │   │       └── stage.yml │   └── product │       ├── _ │       │   ├── _.yml │       │   ├── dev.yml │       │   ├── prod.yml │       │   └── stage.yml │       ├── api │       │   ├── _.yml │       │   ├── dev.yml │       │   ├── prod.yml │       │   └── stage.yml │       ├── chat │       │   └── _.yml │       └── frontend │           ├── _.yml │           ├── dev.yml │           ├── prod.yml │           └── stage.yml └── vars     ├── infrastructure.yaml     └── products.yaml 

vars/infrastructure.yaml —

 releases:   - name: postgresql     repo: bitnami     version: 8.6.13    - name: adminer     repo: cetic     version: 0.1.5    - name: rabbitmq     repo: bitnami     version: 7.6.6    - name: ns-ready     repo: my-project     version: 0.1.1

vars/products.yaml

releases:   - name: adm-api     path: rdw/sbs/adm/api   - name: frontend     path: my-project/internal/frontend   - name: api     path: my-project/internal/api   - name: chat     path: my-project/internal/chat 

helmwave.yml.tpl

project: my-project version: 0.5.0  repositories:   - name: bitnami     url: https://charts.bitnami.com/bitnami   - name: cetic     url: https://cetic.github.io/helm-charts  .options: &options   install: true   wait: true   timeout: 5m   atomic: false   maxhistory: 10   namespace: {{ requiredEnv "HELM_NS" }}  releases:   {{- with readFile "vars/products.yaml" | fromYaml | get "releases" }}   {{- range $v := . }}   - name: {{ $v | get "name" }}     chart: my-project/{{ $v | get "name" }}     options:       <<: *options     store:       path: {{ $v | get "path" }}     tags:       - {{ $v | get "name" }}       - product     values:       # all products & all envs       - values/product/_/_.yml       # all products & an env       - values/product/_/{{ requiredEnv "CI_ENVIRONMENT" }}.yml       # a product & all envs       - values/product/{{ $v | get "name" }}/_.yml       # a product & an env       - values/product/{{ $v | get "name" }}/{{ requiredEnv "CI_ENVIRONMENT" }}.yml   {{ end }}   {{- end }}    {{- with readFile "vars/infrastructure.yaml" | fromYaml | get "releases" }}   {{- range $v := . }}   - name: {{ $v | get "name" }}     chart: {{ $v | get "repo" }}/{{ $v | get "name" }}     options:       <<: *options       chartpathoptions:         version: {{ $v | get "version" }}     tags:       - {{ $v | get "name" }}       - infrastructure     values:       # a svc & all envs       - values/infrastructure/{{ $v | get "name" }}/_.yml       # a svc & an env       - values/infrastructure/{{ $v | get "name" }}/{{ requiredEnv "CI_ENVIRONMENT" }}.yml   {{ end }}   {{- end }} 

Контуры в Store

Допустим у нас есть 2 окружения dev и prod.
И в prod’e нам не нужна база данных

vars/infrastructure.yaml

releases:   - name: rabbitmq     repo: stable     version: 6.18.2     envs:       - _ # all environments     tags:       - queue    - name: postgresql     repo: bitnami     version: 8.6.13     envs:       - dev # only dev     tags:       - db

# vim: set filetype=yaml: {{- $env := requiredEnv "CI_ENVIRONMENT" }} # Look at this first  project: insider version: 0.5.0  repositories:   - name: stable     url: https://kubernetes-charts.storage.googleapis.com   - name: bitnami     url: https://charts.bitnami.com/bitnami  .options: &options   install: true   wait: true   force: false   timeout: 5m   atomic: false   maxhistory: 10   namespace: {{ requiredEnv "HELM_NS" }}  releases:   {{- with readFile "vars/infrastructure.yaml" | fromYaml | get "releases" }}   {{- range $v := . }}   {{- $envs := $v | get "envs" }}   {{- if or (has "_" $envs) (has $env $envs) }}   - name: {{ $v | get "name" }}     chart: {{ $v | get "repo" }}/{{ $v | get "name" }}     options:       <<: *options       chartpathoptions:         version: {{ $v | get "version" }}     tags:       - {{ $v | get "name" }}       - infrastructure       {{- if $v | hasKey "tags" }}       - {{ $v | get "tags" | toYaml }}       {{- end }}     values:       # a svc & all envs       - values/infrastructure/{{ $v | get "name" }}/_.yml       # a svc & an env       - values/infrastructure/{{ $v | get "name" }}/{{ $env }}.yml   {{ end }}   {{- end }}   {{- end }} 

База по умолчанию выключена

$ helmwave planfile

Чтобы postgresql включился

$ CI_ENVIRONMENT=dev helmwave planfile

Giltab-CI Pipelines

Рассмотрим шаблон gitlab-ci с использованием helmwave из проекта g-ci

variables:   HELMWAVE_LOG_LEVEL: debug  .helmwave-deploy:   stage: deploy   environment:     name: ref/$CI_COMMIT_REF_SLUG   image:     name: diamon/helmwave:0.5.0     entrypoint: [""]   script:     - helmwave deploy  helmwave deploy:   extends: .helmwave-deploy

С использованием include

include: https://gitlab.com/g-ci/deploy/-/raw/master/helmwave.yml  helmwave deploy:   environment:     name: prod

P.S.

Helmwave source: https://github.com/zhilyaev/helmwave/
G-CI: https://gitlab.com/g-ci
Приходите к нам в telegram с любыми вопросами!