Использование Helm

В этом руководстве объясняются основы использования Helm для управления пакетами на вашем кластере Kubernetes. Руководство предполагает, что вы уже установили Helm CLI.

Если вы просто заинтересованы нескольких командам, то можете начать с Краткого Руководства. В этой главе описаны особенности команд Helm.

Three Big Concepts

Chart – это пакет Helm. Он содержит описания ресурсов, необходимые для запуска приложения, инструмента или службы внутри кластера Kubernetes.

Репозиторий это место, где можно собирать charts-ы и делиться ими. Очень похоже на Perl's CPAN archive или Fedora Package Database, но для пакетов Kubernetes.

Релиз это пример charts-а, работающего в кластере Kubernetes. Один chart часто может быть установлен много раз в одном и том же кластере. Каждый раз, когда он устанавливается, создается новый release. Рассмотрим график MySQL. У каждого из них будет свой release, который, в свою очередь, будет иметь своё имя release name.

Зная эти понятия, объяснить работу Helm можно так:

Helm устанавливает charts в Kubernetes, создавая новый release для каждой установки. А для поиска новых графиков можно воспользоваться поиском Helm chart repositories.

'helm search': Поиск Charts

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

  • helm search hub ищет в the Artifact Hub, который агрегирует списки из различных хранилищ
  • helm search repo поиск в репозиториях, которые вы добавили в свой локальный каталог helm client (используя helm repo add). Этот поиск выполняется по локальным данным, не используя подключение к публичной сети.

Вы можете найти общедоступные chart-ы, запустив helm search hub:

$ helm search hub wordpress
URL                                                 CHART VERSION APP VERSION DESCRIPTION
https://hub.helm.sh/charts/bitnami/wordpress        7.6.7         5.2.4       Web publishing platform for building blogs and ...
https://hub.helm.sh/charts/presslabs/wordpress-...  v0.6.3        v0.6.3      Presslabs WordPress Operator Helm Chart
https://hub.helm.sh/charts/presslabs/wordpress-...  v0.7.1        v0.7.1      A Helm chart for deploying a WordPress site on ...

Выше приведен поиск всех chart-ов wordpress на Artifact Hub.

Поиск показывает все доступные chart-ы с определенным именем helm search hub.

Используя helm search repo, вы можете найти названия chart-ов в уже добавленных вами репозиториях:

$ helm repo add brigade https://brigadecore.github.io/charts
"brigade" has been added to your repositories
$ helm search repo brigade
NAME                          CHART VERSION APP VERSION DESCRIPTION
brigade/brigade               1.3.2         v1.2.1      Brigade provides event-driven scripting of Kube...
brigade/brigade-github-app    0.4.1         v0.2.1      The Brigade GitHub App, an advanced gateway for...
brigade/brigade-github-oauth  0.2.0         v0.20.0     The legacy OAuth GitHub Gateway for Brigade
brigade/brigade-k8s-gateway   0.1.0                     A Helm chart for Kubernetes
brigade/brigade-project       1.0.0         v1.0.0      Create a Brigade project
brigade/kashti                0.4.0         v0.4.0      A Helm chart for Kubernetes

Helm search использует приближённый поиск подстроки (fuzzy string matching), поэтому вы можете вводить части слов или фраз:

$ helm search repo kash
NAME            CHART VERSION APP VERSION DESCRIPTION
brigade/kashti  0.4.0         v0.4.0      A Helm chart for Kubernetes

Поиск – это хороший способ найти доступные пакеты. Как только вы нашли пакет , который хотите установить, вы можете использовать helm install для его установки.

'helm install': Установка пакета

Чтобы установить новый пакет, используйте команду helm install. В самом простом случае она ожидает два аргумента: имя выпуска _release_name_, и имя chart-а, который Вы хотите установить.

$ helm install happy-panda bitnami/wordpress
NAME: happy-panda
LAST DEPLOYED: Tue Jan 26 10:27:17 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
** Please be patient while the chart is being deployed **

Your WordPress site can be accessed through the following DNS name from within your cluster:

    happy-panda-wordpress.default.svc.cluster.local (port 80)

To access your WordPress site from outside the cluster follow the steps below:

