Версия: 2.0.x

Приемка, эксплуатация и troubleshooting

Этот документ используют после первичной установки и после upgrade. Цель - проверить, что Kubernetes, Keycloak, CM, Engine, IDE, AI/MCP, Grafana, RBAC и direct SQL работают как одна система.

Во всех командах значения в фигурных скобках заменяются вручную. Например, {cm_url} - это public URL CM API из шага service exposure, а {cm_admin_access_token} - поле .accessToken из ответа POST /auth/login.

1. Проверьте Kubernetes baseline

Выполните:

kubectl get nodes -o wide
kubectl get pods -A
kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded
helm list -A

Ожидаемо:

все nodes в состоянии Ready;
нет неожиданных pods в Pending, CrashLoopBackOff, ImagePullBackOff или долгом Terminating;
Helm releases установлены в ожидаемых namespaces.

Если есть non-running pods, сначала смотрите events и logs:

kubectl -n {namespace} describe pod {pod_name}
kubectl -n {namespace} logs {pod_name} --tail=200
kubectl -n {namespace} get events --sort-by=.lastTimestamp

2. Проверьте CM и лицензию

CM должен отвечать до установки IDE/AI/MCP, потому что Engine lifecycle и bootstrap выполняются через CM API.

curl -fsS {cm_url}/actuator/health | jq

Ожидаемо: status равен UP.

Получите admin token:

curl -fsS -X POST {cm_url}/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"{cm_admin_username}","password":"{cm_admin_web_password}"}' \
  | jq

Скопируйте .accessToken; дальше это {cm_admin_access_token}.

Проверьте identity и license:

curl -fsS {cm_url}/auth/me \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

curl -fsS {cm_url}/license \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

Ожидаемо:

/auth/me возвращает вашего Keycloak username;
cmRoles содержит cm_admin;
license status позволяет работать с защищенными endpoint-ами.

3. Проверьте Engine через CM API

Engine устанавливается и управляется только через CM API. Не используйте kubectl scale для штатных FE/CN операций: Kubernetes должен видеть изменения из Selena Custom Resource, а не ручной scale StatefulSet.

Проверьте статус:

curl -fsS '{cm_url}/engine/cluster/status?refresh=true' \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

Ожидаемо:

status равен READY;
lastApplyError пустой или null;
FE и CN components показывают ожидаемое число replicas;
FE service имеет endpoint для SQL.

Проверьте operation events, если предыдущая команда вернула lastOperationId или вы только что запускали install/scale/restart:

curl -fsS {cm_url}/engine/cluster/operations/{operation_id}/events \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

Проверьте Kubernetes ресурсы Engine только как read-only диагностику:

kubectl -n {engine_namespace} get pods,svc,pvc -o wide

4. Проверьте CM RBAC

Admin должен видеть diagnostic и mutating endpoints:

curl -fsS {cm_url}/selena/status \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

curl -fsS {cm_url}/selena/roles \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

Получите viewer token так же через POST /auth/login, но под пользователем из /cm/viewers. Скопируйте .accessToken; дальше это {cm_viewer_access_token}.

Viewer должен читать разрешенные status endpoints, но не должен менять Engine:

curl -i -sS -X POST {cm_url}/engine/cluster/components/cn:scale \
  -H 'Authorization: Bearer {cm_viewer_access_token}' \
  -H 'Content-Type: application/json' \
  -d '{"replicas":3}'

Ожидаемо: HTTP 403.

Пользователь без /cm/admins, /cm/role-admins и /cm/viewers не должен получать доступ к protected CM API. Для проверки получите token такого пользователя и выполните:

curl -i -sS {cm_url}/selena/status \
  -H 'Authorization: Bearer {cm_plain_user_access_token}'

Ожидаемо: HTTP 403.

5. Проверьте Keycloak token claims

Проверьте, что token содержит стабильный username, full group paths и нужный audience. Сначала получите access token через Keycloak:

curl -fsS -X POST {keycloak_public_url}/realms/selena/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'client_id=selena-engine' \
  --data-urlencode 'client_secret={selena_engine_client_secret}' \
  --data-urlencode 'username={keycloak_test_username}' \
  --data-urlencode 'password={keycloak_test_password}' \
  | jq

