Конфигурация кластера Cozystack on Cozystack

Справочник Platform Package

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

На этой странице описана роль Cozystack Platform Package и приведен полный справочник по его values.

Основная конфигурация Cozystack задается custom resource Package. Этот Package включает вариант Cozystack, настройки компонентов, ключевые сетевые параметры, опубликованные сервисы и другие опции.

Пример

Ниже пример конфигурации для установки Cozystack с вариантом isp-full, root host example.org, а также опубликованными и доступными пользователям Cozystack Dashboard и API:

apiVersion: cozystack.io/v1alpha1
kind: Package
metadata:
 name: cozystack.cozystack-platform
spec:
 variant: isp-full
 components:
 platform:
 values:
 publishing:
 host: "example.org"
 apiServerEndpoint: "https://api.example.org:443"
 exposedServices:
 - dashboard
 - api
 networking:
 podCIDR: "10.244.0.0/16"
 podGateway: "10.244.0.1"
 serviceCIDR: "10.96.0.0/16"
 joinCIDR: "100.64.0.0/16"

Справочник

Поля уровня Package

Поле	Описание
`spec.variant`	Вариант, используемый для установки, например `isp-full`, `isp-full-generic`, `isp-hosted`, `distro-full`.

Platform values (`spec.components.platform.values.*`)

Публикация

