Модуль управления конфигурациями узлов (shturval-node-config)

О сервисе #

Настройка NCI в интерфейсе, селекторы, приоритеты и примеры разделов — на странице Конфигурация узлов (NCI).

Состояние сервиса можно посмотреть в интерфейсе: Сервисы и репозитории → Установленные сервисы → Модуль управления конфигурациями узлов (shturval-node-config) → Управлять.

Содержание #

1. Обзор
2. Архитектура
3. Установка / развёртывание
4. Диагностика
5. Жизненный цикл
6. Параметры оператора и демона
7. Справочник CRD/API

1. Обзор #

shturval-node-config обеспечивает доставку и применение конфигурации узлов Kubernetes-кластера. Оператор управляет объектами конфигурации и безопасной перезагрузкой, а демон std применяет конфигурацию на узле, сообщает о необходимости перезагрузки и завершает её после разрешения со стороны оператора.

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

Администратор создаёт и изменяет объекты NodeConfigItem, оператор сопоставляет их с NodeConfig конкретных узлов, а демон std на каждом узле получает итоговую конфигурацию, применяет её и отражает состояние обратно в NodeConfig.status. При необходимости оператор выполняет cordon/drain и только после этого разрешает перезагрузку узла.

Сквозная последовательность (NCI → NodeConfig → демон, дрейн, перезагрузка, CSR) на схеме ниже; подробные шаги — в §5.

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

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

• shturval-node-config-crds — чарт CRD группы node.shturval.tech;
• shturval-node-config — основной чарт модуля. (см. скриншот ниже)

Общая схема архитектуры, см. иллюстрацию ниже.

Оператор shturval-node-config #

Оператор управляет конфигурацией узлов кластера через CRD NodeConfig и NodeConfigItem, оркестрирует дрейн и перезагрузку и автоматически одобряет CSR для kubelet-serving.

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

Компоненты #

Демон std #

std (shturvald) работает на каждом Linux-узле кластера. Он применяет объединённую конфигурацию узла, следит за локальным init-конфигом, синхронизирует состояние с объектом NodeConfig и выполняет перезагрузку только после разрешения от оператора.

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

Основные задачи #

Объекты в кластере #

Внешние зависимости #

Демон shurvald (std) #

Демон развёртывается непосредственно на Linux-узле и работает как системная служба. Он использует локальные файлы в /etc/std/, kubeconfig kubelet и очередь синхронизации для применения конфигурации и обмена состоянием с оператором.

Схемы демона #

Логическая архитектура демона std на узле, см. иллюстрацию ниже.

Схема показывает внутреннюю архитектуру демона на Linux-узле: systemd unit shturvald.service и fsnotify-наблюдатель за /etc/std/nci.json ставят задачи в rate-limited WorkQueue; worker goroutine через NodeReader читает NodeConfig и NCI из API кластера, объединяет конфигурацию в /etc/std/merged.json, применяет её к ОС (пакеты, файлы, kubelet, runtime, sysctl), а NodeWriter записывает статус и условия обратно в NodeConfig.

Поток обработки: конфигурация, применение, взаимодействие с NodeConfig, см. иллюстрацию ниже.

Компоненты на узле #

Связь оператора и демона #

3. Установка / развёртывание #

shturval-node-config — критический сервис платформы. Включение и жизненный цикл контроллера в кластере обеспечивает cluster-manager (сервис платформы); объекты ShturvalServiceConfig (SSC) для связанных чартов создаются и сопровождаются как часть платформенной конфигурации, а не как произвольная ручная установка Helm-чарта администратором.

Агент std (shturvald) устанавливается платформой на узлы автоматически в рамках процесса подготовки узла (bootstrap). Отдельной ручной установки агента не требуется.

CRD, контроллеры и владение ресурсами:

4. Диагностика #

Оператор shturval-node-config #

Быстрые проверки #

kubectl get nc
kubectl get nci

Оператор публикует следующие печатаемые колонки для NodeConfig:

Для NodeConfigItem доступны колонки:

Conditions ресурса NodeConfig #

Обратите внимание! NodeDrained появляется только при rebootscheduled=true, а RebootScheduled появляется только при rebootrequired=true.

Демон std #

Быстрые проверки #

systemctl status shturvald
std node status
std node info

Если демон ещё не присоединился к кластеру, дополнительным ориентиром служит наличие файлов /etc/std/nci.json и /etc/kubernetes/kubelet.conf.

Состояния демона #

Аннотации, влияющие на диагностику #

Типичные эксплуатационные ситуации #

Если после сверки локального init NCI и ожидаемой конфигурации кластера требуется повторно запустить применение конфигурации, удалите аннотацию node.shturval.tech/initchecksum, записанную в NodeConfig:

kubectl get nodeconfig <node-name> -o jsonpath='{.status}'
kubectl annotate nodeconfig <node-name> node.shturval.tech/initchecksum-

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

Оператор shturval-node-config #

Полный сценарий на одной схеме: см. также §1 — место в цепочке.

Контур Node → NodeConfig #

Согласование Node и NodeConfig, см. иллюстрацию ниже.

Контур NodeConfigItem → NodeConfig #

Согласование NodeConfigItem и выбранных NodeConfig, см. иллюстрацию ниже.

Контур применения и перезагрузки #

Согласование NodeConfig в контуре применения и перезагрузки, см. иллюстрацию ниже.

Согласование NodeConfig: дрейн:

Согласование NodeConfig: очередь перезагрузок:

Согласование NodeConfig: условия:

Политика дрейна #

Финалайзеры #

Демон std #

Порядок запуска #

Цикл применения конфигурации #

Перезагрузка и повторное применение #

6. Параметры оператора и демона #

Оператор shturval-node-config #

Флаги процесса #

Переменные окружения #

Демон std #

Глобальные флаги CLI #

Основные команды #

Эксплуатационные ограничения #

7. Справочник CRD/API #

Группа API контура: node.shturval.tech, версия v1beta2.

NodeConfig #

NodeConfig создаётся автоматически для каждого Node и не предназначен для ручного создания.

Характеристики ресурса #

spec #

status #

Conditions #

Пример #

apiVersion: node.shturval.tech/v1beta2
kind: NodeConfig
metadata:
  name: node-1
  labels:
    kubernetes.io/os: linux
    node.shturval.tech/applygroup: workers
spec:
  applygroup: workers
  donotdrain: false
  nodeconfigitems:
    - packages-basic-install
    - kubelet-basic

NodeConfigItem #

NodeConfigItem создаётся администратором и задаёт переиспользуемый шаблон конфигурации для группы узлов, выбранных по меткам.

Характеристики ресурса #

spec #

status #

Примеры #

Минимальный пример установки пакетов:

apiVersion: node.shturval.tech/v1beta2
kind: NodeConfigItem
metadata:
  name: packages-basic-install
spec:
  nodeconfigselector:
    node-role.kubernetes.io/worker: ""
  packages:
    - name: chrony
      state: present
    - name: curl
      state: present

Пример настройки kubelet:

apiVersion: node.shturval.tech/v1beta2
kind: NodeConfigItem
metadata:
  name: kubelet-basic
spec:
  nodeconfigselector:
    node-role.kubernetes.io/worker: ""
  kubelet:
    cpuManagerPolicy: none
    memoryManagerPolicy: None
    maxPods: 110
    hairpinMode: promiscuous-bridge

OIDC и AuthenticationConfiguration #

kube-apiserver проверяет пользователей по JWT-токену внешнего OIDC-провайдера.

Раньше OIDC в kube-apiserver настраивали флагами запуска: --oidc-issuer-url, --oidc-client-id и другими --oidc-*. Так можно было подключить только одного провайдера.

С Kubernetes 1.34 те же настройки задают файлом AuthenticationConfiguration (apiserver.config.k8s.io/v1). В файле список jwt: каждый элемент — отдельный провайдер со своим адресом издателя (issuer.url) и при необходимости своим адресом discovery (issuer.discoveryURL).

Флаги --oidc-* и путь к этому файлу (--authentication-config) нельзя задать одновременно: kube-apiserver не запустится.

Поля одного провайдера доступно задать в интерфейсе на странице Конфигурация узлов (NCI). Несколько провайдеров могут быть заданы только в манифесте.

В NCI:

• spec.kubeapi.oidc — один провайдер, как в интерфейсе. Поле поддерживается, но конвертируется в одну запись JWT.
• spec.kubeapi.authenticationConfiguration.jwt — список провайдеров.

Через API платформы в oidc можно передать несколько провайдеров: каждый элемент списка — отдельный издатель. У элемента могут быть несколько идентификаторов клиента (clientid), признак exist и discoveryURL. В объекте NCI в кластере эти элементы записываются в authenticationConfiguration.jwt.

После перехода на файл демон делает на узле следующее:

1. Записывает конфигурацию в /etc/kubernetes/auth-config/authentication-config.yaml.
2. В манифесте kube-apiserver указывает путь к этому файлу аргументом --authentication-config= и подключает каталог /etc/kubernetes/auth-config/, чтобы API-сервер читал файл.
3. Удаляет старые флаги --oidc-*.

Если позже файл или аргументы на узле перестанут совпадать с NCI, демон снова приведёт их к нужному виду.

Если к узлу привязано несколько NCI, списки JWT из них объединяются.

• Один и тот же issuer.url в двух NCI — в итоге остаётся описание из NCI с большим приоритетом.
• Новый issuer.url — провайдер добавляется в список.
• exist: false у записи с нужным URL — этого провайдера в итоговой конфигурации не будет. Если exist не указан или true — провайдер остаётся.

В одном NCI нельзя указать два одинаковых issuer.url. Сертификат CA должен быть в формате PEM. Иначе объект не сохранится.

Пример с одним oidc — на странице Конфигурация узлов (NCI). Несколько провайдеров:

apiVersion: node.shturval.tech/v1beta2
kind: NodeConfigItem
metadata:
  name: auth-config-nci
spec:
  nodeconfigselector:
    node-role.kubernetes.io/control-plane: ""
  kubeapi:
    authenticationConfiguration:
      jwt:
        - issuer:
            url: https://auth.example.com
            discoveryURL: https://discovery.example.com/.well-known/openid-configuration
            audiences:
              - backend
          claimMappings:
            username:
              claim: sub
              prefix: "shturval:"
            groups:
              claim: groups
              prefix: "shturval:"
        - issuer:
            url: https://sso.example.com
            audiences:
              - backend
          claimMappings:
            username:
              claim: sub
        - exist: false
          issuer:
            url: https://old-idp.example.com
          claimMappings:
            username:
              claim: sub
  priority: 100

Данные, которые демон пишет в NodeConfig #

Аннотации #

Состояния применения #