Масштабирование и изменение master-узлов

Масштабирование и переход single-master/multi-master

Режимы работы control plane

Deckhouse Kubernetes Platform (DKP) поддерживает два режима работы control plane:

1. Single-master:
   • kube-apiserver использует только локальный экземпляр etcd;
   • на узле запускается прокси-сервер, который принимает запросы на localhost;
   • kube-apiserver “слушает” только на IP-адресе master-узла.
2. Multi-master:
   • kube-apiserver работает со всеми экземплярами etcd в кластере;
   • на всех узлах настраивается дополнительный прокси:
     • если локальный kube-apiserver недоступен, запросы автоматически перенаправляются на другие узлы;
   • это обеспечивает отказоустойчивость и возможность масштабирования.

Автоматическое масштабирование master-узлов

Deckhouse Kubernetes Platform (DKP) позволяет автоматически добавлять и удалять master-узлы, используя лейбл node-role.kubernetes.io/control-plane="".

Автоматическое управление master-узлами:

• Добавление лейбла node-role.kubernetes.io/control-plane="" на узел:
  • разворачиваются все компоненты control plane;
  • узел подключается к etcd-кластеру;
  • автоматически регенерируются сертификаты и конфигурационные файлы.
• Удаление лейбла node-role.kubernetes.io/control-plane="" с узла:
  • компоненты control plane удаляются;
  • узел корректно исключается из etcd-кластера;
  • обновляются связанные конфигурационные файлы.

Типовые сценарии масштабирования

Deckhouse Kubernetes Platform (DKP) поддерживает автоматическое и ручное масштабирование master-узлов как в облачных, так и в bare-metal кластерах:

1. Миграция single-master → multi-master:

   • добавьте один или несколько новых master-узлов;
   • установите им лейбл node-role.kubernetes.io/control-plane="";
   • DKP автоматически:
     • развернёт все компоненты control plane;
     • настроит узлы для работы с etcd-кластером;
     • синхронизирует сертификаты и конфигурационные файлы.

2. Миграция multi-master → single-master:

   • снимите лейблы node-role.kubernetes.io/control-plane="" и node-role.kubernetes.io/master="" со всех лишних master-узлов;
   • для bare-metal кластеров:
     • чтобы корректно исключить узлы из etcd:
       • выполните команду d8 k delete node <имя-узла>;
       • выключите соответствующие виртуальные машины или серверы.

   Важно. В облачных кластерах все необходимые действия автоматически выполняются с помощью команды dhctl converge.

3. Изменение числа master-узлов в облачном кластере:

   • Аналогично добавлению/удалению узлов, но чаще всего выполняется с помощью команды dhctl converge или вручную через облачные инструменты.

4. Миграция multi-master (3 master-узла) → 2 master-узла и 1 arbiter-узел в облачном кластере:

   • В настройках облачного провайдера для параметра masterNodeGroup.replicas укажите 2 и создайте NodeGroup для arbiter-узла. Аналогично добавлению/удалению узлов, но чаще всего выполняется с помощью команды dhctl converge или вручную через облачные инструменты.

     Подробнее о настройке режима HA c двумя master-узлами и arbiter-узлом в облачном кластере можно почитать в разделе Управление режимом HA.

5. Миграция multi-master (3 master-узла) → 2 master-узла и 1 arbiter-узел в статическом кластере:

   • создайте NodeGroup для arbiter-узла и добавьте узел в кластер;
   • снимите лейблы node-role.kubernetes.io/control-plane="", node-role.kubernetes.io/master="" и node.deckhouse.io/group-"" с лишнего master-узла;
   • чтобы корректно исключить узел из etcd в bare-metal кластере:
     • выполните команду d8 k delete node <имя-узла>;
     • выключите соответствующую виртуальную машину или сервер.

     Подробнее о настройке режима HA c двумя master-узлами и arbiter-узлом в статическом кластере можно почитать в разделе Управление режимом HA.

Удаление роли master с узла без удаления самого узла

Если необходимо вывести узел из состава master-узлов, но сохранить его в кластере для других задач, выполните следующие шаги:

1. Снимите лейблы, чтобы узел больше не рассматривался как master:

   d8 k label node <имя-узла> node-role.kubernetes.io/control-plane-
   d8 k label node <имя-узла> node-role.kubernetes.io/master-
   d8 k label node <имя-узла> node.deckhouse.io/group-
   

