Шаблонизация кластеров

Концепции

dhctl

Чтобы установить Deckhouse Kubernetes Platform вручную, используют утилиту dhctl. На вход она принимает три набора данных:

• Конфигурацию SSH-подключения к машине, которая станет первым master-узлом. Конфигурация используется в виде ключей командной строки dhctl (есть возможность задать в виде YAML). Будем далее ссылаться на него под именем SSHConfig.
• Инфраструктурная и базовая конфигурация кластера в виде yaml-файла, будем далее ссылаться на него под именем config.yaml.
• Необязательный набор ресурсов который нужно создать на последнем шаге установки, будем далее ссылаться на него под именем resources.yaml.

Соответствие имен файлов и их содержимое приведено только для наглядности и совместимости со старыми версиями dhctl. Современные версии dhctl не ограничивают пользователя количеством и именами конфигурационных файлов для установки.

Какие логические части содержатся в этих данных?

• SSHConfig
  • Имя пользователя, пароль и ключ для подключения к существующей машине или той, которая будет создана в процессе создания кластера (возможность задать пароль для sudo в разработке).
  • IP-адрес машины, если кластер разворачивается на заранее созданных машинах («статический» тип кластера)
  • Остальные параметры можно посмотреть в справке команды dhctl, в данной документации дополнительные детали несущественны
• InitConfiguration — конфигурация доступа к хранилищу образов (dockerconfig)
• ClusterConfiguration — конфигурация Kubernetes: версия, подсетей подов, сервисов и т. п.
  • Параметры размещения в инфраструктуре
    • <Provider>ClusterConfiguration — параметры размещения кластера в облаке или API виртуализации, если Deckhouse Kubernetes Platform устанавливается не на статические ресурсы;
    • или StaticClusterConfiguration для статического кластера
• resources.yaml — произвольная конфигурация Deckhouse Kubernetes Platform в виде манифестов Kubernetes

Все эти данные в разных комбинациях используются для создания, изменения и удаления кластеров. Эти же данные используются в Deckhouse Commander, а dhctl используется как внутренний компонент.

Deckhouse Commander

Deckhouse Commander использует тот же набор данных для конфигурации кластеров, что и dhctl. Это включает в себя параметры подключения (SSHConfig), конфигурация Kubernetes (ClusterConfiguration, <Provider>ClusterConfiguration и StaticClusterConfiguration), произвольные манифесты (resources.yaml).

Однако в Deckhouse Commander пользователь не сталкивается напрямую с конфигурированием InitConfiguration. Вместо этого используется конфигурация хранилищ образов через специальные формы. Данные из этих форм автоматически преобразуются в InitConfiguration и передаются в dhctl. Обратим внимание, что конфигурация хранилищ образов в Deckhouse Commander не связана с конфигурацией шаблона, но является необходимым шагом для рендеринга шаблона и для создания кластера.

Deckhouse Commander добавляет возможность автоматически синхронизировать полную желаемую конфигурацию с кластером.

• Для создания и удаления кластера требуется SSH-доступ к master-узлу, а для изменений не требуется.
• Хранилище образов выбирается во время установки. Для существующего кластера, управляемого DKP версии 1.72 и выше, его можно сменить позже; порядок описан в разделе Изменение хранилища образов кластера.
• Базовая инфраструктурная конфигурация управляется с помощью доступа в API облака, в то время как операционная конфигурация используется с помощью commander-agent (далее — «агент») — вспомогательного модуля, который включается в кластере в процессе его создания или присоединения к Deckhouse Commander.

Deckhouse Commander — источник истины конфигурации. Deckhouse Commander отслеживает, что конфигурация кластера соответствует заданной. Если Deckhouse Commander обнаруживает расхождение, он принимает попытку привести кластер к заданной конфигурации. Далее для этого мы будем использовать «синхронизация».

• Синхронизация инфраструктуры проводится компонентом cluster-manager, который использует dhctl.
• Синхронизация операционной конфигурации проводится компонентом агентом.

Deckhouse Commander делит конфигурацию Deckhouse Kubernetes Platform по принципу отслеживаемости. Причем пользователь решает какую часть конфигурации синхронизировать, а какую задать один раз при создании кластера. Как эта конфигурация выглядит с точки зрения Deckhouse Commander:

Шаблоны

Идея