Скопируйте .access_token; дальше это {keycloak_test_access_token}.

Расшифруйте payload:

python3 -c 'import base64,json; token="{keycloak_test_access_token}"; payload=token.split(".")[1]; payload += "=" * (-len(payload) % 4); print(json.dumps(json.loads(base64.urlsafe_b64decode(payload)), indent=2, ensure_ascii=False))'

Ожидаемо:

preferred_username совпадает с canonical Selena username;
groups содержит full paths, например /cm/admins;
aud содержит selena-engine.

6. Проверьте membership refresh и RBAC

CM не читает LDAP напрямую. Цепочка такая:

LDAP/AD -> Keycloak federation -> Keycloak groups -> CM scheduled refresh
-> CM PostgreSQL snapshot -> Selena native users and role grants

Membership refresh включен по умолчанию в CM. Эти values обычно не задают в minimal profile; переопределяйте их только для изменения SLA или lock window.

Property	Рекомендуемый default	Что означает
`CM_GROUP_FILE_REFRESH_ENABLED`	`true`	Product default. Включает scheduled refresh Keycloak membership.
`CM_GROUP_FILE_REFRESH_INITIAL_DELAY`	`10s`	Сколько CM ждет после старта перед первым refresh.
`CM_GROUP_FILE_REFRESH_INTERVAL`	`30s`	Как часто CM проверяет изменения membership.
`CM_GROUP_FILE_FULL_RECONCILE_INTERVAL`	`PT6H`	Как часто CM делает полный safety reconcile даже без hash changes.

В HA только одна CM replica выполняет refresh благодаря ShedLock. На обычное добавление или удаление пользователя из группы закладывайте 1-2 минуты: это покрывает interval, Keycloak Admin API и SQL reconcile в Selena.

Если external group mappings пустые, CM покажет skipped refresh и не будет reconcile'ить пустой snapshot. Это ожидаемо до настройки group mappings.

Проверьте snapshot status:

curl -fsS {cm_url}/selena/membership-snapshot/status \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

curl -fsS {cm_url}/selena/membership-snapshot/groups \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

Regression сценарии:

Сценарий	Действие	Ожидаемо
Добавить пользователя в mapped group	В Keycloak добавьте `{rbac_test_username}` в `/ldap/selena-readers` или другую mapped group.	После refresh у пользователя появляется mapped Selena role.
Удалить пользователя из mapped group	Уберите того же пользователя из группы.	После refresh mapped role исчезает, остальные роли не трогаются.
Создать новую business group	Создайте группу в Keycloak, добавьте mapping в CM values и сделайте Helm upgrade CM.	После refresh members получают роль из mapping.
Удалить group mapping	Уберите mapping из CM values и сделайте Helm upgrade CM.	После full reconcile stale access исчезает.
Удалить группу в Keycloak	Удалите тестовую группу после удаления mapping.	CM refresh не должен ломать остальные groups.

Проверьте drift для пользователя:

curl -fsS {cm_url}/me/drift \
  -H 'Authorization: Bearer {rbac_test_user_access_token}' \
  | jq

Проверьте grants напрямую:

mysql --protocol=TCP \
  -h {selena_fe_mysql_host} \
  -P 9030 \
  -u {rbac_test_username} \
  -p'{rbac_test_cli_secret}' \
  -e "SHOW GRANTS;"

7. Проверьте direct SQL CLI secret

И LDAP/AD-backed users, и Keycloak-local users используют Keycloak для web login, но direct SQL password всегда генерирует CM.

Получите user token через CM login:

curl -fsS -X POST {cm_url}/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"{sql_test_username}","password":"{sql_test_web_password}"}' \
  | jq

Скопируйте .accessToken; дальше это {sql_test_access_token}.

Сгенерируйте CLI secret:

curl -fsS -X POST {cm_url}/me/cli-secret:reset \
  -H 'Authorization: Bearer {sql_test_access_token}' \
  | jq

Скопируйте .cliSecret; дальше это {sql_test_cli_secret}. Это значение показывается только один раз.

Подключитесь стандартным MySQL-compatible client:

mysql --protocol=TCP \
  -h {selena_fe_mysql_host} \
  -P 9030 \
  -u {sql_test_username} \
  -p'{sql_test_cli_secret}' \
  -e "SELECT CURRENT_USER(); SHOW GRANTS;"

DBeaver и IntelliJ IDEA Database Tools должны использовать обычный MySQL driver: host {selena_fe_mysql_host}, port 9030, user {sql_test_username}, password {sql_test_cli_secret}. mysql_clear_password для LDAP password flow не нужен, потому что Selena Engine не подключается к LDAP напрямую.

8. Проверьте IDE

Откройте {ide_public_url} в браузере.

Проверьте:

login переводит в Keycloak realm selena;
после login отображается IDE;
user видит только каталоги и объекты, разрешенные его Selena roles;
простой query выполняется от имени user, а не service account;
logout возвращает пользователя в expected public URL, без redirect loop.

Если IDE не открывается:

kubectl -n {selena_namespace} get pods -l app.kubernetes.io/instance=selena-ide -o wide
kubectl -n {selena_namespace} logs deploy/selena-ide-web --tail=200
kubectl -n {selena_namespace} logs deploy/selena-ide-worker --tail=200

9. Проверьте AI frontend, AI backend и MCP

AI/MCP ставятся только после Engine READY и POST /engine/cluster:bootstrap-auth-rbac, потому что MCP должен знать FE host и runtime secret.

Проверьте pods:

kubectl -n {selena_namespace} get deploy selena-ai-backend selena-ai-frontend selena-ai-mcp -o wide
kubectl -n {selena_namespace} get pods -l app.kubernetes.io/instance=selena-ai -o wide
kubectl -n {selena_namespace} get svc selena-ai-mcp -o jsonpath='{.spec.sessionAffinity}{"\n"}'

Ожидаемо:

backend, frontend и MCP имеют нужное число replicas;
pods Ready;
MCP service использует ClientIP session affinity, если это включено в values.

Проверьте backend health:

curl -fsS {ai_public_url}/api/v1/health | jq

В IDE откройте AI panel и отправьте короткий вопрос, например:

show my current catalogs

Ожидаемо: AI отвечает, а запросы к Selena идут через MCP и impersonation.

Если AI не отвечает:

kubectl -n {selena_namespace} logs deploy/selena-ai-backend --tail=200
kubectl -n {selena_namespace} logs deploy/selena-ai-mcp --tail=200

10. Проверьте Grafana

Откройте {grafana_public_url}.

Проверьте три пользователя:

Пользователь	Keycloak membership	Ожидаемый результат
Grafana admin	`/grafana/admins`	Входит как Grafana Admin.
Grafana viewer	`/grafana/viewers`	Входит как Grafana Viewer.
Без Grafana role	Нет `/grafana/admins` и `/grafana/viewers`	Доступ запрещен.

После изменения membership выйдите из Grafana и войдите снова, чтобы Grafana получила свежий OAuth token.

11. Проверьте Engine lifecycle операции

Все операции запускайте через CM API. После каждой операции смотрите operation events и финальный cluster status.

Эти проверки меняют live Engine replicas или перезапускают cluster. На production выполняйте их только если это входит в acceptance scope и есть approved maintenance window. Для обычной read-only приемки достаточно проверить status/events из раздела 3.

Scale CN down:

curl -fsS -X POST {cm_url}/engine/cluster/components/cn:scale \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  -H 'Content-Type: application/json' \
  -d '{"replicas":2}' \
  | jq

Скопируйте .operationId; дальше это {scale_cn_down_operation_id}.

curl -fsS {cm_url}/engine/cluster/operations/{scale_cn_down_operation_id}/events \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

curl -fsS '{cm_url}/engine/cluster/status?refresh=true' \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

Scale CN back:

curl -fsS -X POST {cm_url}/engine/cluster/components/cn:scale \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  -H 'Content-Type: application/json' \
  -d '{"replicas":3}' \
  | jq

Scale FE follower down и back выполняется тем же endpoint-ом с component fe. Не scale-ите FE до 0: production cluster потеряет SQL entrypoint.

