Guide

The module is available only in Deckhouse Enterprise Edition.

The module is actively developed. It might significantly change in the future.

Address

Given the public domain template in a cluster is %s.example.com, Deckhouse Commander will be available at https://commander.example.com.

Cluster and Resource Parameter Scheme

There are two forms based on input parameter scheme:

cluster parameter form, the input scheme is specified in a cluster template;
resource form, the input scheme is specified in its catalog.

The scheme defines an object. There is always an option to edit it in the visual form editor.

Common fields

Text input

A string with default value

- key: something
  type: string
  title: Something
  default: No input

Optional parameter

- key: something
  type: string
  title: Something
  optional: true

The parameter is filled once during the creation of the resource or cluster, and then it cannot be edited (immutable).

- key: something
  type: string
  title: Something
  immutable: true

The password and its description (see format and description)

- key: password
  type: string
  format: password
  minLength: 8
  span: 2
  title: Password
  description: |
    Create a good password.

    The password must contain such and such elements and be updated every N days.

Number input

One can specify the maximum value and mark the field as optional

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

One can set a minimum and make the input field span over 4 columns (it is maximum width).

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

One can set maximum and minimum values.

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

Predefined values

Simple values

Selection of predefined values. The user sees in the interface the value that they select.

- key: kubeVersion
  type: string
  title: Kubernetes Version
  enum:
    - Automatic
    - "1.25"
    - "1.26"
    - "1.27"

Complex values

Selection of pre-defined object values. In the interface, the user sees a value from text, while technically value is chosen for the template. Note that in value only object (key-value) type values are available. This value is not described by a schema, the structure of the object is arbitrary.

- key: kubeVersion
  title: Kubernetes Version
  select:
  - text: Default
    value:
       version: Automatic
       isSupported: true
  - text: 1.25 (EOL in March)
    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 (experimental support)
    value:
       version: 1.28.0
       isSupported: false

Fields supported in cluster template

Single resource from a catalog

Catalogs have an unchangeable technical name (slug). It is specified in the catalog property:

- key: slot
  catalog: yandex-cloud-slot
  title: Cloud slot for the cluster
  immutable: true
  description: >
    Select a letter. It will determine the domain, prefix in the cloud, and IP address.
    This slot is unique for all clusters regardless of the template.

    Let's say you chose 'N'. The domain template will be '%s.X.kube.example.com'.
    We recommend naming the cluster 'dev-X'.

    The login and password are always 'admin@example.com'.

Multiple resources from a catalog

Multiple choice is provided by a pair of properties: minItems and maxItems. Any field can be made a list of data if both of these fields are specified.

- key: slot
  catalog: virtual-machines
  title: Worker nodes
  description: Any count of worker nodes
  minItems: 0
  maxItems: 10000

Auto-selection

Sometimes it is not important to the user which resource is selected from the pool of resources. Therefore, auto-selection makes a substitution of a free resource automatically. The automatically selected resource can be replaced manually with another one.

- key: publicAddressesForFrontendNodes
  title: Public addresses
  catalog: public-ip-addresses
  minItems: 3
  maxItems: 3
  autoselect: true

Parts

Separators

`header`

Type: string

The only type of a divider is a header. It supports only text. It has no other properties.

- header: Access to container images

Properties of input fields

`key`

Type: string
Required

It is necessary to identify the value of an input field in a template. Therefore, there must always be a key field property — this field name will be used in the template during configuration rendering.

In the schema:

- key: podSubnet
  title: Pod subnet
  type: string

In a template:

podSubnet: {{ .podSubnet | quote }}

`type`

Type: string
Required
Supported values:
- string
- number
- boolean

The value has a predefined type: string, number, or boolean.

`title`

Type: string
Required

The field has a title that conveys meaning. It is one line of text. It is displayed in the parameter form and in the audit.

`description`

Type: string

A field may have a comment that reveals the meaning, explains boundary conditions, recording format or exceptions. There may be several lines of text.

`default`

Type: depends on type

The Default value is filled in if the field is marked optional. Also, this value is shown to the user, for example, in the form of a placeholder. The value type of this property must match the type.

`format`

Type: string
Supported values:
- password
- date-time
- url
- email
- uuid
- cuid
- cuid2
- ulid
- emoji

String parameters can have a format that determines the specifics of their display and validation.

`span`

Type: number
Supported values: 1, 2, 3, 4
Default: 1

This is a decorative property that specifies how much width to occupy on the screen in fractions: from 1 to 4. Input fields fill the form one line at a time horizontally, like text. In this case, the width of a “line” in the form is 4 elements.

`optional`

Type: boolean
Default: false

This flag indicates that the field is optional. An empty value will be ignored and the property will not be passed to the template.

`immutable`

Type: boolean
Default: false

This flag indicates that the field is filled only once when it appears in the input parameters. The field becomes unavailable for editing if it has already been filled. This means that when you update a cluster to a new template with an immutable field, you can fill it in.

Immunity depends on the life cycle of the parameter in the form, not the cluster.

`enum`

Type: array

Lists the possible values that the field accepts. The field is represented by a select regardless of the value type selected in type.

`selector`

Type: array

