#Работа с Helm charts

#1. Понимание Helm

Helm — это менеджер пакетов, который упрощает развертывание приложений и сервисов в кластерах Alauda Container Platform.
Helm использует формат упаковки, называемый charts. Helm chart — это набор файлов, описывающих ресурсы Kubernetes.
Создание chart в кластере порождает экземпляр chart, называемый release.
Каждый раз при создании chart, обновлении или откате release создаётся инкрементальная ревизия.

#1.1. Ключевые возможности

Helm предоставляет возможность:

• Искать большое количество charts в репозиториях charts
• Модифицировать существующие charts
• Создавать собственные charts с использованием ресурсов Kubernetes
• Упаковывать приложения и делиться ими в виде charts

#1.2. Каталог

Каталог построен на основе Helm и представляет собой комплексную платформу управления распространением Chart, расширяющую ограничения CLI-инструмента Helm. Платформа позволяет разработчикам удобнее управлять, развертывать и использовать charts через удобный интерфейс.

#Определения терминов

#1.3. Понимание HelmRequest

В Alauda Container Platform развертывания Helm в основном управляются через кастомный ресурс HelmRequest. Такой подход расширяет стандартный функционал Helm и интегрирует его в нативную модель ресурсов Kubernetes.

#Отличия HelmRequest от Helm

Стандартный Helm использует CLI-команды для управления релизами, тогда как в Alauda Container Platform используются ресурсы HelmRequest для определения, развертывания и управления Helm charts. Основные отличия:

1. Декларативный vs Императивный: HelmRequest обеспечивает декларативный подход к развертыванию Helm, в то время как традиционный Helm CLI — императивный.
2. Нативность Kubernetes: HelmRequest — это кастомный ресурс, напрямую интегрированный с API Kubernetes.
3. Непрерывная синхронизация: Captain постоянно отслеживает и синхронизирует ресурсы HelmRequest с их желаемым состоянием.
4. Поддержка мультикластерности: HelmRequest поддерживает развертывания в нескольких кластерах через платформу.
5. Интеграция с функциями платформы: HelmRequest может интегрироваться с другими функциями платформы, такими как ресурсы Application.

#Интеграция HelmRequest и Application

Ресурсы HelmRequest и Application концептуально схожи, и пользователи могут захотеть видеть их единообразно. Платформа предоставляет механизм синхронизации HelmRequest как ресурсов Application.

Пользователи могут пометить HelmRequest для развертывания как Application, добавив следующую аннотацию:

alauda.io/create-app: "true"

При включении этой функции в UI платформы отображаются дополнительные поля и ссылки на соответствующую страницу Application.

#Рабочий процесс развертывания

Рабочий процесс развертывания charts через HelmRequest включает:

1. Пользователь создаёт или обновляет ресурс HelmRequest
2. HelmRequest содержит ссылки на chart и значения для применения
3. Captain обрабатывает HelmRequest и создаёт Helm Release
4. Release содержит развернутые ресурсы
5. Metis отслеживает HelmRequest с аннотациями приложения и синхронизирует их с Applications
6. Application предоставляет единый обзор развернутых ресурсов

#Определения компонентов

