Быстрый старт: Kubernetes / Helm

Эта инструкция — для администратора, который ставит Portal в кластер Kubernetes через Helm и программу portal-cli из готового архива (bundle).

Читайте сверху вниз. На каждом шаге есть команда и способ проверить успех.

Если ещё не уверены, что нужен Kubernetes — сначала выберите канал. Для одного сервера чаще проще Docker.

---

0. Что вы получите в итоге

После всех шагов:

1. В namespace portal работают поды API, Worker, Frontend, БД, кэш, хранилище, Portal Office.
2. Через Ingress открывается сайт Portal (и Office).
3. Есть пользователь admin с паролем, который установщик печатает в конце (и сохраняет в секретах).
4. На корневом узле доступна страница welcome.

---

1. Что понадобится заранее

Что	Минимум	Зачем
Кластер Kubernetes	версия 1.28+	куда ставим
Helm	3.12+	установка chart
kubectl	с доступом к кластеру	команды kubectl …
Ingress Controller	рекомендуется nginx-ingress	вход снаружи на HTTP/HTTPS
StorageClass	для PVC	диски PostgreSQL, Valkey (Redis), SeaweedFS
Память кластера	8 GB RAM минимум для пилота	иначе поды не встанут
Образы Portal	в registry кластера или загружены на ноды	см. §3 и air-gapped
Архив	portal-1.0.0-k8s-bundle.tar.gz (версия может отличаться)	от поставщика

Шаг 1.1. Проверьте инструменты

kubectl version --client
helm version
kubectl get nodes

Как проверить успех:

• kubectl и helm печатают версии;
• kubectl get nodes показывает хотя бы одну ноду в статусе Ready.

Если nodes пустой или Forbidden — нет доступа к кластеру: исправьте kubeconfig и повторите.

---

2. Ingress Controller (если ещё нет)

Portal нужен Ingress, чтобы браузер попадал на Frontend и Office.

Проверка:

kubectl get pods -A | grep -i ingress

Если Ingress уже есть — пропустите этот шаг.

Если нет — пример установки nginx-ingress:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install ingress-nginx ingress-nginx/ingress-nginx -n ingress --create-namespace

Как проверить:

kubectl get pods -n ingress
kubectl get svc -n ingress

Поды контроллера должны быть Running. Запомните внешний IP / LoadBalancer — на него потом укажет DNS.

---

3. Распакуйте bundle и загрузите образы

Bundle — архив с chart, образами, portal-cli и документацией.

cd /opt
tar xzf portal-1.0.0-k8s-bundle.tar.gz
cd portal-1.0.0-k8s-bundle
pwd
ls -la
chmod +x portal-cli/portal-cli

Что должны увидеть: каталоги portal-cli/, images/, helm/ (или путь к chart в поставке).

Загрузка образов на машину, где есть Docker (часто bastion / jump-хост):

docker load -i images/portal-images.tar
docker images | grep portal

