Отправка и извлечение чартов Helm в Реестр контейнеров Azure

  • Статья

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

В этой статье показано, как разместить репозитории чартов Helm в Реестре контейнеров Azure с помощью команд Helm 3 и сохранения чартов в виде артефактов OCI. Во многих случаях для разрабатываемых приложений можно создавать и отправлять собственные чарты. Дополнительные сведения о создании собственных чартов Helm см. в разделе Руководство разработчика шаблона чарта. Можно также сохранить существующий чарт Helm из другого репозитория Helm.

Важно!

Эта статья обновлена с помощью команд Helm 3. Helm 3.7 включает изменения в командах CLI Helm и поддержку OCI, реализованную в более ранних версиях Helm 3. Согласно проекту helm развивается вместе с версией. Рекомендуется использовать версию не ниже 3.7.2.

Helm 3 или Helm 2?

Для хранения, установки чартов Helm и управления ими используются команды в интерфейсе командной строки Helm. Основные выпуски Helm включают Helm 3 и Helm 2. Дополнительные сведения о различиях версий см. в разделе часто задаваемых вопросов о версии.

Для размещения чартов Helm в Реестре контейнеров Azure следует использовать Helm 3. Возможности Helm 3:

  • Хранение чатов Helm в репозиториях в Реестре контейнеров Azure и управление ими
  • Чарты Helm хранятся в реестре как артефакты OCI. Реестр контейнеров Azure предоставляет общедоступную поддержку артефактов OCI, включая чарты Helm.
  • Проверка подлинности в реестре с помощью команды helm registry login или az acr login.
  • Использование команд helm для отправки, извлечения чартов Helm в реестре и управления ими.
  • Использование helm install для установки чартов в кластер Kubernetes из реестра.

Поддерживаемые компоненты

Реестр контейнеров Azure поддерживает определенные функции управления чартами Helm в зависимости от того, используется ли Helm 3 (текущая версия) или Helm 2 (нерекомендуемая версия).

Компонент Helm 2 Helm 3
Управление чартами с помощью команд az acr helm ✔️
Хранение чартов в виде артефактов OCI ✔️
Управление чартами с помощью команд az acr repository и колонки Репозитории на портале Azure ✔️

Примечание.

Начиная с Helm 3 команды az acr helm для использования с клиентом Helm 2 являются устаревшими. Перед удалением команды будет отправлено соответствующее уведомление (не позднее чем за 3 месяца).

Совместимость версий чартов

Следующие версии чартов Helm могут храниться в Реестре контейнеров Azure и устанавливаться клиентами Helm 2 и Helm 3.

Версия Helm 2 Helm 3
apiVersion v1 ✔️ ✔️
apiVersion v2 ✔️

Переход с Helm 2 на Helm 3

Если вы ранее сохранили и развернули чарты с помощью Helm 2 и Реестра контейнеров Azure, мы рекомендуем перейти на Helm 3. См.

Необходимые компоненты

Для сценария, описанного в этой статье, необходимы следующие ресурсы.

  • Реестр контейнеров Azure в подписке Azure. При необходимости создайте реестр с помощью портала Azure или Azure CLI.
  • Клиент Helm версии 3.7 или более поздней — выполните команду helm version, чтобы узнать текущую версию. Дополнительные сведения о том, как установить и обновить Helm, см. здесь. При обновлении более ранней версии Helm 3 ознакомьтесь с заметками о выпуске.
  • Кластер Kubernetes, куда будет установлен чарт Helm. При необходимости создайте кластер AKS с помощью Azure CLI, с помощью Azure PowerShell или с помощью портал Azure.
  • Azure CLI версии 2.0.71 или более поздней. Выполните команду az --version, чтобы узнать номер версии. Если вам необходимо выполнить установку или обновление, см. статью Установка Azure CLI 2.0.

Настройка клиента Helm

Используйте команду helm version, чтобы убедиться, что Helm 3 установлен:

helm version

Примечание.

Указанная версия должна быть не ниже 3.8.0, так как поддержка OCI в более ранних версиях была экспериментальной.

Задайте следующие переменные среды для целевого реестра. ACR_NAME — это имя ресурса реестра. Если URL-адрес реестра ACR — myregistry.azurecr.io, задайте для ACR_NAME значение myregistry

ACR_NAME=<container-registry-name>

