Настройка HA-кластера Kubernetes: несколько control plane, HAProxy и VIP | AdminWiki

Настройка HA-кластера Kubernetes: несколько control plane, HAProxy и VIP

18 ноября 2026 15 мин. чтения

Отказоустойчивый control plane Kubernetes держится на трёх вещах: несколько узлов с kube-apiserver, общий endpoint, на который смотрят kubelet и kubectl, и etcd с рабочим кворумом. Падение одного узла при такой схеме не останавливает управление кластером: балансировщик выкидывает недоступный backend, остальные API-серверы продолжают принимать запросы.

Рабочий минимум для продакшена: 3 узла control plane, HAProxy перед ними на порту 6443 и VIP через keepalived либо внешний балансировщик от облака. etcd работает на тех же трёх узлах (stacked) или выносится на отдельный кластер (external). Кворум из 3 участников переживает отказ одного, из 5 - отказ двух.

HA закрывает отказ узла и обслуживание control plane по одному. Резервное копирование etcd она не заменяет: снапшот снимают перед любыми изменениями сертификатов, сети и состава узлов.

Что даёт HA control plane и когда он нужен

Один control plane - это единая точка отказа для управления. Узел ушёл в ребут или завис kubelet, и вы не создаёте поды, не меняете Deployment, не читаете состояние кластера. Поды на worker-узлах при этом продолжают работать, но управлять ими нечем. Второй сценарий не менее частый: плановое обслуживание, обновление минорной версии, замена диска. На одиночном узле любая такая работа означает простой управления.

Из чего состоит отказоустойчивый control plane

Компоненты распределены по узлам, и каждый решает свою задачу:

  • kube-apiserver - единственная точка входа в кластер. Через него работают kubectl, kubelet, controller-manager, scheduler и все контроллеры. Слушает 6443/TCP на каждом узле control plane.
  • etcd - хранилище всего состояния кластера: объектов API, секретов, конфигураций. Источник истины, без которого API-сервер бесполезен.
  • kube-controller-manager и kube-scheduler работают в режиме leader election: активен один экземпляр, остальные ждут и перехватывают лидерство при отказе. Лидерство видно по объектам Lease в namespace kube-system.
  • Балансировщик стоит перед kube-apiserver:6443 и раздаёт трафик на живые узлы. Без него общий endpoint не собрать.

kubelet и kubectl обращаются не к IP конкретного узла, а к общему адресу: VIP или DNS-имени. Этот адрес задаётся в controlPlaneEndpoint и попадает в сертификат API-сервера и в kubeconfig. Подробнее о связях между компонентами и о том, как запрос проходит от манифеста до запуска контейнера, разбираем в материале про архитектуру Kubernetes по слоям.

Один control plane или несколько: критерий выбора

Решение принимают по цене простоя управления, а не по размеру кластера. Три тысячи подов на двух worker-узлах не требуют пяти control plane, а кластер с еженедельными релизами требует минимум трёх.

СценарийControl planeetcdЧто получаете
Лаба, обучение, стенд для проверки манифестов1stackedПростой управления при любом отказе узла
Внутренний сервис без требований к доступности управления1stackedПростая эксплуатация, снапшоты etcd обязательны
Прод, где управление должно переживать отказ узла3stacked или externalОтказ одного узла без остановки API
Крупная инсталляция, частые изменения, много операторов5externalОтказ двух узлов, больше etcd-трафика и требований к сети

Два control plane кворум не усиливают: для большинства из двух нужны оба узла, отказ любого останавливает запись в etcd. Берите 1, 3 или 5. Конкретные проценты доступности не приводим: они зависят от инфраструктуры, а не от схемы. Общие принципы проектирования без единой точки отказа, включая мультизональное размещение, собраны в гайде про отказоустойчивый кластер Kubernetes.

Stacked etcd или внешний etcd: что выбрать

В stacked-схеме etcd запускается статическими подами на тех же узлах, что и kube-apiserver. Плюсы: меньше машин, один сертификат infra-слоя, проще bootstrap через kubeadm. Минус: отказ узла бьёт одновременно по API и по etcd, а нагрузка на диск конкурирует с остальными компонентами.

Во external-схеме etcd живёт на отдельных узлах. Control plane и хранилище изолированы: падение узла с API не уменьшает кворум etcd, а деградация etcd не роняет API-серверы. Плата: вдвое больше машин, отдельные сертификаты и отдельная процедура обновления.