Deckhouse Commander создан для того, чтобы управлять типовыми кластерами. Так как все виды конфигурации в Deckhouse Commander представлены в формате YAML, шаблонизация кластеров представляет собой шаблоны YAML-конфигурации и описание схемы этих входных параметров шаблона. Для шаблонизации YAML используется синтаксис go template и набор функций sprig. Для описания схемы входных параметров используется собственный синтаксис для полей.

Конфигурация кластера создается за счет подстановки входных параметров в шаблоны секций. Входные параметры валидируются заданной для них схемой.

Версии шаблона

Важная черта шаблона — эволюция. Недостаточно создать парк кластеров на основе шаблонов. Шаблоны совершенствуются и актуализируются под новые версии ПО и новые требования эксплуатации кластеров. Обновлённый шаблон позволяет и создавать новые кластеры, отвечающие современным требованиям, и актуализировать уже существующие кластеры.

Для эволюции шаблонов в Deckhouse Commander предусмотрен механизм версионирования. Когда шаблон получает обновления, для него создается новая версия. Версия может быть сопровождена комментарием. На основе версии шаблона можно создать кластер и протестировать его работоспособность. Если версия шаблона не подходит для того, чтобы ею пользовались, ее можно отметить недоступной для использования. Тогда администраторы кластеров не смогут перевести кластер на версию шаблона.

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

Публикация версии шаблона

Для того, чтобы использовать единый шаблон для всех рабочих пространств, существует механизм его публикации. Публикуются конкретные версии шаблона, которые впоследствии будут доступны в других рабочих пространствах. Для публикации шаблона необходимо выбрать нужный шаблон, открыть вкладку «Версии» и нажать кнопку «Опубликовать» напротив желаемой версии. После этого шаблон и его версия станут доступны в остальных рабочих пространствах в режиме «только для чтения».

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

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

Сложность шаблона

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

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

Только автор шаблона определяет, насколько будет просто или тяжело использовать шаблон конечному пользователю, и какие решения необходимо пользователю принять, чтобы успешно создать кластер. Чем сложнее шаблон, тем сложнее шаблонизирующий его код и тем сложнее форма параметров шаблона. Пользователи Deckhouse Commander сами определяют соотношение сложности шаблона и количества шаблонов для разных сценариев. Deckhouse Commander — достаточно гибкий инструмент. С ним можно сделать как один шаблон на все случаи жизни, так и множество шаблонов для каждого отдельного сценария использования.

Встроенные шаблоны

В каждом рабочем пространстве Deckhouse Commander уже доступен набор предустановленных шаблонов для типовых провайдеров. Их можно использовать как есть, взять за основу для собственных шаблонов или заменить своими. Ниже по каждому шаблону приведено краткое описание и его входные параметры.

Статический (cni-cilium)

Кластер на заранее подготовленных серверах (bare metal) с сетевым плагином Cilium.

• Общие параметры: домен для приложений кластера, канал обновлений Deckhouse, версия Kubernetes, доступ по SSH, параметры прокси.
• Специфичные параметры: списки хостов по ролям (master, frontend, system, worker), сети подов, сервисов и узлов, приватный SSH-ключ и sudo-пароль, при необходимости — бастион-хост.

Yandex Cloud

Облачный кластер в Yandex Cloud.

• Общие параметры: домен для приложений кластера, канал обновлений Deckhouse, версия Kubernetes, префикс облачных объектов, доступ по SSH, размеры и количество узлов по ролям (master, frontend, system, worker), параметры прокси.
• Специфичные параметры: идентификаторы облака и директории, ключ сервисного аккаунта, образ виртуальной машины, зоны узлов.

OpenStack

Облачный кластер в OpenStack.

• Общие параметры: домен для приложений кластера, канал обновлений Deckhouse, версия Kubernetes, префикс облачных объектов, доступ по SSH, размеры и количество узлов по ролям (master, frontend, system, worker), параметры прокси.
• Специфичные параметры: Identity API URL и учётные данные (пользователь, пароль, домен, проект), регион, внешняя сеть, образ, зона доступности, тип и размер диска, типы инстансов узлов.

VMware vSphere

Кластер в VMware vSphere (vCenter).

• Общие параметры: домен для приложений кластера, канал обновлений Deckhouse, версия Kubernetes, префикс облачных объектов, доступ по SSH, размеры и количество узлов по ролям (master, frontend, system, worker), параметры прокси.
• Специфичные параметры: адрес и учётные данные vCenter, пулы ресурсов, категории и теги регионов и зон, сети, каталог виртуальных машин, хранилище, образ.

