Home 2.15 Документация «Штурвал» Администратору кластера Сервисы и репозитории Сервисы в составе платформы Специфические сервисы кластера управления Модуль аутентификации (shturval-auth) Оператор аутентификации (auth-controller) Оператор аутентификации (auth-controller)
Раздел «Администратору кластера»: быстрый переход по подразделам
На этой странице
Expand Collapse О сервисе # Параметр Значение Название в интерфейсе Модуль управления аутентификацией Системное название 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 .
Содержание # Обзор Архитектура Установка / развёртывание Диагностика Жизненный цикл Параметры оператора Справочник CRD/API 1. Обзор # Назначение: автоматическая согласованность объектов интеграции с авторизационной подсистемой: регистрируемые клиентские записи AuthOidcClientSecretUser
Функции # Контур Назначение в эксплуатации 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 AuthOidcClientauthn-serverUser
Ключевые характеристики # Характеристика Значение API group auth.shturval.tech, версия v1beta1CR типы User, AuthOidcClientОбласть CR Namespaced Leader election ID 953fa84f.shturval.techПробы оператора Адрес здоровья :8081 на флагах управления Webhook По умолчанию порт 9443, каталог сертификатов задаётся флагами Изоляция процесса Бинарь /manager в контейнере
2. Архитектура # Компонент Kind Scope Описание UserCustomResourceDefinition + экземпляры Namespace bcrypt hash пользователя и группы. AuthOidcClientCustomResourceDefinition + экземпляры Namespace Регистрируемые OAuth-клиенты. auth-controllerDeployment Namespace Управляющая логика оператора. Secretcore/v1Namespace Связанная с клиентом конфиденциальная информация после согласования.
Точные имена рабочих ресурсов, labels и количество реплик определяются шаблонами chart shturval-auth.
3. Установка / развёртывание # Оператор поставляется в составе Helm chart shturval-auth. Chart создаёт Deployment auth-controller, RBAC, webhook Service и связанные TLS-материалы. Пространство имён задаётся релизом платформы.
Любые изменения параметров должны выполняться через ShturvalServicePatch (SSP)
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-address0Адрес метрик процесса. --health-probe-bind-address:8081Пробы живучести. --leader-electfalseLeader election. --metrics-securetrueБезопасные метрики. --enable-http2falseHTTP/2. --root-ca-configmap-volume-path/root-ca/ca-bundle.pemТочка монтирования корневых CA для исходящих TLS-проверок. --webhook-port9443Порт webhook. --webhook-cert-dir/tmp/k8s-webhook-server/serving-certs/Каталог TLS-материалов webhook. --debugfalseПодробная запись журнала через zap.
Переменные окружения # Переменная Значение AUTHN_ISSUERIssuer внутреннего авторизационного провайдера. ENABLE_WEBHOOKSПри false блокирует регистрацию webhook. LOG_LEVELУровень записи журнала.
7. Справочник CRD/API # Группа: auth.shturval.techv1beta1Namespaced .
User # Поле spec Тип Обязательно Описание passwordHashstring Да bcrypt hash пароля пользователя. groups[]stringНет Группы локального пользователя.
AuthOidcClient # Поле spec Тип Обязательно Описание clientSecretRefSecretReferenceНет Secret с client ID и client secret OAuth. providerTypestring enum (shturval) Да Класс управления клиентами.
Поле status Описание clientInfoIssuer URL, CA, claims mapping групп и username. clientHashmd5 наблюдаемых данных конфигурации клиента для обнаружения изменений. clientSecretRefНаблюдаемое положение секрета. readyБулева готовность. conditionsПоследовательность фаз согласования.
Condition True False причины ConditionInitClientManagerМенеджер провайдеров успешно построен. Ошибка конфигурирования. ConditionCreateClientКлиент существует или создан. Ошибка записи конфигурации у провайдера. ConditionValidateClientStatusВнешнее состояние клиента синхронно ожиданиям платформы. Ошибка статусной валидации.
Изменено 2026-07-16 в 11:52