КритерийStacked etcdExternal etcd
Число машин для 3 control plane33 control plane + 3 etcd
Сложность развёртыванияНиже: kubeadm создаёт etcd самВыше: etcd поднимают и подключают отдельно
Изоляция отказовОтказ узла снижает и доступность API, и кворумОтказы control plane и etcd не связаны
Требования к дискуДиск общий с control plane, конкуренция за fsyncОтдельные NVMe под /var/lib/etcd
Резервное копированиеСнапшот с любого узла control planeСнапшот с любого узла etcd
Когда выбиратьКоманда без выделенного парка машин, кластеры до сотен узловЖёсткие требования к изоляции отказов и предсказуемости etcd

Для stacked-схемы число control plane и число etcd-участников совпадает: три control plane означают три etcd. Для external считают отдельно: три control plane и три etcd-узла, кворум считается только по etcd.

Кворум etcd: почему нечётное число узлов

etcd использует Raft: запись подтверждается, когда её приняло большинство участников. Кворум для кластера из n участников составляет (n/2)+1, поэтому чётное число не даёт выигрыша (FAQ по etcd). Кластер из 4 узлов требует 3 голоса, то есть переживает тот же один отказ, что и кластер из 3, но тратит лишнюю машину. Трёхузловой etcd - минимальная HA-конфигурация, и для работы ему нужны как минимум два узла (A Guide to etcd).

Узлов etcdКворумПереживает отказов
110
220
321
431
532
743

При потере кворума или отсутствии лидера etcd не принимает обновления и записи: с точки зрения клиента хранилище становится доступным только для чтения (A Guide to etcd). Как именно это отразится на конкретных операциях через Kubernetes API, зависит от версии и состояния кластера, поэтому проверяйте поведение на своём стенде. Практический вывод один: выключать два узла из трёх «на минутку» нельзя, пока большинство не восстановлено, изменяющие запросы проходить не будут.

Требования к диску и сети для etcd

etcd синхронно пишет журнал на диск и чувствителен к задержке fsync. Практические требования:

  • SSD или NVMe, отдельный диск под /var/lib/etcd. Сетевые хранилища с плавающей задержкой дают всплески commit latency и внеплановые выборы лидера.
  • Все etcd-узлы в одной сети с низкой задержкой. Растягивать кворум между дата-центрами рискованно: сетевая деградация между площадками легко приводит к потере лидера.
  • Стабильная пропускная способность: снапшоты etcd передаются по сети, при узком канале отставший участник долго догоняет.

Конкретные пороги по IOPS и миллисекундам зависят от версии etcd и профиля нагрузки, поэтому фиксированные цифры здесь не приводим. Смотрите метрики etcd_disk_wal_fsync_duration_seconds и etcd_disk_backend_commit_duration_seconds: устойчивый рост обеих означает, что диск не тянет, и первым делом нужно менять носитель, а не крутить таймауты.

Балансировщик перед kube-apiserver: HAProxy и keepalived

Схема: VIP держит keepalived через VRRP, HAProxy слушает VIP:6443 и проксирует на kube-apiserver:6443 всех узлов control plane. Клиенты (kubelet, kubectl, controller-manager) знают только VIP.

HAProxy можно поставить на отдельные узлы или на сами control plane. Во втором случае есть нюанс: kube-apiserver уже занимает 6443 на этих хостах, поэтому HAProxy биндится именно на адрес VIP, а не на 0.0.0.0. На backup-узле VIP отсутствует, и bind без дополнительной настройки упадёт. Включите net.ipv4.ip_nonlocal_bind=1 через sysctl на узлах с HAProxy.

Конфигурация HAProxy для kube-apiserver

Трафик к API ведут в TCP-режиме, а health check делают по HTTPS на /healthz. Директива http-check expect задаёт статус, при котором сервер считается здоровым; в примере ниже это 200 OK (Health checks, HAProxy). Проверка подтверждает, что на порту отвечает TLS и эндпоинт возвращает ожидаемый статус.

global
    maxconn 4000
    daemon

defaults
    mode tcp
    timeout connect 5s
    timeout client  1m
    timeout server  1m

frontend k8s-api
    bind 10.0.0.100:6443
    default_backend k8s-api-servers

backend k8s-api-servers
    balance roundrobin
    option httpchk GET /healthz
    http-check expect status 200
    default-server check check-ssl verify none inter 3s fall 3 rise 2
    server cp1 10.0.0.11:6443
    server cp2 10.0.0.12:6443
    server cp3 10.0.0.13:6443

Параметр verify none относится только к проверке здоровья: HAProxy проверяет, что на порту отвечает TLS и /healthz возвращает 200, и не валидирует цепочку сертификата, потому что сертификат API-сервера выписан на имя endpoint, а не на IP backend. На проверку TLS со стороны kubectl и kubelet это не влияет, и отключать валидацию в клиентах нельзя. Если HTTP-проверка не подходит, оставьте только проверку TCP-портом (check без option httpchk): HAProxy исключит узел, который не принимает соединения.