VMware Cloud Director

Кластер в VMware Cloud Director.

• Общие параметры: домен для приложений кластера, канал обновлений Deckhouse, версия Kubernetes, префикс облачных объектов, доступ по SSH, размеры и количество узлов по ролям (master, frontend, system, worker), параметры прокси.
• Специфичные параметры: адрес и учётные данные vCD (или токен), организация, дата-центр и приложение (vApp), основная сеть и Edge Gateway, хранилище, образ, виртуальный бастион.

zVirt

Кластер в zVirt.

• Общие параметры: домен для приложений кластера, канал обновлений Deckhouse, версия Kubernetes, префикс облачных объектов, доступ по SSH, размеры и количество узлов по ролям (master, frontend, system, worker), параметры прокси.
• Специфичные параметры: адрес и учётные данные zVirt, идентификаторы кластера, профиля vNIC и домена хранения, образ виртуальной машины.

Huawei Cloud (cloud.ru)

Кластер в Huawei Cloud (cloud.ru).

• Общие параметры: домен для приложений кластера, канал обновлений Deckhouse, версия Kubernetes, префикс облачных объектов, доступ по SSH, размеры и количество узлов по ролям (master, worker), параметры прокси.
• Специфичные параметры: ключ доступа и секрет, идентификаторы проекта и подпроекта, адрес облака, образ и пользователь виртуальной машины, типы дисков узлов, включение Ingress-контроллера.

DKP на Deckhouse Virtualization Platform

Кластер поверх виртуализации Deckhouse Virtualization Platform (DVP).

• Общие параметры: домен для приложений кластера, канал обновлений Deckhouse, версия Kubernetes, префикс кластера, доступ по SSH, размеры и количество узлов по ролям (master, frontend, system, worker), параметры прокси.
• Специфичные параметры: kubeconfig для доступа к DVP API, проект DVP, тип и имя образа, хранилище (StorageClass), класс виртуальной машины, загрузчик, правила управления трафиком.

Deckhouse Virtualization Platform на bare metal

Статический кластер на bare metal с включённой виртуализацией по умолчанию. Сразу разворачивает кластер с виртуализацией для запуска виртуальных машин, без промежуточного general-purpose DKP.

• Общие параметры: домен для приложений кластера, канал обновлений Deckhouse, версия Kubernetes, доступ по SSH, параметры прокси.
• Специфичные параметры: списки хостов по ролям (master, worker), сети узлов, приватный SSH-ключ, включение sds-replicated-volume, сеть виртуализации.

Managed Kubernetes

Существующий кластер Kubernetes, control plane которого управляется провайдером (например, Amazon EKS).

• Общие параметры: домен для приложений кластера, канал обновлений Deckhouse.
• Специфичные параметры: kubeconfig целевого кластера.

Создание шаблона

Добавить шаблон в Deckhouse Commander можно двумя способами: импортировать существующий (например, созданный ранее в другой инсталляции Deckhouse Commander) или создать с нуля. В конечном счете шаблонизированная конфигурация должна будет удовлетворять особенностями dhctl и Deckhouse Kubernetes Platform той версии, которая будет устанавливаться с помощью шаблона.

Где почерпнуть документацию для видов конфигурации

• Входные параметры
  • Схема входных параметров
• Размещение
  • Статические ресурсы
  • Yandex Cloud
  • OpenStack
  • VMware vSphere
  • VMware Cloud Director
  • Amazon Web Services
  • Google Cloud Platform
  • Microsoft Azure
  • zVirt
  • Базис.DynamiX
  • Huawei Cloud
• Kubernetes
  • ClusterConfiguration
• Доступ к хранилищу образов
  • Конфигурация хранилищ образов в Deckhouse Commander
  • InitConfiguration (данный конфигурационный файл не редактируется напрямую, а генерируется автоматически).
• Подключение
  • Примеры параметров SSH и kubeconfig приведены ниже

Специальные переменные

В шаблонах кластеров есть несколько специальных переменных.

Переменная dc_deckhouseVersion содержит версию Deckhouse, известную на момент рендеринга: текущую версию кластера (для уже существующего кластера) либо версию, разрешенную из хранилища образов кластера по каналу обновлений или dev-ветке. Версия указывается без префикса v (например, 1.76.3) и всегда является валидной семантической версией: у сборки из dev-ветки версии нет, поэтому для нее переменная равна 0.0.0, а имя ветки доступно в dc_deckhouseDevBranch — семвер-функции вроде semverCompare не падают на рендеринге.

