Провайдер oVirt (shturval-capov)

О сервисе #

CAPOV (Cluster API Provider for oVirt) — инфраструктурный провайдер Cluster API для платформы виртуализации oVirt (Red Hat Virtualization). Оператор запускается в управляющем кластере Kubernetes и автоматизирует создание, настройку и удаление виртуальных машин в oVirt при развёртывании рабочих кластеров средствами CAPI.

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

Содержание #

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

1. Обзор #

CAPOV реализует контракт Cluster API для инфраструктурного провайдера: получает запросы от CAPI-контроллеров и выполняет необходимые операции в oVirt через его REST API.

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

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

• Группа API: infrastructure.cluster.x-k8s.io/v1beta1
• Namespace оператора: capov-system
• Параллельная обработка: до 10 одновременных reconcile для OVirtMachine
• Leader election включён: безопасная работа при нескольких репликах
• Метрики: HTTPS на порту :8443; health/readiness: HTTP на :8081

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

Компоненты #

Связи CR и ресурсов #

Два контроллера #

Порты пода #

Метрики и ServiceMonitor #

• Service capov-metrics-service в namespace оператора экспонирует порт 8443 (https) на под с меткой control-plane: controller-manager.
• При наличии в кластере CRD Prometheus Operator (monitoring.coreos.com/v1) чарт создаёт ServiceMonitor capov-metrics-monitor: scrape пути /metrics по HTTPS с токеном service account (метка release: shturval-metrics — согласуйте с вашим Prometheus-стеком).

Флаги запуска (из Helm-чарта) #

Чарт задаёт только часть аргументов; остальные — значения по умолчанию бинарника main.go:

/manager
  --metrics-bind-address=:8443
  --leader-elect
  [--feature-gates=disk-keep-template-name=true,...]

Дополнительные флаги не выставляются Helm-шаблоном, но поддерживаются при ручной отладке:

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

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

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

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

Если при развёртывании платформы работа сервиса была отключена, SSC провайдера могли получить режим отсутствия (mode: absent). Чтобы провайдер был доступен для работы с виртуализацией (zVirt, oVirt, HostVM, РЕД Виртуализация, ROSA Virtualization и т.п.), переведите сначала режим shturval-capov-crds в auto, затем shturval-capov в auto. Изменить режим можно в интерфейсе: на вкладке Платформа в карточке Провайдеры инфраструктуры нажмите Управлять, затем в блоке Сервисы провайдеров переведите переключатель.

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

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

Структура значений чарта описывается полем spec.customvalues у ShturvalServiceConfig и совпадает с helm/main/values.yaml. Полный список поддерживаемых параметров:

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

Affinity по умолчанию #

Чарт настраивает мягкое предпочтение (preferredDuringSchedulingIgnoredDuringExecution): поды оператора предпочтительно планируются на ноды с ролью infra. При отсутствии таких нод под может быть запланирован на любую рабочую ноду, в том числе control-plane.

Пример кастомизации через SSP (ресурсы и nodeSelector) #

apiVersion: ops.shturval.tech/v1beta2
kind: ShturvalServicePatch
metadata:
  name: shturval-capov-resources
  labels:
    ops.shturval.tech/ssc: shturval-capov
spec:
  shturvalServiceConfigName: shturval-capov
  customvalues:
    manager:
      tag: "2.14.0"
    resources:
      limits:
        cpu: 1000m
        memory: 256Mi
      requests:
        cpu: 50m
        memory: 128Mi
    nodeSelector:
      node-role.kubernetes.io/infra: ""

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

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

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

4. Диагностика и устранение неполадок #

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

# Статус пода
kubectl get pods -n capov-system
kubectl describe pod -n capov-system -l control-plane=controller-manager

# Логи оператора (последние 100 строк)
kubectl logs -n capov-system deployment/capov-controller-manager --tail=100

# Логи в режиме follow
kubectl logs -n capov-system deployment/capov-controller-manager -f

# Включить debug-логирование (через переопределение args)
# Добавить в deployment args: --debug=true

# Сервис метрик (если нужен доступ к /metrics вручную)
kubectl get svc -n capov-system capov-metrics-service

# ServiceMonitor (при установленном Prometheus Operator)
kubectl get servicemonitor -n capov-system 2>/dev/null || true

4.2 Проверка ресурсов #

# Все OVirtProvider и их статус
kubectl get capovp
# NAME          READY
# ovirt-prod    true

# Все OVirtCluster во всех namespace
kubectl get capovc -A

# Все OVirtMachine во всех namespace
kubectl get capovm -A
# NAMESPACE   NAME             READY
# default     worker-abc123    true
# default     worker-def456    false