1. Get the WordPress URL by running these commands:

  NOTE: It may take a few minutes for the LoadBalancer IP to be available.
        Watch the status with: 'kubectl get svc --namespace default -w happy-panda-wordpress'

   export SERVICE_IP=$(kubectl get svc --namespace default happy-panda-wordpress --template "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}")
   echo "WordPress URL: http://$SERVICE_IP/"
   echo "WordPress Admin URL: http://$SERVICE_IP/admin"

2. Open a browser and access WordPress using the obtained URL.

3. Login with the following credentials below to see your blog:

  echo Username: user
  echo Password: $(kubectl get secret --namespace default happy-panda-wordpress -o jsonpath="{.data.wordpress-password}" | base64 --decode)

После установки wordpress chart-а обратите внимание, что при установке создается новый объект release. Текущей релиз называется happy-panda. (Если вы хотите чтобы Helm сгенерировал имя за вас, оставьте название релиза и используйте --generate-name.)

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

Helm не ждет, пока все ресурсы будут запущены, прежде чем он завершит свою работу. Для многих chart-ов требуются образ Docker-а размером более 600M, и их установка в Kubernetes кластер может занять много времени.

Чтобы отслеживать состояние релиза или перечитывать информацию о конфигурации, вы можете использовать helm status:

$ helm status happy-panda
NAME: happy-panda
LAST DEPLOYED: Tue Jan 26 10:27:17 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
** Please be patient while the chart is being deployed **

Your WordPress site can be accessed through the following DNS name from within your cluster:

    happy-panda-wordpress.default.svc.cluster.local (port 80)

To access your WordPress site from outside the cluster follow the steps below:

1. Get the WordPress URL by running these commands:

  NOTE: It may take a few minutes for the LoadBalancer IP to be available.
        Watch the status with: 'kubectl get svc --namespace default -w happy-panda-wordpress'

   export SERVICE_IP=$(kubectl get svc --namespace default happy-panda-wordpress --template "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}")
   echo "WordPress URL: http://$SERVICE_IP/"
   echo "WordPress Admin URL: http://$SERVICE_IP/admin"

2. Open a browser and access WordPress using the obtained URL.

3. Login with the following credentials below to see your blog:

  echo Username: user
  echo Password: $(kubectl get secret --namespace default happy-panda-wordpress -o jsonpath="{.data.wordpress-password}" | base64 --decode)

Выше показано текущее состояние вашего релиза.

Настройка Chart-а Перед установкой

Изначально Helm использует параметры конфигурации по умолчанию. Но вы всегда можете настроить chart используя свою конфигурацию

Чтобы увидеть, какие параметры есть в chart-е, используйте helm show values:

$ helm show values bitnami/wordpress
## Global Docker image parameters
## Please, note that this will override the image parameters, including dependencies, configured to use the global value
## Current available global Docker image parameters: imageRegistry and imagePullSecrets
##
# global:
#   imageRegistry: myRegistryName
#   imagePullSecrets:
#     - myRegistryKeySecretName
#   storageClass: myStorageClass

## Bitnami WordPress image version
## ref: https://hub.docker.com/r/bitnami/wordpress/tags/
##
image:
  registry: docker.io
  repository: bitnami/wordpress
  tag: 5.6.0-debian-10-r35
  [..]

Затем вы можете переопределить любой из этих параметров в файле формата YAML, а затем передать этот файл во время установки.

$ echo '{mariadb.auth.database: user0db, mariadb.auth.username: user0}' > values.yaml
$ helm install -f values.yaml bitnami/wordpress --generate-name

Команды выше создадут пользователя для MariaDB с именем user0 и предоставит этому пользователю доступ к созданной базе данных user0db, но использует остальные значения chart-а по умолчанию.

Существует два способа передачи конфигурационных данных во время установки:

  • --values (или -f): Укажите YAML файл с конфигурацией. Это можно сделать несколько раз, и самый правый файл будет иметь приоритет
  • --set: переопределения в командной строке.

Если используются оба параметра, то значения --set объединяются в --values с более высоким приоритетом. Переопределения, указанные с помощью --set, сохраняются в ConfigMap. Значения, которые были --set, можно просмотреть для данного выпуска с помощью helm get values <release-name>. Значения --set, можно очистить, выполнив helm upgrade с --reset-values.

Формат и Ограничения--set

Параметр --set принимает ноль или более пар имя/значение. В самом простом случае он используется следующим образом: --set name=value. Пример в YAML формате:

name: value

Несколько значений разделяются символами,. --set a=b,c=d в YAML формате выглядит так:

a: b
c: d

Поддерживаются более сложные выражения. Например, --set outer.inner=value

outer:
  inner: value

Списки могут быть предоставлены путем включения значений в { и }. Например, --set name={a, b, c}:

name:
  - a
  - b
  - c

Начиная с Helm 2.5.0, доступ к элементам списка возможен с помощью синтаксиса индекса массива. Например, --set servers[0].port=80:

servers:
  - port: 80

Можно задать несколько значений. Строка --set servers[0].port=80,servers[0].host=example становится:

servers:
  - port: 80
    host: example

Иногда вам нужно использовать специальные символы в --set. Вы можете использовать обратную косую черту для экранирования символов; --set name=value1\,value2:

name: "value1,value2"

Точно так же вы можете экранировать точки, что может пригодиться, когда chart-ы используют функцию toYaml для анализа аннотаций, меток и селекторов узлов. Пример синтаксиса --set nodeSelector."kubernetes\.io/role"=master:

nodeSelector:
  kubernetes.io/role: master

Deeply nested data structures can be difficult to express using --set. Chart designers are encouraged to consider the --set usage when designing the format of a values.yaml file (read more about Values Files).

Дополнительные Методы Установки