Переменная dc_deckhouseEdition содержит издание того же разрешенного релиза (например, EE или CSE) из лейбла образа релиза. Оно может быть пустым, если у образа нет лейбла издания, — используйте default. Регистр значения соответствует лейблу; сравнивайте без учета регистра: {{ if eq (.dc_deckhouseEdition | lower) "cse" }}.

Переменная dc_deckhouseDevBranch содержит имя dev-ветки (main, pr1234), а для каналов обновлений и зафиксированных версий она пуста, поэтому заодно работает как флаг: {{ if .dc_deckhouseDevBranch }}.

Переменные можно использовать и как обычные значения, и в логике шаблона:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-info
data:
  deckhouseVersion: "{{ .dc_deckhouseVersion }}"
  edition: "{{ .dc_deckhouseEdition }}"
  build: {{ if .dc_deckhouseDevBranch }}dev-{{ .dc_deckhouseDevBranch }}{{ else }}release{{ end }}
  metrics: {{ if semverCompare ">=1.76.0" .dc_deckhouseVersion }}v2{{ else }}v1{{ end }}

Особенности:

• Шаблон не должен вычислять releaseChannel, imagesRepo или dev-ветку на основе dc_deckhouseVersion, dc_deckhouseEdition или dc_deckhouseDevBranch: версия разрешается на основе этих параметров, поэтому такое использование циклично и завершает рендеринг с ошибкой.

Параметры хранилища образов

Все параметры хранилища образов, выбранного для кластера, доступны в шаблонах конфигурации кластера, ресурсов и параметров SSH как переменные dc_registry*. Каждое поле записи хранилища образов отдаётся как есть, а к нему — производные значения в том виде, в котором их ожидают конфигурации DKP.

Переменные существуют всегда: незаданное значение — пустая строка, поэтому их можно проверять через {{ if .dc_registryCA }}. Значения подставляются и в превью, и при установке, а после смены хранилища образов кластера обновляются.

Секция InitConfiguration для DKP ниже 1.75:

apiVersion: deckhouse.io/v1
kind: InitConfiguration
deckhouse:
  imagesRepo: {{ .dc_registryImagesRepo }}
  registryDockerCfg: {{ .dc_registryDockerCfg }}
  registryScheme: {{ .dc_registryScheme }}
  {{- if .dc_registryCA }}
  registryCA: |
    {{- .dc_registryCA | nindent 4 }}
  {{- end }}

Секция ModuleConfig deckhouse для DKP 1.75 и выше:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse
spec:
  version: 1
  settings:
    registry:
      mode: Direct
      direct:
        imagesRepo: {{ .dc_registryImagesRepo }}
        scheme: {{ .dc_registryScheme }}
        username: {{ .dc_registryUsername | quote }}
        password: {{ .dc_registryPassword | quote }}
        {{- if .dc_registryCA }}
        ca: |
          {{- .dc_registryCA | nindent 10 }}
        {{- end }}

В секции ModuleConfig deckhouse для режима Unmanaged модуля registry вместо mode: Direct и секции direct используйте mode: Unmanaged и секцию unmanaged с теми же полями.

Ручной режим хранилища образов

В режимах Direct, Unmanaged и «InitConfiguration (deprecated)» Deckhouse Commander сам добавляет секцию хранилища образов в конфигурацию: в ModuleConfig deckhouse для Direct и Unmanaged (с соответствующим режимом модуля registry) и в InitConfiguration для «InitConfiguration (deprecated)». Если шаблон описывает эту секцию сам — например, для нестандартной сборки DKP, — выберите для кластера режим «Вручную (YAML)» (Manual). В ручном режиме Deckhouse Commander не добавляет и не проверяет секцию хранилища образов, а переменные dc_registry* — единственный способ получить в шаблоне параметры выбранного хранилища образов. Секцию InitConfiguration разместите в шаблоне конфигурации кластера рядом с ClusterConfiguration, секцию ModuleConfig deckhouse — в шаблоне ресурсов.

