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

Концепции

dhctl

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

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

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

1. config.yaml
   1. InitConfiguration — конфигурация установки кластера, содержит адрес реестра контейнеров и доступ к нему
   2. Ресурсы ModuleConfig — конфигурация встроенных модулей: явное включение или выключение, а так же переопределение настроек по умолчанию
   3. ClusterConfiguration — конфигурация Kubernetes: версия, подсетей подов, сервисов и т.п.
   4. Параметры размещения
      1. <Provider>ClusterConfiguration — параметры размещения кластера в облаке или API виртуализации, если Deckhouse Kubernetes Platform устанавливается не на статические ресурсы;
      2. или StaticClusterConfiguration для статического кластера
2. resources.yaml
   1. Произвольные ресурсы Kubernetes в том числе ModuleConfig для не встроенных модулей в Deckhouse Kubernetes Platform
3. SSHConfig
   1. Имя пользователя, пароль и ключ для подключения к существующей машине или той, которая будет создана в процессе создания кластера
   2. IP-адрес машины, если кластер разворачивается на статических ресурсах и адрес будущего мастер-узла известен заранее
   3. Остальные параметры можно посмотреть в справке команды dhctl, в данной документации дополнительные детали несущественны

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

Как видно, вся предоставленная конфигурация используется для того, чтобы создать кластер. Для этого используется dhctl bootstrap со всей предоставленной конфигурацией.

Изменения, которые можно внести в кластер тем же инструментом, касаются либо параметров размещения (например, ресурсы перманентных узлов, созданных Terraform) либо параметров Kubernetes. Только настройки подключения и общие параметры кластера доступны для изменения с dhctl converge. Но изменение конфигурации платформы или дополнительные ресурсы кластера таким образом не применить.

Наконец, чтобы удалить кластер, достаточно иметь к нему подключение: операция dhctl destroy использует только SSHConfig.

Deckhouse Commander

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

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

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

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

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

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

• Входные параметры
• Kubernetes
  • ClusterConfiguration
• Размещение
  • Статические ресурсы
  • Yandex Cloud
  • VMware Cloud Director
  • VMware vSphere
  • OpenStack
  • Amazon Web Services
  • Google Cloud Platform
  • Microsoft Azure
• Параметры SSH
  • См. примеры ниже
• Ресурсы
  • Произвольные манифесты ресурсов Kubernetes и Deckhouse. Deckhouse Commander будет синхронизировать эти ресурсы.
• Первичные ресурсы
  • Произвольные манифесты ресурсов Kubernetes и Deckhouse. Deckhouse Commander не будет синхронизировать эти ресурсы.
• Стартовая конфигурация
  • InitConfiguration

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

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

Параметры 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-хосту в переданном списке, будет пробовать хосты по порядку до первого успешного подключения. Первый подключенный хост станет мастер-узлом кластера. Когда Deckhouse установится на первом мастер-узле, он сможет сам добавить два оставшихся мастер-узла в кластер, если они заявлены в шаблоне. Для этого нужно сообщить Deckhouse, что машины существуют, как на них попасть, и что их нужно добавить в кластер. Для этого необходимо для двух мастеров создать StaticInstance, определить для них SSHCredentials, а также явно прописать группу узлов master с параметром spec.staticInstances.count=2, чтобы два статических мастер-узла не только были известны 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 }}

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

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

Обратите внимание на commanderUrl. Вам предстоит уточнить схему этого адреса: HTTP или HTTPS.

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

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

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.

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