Как настроить?

Основы конфигурации Deckhouse

Deckhouse конфигурируется с помощью:

• Глобальных настроек. Глобальные настройки хранятся в ресурсе ModuleConfig/global. Эти настройки можно рассматривать как специальный модуль global, который нельзя отключить.
• Настроек модулей. Настройки каждого модуля хранятся в ресурсе ModuleConfig, имя которого совпадает с именем модуля (в kebab-case).
• Кастомных ресурсов. Некоторые модули настраиваются с помощью дополнительных кастомных ресурсов.

Пример набора кастомных ресурсов конфигурации Deckhouse:

# Глобальные настройки.
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: global
spec:
  version: 1
  settings:
    modules:
      publicDomainTemplate: "%s.kube.company.my"
---
# Настройки модуля monitoring-ping.
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: monitoring-ping
spec:
  version: 1
  settings:
    externalTargets:
    - host: 8.8.8.8
---
# Отключить модуль dashboard.
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: dashboard
spec:
  enabled: false

Посмотреть список кастомных ресурсов ModuleConfig, состояние модулей (включен/выключен) и их статус можно с помощью следующей команды:

d8 k get moduleconfigs

$ d8 k get moduleconfigs
NAME            ENABLED   VERSION   AGE     MESSAGE
deckhouse       true      1         12h
documentation   true      1         12h
global                    1         12h
prometheus      true      2         12h
upmeter         false     2         12h

Чтобы изменить глобальную конфигурацию Deckhouse или конфигурацию модуля, нужно создать или отредактировать соответствующий ресурс ModuleConfig.

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

d8 k edit moduleconfig/upmeter

После завершения редактирования изменения применяются автоматически.

Изменение конфигурации кластера

Общие параметры кластера хранятся в структуре ClusterConfiguration.

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

d8 system edit cluster-configuration

После сохранения изменений DKP автоматически приведёт кластер в соответствие с новой конфигурацией. В зависимости от размеров кластера это может занять некоторое время.

Изменение защищённых параметров

Некоторые параметры кластера критичны для его работы и по умолчанию не могут быть изменены в работающем кластере. К таким параметрам относятся:

• podSubnetCIDR — адресное пространство сети подов;
• podSubnetNodeCIDRPrefix — размер префикса сети подов на узел;
• serviceSubnetCIDR — адресное пространство сети сервисов.

Попытки изменить эти параметры будут заблокированы admission webhook с сообщением об ошибке.

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

Изменение защищённых параметров с использованием dhctl

Используйте утилиту dhctl из контейнера инсталлятора DKP с флагом --yes-i-am-sane-and-i-understand-what-i-am-doing.

Она автоматически:

• добавит аннотацию deckhouse.io/allow-unsafe к секрету d8-cluster-configuration;
• откроет редактор для изменения конфигурации;
• удалит аннотацию после сохранения изменений.

Для изменения защищённых параметров с помощью dhctl выполните следующие шаги:

1. Получите текущую версию и редакцию DKP из вашего кластера. Для этого на локальной машине запустите контейнер установщика DKP соответствующей редакции и версии:

   DH_VERSION=$(d8 k -n d8-system get deployment deckhouse -o jsonpath='{.metadata.annotations.core\.deckhouse\.io\/version}')
   DH_EDITION=$(d8 k -n d8-system get deployment deckhouse -o jsonpath='{.metadata.annotations.core\.deckhouse\.io\/edition}' | tr '[:upper:]' '[:lower:]')
   

2. Запустите контейнер инсталлятора DKP (при необходимости измените адрес registry):

   docker run --pull=always -it [<MOUNT_OPTIONS>] \
     registry.deckhouse.ru/deckhouse/${DH_EDITION}/install:${DH_VERSION} bash
   

   Где <MOUNT_OPTIONS> — параметры монтирования файлов в контейнер установщика, такие как:

   • SSH-ключи доступа;
   • файл конфигурации;
   • файл ресурсов и т. д.

3. Внутри контейнера выполните следующую команду для редактирования конфигурации кластера:

   dhctl config edit cluster-configuration \
     --ssh-agent-private-keys=/tmp/.ssh/<SSH_KEY_FILENAME> \
     --ssh-user=<USERNAME> \
     --ssh-host=<MASTER-NODE-HOST> \
     --yes-i-am-sane-and-i-understand-what-i-am-doing
   

   Где:

   • <SSH_KEY_FILENAME> — имя файла вашего приватного SSH-ключа,
   • <USERNAME> — SSH-пользователь с правами sudo на целевом master-узле кластера,
   • <MASTER-NODE-HOST> — IP-адрес или имя хоста master-узла.