balance roundrobin распределяет запросы по кругу, leastconn уместен при длительных watch-соединениях и неравномерной нагрузке. После правки конфига проверьте синтаксис: haproxy -c -f /etc/haproxy/haproxy.cfg, затем перезагрузите сервис и посмотрите статистику на служебном порту (например, http://127.0.0.1:8404/stats), где все три backend должны быть в состоянии UP.

keepalived и VIP: зачем и как

keepalived держит VIP на активном узле и передаёт его резервному при отказе: протокол VRRP, приоритеты, общий virtual_router_id. HAProxy на резервном узле уже запущен и слушает тот же адрес, поэтому переезд VIP занимает секунды.

vrrp_instance VI_K8S_API {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 150
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass CHANGE_ME_PASSWORD
    }
    virtual_ipaddress {
        10.0.0.100/24
    }
}

На втором узле тот же блок со state BACKUP и priority 100. Пароль замените на свой и не храните в публичном репозитории. keepalived не балансирует трафик и не заменяет HAProxy: он только даёт один IP, который переживает отказ балансировщика.

VIP обязан попасть в SAN сертификата kube-apiserver. При kubeadm init с controlPlaneEndpoint это происходит автоматически, при ручной генерации сертификатов адрес добавляют в san списка. Проверить можно так:

openssl x509 -in /etc/kubernetes/pki/apiserver.crt -text -noout | grep -A2 "Subject Alternative Name"

В выводе должны быть DNS-имя endpoint и IP VIP. Если VIP нет, kubectl и kubelet получат ошибку проверки сертификата x509.

Проверка после настройки: curl --cacert /etc/kubernetes/pki/ca.crt https://10.0.0.100:6443/healthz возвращает ok. Затем остановите keepalived на активном узле командой systemctl stop keepalived, убедитесь, что VIP переехал (ip addr show eth0 на втором узле), а healthz по-прежнему отвечает. Менять сетевые настройки и правила файрвола на удалённом сервере рискованно: держите доступ через консоль гипервизора или out-of-band, иначе переезд VIP можно не пережить.

kubeadm init с controlPlaneEndpoint: пошаговый порядок

Порядок важен: сначала балансировщик и VIP, потом init. Если сделать наоборот, controlPlaneEndpoint придётся дописывать в сертификаты и kubeconfig вручную.

  1. Поднимите два узла под HAProxy и keepalived, настройте VIP и проверьте healthz хотя бы на одном живом API-сервере (для первого шага backend может быть один).
  2. Подготовьте первый узел control plane: container runtime, kubelet, kubeadm, kubectl одной минорной версии, отключённый swap, модули ядра, корректный /etc/hosts.
  3. Создайте kubeadm-config.yaml с controlPlaneEndpoint и localAPIEndpoint.
  4. Выполните kubeadm init --config kubeadm-config.yaml --upload-certs. Флаг upload-certs загружает сертификаты control plane в Secret kubeadm-certs, чтобы новые узлы получили их при join (kubeadm init, Kubernetes).
  5. Скопируйте admin.conf в ~/.kube/config и проверьте kubectl get nodes.
  6. Присоедините второй и третий control plane через kubeadm join --control-plane.

Пример ClusterConfiguration для HA

Точный apiVersion kubeadm-конфига зависит от релиза, и в этой статье конкретная версия не фиксируется. Не угадывайте её: выполните kubeadm config print init-defaults на установленной версии kubeadm и возьмите apiVersion и набор полей из вывода. Ниже - структура конфига с заполненными полями; apiVersion подставьте из вывода команды.

apiVersion: kubeadm.k8s.io/<версия из kubeadm config print init-defaults>
kind: ClusterConfiguration
kubernetesVersion: "v1.XX.Y"
controlPlaneEndpoint: "k8s-api.example.internal:6443"
networking:
  podSubnet: "10.244.0.0/16"
  serviceSubnet: "10.96.0.0/12"
---
apiVersion: kubeadm.k8s.io/<версия из kubeadm config print init-defaults>
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: "10.0.0.11"
  bindPort: 6443

Разница между полями принципиальна: localAPIEndpoint.advertiseAddress - IP конкретного узла, на котором слушает kube-apiserver; controlPlaneEndpoint - общий адрес, VIP или DNS-имя балансировщика. Именно controlPlaneEndpoint попадает в сертификат API-сервера, в kubeconfig и в конфигурацию kubelet. Поменять его после init без перевыпуска сертификатов и правки kubeconfig на всех узлах не получится.

