Оператор согласования прав (permissions operator)

Компонент развёртывается как stp-controller в составе Helm chart shturval-backend. Отдельного Helm chart только для оператора прав нет: вместе с ним в chart входят backend API, Envoy, OPA и Swagger UI.

Содержание #

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

1. Обзор #

Назначение: оператор согласует объекты Permission, Scope, UserRole, GroupRole, Tenant с фактическими правами: агрегирующие и клиентские ClusterRole, привязки субъектов через плагины (RBAC, Argo CD, Kubeflow, tenant), дочерние области для тенантов и in-memory модель для политик. HTTP endpoint /bundle (типовой порт 8082) отдаёт данные для OPA; при включённых webhook выполняется валидация UserRole, GroupRole, Tenant.

Функции #

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

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

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

Цепочка на высоком уровне: объекты Tenant порождают/обновляют связанный Scope; согласование Scope обновляет модель хранения и статусы (в т.ч. аннотации кластеров); UserRole / GroupRole требуют существования соответствующего Scope и выставляют ссылку владельца; Permission обновляет платформенные и клиентские ClusterRole, изменения Permission через watch влияют на дальнейшее согласование Scope.

Цепочка управления: CR, оператор, клиентские кластеры и bundle #

Пользователь или CI применяет CR через Kubernetes API. API-сервер сохраняет объекты Tenant, Scope, Permission, UserRole и GroupRole, после чего permissions operator читает их, выполняет согласование и обращается к внешним контурам: плагинам RBAC, Argo CD, Kubeflow, клиентским кластерам и объектам CAPI Cluster.

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

Компоненты и контроллеры #

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

Компоненты рабочей нагрузки #

Архитектура runtime: Deployment менеджера, RBAC, webhook, bundle #

Схема показывает состав процесса менеджера внутри Pod: контроллеры ресурсов, HTTP endpoint bundle на порту 8082, метрики через kube-rbac-proxy, readiness-пробу на 8081 и admission webhook для UserRole, GroupRole и Tenant. Менеджер работает с Kubernetes API, CRD группы permissions.shturval.tech, сервисным аккаунтом, CAPI-кластерами и потребителями OPA bundle.

Граф связей CR и движка хранения прав #

Диаграмма описывает, как CR связаны между собой и с in-memory StorageEngine. Tenant владеет связанным Scope и создаёт роли tenant-get / tenant-edit; UserRole и GroupRole ссылаются на Scope и имена Permission; Permission наполняет модель прав и порождает ClusterRole на платформе и в клиентских кластерах.

Связь с внешними объектами #

RBAC детализируется манифестами поставки; перечень точных правил в данном документе не дублируется.

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

Платформа и Helm #

Компонент входит в chart shturval-backend: Deployment stp-controller, сервис для bundle и связанные объекты задаются шаблонами chart. Отдельного Helm chart только для permissions-operator нет — используется общий chart backend.

Типовая установка на management-кластер выполняется через cluster-manager: создаются и обновляются объекты ShturvalServiceConfig (SSC) с указанием имени чарта shturval-backend, namespace shturval-backend, зависимостей от shturval-backend-crds и shturval-ingress-controller, версии chart из параметров релиза платформы и пользовательских values.

Локальная установка CRD/RBAC через Kustomize для разработки использует namespace stp-system; в эксплуатации через платформу типичен namespace релиза shturval-backend — это должно согласовываться с переменной окружения namespace процесса.

Зависимости для клиентских правил #

Для Permission с granted_cluster_rules (политики в клиентских кластерах) на платформе должны существовать Secret’ы kubeconfig по соглашению имени и ключа (см. §2). Отдельные SSH-ключи к узлам в описанной цепочке getter не используются.

Настройка через SSP #

Любые изменения Helm values.yaml для компонента оператора в продакшене должны подаваться через ShturvalServicePatch (SSP) поверх соответствующего SSC, без прямого редактирования релиза в обход платформенных практик.

При необходимости тонкой настройки аргументов контейнера и ресурсов сверяйте фактический chart и документацию релиза платформы для используемой версии.

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

Типовые проверки (namespace подставьте фактический для релиза, обычно shturval-backend):

• состояние Pod’ов Deployment stp-controller;
• события Pod’ов и логи контейнера manager при ошибках согласования или webhook;
• доступность пробы здоровья на адресе, заданном аргументами (типово :8081);
• для политик OPA — доступность сервиса bundle (порт 8082 в типовой конфигурации флагов).

Готовность и статусы (Ready, плагины) #

Статусы плагинов (PluginApplyStatus) #

Условия Tenant (status.condition) #

Типичные симптомы #

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

Общая схема взаимодействия контуров:

Упрощённый сквозной контур: API Kubernetes и согласование ресурсов #

Схема показывает типовую последовательность: пользователь или CI применяет Scope, Permission и UserRole; API-сервер запускает соответствующие reconcile-проходы. ScopeReconciler обновляет статус и аннотации, PermissionReconciler создаёт или обновляет ClusterRole, а UserRoleReconciler читает Scope, выставляет owner reference, применяет плагины интеграций и обновляет статус роли.

Permission #

• Финалайзер: permissions.shturval.tech/finalizer.
• Создание / обновление: очистка status.applied_to_clusters, запись в модель; при платформенных правилах — обновление агрегирующего ClusterRole; при клиентских — выборка кластеров и обновление ClusterRole в каждом; выставление Ready при успехе.
• Удаление: если есть привязки ролей к данному permission — перенос повторной попытки примерно через минуту; иначе удаление платформенных и клиентских ClusterRole, снятие финалайзера.
• События CAPI: при готовности control plane или удалении кластера — повторное согласование затронутых Permission (с фильтром по применённым кластерам).

Scope #

• Удаление: если в модели ещё есть пользователи/группы для имени scope — повтор через ~5 с; иначе удаление из модели и снятие финалайзера.
• Обновление: пересчёт кластеров, аннотации, статусы namespace; для уровня namespace — проверки существования namespace в целевых кластерах; периодические повторы для уровней cluster (до ~30 мин) и namespace (~5 мин) при необходимости.

UserRole и GroupRole #

• Удаление: сброс статусов плагинов, вызов удаления у всех плагинов, расчёт готовности, снятие финалайзера и удаление из модели.
• Обновление: финалайзер, привязка к Scope, обновление модели, последовательное применение плагинов; при ошибках — немедленный requeue; при успехе — очистка «неопределённых» статусов плагинов.
• Наблюдение: изменения связанного Scope; для UserRole — также изменение Cluster.Spec.Paused.

Tenant #

• Создание / обновление: при первом добавлении финалайзера — немедленный повтор входа; генерация и применение Scope, создание ролей tenant-get / tenant-edit, регистрация в модели, условие TenantCreated.
• Удаление: проверка отсутствия дочерних tenants; удаление Scope; пока Scope существует — повтор через ~5 с; затем удаление ролей и записей в модели, очистка родительского scope, снятие финалайзера.

Префиксы имён создаваемых ClusterRole: shturval: для пользовательских ролей, platform: для платформенных.

Диаграммы переходов при согласовании #

Ниже — схемы, ориентированные на понимание состояний объекта в кластере: готовность, удаление и финалайзеры.

Согласование Permission: создание/обновление ClusterRole, удаление #

Если объект Permission отсутствует, reconcile завершается пустым результатом. Для существующего объекта оператор разделяет путь удаления и путь обновления: при удалении ждёт, пока UserRole и GroupRole перестанут ссылаться на permission, затем удаляет платформенные и клиентские ClusterRole, запись из движка и финалайзер; при обновлении добавляет финалайзер, обновляет модель, синхронизирует нужные ClusterRole и выставляет успешную готовность.

Согласование UserRole: привязка к Scope, плагины, готовность #

При обновлении UserRole оператор добавляет финалайзер, получает Scope, устанавливает controller reference, обновляет запись в движке и применяет права через плагины. Затем пересчитывается готовность: при незавершённом применении объект ставится в повторную обработку, а при успехе очищаются неопределённые результаты и reconcile завершается без повторного запуска; при удалении плагины вызываются на очистку, пересчитывается готовность удаления и снимается финалайзер.

Согласование GroupRole: симметрично UserRole #

Поток для GroupRole повторяет логику UserRole, но субъектом является claim группы. Оператор добавляет финалайзер, читает связанный Scope, выставляет owner reference, обновляет модель и применяет разрешения через плагины; при удалении удаляет плагиновые права, проверяет готовность очистки и только после этого снимает финалайзер.

Согласование Scope: кластеры, namespace, повторные попытки #

Для активного Scope оператор добавляет финалайзер, фильтрует кластеры по идентификаторам и аннотациям, обновляет пути в StorageEngine, записывает в статус permissions, paths и objectsStatus, после чего выставляет готовность. Если scope уровня platform или cluster/namespace требует повторной проверки, reconcile планируется повторно с интервалами для cluster и namespace; при удалении оператор ждёт, пока в движке не останется пользователей или групп, затем удаляет scope из модели и снимает финалайзер.

Согласование Tenant: дочерний Scope, роли tenant-get / tenant-edit #

При создании или обновлении Tenant оператор добавляет финалайзер, генерирует и применяет связанный Scope, создаёт роли tenant-get и tenant-edit, добавляет tenant в движок и выставляет условие TenantCreated=True. При удалении сначала проверяется отсутствие дочерних tenants; затем оператор удаляет Scope, ждёт его исчезновения, удаляет роли, удаляет tenant из модели, очищает ссылку в родительском scope и снимает финалайзер.

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

Аргументы процесса задаются флагами в точке входа. В поставке они передаются через шаблон Deployment chart и SSP; администратор может переопределять их только через согласованные с платформой механизмы, без импровизации имён:

Опции логгера zap также пробрасываются через стандартный механизм флагов.

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

Обратите внимание! при ENABLE_WEBHOOKS=false валидация на admission для перечисленных типов не выполняется на стороне оператора; использование только в контролируемых сценариях диагностики.

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

Общие сведения: group permissions.shturval.tech, version v1beta1, scope всех CR — Namespaced.

Permission #

spec

status

Отдельных условий типа metav1.Condition нет — только поле ready.

Scope #

spec

status

UserRole #

spec

status: RoleStatus — ready, вложенная карта permissions → кластеры/платформа → плагины → PluginObject.

GroupRole #

spec

status: как у UserRole.

Tenant #

spec

status