Провайдер Shturval v2 (shturval-capsm)

О сервисе #

Справочно: перечень объектов Shturval* см. в разделе Кастомные ресурсы жизненного цикла узлов — Shturval v2.

Содержание #

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

1. Обзор #

shturval-manual — оператор Kubernetes, реализующий роль CAPI infrastructure provider для платформы Штурвал. Оператор управляет bare-metal- и SSH-узлами: автоматически регистрирует физические хосты, контролирует их готовность, связывает с объектами Cluster API и выполняет начальную инициализацию (bootstrap) узлов Kubernetes.

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

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

Обратите внимание! Провайдер shturval-capsm (Shturval v2 / manual) рассчитан на архитектуру x86_64. Перед развёртыванием убедитесь, что целевые узлы соответствуют поддерживаемой архитектуре.

Контроллеры и webhook #

Оператор регистрирует четыре контроллера и один mutating webhook:

Ограничения эксплуатации #

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

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

Параметры безопасности пода #

Под развёртывается в соответствии с политикой Pod Security Standards: restricted:

RBAC #

Оператор работает от имени ServiceAccount controller-manager, которому назначена ClusterRole manager-role через ClusterRoleBinding.

Дополнительно предусмотрены агрегированные роли для каждого CRD-вида с суффиксами -admin, -editor, -viewer.

Взаимодействие с внешними системами #

Оператор подключается по SSH к физическим узлам, адреса которых заданы в ShturvalProvider.spec.hosts. Для аутентификации используются Kubernetes Secrets, на которые ссылаются ShturvalProvider.spec.credentials.secretRef и, при необходимости, ShturvalHost.spec.credentials.ssh.

Secret типа Opaque с данными для подключения по SSH создается в кластере управления в неймспейсе shturval-capsm. Имя формируется из имени экземпляра провайдера Shturval v2 с суффиксом capsm-v2-provider-secret.

Пример Secret:

apiVersion: v1
kind: Secret
metadata:
  name: provider-name-capsm-v2-provider-secret
  namespace: shturval-capsm
type: Opaque
data:
  sshKey: LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0KdXNlcnNzaGtleQotLS0tLUVORCBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0=
  sshUser: c2h0dXJ2YWw=
  sshPassword: bXlwYXNzd29yZA==

Приватный ключ должен быть незашифрованным, без passphrase: парольная защита ключа не поддерживается.

3. Установка сервиса #

Провайдер CAPSM — инфраструктурный провайдер Cluster API (infrastructure.cluster.x-k8s.io). В платформе «Штурвал» подключение и жизненный цикл такого провайдера в управляющем кластере обеспечивает cluster-manager; объекты ShturvalServiceConfig (SSC) для чартов провайдера создаются и сопровождаются как часть платформенной конфигурации, а не как произвольная ручная установка сервисного чарта.

В рабочей среде провайдер представлен двумя SSC:

• shturval-capsm — основной чарт оператора;
• shturval-capsm-crds — чарт CRD модуля провайдера.

CRD-чарт выделяется в отдельный SSC, чтобы аннотация helm.sh/resource-policy: keep защищала CRD от удаления при обновлении основного чарта.

Для корректной работы в кластере управления должны быть доступны CRD основного Cluster API (shturval-capi-crds и связанный с ним компонент shturval-capi).

Ниже приведены имена чартов и соответствие spec.customvalues файлу helm/main/values.yaml основного чарта — для сопоставления с релизом и настройки через ShturvalServicePatch (SSP). Это не дублирует полный сценарий развёртывания через UI/API cluster-manager.

Если при развёртывании платформы работа сервиса была отключена, SSC провайдера могли получить режим отсутствия (mode: absent). Чтобы провайдер был доступен для работы с инфраструктурой Shturval v2, переведите сначала режим shturval-capsm-crds в auto, затем shturval-capsm в auto. Изменить режим можно в интерфейсе: на вкладке Платформа в карточке Провайдеры инфраструктуры нажмите Управлять, затем в блоке Сервисы провайдеров переведите переключатель.