This is a more complex version of enum. It provides a string representation of an object (text) and an arbitrarily complex value in value that will be selected for the template. The text is provided for humans, and the values are for the template.

Example:

- key: kubeVersion
  title: Kubernetes Version
  select:
  - text: Default
    value:
       version: Automatic
       isSupported: true
  - text: 1.25 (EOL in March)
    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 (experimental support)
    value:
       version: 1.28.0
       isSupported: false

`catalog`

Type: string

Selecting one value from the resources catalog. Write the slug of the resources catalog in the value. The type field does not need to be specified, because in fact it is object, the schema of which is described in the specified catalog. To select several values (and get a list of resources at the entrance to the template), use minItems and maxItems.

Example:

- key: workerMachine
  title: Virtual machine
  catalog: virtual-machines

- key: workerMachines
  title: Virtual machines
  catalog: virtual-machines
  minItems: 1
  maxItems: 10

`maxLength` (for strings)

Type: number

For type: string, this field adds validation on the string length.

`minItems`, `maxItems` (for resources selection)

Type: number

Validation of the number of items selected from the resource catalog. This pair of fields is optional, but it is prohibited to use them separately: if used, then both at once.

`autoselect` (for resources selection)

Type: boolean
Default: false

Sometimes, it is not so important for the user which specific resource is chosen. In this case, the form chooses an available resource for the user. However, the user always has the option to change them.

Example:

- key: publicAddressesForFrontendNodes
  title: Public addresses
  catalog: public-ip-addresses
  minItems: 3
  maxItems: 3
  autoselect: true

`identifier`

Type: boolean
Default: depends on values

A resource is a flat object. A resource has a compact one-line representation made up of the field values of the resource (without keys). The resource values are separated by commas in the order specified by the schema. This compact representation can be seen both in the list of resources inside the directory and in the selection of a resource in a cluster view (dropdown lists). To select a limited set of fields for a compact display of a resource, use the identifier property.

For example, consider a resource and its possible schema options.

## Resource
login: John
password: E3xE#%DH@hW
age: 42

Show all fields Hide a field Choose shown explicitly

Scheme

	Show all fields	Hide a field	Choose shown explicitly
Scheme	`- key: login type: string title: Username unique: true pattern: ^[a-z0-9.-]+$ - key: password type: string title: Password format: password - key: age type: number title: Age`	`- key: login type: string title: Username unique: true pattern: ^[a-z0-9.-]+$ - key: password type: string title: Password format: password + identifier: false - key: age type: number title: Age`	`- key: login type: string title: Username unique: true pattern: ^[a-z0-9.-]+$ + identifier: true - key: password type: string title: Password format: password - key: age type: number title: Age + identifier: true`
Representation	`John, E3xE#%DH@hW, 42`	`John, 42`	`John, 42`
Behavior	`identifier=true` is the default for all fields	`identifier=true` is the default for all fields, `identifier=false` applies indiviually	`identifier=false` is the default for all fields if `identifier=true` is explicitly set somewhere

- key: login
  type: string
  title: Username
  unique: true
  pattern: ^[a-z0-9.-]+$

- key: password
  type: string
  title: Password
  format: password

- key: age
  type: number
  title: Age

 - key: login
   type: string
   title: Username
   unique: true
   pattern: ^[a-z0-9.-]+$

 - key: password
   type: string
   title: Password
   format: password
+  identifier: false

 - key: age
   type: number
   title: Age

 - key: login
   type: string
   title: Username
   unique: true
   pattern: ^[a-z0-9.-]+$
+  identifier: true

 - key: password
   type: string
   title: Password
   format: password

 - key: age
   type: number
   title: Age
+  identifier: true

Representation

John, E3xE#%DH@hW, 42

John, 42

Behavior

identifier=true is the default for all fields

identifier=true is the default for all fields, identifier=false applies indiviually

identifier=false is the default for all fields if identifier=true is explicitly set somewhere

`unique`

Type: boolean
Default: false

This flag marks resource fields that must be unique within a catalog. It is prohibited to create, restore from archive, or import non-unique data.

This flag also marks cluster fields that must be unique among all clusters. Saving a cluster with non-unique data will result in a validation error and prevent creation and editing of the cluster.

The selection from a catalog for clusters is unique to the extent that resources are unique. It is not necessary to mark a selection from a catalog with this flag.

- key: subnetCIDR
  type: string
  title: Subnet CIDR
  unique: true

Address

Cluster and Resource Parameter Scheme

Common fields

Text input

Number input

Predefined values

Simple values

Complex values

Fields supported in cluster template

Single resource from a catalog

Multiple resources from a catalog

Auto-selection

Parts

Separators

header

Properties of input fields

key

type

title

description

default

format

span

optional

immutable

enum

selector

catalog

maxLength (for strings)

minItems, maxItems (for resources selection)

autoselect (for resources selection)

identifier

unique

`header`

`key`

`type`

`title`

`description`

`default`

`format`

`span`

`optional`

`immutable`

`enum`

`selector`

`catalog`

`maxLength` (for strings)

`minItems`, `maxItems` (for resources selection)

`autoselect` (for resources selection)

`identifier`

`unique`