Стадия жизненного цикла модуля: General Availability

Как добавить master-узлы в облачном кластере?

Порядок конвертирования кластера с одним master-узлом в мультимастерный кластер описан в FAQ модуля control-plane-manager.

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

Порядок конвертирования мультимастерного кластера в кластер с одним master-узлом описан в FAQ модуля control-plane-manager.

Статические узлы

Добавить статический узел в кластер можно вручную (пример) или с помощью Cluster API Provider Static.

Как добавить статический узел в кластер (Cluster API Provider Static)?

Чтобы добавить статический узел в кластер (сервер bare-metal или виртуальную машину), выполните следующие шаги:

  1. Подготовьте необходимые ресурсы:

    • Выделите сервер или виртуальную машину и убедитесь, что узел имеет необходимую сетевую связанность с кластером.

    • При необходимости установите дополнительные пакеты ОС и настройте точки монтирования, которые будут использоваться на узле.

  2. Создайте пользователя с правами sudo:

    • Добавьте нового пользователя (в данном примере — caps) с правами выполнения команд через sudo:

      useradd -m -s /bin/bash caps 
      usermod -aG sudo caps
      
    • Разрешите пользователю выполнять команды через sudo без ввода пароля. Для этого отредактируйте конфигурацию sudo (отредактировав файл /etc/sudoers, выполнив команду sudo visudo или другим способом):

      caps ALL=(ALL) NOPASSWD: ALL
      
  3. На сервере откройте файл /etc/ssh/sshd_config и убедитесь, что параметр UsePAM установлен в значение yes. Затем перезапустите службу sshd:

    sudo systemctl restart sshd
    
  4. Сгенерируйте на сервере пару SSH-ключей с пустой парольной фразой:

    ssh-keygen -t ed25519 -f caps-id -C "" -N ""
    

    Приватный и публичный ключи будут сохранены в файлах caps-id и caps-id.pub соответственно в текущей директории.

  5. Добавьте полученный публичный ключ в файл /home/caps/.ssh/authorized_keys пользователя caps, выполнив в директории с ключами на сервере следующие команды:

    mkdir -p /home/caps/.ssh 
    cat caps-id.pub >> /home/caps/.ssh/authorized_keys 
    chmod 700 /home/caps/.ssh 
    chmod 600 /home/caps/.ssh/authorized_keys
    chown -R caps:caps /home/caps/
    
  6. Создайте ресурс SSHCredentials.
  7. Создайте ресурс StaticInstance.
  8. Создайте ресурс NodeGroup с nodeType Static, указав желаемое количество узлов в группе и, при необходимости, фильтр выбора StaticInstance.

Пример добавления статического узла.

Как добавить несколько статических узлов в кластер вручную?

Используйте существующий или создайте новый кастомный ресурс (Custom Resource) NodeGroup (пример NodeGroup с именем worker).

Автоматизировать процесс добавления узлов можно с помощью любой платформы автоматизации. Далее приведен пример для Ansible.

  1. Получите один из адресов Kubernetes API-сервера. Обратите внимание, что IP-адрес должен быть доступен с узлов, которые добавляются в кластер:

    d8 k -n default get ep kubernetes -o json | jq '.subsets[0].addresses[0].ip + ":" + (.subsets[0].ports[0].port | tostring)' -r
    

    Проверьте версию K8s. Если версия >= 1.25, создайте токен node-group:

    d8 k create token node-group --namespace d8-cloud-instance-manager --duration 1h
    

    Сохраните полученный токен, и добавьте в поле token: playbook’а Ansible на дальнейших шагах.

  2. Если версия Kubernetes меньше 1.25, получите Kubernetes API-токен для специального ServiceAccount’а, которым управляет Deckhouse:

    d8 k -n d8-cloud-instance-manager get $(d8 k -n d8-cloud-instance-manager get secret -o name | grep node-group-token) \
      -o json | jq '.data.token' -r | base64 -d && echo ""
    
  3. Создайте Ansible playbook с vars, которые заменены на полученные на предыдущих шагах значения:

    - hosts: all
      become: yes
      gather_facts: no
      vars:
        kube_apiserver: <KUBE_APISERVER>
        token: <TOKEN>
      tasks:
        - name: Check if node is already bootsrapped
          stat:
            path: /var/lib/bashible
          register: bootstrapped
        - name: Get bootstrap secret
          uri:
            url: "https://{{ kube_apiserver }}/api/v1/namespaces/d8-cloud-instance-manager/secrets/manual-bootstrap-for-{{ node_group }}"
            return_content: yes
            method: GET
            status_code: 200
            body_format: json
            headers:
              Authorization: "Bearer {{ token }}"
            validate_certs: no
          register: bootstrap_secret
          when: bootstrapped.stat.exists == False
        - name: Run bootstrap.sh
          shell: "{{ bootstrap_secret.json.data['bootstrap.sh'] | b64decode }}"
          args:
            executable: /bin/bash
          ignore_errors: yes
          when: bootstrapped.stat.exists == False
        - name: wait
          wait_for_connection:
            delay: 30
          when: bootstrapped.stat.exists == False
    
  4. Определите дополнительную переменную node_group. Значение переменной должно совпадать с именем NodeGroup, которой будет принадлежать узел. Переменную можно передать различными способами, например с использованием inventory-файла:

    [system]
    system-0
    system-1
    
    [system:vars]
    node_group=system
    
    [worker]
    worker-0
    worker-1
    
    [worker:vars]
    node_group=worker
    
  5. Запустите выполнение playbook’а с использованием inventory-файла.

Как вручную очистить статический узел?

Инструкция справедлива как для узла, настроенного вручную (с помощью бутстрап-скрипта), так и для узла, настроенного с помощью CAPS.

Чтобы вывести из кластера узел и очистить сервер (ВМ), выполните следующую команду на узле:

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

Можно ли удалить StaticInstance?

StaticInstance, находящийся в состоянии Pending можно удалять без каких-либо проблем.

Чтобы удалить StaticInstance находящийся в любом состоянии, отличном от Pending (Running, Cleaning, Bootstrapping), выполните следующие шаги:

  1. Добавьте лейбл "node.deckhouse.io/allow-bootstrap": "false" в StaticInstance.

    Пример команды для добавления лейбла:

    d8 k label staticinstance d8cluster-worker node.deckhouse.io/allow-bootstrap=false
    
  2. Дождитесь, пока StaticInstance перейдет в статус Pending.

    Для проверки статуса StaticInstance используйте команду:

    d8 k get staticinstances
    
  3. Удалите StaticInstance.

    Пример команды для удаления StaticInstance:

    d8 k delete staticinstance d8cluster-worker
    
  4. Уменьшите значение параметра NodeGroup.spec.staticInstances.count на 1.

Как изменить IP-адрес StaticInstance?

Изменить IP-адрес в ресурсе StaticInstance нельзя. Если в StaticInstance указан ошибочный адрес, то нужно удалить StaticInstance и создать новый.

Как мигрировать статический узел настроенный вручную под управление CAPS?

Необходимо выполнить очистку узла, затем добавить узел под управление CAPS.

Почему SSH-ключ и sudo-пароль в SSHCredentials отображаются как <omitted>?

Параметры privateSSHKey, sudoPassword (v1alpha1) и sudoPasswordEncoded (v1alpha2) ресурса SSHCredentials содержат конфиденциальные данные и защищены от просмотра.

Если у пользователя нет прав на чтение конфиденциальных данных SSHCredentials, API возвращает <omitted> вместо фактического значения. При этом остальные параметры — user, sshPort, sshExtraArgs — и метаданные ресурса остаются доступными пользователям, которым разрешено чтение SSHCredentials.

Дополнительно kube-apiserver защищает эти данные следующим образом:

  • удаляет аннотацию kubectl.kubernetes.io/last-applied-configuration из ответов API, если она может содержать копию конфиденциальных значений;
  • заменяет конфиденциальные значения на "******" в событиях аудита независимо от прав пользователя и уровня аудита;
  • шифрует ресурс в etcd с использованием того же механизма, что и для секретов Kubernetes, если включён параметр apiserver.encryptionEnabled модуля control-plane-manager.

Незамаскированные значения доступны контроллеру CAPS, которому они необходимы для подключения к узлу по SSH, а также пользователям с уровнем доступа SuperAdmin и участникам группы kubeadm:cluster-admins.

Роли d8:subsystem:cluster:viewer и d8:subsystem:cluster:manager позволяют читать ресурс SSHCredentials, но не предоставляют доступ к SSH-ключу и sudo-паролю.

Чтобы проверить, может ли пользователь читать конфиденциальные данные SSHCredentials, выполните:

d8 k auth can-i get sshcredentials/sensitive --as=<user>

Значение <omitted> означает, что фактическое значение скрыто от текущего пользователя. Это поведение применяется как к v1alpha1, так и к v1alpha2, поэтому использование другой версии API не позволяет получить скрытые данные.

Как изменить NodeGroup у статического узла?

Если узел находится под управлением CAPS, то изменить принадлежность к NodeGroup у такого узла нельзя. Единственный вариант — удалить StaticInstance и создать новый.

Чтобы перенести существующий статический узел созданный вручную из одной NodeGroup в другую, необходимо изменить у узла лейбл группы:

d8 k label node --overwrite <node_name> node.deckhouse.io/group=<new_node_group_name>
d8 k label node <node_name> node-role.kubernetes.io/<old_node_group_name>-

Применение изменений потребует некоторого времени.

Как очистить узел для последующего ввода в кластер?

Это необходимо только в том случае, если нужно переместить статический узел из одного кластера в другой. Имейте в виду, что эти операции удаляют данные локального хранилища. Если необходимо просто изменить NodeGroup, следуйте этой инструкции.

Если на зачищаемом узле есть пулы хранения LINSTOR/DRBD, то предварительно перенесите ресурсы с узла и удалите узел LINSTOR/DRBD, следуя инструкции.

Для всех узлов кроме control-plane

  1. Удалите узел из кластера Kubernetes:

    d8 k drain <node> 
    d8 k drain <node> --ignore-daemonsets --delete-emptydir-data 
    d8 k delete pods --all-namespaces --field-selector spec.nodeName=<node> --force 
    d8 k delete node <node>
    
  2. Запустите на узле скрипт очистки:

    bash /var/lib/bashible/cleanup_static_node.sh --yes-i-am-sane-and-i-understand-what-i-am-doing
    
  3. После перезагрузки узла запустите скрипт bootstrap.sh.

Для узлов control-plane

  1. Снимите лейблы node-role.kubernetes.io/control-plane, node-role.kubernetes.io/master и node.deckhouse.io/group с узла:

    d8 k label node <node> node-role.kubernetes.io/control-plane- node-role.kubernetes.io/master- node.deckhouse.io/group-
    
  2. Убедитесь, что удаляемый узел с control-plane пропал из списка членов кластера etcd:

    d8 k -n kube-system exec -ti $(d8 k -n kube-system get pod -l component=etcd,tier=control-plane -o name | head -n1) -- 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
    
  3. Удалите узел из кластера Kubernetes:

    d8 k drain <node> 
    d8 k drain <node> --ignore-daemonsets --delete-emptydir-data
    d8 k delete pods --all-namespaces --field-selector spec.nodeName=<node> --force 
    d8 k delete node <node>
    
  4. Запустите на узле скрипт очистки:

    bash /var/lib/bashible/cleanup_static_node.sh --yes-i-am-sane-and-i-understand-what-i-am-doing
    
  5. После перезагрузки узла запустите скрипт bootstrap.sh.

  6. Дождитесь прохождения очередей Deckhouse и убедитесь, что член кластера etcd снова появился в списке:

    d8 k -n kube-system exec -ti $(d8 k -n kube-system get pod -l component=etcd,tier=control-plane -o name | head -n1) -- 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
    

Как понять, что что-то пошло не так?

Если узел в NodeGroup не обновляется (значение UPTODATE при выполнении команды d8 k get nodegroup меньше значения NODES) или вы предполагаете какие-то другие проблемы, которые могут быть связаны с модулем node-manager, нужно проверить логи сервиса bashible. Сервис bashible запускается на каждом узле, управляемом модулем node-manager.

Чтобы проверить логи сервиса bashible, выполните на узле следующую команду:

journalctl -fu bashible

Пример вывода, когда все необходимые действия выполнены:

May 25 04:39:16 kube-master-0 systemd[1]: Started Bashible service.
May 25 04:39:16 kube-master-0 bashible.sh[1976339]: Configuration is in sync, nothing to do.
May 25 04:39:16 kube-master-0 systemd[1]: bashible.service: Succeeded.

Как посмотреть, что в данный момент выполняется на узле при его создании?

Если необходимо узнать, что происходит на узле (например, узел долго создается), можно проверить логи cloud-init. Для этого выполните следующие шаги:

  1. Найдите узел, который находится в стадии бутстрапа:

    d8 k get instances | grep Pending
    

    Пример:

    d8 k get instances | grep Pending
    dev-worker-2a6158ff-6764d-nrtbj   Pending   46s
    
  2. Получите информацию о параметрах подключения для просмотра логов:

    d8 k get instances dev-worker-2a6158ff-6764d-nrtbj -o yaml | grep 'bootstrapStatus' -B0 -A2
    

    Пример:

    d8 k get instances dev-worker-2a6158ff-6764d-nrtbj -o yaml | grep 'bootstrapStatus' -B0 -A2
    bootstrapStatus:
      description: Use 'curl -N http://192.168.199.158:8000' to get bootstrap logs.
      logsEndpoint: http://192.168.199.158:8000
    
  3. Выполните полученную команду (в примере выше — curl -N http://192.168.199.158:8000), чтобы просмотреть логи cloud-init и определить, на каком этапе остановилась настройка узла.

Логи первоначальной настройки узла находятся в /var/log/cloud-init-output.log.

Как обновить ядро на узлах?

Для дистрибутивов, основанных на Debian

Создайте ресурс NodeGroupConfiguration, указав в переменной desired_version shell-скрипта (параметр spec.content ресурса) желаемую версию ядра:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: install-kernel.sh
spec:
  bundles:
    - '*'
  nodeGroups:
    - '*'
  weight: 32
  content: |
    # Copyright 2022 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.

    desired_version="5.15.0-53-generic"

    bb-event-on 'bb-package-installed' 'post-install'
    post-install() {
      bb-log-info "Setting reboot flag due to kernel was updated"
      bb-flag-set reboot
    }

    version_in_use="$(uname -r)"

    if [[ "$version_in_use" == "$desired_version" ]]; then
      exit 0
    fi

    bb-deckhouse-get-disruptive-update-approval
    bb-apt-install "linux-image-${desired_version}"

Для дистрибутивов, основанных на CentOS

Создайте ресурс NodeGroupConfiguration, указав в переменной desired_version shell-скрипта (параметр spec.content ресурса) желаемую версию ядра:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: install-kernel.sh
spec:
  bundles:
    - '*'
  nodeGroups:
    - '*'
  weight: 32
  content: |
    # Copyright 2022 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.

    desired_version="3.10.0-1160.42.2.el7.x86_64"

    bb-event-on 'bb-package-installed' 'post-install'
    post-install() {
      bb-log-info "Setting reboot flag due to kernel was updated"
      bb-flag-set reboot
    }

    version_in_use="$(uname -r)"

    if [[ "$version_in_use" == "$desired_version" ]]; then
      exit 0
    fi

    bb-deckhouse-get-disruptive-update-approval
    bb-dnf-install "kernel-${desired_version}"

На что влияют параметры NodeGroup?

Параметр NG Disruption update Перезаказ узлов Рестарт kubelet
chaos - - -
cloudInstances.classReference - + -
cloudInstances.maxSurgePerZone - - -
cri.containerd.maxConcurrentDownloads - - +
cri.type - (NotManaged) / + (other) - -
disruptions - - -
kubelet.maxPods - - +
kubelet.rootDir - - +
kubelet.topologyManager + (политика, отличная от None, подробнее) - +
kubernetesVersion - - +
nodeTemplate - - -
static - - +
update.maxConcurrent - - -

Подробно о всех параметрах можно прочитать в описании кастомного ресурса NodeGroup.

При изменении параметров InstanceClass или instancePrefix будет происходить процесс, аналогичный обновлению Deployment в Kubernetes (при изменении InstanceClass будет создан новый MachineSet, а при изменении instancePrefix — новый MachineDeployment). Новые инстансы будут создаваться в соответствии со значением параметра cloudInstances.maxSurgePerZone. По мере их создания старые инстансы будут постепенно удаляться с предварительным выполнением операции drain.

При обновлении, которое требует прерывания работы узла (disruption update), выполняется процесс вытеснения подов с узла. Если какой-либо под не может быть вытеснен, попытка повторяется каждые 20 секунд до достижения глобального таймаута в 5 минут. После истечения этого времени, поды, которые не удалось вытеснить, удаляются принудительно.

Как пересоздать эфемерные машины в облаке с новой конфигурацией?

При изменении конфигурации Deckhouse (как в модуле node-manager, так и в любом из облачных провайдеров) виртуальные машины не будут перезаказаны. Пересоздание происходит только после изменения ресурсов InstanceClass или NodeGroup.

Чтобы принудительно пересоздать все узлы, связанные с ресурсом Machines, следует добавить/изменить аннотацию manual-rollout-id в NodeGroup: d8 k annotate NodeGroup имя_ng "manual-rollout-id=$(uuidgen)" --overwrite.

Как выделить узлы под специфические нагрузки?

Запрещено использование домена deckhouse.io в ключах labels и taints у NodeGroup. Он зарезервирован для компонентов Deckhouse. Следует отдавать предпочтение в пользу ключей dedicated или dedicated.client.com.

Для решений данной задачи существуют два механизма:

  1. Установка лейблов в NodeGroup spec.nodeTemplate.labels для последующего использования их в Pod spec.nodeSelector или spec.affinity.nodeAffinity. Указывает, какие именно узлы будут выбраны планировщиком для запуска целевого приложения.
  2. Установка ограничений в NodeGroup spec.nodeTemplate.taints с дальнейшим снятием их в Pod spec.tolerations. Запрещает исполнение не разрешенных явно приложений на этих узлах.

Deckhouse по умолчанию поддерживает использование taint’а с ключом dedicated, поэтому рекомендуется применять этот ключ с любым значением для taints на ваших выделенных узлах.

Если требуется использовать другие ключи для taints (например, dedicated.client.com), необходимо добавить соответствующее значение ключа в массив .spec.settings.modules.placement.customTolerationKeys. Это обеспечит разрешение системным компонентам, таким как cni-flannel, использовать эти узлы.

Подробности в статье на Habr.

Как выделить подам отдельные CPU и выровнять их по NUMA?

Используйте параметр spec.kubelet.topologyManager в NodeGroup. Deckhouse настроит менеджеры CPU, памяти и топологии kubelet и рассчитает значения, зависящие от NUMA, на каждом узле группы.

Результат зависит от policy:

policy Что получают поды Настройки kubelet
None (по умолчанию) Ничего, все поды делят все CPU Не задаются, используются значения kubelet по умолчанию
BestEffort Эксклюзивные CPU для контейнеров Guaranteed-подов с целым числом CPU, память, закреплённая за NUMA-узлами. NUMA-выравнивание CPU, памяти и устройств, если возможно cpuManagerPolicy: static, memoryManagerPolicy: Static, topologyManagerPolicy: best-effort
Restricted Эксклюзивные целые физические ядра. Под получает CPU, память и устройства из наименьшего возможного набора NUMA-узлов, иначе отклоняется cpuManagerPolicy: static с full-pcpus-only, memoryManagerPolicy: Static, topologyManagerPolicy: restricted
SingleNumaNode Эксклюзивные целые физические ядра. CPU, память и устройства берутся из одного NUMA-узла, иначе под отклоняется cpuManagerPolicy: static с full-pcpus-only, memoryManagerPolicy: Static, topologyManagerPolicy: single-numa-node

Параметр scope задаёт, что выравнивается, для всех политик, кроме None: Pod (по умолчанию) выравнивает все контейнеры пода вместе, Container выравнивает каждый контейнер отдельно.

Параметр enabled устарел и ни на что не влияет: менеджерами управляет только policy. Чтобы выключить их, задайте policy: None.

Для всех политик, кроме None, Deckhouse также:

  • распределяет reservedMemory по NUMA-узлам пропорционально их памяти без hugepages;
  • включает prefer-closest-numa-nodes для Restricted, если узел сообщает полную таблицу расстояний между NUMA-узлами, а их номера идут подряд с 0;
  • задаёт max-allowable-numa-nodes, если NUMA-узлов больше 8.

Для политик BestEffort, Restricted и SingleNumaNode нужен resourceReservation.mode Auto или Static с положительным static.cpu.

При любой политике, кроме None, в том числе при BestEffort, память Guaranteed-пода закрепляется за NUMA-узлами, выбранными при допуске. Под, память которого не удаётся разместить, отклоняется с UnexpectedAdmissionError. Контейнер может быть завершён OOM killer, когда на его NUMA-узлах заканчивается память, даже если на других NUMA-узлах она свободна.

Эксклюзивные CPU забираются из общего пула. Burstable- и BestEffort-поды, включая системные компоненты, работают на оставшихся CPU. Это заметно для подов, которые потребляют больше CPU, чем запрашивают: без эксклюзивных CPU они используют простой всех ядер, а с эксклюзивными CPU делят оставшиеся. В режиме Auto общий пул может сократиться до 1 CPU. При необходимости используйте Static с большим static.cpu.

NodeGroup ниже выделяет Guaranteed-подам на узлах worker-dpdk целые физические ядра в одном NUMA-узле:

apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: worker-dpdk
spec:
  nodeType: Static
  kubelet:
    topologyManager:
      policy: SingleNumaNode
    resourceReservation:
      mode: Auto

Эксклюзивные CPU получают только контейнеры Guaranteed-подов с целым числом CPU: в каждом контейнере requests равны limits по CPU и памяти, а значение CPU целое:

apiVersion: v1
kind: Pod
metadata:
  name: dpdk-app
spec:
  containers:
  - name: app
    image: registry.example.com/dpdk-app:latest
    resources:
      requests:
        cpu: "4"
        memory: 8Gi
      limits:
        cpu: "4"
        memory: 8Gi

Правила политик Restricted и SingleNumaNode

  • Число CPU контейнера должно быть кратно числу потоков на ядро. При включённом SMT (Hyper-Threading) нечётное число CPU отклоняется с SMTAlignmentError.
  • При SingleNumaNode под (при scope: Pod) или каждый контейнер (при scope: Container) должен помещаться в один NUMA-узел. Рассчитывайте размер подов по самому маленькому NUMA-узлу группы.
  • Под, который не удаётся выровнять, отклоняется: с TopologyAffinityError, если не помещаются CPU, и с UnexpectedAdmissionError, если не помещается память.
  • Планировщик не знает о NUMA-узлах. Он может назначить под на узел, где под затем будет отклонён. Контроллер пода (например, Deployment или StatefulSet) создаст новый под, который тоже может быть отклонён.

Изменение настроек

Изменение policy, а при политике, отличной от None, и scope перезапускает kubelet на узлах группы.

Узел запрашивает прерывание работы (disruption), если выполнены все условия:

  • новая конфигурация kubelet использует политику, отличную от None;
  • меняются настройки CPU или памяти kubelet, например policy, scope, резерв CPU или памяти в resourceReservation или объём памяти либо hugepages на узле. Другие резервы, например ephemeralStorage, прерывания не вызывают;
  • на узле работают Guaranteed-поды. Поды DaemonSet и статические поды не учитываются, потому что drain их не вытесняет.

Прерывание обрабатывается по настройкам disruptions группы:

  • при approvalMode: Automatic выполняется drain узла, затем узел получает новую конфигурацию;
  • при approvalMode: Automatic и automatic.drainBeforeApproval: false drain не выполняется. После перезапуска kubelet работающие поды, не подходящие под новую политику, будут остановлены;
  • при approvalMode: Manual drain автоматически не выполняется. Выполните drain узла, затем выполните d8 k annotate node <NODE_NAME> update.node.deckhouse.io/disruption-approved=;
  • при approvalMode: RollingUpdate (только облачные узлы) узел заменяется новым.

Переход на None не вызывает drain: работающие контейнеры сохраняют свои CPU и NUMA-узел памяти до пересоздания. Чтобы распределить их по всем CPU, перезапустите нагрузку, например командой d8 k rollout restart.

Ограничения

  • Узлы с более чем 8 NUMA-узлами поддерживаются, но допуск подов на них занимает больше времени.
  • Узлы одной группы могут иметь разную NUMA-раскладку. Каждый узел получает свои значения, но предельный размер пода задаёт самый маленький NUMA-узел.
  • Скрипты NodeGroupConfiguration не должны менять резервы и политики менеджеров в /var/lib/kubelet/config.yaml.
  • Выделяйте hugepages до настройки kubelet. Шаги NodeGroupConfiguration выполняются по порядку weight вместе со встроенными шагами, а kubelet настраивается на шаге 64, поэтому используйте weight меньше 64. Распределение резерва по NUMA-узлам учитывает hugepages, выделенные к этому моменту. Выделенные позже hugepages меняют распределение и могут вызвать ещё один drain, если на узле работают Guaranteed-поды.

Как выделить узлы под системные компоненты?

Фронтенд

Для Ingress-контроллеров используйте NodeGroup со следующей конфигурацией:

nodeTemplate:
  labels:
    node-role.deckhouse.io/frontend: ""
  taints:
    - effect: NoExecute
      key: dedicated.deckhouse.io
      value: frontend

Системные

Для компонентов подсистем Deckhouse параметр NodeGroup будет настроен с параметрами:

nodeTemplate:
  labels:
    node-role.deckhouse.io/system: ""
  taints:
    - effect: NoExecute
      key: dedicated.deckhouse.io
      value: system

Как ускорить заказ узлов в облаке при горизонтальном масштабировании приложений?

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

Необходимые настройки целевой NodeGroup будут следующие:

  1. Указать абсолютное количество предварительно подготовленных узлов (или процент от максимального количества узлов в этой группе) в параметре cloudInstances.standby.
  2. При наличии на узлах дополнительных служебных компонентов, не обслуживаемых Deckhouse (например, DaemonSet filebeat), задать их процентное потребление ресурсов узла можно в параметре standbyHolder.overprovisioningRate.
  3. Для работы этой функции требуется, чтобы как минимум один узел из группы уже был запущен в кластере. Иными словами, либо должна быть доступна одна реплика приложения, либо количество узлов для этой группы cloudInstances.minPerZone должно быть 1.

Пример:

cloudInstances:
  maxPerZone: 10
  minPerZone: 1
  standby: 10%
  standbyHolder:
    overprovisioningRate: 30%

Как выключить machine-controller-manager/CAPI в случае выполнения потенциально деструктивных изменений в кластере?

Использовать эту настройку допустимо только тогда, когда вы четко понимаете, зачем это необходимо.

Для того чтобы временно отключить machine-controller-manager (MCM) и предотвратить его автоматические действия, которые могут повлиять на инфраструктуру кластера (например, удаление или пересоздание узлов), установите следующий параметр в конфигурации:

mcmEmergencyBrake: true

Для отключения CAPI установите следующий параметр в конфигурации:

capiEmergencyBrake: true

Как восстановить master-узел, если kubelet не может загрузить компоненты control plane?

Подобная ситуация может возникнуть, если в кластере с одним master-узлом на нем были удалены образы компонентов control plane (например, удалена директория /var/lib/containerd). В этом случае kubelet при рестарте не сможет скачать образы компонентов control plane, поскольку на master-узле нет параметров авторизации в registry.deckhouse.ru.

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

containerd

Для восстановления работоспособности master-узла нужно в любом рабочем кластере под управлением Deckhouse выполнить команду:

d8 k -n d8-system get secrets deckhouse-registry -o json |
jq -r '.data.".dockerconfigjson"' | base64 -d |
jq -r '.auths."registry.deckhouse.ru".auth'

Вывод команды нужно скопировать и присвоить переменной AUTH на поврежденном master-узле.

Далее на поврежденном master-узле нужно загрузить образы компонентов control-plane:

for image in $(grep "image:" /etc/kubernetes/manifests/* | awk '{print $3}'); do
  crictl pull --auth $AUTH $image
done

После загрузки образов необходимо перезапустить kubelet.

Как изменить CRI для NodeGroup?

Смена CRI возможна только между Containerd на NotManaged и обратно (параметр cri.type).

Для изменения CRI для NodeGroup, установите параметр cri.type в Containerd или в NotManaged.

Пример YAML-манифеста NodeGroup:

apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: worker
spec:
  nodeType: Static
  cri:
    type: Containerd

Также эту операцию можно выполнить с помощью патча:

  • Для Containerd:

    d8 k patch nodegroup <имя NodeGroup> --type merge -p '{"spec":{"cri":{"type":"Containerd"}}}'
    
  • Для NotManaged:

    d8 k patch nodegroup <имя NodeGroup> --type merge -p '{"spec":{"cri":{"type":"NotManaged"}}}'
    

При изменении cri.type для NodeGroup, созданных с помощью dhctl, необходимо обновить это значение в dhctl config edit provider-cluster-configuration и настройках объекта NodeGroup.

После изменения CRI для NodeGroup модуль node-manager будет поочередно перезагружать узлы, применяя новый CRI. Обновление узла сопровождается простоем (disruption). В зависимости от настройки disruption для NodeGroup, модуль node-manager либо автоматически выполнит обновление узлов, либо потребует подтверждения вручную.

Почему изменение CRI могло не примениться?

При попытке сменить CRI изменения могут не вступить в силу. Наиболее частая причина — наличие на узлах лейблов node.deckhouse.io/containerd-v2-unsupported и node.deckhouse.io/containerd-config=custom.

Лейбл node.deckhouse.io/containerd-v2-unsupported добавляется на узел, если выполняется хотя бы одно из следующих условий:

  • Версия ядра ниже 5.8;
  • Версия ядра Linux входит в диапазоны 6.12.0–6.12.28 или 6.14.0–6.14.6 (эти версии подвержены уязвимости CVE-2025-37999 в EROFS);
  • Версия systemd ниже 244;
  • Отсутствует cgroup v2;
  • Недоступна файловая система EROFS.

Лейбл node.deckhouse.io/containerd-config=custom выставляется, если на узле присутствуют файлы с расширением .toml в директориях /etc/containerd/conf.d/ (если на узлах кластера используется CRI containerd v1) или /etc/containerd/conf2.d/ (если на узлах кластера используется CRI containerd v2). Файлы d8-gpu-*.toml модуля gpu не учитываются. В этом случае следует удалить такие файлы (если это не повлечёт критичных последствий для работы контейнеров) и удалить соответствующие ресурсы NodeGroupConfiguration (NGC), с помощью которых они могли быть добавлены.

Если используется виртуализация Deckhouse Platform, причиной невозможности смены CRI может быть NGC containerd-dvcr-config.sh. Если платформа виртуализации уже установлена и работает, этот NGC можно удалить.

Если нет возможности удалить ресурс NodeGroupConfiguration, вносящий изменения в конфигурацию containerd и несовместимый с версией containerd v2, используйте универсальный шаблон:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
spec:
  bundles:
  - '*'
  content: |
    {{- if eq .cri "ContainerdV2" }}
  # <Скрипт для изменения конфигурации для ContainerdV2>.
    {{- else }}
  # <Скрипт для изменения конфигурации для ContainerdV1>.
    {{- end }}
  nodeGroups:
  - '*'
  weight: 31

Кроме того, для смены CRI может понадобиться снять пользовательский лейбл node.deckhouse.io/containerd-config=custom. Сделать это можно с помощью команды:

for node in $(d8 k get nodes -l node-role.kubernetes.io/<Название NodeGroup, где меняется CRI>=); do d8 k label $node node.deckhouse.io/containerd-config-; done

Как изменить CRI для всего кластера?

Смена CRI возможна только между Containerd на NotManaged и обратно (параметр cri.type).

Для изменения CRI для всего кластера, необходимо с помощью утилиты dhctl отредактировать параметр defaultCRI в конфигурационном файле cluster-configuration.

Также возможно выполнить эту операцию с помощью d8 k patch.

  • Для Containerd:

    data="$(d8 k -n kube-system get secret d8-cluster-configuration -o json | jq -r '.data."cluster-configuration.yaml"' | base64 -d | sed "s/NotManaged/Containerd/" | base64 -w0)"
    d8 k -n kube-system patch secret d8-cluster-configuration -p "{\"data\":{\"cluster-configuration.yaml\":\"$data\"}}"
    
  • Для NotManaged:

    data="$(d8 k -n kube-system get secret d8-cluster-configuration -o json | jq -r '.data."cluster-configuration.yaml"' | base64 -d | sed "s/Containerd/NotManaged/" | base64 -w0)"
    d8 k -n kube-system patch secret d8-cluster-configuration -p "{\"data\":{\"cluster-configuration.yaml\":\"$data\"}}"
    

Если необходимо, чтобы отдельные NodeGroup использовали другой CRI, перед изменением defaultCRI необходимо установить CRI для этой NodeGroup, как описано в документации.

Изменение defaultCRI влечет за собой изменение CRI на всех узлах, включая master-узлы. Если master-узел один, данная операция является опасной и может привести к полной неработоспособности кластера. Рекомендуется использовать multimaster-конфигурацию и менять тип CRI только после этого.

При изменении CRI в кластере для master-узлов необходимо выполнить дополнительные шаги:

  1. Чтобы определить, какой узел в текущий момент обновляется в master NodeGroup, используйте следующую команду:

    d8 k get nodes -l node-role.kubernetes.io/control-plane="" -o json | jq '.items[] | select(.metadata.annotations."update.node.deckhouse.io/approved"=="") | .metadata.name' -r
    
  2. Подтвердите остановку (disruption) для master-узла, полученного на предыдущем шаге:

    d8 k annotate node <имя master-узла> update.node.deckhouse.io/disruption-approved=
    
  3. Дождитесь перехода обновленного master-узла в Ready. Выполните итерацию для следующего master-узла.

Как добавить шаг для конфигурации узлов?

Дополнительные шаги для конфигурации узлов задаются с помощью кастомного ресурса NodeGroupConfiguration.

Как автоматически проставить на узел кастомные лейблы?

  1. На узле создайте каталог /var/lib/node_labels.

  2. Создайте в нём файл или файлы, содержащие необходимые лейблы. Количество файлов может быть любым, как и вложенность подкаталогов, их содержащих.

  3. Добавьте в файлы нужные лейблы в формате key=value. Например:

    example-label=test
    
  4. Сохраните файлы.

При добавлении узла в кластер указанные в файлах лейблы будут автоматически проставлены на узел.

Обратите внимание, что добавить таким образом лейблы, использующиеся в Deckhouse Platform, невозможно. Работать такой метод будет только с кастомными лейблами, не пересекающимися с зарезервированными для Deckhouse.

Как развернуть кастомный конфигурационный файл containerd?

Пример NodeGroupConfiguration основан на функциях, заложенных в скрипте 032_configure_containerd.sh.

Добавление кастомных настроек вызывает перезапуск сервиса containerd.

Bashible на узлах объединяет конфигурацию containerd для Deckhouse Platform с конфигурацией из файла:

  • /etc/containerd/conf.d/*.toml — если в качестве CRI на узлах кластера используется containerd v1;
  • /etc/containerd/conf2.d/*.toml — если в качестве CRI на узлах кластера используется containerd v2.

Вы можете переопределять значения параметров, которые заданы в файле /etc/containerd/deckhouse.toml, но их работу придётся обеспечивать самостоятельно. Также, лучше изменением конфигурации не затрагивать master-узлы (nodeGroup master).

Далее приведены примеры конфигурации ресурсов NodeGroupConfiguration, добавляющих кастомный конфигурационный файл для соответствующей версии containerd.

  • Для containerd v1
  • Для containerd v2
apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: containerd-option-config.sh
spec:
  bundles:
    - '*'
  content: |
    # Copyright 2024 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.

    mkdir -p /etc/containerd/conf.d
    bb-sync-file /etc/containerd/conf.d/additional_option.toml - << EOF
    oom_score = 500
    [metrics]
    address = "127.0.0.1"
    grpc_histogram = true
    EOF
  nodeGroups:
    - "worker"
  weight: 31
apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: containerd-option-config.sh
spec:
  bundles:
    - '*'
  content: |
    # Copyright 2024 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.

    mkdir -p /etc/containerd/conf2.d
    bb-sync-file /etc/containerd/conf2.d/runtimeclass.toml - << "EOF"
    [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.gpu-large-shm]
      runtime_type = "io.containerd.runc.v2"
      [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.gpu-large-shm.options]
        BinaryName = ""
        SystemdCgroup = true
        ShmSize = 17179869184
    EOF
  nodeGroups:
    - "worker"
  weight: 31

Как добавить конфигурацию для дополнительного registry?

В containerd существует два способа описания конфигурации registry: устаревший и актуальный.

Для проверки наличия устаревшего способа конфигурации выполните на узлах кластера следующие команды:

cat /etc/containerd/config.toml | grep 'plugins."io.containerd.grpc.v1.cri".registry.mirrors'
cat /etc/containerd/config.toml | grep 'plugins."io.containerd.grpc.v1.cri".registry.configs'

# Пример вывода:
# [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
#   [plugins."io.containerd.grpc.v1.cri".registry.mirrors."<REGISTRY_URL>"]
# [plugins."io.containerd.grpc.v1.cri".registry.configs]
#   [plugins."io.containerd.grpc.v1.cri".registry.configs."<REGISTRY_URL>".auth]

Для проверки наличия актуального способа конфигурации выполните на узлах кластера следующую команду:

cat /etc/containerd/config.toml | grep '/etc/containerd/registry.d'

# Пример вывода:
# config_path = "/etc/containerd/registry.d"

Устаревший способ

Этот формат конфигурации containerd устарел (deprecated).

Используется в containerd v1, если Deckhouse не управляется с помощью модуля registry.

Конфигурация описывается в основном конфигурационном файле containerd /etc/containerd/config.toml.

Пользовательская конфигурация добавляется через механизм toml merge. Конфигурационные файлы из директории /etc/containerd/conf.d объединяются с основным файлом /etc/containerd/config.toml. Применение merge происходит на этапе выполнения скрипта 032_configure_containerd.sh, поэтому соответствующие файлы должны быть добавлены заранее.

Пример конфигурационного файла для директории /etc/containerd/conf.d/:

[plugins]
  [plugins."io.containerd.grpc.v1.cri"]
    [plugins."io.containerd.grpc.v1.cri".registry]
      [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
        [plugins."io.containerd.grpc.v1.cri".registry.mirrors."${REGISTRY_URL}"]
          endpoint = ["https://${REGISTRY_URL}"]
      [plugins."io.containerd.grpc.v1.cri".registry.configs]
        [plugins."io.containerd.grpc.v1.cri".registry.configs."${REGISTRY_URL}".auth]
          auth = "${BASE_64_AUTH}"
          username = "${USERNAME}"
          password = "${PASSWORD}"
        [plugins."io.containerd.grpc.v1.cri".registry.configs."${REGISTRY_URL}".tls]
          ca_file = "${CERT_DIR}/${CERT_NAME}.crt"
          insecure_skip_verify = true

Добавление кастомных настроек через механизм toml merge вызывает перезапуск сервиса containerd.

Как добавить авторизацию в дополнительный registry (устаревший способ)?

Пример добавления авторизации в дополнительный registry при использовании устаревшего способа конфигурации:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: containerd-additional-config-auth.sh
spec:
  # Для добавления файла перед шагом '032_configure_containerd.sh'.
  weight: 31
  bundles:
    - '*'
  nodeGroups:
    - "*"
  content: |
    # Copyright 2023 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    
    REGISTRY_URL=private.registry.example

    mkdir -p /etc/containerd/conf.d
    bb-sync-file /etc/containerd/conf.d/additional_registry.toml - << EOF
    [plugins]
      [plugins."io.containerd.grpc.v1.cri"]
        [plugins."io.containerd.grpc.v1.cri".registry]
          [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
            [plugins."io.containerd.grpc.v1.cri".registry.mirrors."${REGISTRY_URL}"]
              endpoint = ["https://${REGISTRY_URL}"]
          [plugins."io.containerd.grpc.v1.cri".registry.configs]
            [plugins."io.containerd.grpc.v1.cri".registry.configs."${REGISTRY_URL}".auth]
              username = "username"
              password = "password"
              # OR
              auth = "dXNlcm5hbWU6cGFzc3dvcmQ="
    EOF
Как настроить сертификат для дополнительного registry (устаревший способ)?

Пример настройки сертификата для дополнительного registry при использовании устаревшего способа конфигурации:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: containerd-additional-config-tls.sh
spec:
  # Для добавления файла перед шагом '032_configure_containerd.sh'.
  weight: 31
  bundles:
    - '*'
  nodeGroups:
    - "*"
  content: |
    # Copyright 2023 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    
    REGISTRY_URL=private.registry.example
    CERT_FILE_NAME=${REGISTRY_URL}
    CERTS_FOLDER="/var/lib/containerd/certs/"


    mkdir -p ${CERTS_FOLDER}
    bb-sync-file "${CERTS_FOLDER}/${CERT_FILE_NAME}.crt" - << EOF
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
    EOF

    mkdir -p /etc/containerd/conf.d
    bb-sync-file /etc/containerd/conf.d/additional_registry.toml - << EOF
    [plugins]
      [plugins."io.containerd.grpc.v1.cri"]
        [plugins."io.containerd.grpc.v1.cri".registry]
          [plugins."io.containerd.grpc.v1.cri".registry.configs]
            [plugins."io.containerd.grpc.v1.cri".registry.configs."${REGISTRY_URL}".tls]
              ca_file = "${CERTS_FOLDER}/${CERT_FILE_NAME}.crt"
    EOF

Помимо containerd, сертификат можно добавить в операционную систему.

Как добавить TLS skip verify (устаревший способ)?

Пример добавления TLS skip verify при использовании устаревшего способа конфигурации:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: containerd-additional-config-skip-tls.sh
spec:
  # Для добавления файла перед шагом '032_configure_containerd.sh'.
  weight: 31
  bundles:
    - '*'
  nodeGroups:
    - "*"
  content: |
    # Copyright 2023 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    
    REGISTRY_URL=private.registry.example

    mkdir -p /etc/containerd/conf.d
    bb-sync-file /etc/containerd/conf.d/additional_registry.toml - << EOF
    [plugins]
      [plugins."io.containerd.grpc.v1.cri"]
        [plugins."io.containerd.grpc.v1.cri".registry]
          [plugins."io.containerd.grpc.v1.cri".registry.configs]
            [plugins."io.containerd.grpc.v1.cri".registry.configs."${REGISTRY_URL}".tls]
              insecure_skip_verify = true
    EOF

После применения конфигурационного файла проверьте доступ к registry с узлов, используя команду:

# Через cri-интерфейс.
crictl pull private.registry.example/image/repo:tag
Как настроить зеркало для доступа к публичным registries (устаревший способ)?

Пример настройки зеркала к публичным registries при использовании устаревшего способа конфигурации:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: mirror-to-harbor.sh
spec:
  weight: 31
  bundles:
    - '*'
  nodeGroups:
    - "*"
  content: |
    # Copyright 2023 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.

    sed -i '/endpoint = \["https:\/\/registry-1.docker.io"\]/d' /var/lib/bashible/bundle_steps/032_configure_containerd.sh
    mkdir -p /etc/containerd/conf.d
    bb-sync-file /etc/containerd/conf.d/mirror-to-harbor.toml - << "EOF"
    [plugins]
      [plugins."io.containerd.grpc.v1.cri"]
        [plugins."io.containerd.grpc.v1.cri".registry]
          [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
            [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
              endpoint = ["https://registry.private.network/v2/dockerhub-proxy/"]
            [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
              endpoint = ["https://registry.private.network/v2/YOUR_GCR_PROXY_REPO/"]
    EOF

Новый способ

Используется в containerd v2.

Используется в containerd v1, если управление осуществляется через модуль registry (например, в режиме Direct).

Конфигурация описывается в каталоге /etc/containerd/registry.d и задаётся через создание подкаталогов с именами, соответствующими адресу registry:

/etc/containerd/registry.d
├── private.registry.example:5001
│   ├── ca.crt
│   └── hosts.toml
└── registry.deckhouse.ru
    ├── ca.crt
    └── hosts.toml

Пример содержимого файла hosts.toml:

[host]
  # Mirror 1.
  [host."https://${REGISTRY_URL_1}"]
    capabilities = ["pull", "resolve"]
    ca = ["${CERT_DIR}/${CERT_NAME}.crt"]

    [host."https://${REGISTRY_URL_1}".auth]
      username = "${USERNAME}"
      password = "${PASSWORD}"

  # Mirror 2.
  [host."http://${REGISTRY_URL_2}"]
    capabilities = ["pull", "resolve"]
    skip_verify = true

Изменения конфигураций не приводят к перезапуску сервиса containerd.

Как добавить авторизацию в дополнительный registry (актуальный способ)?

Пример добавления авторизации в дополнительный registry при использовании актуального способа конфигурации:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: containerd-additional-config-auth.sh
spec:
  # Шаг может быть любой, т.к. не требуется перезапуск сервиса containerd.
  weight: 0
  bundles:
    - '*'
  nodeGroups:
    - "*"
  content: |
    # Copyright 2023 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    
    REGISTRY_URL=private.registry.example

    mkdir -p "/etc/containerd/registry.d/${REGISTRY_URL}"
    bb-sync-file "/etc/containerd/registry.d/${REGISTRY_URL}/hosts.toml" - << EOF
    [host]
      [host."https://${REGISTRY_URL}"]
        capabilities = ["pull", "resolve"]
        [host."https://${REGISTRY_URL}".auth]
          username = "username"
          password = "password"
    EOF
Как настроить сертификат для дополнительного registry (актуальный способ)?

Пример настройки сертификата для дополнительного registry при использовании актуального способа конфигурации:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: containerd-additional-config-tls.sh
spec:
  # Шаг может быть любой, тк не требуется перезапуск сервиса containerd.
  weight: 0
  bundles:
    - '*'
  nodeGroups:
    - "*"
  content: |
    # Copyright 2023 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    
    REGISTRY_URL=private.registry.example

    mkdir -p "/etc/containerd/registry.d/${REGISTRY_URL}"

    bb-sync-file "/etc/containerd/registry.d/${REGISTRY_URL}/ca.crt" - << EOF
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
    EOF

    bb-sync-file "/etc/containerd/registry.d/${REGISTRY_URL}/hosts.toml" - << EOF
    [host]
      [host."https://${REGISTRY_URL}"]
        capabilities = ["pull", "resolve"]
        ca = ["/etc/containerd/registry.d/${REGISTRY_URL}/ca.crt"]
    EOF

Помимо containerd, сертификат можно добавить в операционную систему.

Как добавить TLS skip verify (актуальный способ)?

Пример добавления TLS skip verify при использовании актуального способа конфигурации:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: containerd-additional-config-skip-tls.sh
spec:
  # Шаг может быть любой, тк не требуется перезапуск сервиса containerd.
  weight: 0
  bundles:
    - '*'
  nodeGroups:
    - "*"
  content: |
    # Copyright 2023 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.
    
    REGISTRY_URL=private.registry.example

    mkdir -p "/etc/containerd/registry.d/${REGISTRY_URL}"
    bb-sync-file "/etc/containerd/registry.d/${REGISTRY_URL}/hosts.toml" - << EOF
    [host]
      [host."https://${REGISTRY_URL}"]
        capabilities = ["pull", "resolve"]
        skip_verify = true
    EOF

После применения конфигурационного файла проверьте доступ к registry с узлов, используя команды:

# Через cri интерфейс.
crictl pull private.registry.example/image/repo:tag

# Через ctr с указанием директории с конфигурациями.
ctr -n k8s.io images pull --hosts-dir=/etc/containerd/registry.d/ private.registry.example/image/repo:tag

# Через ctr для http репозитория.
ctr -n k8s.io images pull --hosts-dir=/etc/containerd/registry.d/ --plain-http private.registry.example/image/repo:tag
Как настроить зеркало для доступа к публичным registries (актуальный способ)?

Пример настройки зеркала к публичным registries при использовании актуального способа конфигурации:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: mirror-to-harbor.sh
spec:
  weight: 31
  bundles:
    - '*'
  nodeGroups:
    - "*"
  content: |
    # Copyright 2023 Flant JSC
    #
    # Licensed under the Apache License, Version 2.0 (the "License");
    # you may not use this file except in compliance with the License.
    # You may obtain a copy of the License at
    #
    #     http://www.apache.org/licenses/LICENSE-2.0
    #
    # Unless required by applicable law or agreed to in writing, software
    # distributed under the License is distributed on an "AS IS" BASIS,
    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    # See the License for the specific language governing permissions and
    # limitations under the License.

    REGISTRY1_URL=docker.io
    mkdir -p "/etc/containerd/registry.d/${REGISTRY1_URL}"
    bb-sync-file "/etc/containerd/registry.d/${REGISTRY1_URL}/hosts.toml" - << EOF
    [host."https://registry.private.network/v2/dockerhub-proxy/"]
      capabilities = ["pull", "resolve"]
      override_path = true
    EOF
    REGISTRY2_URL=gcr.io
    mkdir -p "/etc/containerd/registry.d/${REGISTRY2_URL}"
    bb-sync-file "/etc/containerd/registry.d/${REGISTRY2_URL}/hosts.toml" - << EOF
    [host."https://registry.private.network/v2/dockerhub-proxy/"]
      capabilities = ["pull", "resolve"]
      override_path = true
    EOF

Как использовать NodeGroup с приоритетом?

С помощью параметра priority кастомного ресурса NodeGroup можно задавать порядок заказа узлов в кластере. Например, можно сделать так, чтобы сначала заказывались узлы типа spot-node, а если они закончились — обычные узлы. Или чтобы при наличии ресурсов в облаке заказывались узлы большего размера, а при их исчерпании — узлы меньшего размера.

Пример создания двух NodeGroup с использованием узлов типа spot-node:

---
apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: worker-spot
spec:
  cloudInstances:
    classReference:
      kind: AWSInstanceClass
      name: worker-spot
    maxPerZone: 5
    minPerZone: 0
    priority: 50
  nodeType: CloudEphemeral
---
apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: worker
spec:
  cloudInstances:
    classReference:
      kind: AWSInstanceClass
      name: worker
    maxPerZone: 5
    minPerZone: 0
    priority: 30
  nodeType: CloudEphemeral

В приведенном выше примере, cluster-autoscaler сначала попытается заказать узел типа _spot-node. Если в течение 15 минут его не получится добавить в кластер, NodeGroup worker-spot будет поставлен на паузу (на 20 минут) и cluster-autoscaler начнет заказывать узлы из NodeGroup worker. Если через 30 минут в кластере возникнет необходимость развернуть еще один узел, cluster-autoscaler сначала попытается заказать узел из NodeGroup worker-spot и только потом — из NodeGroup worker.

После того как NodeGroup worker-spot достигнет своего максимума (5 узлов в примере выше), узлы будут заказываться из NodeGroup worker.

Шаблоны узлов (labels/taints) для NodeGroup worker и worker-spot должны быть одинаковыми, или как минимум подходить для той нагрузки, которая запускает процесс увеличения кластера.

Как интерпретировать состояние группы узлов?

Ready — группа узлов содержит минимально необходимое число запланированных узлов с состоянием Ready для всех зон.

Пример 1. Группа узлов в состоянии Ready:

apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: ng1
spec:
  nodeType: CloudEphemeral
  cloudInstances:
    maxPerZone: 5
    minPerZone: 1
status:
  conditions:
  - status: "True"
    type: Ready
---
apiVersion: v1
kind: Node
metadata:
  name: node1
  labels:
    node.deckhouse.io/group: ng1
status:
  conditions:
  - status: "True"
    type: Ready

Пример 2. Группа узлов в состоянии Not Ready:

apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: ng1
spec:
  nodeType: CloudEphemeral
  cloudInstances:
    maxPerZone: 5
    minPerZone: 2
status:
  conditions:
  - status: "False"
    type: Ready
---
apiVersion: v1
kind: Node
metadata:
  name: node1
  labels:
    node.deckhouse.io/group: ng1
status:
  conditions:
  - status: "True"
    type: Ready

Updating — группа узлов содержит как минимум один узел, в котором присутствует аннотация с префиксом update.node.deckhouse.io (например, update.node.deckhouse.io/waiting-for-approval).

WaitingForDisruptiveApproval — группа узлов содержит как минимум один узел, в котором присутствует аннотация update.node.deckhouse.io/disruption-required и отсутствует аннотация update.node.deckhouse.io/disruption-approved.

Scaling — рассчитывается только для групп узлов с типом CloudEphemeral. Состояние True может быть в двух случаях:

  1. Когда число узлов меньше желаемого числа узлов в группе, то есть когда нужно увеличить число узлов в группе.
  2. Когда какой-то узел помечается к удалению или число узлов больше желаемого числа узлов, то есть когда нужно уменьшить число узлов в группе.

Желаемое число узлов — это сумма всех реплик, входящих в группу узлов.

Пример. Желаемое число узлов равно 2:

apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: ng1
spec:
  nodeType: CloudEphemeral
  cloudInstances:
    maxPerZone: 5
    minPerZone: 2
status:
...
  desired: 2
...

Error — содержит последнюю ошибку, возникшую при создании узла в группе узлов.

Как заставить werf игнорировать состояние Ready в группе узлов?

werf проверяет состояние Ready у ресурсов и в случае его наличия дожидается, пока значение станет True.

Создание (обновление) ресурса nodeGroup в кластере может потребовать значительного времени на развертывание необходимого количества узлов. При развертывании такого ресурса в кластере с помощью werf (например, в рамках процесса CI/CD) развертывание может завершиться по превышении времени ожидания готовности ресурса. Чтобы заставить werf игнорировать состояние nodeGroup, необходимо добавить к nodeGroup следующие аннотации:

metadata:
  annotations:
    werf.io/fail-mode: IgnoreAndContinueDeployProcess
    werf.io/track-termination-mode: NonBlocking

Что такое ресурс Instance?

Ресурс Instance в Kubernetes представляет собой описание объекта эфемерной виртуальной машины, но без конкретной реализации. Это абстракция, которая используется для управления машинами, созданными с помощью таких инструментов, как MachineControllerManager или Cluster API Provider Static.

Объект не содержит спецификации. Статус содержит:

  1. Ссылку на InstanceClass, если он существует для данной реализации.
  2. Ссылку на объект Node Kubernetes.
  3. Текущий статус машины.
  4. Информацию о том, как проверить логи создания машины (появляется на этапе создания машины).

При создании или удалении машины создается или удаляется соответствующий объект Instance. Самостоятельно ресурс Instance создать нельзя, но можно удалить. В таком случае машина будет удалена из кластера (процесс удаления зависит от деталей реализации).

Когда требуется перезагрузка узлов?

Некоторые операции по изменению конфигурации узлов могут потребовать перезагрузки.

Перезагрузка узла может потребоваться при изменении некоторых настроек sysctl, например, при изменении параметра kernel.yama.ptrace_scope (изменяется при использовании команды astra-ptrace-lock enable/disable в Astra Linux).

Как включить задержку выключения или перезагрузки узла, пока на нём работают критичные поды?

Доступно в редакциях EE, Ultimate.

Для принятия решения о блокировке выключения Deckhouse Platform дополнительно опрашивает NodeGroup. Если текущий узел принадлежит к группе master и является единственным master-узлом в кластере, блокировка выключения для него применена не будет.

Чтобы включить механизм задержки перезагрузки или выключения узла (далее просто «выключение узла»), добавьте на под лейбл pod.deckhouse.io/inhibit-node-shutdown (для Deployment укажите лейбл в шаблоне пода).

Пример манифеста пода с лейблом pod.deckhouse.io/inhibit-node-shutdown:

apiVersion: v1
kind: Pod
metadata:
  name: my-stateful-app
  labels:
    app: my-stateful-app
    pod.deckhouse.io/inhibit-node-shutdown: "true"
spec:
  containers:
    - name: app
      image: my-registry/my-app:1.0.0

Блокировка срабатывает только для подов с лейблом pod.deckhouse.io/inhibit-node-shutdown в фазе Running на узле. Поды без лейбла kubelet выключает по обычному сценарию graceful shutdown.

Поиск подов, блокирующих выключение, и диагностика на узле

Для поиска подов, из-за которых блокируется выключение узла, используйте команду:

d8 k get po -A -l pod.deckhouse.io/inhibit-node-shutdown -o wide

Для просмотра состояния GracefulShutdownPostpone на узле используйте команду:

d8 k get node <NODE_NAME> -o jsonpath='{range .status.conditions[?(@.type=="GracefulShutdownPostpone")]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

Возможные значения поля reason:

  • WaitingForShutdownSignal — на узле работает механизм блокировки выключения, но блокировка ещё не началась;
  • PodsWithLabelAreRunningOnNode — выключение заблокировано, поскольку на узле ещё работают поды с лейблом pod.deckhouse.io/inhibit-node-shutdown;
  • NoRunningPodsWithLabel — блокировка снята, выключение может быть продолжено.

Как настроить fencing для группы узлов?

Fencing защищает кластер от узлов, потерявших связь с ним. Узел, который не видит кластер, сам останавливает свою работу через kernel panic. После этого Kubernetes может безопасно перенести нагрузку на другие узлы.

Режим fencing задаётся в параметре spec.fencing.mode ресурса NodeGroup:

apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: worker
spec:
  nodeType: Static
  fencing:
    mode: Normal

Каждый режим выбирает встроенный профиль FencingSLAProfile. Профиль задаёт тайминги обнаружения отказа и таймаут watchdog:

Режим Профиль Через сколько агент считает control plane потерянным (controlPlaneLostAfter) Таймаут watchdog Реакция на отказ
Disabled нет нет нет Fencing выключен. Это режим по умолчанию.
Critical critical 4,15 с 5 с Около 12 с
Normal normal 9,1 с 15 с Около 30 с
Slow slow 20,2 с 30 с Около 60 с

Время реакции — целевое значение с допуском ±20 %. Отказавший узел останавливается не позже чем через controlPlaneLostAfter + 0,2 с + таймаут watchdog после отказа: 9,35 с в режиме Critical, 24,3 с в режиме Normal и 50,4 с в режиме Slow.

Короткий таймаут даёт быструю реакцию, но повышает риск ложной паники, когда кластер работает медленно. Режим Slow подходит для групп с нестабильной сетью или высокой нагрузкой. Режим Critical используйте, только если быстрая реакция важнее риска ложной паники.

Режим Critical доступен только в коммерческих редакциях Deckhouse. В Community Edition (CE) Deckhouse не позволяет задать группе узлов режим Critical. Группа, у которой этот режим уже задан (например, после переключения редакции на CE), работает как Normal.

Учитывайте следующее:

  • Значение Watchdog параметра spec.fencing.mode устарело и работает как Slow. Используйте Normal, Slow или Critical (Critical доступен только в коммерческих редакциях).
  • Параметр spec.fencing.watchdog.timeout устарел, Deckhouse его игнорирует. Таймаут watchdog берётся из профиля режима.
  • В кластере с одним master-узлом Deckhouse не позволяет включить fencing. Подробнее — в разделе «Fencing в кластере с одним master-узлом».
  • Deckhouse не позволяет менять режим группы узлов, пока у узла этой группы есть объект FencingFailedNodeState. Подробнее — в разделе «Известные ограничения эвакуации».
  • Если хотя бы у одной группы узлов режим отличается от Disabled, fencing-agent запускается на всех узлах кластера. На узлах группы с режимом Disabled агент только участвует в обнаружении отказов и не вооружает watchdog.
  • На узлах групп с режимом, отличным от Disabled, fencing устанавливает параметр ядра kernel.panic в 0. После fencing-паники узел сам не перезагружается.
  • Когда группе задают режим, отличный от Disabled, новый под агента на узле запускается только после того, как bashible загрузит softdog и появится /dev/watchdog. До этого под находится в состоянии ContainerCreating с событием FailedMount, и агент на узле не работает. Если у группы уже есть поды агента, DaemonSet заменяет их по 10 % узлов за раз. На узлах Deckhouse Engine softdog встроен в ядро, и под не ждёт. Если узел ждёт дольше 5 минут, срабатывает алерт D8FencingAgentDown. Когда bashible загрузит softdog, под запустится, и алерт прекратится. Действий не требуется. Если под не запускается, проверьте логи bashible на узле.

Как проверить состояние fencing на узлах?

Выполните команду:

d8 k get nodes -o custom-columns='NAME:.metadata.name,READY:.status.conditions[?(@.type=="Ready")].status,FENCING:.status.conditions[?(@.type=="Fencing")].reason,PROFILE:.metadata.annotations.node-manager\.deckhouse\.io/fencing-profile'

Колонка READY показывает статус condition Ready узла. Колонка FENCING показывает причину (reason) condition Fencing, например, Armed или GroupDisabled. Колонка PROFILE показывает аннотацию узла node-manager.deckhouse.io/fencing-profile. В аннотации указан FencingSLAProfile режима группы узлов (slow для устаревшего режима Watchdog), даже если watchdog узла не вооружён. Если у группы режим Disabled, в аннотации указано disabled. Если fencing-agent на узле не работает, в колонках FENCING и PROFILE выводится <none>. Например, так бывает, когда у всех групп узлов режим Disabled.

Если fencing остановил узел после потери связи с API-сервером, узел не может обновить свой condition Fencing. Пока узел не перезагрузится и агент не запустится снова, в колонке FENCING может оставаться Armed. Чтобы найти остановленный узел, смотрите на колонку READY: её значение не True.

Что происходит при перезапуске fencing-agent?

  • При плановой остановке агента, например при обновлении DaemonSet, удалении пода или выключении узла, агент разоружает watchdog. Узел не останавливается. Если агент уже перестал сбрасывать таймер после потери control plane, watchdog остаётся вооружённым.
  • Если агент упал или был убит, watchdog остаётся вооружённым. Отсчёт таймаута watchdog начинается с момента остановки процесса агента. При старте новый процесс агента проверяет, доступен ли control plane:
    • Если control plane доступен, агент разоружает watchdog, а затем вооружает его снова, как при обычном старте. До этого причина condition Fencing — не Armed.
    • Если control plane недоступен, агент не разоружает watchdog. Если агент не вооружит watchdog снова до истечения таймаута, узел остановится.
  • Если агент падает при каждом старте, а control plane доступен, узел обычно продолжает работать, но его watchdog не вооружён. Срабатывает алерт D8FencingAgentRestarted, причина condition Fencing — не Armed. Посмотрите логи агента и устраните причину падений.

Каковы ограничения softdog?

В качестве watchdog fencing использует модуль ядра softdog. Deckhouse загружает модуль с параметром soft_panic=1. Если fencing-agent перестаёт сбрасывать таймер, таймер истекает и ядро уходит в kernel panic.

softdog — это таймер того самого ядра, которое он должен защищать. При hard lockup ядра таймер не срабатывает, и узел не паникует. Если на узле есть аппаратный watchdog, используйте его вместо softdog: он срабатывает, даже когда ядро зависло.

Узлы Deckhouse Engine

На узлах групп с systemType: Immutable (Deckhouse Engine) softdog встроен в ядро. Скрипт NodeGroupConfiguration на этих узлах не выполняется.

На узлах, установленных до выпуска Deckhouse Engine со встроенным softdog, его нет. Такие узлы получают softdog только после переустановки или обновления загрузочного раздела.

Как fencing работает на master-узлах?

Fencing-agent обрабатывает master-узлы так же, как worker-узлы: действуют те же режимы и условия, особого правила для группы master нет.

Учитывайте следующее:

  • После fencing-паники master-узел сам не поднимается. Верните узел в кластер вручную. Если на узле работал etcd, верните узел в кластер etcd вручную.
  • Когда отказывает master-узел, taint на него ставится позже, чем на worker-узел, обычно на 10–20 секунд. kube-apiserver на других master-узлах отправляет запросы и в etcd на отказавшем master-узле и примерно 10 секунд ждёт ответа. Запросы fencing-controller тоже ждут. Действий не требуется.
  • fencing-controller работает на master-узлах. Если master-узел контроллера отказал или не готов, Kubernetes сразу вытесняет с него под контроллера, и контроллер запускается на другом master-узле. В этом случае taint на отказавший узел ставится позже: на время, за которое Kubernetes помечает master-узел недоступным (параметр nodeMonitorGracePeriodSeconds модуля control-plane-manager, по умолчанию 40 секунд), и на время запуска пода. В кластере без режима высокой доступности у контроллера одна реплика.

Fencing в кластере с одним master-узлом

Узел с fencing останавливается, когда теряет control plane. В кластере с одним master-узлом отказ или перезапуск этого узла останавливает все узлы с fencing. Кроме того, когда master-узел останавливается, поставить taint и перенести нагрузку становится некому. Поэтому Deckhouse не позволяет включить fencing в кластере с одним master-узлом:

  • Deckhouse отклоняет изменение NodeGroup, которое включает fencing, то есть меняет spec.fencing.mode с Disabled на другой режим.
  • При создании NodeGroup с режимом, отличным от Disabled, Deckhouse только выдаёт предупреждение. Так установка кластера с fencing в ресурсах установки не прерывается.
  • NodeGroup, у которой fencing уже включён, можно изменять как раньше. Уже включённый fencing Deckhouse не выключает.

Master-узлы Deckhouse считает так: узлы с лейблом node-role.kubernetes.io/control-plane, а если таких узлов нет — системные узлы с лейблом node-role.deckhouse.io/master.

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

Чтобы включить fencing в группе master, сначала добавьте в кластер master-узлы, а затем задайте режим группы.

Какие сетевые порты нужны для fencing?

Агенты fencing-agent на всех узлах соединяются друг с другом по порту 8500. Перед включением fencing откройте следующие правила доступа:

  • Порт 8500 TCP и UDP между InternalIP-адресами всех узлов кластера.
  • Порт 8500 UDP между адресами SystemNetwork на всех узлах. Это правило нужно, только если используется вторая сеть (параметр settings.fencing.systemNetworkFallback.systemNetworkName модуля node-manager). TCP для этой сети не нужен. Сейчас агенты не обмениваются сообщениями через вторую сеть. Правило нужно открыть заранее, для fallback через SystemNetwork.

Что означает алерт D8FencingSystemNetworkNotFound?

Алерт означает, что в параметре settings.fencing.systemNetworkFallback.systemNetworkName модуля node-manager указана SystemNetwork, которой нет в кластере. Агенты не могут использовать вторую сеть. Deckhouse параметр не меняет.

Чтобы устранить проблему, выполните одно из действий:

  • Создайте SystemNetwork.
  • Укажите имя существующей сети.
  • Удалите имя из параметра.

Учитывайте следующее:

  • Deckhouse проверяет существование SystemNetwork, когда вы задаёте параметру systemNetworkName новое непустое значение. Отклонить можно только такое изменение. Удаление значения и изменение остальных полей ModuleConfig проходят всегда, в том числе когда проверка недоступна.
  • При dhctl bootstrap проверка ещё не работает: Deckhouse принимает параметр без проверки. Если сети нет, алерт появляется после запуска модуля.
  • Алерт гаснет примерно через 10 минут после восстановления сети.
  • Пока у всех групп узлов режим Disabled, алерт не появляется: в этом случае агенты вторую сеть не используют. Алерт появится, когда вы включите fencing.

Как fencing защищает ключ сети?

Агенты fencing-agent используют общий ключ, чтобы шифровать сообщения друг другу. Ключ хранится в Secret fencing-memberlist-key в пространстве имён d8-cloud-instance-manager. Если удалить Secret, Deckhouse сгенерирует новый ключ и появится алерт D8FencingKeyRegenerated.

Получив новый ключ, агент сохраняет старый и начинает использовать новый через 2 минуты. Задержка нужна, чтобы kubelet на всех узлах успел обновить Secret. Старый ключ агент удаляет через такую же задержку.

Как выполнить плановую ротацию ключа сети fencing?

В поле data Secret fencing-memberlist-key в пространстве имён d8-cloud-instance-manager два ключа:

  • primary — этим ключом агенты шифруют сообщения. Ключ обязателен.
  • secondary — этим ключом агенты только расшифровывают сообщения. Ключ необязателен.

Каждый ключ — ровно 32 случайных байта. В поле data значение — эти 32 байта в кодировке base64. Не записывайте строку base64 в поле stringData: тогда агенты получат ключ неверной длины.

Чтобы выполнить ротацию ключа, выполните шаги:

  1. Создайте новый ключ, запишите его в primary, а текущий перенесите в secondary. Ключ хранится только в переменной shell, поэтому не попадает ни в вывод, ни в историю команд:

    NEW_KEY=$(head -c 32 /dev/urandom | base64)
    d8 k -n d8-cloud-instance-manager patch secret fencing-memberlist-key --type=json -p "[{\"op\":\"copy\",\"from\":\"/data/primary\",\"path\":\"/data/secondary\"},{\"op\":\"replace\",\"path\":\"/data/primary\",\"value\":\"${NEW_KEY}\"}]"
    unset NEW_KEY
    

    kubelet обновляет Secret на узлах обычно примерно за 1 минуту. Каждый агент сохраняет текущий ключ, добавляет новый и начинает использовать новый через 2 минуты. Во время ротации агенты со старым и с новым ключом расшифровывают сообщения друг друга.

  2. Подождите не меньше 10 минут. За это время все агенты переходят на новый ключ. Удалите старый ключ из Secret:

    d8 k -n d8-cloud-instance-manager patch secret fencing-memberlist-key --type=json -p '[
      {"op": "remove", "path": "/data/secondary"}
    ]'
    

Не удаляйте Secret, чтобы сменить ключ. Тогда Deckhouse создаст новый ключ без старого, и появится алерт D8FencingKeyRegenerated.

Если у ключа неверный формат, работающие агенты продолжают использовать текущие ключи и не принимают неверный ключ. Метрика d8_fencing_agent_config_invalid{parameter="key"} этих агентов равна 1. Агент, который запускается с неверным ключом primary, не может соединиться с другими агентами и не вооружает watchdog. Condition Fencing его узла — False с причиной InvalidKey, а через 10 минут появляется алерт D8FencingAgentInvalidKey. Чтобы найти такие узлы, используйте команду из раздела Как проверить состояние fencing на узлах?. Чтобы проверить длину ключа primary, выполните команду. Она должна вывести 32:

d8 k -n d8-cloud-instance-manager get secret fencing-memberlist-key -o jsonpath='{.data.primary}' | base64 -d | wc -c

Как механизм fencing обрабатывает разные типы узлов?

Механизм fencing останавливает узел, который потерял связь с кластером, и защищает кластер от «зомби»-узлов с неопределённым состоянием.

Узел с вооружённым watchdog работает, только пока видит control plane. Если узел не видит control plane дольше controlPlaneLostAfter из профиля, fencing-agent сразу перестаёт сбрасывать таймер watchdog (модуль ядра softdog). По истечении таймаута происходит kernel panic — это гарантирует, что на узле не останется работающей нагрузки.

Пока у узла есть объект FencingFailedNodeState, узел видит control plane, только если может записать свой heartbeat через API-сервер. Узел, который не может записать heartbeat, останавливается так же.

Перестав сбрасывать таймер, агент продолжает проверять control plane:

  • Если control plane снова доступен до истечения таймаута watchdog, агент снова сбрасывает таймер, и узел продолжает работать. Поэтому короткая пауза control plane не останавливает узлы.
  • Агент также опрашивает агентов других узлов. Он ищет свидетеля — узел, который видит control plane. Агент отправляет свидетелю сообщение об остановке, и свидетель записывает аттестацию в объект FencingFailedNodeState узла. После этого сообщения остановка окончательна: агент больше не сбрасывает таймер. Остановка окончательна и тогда, когда объект FencingFailedNodeState узла находится в фазе Proven.

Пауза control plane во всём кластере затрагивает все узлы с вооружённым watchdog одновременно. По замерам на кластере все узлы переживают паузу не дольше следующего времени:

Режим Пауза, которую переживают узлы
Critical 7,35 с
Normal 21,6 с
Slow 45,7 с

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

Подробнее о работе fencing-agent можно почитать в описании параметра spec.fencing.mode ресурса NodeGroup.

После остановки узла поведение зависит от типа группы узлов (лейбл node.deckhouse.io/type) и её engine (status.engine):

  1. Узел остаётся выключенным. Deckhouse отключает автоматическую перезагрузку после kernel panic на уровне ОС. Это действует для всех узлов групп, режим fencing которых отличается от Disabled. Это предотвращает возврат узла в кластер с неопределённым состоянием.
  2. Когда остановка узла гарантирована, fencing-controller ставит на Node taint node.kubernetes.io/out-of-service. Остановка гарантирована, если свидетель её подтвердил и таймаут watchdog узла истёк, или если узел молчит столько времени, сколько ему нужно, чтобы остановиться. Сроки и случаи, когда контроллер не ставит taint, описаны в разделе «Когда контроллер ставит taint». После установки taint контроллер ставит подам узла фазу Failed и условие DisruptionTarget и сразу удаляет эти поды, в том числе поды, которые терпят taint. Поды DaemonSet и static-поды контроллер не удаляет. Finalizer подов контроллер не снимает: под с finalizer остаётся в API, пока владелец finalizer не снимет его. Поды StatefulSet и поды с томами ReadWriteOnce запускаются на других узлах. Эвакуация завершена, когда у узла не осталось объектов VolumeAttachment. Если эвакуация не завершилась за 60 секунд, инцидент остаётся в фазе Evicting и получает условие Progressing со статусом False. Причина условия указывает, что мешает эвакуации сейчас: VolumesAttached, PodsRemaining или TooManyUnhealthyMachines. Контроллер продолжает проверять узел и завершает эвакуацию, когда причина устранена.
  3. После эвакуации Deckhouse действует так:
    • Для узла группы CloudPermanent, CloudStatic или Static (включая группу Static с staticInstances, то есть CAPS), для master-узла и для узла etcd-arbiter Deckhouse только оставляет taint. Объект Node Deckhouse не удаляет никогда.
    • Для узла группы CloudEphemeral с status.engine: CAPI Deckhouse удаляет объект Node, только если MachineHealthCheck кластера Cluster API показывает свои машины и нездоровых из них не больше 50 %. Остановленную машину Deckhouse считает нездоровой. Затем MachineHealthCheck выставляет у Machine condition HealthCheckSucceeded в False с причиной NodeDeleted и заменяет машину. Если нездоровых машин больше 50 % или MachineHealthCheck ещё не показывает свои машины, Deckhouse пока не удаляет объект Node. Контроллер продолжает проверять машины. Когда нездоровых машин становится не больше 50 %, контроллер удаляет объект Node и завершает эвакуацию.
    • Для узла группы CloudEphemeral с status.engine: MCM Deckhouse удаляет Machine (machine.sapcloud.io). Machine Controller Manager создаёт новую машину.
  4. Узел, который Deckhouse не заменяет, остаётся выключенным, пока вы его не запустите. Когда узел возвращается (Node в состоянии Ready и у него новый boot ID), fencing-controller снимает taint автоматически. Контроллер работает, только пока хотя бы у одной группы узлов режим отличается от Disabled. Если выключить fencing во всех группах узлов, taint останется на узле. Подробнее — в разделе «Что делать с taint out-of-service перед выключением fencing во всех группах узлов?»

Если fencing-controller не ставит taint, Kubernetes ставит на Node taint node.kubernetes.io/unreachable и выселяет поды узла через время, заданное в параметре failedNodePodEvictionTimeoutSeconds модуля control-plane-manager (по умолчанию 300 секунд).

Узел группы с включённым fencing может вернуться в кластер не так, как описано выше. Если это произошло, обратитесь в поддержку. Ваше обращение поможет уточнить цепочку проверок и защитных механизмов.

Когда контроллер ставит taint

Контроллер ставит taint node.kubernetes.io/out-of-service только на остановленный узел. Остановку контроллер доказывает одним из двух способов:

  • Аттестация свидетеля. Свидетель — узел, агент которого получил от отказавшего узла сообщение об остановке. Агент свидетеля записывает аттестацию в объект FencingFailedNodeState отказавшего узла. Увидев аттестацию, контроллер ждёт watchdog.timeout + watchdog.margin из профиля. За это время watchdog отказавшего узла истекает.
  • Молчание узла. Например, узел выключен или потерял все сети, и подтвердить его остановку некому. Контроллер ждёт controlPlaneLostAfter + 0,2 с + watchdog.timeout + watchdog.margin + 0,9 с из профиля после последнего признака жизни узла. Последний признак жизни — более поздний из двух моментов: когда контроллер впервые увидел объект FencingFailedNodeState и когда он увидел последний heartbeat узла плюс heartbeat.interval. За это время узел обнаруживает потерю control plane, и его watchdog истекает.

Контроллер использует тот способ, который даёт доказательство раньше:

Режим Профиль Время после аттестации Время после последнего признака жизни
Critical critical 5,3 с 10,55 с
Normal normal 15,75 с 25,95 с
Slow slow 31,5 с 52,8 с

Когда инцидент переходит в фазу Proven, контроллер записывает событие. В событии указаны способ доказательства и время.

Профиль контроллер берёт из поля spec.profileRef.name объекта FencingFailedNodeState. Агент, который создаёт объект, записывает более медленный из двух профилей: профиль, который применил отказавший узел, и профиль группы узлов на момент создания объекта. Deckhouse не позволяет менять режим группы, пока у узла этой группы есть объект FencingFailedNodeState. Подробнее — в разделе «Известные ограничения эвакуации».

Контроллер не ставит taint в следующих случаях:

  • Watchdog узла не был вооружён (spec.armed равно false). Например, узел входит в группу с режимом Disabled.
  • Condition Fencing у Node не True, то есть агент узла не сообщил, что watchdog вооружён. Контроллер не доказывает отказ, и инцидент остаётся в фазе Suspected. Контроллер проверяет узел снова каждые 5 секунд.
  • Узел пишет heartbeat. Каждый новый heartbeat начинает отсчёт времени после последнего признака жизни заново. Heartbeat после аттестации также отменяет доказательство этой аттестацией, и срабатывает алерт D8FencingNodeAliveAfterAttestation.
  • На узле есть одна из аннотаций обслуживания node-manager.deckhouse.io/fencing-disable, update.node.deckhouse.io/approved или update.node.deckhouse.io/disruption-approved, или агент узла останавливается штатно. Контроллер проверяет узел снова каждые 5 секунд.
  • UID в owner reference объекта FencingFailedNodeState не совпадает с UID узла с этим именем, например узел создан заново под тем же именем. По такому объекту контроллер ничего не делает.
  • Контроллер не может использовать профиль. Срабатывает алерт D8FencingProfileIsUnavailable.

Фазы инцидента fencing

Фазу инцидента контроллер записывает в поле status.phase объекта FencingFailedNodeState. Имя объекта совпадает с именем узла. Чтобы посмотреть инциденты, выполните команду:

d8 k get fencingfailednodestates

Фазы:

  • Suspected — агент обнаружил отказ узла. Контроллер ждёт доказательства отказа.
  • FallbackAlive — узел пишет heartbeat через API-сервер. Узел работает, но агенты других узлов не могут к нему подключиться.
  • Proven — контроллер доказал отказ аттестацией свидетеля или молчанием узла. Подробнее — в разделе «Когда контроллер ставит taint».
  • Evicting — на узле стоит taint. Контроллер удаляет поды и ждёт, пока у узла не останется объектов VolumeAttachment.
  • Evicted — эвакуация завершена. Контроллер сначала записывает эту фазу, а затем удаляет Node или Machine узла, который заменяет облако.

Описание всех полей — в разделе FencingFailedNodeState.

Алерты fencing

fencing-controller выдаёт следующие алерты:

  • D8FencingNodeFailed — у узла с вооружённым watchdog есть инцидент.
  • D8FencingNodeIsolatedFromPeers — инцидент находится в фазе FallbackAlive 1 минуту. Узел работает, но сеть между ним и другими узлами нарушена. Обычно трафик агентов блокирует правило межсетевого экрана или ACL.
  • D8FencingNodeAliveAfterAttestation — после аттестации узел записал heartbeat. Пока узел пишет heartbeat, контроллер не ставит на него taint. Проверьте узел.
  • D8FencingEvictionNotProgressing — эвакуация не завершилась за 60 секунд. Метка reason указывает причину условия Progressing.
  • D8NodeOutOfServiceTainted — на узле стоит taint node.kubernetes.io/out-of-service 30 минут. Запустите узел снова или удалите его из кластера.
  • D8FencingProfileIsUnavailable — контроллер не может использовать профиль инцидента и не ставит taint.

Алерты контроллера существуют, только пока контроллер работает, то есть пока хотя бы у одной группы узлов режим отличается от Disabled.

Алерт агента fencing D8FencingWatchdogDeviceMissing срабатывает, когда у агента 30 минут нет устройства watchdog. Агент не вооружает watchdog, поэтому контроллер никогда не ставит taint на этот узел. Обычно DaemonSet группы узлов ещё не заменил под агента предыдущей ревизии.

Известные ограничения эвакуации

fencing-controller работает на master-узлах. В кластере с несколькими master-узлами у контроллера несколько реплик, и работает только лидер. Новый лидер заново отсчитывает сроки инцидентов от того, что видит сам. Поэтому, если лидер сменился во время инцидента, taint ставится позже — до примерно 20 секунд плюс время после последнего признака жизни из таблицы в разделе «Когда контроллер ставит taint». Действий не требуется. Лидер может смениться в следующих случаях:

  • Отказал master-узел лидера.
  • На master-узле лидера kubernetes-api-proxy перезапустился с новым манифестом, например при обновлении Deckhouse. Контроллер подключается к API-серверу через этот прокси.

На master-узлах Deckhouse Engine (systemType: Immutable) и при выключенном модуле control-plane-manager контроллер подключается к API-серверу через ClusterIP сервиса kubernetes. Когда master-узел отказывает, запросы контроллера в течение нескольких секунд могут уходить на отказавший master-узел. Тогда taint отказавшего узла ставится позже, и лидер может смениться.

Когда отказывает master-узел контроллера, контроллер запускается на другом master-узле только после того, как Kubernetes пометит отказавший master-узел недоступным. До этого контроллер не ставит taint. Подробнее — в разделе «Как fencing работает на master-узлах?».

Deckhouse не позволяет менять режим группы узлов, пока у узла этой группы есть объект FencingFailedNodeState. Контроллер считает сроки инцидента по профилю из объекта, а watchdog узла уже может работать со сроками нового режима. В сообщении об ошибке перечислены узлы, у которых есть такие объекты. Дождитесь окончания инцидентов, затем меняйте режим. Инцидент заканчивается, когда узел вернулся после перезагрузки или когда удалён его объект Node. Чтобы найти объекты:

d8 k get fencingfailednodestates

Меняйте режим группы узлов, только когда все узлы группы работают нормально.

После переключения редакции на CE объект FencingFailedNodeState с профилем critical остаётся в кластере, так как в CE такого профиля нет. У объекта появляется условие ConfigurationError, срабатывает алерт D8FencingProfileIsUnavailable, и контроллер не эвакуирует узел. Когда узел вернётся, то есть Node будет Ready с новым boot ID, контроллер удалит объект сам. В остальных случаях убедитесь, что узел работает или выключен. Затем удалите объект:

d8 k delete fencingfailednodestate <NODE_NAME>

Если узел снова откажет, агенты создадут новый объект с профилем текущего режима. Если на узле стоит taint node.kubernetes.io/out-of-service, после удаления объекта он остаётся. Снимите taint, когда узел снова заработает:

d8 k taint node <NODE_NAME> node.kubernetes.io/out-of-service-

Узел с вооружённым watchdog останавливается, когда не видит control plane. Если сеть отделила часть кластера от control plane, все узлы с вооружённым watchdog в этой части останавливаются, даже если работают нормально.

О том, что watchdog узла вооружён, контроллер узнаёт только из condition Fencing у Node. Агент записывает этот condition после того, как вооружил или разоружил watchdog. Между этими двумя моментами condition может быть неверным. Известны два таких случая:

  • Агент вооружил watchdog, но статус True у condition не дошёл до API-сервера, и в этот момент узел отказал. Например, так бывает, если узел отказал во время перезапуска агента. Контроллер не ставит taint на этот узел, пока узел не вернётся.
  • Агент упал, и новый процесс агента разоружил watchdog. Затем узел потерял control plane раньше, чем агент записал статус False у condition. Узел работает, его watchdog не вооружён, но condition остаётся True. Контроллер не ставит taint на этот узел: если у узла появится объект FencingFailedNodeState, в нём будет spec.armed: false.

Откат Deckhouse на версию с fencing 1.0 не поддерживается. Если откат всё же нужен, выгрузите модуль ядра softdog на узлах. Иначе модуль сохранит таймаут fencing 2.0 (5 секунд у профиля Critical), агент fencing 1.0 сбрасывает таймер реже, и узел уходит в kernel panic.

Что делать с taint out-of-service перед выключением fencing во всех группах узлов?

Taint node.kubernetes.io/out-of-service с вернувшегося узла снимает только fencing-controller. Когда последняя группа узлов получает режим Disabled, Deckhouse удаляет контроллер вместе с агентами fencing. Если в этот момент на узле стоит taint, он остаётся на узле. Deckhouse его не снимает, и алерты fencing после этого не срабатывают. Kubernetes не запускает поды на таком узле.

То же происходит при выключении модуля node-manager, так как Deckhouse удаляет контроллер вместе с модулем. Deckhouse выключает модуль только после подтверждения аннотацией modules.deckhouse.io/allow-disabling=true на ModuleConfig. До подтверждения задайте режим Disabled всем группам узлов и дождитесь, когда в пространстве имён d8-cloud-instance-manager не останется подов fencing-agent. Иначе агент может не успеть сообщить об остановке, и watchdog остановит его узел. Шаги ниже тоже выполните до того, как задать режим Disabled последней группе узлов.

Прежде чем задать режим Disabled последней группе узлов, выполните следующие шаги:

  1. Найдите узлы с taint и инциденты fencing:

    d8 k get nodes -o custom-columns='NAME:.metadata.name,TAINTS:.spec.taints[*].key' | grep -E '^NAME|node.kubernetes.io/out-of-service'
    d8 k get fencingfailednodestates
    
  2. Для каждого узла с taint убедитесь, что узел снова работает или что вы его заменили. Затем снимите taint:

    d8 k taint node <NODE_NAME> node.kubernetes.io/out-of-service-
    

    Если узел всё ещё остановлен, fencing можно выключить. Но тогда снимите taint вручную после того, как запустите узел.

Если снова включить fencing, контроллер снимет taint по обычному правилу: когда Node в состоянии Ready, у него новый boot ID и у него ещё есть объект FencingFailedNodeState.

Как работать с GPU-узлами?

GPU-узлами управляет модуль gpu. Модуль node-manager не подготавливает GPU-узлы и не разворачивает компоненты NVIDIA.

Секцию spec.gpu в NodeGroup использует модуль gpu: по ней он выбирает группы узлов, которые обслуживает в режиме Device Plugin, и задаёт для них стратегию разделения GPU. Если модуль gpu выключен, секция spec.gpu ни на что не влияет и срабатывает алерт NodeGroupGPUModuleDisabled.

Как добавить GPU-узлы, установить драйвер и NVIDIA Container Toolkit, настроить разделение GPU и MIG, а также мониторинг GPU, описано в документации модуля gpu.