# Подробная информация о машине
kubectl describe capovm worker-def456 -n default

4.3 Машина зависла в состоянии “не Ready” #

Первый шаг: получить условия машины.

kubectl get capovm worker-def456 -n default \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

Условие CanConnectToOVirt = False

Оператор не может подключиться к oVirt. Причины:

• Неверный URL в spec.engine объекта OVirtProvider
• Неверные учётные данные (spec.user / spec.pass)
• Проблемы с TLS (неверный сертификат, попробуйте spec.tls.insecure: true для диагностики)
• Сетевые проблемы между подом оператора и oVirt Engine

# Проверить OVirtProvider
kubectl get capovp ovirt-prod -o yaml

# Проверить сеть из пода оператора
kubectl exec -n capov-system deployment/capov-controller-manager -- \
  wget -qO- https://ovirt.example.com/ovirt-engine/api --no-check-certificate

Если status.failureReason = OVirtEngineConnectionCritical — требуется исправить OVirtProvider и сбросить FailureReason (удалить поле через patch или пересоздать OVirtMachine):

kubectl patch capovm worker-def456 -n default \
  --type=merge \
  -p '{"status":{"failureReason":null,"failureMessage":null}}'

Условие MachineCreated = False

ВМ не создана в oVirt:

• Шаблон spec.template не существует в oVirt
• Кластер oVirt spec.ovirtcluster не найден
• Указан spec.storagedomainname, но домен хранения с таким именем в oVirt отсутствует или недоступен для размещения дисков
• Bootstrap Secret ещё не готов (нормально в начале создания, оператор повторит попытку)

Условие MachineDiskResized = False

• Запрошенный размер диска osdisksizegb меньше, чем размер диска в шаблоне — уменьшить нельзя

Условие MachineNetworkSet = False

• vNIC Profile с именем из spec.nics[].vnicprofile не найден в oVirt

Условие K8sProviderIDSetup = False

• ВМ ещё не зарегистрировалась в рабочем кластере как Node
• Проблемы с доступом оператора к API рабочего кластера

4.4 Машина не удаляется #

kubectl describe capovm worker-def456 -n default | grep -A5 "Conditions"

Если MachineDeleted = False с причиной VMHasNonSystemDisk:

message: VM has non system disk, cannot delete

Это означает, что к ВМ подключён CSI-диск, который ещё не отсоединён. Оператор будет повторять попытку каждую минуту. Решение: убедиться, что PVC/PV освобождены перед удалением Node.

Если CSI завис, диск можно отсоединить вручную в интерфейсе oVirt — оператор удалит ВМ на следующей итерации.

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

5.1 Создание #

Контроллер OVirtMachineReconciler выполняет шаги последовательно. Если шаг завершается ошибкой, объект попадает в очередь повтора. Прогресс каждого шага отражается в status.conditions.

Домен хранения для дисков новой ВМ задаётся опциональным полем spec.storagedomainname. Если оно не указано, диски создаются в том же домене хранения, что и диски шаблона в oVirt (см. §7.3).

5.2 Удаление #

При наличии deletionTimestamp контроллер переходит в ветку Deleting на схеме: выключает ВМ, удаляет её в oVirt и снимает finalizer. Если к ВМ подключён не системный (CSI) диск, удаление блокируется до его отсоединения (см. §4.4).

5.3 Состояния (Conditions) #

Просмотр условий:

kubectl get capovm worker-abc123 -n default \
  -o jsonpath='{.status.conditions}' | jq .

Пример вывода для машины в промежуточном состоянии (запускается):

[
  {"type": "CanConnectToOVirt", "status": "True"},
  {"type": "MachineCreated",    "status": "True"},
  {"type": "MachineDiskResized","status": "True"},
  {"type": "MachineNetworkSet", "status": "True"},
  {"type": "MachineOn",         "status": "False",
   "reason": "VMPoweringUp",    "severity": "Info",
   "message": "powering up"},
  {"type": "K8sProviderIDSetup","status": "False"}
]

5.4 Критические ошибки (FailureReason) #

Если оператор встречает ошибку, после которой автоматический retry невозможен или бессмысленен, он выставляет status.failureReason и status.failureMessage.

6. Параметры оператора (Feature Gates) #

Feature gates — флаги, изменяющие поведение оператора при работе с дисками ВМ. Передаются через аргумент --feature-gates (Helm: values.featureGates). В среде Штурвал задаются в customvalues.featureGates через SSP; редактировать SSC для этой цели не рекомендуется. Общий порядок работы с SSP — Как управлять CustomValues сервисов.

Формат #

