Руководство

Модуль доступен только в Deckhouse Enterprise Edition.

Модуль находится в процессе активного развития. Функциональность может существенно измениться.

Адрес

Если шаблон публичных доменов в кластере %s.example.com, то в веб-приложение можно зайти по адресу https://commander.example.com

Схема параметров кластера и ресурса

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

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

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

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

Ввод строки

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

- 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`
Представление	`anatoly, E3xE#%DH@hW, 42`	`anatoly, 42`	`anatoly, 42`
Поведение	По умолчанию для всех полей `identifier=true`	По умолчанию для всех полей `identifier=true`, а `identifier=false` работает для индивидуального поля	Если явно указано `identifier=true` хотя бы одном поле, то по умолчанию для всех полей `identifier=false`

- 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

Представление

anatoly, E3xE#%DH@hW, 42

anatoly, 42

Поведение

По умолчанию для всех полей identifier=true

По умолчанию для всех полей identifier=true, а identifier=false работает для индивидуального поля

Если явно указано identifier=true хотя бы одном поле, то по умолчанию для всех полей identifier=false

`unique`

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

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

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

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

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

Адрес

Схема параметров кластера и ресурса

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

Ввод строки

Ввод числа

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

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

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

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

Выбор одного ресурса из каталога

Выбор нескольких ресурсов

Автовыбор

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

Разделитель

header

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

key

type

title

description

default

format

span

optional

immutable

enum

selector

catalog

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

minItems, maxItems (для выбора ресурсов)

autoselect (для выбора ресурсов)

identifier

unique

`header`

`key`

`type`

`title`

`description`

`default`

`format`

`span`

`optional`

`immutable`

`enum`

`selector`

`catalog`

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

`minItems`, `maxItems` (для выбора ресурсов)

`autoselect` (для выбора ресурсов)

`identifier`

`unique`