2. Убедитесь, что удаляемый master-узел пропал из списка членов кластера etcd:

   Пример:

   for pod in $(d8 k -n kube-system get pod -l component=etcd,tier=control-plane -o name); do
     d8 k -n kube-system exec "$pod" -- etcdctl --cacert /etc/kubernetes/pki/etcd/ca.crt \
     --cert /etc/kubernetes/pki/etcd/ca.crt --key /etc/kubernetes/pki/etcd/ca.key \
     --endpoints https://127.0.0.1:2379/ member list -w table
     if [ $? -eq 0 ]; then
       break
     fi
   done
   

3. Удалите статические манифесты компонентов control plane, чтобы они больше не запускались на узле и лишние файлы PKI. Для этого зайдите на узел и выполните следующие команды:

   rm -f /etc/kubernetes/manifests/{etcd,kube-apiserver,kube-scheduler,kube-controller-manager}.yaml
   rm -f /etc/kubernetes/{scheduler,controller-manager}.conf
   rm -f /etc/kubernetes/authorization-webhook-config.yaml
   rm -f /etc/kubernetes/admin.conf /root/.kube/config
   rm -rf /etc/kubernetes/deckhouse
   rm -rf /etc/kubernetes/pki/{ca.key,apiserver*,etcd/,front-proxy*,sa.*}
   rm -rf /var/lib/etcd/member/
   

После выполнения этих шагов узел больше не будет считаться master-узлом, но останется в кластере и может использоваться для других задач.

Изменение образа ОС master-узлов в мультимастерном кластере

Способ изменения ОС зависит от типа кластера: в облачном кластере узлы заменяются через dhctl converge, в статическом — вручную, по одному узлу.

В облачном кластере

Чтобы изменить образ ОС master-узлов в облачном мультимастерном кластере, выполните следующие шаги:

1. Сделайте резервную копию etcd и директории /etc/kubernetes.
2. Скопируйте полученный архив за пределы кластера (например, на локальную машину).
3. Убедитесь, что в кластере нет алертов, которые могут помешать обновлению master-узлов.

4. Убедитесь, что очередь Deckhouse пуста.

   d8 system queue list
   

5. На локальной машине авторизуйтесь в хранилище образов контейнеров (измените адрес хранилища образов при необходимости):

   docker login registry.deckhouse.ru
   

   В процессе авторизации необходимо будет ввести Username и Password.

   При авторизации в хранилище registry.deckhouse.ru поле Username должно иметь значение license-token, а Password — содержать ключ лицензии Deckhouse Kubernetes Platform.

6. На локальной машине запустите контейнер установщика DKP соответствующей редакции и версии (измените адрес хранилища образов при необходимости):

   DH_VERSION=$(d8 k -n d8-system get deployment deckhouse -o jsonpath='{.metadata.annotations.core\.deckhouse\.io\/version}') 
   DH_EDITION=$(d8 k -n d8-system get deployment deckhouse -o jsonpath='{.metadata.annotations.core\.deckhouse\.io\/edition}' | tr '[:upper:]' '[:lower:]' ) 
   docker run --pull=always -it -v "$HOME/.ssh/:/tmp/.ssh/" \
     registry.deckhouse.ru/deckhouse/${DH_EDITION}/install:${DH_VERSION} bash
   

7. В контейнере с инсталлятором выполните следующую команду, чтобы проверить состояние перед началом работы:

   dhctl terraform check --ssh-agent-private-keys=/tmp/.ssh/<SSH_KEY_FILENAME> --ssh-user=<USERNAME> \
     --ssh-host <MASTER-NODE-0-HOST> --ssh-host <MASTER-NODE-1-HOST> --ssh-host <MASTER-NODE-2-HOST>
   

   Ответ должен сообщить, что Terraform не нашёл расхождений и изменений не требуется.

