Изменено 2026-07-01 в 19:41

Модуль управления аутентификацией (shturval-auth)

О сервисе

Параметр	Значение
Название в интерфейсе	Модуль управления аутентификацией
Системное название (идентификатор)	`shturval-auth`
Назначение в кластере	Аутентификация и авторизация пользователей платформы: интеграция с LDAP и внешними провайдерами Keycloak или Blitz. Устанавливается в кластер управления.
Критический	Да
Публичный репозиторий	— (компонент платформы «Штурвал»)
Зависимости	`shturval-ingress-controller`
Неймспейс	`shturval-backend`

1. Обзор

Назначение: автоматическая согласованность объектов интеграции с авторизационной подсистемой: регистрируемые клиентские записи (AuthOidcClient) с обновлением статусных условий и связанным Secret, а также объектная модель локальных пользователей (User) со строгостью bcrypt через validating webhook при Create/Update.

Функции

Контур	Назначение в эксплуатации
`UserReconciler`	Присутствует в сборке reconcile (без наблюдаемых изменений объекта без других триггеров)
`AuthOidcClientReconciler`	Создание/повторное согласование OIDC клиента у провайдера, наблюдаемость через статусные поля
Validating webhook	Проверка корректности `spec.passwordHash` у `User`
Отслеживание изменений провайдера	Отдельный канал событий для повторной постановки согласований связанных CR

Сценарии инициации

Что происходит	Кто инициирует	Наблюдаемый эффект
Согласование `AuthOidcClient`	Плоскость Kubernetes / собственный источник событий	Обновление `status`, при необходимости Secret
Изменение `User`	Плоскость Kubernetes	Специализированное изменение spec/status оператором не производится; проверку пароля выполняет webhook при create/update
Вызов validating webhook	apiserver при create/update `User`	Отклонение некорректных значений bcrypt
Пробы живучести и готовности	kubelet	HTTP `/healthz`, `/readyz` на управляемых адресах

Ограничения и следствия

Ограничение	Следствие для администратора
`UserReconciler` без модифицирующей логики	Опирайтесь на webhook и смежные сервисы; не ждите «автоисправлений» в reconcile этого типа на стороне оператора
`spec.providerType` только значение `shturval`	Другие провайдеры требуют расширения продукта; текущее поле задаёт связку клиента именно со встроенной реализацией
`AUTHN_ISSUER` sentinel по умолчанию	Обязательно задавать осмысленное значение в production через шаблоны окружения
Упомянута возможная недонастройка TLS webhook watcher	После изменений инфраструктуры сертификатов проверяйте согласование admission

Место в цепочке управления

CR AuthOidcClient становится источником прав данных для приложения authn-server (OAuth/OIDC конфиг клиентов через watcher). Изменение клиента триггерит согласование оператором до выставления готовности в статусах. User ограничен политикой пароля через webhook перед тем, как учётными данными сможет пользоваться login-flow.

Ключевые характеристики

Характеристика	Значение
API group	`auth.shturval.tech`, версия `v1beta1`
CR типы	`User`, `AuthOidcClient`
Область CR	Namespaced
Leader election ID	`953fa84f.shturval.tech`
Пробы оператора	Адрес здоровья `:8081` на флагах управления
Webhook	По умолчанию порт 9443, каталог сертификатов из флагов
Изоляция процесса	Бинарь `/manager` в контейнере

Компоненты в кластере

Объект	Назначение
Deployment оператора	manager controller-runtime и сайд-кары по шаблону chart
Service webhook	точка входа admission для apiserver до `User`
Secret	объект с учётными данными OIDC клиента (владение/обновление — из согласования `AuthOidcClient`)

2. Архитектура

Компонент	Kind	Scope	Описание
`User`	CustomResourceDefinition + экземпляры	Namespace	bcrypt hash пользователя и группы
`AuthOidcClient`	CustomResourceDefinition + экземпляры	Namespace	регистрируемые OAuth клиенты
`auth-controller`	Deployment	Namespace	управляющая логика
`Secret` (`core/v1`)	связанная с клиентом конфиденция	Namespace	наблюдаемое после согласования

Точное имя каждого рабочего ресурса (labels, счётчик реплик) определяется шаблонами chart helm/auth.

3. Установка / развёртывание

Поставляется единым Helm-chart платформы sh-backend из каталога helm/auth (шаблоны Deployment, RBAC, webhook-сервис, сертификаты ingress/monitoring объявляет chart). Пространство имён задаётся релизом Helm.

Любые правки параметров перевода конфигурации в production должны идти через ShturvalServicePatch (SSP) над соответствующим SSC платформы, без неконтролируемого патча манифестов.

4. Диагностика

kubectl get deploy,pods -n "${NAMESPACE}"
kubectl logs -n "${NAMESPACE}" deploy/auth-controller -c manager --tail=200
kubectl get authoidcclients.auth.shturval.tech -n "${NAMESPACE}" -o wide
kubectl get users.auth.shturval.tech -n "${NAMESPACE}" -o wide
kubectl get validatingwebhookconfiguration

