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

О сервисе

ПараметрЗначение
Название в интерфейсеМодуль управления сервисами
Системное название (идентификатор)shturval-services
Назначение в кластереОркестрация установки и обновления платформенных сервисов: реагирует на ShturvalServiceConfig (SSC) и ShturvalServicePatch (SSP), разворачивает и обновляет Helm-релизы. Не предназначен для развёртывания пользовательских приложений (для этого используется ArgoCD, shturval-cd).
КритическийДа
Публичный репозиторий— (компонент платформы «Штурвал», на базе Helm и Flux)
Зависимостиshturval-services-crds, shturval-networking
Неймспейсshturval-services-system

Содержание

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

1. Обзор

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

Как модуль работает с ресурсами

Оператор управляет тремя cluster-scoped CRD в группе ops.shturval.tech:

РесурсРоль
ShturvalRepoConfigОписывает Helm-репозиторий (URL, учётные данные) для движка в Pod’е оператора
ShturvalServiceConfig (SSC)Описывает один Helm-релиз: чарт, версию, namespace, репозиторий (spec.reponame), режим и базовые customvalues
ShturvalServicePatch (SSP)Переопределяет mode и/или customValues у выбранного SSC без прямого редактирования SSC

Цепочка для администратора: ShturvalRepoConfig → ShturvalServiceConfig → Helm-релиз в целевом namespace. SSP ссылается на SSC по spec.shturvalServiceConfigName и накладывается при согласовании SSC, а не отдельным Helm-вызовом из контроллера SSP.

Контроллер ShturvalServicePatch не устанавливает Helm-релиз. Он связывает SSP с целевым SSC (Accepted, ownerReference, лейбл ops.shturval.tech/ssc). Слияние mode и customValues выполняется при согласовании ShturvalServiceConfig (см. схему §3 — блок Apply SSP patches). Итоговые values записываются в status.appliedCustomValues, режим — в status.appliedMode, имена применённых патчей — в status.appliedPatches. Условие Applied у SSP выставляется, когда имя SSP появляется в ssc.status.appliedPatches.

Функции

КомпонентНазначениеЗаметки для эксплуатации
Регистрация репозиториев (ShturvalRepoConfig)Добавление/удаление записей Helm-репозитория в runtimeОперации с файлом репозиториев в Pod’е сериализованы (мьютекс), согласование идемпотентно
Согласование сервисов (ShturvalServiceConfig)Install/upgrade/rollback/uninstall релиза, режимы auto / manual / absent, дрейф и healthЗависимости между SSC, обработка «зависших» релизов, финалайзеры; при reconcile — слияние SSP и запись appliedCustomValues
Патчи (ShturvalServicePatch)Переопределение mode и customValues поверх SSCСвязь с SSC через ownerReference; порядок по patchOrder; фактическое применение — в reconcile SSC
Mutating webhook для ShturvalServiceConfigСинхронизация spec.serviceclass в метку shturval.tech/classТребуется рабочий TLS для webhook (см. Ограничения)
Validating webhook для ShturvalServiceConfigЗарезервированоЛогика валидации не реализована (заглушка); см. Ограничения
Подсистема проверки здоровья (GitOpsEngine)Проверка здоровья и дрейфа ресурсов релизаУчитываются объекты с меткой app.kubernetes.io/managed-by

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

Что происходитКто инициируетНаблюдаемый эффект
Согласование репозиторияПлоскость управления (события ShturvalRepoConfig)Обновление status, регистрация репозитория в движке Helm в Pod’е
Согласование сервисаПлоскость управления (события ShturvalServiceConfig и связанных SSP)Слияние SSP, изменение Helm-релиза в целевом namespace, обновление appliedCustomValues / appliedMode / appliedPatches и условий в status
Согласование патчаПлоскость управления (события SSP и изменения appliedPatches у SSC)OwnerReference, лейблы, условия Accepted / Applied
Mutating webhookAPI-сервер при Create/Update ShturvalServiceConfigУстановка/актуализация лейбла класса сервиса
Validating webhookAPI-сервер при Create/Update ShturvalServiceConfigБез подтверждённой бизнес-логики валидации
Фоновая проверка здоровьяЗапуск процесса оператораГотовность движка к проверкам drift/health

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