На скриншоте показан выбор режима Авто для сервиса провайдера (см. скриншот ниже).

3.1 Параметры customvalues #

Структура значений основного чарта описывается полем spec.customvalues у соответствующего ShturvalServiceConfig и совпадает с helm/main/values.yaml чарта shturval-capsm. Полный список полей, задаваемых через этот файл:

Рекомендация: не правьте объект ShturvalServiceConfig вручную для смены лимитов, nodeSelector, образа оператора и прочих параметров релиза — такой объект относится к платформенной конфигурации и может быть перезаписан при обновлениях. Все изменения поведения сервиса вносите через ShturvalServicePatch (SSP), накладывающий spec.customvalues поверх базового SSC.

Webhook #

По умолчанию webhook ShturvalCluster включён. Для отключения установите переменную окружения ENABLE_WEBHOOKS=false в контейнере manager. Webhook требует TLS-сертификат; путь задаётся через --webhook-cert-path (см. раздел 6).

Создание ShturvalProvider #

ShturvalProvider — глобальный (cluster-scoped) объект-конфигурация провайдера. При создании ShturvalProvider контроллер автоматически создаёт объекты ShturvalHost для каждого адреса из spec.hosts. Объект должен существовать до создания кластеров и машин.

Пример минимального ShturvalProvider:

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: ShturvalProvider
metadata:
  name: shturval-demo
spec:
  systemRegistry: registry.example.com
  releaseVersion: "2.14"
  licenseToken: "<лицензионный токен>"
  credentials:
    secretRef:
      name: shturval-demo-provider-secret
      namespace: shturval-capsm
  hosts:
    - address: 192.168.1.10
      labels:
        role: worker
        zone: dc1
    - address: 192.168.1.11
      labels:
        role: master
        zone: dc1
  paused: false

Поле spec.releaseVersion задаёт версию платформы для bootstrap хостов (загрузка stc-<releaseVersion>). Чтобы на кластере управления 2.14.1 развернуть клиентский кластер более ранней версии, укажите полную версию, например releaseVersion: "2.13.1", до добавления хостов — см. Как создать клиентский кластер с провайдером Shturval v2 версии ниже 2.14.1.

После создания ShturvalProvider контроллер создаёт ShturvalHost с именем, равным IP-адресу хоста, и меткой provider_config_name: <имя провайдера>. Поля spec.systemRegistry, spec.releaseVersion и spec.licenseToken автоматически копируются в каждый ShturvalHost.

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

Где настраивать #

Сервисы и репозитории → Установленные сервисы → shturval-capsm → Управлять. Сервис размещается в кластере управления.

Чтобы включить сервис и настроить экземпляр: вкладка Платформа → карточка Провайдеры инфраструктуры → Управлять. Подробнее — Shturval v2. Общий обзор — Как устроена работа с провайдерами в платформе.

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

Проверка работоспособности оператора #

Диагностика ShturvalHost #

kubectl get shturvalhost
kubectl describe shturvalhost <имя-хоста>

Флаги в выводе kubectl get shturvalhost:

Conditions для ShturvalHost #

status.readyformachine = true выставляется, когда одновременно выполняются: CanConnectToTheNode=True, CheckSudo=True, ShturvalNodeConfigIsCorrect=True и хотя бы одно из: StcCompleted=True или StdDeployed=True.

Conditions для ShturvalMachine #

Conditions для ShturvalCluster #

Типичные сбои #

Просмотр информации об узле #

После успешного прохождения всех проверок оператор заполняет status.nodeInfo у ShturvalHost:

kubectl get shturvalhost <имя-хоста> -o jsonpath='{.status.nodeInfo}' | python -m json.tool

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

Контроллер ShturvalProvider #

Контроллер полностью управляет жизненным циклом объектов ShturvalHost на основе spec.hosts.