8. В контейнере с инсталлятором выполните следующую команду и укажите необходимый образ ОС в параметре masterNodeGroup.instanceClass (укажите адреса всех master-узлов в параметре --ssh-host):

   dhctl config edit provider-cluster-configuration --ssh-agent-private-keys=/tmp/.ssh/<SSH_KEY_FILENAME> --ssh-user=<USERNAME> \
     --ssh-host <MASTER-NODE-0-HOST> --ssh-host <MASTER-NODE-1-HOST> --ssh-host <MASTER-NODE-2-HOST>
   

9. В контейнере с инсталлятором выполните следующую команду, чтобы провести обновление узлов:

   Внимательно изучите действия, которые планирует выполнить converge, когда запрашивает подтверждение.

   При выполнении команды узлы будут заменены на новые с подтверждением на каждом узле. Замена будет выполняться по очереди в обратном порядке (2,1,0).

   dhctl converge --ssh-agent-private-keys=/tmp/.ssh/<SSH_KEY_FILENAME> --ssh-user=<USERNAME> \
     --ssh-host <MASTER-NODE-0-HOST> --ssh-host <MASTER-NODE-1-HOST> --ssh-host <MASTER-NODE-2-HOST>
   

   Следующие действия выполняйте поочерёдно на каждом master-узле, начиная с узла с наивысшим номером (с суффиксом 2) и заканчивая узлом с наименьшим номером (с суффиксом 0).

10. На созданном узле откройте журнал systemd-юнита bashible.service. Дождитесь окончания настройки узла — в журнале должно появиться сообщение nothing to do:

    journalctl -fu bashible.service
    

11. Проверьте, что узел etcd отобразился в списке узлов кластера:

    for pod in $(d8 k -n kube-system get pod -l component=etcd,tier=control-plane -o name); do
      d8 k -n kube-system exec "$pod" -- etcdctl --cacert /etc/kubernetes/pki/etcd/ca.crt \
      --cert /etc/kubernetes/pki/etcd/ca.crt --key /etc/kubernetes/pki/etcd/ca.key \
      --endpoints https://127.0.0.1:2379/ member list -w table
      if [ $? -eq 0 ]; then
        break
      fi
    done
    

12. Убедитесь, что control-plane-manager функционирует на узле.

    d8 k -n kube-system wait pod --timeout=10m --for=condition=ContainersReady \
      -l app=d8-control-plane-manager --field-selector spec.nodeName=<MASTER-NODE-N-NAME>
    

13. Выполните проверку очереди Deckhouse и убедитесь, что отсутствуют ошибки, с помощью команды:

    d8 system queue list
    

14. Перейдите к обновлению следующего узла.

В статическом кластере

Инструкция ниже описывает замену ОС на master-узлах, которые добавлены в кластер вручную с помощью скрипта bootstrap.sh. Выполняйте шаги поочерёдно для каждого master-узла и переходите к следующему только после того, как текущий узел вернулся в кластер и стал работоспособен.

Чтобы изменить ОС вручную добавленного master-узла, выполните следующие шаги:

1. Сделайте резервную копию etcd и директории /etc/kubernetes. Если используется модуль stronghold, убедитесь, что создана резервная копия его данных.

2. Проверьте состояние кластера, отсутствие алертов и незавершённых задач в очереди Deckhouse:

   d8 status
   

3. Снимите с узла лейблы master-узла:

   d8 k label node <MASTER_NODE_NAME> node-role.kubernetes.io/control-plane- \
     node-role.kubernetes.io/master- node.deckhouse.io/group-
   

   где <MASTER_NODE_NAME> — имя изменяемого master-узла.

4. Убедитесь, что узел удалён из списка членов кластера etcd:

   for pod in $(d8 k -n kube-system get pod -l component=etcd,tier=control-plane -o name); do
     d8 k -n kube-system exec "$pod" -- etcdctl --cacert /etc/kubernetes/pki/etcd/ca.crt \
       --cert /etc/kubernetes/pki/etcd/ca.crt --key /etc/kubernetes/pki/etcd/ca.key \
       --endpoints https://127.0.0.1:2379/ member list -w table
     if [ $? -eq 0 ]; then
       break
     fi
   done
   

5. Вытесните нагрузку с узла командой d8 k drain:

   d8 k drain <MASTER_NODE_NAME> --ignore-daemonsets --delete-emptydir-data
   

6. Принудительно удалите оставшиеся на узле поды:

   d8 k delete pods --all-namespaces --field-selector spec.nodeName=<MASTER_NODE_NAME> --force
   