Если в кластере private registry — после docker load сделайте retag и docker push для образов portal/* в ваш registry (как принято у вас). Без доступных образов поды останутся в ImagePullBackOff.

Как проверить: docker images | grep portal не пустой; в кластере после установки поды не в ErrImagePull.

---

4. Установка через portal-cli

Все команды — из корня распакованного k8s-bundle, с рабочим kubectl на нужный контекст:

./portal-cli/portal-cli install --mode k8s

Production-профиль (по желанию)

Включает PgBouncer и 2 реплики API/Worker:

./portal-cli/portal-cli install --mode k8s --prod

Что делает установщик

1. Создаёт namespace portal.
2. Поднимает PostgreSQL, Valkey (Redis), SeaweedFS (StatefulSet + PVC).
3. Запускает Job db-init: SQL-миграции, seed (admin, системные узлы, страница welcome), bucket S3.
4. Запускает API, Worker, Frontend, Portal Office.
5. Создаёт Ingress для портала и Portal Office.

В конце portal-cli печатает логин и пароль администратора. Их же показывают заметки Helm:

helm get notes portal -n portal

Как проверить успех — §5 и §6. Не закрывайте терминал, пока не сохраните пароль.

---

5. Узнайте пароль admin и URL

Пароль

Логин по умолчанию: admin (или значение seed.adminLogin в values).

Пароль:

• выводится при установке;
• лежит в сгенерированном файле portal-values.generated.yaml (поле secrets.seedAdminPassword);
• либо в секрете Kubernetes:

kubectl get secret portal-secrets -n portal \
  -o jsonpath='{.data.seed-admin-password}' | base64 -d; echo

Как проверить: команда печатает строку пароля и перевод строки. Сохраните пароль в сейф организации.

URL

Адрес: http://<ingress.host>
По умолчанию часто http://portal.local — добавьте имя в DNS или в /etc/hosts на своём ПК (см. §10).

---

6. Проверка: поды и API

Шаг 6.1. Статус через portal-cli

./portal-cli/portal-cli status --mode k8s

Шаг 6.2. Поды в namespace

kubectl get pods -n portal

Ожидание: основные поды в Running (Job db-init может быть Completed — это нормально).

Если CrashLoopBackOff / Pending:

kubectl describe pod -n portal ИМЯ_ПОДА
kubectl logs -n portal ИМЯ_ПОДА --tail=80
kubectl logs -n portal job/portal-db-init

Шаг 6.3. Версия API

Если Ingress уже резолвится с вашей машины:

curl -sS http://portal.local/api/v1/system/version

Подставьте свой host. Если DNS ещё нет — временный доступ через port-forward:

kubectl port-forward -n portal svc/portal-frontend 8080:80

В другом терминале:

curl -sS http://localhost:8080/api/v1/system/version

В браузере: http://localhost:8080 (пока открыт port-forward).

Успех: JSON с версией; вход под admin работает.

---

7. Активация лицензии

Без LICENSE.key запись в Portal ограничена. Ключ — у поставщика (в т.ч. trial 30 дней). Канал в ключе должен быть k8s.

1. Войдите как admin → Админка → Настройки → Продукт и лицензия.
2. Передайте поставщику Привязку.
3. Активируйте полученный LICENSE.key.

Или с jump-хоста (из каталога bundle):

./portal-cli/portal-cli license activate --file LICENSE.key
./portal-cli/portal-cli upgrade --mode k8s

Подробнее: Лицензии и тарифы.

---

8. Обновление

./portal-cli/portal-cli upgrade --mode k8s

При upgrade Job db-init применяет миграции (при необходимости Job пересоздают; либо helm upgrade — как описано в полной инструкции).

Онлайн из админки

1. На jump-хосте с тем же kubeconfig запустите:

./portal-cli/portal-cli update-runner --mode k8s

Оставьте процесс запущенным (Online).

2. В админке: Настройки → Продукт и лицензия → Обновить.

Полная инструкция: Обновление Portal.

Проверка после обновления:

./portal-cli/portal-cli status --mode k8s
kubectl get pods -n portal
curl -sS http://portal.local/api/v1/system/version

---

9. Конфигурация: какие файлы править

Файл	Назначение
helm/portal/values.yaml	Значения chart по умолчанию
portal-values.generated.yaml	Секреты и параметры, которые сгенерировал portal-cli (пароли и т.п.)

Редактор на jump-хосте — снова nano (сохранение Ctrl+O, выход Ctrl+X):

nano portal-values.generated.yaml

Важные параметры (пример)

ingress:
  host: portal.company.ru
  tls:
    enabled: true
    secretName: portal-tls

backend:
  replicas: 3

pgbouncer:
  enabled: true

postgresql:
  enabled: true   # false + host — если внешняя БД
  storage: 100Gi  # обязателен при enabled: true

seaweedfs:
  enabled: true   # false + s3.endpoint — внешнее хранилище
  storage: 500Gi  # обязателен при enabled: true

Размер PVC не зашит навсегда в chart — задайте под ваш StorageClass и объём документов. Redis по умолчанию использует 1Gi (redis.storage).

При установке через portal-cli размеры PVC часто подставляются автоматически (100Gi / 500Gi). Переопределение:

• переменные окружения PORTAL_PG_STORAGE и PORTAL_S3_STORAGE;
• или явно в portal-values.generated.yaml.

Для загрузки файлов до 4 ГБ в values уже задано
nginx.ingress.kubernetes.io/proxy-body-size: "4096m".

Внешний S3 (пример)

seaweedfs:
  enabled: false

s3:
  endpoint: s3.corp.local
  port: 443
  useSsl: true
  accessKey: portal-rw
  bucket: portal-files

secrets:
  s3SecretKey: "..."

Подробнее: Внешние сервисы.

Ручной Helm (если нужно явно)

helm upgrade --install portal ./deploy/helm/portal \
  -n portal --create-namespace \
  -f portal-values.generated.yaml \
  --set postgresql.storage=100Gi \
  --set seaweedfs.storage=500Gi

Путь к chart в готовом client-bundle может называться иначе (смотрите ls helm/ в вашем архиве). В исходниках репозитория chart лежит в deploy/helm/portal. Главное — указать каталог chart из вашей поставки и актуальный -f с секретами.

---

10. DNS или /etc/hosts

Добавьте записи на IP Ingress:

Имя	Куда
portal.company.ru	IP Ingress
office.company.ru	тот же IP (если так задано в values)

Для пилота на своём компьютере можно временно прописать в /etc/hosts:

127.0.0.1 portal.local office.portal.local

(Если Ingress не на localhost — поставьте реальный IP сервиса Ingress вместо 127.0.0.1.)

Узнать внешний адрес контроллера:

kubectl get svc -n ingress
# или: kubectl get ingress -n portal

Как проверить: с вашего ПК ping/curl до имени хоста доходит; в браузере открывается логин Portal.

---

11. Структура chart (ориентир)

В поставке обычно так:

helm/portal/
  Chart.yaml
  values.yaml
  templates/
    backend.yaml, worker.yaml, frontend.yaml
    postgresql.yaml, redis.yaml, seaweedfs.yaml
    db-init-job.yaml
    ingress.yaml

Это справочно: править шаблоны вручную не нужно для типовой установки.

---

12. Разработка расширений (кратко)

Как в Docker: пакеты ставятся hot deploy без обязательного рестарта подов. Штатные образы без отладчика в контейнере — брейкпоинты из IDE к Api/Worker не входят в поставку. Диагностика: kubectl logs. См. Отладка расширений.

---

13. Типичные проблемы

Что видите	Что сделать
ImagePullBackOff	Образы не в registry / на ноде — §3 (load, retag, push)
PVC Pending	Нет StorageClass или мало места — проверьте kubectl get sc и размеры storage
Ingress 404 / не открывается	Host в values ≠ DNS; нет Ingress Controller — §2 и §10
Job db-init Failed	kubectl logs -n portal job/portal-db-init
Не знаете пароль admin	Команда с seed-admin-password в §5
Нельзя сохранять в UI	Активируйте лицензию канала k8s — §7

Общее: Устранение неполадок.

---

14. Связанные документы

• Какой вариант установки выбрать
• Лицензии и тарифы
• Быстрый старт: Docker
• Обновление Portal
• Внешние сервисы
• Air-gapped установка
• Portal Office