Если шаблон содержит секцию хранилища образов, а выбран любой режим, кроме «Вручную (YAML)», в интерфейсе показывается предупреждение: установщик отклонит конфигурацию с двумя описаниями хранилища образов. Наличие секции в шаблоне в ручном режиме Deckhouse Commander не проверяет — за неё отвечает автор шаблона. Если ни один из шаблонов версии (конфигурация кластера, размещение, dhctl-конфигурация, ресурсы, первичные ресурсы и шаблоны групп ресурсов) не использует переменные dc_registry*, под переключателем режима показывается предупреждение: в этом режиме необходимо обеспечить генерацию конфигурации хранилища образов через YAML-конфигурацию шаблона кластера. Проверка выполняется по тексту шаблонов в браузере и не блокирует сохранение. Под переключателем ручного режима интерфейс также показывает пример секции registry для ModuleConfig/deckhouse в режиме Direct с переменными dc_registryImagesRepo, dc_registryScheme, dc_registryUsername и dc_registryPassword.

Установщик в ручном режиме выбирается по записи хранилища образов, выбранной для кластера, а не по секции в шаблоне: секция может находиться там, где её ожидает конкретная версия DKP. Канал обновлений по-прежнему берётся из шаблона (releaseChannel в ModuleConfig deckhouse), если у хранилища образов не задана dev-ветка.

Обязательные манифесты

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

Параметры SSH для облачного кластера

Для облачного кластера можно использовать приватный ключ, созданный Deckhouse Commander, если вы не предоставляете заранее определенный ключ в образе ОС. Также в образах виртуальных машин будет создан пользователь, под которым Deckhouse Commander подключится к созданной машине, чтобы завести ее как master-узел.

apiVersion: dhctl.deckhouse.io/v1
kind: SSHConfig
# имя пользователя для SSH, определяется образом ОС в разделе «Размещение»
sshUser: ubuntu
sshPort: 22
# приватный ключ, который будет использовать для подключения к ВМ по SSH
sshAgentPrivateKeys:
- key: |
    {{- .dc_sshPrivateKey | nindent 4 }}

Параметры SSH и ресурсы для статического кластера

Так как машины созданы заранее, и на них настроен сервер SSH, пользователь и ключ, то эти данные необходимо сообщить во входных параметрах кластера. В отличие от облачной конфигурации выше, мы используем не встроенный параметр, а явно переданный пользователем. Часть данных всегда можно задать внутри шаблона, если их параметризация не представляется целесообразной.

Обратите внимание на манифесты SSHHost. Они объявляют IP-адреса, к которому у Deckhouse Commander есть доступ. В данном примере предполагается, что входной параметр .masterHosts — это список IP-адресов, на основании которых в конфигурации будет набор SSH-хостов. Так как это мастера, их следует указывать в количестве 1 или 3.

apiVersion: dhctl.deckhouse.io/v1
kind: SSHConfig
# имя пользователя и порт для SSH, сконфигурированные на машинах
sshUser: {{ .sshUser }}
sshPort: {{ .sshPort }}
# приватный ключ, используемый на машинах, передается как входной параметр в кластер
sshAgentPrivateKeys:
- key: |
    {{- .sshPrivateKey | nindent 4 }}

{{- range $masterHost := .masterHosts }}
---
apiVersion: dhctl.deckhouse.io/v1
kind: SSHHost
host: {{ $masterHost.ext_ip }}
{{- end }}

Deckhouse Commander подключится только к одному SSH-хосту в переданном списке, будет пробовать хосты по порядку до первого успешного подключения. Первый подключенный хост станет master-узлом кластера. Когда Deckhouse установится на первом master-узле, он сможет сам добавить два оставшихся master-узла в кластер, если они заявлены в шаблоне. Для этого нужно сообщить Deckhouse, что машины существуют, как на них попасть, и что их нужно добавить в кластер. Для этого необходимо для двух мастеров создать StaticInstance, определить для них SSHCredentials, а также явно прописать группу узлов master с параметром spec.staticInstances.count=2, чтобы два статических master-узла не только были известны Deckhouse, но и были востребованы как master-узлы. Эту часть шаблона целесообразно определить в «Ресурсах». Ниже представлен код шаблона для этой задачи:

---
apiVersion: deckhouse.io/v1alpha1
kind: SSHCredentials
metadata:
  name: commander-ssh-credentials
  labels:
    heritage: deckhouse-commander
spec:
  sshPort: {{ .sshPort }}
  user: {{ .sshUser }}
  privateSSHKey: {{ .sshPrivateKey | b64enc }}