helm install может установить один из нескольких источников:

  • Репозиторий chart-ов (как мы видели выше)
  • Локальное хранилище chart-ов (helm install foo foo-0.1.1.tgz)
  • Распакованная директория с chart-ами (helm install foo path/to/foo)
  • Полный URL до chart-а (helm install foo https://example.com/charts/foo-1.2.3.tgz)

'helm upgrade' и 'helm rollback': Обновление Релиза и Восстановление После Сбоя

Когда выпускается новая версия chart-а или когда вы хотите изменить конфигурацию своего релиза, вы можете использовать команду helm upgrade.

An upgrade takes an existing release and upgrades it according to the information you provide. Because Kubernetes charts can be large and complex, Helm tries to perform the least invasive upgrade. It will only update things that have changed since the last release.

Обновление использует существующий релиз и обновляет его в соответствии с предоставленной вами информацией. Из-за того, что chart-ы Kubernetes могут быть большими и сложными, Helm пытается выполнить наименее инвазивное обновление. Он будет обновлять только то, что изменилось с момента последнего релиза.

$ helm upgrade -f panda.yaml happy-panda bitnami/wordpress

В приведенном выше случае релиз happy-panda обновляется с тем же chart, но с новым файлом YAML:

mariadb.auth.username: user1

Вы можете использовать helm get values, чтобы увидеть, заработа ли новая версия.

$ helm get values happy-panda
mariadb:
  auth:
    username: user1

Команда helm get - это полезный инструмент для просмотра релизов в кластере. И как мы видим выше, она показывает, что наши новые значения из panda.yaml были развернуты в кластере.

Теперь, если что-то идет не так, как планировалось во время выпуска, легко откатиться к предыдущему выпуску, используя helm rollback [RELEASE] [REVISION].

$ helm rollback happy-panda 1

Пример выше возвращает happy-panda к самой первой версии выпуска. Версия выпуска-это инкрементная версия. Каждый раз, когда происходит установка, обновление или откат, номер версии увеличивается на 1. Первый номер редакции всегда равен 1. Мы можем использовать helm history [RELEASE], чтобы увидеть номера версий для определенного релиза.

Полезные Опции для Установки/Обновлении/Отката

Существует несколько других полезных параметров, которые вы можете указать для настройки поведения Helm во время установки/обновления/отката. Обратите внимание, что это не полный список флагов cli. Чтобы увидеть описание всех флагов, просто запустите helm <command> --help.

  • --timeout: Go duration время ожидания выполнения Kubernetes команд. Стандартное время 5m0s.
  • --wait: Ждет, пока все Pods не будут в состоянии готовности, Развертывания должны иметь минимум (Desired минус maxUnavailable) Pods в состоянии готовности и Services должны иметь IP адрес (и Ingress если есть LoadBalancer) перед пометкой успешного релиза. Он будет ждать до значения --timeout. Если тайм - аут достигнут, то релиз будет помечен как FAILED. Note: In scenarios where Deployment has replicas set to 1 and maxUnavailable is not set to 0 as part of rolling update strategy, --wait will return as ready as it has satisfied the minimum Pod in ready condition.
  • --no-hooks: Это пропускает запуск hooks для команды
  • --recreate-pods (доступно только для upgrade и rollback): Этот флаг приведет к пересозданию всех pods (with the exception of pods belonging to deployments). (УСТАРЕЛО в Helm 3)

'helm uninstall': Удаление Релиза

Когда потребуется удалить релиз из кластера, используйте команду helm uninstall:

$ helm uninstall happy-panda

Это приведет к удалению релиза из кластера. Вы можете просмотреть все ваши текущие развернутые релизы с помощью команды helm list :

$ helm list
NAME            VERSION UPDATED                         STATUS          CHART
inky-cat        1       Wed Sep 28 12:59:46 2016        DEPLOYED        alpine-0.1.0

Из примера выше видно, что релиз happy-panda был удален.

В предыдущих версиях Helm, когда релиз удалялся, запись о его удалении оставалась. В Helm 3, Удаление удаляет записи релиза, а также. Если вы хотите сохранить запись об удалении выпуска, используйте helm uninstall --keep-history. Использование helm list --uninstalled покажет только те выпуски, которые были удалены с флагом --keep-history.

Флаг helm list --all покажет вам все релизы, сохраненные Helm, включая записи для неудачных или удаленных элементов (если был указан параметр --keep-history ):

$  helm list --all
NAME            VERSION UPDATED                         STATUS          CHART
happy-panda     2       Wed Sep 28 12:47:54 2016        UNINSTALLED     wordpress-10.4.5.6.0
inky-cat        1       Wed Sep 28 12:59:46 2016        DEPLOYED        alpine-0.1.0
kindred-angelf  2       Tue Sep 27 16:16:10 2016        UNINSTALLED     alpine-0.1.0

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

'helm repo': Работа с Репозиториями

Helm 3 больше не поставляется со стандартным хранилищем chart-ов. Команды helm repo предоставляет возможности добавления, перечисления и удаления репозиториев.

Узнать о настроенных репозитории можно с помощью helm repo list:

$ helm repo list
NAME            URL
stable          https://charts.helm.sh/stable
mumoshu         https://mumoshu.github.io/charts

Новые репозитории могут быть добавлены с помощью helm repo add:

$ helm repo add dev https://example.com/dev-charts

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

Репозитории могут быть удалены с помощью helm repo remove.

Создание Собственных Chart-ов

Руководство по разработке Chart-ов объясняет, как создавать свои собственные chart-ы. Но вы можете быстро начать работу с помощью команды helm create:

$ helm create deis-workflow
Creating deis-workflow

Теперь у вас есть chart в ./deis-workflow. Вы можете редактировать его и создавать свои собственные шаблоны.

У Helm есть линтер для проверки корректности chart-а, воспользоваться им можно с помощью helm lint.

Когда придет время упаковать chart в пакет для распространения вам поможет команда helm package

$ helm package deis-workflow
deis-workflow-0.1.0.tgz

Теперь вы можете с легкостью поставить этот chart в ваш Helm с помощью helm install

$ helm install deis-workflow ./deis-workflow-0.1.0.tgz
...

Упакованные chart-ы могут быть загружены в репозиторий chart-ов. Смотрите документацию по Helm chart репозитории для того, что бы узнать новые детали.

Заключение

В этой главе рассмотрены основные схемы использования клиента helm, включая поиск, установку, обновление и удаление. Он также охватывает полезные служебные команды, такие как helm status, helm get, и helm repo.

Для получения дополнительной информации об этих командах обратитесь к встроенной справке Helm: helm help.

Helm Project
Blog
Events
Quick Start Guide
Code of Conduct
Charts
Introduction
Chart tips & tricks
Developing Charts
Search 800+ Charts
Development
#helm-dev (slack)
Contribution Guide
Maintainers
Weekly Meetings
Community
#helm-users (slack)
Mailing List
Logos & Art
Twitter

Мы являемся выпускным проектом Cloud Native Computing Foundation.

We are a Cloud Native Computing Foundation project

© Helm Authors 2021 | Documentation distributed under CC-BY-4.0

© 2021 The Linux Foundation. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page.