Оператор аутентификации (auth-controller)

О сервисе

Параметр Значение
Название в интерфейсе Модуль управления аутентификацией
Системное название chart shturval-auth
Компонент auth-controller
Назначение в кластере Согласование объектов User и AuthOidcClient, проверка локальных пользователей через validating webhook, подготовка данных для OIDC-клиентов.
Критический Да
Публичный репозиторий — (компонент платформы «Штурвал»)
Неймспейс shturval-backend

auth-controller входит в Helm chart shturval-auth. Этот chart также разворачивает authn-server, session-manager и ldap-cache.

Содержание

  1. Обзор
  2. Архитектура
  3. Установка / развёртывание
  4. Диагностика
  5. Жизненный цикл
  6. Параметры оператора
  7. Справочник CRD/API

1. Обзор

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

Функции

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

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

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

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

Ограничение Следствие для администратора
UserReconciler без модифицирующей логики Опирайтесь на webhook и смежные сервисы; не ждите автоисправления User в reconcile.
spec.providerType принимает только значение shturval Поле задаёт связку клиента со встроенной реализацией авторизационного провайдера.
AUTHN_ISSUER должен указывать на рабочий issuer Проверяйте значение при переводе стенда в production.
Webhook зависит от TLS-материалов и Service После изменений сертификатов проверяйте доступность admission.

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

CR AuthOidcClient становится источником данных для приложения authn-server: watcher authn-server получает конфигурацию OAuth/OIDC-клиентов из согласованных ресурсов. 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 в контейнере

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

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

Точные имена рабочих ресурсов, labels и количество реплик определяются шаблонами chart shturval-auth.

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

Оператор поставляется в составе Helm chart shturval-auth. Chart создаёт Deployment auth-controller, RBAC, webhook Service и связанные TLS-материалы. Пространство имён задаётся релизом платформы.

Любые изменения параметров должны выполняться через 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-server и связанный Secret.
Webhook недоступен Ошибка сертификатов, Service или CA bundle Восстановить связность API-сервера до webhook Service.
User отклоняется при создании bcrypt hash не прошёл validating webhook Использовать корректный формат bcrypt hash.

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

User

Этап Поведение
Create/Update Webhook проверяет bcrypt; объект сохраняется при успешной валидации.
Reconcile оператора Завершается без наблюдаемых изменений spec/status.
Delete Используются стандартные политики удаления Kubernetes.

AuthOidcClient

Этап Поведение
Стартовое согласование До финального состояния выставляется Ready=false, затем выполняется сверка с менеджером провайдера.
Повтор При ошибках reconcile возвращает ошибку controller-runtime.
Связать Secret Secret становится связанным объектом по условию CR.
Удаление Проверяйте остаточные ресурсы у провайдера после удаления CR.

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

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

Флаг По умолчанию Значение
--metrics-bind-address 0 Адрес метрик процесса.
--health-probe-bind-address :8081 Пробы живучести.
--leader-elect false Leader election.
--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/ Каталог TLS-материалов webhook.
--debug false Подробная запись журнала через zap.

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

Переменная Значение
AUTHN_ISSUER Issuer внутреннего авторизационного провайдера.
ENABLE_WEBHOOKS При false блокирует регистрацию webhook.
LOG_LEVEL Уровень записи журнала.

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

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

User

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

AuthOidcClient

Поле spec Тип Обязательно Описание
clientSecretRef SecretReference Нет Secret с client ID и client secret OAuth.
providerType string enum (shturval) Да Класс управления клиентами.
Поле status Описание
clientInfo Issuer URL, CA, claims mapping групп и username.
clientHash md5 наблюдаемых данных конфигурации клиента для обнаружения изменений.
clientSecretRef Наблюдаемое положение секрета.
ready Булева готовность.
conditions Последовательность фаз согласования.
Condition True False причины
ConditionInitClientManager Менеджер провайдеров успешно построен. Ошибка конфигурирования.
ConditionCreateClient Клиент существует или создан. Ошибка записи конфигурации у провайдера.
ConditionValidateClientStatus Внешнее состояние клиента синхронно ожиданиям платформы. Ошибка статусной валидации.
← Модуль управления аутентификацией (shturval-auth)
Модуль обновления кластера (shturval-update) →