ОграничениеСледствие
TLS для webhooks ожидается через cert-managerБез настроенного механизма выдачи сертификатов webhook’и не введутся в рабочее состояние
ShturvalServiceConfig с именем shturval-services обрабатывается с write-lock и задержкой 1 минута после разблокировкиПри изменении такого SSC остальные согласования SSC могут ожидать до ~1 минуты
spec.iscritical: true запрещает удаление в режиме absentПеред снятием релиза необходимо снять критичность в спецификации
Клиентская TLS-аутентификация для Helm-репозитория (поля вроде cert/key/ca для репо) не поддержана в APIАутентификация — по учётным данным и флагу insecure в рамках описанного ShturvalRepoConfig
MaxHistory в Helm-логике фиксирован (значение 2 в поставке оператора)Для откатов доступно ограниченное число ревизий; изменение требует новой версии образа
Validating webhook для SSC — без реализованной валидацииОшибки в spec SSC на уровне admission не отлавливаются этим webhook’ом
Метрики по умолчанию отключены (--metrics-bind-address=0)Сбор метрик с процесса потребует явной настройки в манифесте развёртывания
HTTP/2 по умолчанию отключён для серверов метрик и webhookПоведение при интеграции с внешними прокси — учитывать настройки

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

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

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

Цепочка управления: репозиторий, релиз, патч, вебхуки

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

ХарактеристикаЗначение
API Groupops.shturval.tech
Версии APIv1beta1 (spoke), v1beta2 (hub, storage)
Типовой namespace развёртывания (Kustomize / Helm)shturval-services-system
Leader electionПо умолчанию выключена
МетрикиПо умолчанию отключены
WebhookMutating + Validating для ShturvalServiceConfig (v1beta2); в поставке также предусмотрен шаблон для RepoConfig
Параллельность согласования SSCДо 5 одновременных reconciles (значение из поставки контроллера)
Поведение при панике в контроллере SSCВключён recover panic

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

КомпонентТип KubernetesScopeНазначение
ShturvalRepoConfigCRDClusterHelm-репозиторий (URL, учётные данные)
ShturvalServiceConfigCRDClusterПараметры одного Helm-релиза
ShturvalServicePatchCRDClusterПатч mode/customValues для выбранного SSC
Pod оператораDeploymentNamespacedПроцесс в типовом namespace shturval-services-system
MutatingWebhook (SSC)MutatingWebhookConfigurationClusterСинхронизация класса в лейбл
ValidatingWebhook (SSC)ValidatingWebhookConfigurationClusterБез бизнес-логики валидации

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

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

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

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

Имя чарта (Helm name)Каталог в исходникахНазначение
shturval-services-crdshelm/crdsУстановка CRD (ShturvalRepoConfig, ShturvalServiceConfig, ShturvalServicePatch)
shturval-serviceshelm/mainРазвёртывание оператора: Deployment, RBAC, webhook, сервисы

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

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

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

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

Компоненты рабочей нагрузки (Deployment, RBAC, webhook)
ЭлементОписание
Контейнер оператораБинарь shturval-operator, пробы health/readiness на адресе, заданном флагом (типово :8081)
Роли и привязкиClusterRole/Binding для работы с CRD и кластерными операциями согласно поставляемым манифестам
WebhookService и TLS (через cert-manager в типовой поставке) для mutating/validating
cert-managerОжидается в кластере для выдачи сертификатов webhook (см. Ограничения)

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

Система / объектРоль
HTTP(S) Helm-репозиторииИсточник чартов по ShturvalRepoConfig
API KubernetesОбъекты CRD, Secret’ы, Namespace, отслеживаемые ресурсы релизов
Сторонние чарты в целевых namespaceРазворачиваются Helm’ом согласно ShturvalServiceConfig

Диаграммы

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

Архитектура развёртывания

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

Иллюстрация: Диаграммы

CRD и связи ресурсов


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

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

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

Иллюстрация: Сквозной сценарий (E2E)

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

ShturvalRepoConfig

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

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

Иллюстрация: ShturvalRepoConfig

Согласование ShturvalRepoConfig

ShturvalServiceConfig

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

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