--feature-gates=disk-keep-template-name=true,disk-add-vm-name=false

Неизвестные ключи и некорректные значения молча игнорируются.

Доступные gates #

Настройка через SSP (рекомендуется) #

Создайте или измените ShturvalServicePatch, связанный с shturval-capov (см. Как управлять CustomValues сервисов):

apiVersion: ops.shturval.tech/v1beta2
kind: ShturvalServicePatch
metadata:
  name: shturval-capov-featuregates
  labels:
    ops.shturval.tech/ssc: shturval-capov
spec:
  shturvalServiceConfigName: shturval-capov
  customvalues:
    featureGates:
      disk-add-vm-name: true
      disk-clone: false

SSP накладывается поверх SSC.spec.customvalues. После применения или изменения патча оператор платформы обновляет Deployment — под пересоздаётся автоматически.

Перемещение диска в Storage Domain #

Если вы задали имя домена хранения (Storage Domain) в oVirt провайдере или в InfraMachineTemplate, где будут создаваться диски виртуальных машин, потребуется включить клонирование дисков.

Примените в кластере управления ShturvalServicePatch:

apiVersion: ops.shturval.tech/v1beta2
kind: ShturvalServicePatch
metadata:
  name: shturval-capov-disk-clone
  labels:
    ops.shturval.tech/ssc: shturval-capov
spec:
  shturvalServiceConfigName: shturval-capov
  customvalues:
    featureGates:
      disk-clone: true

После применения патча дождитесь обновления сервиса shturval-capov и повторите создание или восстановление узлов.

Зачем нужно переименование дисков #

Когда CAPI создаёт несколько ВМ из одного шаблона, oVirt наследует алиасы дисков непосредственно из шаблона. В результате все диски всех созданных ВМ получают одинаковые алиасы — те же, что были у дисков шаблона.

Проблема становится очевидной в разделе Storage → Disks (Хранилище → Диски): это глобальный каталог всех дисков дата-центра. В нём невозможно по имени определить, какому узлу кластера принадлежит тот или иной диск — все записи выглядят одинаково. Установка disk-add-vm-name: true устраняет проблему: имя ВМ добавляется к алиасу, алиас становится уникальным и однозначно указывает на ВМ-владельца.

Где виден алиас диска в oVirt #

Алиас — это отображаемое имя объекта Disk в oVirt. Он виден в двух местах:

• Storage → Disks — глобальный список всех дисков дата-центра. Именно здесь одинаковые алиасы создают путаницу при большом числе узлов.
• Compute → Virtual Machines → [ВМ] → вкладка Disks — список дисков, подключённых к конкретной ВМ.

Имена дисков: поведение по комбинациям флагов #

Во всех примерах ниже: имя ВМ — worker-abc123, шаблон — rhcos-4.14.

disk-keep-template-name: true, disk-add-vm-name: false (значения по умолчанию)

Переименование не выполняется. Оператор не трогает алиасы — они остаются такими, какими их назначил oVirt при создании ВМ из шаблона.

disk-keep-template-name: true, disk-add-vm-name: true

Имя ВМ вставляется перед суффиксом _Disk…. Шаблонная часть алиаса сохраняется.

disk-keep-template-name: false, disk-add-vm-name: true

Шаблонная часть алиаса удаляется. Алиас строится только из имени ВМ и суффикса _Disk…. Если имя ВМ уже присутствует в алиасе, переименование не выполняется.

Поведение при disk-clone: true #

При создании ВМ значение feature gate disk-clone передаётся в запрос добавления ВМ в oVirt как параметр Clone: при disk-clone: true — Clone(true), при disk-clone: false — Clone(false). В коде оператора нет иной логики, завязанной на этот флаг, кроме передачи булева значения в этот вызов.

Проверить текущие feature gates в логах при запуске пода:

kubectl logs -n capov-system deployment/capov-controller-manager | grep "feature gates"

7. CRD: Справочник ресурсов #

7.1 OVirtProvider #

Область: cluster-scoped (без namespace) Short name: capovp Группа: infrastructure.cluster.x-k8s.io/v1beta1

Хранит параметры подключения к oVirt Engine. Один объект может использоваться несколькими машинами из разных namespace’ов.

Поля спецификации #

Статус #

Примеры #

Вариант 1: Отключить проверку TLS (dev/test)

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OVirtProvider
metadata:
  name: ovirt-dev
spec:
  engine: "https://ovirt-dev.example.com/ovirt-engine/api"
  user: "admin@internal"
  pass: "changeme"
  tls:
    insecure: true

Вариант 2: Системные CA (публичный сертификат)

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OVirtProvider
metadata:
  name: ovirt-prod
