Cozystack Руководство по разработке

Cozystack — платформа на основе операторов. Начальная загрузка и текущее управление осуществляются набором контроллеров, работающих внутри кластера. Высокоуровневый поток выглядит так:

Инсталлятор чарта (packages/core/installer) применяется через helm install. Он разворачивает Deployment cozystack-operator в пространстве имён cozy-system.
cozystack-operator запускается и выполняет однократную начальную загрузку:
- Устанавливает CRD Cozystack (Package, PackageSource) из встроенных манифестов (internal/crdinstall).
- Устанавливает компоненты Flux (source-controller, helm-controller, source-watcher) из встроенных манифестов (internal/fluxinstall).
- Создаёт начальный OCIRepository (cozystack-platform) из значений platformSourceUrl и platformSourceRef, заданных в инсталляторе.
- Создаёт PackageSource, ссылающийся на начальный OCIRepository.
Цикл согласования берёт управление. Оператор следит за CRD PackageSource и Package и преобразует их в объекты Flux HelmRelease. Flux затем устанавливает реальные Helm-чарты и управляет ими.
Platform chart (packages/core/platform) разворачивается как обычный Package. Он читает конфигурацию кластера из ресурса cozystack.cozystack-platform Package и создаёт шаблоны манифестов пакетов, определяющих, какие системные компоненты должны быть установлены. Platform chart также создаёт вторичный OCIRepository (cozystack-packages), копируя спецификацию из начального OCIRepository. Все PackageSource ссылаются на этот вторичный репозиторий. При обновлениях platform chart выполняет миграции как pre-upgrade хуки перед созданием или обновлением HelmRelease компонентов.
FluxCD — движок выполнения, он согласует объекты HelmRelease, созданные оператором, загружает артефакты чартов из ресурсов ExternalArtifact и применяет их к кластеру.

Полную цепочку согласования (PackageSource → ArtifactGenerator → ExternalArtifact → Package → HelmRelease → Pods), разрешение зависимостей, потоки обновления и отката, а также CLI cozypkg см. в разделе Ключевые концепции.

OCIRepository и поток миграции

Cozystack использует два ресурса OCIRepository для управления обновлениями платформы:

OCIRepository	Создаётся	Ссылается на
cozystack-platform	cozystack-operator	Настраивается через значения инсталлятора (`platformSourceUrl`, `platformSourceRef`)
cozystack-packages	Platform chart (`repository.yaml`)	Копирует спецификацию из `cozystack-platform`

Все PackageSource в packages/core/platform/sources/ ссылаются на cozystack-packages.

Выполнение миграций

Миграции выполняются как Helm pre-upgrade хуки в platform chart:

# packages/core/platform/templates/migration-hook.yaml
metadata:
  name: cozystack-migration-hook
annotations:
  helm.sh/hook: pre-upgrade,pre-install
  helm.sh/hook-weight: "1"

Контейнер миграции считывает текущую версию из ConfigMap cozystack-version и выполняет скрипты миграции последовательно от CURRENT_VERSION до TARGET_VERSION - 1. Каждая миграция обновляет ConfigMap при успехе, обеспечивая идемпотентность миграций и возможность возобновления после сбоев.

Зачем два репозитория?

Разделение гарантирует, что:

Начальный OCIRepository управляется оператором (через значения инсталлятора).
Все PackageSource имеют согласованную ссылку (cozystack-packages), а не указывают напрямую на источник, управляемый оператором.
Platform chart может выполнять миграции перед созданием вторичного OCIRepository, гарантируя выполнение миграций до обновления компонентов.

Ключевые бинарные файлы

Бинарный файл	Источник	Роль
cozystack-operator	`cmd/cozystack-operator`	Начальная загрузка (CRD, Flux, источник платформы), согласование `PackageSource` и `Package`, репликация секрета `cozystack-values`.
cozystack-controller	`cmd/cozystack-controller`	Согласование рабочих нагрузок и `ApplicationDefinition`, управление дашбордами.
cozystack-api	`cmd/cozystack-api`	Уровень агрегации API Kubernetes для групп API `apps.cozystack.io` и `core.cozystack.io`.
cozypkg	`cmd/cozypkg`	CLI для управления пакетами.

Структура репозитория

Основная структура репозитория cozystack:

├── api                 # Go-типы для CRD Cozystack (Package, PackageSource и т.д.)
├── cmd                 # Точки входа для всех бинарных файлов
│   ├── cozystack-operator      # Основной оператор платформы
│   ├── cozystack-controller    # Контроллеры рабочих нагрузок и приложений
│   ├── cozystack-api           # Агрегированный API-сервер
│   └── cozypkg                 # CLI для управления пакетами
├── internal            # Реализации контроллеров и согласователей
│   ├── operator                # Согласователи PackageSource и Package
│   ├── controller              # Контроллеры рабочих нагрузок и ApplicationDefinition
│   ├── fluxinstall             # Встроенные манифесты Flux и инсталлятор
│   ├── crdinstall              # Встроенные манифесты CRD и инсталлятор
│   └── cozyvaluesreplicator    # Логика репликации секретов
├── packages            # Helm-чарты, организованные по слоям
│   ├── core                    # Начальная загрузка и конфигурация платформы
│   ├── system                  # Инфраструктурные операторы и upstream-чарты
│   ├── apps                    # Пользовательские чарты приложений
│   └── extra                   # Чарты приложений для конкретных тенантов
├── pkg                 # Общие Go-библиотеки
├── dashboards          # Дашборды Grafana
├── hack                # Вспомогательные скрипты для локальной разработки
└── docs                # Журналы изменений и примечания к релизам

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

Пакеты

core

Core-пакеты отвечают за начальную загрузку и конфигурацию на уровне платформы.

installer

Helm-чарт, разворачивающий Deployment cozystack-operator. Он создаёт пространство имён cozy-system, ServiceAccount с правами cluster-admin и Deployment оператора с флагами, инициирующими установку CRD и Flux при запуске. Образ оператора и URL источника платформы задаются во время сборки.

platform

Helm-чарт, разворачиваемый как обычный Package (не применяется напрямую). Он читает конфигурацию кластера из ресурса cozystack.cozystack-platform Package и создаёт шаблоны манифестов согласно указанному варианту и настройкам компонентов, определяя, какие системные компоненты должны быть установлены.

flux-aio

Компоненты Flux, упакованные для развёртывания оператором.

talos

Конфигурационные ресурсы Talos OS.

Core-пакеты не используют Helm для применения манифестов; они предназначены для использования только как helm template . | kubectl apply -f -.

system

System-пакеты настраивают систему для управления и развёртывания пользовательских приложений. Необходимы для работы всей платформы. System-пакеты включают два вида компонентов:

Операторы (например, postgres-operator, kafka-operator, redis-operator): Контроллеры, умеющие управлять полным жизненным циклом конкретного приложения, включая операции второго дня.
Upstream Helm-чарты для приложений без выделенного оператора (например, nats, ingress-nginx): Эти чарты размещаются в system, чтобы пакеты apps и extra могли разворачивать их через Flux HelmRelease CR, фактически используя FluxCD в качестве оператора.

System-пакеты используют Helm для установки и управляются FluxCD.

apps

Эти пользовательские приложения отображаются в дашборде и включают манифесты для применения к кластеру. Чарты apps служат высокоуровневым API для пользователей. Они определяют только те параметры, которые должны быть открыты и проверены через values.schema.json, сохраняя интерфейс минимальным и безопасным. Чарты apps не должны содержать бизнес-логику развёртывания самого приложения — вместо этого они делегируют её оператору или FluxCD.

В зависимости от наличия выделенного оператора приложения apps следуют одному из двух паттернов:

Паттерн на основе оператора

Когда для приложения есть выделенный оператор (например, PostgreSQL, MongoDB, Redis, Kafka), чарт app создаёт экземпляры CRD, которыми управляет оператор: Оператор обрабатывает все детали развёртывания и операции второго дня (масштабирование, резервное копирование, восстановление).

packages/system/postgres-operator/ # Helm-чарт оператора
packages/apps/postgres/            # App-чарт создаёт postgresql.cnpg.io/v1.Cluster CR

Паттерн на основе HelmRelease

Когда для приложения нет выделенного оператора и стандартным методом развёртывания является Helm-чарт, основной upstream-чарт размещается в system/, а app-чарт создаёт Flux HelmRelease CR, указывающий на него:

packages/system/nats/ # Upstream Helm-чарт
packages/apps/nats/   # App-чарт создаёт HelmRelease CR

В этом случае FluxCD выступает оператором, управляя жизненным циклом Helm-релиза. App-чарт контролирует values.yaml для релиза. Другие примеры этого паттерна: extra/ingress, extra/seaweedfs, extra/monitoring.

extra

Аналогично apps, но не отображается в каталоге приложений. Могут устанавливаться только в составе тенанта. Разрешения на установку этих приложений настраиваются для каждого тенанта индивидуально. Подробнее о Системе тенантов читайте на странице основных концепций. В одном пространстве имён тенанта можно использовать только один тип приложения. Extra-пакеты следуют тем же двум архитектурным паттернам, что и apps (на основе оператора или HelmRelease). Пакеты apps и extra используют Helm для установки приложения и управляются FluxCD через дашборд.

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

Каждый пакет — это типичный Helm-чарт, содержащий все необходимые образы и манифесты для платформы. Мы рекомендуем упаковывать upstream-чарты в директорию ./charts и переопределяя values.yaml в корне приложения. Такая структура упрощает обновление upstream-чартов и внесение изменений в манифесты.

├── Chart.yaml                  # Определение Helm-чарта и описание параметров
├── Makefile                    # Общие цели для упрощения локальной разработки
├── charts                      # Директория для upstream-чартов
├── images                      # Директория для Docker-образов
├── patches                     # Опциональная директория для патчей upstream-чартов
├── templates                   # Дополнительные манифесты для upstream Helm-чарта
├── templates/dashboard-resourcemap.yaml # Роль для отображения ресурсов k8s в дашборде
├── values.yaml                 # Значения переопределения для upstream Helm-чарта
└── values.schema.json          # JSON-схема для валидации входных значений и отрисовки элементов UI в дашборде

Для генерации файлов README.md и values.schema.json можно использовать readme-generator от Bitnami. Просто установите его как бинарный файл readme-generator в своей системе и запустите генерацию командой make generate.

Принципы разработки Helm-чартов

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

Простое обновление upstream-чартов

Оригинальный upstream-чарт должен быть легко обновляемым, переопределяемым и изменяемым. Мы используем подход, при котором оригинальные чарты загружаются в ./charts и хранятся в оригинальном виде. Кастомизации вносятся через переопределения values.yaml и дополнительные templates/, а структурные изменения в upstream-чарте применяются через patches/. Такое разделение гарантирует простое обновление до новой upstream-версии: выполните make update, просмотрите diff и при необходимости повторно примените патчи.

Локальные артефакты

Патчи и образы контейнеров хранятся локально и являются частью пакета. Директория patches/ содержит любые изменения upstream-чарта, а директория images/ — Dockerfile для сборки всех необходимых образов. Это обеспечивает полную воспроизводимость — всё необходимое для сборки и запуска пакета находится внутри его директории.

В настоящее время не все пакеты собирают свои образы локально — некоторые всё ещё ссылаются на образы из внешних реестров.

Рабочий процесс локальной разработки и тестирования

Каждый пакет должен быть легко обновляемым и тестируемым локально на реальном кластере без использования CI-пайплайнов. Стандартные цели make (make image, make diff, make apply) обеспечивают быструю обратную связь: сборка образов, сравнение отрендеренных манифестов с живым кластером и их применение.

Без внешних зависимостей

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

Как отмечалось выше, полная самодостаточность образов находится в процессе реализации. Некоторые пакеты всё ещё зависят от внешних образов.

Разработка

Настройка Buildx

Для сборки образов необходимо установить и настроить плагин docker buildx. Вместо встроенного сборщика можно настроить дополнительные, которые могут быть удалёнными или поддерживать несколько архитектур. В этом примере показано, как настроить драйвер kubernetes, позволяющим собирать образы непосредственно в кластере Kubernetes:

docker buildx create \
  --bootstrap \
  --name=buildkit \
  --driver=kubernetes \
  --driver-opt=namespace=tenant-kvaps,replicas=2 \
  --platform=linux/amd64 \
  --platform=linux/arm64

Либо опустите параметры –driver*, чтобы настроить среду сборки в локальном Docker-окружении.

Управление пакетами

Каждое приложение включает Makefile для упрощения процесса разработки. Для каждого пакета мы следуем стандартному набору команд:

make update # Обновить Helm-чарт и версии из upstream-источника
make image  # Собрать Docker-образы, используемые в пакете
make show   # Показать вывод отрендеренных шаблонов
make diff   # Сравнить Helm-релиз с объектами в кластере Kubernetes
make apply  # Применить Helm-релиз к кластеру Kubernetes

Например, для обновления cilium:

cd packages/system/cilium  # Перейти в директорию приложения
make update                 # Загрузить новую версию из upstream
make image                  # Собрать образ cilium
git diff .                  # Показать diff с изменёнными манифестами
make diff                   # Показать diff с применёнными манифестами кластера
make apply                  # Применить изменённые манифесты к кластеру
kubectl get pod -n cozy-cilium # Проверить корректность работы
git commit -m "Update cilium to v1.15.5" # Зафиксировать изменения в ветке

Для сборки контейнера cozystack с обновлённым чартом:

cd packages/core/installer # Перейти в директорию пакета cozystack
make image-packages         # Собрать образ пакетов
make apply                  # Применить к кластеру
kubectl get pod -n cozy-system # Проверить корректность работы
kubectl get hr -A           # Проверить объекты HelmRelease

При пересборке образов указывайте переменную окружения REGISTRY, указывающую на ваш Docker-реестр. Не стесняйтесь заглядывать в каждый Makefile, чтобы лучше понять логику.

Тестирование

Платформа включает скрипт e2e.sh, выполняющий следующие задачи:

Запускает три виртуальные машины QEMU
Настраивает Talos Linux
Устанавливает Cozystack
Ожидает установки всех HelmRelease
Выполняет дополнительные проверки работоспособности компонентов

Скрипт e2e.sh можно запускать как локально, так и непосредственно в контейнере Kubernetes. Для запуска тестов в кластере Kubernetes перейдите в директорию packages/core/testing и выполните следующие команды:

make apply  # Создать тестовую песочницу в кластере Kubernetes
make test   # Запустить end-to-end тесты в существующей песочнице
make delete # Удалить тестовую песочницу из кластера Kubernetes

⚠️ Для запуска e2e-тестов в кластере Kubernetes узлы должны иметь достаточно свободных ресурсов для запуска вложенных виртуальных машин (QEMU) с поддержкой KVM. Рекомендуется использовать bare-metal узлы родительского кластера Cozystack.

Динамическая среда разработки

Если вы предпочитаете разрабатывать Cozystack в виртуальных машинах вместо изменения существующего кластера, пакет packages/core/testing включает дополнительные опции:

make exec  # Открывает интерактивную оболочку в контейнере песочницы.
make login # Загружает kubeconfig во временную директорию и запускает оболочку с окружением песочницы; требует fzf.
make proxy # Включает SOCKS5 прокси-сервер; требуются mirrord и gost.

Прокси Socks5 можно настроить в браузере для доступа к сервисам кластера, работающего в песочнице. Для удобства переключения можно использовать расширение Proxy Toggle.