curl -fsS -X POST {cm_url}/engine/cluster/components/fe:scale \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  -H 'Content-Type: application/json' \
  -d '{"replicas":2}' \
  | jq

curl -fsS -X POST {cm_url}/engine/cluster/components/fe:scale \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  -H 'Content-Type: application/json' \
  -d '{"replicas":3}' \
  | jq

Restart через CM:

curl -fsS -X POST {cm_url}/engine/cluster:restart \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

Ожидаемо:

operation status становится APPLIED;
cluster возвращается в READY;
FE service и direct SQL продолжают работать после восстановления replicas.

12. Проверьте Helm values перед upgrade

External docs используют customer-specific values files, созданные из шаблонов deploy/k8s/docs-external/values-minimal. В командах ниже {selena_cm_values} - это ваш заполненный CM values file, а не шаблон values-minimal.

helm lint deploy/k8s/charts/internal/selena-cm/chart \
  -f {selena_cm_values}

helm template selena-cm deploy/k8s/charts/internal/selena-cm/chart \
  -n {selena_namespace} \
  -f {selena_cm_values}

Перед production upgrade сделайте:

helm upgrade --install selena-cm deploy/k8s/charts/internal/selena-cm/chart \
  -n {selena_namespace} \
  -f {selena_cm_values} \
  --wait \
  --timeout 15m

kubectl -n {selena_namespace} rollout status deploy/selena-cm
curl -fsS {cm_url}/actuator/health | jq

Если helm --wait упал только из-за долгого LoadBalancer provisioning, сначала проверьте реальные services и pods. Иногда cloud provider создает LB дольше Helm timeout; повторный helm upgrade --install должен завершиться clean.

13. Частые проблемы

Симптом	Что проверить
CM login возвращает 401	Keycloak issuer, client secret `selena-engine`, user password, `preferred_username`.
User вошел в CM, но не получил role	Full group path в token, CM group-role mapping, membership snapshot status, refresh interval.
Direct SQL password не работает	Используется ли `.cliSecret` из последнего reset; подключение идет к FE MySQL port `9030`; username совпадает с Keycloak username.
IDE открывается, но query permission denied	Проверьте grants пользователя через `SHOW GRANTS` и mapped Selena roles.
AI panel не отвечает	Проверьте AI backend health, MCP pods, LLM secret и MCP access к FE service.
Grafana после logout возвращает на старую страницу	Проверьте Grafana OAuth logout URL и Keycloak client `grafana` redirect URIs.
Engine status не `READY`	Смотрите operation events, `kubectl -n {engine_namespace} get pods,events`, operator logs.
LoadBalancer services долго остаются `pending`	Проверьте cloud-provider events и `metadata.annotations` у всех `Service` типа `LoadBalancer`. Если старый overlay задавал static IP/resource-group annotations, Helm/operator могут не удалить map keys при переходе на `null`/`{}`; удалите stale annotations явно командой `kubectl annotate svc <name> <annotation-key>-`.

Диагностика operation events:

curl -fsS {cm_url}/engine/cluster/operations/{operation_id}/events \
  -H 'Authorization: Bearer {cm_admin_access_token}' \
  | jq

1. Проверьте Kubernetes baseline​

2. Проверьте CM и лицензию​

3. Проверьте Engine через CM API​

4. Проверьте CM RBAC​

5. Проверьте Keycloak token claims​

6. Проверьте membership refresh и RBAC​

7. Проверьте direct SQL CLI secret​

8. Проверьте IDE​

9. Проверьте AI frontend, AI backend и MCP​

10. Проверьте Grafana​

11. Проверьте Engine lifecycle операции​

12. Проверьте Helm values перед upgrade​

13. Частые проблемы​

1. Проверьте Kubernetes baseline

2. Проверьте CM и лицензию

3. Проверьте Engine через CM API

4. Проверьте CM RBAC

5. Проверьте Keycloak token claims

6. Проверьте membership refresh и RBAC

7. Проверьте direct SQL CLI secret

8. Проверьте IDE

9. Проверьте AI frontend, AI backend и MCP

10. Проверьте Grafana

11. Проверьте Engine lifecycle операции

12. Проверьте Helm values перед upgrade

13. Частые проблемы