РежимПоведение
autoInstall → обнаружение дрейфа → синхронизация → health; при смене версии — принудительный upgrade
manualОператор не изменяет релиз; status.ready без проверок
absentUninstall, если iscritical не мешает
  • Согласование (общее): до ветвления по spec.mode применяются SSP (patchMode + patchCustomValues, сортировка по patchOrder); записываются status.appliedCustomValues, status.appliedMode, status.appliedPatches (см. блок Apply SSP patches на схеме ниже).
  • Создание/обновление (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, блок Apply SSP patches, движок Helm, health/drift, условия в status.

Согласование ShturvalServiceConfig — обзор

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

Согласование ShturvalServiceConfig — режим auto

Интервалы повторов (ориентиры из логики согласования): добавление финалайзера — порядка секунды; репо не готово — порядка 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).

Контроллер ShturvalServicePatch не устанавливает Helm-релиз. Он связывает SSP с целевым SSC (Accepted, ownerReference, лейбл). Слияние mode и customValues выполняется при согласовании ShturvalServiceConfig. Итоговые values записываются в status.appliedCustomValues, режим — в status.appliedMode, имена патчей — в status.appliedPatches. Условие Applied у SSP выставляется, когда имя SSP появляется в ssc.status.appliedPatches.

  • Координация SSC ↔ SSP (шаги):
ШагРесурс / сигналДействие (смысловой)
1ShturvalServicePatchПроверка целевого SSC, выставление Accepted
2SSP + SSCOwnerReference и лейбл связи
3ShturvalServiceConfig (согласование)Применение патчей; запись status.appliedCustomValues, status.appliedMode, status.appliedPatches
4SSPApplied по факту попадания имени в ssc.status.appliedPatches

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

Согласование ShturvalServicePatch


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

Условия: ShturvalRepoConfig

ConditionПри TrueПри False / причины
InstallРепозиторий добавлен в движокОшибка при добавлении/обновлении репозитория
SyncРепозиторий синхронизированErrorCheckHelmRepo, ErrorRemoveHelmRepo
Uninstall—Для сценария удаления — через финалайзер, отдельная логика

Условия: ShturvalServiceConfig

ConditionПри TrueПри False / причины
InstallРелиз установлен, версия соответствует specRuntimeRepositoryNotReady, RepositoryNotUpdated, WaitingInstallDependency, ErrConvertParams, ErrCheckSscStatus, ErrorInstallService, ErrorUpdateService, ErrorRollbackService, ReleasePending, ReleaseRollback
SyncНет дрейфа values и манифестовGitOpsEngineNotReady, ErrorRenderManifests, ErrorCheckValuesDrift, ErrorCheckDrift, ErrorUpdateService, ReleasePending, ErrGetPendingTime
HealthyУправляемые ресурсы здоровыErrorCheckServiceHealth, ErrorServiceNotHealthy
UninstallРелиз удалён (когда сценарий — удаление)ServiceIsCritical, WaitingUninstallDependency, ServiceUninstalling, ErrRemoveService, ErrorRemoveService, ErrorConvertParams, ErrorCheckSscStatus
PatchПатчи примененыPatchFailed
UpdateNamespaceМетки namespace обновленыGetNamespaceFailed, UpdateNamespaceFailed

Условия: ShturvalServicePatch

ConditionПри TrueПри False / причины
AcceptedSSC найден, ownerReference установленSSCNotFound
AppliedИмя SSP в ssc.status.appliedPatchesNotAppliedYet

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

СимптомВозможная причинаДействие
Webhook не готов, ошибки при создании SSCНет cert-manager / сертификатов, неверные пути к TLSПроверить схему cert-manager и статус Certificate
RepositoryNotUpdated / репо не готовоShturvalRepoConfig не в Sync / нет регистрацииПроверить ShturvalRepoConfig и сетевой доступ к Helm-репо
Долгая блокировка при измененияхИзменяется SSC с именем shturval-servicesПланировать окна; учитывать задержку до ~1 минуты
Нельзя снять релиз (absent)iscritical: trueСнять флаг в spec
ServiceIsCritical при удаленииСм. вышеСнять критичность
ReleasePending / откатРелиз «висел» в pending дольше порога (в поставке — 5 минут)Анализ событий Helm, логи оператора; при необходимости ручной разбор внешнего релиза
Нет валидации на admissionValidating webhook — заглушкаДоп. проверки spec до применения (политика организации)
SSP Accepted=false, SSCNotFoundЦелевой SSC ещё не создан или имя в spec.shturvalServiceConfigName неверноПроверить наличие SSC; контроллер SSP периодически повторяет reconcile
SSP Applied=false, NotAppliedYetSSC ещё не завершил reconcile с применением патчейПроверить status.appliedPatches и condition Patch у SSC

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