Значение	По умолчанию	Описание
`publishing.host`	`"example.org"`	Основной домен для всех сервисов, создаваемых в Cozystack: dashboard, Grafana, Keycloak и других.
`publishing.apiServerEndpoint`	`""`	Используется для генерации kubeconfig-файлов для пользователей. Рекомендуется использовать маршрутизируемый FQDN или IP-адрес вместо адресов, доступных только локально. Пример: `"https://api.example.org"`.
`publishing.exposedServices`	`[api, dashboard, vm-exportproxy, cdi-uploadproxy]`	Список сервисов для публикации. Возможные значения: `api`, `dashboard`, `cdi-uploadproxy`, `vm-exportproxy`.
`publishing.ingressName`	`"tenant-root"`	Ingress controller, используемый для публикации сервисов.
`publishing.externalIPs`	`[]`	Список external IP, используемых указанным ingress controller. Если не задан, по умолчанию используется сервис LoadBalancer.
`publishing.certificates.solver`	`"http01"`	Тип ACME challenge solver для letsencrypt issuer по умолчанию. Возможные значения: `http01`, `dns01`.
`publishing.certificates.issuerName`	`"letsencrypt-prod"`	Имя `ClusterIssuer` для TLS-сертификатов, используемых в системных Helm releases.
`publishing.certificates.wildcardSecretName`	`""`	Operator-provided wildcard TLS Secret. When set, platform services and the root tenant’s ingress/Gateway serve this pre-existing Secret instead of minting per-host ACME certificates (only the NAME travels the values channel — never the key material), and takes precedence over `publishing.certificates.wildcard`. The Secret must exist in the publishing namespace (`tenant-root` by default), hold valid PEM under `tls.crt` / `tls.key` (created as `kubernetes.io/tls`, though only the material is validated), and cover the served hosts. Scoped to the root tenant but not enforced — the name reaches every tenant, so a child running its own ingress controller can be left serving a self-signed certificate ( cozystack/cozystack#3296). See Gateway API → Certificates for the full behaviour and the three child-tenant cases. Leave empty to keep ACME issuance.
`publishing.certificates.dns01.provider`	`"cloudflare"`	DNS-01 provider, когда `solver=dns01`. Возможные значения: `cloudflare`, `route53`, `digitalocean`, `rfc2136`. Это значение читают и per-tenant Issuer (формируемый `cozystack-controller` из CR `TenantGateway`), и общекластерные `ClusterIssuer` `letsencrypt-prod` / `letsencrypt-stage`, используемые прежним ingress-механизмом.
`publishing.certificates.dns01.cloudflare.secretName`	`"cloudflare-api-token-secret"`	Имя Secret с Cloudflare API token, имеющим права `Zone:Read` + `Zone:DNS:Edit` на apex-зону.
`publishing.certificates.dns01.cloudflare.secretKey`	`"api-token"`	Ключ внутри Secret, содержащий API token.
`publishing.certificates.dns01.route53.region`	`""`	AWS-регион hosted zone Route53. Требуется, когда `provider=route53`.
`publishing.certificates.dns01.route53.accessKeyID`	`""`	IAM access key ID. Необязателен при работе с IRSA / instance profile.
`publishing.certificates.dns01.route53.secretName`	`""`	Имя Secret с IAM secret access key. Необязателен при работе с IRSA / instance profile.
`publishing.certificates.dns01.route53.secretKey`	`"secret-access-key"`	Ключ внутри Secret Route53, содержащий secret access key.
`publishing.certificates.dns01.digitalocean.secretName`	`"digitalocean-api-token-secret"`	Имя Secret с DigitalOcean API token, имеющим доступ на запись к apex-домену.
`publishing.certificates.dns01.digitalocean.secretKey`	`"access-token"`	Ключ внутри Secret, содержащий DigitalOcean token.
`publishing.certificates.dns01.rfc2136.nameserver`	`""`	`host:port` авторитетного nameserver, принимающего динамические обновления RFC 2136. Требуется, когда `provider=rfc2136`.
`publishing.certificates.dns01.rfc2136.tsigKeyName`	`""`	Имя TSIG-ключа, авторизующего динамические обновления. Требуется, когда `provider=rfc2136`.
`publishing.certificates.dns01.rfc2136.tsigAlgorithm`	`"HMACSHA256"`	HMAC-алгоритм TSIG.
`publishing.certificates.dns01.rfc2136.secretName`	`""`	Имя Secret с материалом TSIG-ключа. Требуется, когда `provider=rfc2136`.
`publishing.certificates.dns01.rfc2136.secretKey`	`"tsig-secret-key"`	Ключ внутри Secret, содержащий TSIG-ключ.
`publishing.certificates.wildcardSecretName`	`""`	Готовый wildcard TLS Secret, предоставленный оператором. Если задан, платформенные сервисы и ingress/Gateway корневого tenant используют этот уже существующий Secret вместо выпуска отдельных ACME-сертификатов для каждого хоста; через канал values передаётся только ИМЯ, но никогда сам сертификат или приватный ключ. Secret должен уже существовать в namespace публикации (`tenant-root` по умолчанию — namespace, в котором работает корневой ingress controller, выбранный через `publishing.ingressName`), иметь тип `kubernetes.io/tls` и покрывать обслуживаемые хосты (обычно `*.<root-host>` + `<root-host>`). Оставьте пустым, чтобы сохранить выпуск через ACME (см. `solver` / `issuerName` выше).
`publishing.proxyProtocol`	`false`	Включает PROXY-protocol на host ingress-nginx и автоматически разворачивает ouroboros, чтобы исправить возникающую проблему hairpin-NAT. Upstream L4 LB перед ingress-nginx уже должен добавлять PROXY-v1 headers до включения этого флага; инструкции по проверке и путь отключения см. на связанной странице.
`publishing.proxyProtocolAcknowledgeUnclean`	`false`	Флаг подтверждения для асимметрии `helm.sh/resource-policy: keep` на пути отключения host. Переключение `publishing.proxyProtocol` с `true` обратно на `false` прекращает генерацию Package CR `cozystack.ouroboros`, но не удаляет уже существующий ресурс — render платформы будет падать, пока Package CR не будет удалён (это запустит pre-delete cleanup hook чарта) или пока этот флаг не будет установлен в `true`, подтверждая, что оператор обработал асимметрию. Полную последовательность см. в hairpin-proxy-protocol → Disable path.

publishing.exposure is not listed above on purpose: the key existed in v1.4 only and was removed before v1.5 shipped. It has no effect on a v1.5 cluster — the host ingress is exposed through publishing.externalIPs, and a LoadBalancer Service is used when that list is empty. Drop the key when upgrading from v1.4 — and check what the host ingress Service becomes. A v1.4 cluster running publishing.exposure: loadBalancer had a LoadBalancer Service with externalTrafficPolicy: Local; from v1.5 the key is ignored, so a cluster with publishing.externalIPs set silently falls back to a ClusterIP Service with externalTrafficPolicy: Cluster and stops preserving client source IPs.

Варианты Cozystack: обзор и сравнение

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

Введение

Variants - это предопределенные конфигурации Cozystack, определяющие, какие bundles и компоненты включены. Каждый вариант тестируется, версионируется и гарантированно работает как единое целое. Они упрощают установку, снижают риск неправильной конфигурации и помогают выбрать подходящий набор возможностей для вашего развертывания.

Это руководство предназначено для infrastructure engineers, DevOps-команд и platform architects, которые планируют разворачивать Cozystack в разных окружениях. В нем объясняется, как варианты Cozystack помогают адаптировать установку под конкретные потребности: от полнофункциональной platform-as-a-service до полного ручного контроля над установленными packages.

Справочник компонентов Cozystack

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

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

Иногда нужно переопределить отдельные параметры компонентов. Для этого измените соответствующий ресурс Package и укажите значения в секции spec.components. Структура values соответствует файлу values.yaml соответствующего системного chart в репозитории Cozystack.

Например, если нужно включить режим FRR-K8s для MetalLB, посмотрите его values.yaml, чтобы понять доступные параметры, а затем измените Package cozystack.metallb:

apiVersion: cozystack.io/v1alpha1
kind: Package
metadata:
 name: cozystack.metallb
 namespace: cozy-system
spec:
 variant: default
 components:
 metallb:
 values:
 metallb:
 frrk8s:
 enabled: true

Включение и отключение компонентов

В bundles есть опциональные компоненты, которые нужно явно включать в установку. Обычные компоненты bundle, наоборот, можно отключить и исключить из установки, если они не нужны.

Лицензии

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

На этой странице перечислены open-source компоненты, поставляемые с Cozystack, сгруппированные по роли в платформе. Charts, CRDs, controllers и application APIs, поддерживаемые Cozystack, лицензированы под Apache-2.0 и не перечисляются ниже по отдельности. Для каждого upstream-компонента карточка содержит ссылку на upstream-файл лицензии.

Этот справочник вручную сверяется с текущим набором компонентов next. Container images могут включать дополнительные пакеты операционной системы и библиотечные зависимости со своими лицензиями. Зафиксированные upstream-версии managed runtimes (PostgreSQL, MariaDB, Kafka и другие) могут меняться между minor-релизами Cozystack: проверяйте версию Cozystack, которую вы используете.

Операционная система и Kubernetes runtime

Talos Linux

Immutable Linux-дистрибутив, созданный для узлов Kubernetes.

Lineage Controller Webhook

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

lineage controller webhook - это mutating admission webhook, поставляемый в составе Package cozystack.cozystack-engine. При каждом CREATE и UPDATE tenant-ресурсов Pod, Secret, Service, PersistentVolumeClaim, Ingress или WorkloadMonitor он поднимается по графу владения и записывает идентичность владеющего Cozystack Application в labels ресурса (apps.cozystack.io/application.{group,kind,name}). Dashboard Cozystack, aggregated API server и механизм SchedulingClass опираются на эти labels.

Webhook зарегистрирован с failurePolicy: Fail, поэтому kube-apiserver должен иметь доступ к рабочему pod webhook, чтобы tenant CREATE/UPDATE-запросы проходили успешно.

White Labeling

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

White labeling позволяет заменить стандартный брендинг Cozystack собственными логотипами и текстами в Dashboard UI и на страницах аутентификации Keycloak.

Обзор

Брендинг настраивается через поле branding в Platform Package (spec.components.platform.values.branding). Конфигурация автоматически распространяется на:

Dashboard: логотип, заголовок страницы, текст footer, favicon и идентификатор tenant
Keycloak: display name realm на страницах аутентификации

Конфигурация

Измените Platform Package, чтобы добавить или обновить секцию branding:

apiVersion: cozystack.io/v1alpha1
kind: Package
metadata:
 name: cozystack.cozystack-platform
spec:
 variant: isp-full # используйте свой вариант
 components:
 platform:
 values:
 branding:
 # Брендинг Dashboard
 titleText: "My Company Dashboard"
 footerText: "My Company Platform"
 tenantText: "Production v1.0"
 logoText: ""
 logoSvg: "<base64-encoded SVG>"
 iconSvg: "<base64-encoded SVG>"
 # Брендинг Keycloak
 brandName: "My Company"
 brandHtmlName: "<div style='font-weight:bold;'>My Company</div>"

Примените изменения:

Telemetry

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

В этом документе описана телеметрия в проекте Cozystack: зачем собираются данные, какие именно данные собираются, как они обрабатываются и как отказаться от участия.

Зачем мы собираем телеметрию

Cozystack как open source проект развивается благодаря обратной связи сообщества и пониманию реального использования. Данные телеметрии позволяют maintainers понимать, как Cozystack применяется в реальных сценариях. Эти данные помогают принимать решения о приоритете функций, стратегиях тестирования, исправлениях ошибок и общем развитии проекта. Без телеметрии решения приходилось бы принимать на основе предположений или ограниченной обратной связи, что могло бы замедлить улучшения или привести к функциям, которые не соответствуют потребностям пользователей. Телеметрия помогает направлять разработку реальными паттернами использования и требованиями сообщества, делая платформу более надежной и ориентированной на пользователей.

Конфигурация кластера Cozystack on Cozystack

Справочник Platform Package

Пример

Справочник

Поля уровня Package

Platform values (spec.components.platform.values.*)

Публикация

Варианты Cozystack: обзор и сравнение

Введение

Справочник компонентов Cozystack

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

Включение и отключение компонентов

Лицензии

Операционная система и Kubernetes runtime

Lineage Controller Webhook

White Labeling

Обзор

Конфигурация

Telemetry

Зачем мы собираем телеметрию

Platform values (`spec.components.platform.values.*`)