{{- if gt (len .masterHosts) 1 }}
{{-   range $masterInstance := slice .masterHosts 1 }}
---
apiVersion: deckhouse.io/v1alpha1
kind: StaticInstance
metadata:
  labels:
    type: master
    heritage: deckhouse-commander
  name: {{ $masterInstance.hostname | quote }}
spec:
  address: {{ $masterInstance.ip | quote }}
  credentialsRef:
    apiVersion: deckhouse.io/v1alpha1
    kind: SSHCredentials
    name: commander-ssh-credentials
{{-   end }}
{{- end }}

{{- if gt (len .masterHosts) 1 }}
---
apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: master
  labels:
    heritage: deckhouse-commander
spec:
  disruptions:
    approvalMode: Manual
  nodeTemplate:
    labels:
      node-role.kubernetes.io/control-plane: ""
      node-role.kubernetes.io/master: ""
    taints:
    - effect: NoSchedule
      key: node-role.kubernetes.io/master
    - effect: NoSchedule
      key: node-role.kubernetes.io/control-plane
  nodeType: Static
  staticInstances:
    count: 2
    labelSelector:
      matchLabels:
        type: master
{{- end }}

Kubeconfig для managed-кластера

Managed-кластер — кластер Kubernetes, control plane которого управляется провайдером (например, Amazon EKS). Установка в managed-кластер доступна для Deckhouse 1.78 и выше. В шаблоне такого кластера раздел «Kubernetes» (ClusterConfiguration) пустой, а в разделе «Подключение» вместо SSHConfig указывается kubeconfig целевого кластера — подстановкой входного параметра:

{{ .kubeconfig }}

Параметр объявляется как обычный входной параметр шаблона. format: password и multiline: true нужны, чтобы поле корректно отображалось и маскировалось в интерфейсе:

- key: kubeconfig
  type: string
  format: password
  multiline: true
  title: Kubeconfig целевого кластера
  description: |
    Kubeconfig с правами администратора в целевом кластере.

В предустановленном шаблоне «Managed Kubernetes» параметр называется kubeconfig.

Оставьте раздел «Скрипт после установки» в шаблоне managed-кластера пустым: скрипт выполняется по SSH, и с непустым разделом Deckhouse Commander не устанавливает и не изменяет кластер.

Ресурсы: модуль commander-agent

Deckhouse Commander синхронизирует ресурсы с помощью модуля commander-agent. Этот модуль устанавливается в прикладном кластере. Приложение commander-agent запрашивает актуальный список ресурсов для кластера и актуализирует их в кластере, в котором работает. Если модуль не настроен, в ресурсах необходимо создать манифест, включающий модуль.

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: commander-agent
  labels:
    heritage: deckhouse-commander
spec:
  enabled: true
  version: 1
  settings:
    commanderUrl: "https://{{ .dc_domain }}/agent_api/{{ .dc_clusterUUID }}"

Схема параметров кластера и записи инвентаря

Есть две формы, которые пользователь собирает с помощью схемы:

• форма параметров кластера (входные параметры шаблона кластера),
• форма записи.

Схема определяет объект. Всегда есть возможность редактировать ее в визуальном редакторе формы.

Общедоступные поля

Ввод строки

Строка со значением по умолчанию

- key: something
  type: string
  title: Некое значение
  default: Ввода нет

Необязательный параметр, его разрешено не заполнять (optional)

- key: something
  type: string
  title: Некое значение
  optional: true

Параметр заполняется один раз при создании записи или кластера, и далее его нельзя редактировать (immutable)

- key: something
  type: string
  title: Некое значение
  immutable: true

Пароль и пояснение к нему (см format и description)

- key: password
  type: string
  format: password
  minLength: 8
  span: 2
  title: Пароль
  description: |
    Придумайте нормальный пароль.

    Пароль должен содержать то-то и то-то и обновляться каждые N дней.

Ввод числа

Можно задать максимум и необязательность

- key: ordinarySize
  type: number
  optional: true
  max: 13

Можно задать минимум и сделать поле ввода на 4 колонки (максимальная ширина)

- key: eliteSize
  type: number
  description: In cm
  min: 18
  span: 4

Можно задать максимум и минимум

- key: elephantSize
  type: number
  description: In meters
  min: 0.7
  max: 2.5
  span: 1

Ввод предопределенных значений

Простые значения

Выбор из заранее заданных значений. В интерфейсе пользователь видит то значение, которое выбирает