Значение kubernetesVersion подставьте из поддерживаемых релизов в официальной документации Kubernetes на момент развёртывания, в статье конкретный номер не фиксируем.

Проверка после init:

kubectl cluster-info
kubectl get nodes -o wide
kubectl get pods -n kube-system

В kube-system должны быть kube-apiserver, etcd, kube-controller-manager, kube-scheduler и сетевой плагин в состоянии Running. Если kube-apiserver в CrashLoopBackOff, смотрите логи статического пода через crictl logs и вывод journalctl -u kubelet.

Подключение дополнительных control plane через kubeadm join --control-plane

Для присоединения нужны три вещи: адрес controlPlaneEndpoint (VIP, не IP узла), bootstrap-токен и certificate-key. Токен и хеш CA печатает kubeadm token create --print-join-command, ключ сертификатов выдаёт kubeadm init phase upload-certs --upload-certs. Если предопределённый certificate key не передан, команда генерирует новый ключ автоматически (kubeadm init, Kubernetes).

kubeadm join k8s-api.example.internal:6443 \
  --token 000000.1111111111111111 \
  --discovery-token-ca-cert-hash sha256:0000000000000000000000000000000000000000000000000000000000000000 \
  --control-plane \
  --certificate-key 0000000000000000000000000000000000000000000000000000000000000000

Значения в примере - заглушки, подставьте вывод kubeadm. certificate-key даёт доступ к ключам кластера и не должен попадать в тикеты, чаты и репозитории. Сертификаты и ключ шифрования, загруженные фазой upload-certs, по умолчанию истекают через два часа (kubeadm init phase, Kubernetes). Если ключ истёк, загрузите сертификаты повторно командой kubeadm init phase upload-certs --upload-certs на узле control plane и получите новый ключ.

После join на новом узле выполните mkdir -p $HOME/.kube и скопируйте /etc/kubernetes/admin.conf, затем проверьте kubectl get nodes: узел появится с ролью control-plane. В kube-system должно стать на один kube-apiserver, один etcd, один controller-manager и один scheduler больше, причём часть из них будет в состоянии ожидания лидерства - это норма.

Чек-лист проверки отказоустойчивости

Настроенный HA нужно проверить отказом, иначе о его работоспособности ничего не известно. Все шаги выполняйте на тестовом кластере или в согласованное окно обслуживания: остановка kubelet на узле control plane гасит статические поды, включая etcd.

  1. kubectl get nodes: все узлы control plane в статусе Ready.
  2. kubectl get pods -n kube-system: статические поды kube-apiserver, etcd, kube-controller-manager и kube-scheduler в Running, без частых перезапусков.
  3. Остановите один control plane (см. ниже) и проверьте доступность API через VIP.
  4. Проверьте состояние etcd и наличие лидера.
  5. Верните узел в строй и убедитесь, что он снова в кластере, а etcd догнал журнал.
  6. Повторите проверку для балансировщика: остановите keepalived на активном узле и убедитесь, что VIP переехал, а API отвечает.

Проверка API при отказе одного control plane

Самый честный тест - выключить узел целиком, как при аварии. Если такой возможности нет, остановите kubelet: статические поды погаснут вместе с ним.

systemctl stop kubelet
kubectl get nodes
curl --cacert /etc/kubernetes/pki/ca.crt https://k8s-api.example.internal:6443/healthz

Ожидаемый результат: healthz возвращает ok с машины, где kubelet остановлен не был; kubectl get nodes отвечает, упавший узел в статусе NotReady, остальные Ready. Команды kubectl выполняйте с рабочей машины или с другого control plane, а не с выключенного узла.

Если API не отвечает, смотрите по порядку: journalctl -u kubelet на упавшем узле, crictl logs для контейнеров kube-apiserver и etcd, журнал HAProxy (при mode tcp нужен option tcplog, иначе в логах не будет деталей), доступность 6443 между узлами. Возврат узла: systemctl start kubelet, затем проверка kubectl get nodes и etcdctl endpoint health.

Проверка кворума etcd

Команды etcdctl выполняйте с сертификатами etcd, иначе получите ошибку TLS. Для stacked-схемы путь к сертификатам лежит в /etc/kubernetes/pki/etcd/.

etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  endpoint health --cluster
etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  endpoint status --cluster --write-out=table

Ожидаемый результат при отказе одного узла из трёх: два endpoint healthy, один unhealthy, в таблице статусов один лидер и ненулевой raft term не растёт бесконечно. Кворум сохранён, записи проходят. Если healthy меньше двух из трёх, etcd потерял большинство: изменяющие запросы к API проходить не будут, и первым делом нужно вернуть узел, а не перезапускать оставшиеся.