Событие	Возможная причина	Действие
`ConditionCreateClient`=False долго	недоступен issuer / TLS / учёт клиента у провайдера	проверить `AUTHN_ISSUER`, сетевую связность до authn точки и Secret
Webhook недоступен	сертификаты / Service / CA bundle	восстановить связность apiserver до Service webhook
`User` создан с отклонением	хеш bcrypt не принят validating	использовать корректный формат bcrypt hash

Условия AuthOidcClient см. раздел «AuthOidcClient» ниже.

5. Жизненный цикл

`User`

Этап	Поведение
Create/Update	Проверка webhook bcrypt; объект сохранён при успешной валидации
Reconcile оператора	Пустое завершение — отслеживаемые автоматизации на стороне оператора без изменений spec/status
Delete	используйте стандартные Kubernetes garbage policies

`AuthOidcClient`

Этап	Поведение
Стартовое согласование	Принудительный `Ready=false` до финального состояния, сверка с менеджером провайдера
Повтор	На ошибках ошибка возвращается controller-runtime без фиксированного интервала
Связать Secret	объект владений controller по условию CR
Отдельное удаление	В описании dev-delete сценария «очистить провайдера полностью» не указано — возможны остаточные ресурсы у продукта после удаления

Протокол событий из провайдера

Шаг	Участник	Эффект
1	наблюдатель провайдера	событие в канал управляющего сборщика событий
2	`AuthOidcClientReconciler`	фильтрация объектов нужного типа провайдера и постановка в очередь
3	выполнение reconcile	синхронизация статуса и Secret

PNG e2e-lifecycle недоступен — последовательность освещена таблицей.

6. Параметры оператора

Администратор может переопределять поведение только через механизмы поставки chart (SSP/values/environment), не правя код.

Флаги процесса

Флаг	По умолчанию	Значение
`--metrics-bind-address`	`0`	отключённые метрики процесса (если патч включает — используйте согласованный bind)
`--health-probe-bind-address`	`:8081`	пробы живучести
`--leader-elect`	`false`	лидер-выборки (может включаться chart)
`--metrics-secure`	`true`	безопасные метрики
`--enable-http2`	`false`	HTTP/2
`--root-ca-configmap-volume-path`	`/root-ca/ca-bundle.pem`	точка монтирования корневых CA для исходящих TLS проверок провайдеров
`--webhook-port`	`9443`	порт webhook
`--webhook-cert-dir`	`/tmp/k8s-webhook-server/serving-certs/`	секрет материала webhook
`--debug`	`false`	режим подробной записи журнала через zap

Переменные окружения

Переменная	Значение
`AUTHN_ISSUER`	issuer внутреннего авторизационного провайдера — необходим для сборки конфигурации клиента управления
`ENABLE_WEBHOOKS`	`false` блокирует регистрацию webhook (только локальная диагностика)
`LOG_LEVEL` / `--debug`	политики записи журнала

7. Справочник CRD/API

Группа: auth.shturval.tech, версия: v1beta1, scope CR: Namespaced.

`User` — scope Namespaced

spec

Поле	Тип	Обязательно	Описание
`passwordHash`	string	да	bcrypt hash пароля пользователя
`groups`	[]string	нет	группы локального пользователя

status: структура в этой редакции технического руководства не заполняется наблюдаемыми условиями.

`AuthOidcClient` — scope Namespaced

spec

Поле	Тип	Обязательно	Описание
`clientSecretRef`	`SecretReference`	нет	Secret с клиентским id / secret OAuth
`providerType`	string enum (только `shturval`)	да	связанный класс управления клиентами

status

Поле	Описание
`clientInfo`	issuer URL, CA, claims mapping групп/username
`clientHash`	md5 наблюдаемых данных конфигурации клиента для детекта изменений
`clientSecretRef`	наблюдаемое положение секрета
`ready`	булева готовность
`conditions`	последовательность фаз согласования

Conditions

Condition	True	False причины
`ConditionInitClientManager`	успешное построение менеджера провайдеров инициирован	ошибка конфигурирования
`ConditionCreateClient`	клиент существует/создан	ошибка записи конфигурации у провайдера
`ConditionValidateClientStatus`	внешнее состояние клиента синхронно ожиданиям платформы	ошибка статусной валидации

Ограничения эксплуатации (сводка)

Сводка уже приведена в §1. Дополнительно см. ограничения webhook и провайдерского enum.

Где настраивать

Сервисы и репозитории → Установленные сервисы → shturval-auth → Управлять. Подробнее — Интеграция с LDAP и Внешние провайдеры аутентификации.

Модуль управления аутентификацией (shturval-auth)

О сервисе #

Содержание #

1. Обзор #

Функции #

Сценарии инициации #

Ограничения и следствия #

Место в цепочке управления #

Ключевые характеристики #

Компоненты в кластере #

2. Архитектура #

3. Установка / развёртывание #

4. Диагностика #

5. Жизненный цикл #

User #

AuthOidcClient #

Протокол событий из провайдера #

6. Параметры оператора #

Флаги процесса #

Переменные окружения #

7. Справочник CRD/API #

User — scope Namespaced #

AuthOidcClient — scope Namespaced #

Ограничения эксплуатации (сводка) #

Где настраивать #