- key: kubeVersion
  type: string
  title: Версия Kubernetes
  enum:
    - Automatic
    - "1.25"
    - "1.26"
    - "1.27"

Сложные значения

Выбор из заранее заданных объектных значений. В интерфейсе пользователь видит значение из text, в то время как для шаблона технически выбирается value. Обратите внимание, что в value доступны только значения типа object (ключ-значение). Это значение не описывается схемой, структура объекта произвольна.

- key: kubeVersion
  title: Версия Kubernetes
  select:
    - text: По умолчанию
      value:
        version: Automatic
        isSupported: true
    - text: 1.25 (поддержка закончится в марте)
      value:
        version: 1.25.8
        isSupported: true
    - text: 1.26
      value:
        version: 1.26.4
        isSupported: true
    - text: 1.27
      value:
        version: 1.27.3
        isSupported: true
    - text: 1.28 (экспериментальная)
      value:
        version: 1.28.0
        isSupported: false

Поля, доступные в шаблоне кластера

Выбор одной записи из каталога

Каталоги имеют неизменяемое техническое имя (slug). Оно указывается в свойстве catalog:

- key: slot
  catalog: yandex-cloud-slot
  title: Слот для кластера
  immutable: true
  description: >
    Выберите букву. Она определит домен, префикс в облаке и IP-адрес. Этот слот
    уникален для всех кластеров независимо от шаблона.

    Допустим вы выбрали `N`. Шаблон домена будет `%s.X.kube.example.com`. Назовите кластер `dev-X`.

    Логин и пароль — всегда `admin@example.com`

Выбор нескольких записей

Множественный выбор обеспечивается парой свойств: minItems и maxItems. Любое поле можно сделать списком данных, если указать оба этих поля.

- key: slot
  catalog: virtual-machines
  title: Воркер-узлы
  description: Сколько угодно воркеров, можно редактировать
  minItems: 0
  maxItems: 10000

Автовыбор

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

- key: publicAddressesForFrontendNodes
  title: Публичные адреса
  catalog: public-ip-addresses
  minItems: 3
  maxItems: 3
  autoselect: true

Составные части

Разделитель

header

• Тип: string

Единственный тип разделителя — заголовок. Он поддерживает только текст. Других свойств у него нет.

- header: Доступ к образам

Свойства полей ввода

key

• Тип: string

Значение поля ввода нужно идентифицировать в шаблоне. Поэтому всегда должно быть свойство поля key — это имя поля будет использоваться в шаблоне во время рендеринга конфигурации.

• Обязательное поле

В схеме:

- key: podSubnet
  title: Подсеть подов
  type: string

В шаблоне:

podSubnet: {{.podSubnet | quote }}

type

• Тип: string
• Обязательное поле
• Допустимые значения:
  • string
  • number
  • boolean
  • array

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

title

• Тип: string
• Обязательное поле

У поля есть название, передающее смысл. Это одна строка текста. Оно отображается в форме параметров и в аудите.

description

• Тип: string

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

default

• Тип: зависит от type

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

format

• Тип: string

У строк может быть формат, который определит особенности отображения и особенности валидации значений.

• Допустимые значения:
  • password
  • date-time
  • url
  • email
  • uuid
  • cuid
  • cuid2
  • ulid
  • emoji

span

• Тип: number
• Допустимые значения: 1, 2, 3, 4
• По умолчанию: 1

Это декоративное свойство, которое указывает, какую ширину занять на экране в долях: от 1 до 4. Поля ввода заполняют форму построчно по горизонтали, как текст. При этом ширина «строки» формы — это 4 элемента.

optional

• Тип: boolean
• По умолчанию: false

Этот флаг говорит о том, что поле необязательное. Пустое значение будет проигнорировано, и свойство не будет передано в шаблон.

immutable

• Тип: boolean
• По умолчанию: false

Этот флаг говорит о том, что поле заполняется только один раз, когда появляется во входных параметрах. Это поле становится недоступным для редактирования, если оно было уже заполнено. Это означает, что при обновлении кластера на новый шаблон с immutable-полем, его можно заполнить. Иммутабельность зависит от жизненного цикла параметра в форме, а не кластера.

enum

• Тип: array

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

type: array, items.suggestions и items.enum

