Построение собственного KaaS на Proxmox с помощью Cluster API

Построение собственного KaaS на Proxmox с помощью Cluster API

В условиях импортозамещения и роста требований к защите данных многие инженеры и DevOps-команды выбирают гипервизор Proxmox VE как доступную платформу виртуализации. Однако классическое создание и обслуживание виртуальных машин вручную или через традиционные скрипты автоматизации быстро перестает успевать за потребностями продуктовых команд. Для решения этой проблемы под эгидой Kubernetes развивается проект Cluster API (CAPI) — декларативный подход к управлению полным жизненным циклом Kubernetes-кластеров. В сочетании с инфраструктурным провайдером CAPMOX (Cluster API Provider Proxmox) эта технология позволяет превратить гипервизор Proxmox в сервисный KaaS, где создание, масштабирование, ротация и обновление кластеров происходят через привычные манифесты и вызовы API.

Архитектура и основные понятия Cluster API

Главная идея Cluster API заключается в переносе принципов декларативного управления Kubernetes на саму виртуальную инфраструктуру. Кластеры и их узлы становятся первыми гражданами системы, описанными через Custom Resource Definitions (CRD).

Архитектура CAPI разделена на две сущности:

1. Управляющий кластер (Management Cluster): базовый кластер Kubernetes (запущенный в виде Kind или K3s на отдельной виртуальной машине), где развернуты контроллеры CAPI и CAPMOX. Он хранит манифесты и поддерживает целевое состояние всех рабочих окружений.
2. Рабочие кластеры (Workload Clusters): целевые кластеры Kubernetes, на которых выполняются пользовательские приложения.

Управление осуществляется через три типа подключаемых провайдеров:

• Infrastructure Provider (CAPMOX): взаимодействует с API Proxmox VE, создавая, настраивая и удаляя виртуальные машины, диски и сетевые интерфейсы.
• Bootstrap Provider (Kubeadm): готовит свежесозданную виртуальную машину к превращению в узел Kubernetes, генерируя сертификаты и выполняя инициализацию kubeadm init или подключение kubeadm join.
• ControlPlane Provider (KubeadmControlPlane): отвечает за жизненный цикл управляющих узлов (Control Plane), гарантируя высокую доступность и безопасное обновление компонентов API-сервера.

Декларативное описание использует ресурсы: Cluster (верхнеуровневый объект кластера), Machine (конкретная виртуальная машина), MachineSet (поддержание заданного количества узлов) и MachineDeployment (бесшовное стратегическое обновление узлов по аналогии с подами). При возникновении сбоя контроллер MachineHealthCheck автоматически обнаруживает неисправный узел и инициирует его пересоздание через Proxmox.

Подготовка Proxmox: права и учетные записи

Перед сборкой образов и запуском контроллеров необходимо подготовить учетные записи и ограниченные API-токены в гипервизоре Proxmox VE. Сборщику образов и инфраструктурному провайдеру требуются изолированные права доступа.

На любом узле Proxmox VE выполняются следующие команды создания пользователей и токенов:

# Создание пользователя и привилегий для сборщика образов image-builder
pveum user add image-builder@pve
pveum aclmod / -user image-builder@pve -role PVEAdmin
pveum user token add image-builder@pve capi -privsep 0

# Создание пользователя и привилегий для контроллера CAPMOX
pveum user add capmox@pve
pveum aclmod / -user capmox@pve -role PVEAdmin
pveum user token add capmox@pve capi -privsep 0

Использование флага -privsep 0 отключает дополнительное разделение привилегий для токена, позволяя ему наследовать полные права учетной записи в рамках роли PVEAdmin. Сгенерированные секретные ключи токенов необходимо сохранить в защищенное хранилище.

Сборка базовых образов узлов через image-builder

Проект image-builder стандартизирует создание золотых образов виртуальных машин, преконфигурированных под требования Kubernetes. Вместо ручной установки зависимостей используются декларативные рецепты на базе Packer и Ansible, запекающие в образ ядро Linux, контейнерный рантайм (containerd), бинарные файлы kubeadm/kubelet, сетевые утилиты и настройки безопасности.

Порядок подготовки базового образа:

# 1. Клонирование официального репозитория
git clone [email protected]:kubernetes-sigs/image-builder.git
cd image-builder/images/capi

# 2. Установка зависимостей сборки
make deps
export PATH=$PWD/.bin:$PATH

Далее создается файл конфигурации окружения image-builder/images/capi/packer/proxmox/.env:

export PROXMOX_URL="https://<PROXMOX_NODE_IP>:8006/api2/json"
export PROXMOX_USERNAME="image-builder@pve!capi"
export PROXMOX_TOKEN="<IMAGE_BUILD_API_TOKEN>"
export PROXMOX_NODE="<PROXMOX_NODE_NAME>"
export PROXMOX_ISO_POOL="local"
export PROXMOX_STORAGE_POOL="local-lvm"
export DISK_FORMAT="raw"
export PROXMOX_BRIDGE="vmbr0"
export PROXMOX_NIC_MODEL="virtio"
export PACKER_FLAGS="--var memory=2048 --var 'kubernetes_semver=v1.32.5'"

Критическое правило выбора формата хранилища:

• Если Proxmox развернут в виде одиночного узла и использует тонкое LVM-хранилище local-lvm, параметр PROXMOX_STORAGE_POOL задается как local-lvm, а DISK_FORMAT обязан иметь значение raw, поскольку local-lvm LVM-thin хранилище не принимает формат qcow2.
• В случае многоузлового кластера Proxmox с общим сетевым хранилищем (NFS или Ceph) параметр PROXMOX_STORAGE_POOL указывается на имя общего хранилища, а DISK_FORMAT устанавливается в qcow2.

Сборка запускается командой source packer/proxmox/.env && make build-proxmox-ubuntu-2204. В консоли Proxmox создается виртуальная машина, устанавливаются пакеты и выполняется автоматическая конвертация в шаблон VM.

Настройка управляющего кластера и провайдера CAPMOX

Для управления рабочими кластерами разворачивается управляющий кластер (Management Cluster). В качестве локального окружения подходит Kind. На рабочей станции создается конфигурационный файл capmox.env с параметрами доступа к Proxmox и настройками сети:

export PROXMOX_URL="https://<PROXMOX_NODE_IP>:8006"
export PROXMOX_TOKEN="capmox@pve!capi"
export PROXMOX_SECRET="<CAPMOX_API_TOKEN_SECRET>"
export PROXMOX_SOURCENODE="<PROXMOX_NODE_NAME>"
export TEMPLATE_VMID="<BASE_IMAGE_TEMPLATE_ID>"
export ALLOWED_NODES="[<PROXMOX_NODE1>,<PROXMOX_NODE2>]"
export VM_SSH_KEYS="ssh-rsa AAAAB3..."
export CONTROL_PLANE_ENDPOINT_IP="192.168.1.230"
export NODE_IP_RANGES="[192.168.1.220-192.168.1.229]"
export GATEWAY="192.168.1.1"
export IP_PREFIX="24"
export DNS_SERVERS="[192.168.1.1]"
export BRIDGE="vmbr0"
export NETWORK_MODEL="virtio"

Инициализация управляющего кластера выполняется командами:

kind create cluster --name=mgmt-capmox
source capmox.env
clusterctl init --infrastructure proxmox --ipam in-cluster

Декларативный запуск рабочего кластера и CNI

Генерация манифеста рабочего кластера осуществляется командой:

source capmox.env
clusterctl generate cluster capi-quickstart   --kubernetes-version v1.33.0   --control-plane-machine-count=1   --worker-machine-count=1 > capi-quickstart.yaml

Перед применением созданного файла capi-quickstart.yaml необходимо внести две обязательные правки:

1. Разграничение подсетей CIDR: значение cidrBlocks в объекте Cluster изменяется на подсеть, не пересекающуюся с физическим мостом vmbr0 (например, 10.44.0.0/16), во избежание конфликтов IP-адресов подов.
2. Разрешение оверкоммита памяти в Proxmox: контроллер CAPMOX перед запуском виртуальной машины суммирует выделенную память. Чтобы узлы не зависали при высоком выделении RAM, в спецификацию ProxmoxCluster добавляется параметр:

spec:
  schedulerHints:
    memoryAdjustment: 0

Развертывание рабочего кластера и установка сетевого плагина Calico CNI:

# Запуск создания кластера в Proxmox
kubectl apply -f capi-quickstart.yaml

# Экспорт файла kubeconfig созданного кластера
clusterctl get kubeconfig capi-quickstart > capi-quickstart.kubeconfig

# Развертывание плагина Calico CNI
kubectl --kubeconfig=./capi-quickstart.kubeconfig   apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml

Проверка результатов и рекомендации по безопасности

После завершения инициализации контроллер Proxmox склонирует шаблоны виртуальных машин, поднимет узлы, установит сетевой плагин и переведет кластер в статус Ready. Проверить состояние ресурсов можно командами kubectl get cluster и kubectl get machines.

Меры безопасности:

• Файлы .env и capmox.env, содержащие секретные токены Proxmox, необходимо добавить в .gitignore.
• Использование CAPI и CAPMOX позволяет построить полностью прозрачную платформу KaaS, где управление инфраструктурой сведено к работе с GitOps-репозиторием.