Создание хоста: при добавлении адреса в spec.hosts контроллер создаёт ShturvalHost с именем, равным IP-адресу, присваивает ему метки из spec.hosts[].labels, метку provider_config_name: <имя провайдера>, SSH-учётные данные и поля версии (systemRegistry, releaseVersion, licenseToken). Устанавливает OwnerReference провайдера на хост.

Обновление хоста: при изменении меток в spec.hosts[].labels контроллер синхронизирует их в ShturvalHost. Метки из списка системных (architecture, memory, cpu_cores, ethernet_interface, operating_system, root_volume_size, hostname, provider_config_name) не затрагиваются синхронизацией. Поля systemRegistry, releaseVersion, licenseToken синхронизируются всегда. Метки не обновляются, пока хост привязан к машине (MachineAttached=True).

Удаление хоста: при удалении адреса из spec.hosts контроллер запускает удаление соответствующего ShturvalHost. Ожидает завершения очистки финалайзеров.

Удаление провайдера: провайдер может быть удалён только если ни один из его хостов не привязан к кластеру (нет MachineAttached=True). При удалении оператор снимает финалайзер shturval/<имя-провайдера> с Secret-а с учётными данными.

Credentials для хоста: если в spec.hosts[].credentials заданы индивидуальные учётные данные для хоста, они используются вместо глобальных spec.credentials.

Контроллер ShturvalHost #

Контроллер подготавливает физический узел к вступлению в кластер Kubernetes.

Финалайзер #

При первом обнаружении нового ShturvalHost контроллер добавляет финалайзер shturvalhost.infrastructure.cluster.x-k8s.io и завершает итерацию с requeue через 1 секунду.

Подготовка нового хоста #

1. SSH-подключение — устанавливает соединение по spec.address. При сетевой ошибке — CanConnectToTheNode=False, requeue 1 с.
2. Проверка sudo (однократно, пока CheckSudo не True) — при ошибке CheckSudo=False.
3. Развёртывание демона shturvald (однократно, пока StdDeployed или StcCompleted не True) — вызов EnsureSTDDeployed().
4. Получение информации об узле — через shturvald запрашиваются метаданные (архитектура, hostname, память, CPU, machine-id, статус Kubernetes). Если демон удалён вручную, StdDeployed сбрасывается.
5. Проверка занятости — если на узле активен сервис Kubernetes или присутствует kubeconfig, выставляется ShturvalNodeConfigIsCorrect=False (HostOccupied).
6. Уникальность machine-id — оператор ведёт in-memory карту machine-id (инициализируется при старте по всем существующим хостам). При дубликате вызывается ResetMachineID(), итерация перезапускается.
7. Итог — при прохождении всех шагов выставляются ShturvalNodeConfigIsCorrect=True и MachineIDUnique=True; status.readyformachine становится true.

Условие готовности IsReadyForMachine #

Хост считается готовым к привязке машины (readyformachine=true) при одновременном выполнении:

• CanConnectToTheNode=True
• StcCompleted=True ИЛИ StdDeployed=True

Привязка машины #

Когда readyformachine=true, контроллер ищет ShturvalMachine с status.selectedhost == host.name. Из найденных кандидатов выбирается один по приоритету:

приоритет = 10 × len(matchExpressions) + 1 × len(matchLabels)

При одинаковом приоритете выбирается машина с лексикографически меньшим именем. Машины в состоянии удаления пропускаются. После выбора устанавливается status.linkedmachine и MachineAttached=True.

Консистентность привязки #

Пока хост привязан (machineAttachedAndConfirmed=true), каждая итерация проверяет существование ShturvalMachine из status.linkedmachine и то, что машина не удаляется. При несоответствии привязка сбрасывается.

Триггеры reconcile #

Удаление #

При deletionTimestamp != nil контроллер отвязывает связанную машину, очищает служебное состояние хоста и снимает финалайзер shturvalhost.infrastructure.cluster.x-k8s.io.

Контроллер ShturvalMachine #

