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

Docs: Введение в Cozystack

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

Что такое Cozystack

Cozystack — это фреймворк на базе Kubernetes для построения среды частного облака. Он может использоваться отдельной компанией для запуска собственного частного облака или поставщиком услуг для предоставления платформы как услуги нескольким клиентам.

Cozystack закрывает наиболее важные потребности команды разработчиков:

Кластеры Kubernetes для запуска приложений в среде разработки и в продакшене
Стандартные управляемые приложения: базы данных, менеджеры очередей, кэши и многое другое
Виртуальные машины
Надёжное распределённое хранилище

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

Ещё одна мощная функция — система тенантов. Она позволяет изолировать отдельных разработчиков, команды или даже целые компании в их собственных полнофункциональных пространствах — на одном и том же оборудовании.

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

Многопользовательский режим, мультитенантность и встроенный SSO

Cozystack разработан для использования несколькими командами, отделами или даже компаниями. Традиционный подход с выделением каждой команде отдельного пространства имён может быть слишком ограниченным. Командам может потребоваться несколько окружений с одинаковыми именами пространств имён, или им может не хватать прав root для управления собственными моделями доступа.

Система тенантов Cozystack решает эти проблемы, позволяя пользователям разворачивать среду Kubernetes-в-Kubernetes с помощью одного приложения. Пользователи вложенных кластеров Kubernetes имеют полный доступ и контроль. Система квот обеспечивает оптимальное использование оборудования, изолируя ресурсы во избежание проблемы «шумного соседа». Пользователи платформы также могут формировать подробные отчёты об использовании ресурсов для каждого тенанта.

Система единого входа в Cozystack работает на базе Keycloak. Kubernetes API — как в корневом тенанте, так и во вложенных — поддерживает SSO из коробки.

Реплицированная система хранения

Не все компании могут позволить себе выделенное аппаратное обеспечение SAN или NAS. Cozystack включает надёжную распределённую систему хранения, позволяющую создавать отказоустойчивые реплицированные тома. Возможна даже репликация томов между несколькими центрами обработки данных.

Система виртуализации

Обычно приходится выбирать между виртуализацией и контейнеризацией. Cozystack объединяет оба подхода в единой платформе. Нет необходимости поддерживать отдельную инфраструктуру виртуализации. В Cozystack виртуальные машины запускаются непосредственно в Kubernetes и потребляют CPU, память, GPU и хранилище из общего пула ресурсов Kubernetes.

Управляемые базы данных без накладных расходов

Несмотря на высокую эффективность виртуализации Linux-на-Linux, она всё же вносит определённые накладные расходы. Cozystack избегает этого, запуская управляемые базы данных непосредственно в контейнерах на хостовом оборудовании. Можно развернуть несколько высокодоступных баз данных с выделенными IP-адресами на ограниченном оборудовании — при этом каждая имеет прямой доступ к CPU и хранилищу.

Экосистема Kubernetes

Нам неизвестен ни один другой дистрибутив Kubernetes с таким количеством встроенных инфраструктурных компонентов. (Серьёзно — пришлите нам ссылку, если найдёте!) Вместо того чтобы устанавливать компоненты и контроллеры вручную, вы просто выбираете вариант Cozystack, подходящий для ваших нужд. Все компоненты предварительно настроены, проверены на совместимость и обновляются вместе с фреймворком Cozystack.

Docs: Руководство по администрированию

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

Уведомление

Компоненты управления Katamarina основываются на технологиях Cozystack и в настоящий момент наша команда активно занимается русификацией базы знаний.

На данный момент для повседневного использования - полностью актуальная документация размещена на ресурсах основного проекта https://cozystack.ru/

Сотрудники компании Katamarina являются постоянными контрибуторами Upstream-проекта Cozystack и участвуют в развитии ключевого функционала проекта.

Также Katamarina находится в списке компаний, сертифицированных для оказания Enterprise-поддержки в рамках проекта https://cozystack.ru/support/

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

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

Как это работает

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

Оператор обрабатывает все детали развёртывания и операции второго дня (масштабирование, резервное копирование, переключение при сбое). App-чарт просто создаёт соответствующий CRD со значениями, полученными из пользовательского ввода.

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

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

packages/system/nats/ # Upstream Helm-чарт NATS
packages/apps/nats/ # App-чарт создаёт helm.toolkit.fluxcd.io/v2.HelmRelease

В этом случае FluxCD выступает оператором, управляя жизненным циклом Helm-релиза. App-чарт контролирует, какие upstream-значения открываются пользователю, обеспечивая дополнительный уровень безопасности — пользователи не могут обойти валидацию для развёртывания чарта с произвольными значениями.

Другие примеры этого паттерна: extra/ingress, extra/seaweedfs, extra/monitoring.

extra

Аналогично apps, но не отображается в каталоге приложений. Могут устанавливаться только в составе тенанта. Разрешены для использования нижележащими тенантами, установленными в пространстве имён текущего тенанта.

Подробнее о Системе тенантов читайте на странице основных концепций.

В одном пространстве имён тенанта можно использовать только один тип приложения.

Extra-пакеты следуют тем же двум архитектурным паттернам, что и apps (на основе оператора или HelmRelease).

Пакеты apps и extra используют Helm для установки приложения и управляются FluxCD через дашборд.

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

Каждый пакет — это типичный Helm-чарт, содержащий все необходимые образы и манифесты для платформы. Мы следуем логике umbrella-чарта, размещая 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-чарт должен быть легко обновляемым, переопределяемым и изменяемым. Мы используем паттерн umbrella-чарта — upstream-чарты находятся в директории ./charts и хранятся в оригинальном виде. Кастомизации вносятся через переопределения values.yaml и дополнительные templates/, а структурные изменения в upstream-чарте применяются через patches/. Такое разделение гарантирует простое обновление до новой upstream-версии: выполните make update, просмотрите diff и при необходимости повторно примените патчи.

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

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

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

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

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

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

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

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

Разработка

Настройка 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 \
 --use

Либо опустите параметры –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" # Зафиксировать изменения в ветке

Для сборки контейнера 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 узлы должны иметь достаточно свободных ресурсов для создания 3 ВМ и хранения данных развёртываемых приложений.

Рекомендуется использовать bare-metal узлы родительского кластера Cozystack.

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

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

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

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

Proxy Toggle

Docs: Cozystack Роадмап

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

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

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

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