Модуль управления сервисами (shturval-services)

О сервисе #

Содержание #

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

1. Обзор #

Назначение: оператор автоматизирует установку, обновление, откат и удаление Helm-чартов в кластере по объектам ShturvalRepoConfig, ShturvalServiceConfig и ShturvalServicePatch. Область ответственности — регистрация Helm-репозиториев в runtime-движке Helm внутри Pod’а оператора, согласование релизов (install / upgrade / rollback / uninstall), проверка дрейфа манифестов и здоровья ресурсов, помеченных как управляемые Helm.

Функции #

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

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

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

Схема ниже — цепочка Helm-репозиторий / CRD / оператор / Helm-релиз и точки, где вмешиваются webhook и согласование (объекты ShturvalServiceConfig и ShturvalServicePatch в API Kubernetes, релизы и ресурсы в data plane).

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

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

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

Поставка Helm (имена из Chart.yaml) #

Модуль поставляется двумя отдельными Helm-чартами (не путать с CRD ShturvalServiceConfig / «SSC» в API):

Включение и жизненный цикл контроллера в кластере обеспечивает cluster-manager (сервис платформы); объекты ShturvalServiceConfig (SSC) для связанных чартов создаются и сопровождаются как часть платформенной конфигурации, а не как произвольная ручная установка Helm-чарта администратором.

Роль оператора #

Оператор разворачивается как один Deployment в namespace платформенных сервисов. Внутри Pod’а хранятся репозиторный файл и кеш Helm (пути задаются аргументами процесса, типово каталог в образе). Контроллеры обращаются к Kubernetes API и к движку Helm; подсистема health/drift использует gitops-engine и отслеживает объекты с меткой app.kubernetes.io/managed-by.

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

Обратите внимание! без описанного механизма TLS для webhook развёртывание в продакшене с включёнными webhook’ами не будет соответствовать ожидаемой конфигурации.

Связь с внешними системами #

Диаграммы #

Развёртывание оператора (контроллеры, webhook, движок Helm, health checker в Pod’е; доступ к API кластера и внешним Helm-репозиториям).

Связи CRD и сопутствующих объектов (репозиторий, конфигурация сервиса, патч, Helm release, ссылки spec.dependency / reponame и т.д.).

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

Зависимости среды #

• cert-manager версии 1.x или выше в кластере — для TLS webhook оператора (см. Ограничения).

Порядок поставки Helm #

Поставка разделена на два чарта с фиксированными именами в Chart.yaml (см. §2):

1. shturval-services-crds — CRD;
2. shturval-services — оператор (контроллеры, webhook) в namespace shturval-services-system.

Имена Helm release и URL репозитория чартов задаются в вашем контуре поставки платформы.

Параметры чарта (обобщение из технического описания) #

В типовом values основного чарта (без ссылки на внутренние пути) по умолчанию предусматриваются, в частности:

Обратите внимание! пользовательские правки values в эксплуатации под платформой Штурвал согласуются с политикой поставки; для настраиваемых оверлей-значений используйте ShturvalServicePatch (SSP) там, где это применимо к сервису, которым доставляется оператор.

Проверка после развёртывания (без жёстких команд) #

Убедитесь, что Pod оператора в целевом namespace перешёл в Ready, CRD зарегистрированы, объекты Mutating/ValidatingWebhookConfiguration ссылаются на работающий Service и сертификаты (при согласованной схеме с cert-manager). Конкретные команды kubectl в техническом руководстве не приведены; используйте стандартные процедуры вашей среды.

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

Условия: ShturvalRepoConfig #

Условия: ShturvalServiceConfig #

Условия: ShturvalServicePatch #

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

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

Сквозной сценарий (E2E) #

Последовательность: репозиторий → ShturvalServiceConfig / патчи → согласование и состояния релиза. Полезна для понимания порядка шагов при разборе задержек и conditions.

ShturvalRepoConfig #

• Назначение (ресурсы K8s): cluster-scoped CRD, описывающий один логический Helm-репозиторий для движка в Pod’е.
• Создание/обновление: из spec формируется запись; при успехе status.ready, условия Install/Sync, добавляется финалайзер ops.shturval.tech/finalizer.
• Удаление: репозиторий удаляется из движка, финалайзер снимается. (см. скриншот ниже)