• HelmRequest: Определение кастомного ресурса, описывающего желаемое развертывание Helm chart
• Captain: Контроллер, обрабатывающий ресурсы HelmRequest и управляющий Helm релизами (исходный код доступен по адресу https://github.com/alauda/captain)
• Release: Развернутый экземпляр Helm chart
• Charon: Компонент, отслеживающий HelmRequest и создающий соответствующие ресурсы Application
• Application: Унифицированное представление развернутых ресурсов с дополнительными возможностями управления
• Archon-api: Компонент, отвечающий за специфические расширенные функции API внутри платформы

#2 Развертывание Helm Charts как приложений через CLI

#2.1 Обзор рабочего процесса

Подготовка chart → Упаковка chart → Получение API токена → Создание репозитория chart → Загрузка chart → Загрузка связанных образов → Развертывание приложения → Обновление приложения → Удаление приложения → Удаление репозитория chart

#2.2 Подготовка Chart

Helm использует формат упаковки, называемый charts. Chart — это набор файлов, описывающих ресурсы Kubernetes. Один chart может использоваться для развертывания всего — от простого pod до сложного стека приложений.

См. официальную документацию: Helm Charts Documentation

Пример структуры каталога chart:

nginx/
├── Chart.lock
├── Chart.yaml
├── README.md
├── charts/
│   └── common/
│       ├── Chart.yaml
│       ├── README.md
│       ├── templates/
│       │   ├── _affinities.tpl
│       │   ├── _capabilities.tpl
│       │   ├── _errors.tpl
│       │   ├── _images.tpl
│       │   ├── _ingress.tpl
│       │   ├── _labels.tpl
│       │   ├── _names.tpl
│       │   ├── _secrets.tpl
│       │   ├── _storage.tpl
│       │   ├── _tplvalues.tpl
│       │   ├── _utils.tpl
│       │   ├── _warnings.tpl
│       │   └── validations/
│       │       ├── _cassandra.tpl
│       │       ├── _mariadb.tpl
│       │       ├── _mongodb.tpl
│       │       ├── _postgresql.tpl
│       │       ├── _redis.tpl
│       │       └── _validations.tpl
│       └── values.yaml
├── ci/
│   ├── ct-values.yaml
│   └── values-with-ingress-metrics-and-serverblock.yaml
├── templates/
│   ├── NOTES.txt
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── extra-list.yaml
│   ├── health-ingress.yaml
│   ├── hpa.yaml
│   ├── ingress.yaml
│   ├── ldap-daemon-secrets.yaml
│   ├── pdb.yaml
│   ├── server-block-configmap.yaml
│   ├── serviceaccount.yaml
│   ├── servicemonitor.yaml
│   ├── svc.yaml
│   └── tls-secrets.yaml
├── values.descriptor.yaml
├── values.schema.json
└── values.yaml

Описание ключевых файлов:

• values.descriptor.yaml (опционально): Используется с ACP UI для отображения удобных форм
• values.schema.json (опционально): Валидирует содержимое values.yaml и отображает простой UI
• values.yaml (обязательно): Определяет параметры развертывания chart

#2.3 Упаковка Chart

Используйте команду helm package для упаковки chart:

helm package nginx
# 输出: Successfully packaged chart and saved it to: /charts/nginx-8.8.0.tgz

#2.4 Получение API токена

1. В Alauda Container Platform нажмите на аватар в правом верхнем углу → Profile
2. Нажмите Add Api Token
3. Введите подходящее описание и срок действия
4. Сохраните отображённый токен (показывается только один раз)

#2.5 Создание репозитория Chart

Создайте локальный репозиторий chart через API:

curl -k --request POST \
--url https://$ACP_DOMAIN/catalog/v1/chartrepos \
--header 'Authorization:Bearer $API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "apiVersion": "v1",
  "kind": "ChartRepoCreate",
  "metadata": {
    "name": "test",
    "namespace": "cpaas-system"
  },
  "spec": {
    "chartRepo": {
      "apiVersion": "app.alauda.io/v1beta1",
      "kind": "ChartRepo",
      "metadata": {
        "name": "test",
        "namespace": "cpaas-system",
        "labels": {
          "project.cpaas.io/catalog": "true"
        }
      },
      "spec": {
        "type": "Local",
        "url": null,
        "source": null
      }
    }
  }
}'

#2.6 Загрузка Chart

Загрузите упакованный chart в репозиторий:

curl -k --request POST \
--url https://$ACP_DOMAIN/catalog/v1/chartrepos/cpaas-system/test/charts \
--header 'Authorization:Bearer $API_TOKEN' \
--data-binary @"/root/charts/nginx-8.8.0.tgz"

#2.7 Загрузка связанных образов

1. Скачайте образ: docker pull nginx

2. Сохраните в tar-пакет: docker save nginx > nginx.latest.tar

3. Загрузите и отправьте в приватный реестр:

   docker load -i nginx.latest.tar
   docker tag nginx:latest 192.168.80.8:30050/nginx:latest
   docker push 192.168.80.8:30050/nginx:latest

#2.8 Развертывание приложения

Создайте ресурс Application через API:

curl -k --request POST \
--url https://$ACP_DOMAIN/acp/v1/kubernetes/$CLUSTER_NAME/namespaces/$NAMESPACE/applications \
--header 'Authorization:Bearer $API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "apiVersion": "app.k8s.io/v1beta1",
  "kind": "Application",
  "metadata": {
    "name": "test",
    "namespace": "catalog-ns",
    "annotations": {
      "app.cpaas.io/chart.source": "test/nginx",
      "app.cpaas.io/chart.version": "8.8.0",
      "app.cpaas.io/chart.values": "{\"image\":{\"pullPolicy\":\"IfNotPresent\"}}"
    },
    "labels": {
      "sync-from-helmrequest": "true"
    }
  }
}'

#2.9 Обновление приложения

Обновите приложение с помощью PATCH-запроса:

curl -k --request PATCH \
--url https://$ACP_DOMAIN/acp/v1/kubernetes/$CLUSTER_NAME/namespaces/$NAMESPACE/applications/test \
--header 'Authorization:Bearer $API_TOKEN' \
--header 'Content-Type: application/merge-patch+json' \
--data '{
  "apiVersion": "app.k8s.io/v1beta1",
  "kind": "Application",
  "metadata": {
    "annotations": {
      "app.cpaas.io/chart.values": "{\"image\":{\"pullPolicy\":\"Always\"}}"
    }
  }
}'

#2.10 Удаление приложения

Удалите ресурс Application:

curl -k --request DELETE \
--url https://$ACP_DOMAIN/acp/v1/kubernetes/$CLUSTER_NAME/namespaces/$NAMESPACE/applications/test \
--header 'Authorization:Bearer $API_TOKEN'

#2.11 Удаление репозитория Chart

curl -k --request DELETE \
--url https://$ACP_DOMAIN/apis/app.alauda.io/v1beta1/namespaces/cpaas-system/chartrepos/test \
--header 'Authorization:Bearer $API_TOKEN'

#3. Развертывание Helm Charts как приложений через UI

#3.1 Обзор рабочего процесса

Добавление шаблонов в управляемые репозитории → Загрузка шаблонов → Управление версиями шаблонов

#3.2 Предварительные условия

Репозитории шаблонов добавляются администраторами платформы. Пожалуйста, обратитесь к администратору платформы, чтобы получить имена доступных репозиториев шаблонов типа Chart или OCI Chart с правами Management.

#3.3 Добавление шаблонов в управляемые репозитории

1. Перейдите в Catalog.

2. В левой навигационной панели нажмите Helm Charts.

3. Нажмите Add Template в правом верхнем углу страницы и выберите репозиторий шаблонов согласно параметрам ниже.

   Параметр	Описание
   Template Repository	Синхронизирует шаблон напрямую с репозиторием шаблонов типа Chart или OCI Chart с правами Management. Владельцы проектов, назначенные на этот Template Repository, могут напрямую использовать шаблон.
   Template Directory	Если выбран тип репозитория шаблонов OCI Chart, необходимо выбрать или вручную ввести директорию для хранения Helm Chart. Примечание: При ручном вводе новой директории платформа создаст эту директорию в репозитории шаблонов, но существует риск неудачи создания.

4. Нажмите Upload Template и загрузите локальный шаблон в репозиторий.

5. Нажмите Confirm. Процесс загрузки шаблона может занять несколько минут, пожалуйста, подождите.

   Примечание: Когда статус шаблона изменится с Uploading на Upload Successful, это означает успешную загрузку шаблона.

6. Если загрузка не удалась, устраните неполадки согласно появившимся подсказкам.

   Примечание: Неправильный формат файла означает проблему с файлами в загруженном архиве, например, отсутствие содержимого или неправильное форматирование.

#3.4 Удаление конкретных версий шаблонов

Если версия шаблона больше не актуальна, её можно удалить.

#Шаги для выполнения

1. Перейдите в Catalog.

2. В левой навигационной панели нажмите Helm Charts.

3. Нажмите на карточку Chart для просмотра деталей.

4. Нажмите Manage Versions.

5. Найдите устаревший шаблон, нажмите Delete и подтвердите.

   После удаления версии соответствующее приложение не сможет быть обновлено.