Kubernetes (Helm)

Требования

• Kubernetes-кластер и Helm 3
• Ingress-контроллер ingress-nginx; аннотации в примере values.yaml относятся к нему
• PostgreSQL 15 (поддерживается 14), Valkey 9 (standalone-режим), S3-совместимое хранилище, развёрнутые отдельно и доступные из кластера
• Два DNS-имени и TLS-сертификаты: приложение (example.flip-chart.ru) и MCP-сервер (mcp.example.flip-chart.ru)
• Учётные данные SMTP-сервера

Изменение конфигурации

После обновления секрета с конфигурацией требуется перезапуск соответствующего Deployment: kubectl -n flip rollout restart deployment/backend.

Состав чарта

Сабчарт	Образ	Порт	Ingress
backend	flip-backend	9000	/app/api, /app/api/v1/ws, /app/api/v1/flip/backup/upload, редирект /
file-handlers	flip-file-handlers	8080	—
frontend	flip-frontend	80	/app, /app/s3/ → S3-хранилище
mcp-server	flip-mcp-server	8090	mcp.example.flip-chart.ru/

Файлы поставки

├── credentials
│   ├── authorized_key.json      — ключ доступа к реестру Docker-образов
│   └── License_key.txt          — лицензионный ключ приложения
└── deploy
    ├── docker-compose
    │   └── config               — примеры конфигурационных файлов сервисов
    └── kubernetes
        ├── flip-chart-1.0.0.tgz — Helm-чарт
        └── values.yaml          — пример values

Пример values.yaml.

Шаги установки

1. Namespace и доступ к реестру

kubectl create namespace flip
kubectl -n flip create secret docker-registry registrykey \
  --docker-server=cr.yandex \
  --docker-username=json_key \
  --docker-password="$(cat credentials/authorized_key.json)"

2. TLS-сертификаты

kubectl -n flip create secret tls flip-tls     --cert=crt.pem     --key=key.pem
kubectl -n flip create secret tls flip-mcp-tls --cert=mcp-crt.pem --key=mcp-key.pem

При использовании cert-manager его аннотации указываются в ingress соответствующих сабчартов; имена секретов сохраняются.

3. Конфигурационные файлы

Заполните конфигурации по описаниям: backend, file-handlers, frontend, mcp-server.

Адреса внутри кластера

Примеры конфигураций рассчитаны на docker-compose. В Kubernetes сервисы адресуются по именам Service чарта:

Поле	docker-compose	Kubernetes
backend → FileHandlerServiceConfig.Address	http://flip-file-handlers:8080/api	http://file-handlers.flip.svc.cluster.local:8080/api
mcp-server → flipApi.internalUrl	http://flip-backend:9000	http://backend.flip.svc.cluster.local:9000

flip в адресе — namespace установки (global.namespace). Адреса PostgreSQL, Valkey и S3 — внешних сервисов.

Создайте секреты с конфигурациями (имена секретов и ключей должны совпадать с volumes/volumeMounts в values):

kubectl -n flip create secret generic backend-config       --from-file=config.yaml=config/backend/config.yaml
kubectl -n flip create secret generic file-handlers-config --from-file=config.yaml=config/file-handlers/config.yaml
kubectl -n flip create secret generic frontend-config       --from-file=config.js=config/frontend/config.js
kubectl -n flip create secret generic mcp-server-config    --from-file=config.yaml=config/mcp-server/config.yaml

Обновление конфигурации

kubectl -n flip create secret generic backend-config --from-file=config.yaml=config/backend/config.yaml \
  --dry-run=client -o yaml | kubectl apply -f -

4. S3-хранилище

• Создайте бакет и разрешите анонимное чтение объектов.
• Загрузите медиа-ресурсы: распакуйте sources/gifs.tar и скопируйте каталог gifs в корень бакета.
• В values.yaml укажите хост хранилища в frontend.service.s3.storageurl. Чарт создаёт Service типа ExternalName и Ingress /app/s3/(.*), проксирующий запросы к хранилищу через домен приложения.

5. values.yaml

Отредактируйте values.yaml: домены (tlshosts, permanent-redirect), имена TLS-секретов, хост S3, версию образов (image.tag, единая для всех компонентов), ресурсы. Описание параметров — в разделе Параметры values.yaml.

6. Установка

helm install flip ./flip-chart-1.0.0.tgz -f values.yaml -n flip

7. Проверка

kubectl -n flip get pods
kubectl -n flip get ingress

Все поды должны быть в состоянии Running. Приложение доступно по адресу https://example.flip-chart.ru/app. Дальнейшие действия — первый запуск.

Параметры values.yaml

global

Параметр	Описание
global.namespace	Namespace установки.
global.imagePullSecrets	Список секретов доступа к реестру образов.

Общие параметры сабчартов

Одинаковы для backend, file-handlers, frontend, mcp-server.

Параметр	Описание
enabled	Включение компонента.
replicaCount	Количество реплик.
image.repository, image.tag, image.pullPolicy	Образ компонента.
annotations	Аннотации Deployment и подов.
affinity, tolerations, nodeSelector	Размещение подов.
containers.containerPort	Порты контейнера.
containers.readinessProbe	Readiness-проба.
env, envFrom	Переменные окружения.
service.enabled, service.type, service.ports	Kubernetes Service.
resources	Запросы и лимиты CPU/памяти.
volumes, volumeMounts	Монтирование секрета с конфигурацией. Путь внутри контейнера фиксирован (см. конфигурационные файлы).
securityContext	Контекст безопасности контейнера (backend).
serviceMonitor.enabled	ServiceMonitor для Prometheus Operator (backend, file-handlers).

Ingress

Параметр	Описание
backend.ingress.ingressClassName	Класс Ingress-контроллера.
backend.ingress.tlshosts, backend.ingress.tlssecret	Домен приложения и TLS-секрет.
backend.ingress.external	REST API /app/api.
backend.ingress.websocket	WebSocket /app/api/v1/ws, тайм-ауты 86400s.
backend.ingress.upload	Импорт досок /app/api/v1/flip/backup/upload, лимит тела 6G, тайм-ауты 3600s.
backend.ingress.redirect	Редирект / → /app; домен задаётся в аннотации permanent-redirect.
backend.ingress.internal	Служебные эндпоинты /app/api/v1/internal; отключён.
frontend.ingress.ui	Интерфейс /app.
frontend.ingress.s3	Проксирование S3 /app/s3/(.*) на Service frontend-s3; для хранилища по HTTPS требуются аннотации backend-protocol: "HTTPS" и upstream-vhost.
frontend.service.s3.storageurl	Хост S3-хранилища для Service ExternalName.
mcp-server.ingress	MCP-сервер на отдельном домене tlshosts/tlssecret.

Обновление

helm upgrade flip ./flip-chart-1.0.0.tgz -f values.yaml -n flip
kubectl -n flip get pods

Порядок обновления версий — в разделе Обновления.

Удаление

helm uninstall flip -n flip
kubectl delete namespace flip