4. Отредактируйте конфигурацию в открывшемся редакторе, сохраните изменения и выйдите из редактора.

Изменение защищённых параметров вручную

Если необходимо вручную отредактировать конфигурацию:

1. Добавьте аннотацию deckhouse.io/allow-unsafe к секрету d8-cluster-configuration:

   d8 k -n kube-system annotate secret d8-cluster-configuration deckhouse.io/allow-unsafe="true"
   

2. Получите текущую конфигурацию, декодируйте её и сохраните в файл:

   d8 k -n kube-system get secret d8-cluster-configuration \
     -o jsonpath='{.data.cluster-configuration\.yaml}' | base64 -d > cluster-config.yaml
   

3. Отредактируйте файл cluster-config.yaml в предпочитаемом редакторе:

   vi cluster-config.yaml
   

4. Закодируйте отредактированную конфигурацию и обновите секрет:

   d8 k -n kube-system patch secret d8-cluster-configuration \
     --patch="{\"data\":{\"cluster-configuration.yaml\":\"$(base64 -w0 < cluster-config.yaml)\"}}"
   

5. Удалите аннотацию после применения изменений:

   d8 k -n kube-system annotate secret d8-cluster-configuration deckhouse.io/allow-unsafe-
   

6. Удалите временный файл с новой конфигурацией:

   rm cluster-config.yaml
   

Просмотр текущих настроек

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

1. Для просмотра глобальных настроек выполните:

   d8 k get mc global -o yaml
   

2. Для просмотра состояния всех модулей (доступно для Deckhouse версии 1.47+):

   d8 k get modules
   

3. Для просмотра настроек модуля user-authn:

   d8 k get moduleconfigs user-authn -o yaml
   

Настройка модуля

Модуль настраивается с помощью ресурса ModuleConfig, имя которого совпадает с именем модуля (в kebab-case). ModuleConfig имеет следующие поля:

• metadata.name — название модуля Deckhouse в kebab-case (например, prometheus, node-manager);
• spec.version — версия схемы настроек модуля (целое число, больше нуля). Обязательное поле, если spec.settings не пустое. Номер актуальной версии можно увидеть в документации модуля в разделе Настройки:
  • Deckhouse поддерживает обратную совместимость версий схемы настроек модуля. Если используется схема настроек устаревшей версии, при редактировании или просмотре кастомного ресурса будет выведено предупреждение о необходимости обновить схему настроек модуля;
• spec.settings — настройки модуля. Необязательное поле, если используется поле spec.enabled. Описание возможных настроек можно найти в документации модуля в разделе Настройки;
• spec.enabled — необязательное поле для явного включения или отключения модуля. Если не задано, модуль может быть включен по умолчанию в одном из наборов модулей.

Deckhouse не изменяет кастомные ресурсы ModuleConfig. Это позволяет применять подход Infrastructure as Code (IaC) при хранении конфигурации. Другими словами, можно воспользоваться всеми преимуществами системы контроля версий для хранения настроек Deckhouse, использовать Helm, d8 k и другие привычные инструменты.

Пример кастомного ресурса для настройки модуля kube-dns:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: kube-dns
spec:
  version: 1
  settings:
    stubZones:
    - upstreamNameservers:
      - 192.168.121.55
      - 10.2.7.80
      zone: directory.company.my
    upstreamNameservers:
    - 10.2.100.55
    - 10.2.200.55

Некоторые модули настраиваются с помощью дополнительных ресурсов. Воспользуйтесь поиском (вверху страницы) или выберите модуль в меню слева, чтобы просмотреть документацию по его настройкам и используемым кастомным ресурсам.

Включение и отключение модуля

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

Для явного включения или отключения модуля необходимо установить true или false в поле .spec.enabled в соответствующем кастомном ресурсе ModuleConfig. Если для модуля нет такого кастомного ресурса ModuleConfig, его нужно создать.

Пример явного выключения модуля user-authn (модуль будет выключен независимо от используемого набора модулей):

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  enabled: false

Проверить состояние модуля можно с помощью команды d8 k get moduleconfig <ИМЯ_МОДУЛЯ>.

