Установка на Kubernetes (Helm)

Разверните control plane Planeon на Kubernetes с помощью официального Helm-чарта: один values.yaml, пара команд и те же переменные planeon.env, что и в других путях установки — с той разницей, что миграции базы данных встроены в собственный жизненный цикл установки/обновления Helm, а не выполняются вручную.

Запланировано на релиз после 1.0

Helm-чарт — и репозиторий charts.planeon.io, в котором он должен публиковаться, — не входят в релиз v1.0.0; они запланированы на релиз после v1.0.0. Поддерживаемый путь установки для v1.0.0 — Docker Compose. Всё ниже (содержимое чарта, структура values.yaml, хост репозитория) описывает задуманный дизайн, чтобы вы могли планировать заранее; относитесь к этому как к предварительному, пока этот более поздний релиз не выйдет.

Предварительные требования

Kubernetes 1.28 или новее и CLI Helm 3.
Уже установленный ingress-контроллер (например, ingress-nginx), настроенный для адресов веб-консоли, API и gateway. Gateway держит постоянное WebSocket-соединение на каждую сессию рабочего стола, поэтому увеличьте таймауты чтения/отправки прокси вашего контроллера на хосте gateway далеко за значения по умолчанию — для ingress-nginx это nginx.ingress.kubernetes.io/proxy-read-timeout и -proxy-send-timeout (см. пример values.yaml ниже). Точные протоколы и порты для каждого пути — в разделе Требования → Сетевые пути.
Внешние PostgreSQL 16+ и Redis 7+, доступные из кластера — управляемые сервисы или инстансы, которыми вы управляете сами. Чарт также поставляет опциональные саб-чарты postgresql/redis для ознакомительного использования; см. Что разворачивает чарт ниже — там же оговорка про продакшен.
DNS-имя (или имена), указывающее на ваш ingress-контроллер, настроенный на нём TLS, и уже настроенный OIDC-провайдер идентификации с созданным для Planeon приложением — те же предварительные требования, что и у установки через Docker Compose, и по тем же причинам.
Доступ к организации planeon на Docker Hub (или к её зеркалу в приватном registry) для образов, на которые ссылается чарт.

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

Что разворачивает чарт

Компонент	Тип ресурса	Примечания
api	Deployment	REST API; также отдаёт `/healthz` и `/readyz`
worker	Deployment	Реконсиляция пулов и обработка заданий
web	Deployment	Веб-консоль на Node.js
gateway	Deployment	WebSocket-туннель браузерных рабочих столов; должен видеть guacd
guacd	Deployment	`planeon/guacd:v1.0.0` — собственная сборка Planeon с включённым H.264; в стандартном образе сообщества и в большинстве пакетов дистрибутивов его нет, из-за чего современные сессии Windows отображаются чёрным экраном
migrations	Job (хук Helm)	Выполняется до раскатки api/worker/gateway/web, как при установке, так и при обновлении — см. Установка ниже
postgresql	StatefulSet (опциональный саб-чарт)	По умолчанию отключён; включайте только для ознакомления — для продакшена используйте собственный PostgreSQL 16+
redis	StatefulSet (опциональный саб-чарт)	По умолчанию отключён; та же оговорка, что и у postgresql

Добавьте Helm-репозиторий

helm repo add planeon https://charts.planeon.io
helm repo update

values.yaml

Сам чарт выходит вместе с релизом v1.0.0; структура ниже — справочник для предварительного планирования, чтобы вы могли подготовить values.yaml заранее — считайте имена полей иллюстративными, пока не появится собственная документация чарта и helm show values planeon/planeon. В нём те же переменные, что и в planeon.env на странице установки через Docker Compose; здесь этот справочник не повторяется, различается только механизм доставки (значения Helm вместо env_file).

global:
  # Переменные без секретов, применяются к api, worker, web и gateway.
  env:
    APP_ENV: production
    LOG_LEVEL: info
    API_CORS_ALLOWED_ORIGINS: https://vdi.example.com
    AUTH_OIDC_ISSUER_URL: https://idp.example.com/application/o/planeon/
    AUTH_OIDC_AUDIENCE: planeon
    AUTH_OIDC_GROUPS_CLAIM: groups
    AUTH_OIDC_ROLES_CLAIM: roles
    AUTH_BOOTSTRAP_ADMIN_EMAILS: admin@example.com
    NEXT_PUBLIC_API_BASE_URL: https://api.vdi.example.com
    NEXT_PUBLIC_OIDC_AUTHORITY: https://idp.example.com/application/o/planeon/
    NEXT_PUBLIC_OIDC_CLIENT_ID: planeon
    NEXT_PUBLIC_OIDC_SCOPE: "openid profile email groups offline_access"
    GATEWAY_PUBLIC_WS_URL: wss://gateway.vdi.example.com/tunnel

  # Секретные значения (DATABASE_URL, REDIS_ADDR, SECRETS_MASTER_KEY) --
  # создайте этот Secret сами (см. ниже) и сошлитесь на него здесь,
  # вместо того чтобы класть секреты в values.yaml / систему контроля
  # версий.
  existingSecret: planeon-secrets