Контроллер выбирает хост и выполняет bootstrap Kubernetes-узла.

Выбор хоста: если status.selectedhost пуст, контроллер ищет свободный (не занятый) ShturvalHost по метке provider_config_name (берётся из spec.providerConfigName машины или из ShturvalCluster.spec.providerConfigName). Дополнительно применяется spec.hostSelector. Если хост найден, но не готов (readyformachine=false) — ожидание. Если хост готов, но не подтвердил выбор — ожидание подтверждения от ShturvalHost.

Проверка статуса установки компонентов: выполняется команда sudo std node status. При статусе synched переходит к bootstrap. При syncInProgress или waitingRebootApprove — ожидание (requeue через 1 минуту). При syncFailed — фиксируется ошибка, reconcile прекращается.

Bootstrap (версия ≥ 2.14): вызывается node.PreBootstrapWithCloudInit(). Если shturvald требует перезапуска — перезапуск и requeue. Затем node.BootstrapWithCloudInit() с данными из bootstrap-секрета CAPI.

Bootstrap (версия < 2.14): удаляется /etc/std/nci.json, перезапускается shturvald, ожидается synched, затем выполняется BootstrapWithCloudInit.

Установка providerID: после успешного bootstrap контроллер подключается к целевому кластеру, находит Kubernetes-узел с совпадающим machine-id и устанавливает spec.providerID в формате shturval://xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Удаление: при наличии deletionTimestamp контроллер вызывает node.Reset() на узле для его очистки. Если IgnoreResetError=true — ошибки сброса игнорируются и удаление продолжается. После успешной очистки снимается финалайзер.

Триггер reconcile: изменение статуса ShturvalHost (обновление или удаление) ставит в очередь все связанные машины.

Контроллер ShturvalCluster #

reconcileNormal: добавляет финалайзер shturvalcluster.infrastructure.cluster.x-k8s.io, устанавливает status.ready=true и condition ShturvalClusterReconciliationReady=True. Если CAPI-кластер поставил кластер на паузу — выставляет Ready=false.

reconcileDelete: ожидает удаления всех ShturvalMachine с меткой cluster.x-k8s.io/cluster-name: <имя кластера>. Пока машины существуют — requeue каждые 5 секунд. После удаления всех машин снимает финалайзер.

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

Параметры задаются через аргументы запуска контейнера manager. Для изменения используйте механизм кастомизации через cluster-manager или ShturvalServicePatch.

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

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

Все ресурсы принадлежат API-группе infrastructure.cluster.x-k8s.io, версия v1beta1.

ShturvalHost #

Cluster-scoped объект, представляющий физический SSH-узел. Создаётся и управляется контроллером ShturvalProvider.

Короткое имя: smh
Scope: Cluster
Финалайзер: shturvalhost.infrastructure.cluster.x-k8s.io

spec #

status #

ShturvalProvider #

Cluster-scoped объект глобальной конфигурации провайдера: список хостов, реестр образов, версия Штурвала, лицензия, SSH-учётные данные по умолчанию. Является источником истины для всех ShturvalHost.

Короткое имя: smp
Scope: Cluster
Финалайзер: shturvalprovider.infrastructure.cluster.x-k8s.io

spec #

status #

ShturvalCluster #

Namespaced объект кластера Kubernetes в терминах Cluster API.

Короткое имя: smc
Scope: Namespace
Финалайзер: shturvalcluster.infrastructure.cluster.x-k8s.io

spec #

status #

ShturvalMachine #

Namespaced объект, представляющий узел кластера в терминах Cluster API.

Короткое имя: smm
Scope: Namespace
Финалайзер: shturvalmachine.infrastructure.cluster.x-k8s.io

spec #

status #

ShturvalMachineTemplate #

Namespaced шаблон для ShturvalMachine. Используется CAPI при автоматическом создании объектов ShturvalMachine в рамках MachineDeployment или MachineSet.

Короткое имя: smt
Scope: Namespace

spec #