spec:
  engine: "https://ovirt.example.com/ovirt-engine/api"
  user: "admin@internal"
  pass: "s3cr3t"
  tls:
    insecure: false
    cert: true

Вариант 3: Собственный CA-сертификат

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OVirtProvider
metadata:
  name: ovirt-internal
spec:
  engine: "https://ovirt.internal/ovirt-engine/api"
  user: "admin@internal"
  pass: "s3cr3t"
  tls:
    insecure: false
    certs: LS0tLS1CRUdJTi...  # base64-encoded PEM

Проверить статус подключения:

kubectl get capovp
# NAME             READY
# ovirt-prod       true

7.2 OVirtCluster #

Область: namespaced Short name: capovc Группа: infrastructure.cluster.x-k8s.io/v1beta1

Представляет инфраструктурный кластер в oVirt. Создаётся как часть CAPI-кластера: объект Cluster ссылается на OVirtCluster через поле spec.infrastructureRef.

Поля спецификации #

Статус #

Пример #

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OVirtCluster
metadata:
  name: my-cluster
  namespace: default
spec:
  controlPlaneEndpoint:
    host: "10.0.1.100"   # VIP или адрес балансировщика control-plane
    port: 6443

Поведение контроллера:

• При создании: добавляет finalizer capovmachine.infrastructure.cluster.x-k8s.io, выставляет status.ready = true.
• При удалении: снимает finalizer — объект удаляется из etcd.
• Если объект Cluster поставлен на паузу (spec.paused: true), reconcile пропускается. (см. скриншот ниже)

Проверить состояние:

kubectl get capovc -n default
# NAME         CONTROLPLANE ENDPOINT   READY
# my-cluster   10.0.1.100              true

7.3 OVirtMachine #

Область: namespaced Short name: capovm Группа: infrastructure.cluster.x-k8s.io/v1beta1

Представляет одну виртуальную машину в oVirt. Создаётся автоматически CAPI-контроллером на основе OVirtMachineTemplate при масштабировании MachineDeployment или KubeadmControlPlane. Прямое создание OVirtMachine администратором не является типовым сценарием.

Поля спецификации #

Статус #

Пример #

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OVirtMachine
metadata:
  name: worker-abc123
  namespace: default
spec:
  provider: ovirt-prod          # имя OVirtProvider
  ovirtcluster: "Default"       # имя кластера в oVirt (Default — стандартный)
  template: "rhcos-4.14"        # шаблон ВМ в oVirt
  # storagedomainname: "my-datastore"  # опционально: иной домен хранения для дисков, чем у шаблона
  vmtype: server
  cpu:
    sockets: 1
    cores: 4
    threads: 1
  memory:
    sizemb: 8192
    guaranteedmb: 4096
  osdisksizegb: 80
  nics:
    - vnicprofile: "ovirtmgmt"  # имя vNIC Profile в oVirt

Проверить состояние машины:

kubectl get capovm -n default
# NAME            READY
# worker-abc123   true

kubectl describe capovm worker-abc123 -n default

7.4 OVirtMachineTemplate #

Область: namespaced Группа: infrastructure.cluster.x-k8s.io/v1beta1

Шаблон конфигурации для OVirtMachine. Используется объектами MachineDeployment и KubeadmControlPlane как spec.template.spec.infrastructureRef. CAPOV-контроллер не управляет этим ресурсом напрямую — он только читает его при необходимости.

Структура #

OVirtMachineTemplate.spec.template
  ├── metadata (опционально) — стандартные `labels` и `annotations` узла (контракт CAPI MachineTemplate; наследуются на `Machine` и далее на Node по правилам CAPI)
  └── spec — все поля `OVirtMachine.spec`, кроме `providerID` (его выставляет контроллер на созданной машине)

Поле spec.template.spec соответствует схеме OVirtMachine (включая storagedomainname, cpu, memory, nics и т.д.).

Пример #

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OVirtMachineTemplate
metadata:
  name: worker-template
  namespace: default
spec:
  template:
    # metadata:
    #   labels:
    #     node.kubernetes.io/instance-type: "standard"
    spec:
      provider: ovirt-prod
      ovirtcluster: "Default"
      template: "rhcos-4.14"
      # storagedomainname: "my-datastore"
      vmtype: server
      cpu:
        sockets: 1
        cores: 4
        threads: 1
      memory:
        sizemb: 8192
        guaranteedmb: 4096
      osdisksizegb: 80
      nics:
        - vnicprofile: "ovirtmgmt"

Изменение OVirtMachineTemplate не влияет на уже созданные машины. Для применения изменений необходимо обновить ссылку в MachineDeployment (rolling update).