Пример:

$ d8 k get moduleconfig user-authn
NAME         ENABLED   VERSION   AGE   MESSAGE
user-authn   false     1         12h

Наборы модулей

В зависимости от используемого набора модулей (bundle) модули могут быть включены или выключены по умолчанию.

Особенности работы с набором модулей Minimal

Для установки DKP с набором модулей Minimal включите как минимум следующие модули, указав их в конфигурационном файле установщика:

• cni-cilium или другой модуль управления CNI (при необходимости);
• control-plane-manager;
• kube-dns;
• terraform-manager, в случае развертывания облачного кластера;
• node-manager;
• registry-packages-proxy;
• модуль облачного провайдера (например, cloud-provider-aws для AWS), в случае развертывания облачного кластера.

Доступ к документации текущей версии

Документация запущенной в кластере версии Deckhouse доступна по адресу documentation.<cluster_domain>, где <cluster_domain> — DNS-имя в соответствии с шаблоном из параметра modules.publicDomainTemplate глобальной конфигурации.

Управление размещением компонентов Deckhouse

Выделение узлов под определенный вид нагрузки

Если в параметрах модуля не указаны явные значения nodeSelector/tolerations, то для всех модулей используется следующая стратегия:

1. Если параметр nodeSelector модуля не указан, то Deckhouse попытается вычислить nodeSelector автоматически. В этом случае, если в кластере присутствуют узлы с лейблами из списка или лейблами определенного формата, Deckhouse укажет их в качестве nodeSelector ресурсам модуля.
2. Если параметр tolerations модуля не указан, то подам модуля автоматически устанавливаются все возможные toleration’ы, (подробнее).
3. Отключить автоматическое вычисление параметров nodeSelector или tolerations можно, указав значение false.
4. При отсутствии в кластере выделенных узлов и автоматическом выборе nodeSelector (см. п. 1), nodeSelector в ресурсах модуля указан не будет. Модуль в таком случае будет использовать любой узел с не конфликтующими taints.

Возможность настройки nodeSelector и tolerations отключена для модулей:

• которые работают на всех узлах кластера (например, cni-flannel, monitoring-ping);
• которые работают на всех master-узлах (например, prometheus-metrics-adapter, vertical-pod-autoscaler).

Особенности автоматики, зависящие от типа модуля

• Модули monitoring (operator-prometheus, prometheus и vertical-pod-autoscaler):
  • Порядок поиска узлов (для определения nodeSelector):
    1. Наличие узла с лейблом node-role.deckhouse.io/MODULE_NAME.
    2. Наличие узла с лейблом node-role.deckhouse.io/monitoring.
    3. Наличие узла с лейблом node-role.deckhouse.io/system.
  • Добавляемые toleration’ы (добавляются одновременно все):
    • {"key":"dedicated.deckhouse.io","operator":"Equal","value":"MODULE_NAME"} (например, {"key":"dedicated.deckhouse.io","operator":"Equal","value":"operator-prometheus"});
    • {"key":"dedicated.deckhouse.io","operator":"Equal","value":"monitoring"};
    • {"key":"dedicated.deckhouse.io","operator":"Equal","value":"system"}.
• Модули frontend (исключительно модуль ingress-nginx):
  • Порядок поиска узлов (для определения nodeSelector):
    1. Наличие узла с лейблом node-role.deckhouse.io/MODULE_NAME.
    2. Наличие узла с лейблом node-role.deckhouse.io/frontend.
  • Добавляемые toleration’ы (добавляются одновременно все):
    • {"key":"dedicated.deckhouse.io","operator":"Equal","value":"MODULE_NAME"};
    • {"key":"dedicated.deckhouse.io","operator":"Equal","value":"frontend"}.
• Все остальные модули:
  • Порядок поиска узлов (для определения nodeSelector):
    1. Наличие узла с лейблом node-role.deckhouse.io/MODULE_NAME (например, node-role.deckhouse.io/cert-manager).
    2. Наличие узла с лейблом node-role.deckhouse.io/system.
  • Добавляемые toleration’ы (добавляются одновременно все):
    • {"key":"dedicated.deckhouse.io","operator":"Equal","value":"MODULE_NAME"} (например, {"key":"dedicated.deckhouse.io","operator":"Equal","value":"network-gateway"});
    • {"key":"dedicated.deckhouse.io","operator":"Equal","value":"system"}.