Модуль устанавливается cluster-manager как часть платформенной конфигурации. Администратору достаточно убедиться, что в кластере есть cert-manager (см. Ограничения) и что Pod оператора, CRD и webhook в рабочем состоянии.

Порядок поставки Helm и параметры чарта

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

  • 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 основного чарта (без ссылки на внутренние пути) по умолчанию предусматриваются, в частности:

Параметр (логически)Смысл
replicaCountЧисло реплик Deployment (типово 1)
tolerations / affinityСходимость с узлами инфраструктуры / control-plane (шаблон под конкретный кластер)

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

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

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


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

Любые изменения values для чарта, которым доставляется оператор, в среде платформы Штурвал выполняйте через ShturvalServicePatch, если это относится к соответствующему ShturvalServiceConfig.

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

Аргументы процесса (из технического руководства)

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

ПараметрПо умолчанию (из руководства)Смысл
--metrics-bind-address00 — метрики отключены; иначе адрес/порт
--health-probe-bind-address:8081Прослушивание health/readiness
--leader-electfalseLeader election
--metrics-securetrueHTTPS для метрик (если включены)
--enable-http2falseHTTP/2 для серверов метрик и webhook
--webhook-cert-pathпустоКаталог TLS для webhook
--webhook-cert-nametls.crtИмя файла сертификата
--webhook-cert-keytls.keyИмя файла ключа
--metrics-cert-pathпустоКаталог TLS для сервера метрик
--metrics-cert-nametls.crtИмя сертификата метрик
--metrics-cert-keytls.keyИмя ключа метрик
--repo-config/helmКаталог с repositories.yaml
--repo-cache/helmКеш репозиториев
--helm-timeout5mТайм-аут операций Helm
ENABLE_WEBHOOKS(не задана — webhook включены)false — отключение регистрации webhook (например среда без TLS)

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

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

7.1 ShturvalRepoConfig — Cluster

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

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

spec

ПолеТипОбязательностьОписание
urlstringДаURL Helm-репозитория
usernamestringНетЛогин
passwordstringНетПароль
insecureboolНетПропуск проверки TLS сертификата

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

status

ПолеТипОписание
readybooltrue при успешной регистрации
conditionsмассив ConditionСостояние

Conditions

См. §4. Диагностика. Для Install при False — в том числе ошибка при RepoAddOrUpdate.


7.2 ShturvalServiceConfig — Cluster (shortName: ssc)

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

spec

ПолеТипОбязательностьОписание
modeenum: auto / manual / absentДаРежим; по умолчанию auto
chartstringДаИмя чарта (шаблон имени из CRD)
versionstringНетВерсия чарта
namespacestringДаNamespace установки
reponamestringДаИмя ShturvalRepoConfig
dependency[]stringНетИмена SSC-зависимостей
dependencyclass[]stringНетКлассы SSC (достаточно одного Ready SSC с лейблом shturval.tech/class)
serviceclassstringНетКласс сервиса; webhook копирует в лейбл shturval.tech/class
extraargsmap[string]stringНетДоп. аргументы Helm
customvaluesmap[string]interface{}НетЗначения Helm (без жёсткой схемы)
iscriticalboolНетЕсли true, удаление через absent запрещено

status

ПолеТипОписание
readyboolОбщая готовность
currentModeenumФактический режим
currentVersionstringУстановленная версия
conditionsмассив ConditionСостояние
appliedCustomValuesmapИтоговые values после патчей (записываются при согласовании SSC)
appliedModeenumРежим после патчей
appliedPatches[]stringИмена применённых ShturvalServicePatch

Conditions

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


7.3 ShturvalServicePatch — Cluster (shortName: ssp)

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

spec

ПолеТипОбязательностьОписание
shturvalServiceConfigNamestringДаИмя целевого ShturvalServiceConfig
patchOrder*intНетПорядок (меньше — раньше; nil трактуется как 0)
modeenumНетПереопределяет spec.mode SSC
customvaluesmap[string]interface{}НетРекурсивный merge поверх spec.customvalues SSC

status

ПолеТипОписание
observedGenerationint64Последнее обработанное поколение
conditionsмассив ConditionСостояние

Conditions

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


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