7. Удалите объект Node:

   d8 k delete node <MASTER_NODE_NAME>
   

8. На удаляемом master-узле очистите данные DKP. Команда необратимо удаляет данные Kubernetes и DKP с узла. Перед выполнением убедитесь, что выбран правильный узел и созданы необходимые резервные копии:

   bash /var/lib/bashible/cleanup_static_node.sh --yes-i-am-sane-and-i-understand-what-i-am-doing
   

9. Установите на узле требуемую ОС.

10. На одном из оставшихся в кластере master-узлов получите и раскодируйте скрипт для добавления master-узла:

    d8 k -n d8-cloud-instance-manager get secret manual-bootstrap-for-master \
      -o jsonpath='{.data.bootstrap\.sh}' | base64 -d > bootstrap.sh
    

11. Безопасно скопируйте полученный на предыдущем шаге файл bootstrap.sh на добавляемый узел и выполните его на этом узле от пользователя root:

    bash bootstrap.sh
    

12. На добавляемом узле откройте журнал systemd-юнита bashible.service. Дождитесь окончания настройки узла — в журнале должно появиться сообщение nothing to do:

    journalctl -fu bashible.service
    

13. Дождитесь перехода узла в статус Ready:

    d8 k wait node <MASTER_NODE_NAME> --for=condition=Ready --timeout=10m
    

14. Проверьте, что узел отобразился в списке членов кластера etcd:

    for pod in $(d8 k -n kube-system get pod -l component=etcd,tier=control-plane -o name); do
      d8 k -n kube-system exec "$pod" -- etcdctl --cacert /etc/kubernetes/pki/etcd/ca.crt \
        --cert /etc/kubernetes/pki/etcd/ca.crt --key /etc/kubernetes/pki/etcd/ca.key \
        --endpoints https://127.0.0.1:2379/ member list -w table
      if [ $? -eq 0 ]; then
        break
      fi
    done
    

15. Убедитесь, что control-plane-manager функционирует на узле:

    d8 k -n kube-system wait pod --timeout=10m --for=condition=ContainersReady \
      -l app=d8-control-plane-manager --field-selector spec.nodeName=<MASTER_NODE_NAME>
    

16. Убедитесь, что в кластере нет алертов и незавершённых задач:

    d8 status
    

17. Повторите процедуру для следующего master-узла.

Изменение образа ОС в кластере с одним master-узлом

Способ зависит от типа кластера: сначала добавьте дополнительные master-узлы, замените ОС в мультимастерном режиме, затем верните исходное число master-узлов.

В облачном кластере

1. Преобразуйте кластер с одним master-узлом в мультимастерный в соответствии с инструкцией.
2. Измените ОС на master-узлах в соответствии с инструкцией.
3. Преобразуйте мультимастерный кластер в кластер с одним master-узлом в соответствии с инструкцией.

В статическом кластере

1. Добавьте дополнительные master-узлы в соответствии с инструкцией.
2. Измените ОС на master-узлах в соответствии с инструкцией.
3. Выведите лишние master-узлы из роли control plane в соответствии с инструкцией. Затем удалите их из кластера командой d8 k delete node <MASTER_NODE_NAME> и выключите соответствующие серверы.

Добавление master-узлов в статический или гибридный кластер

Важно иметь нечетное количество master-узлов для обеспечения кворума.

В процессе установки Deckhouse Kubernetes Platform с настройками по умолчанию в NodeGroup master отсутствует секция spec.staticInstances.labelSelector с настройками фильтра лейблов по ресурсам staticInstances. Из-за этого после изменения количества узлов staticInstances в NodeGroup master (параметр spec.staticInstances.count) при добавлении обычного узла с помощью Cluster API Provider Static (CAPS) он может быть «перехвачен» и добавлен в NodeGroup master, даже если в соответствующем ему StaticInstance (в metadata) указан лейбл с role, отличающейся от master. Чтобы избежать этого «перехвата», после установки DKP измените NodeGroup master — добавьте в нее секцию spec.staticInstances.labelSelector с настройками фильтра лейблов по ресурсам staticInstances. Пример NodeGroup master с spec.staticInstances.labelSelector:

apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: master
spec:
  nodeType: Static
  staticInstances:
    count: 2
    labelSelector:
      matchLabels:
        role: master

Далее при добавлении в кластер master-узлов с помощью CAPS указывайте в соответствующих им StaticInstance лейбл, заданный в spec.staticInstances.labelSelector NodeGroup master. Пример:

apiVersion: deckhouse.io/v1alpha1
kind: StaticInstance
metadata:
  name: static-master-1
  labels:
    # Лейбл, указанный в spec.staticInstances.labelSelector NodeGroup master.
    role: master
spec:
  # Укажите IP-адрес сервера статического узла.
  address: "<SERVER-IP>"
  credentialsRef:
    kind: SSHCredentials
    name: credentials

В остальном добавление master-узла в статический или гибридный кластер аналогично добавлению обычного узла. Воспользуйтесь для этого соответствующими примерами. Все необходимые действия по настройке компонентов control plane кластера на новом узле будут выполнены автоматически, дождитесь их завершения — появления master-узлов в статусе Ready.

Добавление master-узлов в облачном кластере

Далее описана конвертация кластера с одним master-узлом в мультимастерный кластер.

1. Сделайте резервную копию etcd и директории /etc/kubernetes.
2. Скопируйте полученный архив за пределы кластера (например, на локальную машину).
3. Убедитесь, что в кластере нет алертов, которые могут помешать созданию новых master-узлов.

4. Убедитесь, что очередь Deckhouse пуста:

   d8 system queue list
   

5. На локальной машине авторизуйтесь в хранилище образов контейнеров (измените адрес хранилища образов при необходимости):

   docker login registry.deckhouse.ru
   

   В процессе авторизации необходимо будет ввести Username и Password.

   При авторизации в хранилище registry.deckhouse.ru поле Username должно иметь значение license-token, а Password — содержать ключ лицензии Deckhouse Kubernetes Platform.

6. На локальной машине запустите контейнер установщика DKP соответствующей редакции и версии (измените адрес хранилища образов при необходимости):

   DH_VERSION=$(d8 k -n d8-system get deployment deckhouse -o jsonpath='{.metadata.annotations.core\.deckhouse\.io\/version}') 
   DH_EDITION=$(d8 k -n d8-system get deployment deckhouse -o jsonpath='{.metadata.annotations.core\.deckhouse\.io\/edition}' | tr '[:upper:]' '[:lower:]' ) 
   docker run --pull=always -it -v "$HOME/.ssh/:/tmp/.ssh/" \
     registry.deckhouse.ru/deckhouse/${DH_EDITION}/install:${DH_VERSION} bash
   

7. В контейнере с инсталлятором выполните следующую команду, чтобы проверить состояние перед началом работы:

   dhctl terraform check --ssh-agent-private-keys=/tmp/.ssh/<SSH_KEY_FILENAME> --ssh-user=<USERNAME> --ssh-host <MASTER-NODE-0-HOST>
   

   Ответ должен сообщить, что Terraform не нашёл расхождений и изменений не требуется.

8. В контейнере с инсталлятором выполните следующую команду и укажите требуемое количество master-узлов в параметре masterNodeGroup.replicas:

   dhctl config edit provider-cluster-configuration --ssh-agent-private-keys=/tmp/.ssh/<SSH_KEY_FILENAME> --ssh-user=<USERNAME> \
     --ssh-host <MASTER-NODE-0-HOST>
   

   Для Yandex Cloud, при использовании внешних адресов на master-узлах, количество элементов массива в параметре masterNodeGroup.instanceClass.externalIPAddresses должно равняться количеству master-узлов. При использовании значения Auto (автоматический заказ публичных IP-адресов), количество элементов в массиве все равно должно соответствовать количеству master-узлов.

   Например, при трех master-узлах (masterNodeGroup.replicas: 3) и автоматическом заказе адресов, параметр masterNodeGroup.instanceClass.externalIPAddresses будет выглядеть следующим образом:

   externalIPAddresses:
   - "Auto"
   - "Auto"
   - "Auto"
   

9. В контейнере с инсталлятором выполните следующую команду для запуска масштабирования:

   dhctl converge --ssh-agent-private-keys=/tmp/.ssh/<SSH_KEY_FILENAME> --ssh-user=<USERNAME> --ssh-host <MASTER-NODE-0-HOST>
   

