HELM

Introduction

Quickstart Guide
Using Helm

Charts

Introduction

Quickstart Guide

Добавить репозиторий

helm repo add bitnami https://charts.bitnami.com/bitnami

Посмотреть доступные чарты

helm search repo bitnami

Чтобы зарелизить

helm install bitnami/mysql --generate-name

Чтобы разрелизить uninstall

uninstall удалить все связанные с релизом ресурсы (в том числе релиз хистори)
Можно оставить релиз хистори флагом --keep-history

Без сохранения

[21:00:25] vandud@macbook: ~ [1]$ helm uninstall prometheus-1625763557
release "prometheus-1625763557" uninstalled
[21:00:41] vandud@macbook: ~ [0]$ helm status prometheus-1625763557
Error: release: not found
[21:00:49] vandud@macbook: ~ [1]$

С сохранением

[20:59:31] vandud@macbook: ~ [0]$ helm uninstall loki-stack-1625764074 --keep-history
release "loki-stack-1625764074" uninstalled
[20:59:49] vandud@macbook: ~ [0]$ helm status loki-stack-1625764074
NAME: loki-stack-1625764074
LAST DEPLOYED: Thu Jul  8 20:07:58 2021
NAMESPACE: default
STATUS: uninstalled
REVISION: 1
NOTES:

А потом можем восстановить

[21:05:07] vandud@macbook: ~ [0]$ helm rollback loki-stack-1625764074 1
Rollback was a success! Happy Helming!
[21:05:18] vandud@macbook: ~ [0]$ helm list -a
NAME                 	NAMESPACE	REVISION	UPDATED                             	STATUS  	CHART           	APP VERSION
grafana-1625763384   	default  	1       	2021-07-08 19:56:28.252902 +0300 MSK	deployed	grafana-6.12.0  	8.0.0
loki-stack-1625764074	default  	2       	2021-07-08 21:05:13.667747 +0300 MSK	deployed	loki-stack-2.4.1	v2.1.0
[21:05:24] vandud@macbook: ~ [0]$

Introduction

Using Helm

Three Big Concepts

Чарт это helm-package. Он содержит все что нужно для запуска приложения в k8s

Репозиторий это место для хранения и раздачи чартов

Релиз это экземпляр приложения запущенного через чарт, один и тот же чарт можно устанавливать много раз в один и тот же k8s кластер и каждый раз это будет новый релиз

Чтобы искать чарты можно использовать команду helm search
У нее есть две подкоманды, hub и repo
repo будет искать локально среди добавленных репозиториев
А hub будет искать на https://artifacthub.io (для установки нужно добавить репозиторий)

На сайте хаба есть инструкция (справа кнопка 'install')

Helm устанавливает ресурсы в определeнном порядке (напр. сначала namespace, потом что-то еще, итд)
Этот порядок есть тут https://helm.sh/docs/intro/using_helm/

Helm не ждет пока будут запущены все ресурсы из чарта
Потому что многие чарты используют большие докер образы (по 600M), такая установка может занять значительное время
Для отслеживания статуса релиза можно использовать helm status release-name

Для кастомизации чартов используются values'ы
Чтобы посмотреть что можно указывать через values в конкретном чарте, можно воспользоваться командой

[21:39:20] vandud@macbook: ~ [1]$ helm show values grafana/grafana | head -5
rbac:
  create: true
  ## Use an existing ClusterRole/Role (depending on rbac.namespaced false/true)
  # useExistingRole: name-of-some-(cluster)role
  pspEnabled: true
[21:38:38] vandud@macbook: ~ [0]$ helm show values grafana/grafana | wc -l
     739

Можно переопределить некоторые и передать через ключ -f/--values values.yaml при установке
Или через ключ --set передать конкретные переменные
--set по приоритету выше чем --values, поэтому set наложится на values, который наложится на дефолтные значения
Вложенные элементы можно указывать через точку, списки в скобках итд

--set outer.inner={a, b, c}

То есть через set можно указать полноценный values.yaml

The helm install command can install from several sources:

A chart repository (as we've seen above)
A local chart archive (helm install foo foo-0.1.1.tgz)
An unpacked chart directory (helm install foo path/to/foo)
A full URL (helm install foo https://example.com/charts/foo-1.2.3.tgz)

helm upgrade берет существующий релиз и обновляет его
Через helm rollback можно откатиться на конкретную версию релиза

Группа команд helm repo позволяет управлять репозиториями

helm create позволяет быстро создать каркас для вашего собственного чарта
helm package позволяет упаковать чарт в архив (чарты распрастраняются архивами)

[22:29:50] vandud@macbook: tmp [0]$ helm create vandud-cool-chart
Creating vandud-cool-chart
[22:29:58] vandud@macbook: tmp [0]$ cd vandud-cool-chart/
[22:30:02] vandud@macbook: vandud-cool-chart [0]$ tree
.
|-- Chart.yaml
|-- charts
|-- templates
|   |-- NOTES.txt
|   |-- _helpers.tpl
|   |-- deployment.yaml
|   |-- hpa.yaml
|   |-- ingress.yaml
|   |-- service.yaml
|   |-- serviceaccount.yaml
|   `-- tests
|       `-- test-connection.yaml
`-- values.yaml

3 directories, 10 files
[22:30:04] vandud@macbook: vandud-cool-chart [0]$ helm package .
Successfully packaged chart and saved it to: /tmp/vandud-cool-chart/vandud-cool-chart-0.1.0.tgz
[22:30:09] vandud@macbook: vandud-cool-chart [0]$ tar --list -zf vandud-cool-chart-0.1.0.tgz
vandud-cool-chart/Chart.yaml
vandud-cool-chart/values.yaml
vandud-cool-chart/templates/NOTES.txt
vandud-cool-chart/templates/_helpers.tpl
vandud-cool-chart/templates/deployment.yaml
vandud-cool-chart/templates/hpa.yaml
vandud-cool-chart/templates/ingress.yaml
vandud-cool-chart/templates/service.yaml
vandud-cool-chart/templates/serviceaccount.yaml
vandud-cool-chart/templates/tests/test-connection.yaml
vandud-cool-chart/.helmignore
[22:30:19] vandud@macbook: vandud-cool-chart [0]$

Charts

https://helm.sh/docs/topics/charts/

В helm пакеты называются chart'ами
Чарт это коллекция файлов которые описывают связанные ресурсы кубернетеса
Одиночный чарт может быть использован как для деплоя чего-то простого (под с memcache), так и для деплоя комплексного приложения из многих компонентов (базы данных, http-серверы, итд)

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

Через helm pull chartrepo/chartname можно скачать и посмотреть чарт без его установки

The Chart File Structure

Чарт организован как структура файлов в какой-то директории, название этой директории и есть название чарта
Внутри этой директории хелм ожидает увидеть следующую структуру файлов

wordpress/
  Chart.yaml          # A YAML file containing information about the chart
  LICENSE             # OPTIONAL: A plain text file containing the license for the chart
  README.md           # OPTIONAL: A human-readable README file
  values.yaml         # The default configuration values for this chart
  values.schema.json  # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file
  charts/             # A directory containing any charts upon which this chart depends.
  crds/               # Custom Resource Definitions
  templates/          # A directory of templates that, when combined with values,
                      # will generate valid Kubernetes manifest files.
  templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes

В Хелм зарезервированы перечисленные выше имена файлов, остальное он проигнорит (остальное можно использовать под свои нужды)

The Chart.yaml File

Chart.yaml требуется для чарта
О его содержимом можно почитать тут https://helm.sh/docs/topics/charts/#the-chartyaml-file

Обязательных полей только три

apiVersion: The chart API version (required)
name: The name of the chart (required)
version: A SemVer 2 version (required)

Каждый чарт должен иметь версию, версии подчиняются SemVer2 стандарту

helm package запакует чарт в архив с именем NAME-VERSION.tgz
Сложные SemVer имена версий также будут работать

[19:40:00] vandud@macbook: test-chart [0]$ grep 'version:' Chart.yaml
version: 1.2.3-alpha.1+ef365
[19:40:10] vandud@macbook: test-chart [0]$ helm package .
Successfully packaged chart and saved it to: /tmp/test-chart/test-charnthnth-1.2.3-alpha.1+ef365.tgz
[19:40:14] vandud@macbook: test-chart [0]$

apiVersion: v2 должен быть v2 для 3 helm, и v1 для второго

appVersion указывает на версию приложения в чарте
Например в чарте для drupal указано appVersion: "8.2.1", это значит что внутрь чарта заключен drupal версии "8.2.1"
Это поле не связано с версией чарта
Рекомендуется заключать это поле в кавычки (интерпретатору yaml так легче)

kubeVersion полезное поле, в нем указывается допустимая для этого чарта версия кубера
Если версия не совпадает, то чарт не задеплоится
Эту версию можно указывать гибко, например:

>= 1.13.0 < 1.14.0 || >= 1.14.1 < 1.15.0

Пробел это И
Две палки это ИЛИ

Доступны символы сравнения = != > < >= <=
Диапазоны, вайлдкарды, диапазоны по патчверсиям, диапазоны по минорным версиям, итд

Подробнее об этом https://helm.sh/docs/topics/charts/#the-kubeversion-field

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

Есть два типа чартов (type)

application - by default
library - предоставляет утилиты для chart builder'а

Chart LICENSE, README and NOTES

Файл LICENSE содержит лицензию на чарт в виде обычного текста
Файл README.md обычно содержит описание приложения, рекомендации по запуску чарта, описание опций в values.yaml и их дефолтных значений и какую-то еще полезную информацию
Файл templates/NOTES.txt обрабатывается как темплейт и содержит какие-то рекомендации по использованию, следующие шаги после установки, любую другую полезную инфу (например url до webui или данные для подключения к базе)
Выводится после helm install или helm status

Chart Dependencies

Чарт может зависеть от какого-либо количества других чартов
Эти зависимости могут динамически линковаться через поле dependencies в Chart.yaml
Или вручную через директорию /charts

В секции dependencies можно перечислить чарты от которых зависит наш чарт

dependencies:
  - name: apache
    version: 1.2.3
    repository: https://example.com/charts
  - name: mysql
    version: 3.2.1
    repository: https://another.example.com/charts

name - имя чарта который нам нужен
version - версия этого чарта
ropository - url до репозитория (нужно будет сперва сделать helm repo add чтобы сработало)
Также можо использовать имя добавленного репозитория вместо полного урла

$ helm repo add fantastic-charts https://fantastic-charts.storage.googleapis.com

dependencies:
  - name: awesomeness
    version: 1.0.0
    repository: "@fantastic-charts"

Команда helm dependency update загрузит все зависимости в папку charts/

charts/
  apache-1.2.3.tgz
  mysql-3.2.1.tgz

С помощью alias можно установить установить несколько раз один и тот же чарт

dependencies:
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    alias: new-subchart-1
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    alias: new-subchart-2
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0

condition: subchart1.enabled, global.subchart1.enabled

Condition позволяет указать в себе yaml-path'ы через запятую (один или более) и если путь резолвится из values.yaml в булево значение, то зависимость отключается или включается
Используется первый успешно разрезолвленный путь
Если ни одного пути нет в values то и нет condition

tags содержит лейблы, через values можно управлять включенностью зависимости

dependencies:
  - name: subchart1
    repository: http://localhost:10191
    version: 0.1.0
    condition: subchart1.enabled, global.subchart1.enabled
    tags:
      - front-end
      - subchart1
  - name: subchart2
    repository: http://localhost:10191
    version: 0.1.0
    condition: subchart2.enabled,global.subchart2.enabled
    tags:
      - back-end
      - subchart2

# values.yaml
subchart1:
  enabled: true
tags:
  front-end: false
  back-end: true

Кондишены установленные через values перекрывают тэги, используется первый найденный путь из values, останые игнорятся
Тэги обрабатываются так: если хоть один из тэгов true, то чарт включен
Секция tags: доложна быть в корне values (не должна быть вложенной)

Можно экспортировать values из дочернего чарта

# parent's Chart.yaml file
dependencies:
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    import-values:
      - data

# child's values.yaml file
exports:
  data:
    myint: 99 # эта пара key-value попадет в родительский values

Еще вариант

Все зависимости объединяются в один общий набор и создаются/обновляются по алфавиту

Templates and Values

Шаблоны и values описываются на языке go templates
https://pkg.go.dev/text/template
В темплейтах используются функции из https://github.com/Masterminds/sprig/blob/master/docs/index.md

Темплейты хранятся в папке templates/ и при рендеринге чарта пропускаются сквозь template engine

values'ы появляются из values.yaml файла который положил разработчик чарта (в нем дефолтные значения)
А так же пользователь чарта при установке может использовать свой файл (скормив его команде helm install)

Значения из values.yaml или те что установлены через --set, доступны внутри шаблонов через объект .Values

Есть ряд предустановленных значений
Их нельзя перезаписать и они доступны в любом шаблоне
Через объект Release: имя чарта, namespace куда зарелижен чарт, устанавливается или обновляется релиз
Объект Chart содержит контент файла Chart.yaml
Объект Files позволяет получить доступ к другим файлам чарта (не шаблоны и не из файла .helmignore)
Capabilities про версию куба

Values'ы добавленные через ключ --values при установке, мерджатся с дефолтными

title: "My WordPress Site" # Sent to the WordPress template

mysql:
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  port: 8080 # Passed to Apache

Можно определять значения для дочерних чартов

Из примера выше, wordpress-chart видит .Values.mysql.password, а mysql-chart видит .Values.password
Mysql-chart не увидит title

Есть секция global
Она доступна всем сабчартам

title: "My WordPress Site" # Sent to the WordPress template

global:
  app: MyWordPress

mysql:
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  port: 8080 # Passed to Apache

Превратится в

title: "My WordPress Site" # Sent to the WordPress template

global:
  app: MyWordPress

mysql:
  global:
    app: MyWordPress
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  global:
    app: MyWordPress
  port: 8080 # Passed to Apache

С помощью values.schema.json можно валидировать финальные values объекты (смердженные дефолтный values.yaml, кастомный values, и то что передано через set)
В этом файле можно задавать какие типы данных должны быть у определенных полей и разное другое

helm install/upgrade/lint/template - используют values.schema.json для валидации

Custom Resource Definitions (CRDs)

В кубере есть crd (custom resource definitions)
Они позволяют пользователя определять свои собственные kinds
Хелм тоже их поддерживает

crd yaml'ы должны лежать в папке crds/
Они не могут быть затемплейчены, это просто plain-text'овые yaml документы

Они складываются отдельно потому что helm при установке чарта сначала установит все crd, потом дождется когда они установятся и станут доступны, и только потом начнет устанавливать теплейты

Любой веб-сервер может выполнять функцию chart repository