• type: array — значение поля представляет собой массив строк (list validation в JSON Schema).
• items.suggestions — обязателен как массив для мультиселекта с возможностью ввода произвольных значений. Перечисленные варианты отображаются как опции; пользователь может также ввести свои строки. Пустой массив ([]) означает отсутствие пресетов, только свободный ввод. Применимо только к простым строковым элементам (не к объектному select и не к catalog).
• items.enum — строгий мультиселект: допустимы только перечисленные строки, произвольные значения запрещены.

Мультиселект с возможностью создания:

- key: kubeVersions
  type: array
  title: Версии Kubernetes
  items:
    type: string
    suggestions:
      - "1.32"
      - "1.33"
      - "1.34"

С возможностью создания без пресетов:

- key: tags
  type: array
  title: Теги
  items:
    type: string
    suggestions: []

Строгий мультиселект:

- key: harddrive
  type: array
  title: Выбор диска
  items:
    enum:
      - "sdk1"
      - "sdk2"

К любой из форм при необходимости добавьте minItems / maxItems.

selector

• Тип: array

Это более сложный вариант enum. В нем заложено строковое представление объекта (text) и произвольно сложное значение в value, которое будет выбрано для шаблона. Текст указывают для людей, а значения — для шаблона.

Пример:

- key: kubeVersion
  title: Версия Kubernetes
  select:
    - text: По умолчанию
      value:
        version: Automatic
        isSupported: true
    - text: 1.25 (поддержка закончится в марте)
      value:
        version: 1.25.8
        isSupported: true
    - text: 1.26
      value:
        version: 1.26.4
        isSupported: true
    - text: 1.27
      value:
        version: 1.27.3
        isSupported: true
    - text: 1.28 (экспериментальная)
      value:
        version: 1.28.0
        isSupported: false

catalog

• Тип: string

Выбор одного значения из каталога. В значение вписать slug каталога. Поле type указывать не нужно, потому что фактически это object, схема которого описана в указанном каталоге. Чтобы выбрать несколько значений (и получить список записей на входе в шаблон), используйте minItems и maxItems.

Пример:

- key: workerMachine
  title: Виртуальная машина
  catalog: virtual-machines

- key: workerMachines
  title: Виртуальные машины
  catalog: virtual-machines
  minItems: 1
  maxItems: 10

maxLength (для строки)

• Тип: number

Для type: string это поле добавляет валидацию на длину строки

minItems, maxItems (для выбора записей)

• Тип: number

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

autoselect (для выбора записей)

• Тип: boolean
• По умолчанию: false

Иногда пользователю не столь важно, какая именно запись будет выбрана. Тогда форма выбирает сама за пользователя доступные записи. Но у пользователя при этом всегда есть возможность их изменить.

Пример:

- key: publicAddressesForFrontendNodes
  title: Публичные адреса
  catalog: public-ip-addresses
  minItems: 3
  maxItems: 3
  autoselect: true

identifier

• Тип: boolean
• По умолчанию: зависит от заполнения

Запись — это плоский объект. У записи есть компактное представление в одну строку, составленное из значений полей записи (без ключей). Значения записи указаны через запятую в порядке, заданной схемой. Это компактное представление можно видеть как в перечне записей внутри каталога, так и в выборе записи в форме кластера (выпадающие списки). Чтобы выбрать ограниченный набор полей для компактного отображения записи, используйте свойство identifier.

Например, рассмотрим запись и возможные варианты ее схемы

## Запись
login: anatoly
password: E3xE#%DH@hW
age: 42

- key: login
  type: string
  title: Логин
  unique: true
  pattern: ^[a-z0-9.-]+$

- key: password
  type: string
  title: Пароль
  format: password

- key: age
  type: number
  title: Возраст

 - key: login
   type: string
   title: Логин
   unique: true
   pattern: ^[a-z0-9.-]+$

 - key: password
   type: string
   title: Пароль
   format: password
+  identifier: false

 - key: age
   type: number
   title: Возраст

 - key: login
   type: string
   title: Логин
   unique: true
   pattern: ^[a-z0-9.-]+$
+  identifier: true

 - key: password
   type: string
   title: Пароль
   format: password

 - key: age
   type: number
   title: Возраст
+  identifier: true

unique

• Тип: boolean
• По умолчанию: false

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

Также этим флагом помечаются поля кластера, которые должны быть уникальными среди всех кластеров. Неуникальные данные запрещено сохранять: создание и редактировать кластера завершится с ошибкой валидации.

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

- key: subnetCIDR
  type: string
  title: CIDR подсети
  unique: true