10. Дождитесь появления необходимого количества master-узлов в статусе Ready и готовности всех экземпляров control-plane-manager:

    d8 k -n kube-system wait pod --timeout=10m --for=condition=ContainersReady -l app=d8-control-plane-manager
    

Уменьшение числа master-узлов в облачном кластере

Далее описана конвертация мультимастерного кластера в кластер с одним master-узлом.

1. Сделайте резервную копию etcd и директории /etc/kubernetes.
2. Скопируйте полученный архив за пределы кластера (например, на локальную машину).
3. Убедитесь, что в кластере нет алертов, которые могут помешать обновлению master-узлов.

4. Убедитесь, что очередь DKP пуста:

   d8 system queue list
   

5. На локальной машине авторизуйтесь в хранилище образов контейнеров (измените адрес хранилища образов при необходимости):

   docker login registry.deckhouse.ru
   

   В процессе авторизации необходимо будет ввести Username и Password.

   При авторизации в хранилище registry.deckhouse.ru поле Username должно иметь значение license-token, а Password — содержать ключ лицензии Deckhouse Kubernetes Platform.

6. На локальной машине запустите контейнер установщика DKP соответствующей редакции и версии (измените адрес хранилища образов при необходимости):

   DH_VERSION=$(d8 k -n d8-system get deployment deckhouse -o jsonpath='{.metadata.annotations.core\.deckhouse\.io\/version}') 
   DH_EDITION=$(d8 k -n d8-system get deployment deckhouse -o jsonpath='{.metadata.annotations.core\.deckhouse\.io\/edition}' | tr '[:upper:]' '[:lower:]' ) 
   docker run --pull=always -it -v "$HOME/.ssh/:/tmp/.ssh/" \
     registry.deckhouse.ru/deckhouse/${DH_EDITION}/install:${DH_VERSION} bash
   

7. В контейнере с инсталлятором выполните следующую команду и укажите 1 в параметре masterNodeGroup.replicas:

   dhctl config edit provider-cluster-configuration --ssh-agent-private-keys=/tmp/.ssh/<SSH_KEY_FILENAME> \
     --ssh-user=<USERNAME> --ssh-host <MASTER-NODE-0-HOST>
   

   Для Yandex Cloud при использовании внешних адресов на master-узлах количество элементов массива в параметре masterNodeGroup.instanceClass.externalIPAddresses должно равняться количеству master-узлов. При использовании значения Auto (автоматический заказ публичных IP-адресов) количество элементов в массиве все равно должно соответствовать количеству master-узлов.

   Например, при одном master-узле (masterNodeGroup.replicas: 1) и автоматическом заказе адресов параметр masterNodeGroup.instanceClass.externalIPAddresses будет выглядеть следующим образом:

   externalIPAddresses:
   - "Auto"
   

8. В контейнере с инсталлятором выполните следующую команду для запуска масштабирования:

   dhctl converge --ssh-agent-private-keys=/tmp/.ssh/<SSH_KEY_FILENAME> --ssh-user=<USERNAME> --ssh-host <MASTER-NODE-0-HOST>
   

   Для OpenStack и VK Cloud (OpenStack) после подтверждения удаления узла обязательно проверьте удаление диска <prefix>kubernetes-data-N в самом Openstack.

   Например, при удалении узла cloud-demo-master-2 в веб-интерфейсе Openstack или в OpenStack CLI необходимо проверить отсутствие диска cloud-demo-kubernetes-data-2.

   В случае, если диск kubernetes-data останется, при увеличении количества master-узлов могут возникнуть проблемы в работе ETCD.

9. Выполните проверку очереди Deckhouse и убедитесь, что отсутствуют ошибки, с помощью команды:

   d8 system queue list
   

Доступ к контроллеру DKP в мультимастерном кластере

В кластерах с несколькими master-узлами DKP запускается в режиме высокой доступности (в нескольких экземплярах). Для доступа к активному контроллеру DKP можно использовать следующую команду (на примере команды deckhouse-controller queue list):

d8 system queue list

Дополнительные ресурсы

• Документация модуля control-plane-manager
• Кастомные ресурсы модуля node-manager
• Документация модуля stronghold