Создание примера чарта

Создайте тестовый чарт с помощью следующих команд:

mkdir helmtest

cd helmtest
helm create hello-world

В качестве базового примера измените каталог на папку templates и сначала удалите содержимое:

cd hello-world/templates
rm -rf *

В папке templates создайте файл с именем configmap.yaml, выполнив следующую команду:

cat <<EOF > configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-world-configmap
data:
  myvalue: "Hello World"
EOF

Дополнительные сведения о создании и выполнении этого примера см. в разделе Начало работы в документации по Helm.

Сохраните диаграмму в локальный архив

Измените каталог на подкаталог hello-world. Затем выполните команду helm package, чтобы сохранить диаграмму в локальном архиве.

В следующем примере диаграмма сохраняется с именем и версией в Chart.yaml.

cd ..
helm package .

Она выводит выходные данные следующего вида:

Successfully packaged chart and saved it to: /my/path/hello-world-0.1.0.tgz

Проверка подлинности в реестре

Выполните команду helm registry login для проверки подлинности в реестре. Можно передать учетные данные реестра, соответствующие вашему сценарию, например, учетные данные субъекта-службы, идентификатор пользователя или маркер безопасности в области репозитория.

  • Проверка подлинности с помощью субъекта-службы Microsoft Entra с разрешениями на вытягивание и отправку (роль AcrPush) в реестр. 
    SERVICE_PRINCIPAL_NAME=<acr-helm-sp>
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \
          --scopes $(az acr show --name $ACR_NAME --query id --output tsv) \
           --role acrpush \
          --query "password" --output tsv)
USER_NAME=$(az identity show -n $SERVICE_PRINCIPAL_NAME -g $RESOURCE_GROUP_NAME --subscription $SUBSCRIPTION_ID --query "clientId" -o tsv)
  • Проверка подлинности с помощью отдельного удостоверения Microsoft Entra для отправки и извлечения диаграмм Helm с помощью маркера AD. 
    USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
  • Проверка подлинности с помощью токена уровня репозитория (предварительная версия) 
    USER_NAME="helmtoken"
PASSWORD=$(az acr token create -n $USER_NAME \
                  -r $ACR_NAME \
                  --scope-map _repositories_admin \
                  --only-show-errors \
                  --query "credentials.passwords[0].value" -o tsv)
  • Укажите учетные данные в helm registry login. 
    helm registry login $ACR_NAME.azurecr.io \
  --username $USER_NAME \
  --password $PASSWORD

Передача диаграммы в реестр в качестве артефакта OCI

В CLI Helm 3 выполните команду helm push, чтобы отправить архив диаграммы в полный целевой репозиторий: Разделите слова в названиях диаграмм и используйте только строчные буквы и цифры. В следующем примере пространство имен целевого репозитория — helm/hello-world, а диаграмма помечена как 0.1.0:

helm push hello-world-0.1.0.tgz oci://$ACR_NAME.azurecr.io/helm

После успешной отправки выходные данные выглядят примерно так:

Pushed: <registry>.azurecr.io/helm/hello-world:0.1.0
digest: sha256:5899db028dcf96aeaabdadfa5899db02589b2899b025899b059db02

Вывод списка диаграмм в репозитории

Как и в случае с образами, хранящимися в реестре контейнеров Azure, можно использовать команды az acr repository, чтобы отобразить репозитории, в которых размещены чарты, а также теги и манифесты чарта.

Например, выполните команду az acr repository show, чтобы просмотреть свойства репозитория, созданного на предыдущем шаге.

az acr repository show \
  --name $ACR_NAME \
  --repository helm/hello-world

Она выводит выходные данные следующего вида:

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2021-10-05T12:11:37.6701689Z",
  "imageName": "helm/hello-world",
  "lastUpdateTime": "2021-10-05T12:11:37.7637082Z",
  "manifestCount": 1,
  "registry": "mycontainerregistry.azurecr.io",
  "tagCount": 1
}

Чтобы просмотреть сведения о чарте, хранящемся в репозитории, выполните команду az acr manifest list-metadata. Например:

az acr manifest list-metadata \
  --registry $ACR_NAME \
  --name helm/hello-world

В выходных данных, сокращенных в этом примере, отображается configMediaType для application/vnd.cncf.helm.config.v1+json:

[
  {
    [...]
    "configMediaType": "application/vnd.cncf.helm.config.v1+json",
    "createdTime": "2021-10-05T12:11:37.7167893Z",
    "digest": "sha256:0c03b71c225c3ddff53660258ea16ca7412b53b1f6811bf769d8c85a1f0663ee",
    "imageSize": 3301,
    "lastUpdateTime": "2021-10-05T12:11:37.7167893Z",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "tags": [
      "0.1.0"
    ]

Установка чарта Helm

Выполните команду helm install, чтобы установить диаграмму Helm, отправленную в реестр. Тег диаграммы передается с помощью параметра --version. Укажите имя выпуска, например myhelmtest, или передайте параметр --generate-name. Например:

helm install myhelmtest oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

Выходные данные после успешной установки чарта аналогичны следующим:

NAME: myhelmtest
LAST DEPLOYED: Tue Oct  4 16:59:51 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

Проверьте правильность установки, выполнив команду helm get manifest.

helm get manifest myhelmtest

Команда возвращает данные YAML в файле шаблона configmap.yaml.

Выполните команду helm uninstall, чтобы удалить выпуск чарта в кластере:

helm uninstall myhelmtest

Вытягивание диаграммы в локальный архив

При необходимости можно извлечь диаграмму из реестра контейнеров в локальный архив с помощью helm pull. Тег диаграммы передается с помощью параметра --version. Если локальный архив доступен по текущему пути, эта команда перезаписывает его.

helm pull oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

Удаление чарта из реестра

Чтобы удалить чарт из реестра контейнеров, используйте команду az acr repository delete. Выполните следующую команду и подтвердите операцию при появлении соответствующего запроса:

az acr repository delete --name $ACR_NAME --image helm/hello-world:0.1.0

Перенос реестра для хранения артефактов OCI Helm

Если вы ранее настроили реестр контейнеров Azure в качестве репозитория чартов с помощью Helm 2 и команд az acr helm, рекомендуем обновить клиент для Helm 3. Затем выполните следующие действия, чтобы сохранить диаграммы в виде артефактов OCI в реестре.

Важно!

  • После завершения перехода с репозитория чартов Helm 2 (на основе файла index.yaml) на репозитории артефактов OCI используйте интерфейс командной строки Helm и команды az acr repository для управления чартами. См. предыдущие разделы данной статьи.
  • Репозитории артефактов OCI Helm не обнаруживаются с помощью таких команд Helm, как helm search и helm repo list. Дополнительные сведения о командах Helm, используемых для хранения чартов в качестве артефактов OCI, см. в документации по Helm.

Включение поддержки OCI (включено по умолчанию в Helm версии 3.8.0)

Убедитесь, что вы используете клиент Helm 3:

helm version

Если вы используете Helm версии 3.8.0 или более поздней версии, эта функция включена по умолчанию. Если вы используете более раннюю версию, можно включить поддержку OCI, задав переменную среды:

export HELM_EXPERIMENTAL_OCI=1

Вывод списка текущих чартов

Выведите список чартов, хранящихся в реестре, с именем myregistry:

helm search repo myregistry

В выходных данных показаны чарты и их версии:

NAME                            CHART VERSION   APP VERSION     DESCRIPTION                                       
myregistry/ingress-nginx        3.20.1          0.43.0          Ingress controller for Kubernetes...
myregistry/wordpress            9.0.3           5.3.2           Web publishing platform for building...
[...]

Локальное вытягивание архивов диаграммы

Для каждой диаграммы в репозитории выполните локальное вытягивание архива диаграммы и запишите имя файла:

helm pull myregisry/ingress-nginx
ls *.tgz

Создается локальный архив диаграммы, например ingress-nginx-3.20.1.tgz.

Передача диаграмм как артефактов OCI в реестр

Войдите в реестр:

az acr login --name $ACR_NAME

Передайте каждую диаграмму в реестр: Пример:

helm push ingress-nginx-3.20.1.tgz oci://$ACR_NAME.azurecr.io/helm

После отправки чарта убедитесь, что он хранится в реестре:

az acr repository list --name $ACR_NAME

После отправки всех чартов при необходимости удалите репозиторий чартов Helm 2 из реестра. Это сокращает объем хранилища в реестре:

helm repo remove $ACR_NAME

Следующие шаги