api:
  image:
    repository: planeon/api
    tag: "v1.0.0"
  replicas: 1

worker:
  image:
    repository: planeon/worker
    tag: "v1.0.0"
  replicas: 1

web:
  image:
    repository: planeon/web
    tag: "v1.0.0"
  replicas: 1

gateway:
  image:
    repository: planeon/gateway
    tag: "v1.0.0"
  replicas: 1

guacd:
  image:
    repository: planeon/guacd
    tag: "v1.0.0"

ingress:
  enabled: true
  className: nginx
  web:
    host: vdi.example.com
  api:
    host: api.vdi.example.com
  gateway:
    host: gateway.vdi.example.com
    # Постоянный WebSocket-туннель для браузерных сессий рабочего стола --
    # увеличьте таймауты прокси вашего ingress-контроллера на этом хосте
    # за значения по умолчанию.
    annotations:
      nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
      nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"

postgresql:
  enabled: false # true только для ознакомления -- для продакшена используйте собственный PostgreSQL 16+

redis:
  enabled: false # true только для ознакомления -- для продакшена используйте собственный Redis 7+

Создайте этот Secret перед установкой:

kubectl create secret generic planeon-secrets \
  --from-literal=DATABASE_URL='postgres://planeon:change-me@postgres.example.internal:5432/planeon?sslmode=disable' \
  --from-literal=REDIS_ADDR='redis.example.internal:6379' \
  --from-literal=SECRETS_MASTER_KEY="$(openssl rand -base64 32)"

Если ваш Redis требует аутентификации, добавьте также --from-literal=REDIS_PASSWORD='...' — как и planeon.env на странице Docker Compose, пример выше предполагает её отсутствие.

vdi.example.com, api.vdi.example.com и gateway.vdi.example.com выше — три отдельных ingress-адреса на одном домене — альтернатива примеру с единым адресом и маршрутизацией по пути на странице Docker Compose. Используйте ту структуру, которая подходит вашему DNS; только держите API_CORS_ALLOWED_ORIGINS, NEXT_PUBLIC_API_BASE_URL и GATEWAY_PUBLIC_WS_URL синхронизированными с выбранными адресами.

Справочник по конфигурации описывает каждую переменную из примера выше — значение по умолчанию, обязательность, является ли она секретом и что она делает.

Установка

helm install planeon planeon/planeon -f values.yaml

В отличие от установки через Docker Compose и на ВМ, где шаг миграций вы выполняете сами, этот чарт встраивает миграции в хук Helm pre-install/pre-upgrade: helm install запускает его автоматически, до того как раскатятся поды api/worker/gateway/web. Если Job хука завершается неудачно, установка останавливается на этом шаге, и релиз не переходит к созданию подов приложения — та же гарантия порядка, которую другие пути установки документируют вручную, просто автоматизированная через уже существующие в Helm хуки жизненного цикла. См. Наблюдаемость → Семантика readiness о том, как api и worker отказываются обслуживать трафик на схеме, которая им не соответствует, — именно от этого и защищает такой порядок в любом случае.

Следите за Job миграций напрямую, если хотите:

kubectl get jobs -l app.kubernetes.io/instance=planeon
kubectl logs job/planeon-migrate

Точное имя job и метки задаёт чарт — сверьтесь с тем, как их назовёт helm install, когда чарт выйдет.

Обновление

helm upgrade planeon planeon/planeon -f values.yaml

Тот же хук: миграции выполняются первыми, и только после их успеха Helm раскатывает новые образы api/worker/gateway/web.

Проверка

kubectl get pods -l app.kubernetes.io/instance=planeon
kubectl port-forward svc/planeon-api 9090:9090
curl -fsS http://127.0.0.1:9090/readyz

Как и с Job миграций выше, точное имя Service и порт задаёт чарт — сверьтесь с тем, что реально создаст релиз, когда чарт выйдет.

Как только все поды в состоянии Running, а /readyz возвращает 200, откройте веб-консоль по настроенному вами ingress-адресу и войдите — тот же сценарий bootstrap первого входа, что и в установке через Docker Compose. Если под не переходит в состояние Running или /readyz продолжает отказывать, см. Устранение неполадок.

Предварительные требования​

Что разворачивает чарт​

Добавьте Helm-репозиторий​

values.yaml​

Установка​

Обновление​

Проверка​