Katamarina - PaaS-платформа для построения облачных инфраструктур. – Online-документация Katamarina Cozystack

Docs: Начало работы с Cozystack

Mon, 01 Jan 0001 00:00:00 +0000

Начало работы с Cozystack: развёртывание частного облака с нуля

Это руководство поможет вам выполнить первое развёртывание кластера Cozystack. По ходу работы вы познакомитесь с ключевыми концепциями, научитесь пользоваться Cozystack через дашборд и CLI и получите рабочий proof-of-concept.

Руководство разделено на несколько шагов. Завершайте каждый шаг перед переходом к следующему:

Шаг	Описание
Требования: подготовьте инфраструктуру и инструменты	Подготовьте инфраструктуру и установите необходимые CLI-инструменты на свою машину перед началом этого руководства.
1. Установите Talos Linux	Установите дистрибутив Talos Linux, подготовленный для Cozystack, с помощью `boot-to-talos` — это, вероятно, самый простой способ установки.
2. Установите и инициализируйте кластер Kubernetes	Выполните bootstrap кластера Kubernetes с помощью Talm — инструмента управления конфигурацией Talos, созданного для Cozystack.
3. Установите и настройте Cozystack	Установите Cozystack, получите административный доступ, выполните базовую настройку и откройте дашборд Cozystack.
4. Создайте tenant для пользователей и команд	Создайте пользовательский tenant — основу RBAC в Cozystack — и получите доступ к нему через дашборд и Cozystack API.
5. Разверните управляемые приложения	Начните работать с Cozystack: разверните виртуальную машину, управляемое приложение и Kubernetes-кластер tenant’а.

Требования и набор инструментов

Подготовьте инфраструктуру и установите необходимые инструменты.

1. Установка Talos Linux

Установка Talos Linux на любую машину с помощью cozystack/boot-to-talos.

2. Установка и bootstrap кластера Kubernetes

Используйте Talm CLI, чтобы выполнить bootstrap кластера Kubernetes, готового к установке Cozystack.

3. Установка и настройка Cozystack

Установите Cozystack, получите административный доступ, выполните базовую настройку и включите UI-дашборд.

4. Создание пользовательского tenant’а и настройка доступа

Создайте пользовательский tenant — основу RBAC в Cozystack — и получите доступ к нему через дашборд и Cozystack API.

5. Развёртывание управляемых приложений, ВМ и Kubernetes-кластера tenant’а

Начните использовать Cozystack: разверните виртуальную машину, управляемое приложение и Kubernetes-кластер tenant’а.

Cozystack Documentation

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

Mon, 01 Jan 0001 00:00:00 +0000

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.

Docs: Руководство по развертыванию Cozystack

Mon, 01 Jan 0001 00:00:00 +0000

Руководство по развертыванию Cozystack: от инфраструктуры до готового кластера

Руководство по Cozystack

Если вы устанавливаете Cozystack впервые, рекомендуем пройти руководство по Cozystack. В нем показан самый короткий путь к созданию proof-of-concept кластера Cozystack.

Общий путь установки

Установка Cozystack на bare-metal серверы или виртуальные машины состоит из трех последовательных шагов. Для каждого шага есть несколько вариантов. Мы указываем рекомендуемый вариант, но также приводим альтернативы, чтобы процесс установки оставался гибким:

Установите Talos Linux на bare-metal серверы или виртуальные машины с Linux либо без операционной системы.
Установите и инициализируйте кластер Kubernetes поверх Talos Linux.
Установите и настройте Cozystack в кластере Kubernetes.

Изолированная среда

Cozystack можно установить в изолированной среде без прямого доступа к Интернету. Главное отличие такой установки — использование proxy registry для образов:

Установите Talos Linux на bare-metal серверы или виртуальные машины с Linux либо без операционной системы.
Настройте узлы Talos для изолированной среды и инициализируйте кластер Kubernetes.
Установите и настройте Cozystack в кластере Kubernetes.

Автоматизированная установка с Ansible

Для типовых развертываний Linux (Ubuntu, Debian, RHEL, Rocky, openSUSE) коллекция Ansible автоматизирует весь процесс: подготовку ОС, инициализацию кластера k3s и установку Cozystack.

Установка у конкретных провайдеров

Для облачных провайдеров есть отдельные руководства, которые охватывают все шаги: от подготовки инфраструктуры до установки и настройки Cozystack. Если это ваш случай, рекомендуем использовать руководства ниже:

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

После развертывания кластера перейдите в раздел Администрирование кластера, чтобы выполнить следующие действия:

Требования к оборудованию

Определите требования к оборудованию для вашего сценария использования Cozystack.

Установка Talos Linux на bare metal или виртуальные машины

Шаг 1: установка Talos Linux на виртуальные машины или bare metal для последующей инициализации кластера Cozystack.

Установка и настройка кластера Kubernetes

Шаг 2: установка и настройка кластера Kubernetes, готового к установке Cozystack.

Установка и настройка Cozystack

Шаг 3: установка Cozystack в Kubernetes-кластер — как готовой к использованию платформы или в режиме BYOP (Build Your Own Platform).

Развертывание кластера Cozystack в облаках и у хостинг-провайдеров

Руководства по развертыванию кластеров Cozystack у конкретных облачных и хостинг-провайдеров.

Автоматизированная установка с Ansible

Развертывание Cozystack на generic Kubernetes с помощью Ansible collection cozystack.installer

Руководства для особых случаев развертывания Cozystack

Docs: Cozystack Роадмап

Mon, 01 Jan 0001 00:00:00 +0000

Cozystack Роадмап

Вы можете ознакомиться с нашей дорожной картой по адресу: Ссылка.

Если у вас есть вопросы и комментарии по поводу плана развития или вам необходима определенная функциональность, пожалуйста, сообщите нам об этом по адресу info@katamarina.ru

Присоединяйтесь к нашим community-встречам.

Katamarina - PaaS-платформа для построения облачных инфраструктур. – Online-документация Katamarina Cozystack

Docs: Начало работы с Cozystack

Начало работы с Cozystack: развёртывание частного облака с нуля

Требования и набор инструментов

1. Установка Talos Linux

2. Установка и bootstrap кластера Kubernetes

3. Установка и настройка Cozystack

4. Создание пользовательского tenant’а и настройка доступа

5. Развёртывание управляемых приложений, ВМ и Kubernetes-кластера tenant’а

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

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

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

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

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

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

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

Пакеты

core

installer

platform

flux-aio

talos

system

apps

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

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

extra

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

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

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

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

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

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

Разработка

Настройка Buildx

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

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

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

Docs: Руководство по развертыванию Cozystack

Руководство по развертыванию Cozystack: от инфраструктуры до готового кластера

Руководство по Cozystack

Общий путь установки

Изолированная среда

Автоматизированная установка с Ansible

Установка у конкретных провайдеров

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

Требования к оборудованию

Рекомендации по планированию системных ресурсов

Установка Talos Linux на bare metal или виртуальные машины

Установка и настройка кластера Kubernetes

Установка и настройка Cozystack

Развертывание кластера Cozystack в облаках и у хостинг-провайдеров

Автоматизированная установка с Ansible

Руководства для особых случаев развертывания Cozystack

Docs: Cozystack Роадмап

Cozystack Роадмап