Схема согласования (создание/обновление, удаление, ключевые ветки и статус status.ready).

ShturvalServiceConfig #

• Назначение: один объект описывает один Helm-релиз в spec.namespace с заданным именем чарта, версией, репозиторием и режимом.

Режимы (spec.mode):

• Создание/обновление (auto, обобщение): проверка репозитория; при необходимости обновление кеша; ожидание готовностей dependency / dependencyclass; анализ состояния релиза; install/update; ожидание готовности движка health/drift; проверка дрейфа и health с возможными upgrade/requeue; проставление лейбла shturval.tech/system-namespace на namespace из spec.
• Self-update / SSC с именем shturval-services: для этого имени применяется write-lock к области блокировок и задержка 1 минута после снятия lock — планируйте пики нагрузки и окна изменений.
• Удаление: при iscritical — согласование останавливается с ServiceIsCritical; иначе ожидается отсутствие зависимых SSC, затем удаление релиза и снятие финалайзера ops.shturval.tech/finalizer.

Схема согласования (обзор): ветвление по spec.mode, движок Helm, health/drift, условия в status.

Схема согласования в режиме auto: репозиторий, зависимости, install/update, дрейф, откат при «зависании» релиза, повторы.

Интервалы повторов (ориентиры из логики согласования): добавление финалайзера — порядка секунды; репо не готово — порядка 5 с; движок health не готов / сервис нездоров — порядка 1 мин; зависимости — повтор; успешное завершение без requeue.

ShturvalServicePatch #

• Назначение: переопределить mode и/или customValues у выбранного имени ShturvalServiceConfig без прямого редактирования самого SSC.
• Создание/обновление: фиксация observedGeneration, проверка существования SSC, установка ownerReference, лейбл ops.shturval.tech/ssc → имя SSC; сопоставление с status.appliedPatches у SSC.
• Слияние customValues (правила): ключ с префиксом - удаляет соответствующий ключ из базы; вложенные map мержатся рекурсивно; скаляры заменяются значением из патча.
• Удаление: отдельного финалайзера у SSP нет; при удалении родительского SSC дочерние объекты с ownerReference утилизируются по правилам GC. Контроллер SSP не обрабатывает Delete самого SSC (appliedPatches predicate).
• Координация SSC ↔ SSP (шаги):

Схема согласования SSP: поиск SSC, Accepted / Applied, ownerReference, сопоставление с status.appliedPatches у ShturvalServiceConfig (см. скриншот ниже).

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

Перечислены параметры процесса, явно описанные в техническом руководстве. На практике они задаются аргументами контейнера и, при необходимости, переменными окружения в манифесте/Helm-значениях поставки. Любые изменения values для чарта, которым доставляется оператор, в среде платформы Штурвал выполняйте через ShturvalServicePatch, если это относится к соответствующему ShturvalServiceConfig.

Ограничения, не выведенные в пользовательский Helm chart: MaxHistory=2 для релизов, пороги ожидания pending-релиза, длительности wait для install/uninstall, фиксированные задержки self-update — заданы в образе поставляемой версии; для изменения требуется новая версия образа/оператора.

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

Группа API: ops.shturval.tech. Storage-версия: v1beta2. Spoke: v1beta1 (конверсия).

7.1 ShturvalRepoConfig — Cluster #

Short name: (не задан в выдержке; Kind — ShturvalRepoConfig.) Scope: Cluster.

Без зарегистрированного и готового репозитория не обслуживаются ShturvalServiceConfig, ссылающиеся на это имя.

spec #

Важно: поля TLS клиента для репозитория в API недоступны (закомментированы/не используются) — mTLS/клиентские сертификаты не поддерживаются без изменения продукта.

status #

Conditions #

7.2 ShturvalServiceConfig — Cluster (shortName: ssc) #

Один объект — один Helm-релиз в spec.namespace.

spec #

status #

Conditions #

См. §4. Диагностика.

7.3 ShturvalServicePatch — Cluster (shortName: ssp) #

Патч для mode и/или customValues у указанного SSC.

spec #

status #

Conditions #

См. §4. Диагностика.

Финалайзер (все перечисленные CRD согласно логике): ops.shturval.tech/finalizer (для SSP отдельный финалайзер не требуется — см. §5).