Резервное копирование etcd и риски изменений

etcd хранит состояние кластера целиком, включая секреты и ServiceAccount-токены. Ошибка в etcd стоит дороже ошибки в любом другом компоненте, поэтому снапшот снимают до изменений, а не после первых симптомов.

Снапшот etcd перед изменениями

mkdir -p /backup
etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save /backup/etcd-$(date +%F-%H%M).db

etcdctl snapshot status /backup/etcd-$(date +%F-%H%M).db --write-out=table

snapshot status показывает размер, число ключей и revision. Копию храните вне узла control plane: локальный файл не поможет, если узел потерян. Снапшот содержит секреты кластера, поэтому шифруйте его при передаче и ограничьте права на файл. Восстановление из снапшота - деструктивная операция: она перезаписывает /var/lib/etcd и требует остановки etcd на всех узлах. Сначала отработайте процедуру на тестовом кластере, в продакшене выполняйте по официальной инструкции и только при потере данных.

Типичные ошибки и как их распознать

СимптомПричинаГде смотреть
kubectl падает с ошибкой x509: certificate is valid for ..., not ...VIP или DNS-имя endpoint отсутствует в SAN сертификата kube-apiserveropenssl x509 по /etc/kubernetes/pki/apiserver.crt, поле Subject Alternative Name
kubelet не регистрируется, узел не появляется в get nodeskubelet обращается к недоступному controlPlaneEndpoint или неверный хеш CAjournalctl -u kubelet, /var/lib/kubelet/kubeadm-flags.env
API отвечает на чтение, но apply и create падаютПотерян кворум etcdetcdctl endpoint health --cluster, endpoint status
join --control-plane прерывается на этапе сертификатовИстёк certificate-key или не совпадает версия kubeadmВывод kubeadm join, kubeadm version на обоих узлах
Кластер работает, но события в API идут с задержкойМедленный диск или сеть между etcd-узламиМетрики etcd_disk_wal_fsync_duration_seconds, etcd_disk_backend_commit_duration_seconds

Отдельно про файрвол: по документации Kubernetes kube-apiserver принимает входящие соединения на 6443/tcp, etcd server client API использует 2379-2380/tcp, а kubelet работает через 10250/tcp (Ports and Protocols, Kubernetes). Эти порты нужно открыть между соответствующими узлами. Не отключайте файрвол и не отключайте проверку TLS как способ обойти ошибку: и то и другое маскирует причину и снижает безопасность кластера. Разбор других частых промахов в эксплуатации, включая работу с секретами и мониторинг, собран в подборке 10 частых ошибок при настройке Kubernetes.

Версии Kubernetes и совместимость компонентов

kubeadm, kubelet и kubectl держите одной минорной версии на всех узлах. kubelet не должен быть новее kube-apiserver, а допустимое отставание по минорным версиям менялось между релизами, поэтому сверяйтесь с разделом version skew policy в официальной документации Kubernetes для своей версии. Конкретные номера релизов в статье не фиксируем: поддерживаемые ветки меняются несколько раз в год, и любой зашитый номер устареет быстрее, чем выйдет следующая правка гайда.

Проверка версий перед развёртыванием и обновлением:

kubeadm version
kubelet --version
kubectl version --client
kubeadm upgrade plan

kubeadm upgrade plan покажет текущую версию control plane, доступные цели и предупреждения о пропущенных минорных версиях. Перескакивать через минорную версию kubeadm не позволяет: обновление идёт последовательно, по одной минорной версии за шаг.

Старые гайды опасны конкретными деталями: apiVersion kubeadm-конфига, набор полей ClusterConfiguration и синтаксис команд менялись. Команда kubeadm config print init-defaults и kubeadm config print join-defaults выдаёт актуальный шаблон для установленной версии, это самый надёжный способ получить корректный конфиг без догадок. Если схема control plane и логика leader election вызывают вопросы, разбор отказоустойчивости контроллеров и правил мониторинга есть в материале про аварийную устойчивость контроллеров Kubernetes.

Готовый порядок действий для нового кластера выглядит так: 3 узла control plane, VIP через keepalived, HAProxy с HTTP-проверкой /healthz, kubeadm init с controlPlaneEndpoint на VIP, join двух оставшихся узлов с --control-plane, снапшот etcd сразу после ввода в строй. Дальше - проверка отказом: остановить один узел, убедиться, что kubectl через VIP отвечает и etcd держит кворум, вернуть узел и убедиться, что он вернулся в Ready.

Поделиться: