Чеклист подготовки кластера

Этот чеклист подготавливает Kubernetes-кластер до установки Selena. Не пропускайте его: большинство проблем установки связано не с Selena, а с неподготовленными DNS, StorageClass, registry access, Keycloak URL или Kubernetes permissions.

1. Проверьте доступ к Kubernetes

Чеклист:

• kubectl смотрит в нужный cluster.
• Есть права создавать namespaces, Secrets, ConfigMaps, Services, Deployments, StatefulSets, PVC и CRD.
• Доступен Helm 3.
• В cluster хватает CPU, memory и storage под выбранный размер Engine.

Команды:

kubectl config current-context
kubectl get nodes -o wide
kubectl get storageclass
helm version

Проверка прав:

kubectl auth can-i create namespaces
kubectl auth can-i create secrets -A
kubectl auth can-i create configmaps -A
kubectl auth can-i create persistentvolumeclaims -A
kubectl auth can-i create services -A
kubectl auth can-i create deployments.apps -A
kubectl auth can-i create statefulsets.apps -A
kubectl auth can-i create customresourcedefinitions.apiextensions.k8s.io

Ожидаемо: yes для всех прав, которые нужны выбранному installation path.

2. Выберите namespaces

Рекомендованный baseline:

Namespace	Для чего
selena	CM, IDE, AI backend, AI frontend, MCP и shared application Secrets.
selena-operator	Selena operator, если operator ставится отдельно от application namespace.
selena-engine	Selena Engine FE/CN или FE/BE pods и services.
selena-keycloak	Keycloak, если ставится в этот же cluster.
selena-postgres	PostgreSQL, если ставится в этот же cluster.
selena-monitoring	Prometheus и Grafana, если ставятся в этот же cluster.
selena-minio-operator	MinIO Operator, если bundled MinIO ставится в этот же cluster.
selena-minio	MinIO, если используется S3-compatible storage в Kubernetes.
selena-lakekeeper	Lakekeeper, если используется Iceberg REST catalog.

Создайте namespaces:

kubectl create namespace "{selena_namespace}" --dry-run=client -o yaml | kubectl apply -f -
kubectl create namespace "{operator_namespace}" --dry-run=client -o yaml | kubectl apply -f -
kubectl create namespace "{engine_namespace}" --dry-run=client -o yaml | kubectl apply -f -

Если зависимости тоже ставятся в этот cluster:

kubectl create namespace selena-keycloak --dry-run=client -o yaml | kubectl apply -f -
kubectl create namespace selena-postgres --dry-run=client -o yaml | kubectl apply -f -
kubectl create namespace selena-monitoring --dry-run=client -o yaml | kubectl apply -f -
kubectl create namespace selena-minio-operator --dry-run=client -o yaml | kubectl apply -f -
kubectl create namespace selena-minio --dry-run=client -o yaml | kubectl apply -f -
kubectl create namespace selena-lakekeeper --dry-run=client -o yaml | kubectl apply -f -

3. Подготовьте DNS и публикацию сервисов

Чеклист:

• Решено, как пользователи открывают Keycloak, CM, IDE, Grafana и Selena FE MySQL endpoint.
• Если используется AI Agent, определен browser-reachable URL, который IDE откроет во встроенном iframe. Это может быть отдельный host или path под тем же доменом, что IDE.
• Для production browser-facing endpoints используется HTTPS.
• Keycloak public issuer URL стабилен до настройки OIDC clients.
• PostgreSQL, LDAP/AD, internal Prometheus и service-to-service ports не опубликованы наружу без явного approval security-команды.

Типовые варианты:

Вариант	Когда использовать
Ingress или API gateway	Рекомендованный production-вариант для HTTP(S).
Cloud LoadBalancer	Подходит, если каждому service нужен отдельный внешний адрес.
NodePort	Обычно только controlled/dev environments.
Port-forward	Только временная admin-проверка, не production exposure.

См. Kubernetes documentation:

• Ingress для HTTP/HTTPS routing.
• Services для ClusterIP, NodePort и LoadBalancer.

Минимальные browser-facing HTTP endpoints:

Service	Пример
Keycloak	https://keycloak.example.com
CM API	https://cm.example.com/api/v1
IDE	https://ide.example.com
AI iframe URL	https://ide.example.com/selena/chat или https://ai.example.com
Grafana	https://grafana.example.com

Direct SQL endpoint:

Service	Пример
Selena FE MySQL	selena-sql.example.com:9030

Минимальный Ingress example для HTTP services в {selena_namespace}:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: selena-http
  namespace: {selena_namespace}
spec:
  ingressClassName: {ingress_class_name}
  tls:
    - hosts:
        - cm.example.com
        - ide.example.com
      secretName: {tls_secret_name}
  rules:
    - host: cm.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: selena-cm
                port:
                  number: 8088
    - host: ide.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: selena-ide
                port:
                  number: 10001

Keycloak и Grafana могут быть в других namespaces. В этом случае создайте отдельный Ingress в соответствующем namespace или используйте ваш стандартный API gateway. Для AI iframe URL можно использовать отдельный host https://ai.example.com или path под IDE host, если ваш reverse proxy умеет маршрутизировать этот path в AI frontend Service.

MySQL-compatible endpoint 9030 не является HTTP. Не публикуйте его через обычный HTTP Ingress. Используйте LoadBalancer, TCP Gateway/Ingress controller feature, private endpoint или VPN-only address.

Проверка DNS:

dig +short keycloak.example.com
dig +short cm.example.com
dig +short ide.example.com
dig +short grafana.example.com

4. Подготовьте persistent storage

Чеклист:

• Выбран StorageClass для PostgreSQL.
• Выбран StorageClass для FE metadata/log volumes.
• Выбран StorageClass для CN или BE data/cache/log volumes.
• Dynamic provisioning PVC работает.
• Есть backup/snapshot policy для PostgreSQL и Engine volumes.

Минимальные требования:

Workload	Требования к StorageClass
PostgreSQL	ReadWriteOnce, dynamic provisioning, надежный block storage, поддержка snapshot/backup на уровне платформы. Для production желательно allowVolumeExpansion=true.
Selena FE metadata/log volumes	ReadWriteOnce, persistent disk, стабильная latency. Не используйте ephemeral/local-only storage без отдельного HA/backup решения.
Selena CN/BE data/cache/log volumes	ReadWriteOnce, достаточная throughput/IOPS под compute workload, capacity expansion или понятная процедура расширения.
Multi-zone cluster	StorageClass должен быть topology-aware. Обычно лучше volumeBindingMode: WaitForFirstConsumer, чтобы PVC создавался в зоне, где scheduler разместил pod.

Проверьте выбранный StorageClass:

kubectl get storageclass {storage_class} -o yaml

На что смотреть:

• provisioner соответствует storage driver, approved в вашем cluster;
• volumeBindingMode подходит вашей topology;
• allowVolumeExpansion включен, если вы планируете online/offline расширение PVC;
• reclaim policy соответствует политике заказчика. Для production данных часто требуется Retain или отдельная backup/snapshot процедура.

Проверка StorageClass:

kubectl get storageclass

Проверка dynamic PVC:

cat > /tmp/selena-pvc-test.yaml <<YAML
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: selena-pvc-test
  namespace: {selena_namespace}
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: {storage_class}
  resources:
    requests:
      storage: 1Gi
YAML

kubectl apply -f /tmp/selena-pvc-test.yaml
kubectl -n "{selena_namespace}" get pvc selena-pvc-test
kubectl -n "{selena_namespace}" delete pvc selena-pvc-test

Ожидаемо: PVC переходит в Bound.

5. Подготовьте container registry access

Чеклист:

• Kubernetes nodes могут pull'ить все Selena images.
• Для private registry создан image pull Secret в каждом namespace, где будут запускаться pods.
• Если используется mirror, все image repository/tag в values указывают на mirror.

Что нужно знать:

• image pull Secret имеет type kubernetes.io/dockerconfigjson;
• Secret namespace-scoped, поэтому его нужно создать в каждом namespace, где запускаются pods с private images;
• имя Secret должно совпадать с imagePullSecrets[].name в values или Engine spec. В этих документах используется имя selena-registry.

Если Selena images находятся в private registry, создайте Secret минимум в:

Namespace	Зачем
{selena_namespace}	CM, IDE, AI backend/frontend, MCP.
{engine_namespace}	Selena Engine FE/CN или FE/BE pods.
{operator_namespace}	Selena operator, если operator image тоже private.

Если bundled external images тоже mirror'ятся в private registry, создайте такой же Secret в namespaces этих dependencies.

Создайте pull Secret:

kubectl -n {selena_namespace} create secret docker-registry selena-registry \
  --docker-server={registry_host} \
  --docker-username={registry_username} \
  --docker-password={registry_password} \
  --docker-email={registry_email}

kubectl -n {engine_namespace} create secret docker-registry selena-registry \
  --docker-server={registry_host} \
  --docker-username={registry_username} \
  --docker-password={registry_password} \
  --docker-email={registry_email}

kubectl -n {operator_namespace} create secret docker-registry selena-registry \
  --docker-server={registry_host} \
  --docker-username={registry_username} \
  --docker-password={registry_password} \
  --docker-email={registry_email}

Если Secret уже существует и нужно обновить его без ручного удаления:

kubectl -n {selena_namespace} create secret docker-registry selena-registry \
  --docker-server={registry_host} \
  --docker-username={registry_username} \
  --docker-password={registry_password} \
  --docker-email={registry_email} \
  --dry-run=client -o yaml | kubectl apply -f -

Повторите эту команду для каждого namespace.

Если у администратора уже есть локальный Docker config с доступом к registry:

kubectl -n {selena_namespace} create secret generic selena-registry \
  --from-file=.dockerconfigjson={path_to_docker_config_json} \
  --type=kubernetes.io/dockerconfigjson

Обычно {path_to_docker_config_json} равен ~/.docker/config.json на машине, где выполнен docker login {registry_host}.

Пропишите Secret в values:

imagePullSecrets:
  - name: selena-registry

Для Selena operator ключ находится внутри selenaOperator:

selenaOperator:
  imagePullSecrets:
    - name: selena-registry

Для Engine cluster Secret задается в CM API spec:

"imagePullSecrets": [
  { "name": "selena-registry" }
]

Проверьте Secret:

kubectl -n {selena_namespace} get secret selena-registry
kubectl -n {engine_namespace} get secret selena-registry
kubectl -n {operator_namespace} get secret selena-registry
kubectl -n {selena_namespace} get secret selena-registry \
  -o jsonpath='{.type}{"\n"}'

Ожидаемый type: kubernetes.io/dockerconfigjson.

Kubernetes documentation:

• Pull an Image from a Private Registry
• Specifying imagePullSecrets on a Pod

6. Подготовьте внешние зависимости

Selena может использовать уже существующие customer-managed зависимости или зависимости, установленные в тот же Kubernetes cluster.

Обязательные:

Dependency	Используется для
Keycloak	Web login, token validation, источник group membership.
PostgreSQL	CM DB, Keycloak DB если Keycloak in-cluster, IDE metadata, AI sessions.

Обычно нужны в production:

Dependency	Используется для
S3-compatible object storage	Shared data storage и Iceberg workflows.
Prometheus и Grafana	Monitoring и dashboards.

Optional:

Dependency	Используется для
LDAP/AD	Enterprise users/groups за Keycloak federation.
Lakekeeper	Iceberg REST catalog.
External Secrets или Vault	Доставка secret values в Kubernetes Secrets.