User Guide

Address

If the public domain template in the %s.example.com cluster, the web application can be accessed at https://commander.example.com.

Workspaces

Working with Deckhouse Commander entities is carried out within workspaces. Workspaces can be created and given a new name. In the future, access to workspaces will be possible to control in detail.

Users manage clusters, cluster templates and inventory within a workspace. Also, an API access token is issued within the workspace. The visibility of objects for such a token will be limited only to what is located in the workspace.

Clusters

We recommend installing Deckhouse Commander in the control cluster. This cluster should serve the purpose of centralized management and information collection from the entire application infrastructure, including application clusters. Clusters managed by Deckhouse Commander are called application clusters. Deckhouse Commander is the source of truth for cluster configuration. We will look at how this works in practice.

Cluster configuration

The cluster configuration consists of several sections:

1. Input parameters are formed based on the input parameter schema of the cluster template.
2. Container Registry – select the registry from which the Deckhouse cluster will be installed.
3. Infrastructure section:
   • Kubernetes — ClusterConfiguration.
   • Placement — <Provider>ClusterConfiguration or StaticClusterConfiguration.
   • SSH settings — connection to the cluster master nodes.
4. Kubernetes section — an arbitrary number of tabs with Kubernetes manifests.

Cluster parameters (input parameters)

This is a user configuration template for the template user. See Input parameters.

Container Registry

The container registry is essential for installing and operating the Deckhouse cluster. It stores both Deckhouse releases and the dhctl tool for cluster maintenance.

The container registry is a mandatory configuration parameter for the cluster.

By default, the Deckhouse Commander installation autocreates the control cluster’s container registry for selection.

Registry Parameters

Name

A custom name for the registry displayed in the list of registries. Mandatory parameter.

Container Registry Address

The address of the container registry with Deckhouse images – URL for accessing the registry. Mandatory parameter. Example: registry.deckhouse.io/deckhouse/ee.

Container registry address must be accessible from both the control cluster where Deckhouse Commander is running and from the target cluster’s infrastructure where Deckhouse is being installed.

Authorization

All data necessary for authorization in the specified container registry. Provide a username and password, or in the Auth field, insert a base64-encoded string (corresponding to the auth field in a standard docker config). Additionally, an email may be required depending on the container registry’s authorization settings.

Access Protocol to Container Registry

Choose the access protocol to the container registry: HTTPS or HTTP.

Self-Signed Certificate

Upload a file or specify the certificate text if the specified container registry uses a self-signed certificate.

Managing Registries

Registry addition is done on the cluster creation or editing screen under the “Container Registry” tab, as well as in the “Registries” tab in the “Inventory”. To add a new registry, complete its parameters (see registry parameters).

The “create based on” button allows you to copy all the parameters of the existing registry, change them if necessary and create a new registry. Changing registry entries used in active clusters is not supported.

Registry deletion also occurs on the cluster creation or editing screen under the “Container Registry” tab and in the “Registries” tab in the “Inventory”. A registry can’t be deleted if it’s used in at least one active cluster.

Changing the cluster registry

For existing clusters managed by DKP version 1.72 and higher, it is possible to change the registry via the interface in the “Container Registry” tab (the configuration of the registry module is performed automatically based on the parameters of the selected registry in Deckhouse Commander).

When switching the cluster to another mode, you can monitor the switching status in the cluster admin web UI: Administration / System namespaces / d8-system / Configuration / Secrets / registry-state.

The following conditions in the secret registry-state mean a successful switch:

- lastTransitionTime: "..."
  message: |-
    Mode: Default
    registry.mycompany.org: all 163 items are checked
  reason: Ready
  status: "True"
  type: RegistryContainsRequiredImages
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: ContainerdConfigPreflightReady
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: TransitionContainerdConfigReady
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: InClusterProxyReady
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: DeckhouseRegistrySwitchReady
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: FinalContainerdConfigReady
- lastTransitionTime: "..."
  message: ""
  reason: ""
  status: "True"
  type: Ready

The following conditions in the secret registry-state shows a certain switching error:

- lastTransitionTime: "..."
  message: |-
    Mode: Default
    registry.mycompany.org: 162 of 163 items processed, 1 items with errors:
    - source: module/node-manager/bashible-apiserver
      image: registry.mycompany.org/deckhouse@sha256:5e3a07df520e74842f70915c213c9da918749c39c8df6250ed51b0cb892c9211
      error: HEAD https://registry.mycompany.org/v2/deckhouse/edition/manifests/sha256:5e3a07df520e74842f70915c213c9da918749c39c8df6250ed51b0cb892c9211: unexpected status code 404 Not Found (HEAD responses have no body, use GET for details)
  reason: Processing
  status: "False"
  type: RegistryContainsRequiredImages
- lastTransitionTime: "..."
  message: Transitioning to Direct
  reason: Processing
  status: "False"
  type: Ready

Infrastructure section

Kubernetes

Settings for the Kubernetes version, pod and service subnets. See ClusterConfiguration.

Placement

Features of cluster placement in the infrastructure. Here, for a static cluster, the configuration may remain empty.

• Static resources

For cloud clusters, specifics of access to the cloud API, a set of nodes that will be created automatically and monitored (including master nodes), availability zone settings, etc., are specified.

• OpenStack
• VMware Cloud Director
• VMware vSphere
• Yandex Cloud
• zVirt
• Basis.DynamiX
• Huawei Cloud
• Amazon Web Services
• Google Cloud Platform
• Microsoft Azure

SSH parameters

apiVersion: dhctl.deckhouse.io/v1
kind: SSHConfig

sshBastionHost: 10.1.2.3              # Jump host parameters, if any.
sshBastionPort: 2233
sshBastionUser: debian

sshUser: ubuntu
sshPort: 22
sshAgentPrivateKeys:                  # List of private keys, at least one key is required.
- key: |                              #
    -----BEGIN RSA PRIVATE KEY-----
    .............................
    -----END RSA PRIVATE KEY-----
  passphrase: qwerty123               # Key password, if the key is protected by it.

sshExtraArgs: -vvv                    # Additional SSH parameters.

---

apiVersion: dhctl.deckhouse.io/v1     # Description of hosts for connection.
kind: SSHHost                         # Usually there are 1 or 3 hosts assigned
host: 172.16.0.1                      # for the role of master nodes of static clusters.
---
apiVersion: dhctl.deckhouse.io/v1
kind: SSHHost
host: 172.16.0.2
---
apiVersion: dhctl.deckhouse.io/v1
kind: SSHHost
host: 172.16.0.3

Kubernetes section

Arbitrary manifests of Kubernetes and Deckhouse resources. Depending on the management mode, they will either be enforced in the cluster or created once and then ignored.

Many tabs with manifests can be created, each of which can set the management mode. This allows you to flexibly manage the mandatory and recommended configuration of the cluster.

Cluster status

Infrastructure

Managing clusters boils down to three types of operations: creating, deleting, and changing a cluster. At any given time, a cluster in Deckhouse Commander has one of the infrastructure statuses:

• New — the cluster configuration has been created in Deckhouse Commander, but the cluster itself is still awaiting creation.
• Configuration error — the cluster configuration was created in Deckhouse Commander with errors, so the cluster will not be created.
• Creating — Deckhouse Commander is deploying the cluster.
• Ready — the cluster has been created, and the infrastructure state matches the configuration specified in Deckhouse Commander.
• Changing — Deckhouse Commander is bringing the cluster state to the specified configuration.
• Change error, creation error, deletion error — internal or external errors that occurred during cluster management.
• Archived — the cluster is no longer monitored by Deckhouse Commander; it was previously deleted or left unmanaged by Deckhouse Commander.

Deckhouse Commander performs operations asynchronously using jobs. Operations are shown inside the cluster on the Configuration → Infrastructure operations tab (including for static clusters). A log of execution is available for each job. The result of the job determines the infrastructure status of the cluster.

Operation types:

• Install — Deckhouse Commander deploys a new cluster according to the configuration.
• Change — bringing the infrastructure of an existing cluster to the target state.
• Check — comparing the current infrastructure state with the target configuration without making any changes. Runs at the configured interval.
• Delete — deleting the cluster and the cloud infrastructure associated with it.
• Attach — taking an existing cluster, previously created outside of Deckhouse Commander, under management.
• Detach — releasing the cluster from Deckhouse Commander management without deleting it.

Operation statuses:

• Scheduled — the operation has been created and is waiting for a free cluster manager replica.
• In progress — the cluster manager is executing the operation.
• Successful — the operation completed normally.
• Error — the operation failed. You can retry it manually with the Retry button on the cluster page.
• System error — the operation was interrupted unexpectedly and did not report a regular operation error. For example, the dhctl process or the cluster manager process was stopped, killed by the runtime, or evicted. After this status, the operation can be retried safely.
• Critical error — the operation was interrupted unexpectedly during a phase that changes the cluster infrastructure state. The cluster infrastructure state may be inconsistent and may require manual recovery. Usually this can only happen during phases that deploy or change cluster infrastructure, not configuration.
• Canceled, Canceling, Awaiting cancellation — the operation was canceled by the user or is being canceled.
• Skipped — the operation was not executed because its result became irrelevant (for example, it was superseded by a newer operation).

Infrastructure operations are performed by the cluster manager component. With a given verification interval, the cluster manager verifies that the target and actual infrastructure configurations match. If they do not, it brings the infrastructure to the target state. If the cluster has manual processing mode enabled, the user must manually confirm the changes being made. In automatic cluster processing mode, confirmation is not requested.

The speed at which the cluster manager takes jobs is determined by the number of clusters and the number of cluster manager replicas. If the total number of jobs greatly exceeds the number of cluster manager replicas, then operations on clusters will be delayed.

Kubernetes

In addition to the infrastructure status, the cluster also has a Kubernetes configuration status. It indicates whether the cluster matches the configuration of the Kubernetes manifests. Resource manifests (hereinafter referred to as simply «resources») are part of the cluster configuration.

The Kubernetes configuration status can have three values:

• Configured — full compliance.
• Not configured — discrepancy between the configuration and the state of the cluster.
• No data — data on the configuration status is outdated.

The component responsible for ensuring that the cluster matches the specified resource configuration is installed inside the application cluster — the Deckhouse Commander agent or commander-agent (hereinafter referred to as simply the «agent»). The agent always tries to bring the cluster configuration to the specified one.

The agent connects to the Deckhouse Commander API and downloads resource manifests, then applies them. If a resource created by the agent is deleted in the application cluster, the agent will recreate the resource within a minute. If a resource is deleted from the cluster configuration, the agent will delete the resource in the application cluster. If the agent cannot apply a resource for some reason, the Kubernetes status in Deckhouse Commander will be «not configured».

Each group of Kubernetes resources can have an independent configuration control mode. The «Kubernetes» configuration does not explicitly participate in the reconciliation operation; the agent does this in a separate hidden cycle. The result of the agent’s work is presented in a separate «Kubernetes» table on the cluster page.

In addition to synchronizing resource configurations in Kubernetes, the agent reports telemetry data to Deckhouse Commander:

• The current version of Deckhouse Kubernetes Platform.
• Availability of an update to a new version of Deckhouse Kubernetes Platform.
• Deckhouse Kubernetes Platform update channel.
• Kubernetes version.
• Availability of system components.
• Warnings requiring user attention (alerts, manual confirmation of node reboot, etc.).
• Key cluster metrics: total CPU, memory, disk storage, and total number of nodes.

Creation

Clusters are created based on cluster templates. To create a cluster, the user selects a template, fills in the template input parameters (they are provided by the template), and then clicks the «install» button. This gives the cluster a configuration, and the cluster is assigned to the template, to a specific version of the template. The template version or the template itself can be changed.

As the input parameters are filled in, the cluster configuration is rendered in YAML format. If errors are found in the configuration, the Deckhouse Commander interface will display them. If a new cluster with errors is saved, its installation will not start until the errors are corrected. In other words, the cluster will have the «Configuration error» status, and the installation job will not be created until the configuration is changed to a correct one. Errors in the cluster configuration can be caused by either template code or incorrectly filled in input parameters.

When the configuration becomes valid, a job to install the cluster is created, after which the cluster manager creates the cluster. If the cluster is created on pre-existing machines, Deckhouse Commander configures the Deckhouse Kubernetes Platform components on them, and then creates the specified Kubernetes resources. If the cluster uses the API of a cloud platform or virtualization platform, then before the steps mentioned above, Deckhouse Commander creates the infrastructure. The exact set of cloud resources depends on the cloud provider.

After the cluster is successfully installed, Deckhouse Commander will periodically reconcile its configuration. If the infrastructure configuration diverges from the one declared in Deckhouse Commander, it will create a job to change the infrastructure to bring it to the declared state. Configuration divergence can occur on either the infrastructure side or the Deckhouse Commander side. In the first case, this means a change in the cloud API, for example, if something was manually changed in the cloud resource configuration. In the second case, this means a change in the cluster configuration, which we will discuss in the next section.

Updating

Changing the cluster configuration means that a new configuration has been saved to the cluster, different from the previous one. This can be the result of changing the input parameters of the current cluster template. It can also be the result of switching the cluster to a new version of the template or even to a different template.

When the cluster configuration changes, Deckhouse Commander creates a task to change the cluster infrastructure. The agent brings the Kubernetes configuration to the desired state in parallel with the infrastructure change.

Changes to the cluster configuration can lead to destructive changes in the infrastructure. For example, this can include changes to virtual machines that require their deletion or re-creation. Another example is a change in the composition of cloud availability zones. When Deckhouse Commander detects destructive changes, it does not enforce these changes until the user confirms them.

Deletion

Deleting clusters in Deckhouse Commander can be achieved in two ways. Both methods are available in the cluster on an equal basis.

The first method is to clear the infrastructure of the cluster. In this case, Deckhouse Commander creates a deletion task. Static resources are cleared of Deckhouse Kubernetes Platform components, and cloud resources are deleted (for example, virtual machines). After deletion, the cluster configuration does not disappear; the cluster goes into the archive. Its configuration can be returned to if necessary, and this cluster will no longer be listed among active clusters. This distinguishes the archived cluster from the active one.

The second way to delete a cluster is manual deletion. Deckhouse Commander will move the cluster to the archive but will not clean up the infrastructure. This method can be useful if, for some reason, Deckhouse Commander cannot handle the correct deletion of the cluster using the first method. In this case, the cluster will have the «deletion error» status. The user will need to manually clean up the resources occupied by Deckhouse Kubernetes Platform and move the cluster to the archive manually.

Cluster migration between workspaces

Clusters are created within a workspace. However, it is possible to transfer the created cluster from one workspace to another. During the transfer, the cluster will be detached from its template, and the template will remain in the original workspace. The inventory used in the cluster will be transferred or copied to the new cluster workspace, depending on the mode of using records: exclusively used records will be transferred, and non-exclusively used ones will be copied. At the same time, missing directories with the correct identifier will be created in the new workspace.

Attachment

Deckhouse Commander supports attachment of existing DKP clusters. Unlike the cluster creation process, the attachment procedure requires an already existing cluster.

To join an existing DKP cluster, click the Attach button on the cluster list page, then specify the cluster name and SSH Parameters for connecting to the master node. Example of basic configuration:

apiVersion: dhctl.deckhouse.io/v1
host: MASTER_NODE_ADDRESS
kind: SSHHost
---
apiVersion: dhctl.deckhouse.io/v1
kind: SSHConfig
sshAgentPrivateKeys:
- key: |
    -----BEGIN RSA PRIVATE KEY-----
    .............................
    -----END RSA PRIVATE KEY-----
  passphrase: qwerty123               # Key password, if the key is protected by it.
sshPort: 22
sshUser: ubuntu

Once all the necessary parameters have been specified:

1. Click the Connect button.
2. Deckhouse Commander will verify the configuration’s correctness:
   • If the configuration is correct, it will attempt to connect to the cluster.
3. Upon successful connection:
   • The cluster will be saved with the status Ready to Join.
   • It will become available in the general list of clusters.
4. Navigate to the cluster’s page.
5. Click the Join button.
6. Wait for the joining procedure to complete.
7. Upon successful completion:
   • The cluster will change to the Ready status.

Detachment

Detachment of a cluster is necessary to remove it from the control of Deckhouse Commander. As a result, the cluster’s configuration and Kubernetes resources will no longer be synchronized, and the cluster will become autonomous. Subsequently, such a cluster can be reattached, but information about the template version from which it was deployed will be lost.

To detach a cluster, go to the target cluster’s page, select the Detach option from the operation dropdown menu (3 vertical dots), and confirm your choice. After the detachment procedure is completed, the cluster will be moved to the Archive.

Templates

Deckhouse Commander was created to manage typical clusters. Since all sections of the cluster configuration are presented in YAML format, clustering templating involves marking the required YAML configuration with parameters and describing the schema of these parameters. For YAML templating, the go template syntax and a set of sprig functions are used. To describe the schema of input parameters, a proprietary syntax similar to OpenAPI3 is used, but simpler.

The cluster configuration is created by substituting input parameters into section templates. The input parameters are validated by the schema specified for them. The input parameter schema in the Deckhouse Commander web application can be specified either using text configuration or using a visual form builder. Read about input parameters in the section on working with templates.

Templates have versions. When a template is updated, a new version of the template is created. The previous version of the template remains available so that it can be used in clusters. However, the template author can mark template versions as unavailable for use.

Each cluster in Deckhouse Commander has a configuration that was obtained from a template (unless an existing cluster was imported). The cluster also «remembers» which template and which version of it was used to configure it. Thanks to this binding, a set of input parameters for the cluster is displayed in the cluster in the form of a web form from a given version of a given template.

When a cluster is switched to a new template or a new version of a template, the set of input parameters may change. This may include mandatory parameters that were not initially filled in and do not have default values. Then, when switching from one template to another (or from one version of a template to another version of the same template), it may be necessary to change or supplement the input parameters so that the new configuration is created correctly.

Inside the template interface, there is a list of clusters whose configuration is based on this template at the moment. From this interface, you can translate many clusters to a new (or old) version of the template in a few clicks. This operation will fail if the cluster configuration contains errors. This can happen, among other things, because mandatory input parameters that are not provided in the current version of the template are missing, but are present in the new one.

Creating and maintaining a template can be a painstaking engineering task that requires testing the installation and updating of clusters. Template versions can accumulate during this work. To make it easier to navigate versions, Deckhouse Commander provides the ability to leave a comment for the template version. It is also possible to make template versions unavailable in the cluster interface. This can be useful to protect users from non-working template versions.

Inventory, Catalogs

Catalogs and records

In some cases, in clusters, it is necessary to use the same data repeatedly. For example, for many clusters, you can provide the option to choose a release channel for updating the Deckhouse Kubernetes Platform or IP addresses of available hosts for deploying clusters.

To avoid having to fix such data in templates, use Inventory. Inventory is a collection of catalogs with data. Each catalog defines a data schema, after which the catalog is populated with records. The records are validated against the specified data schema.

When creating a catalog, you can choose how to use the records:

1. A record in the catalog can be used simultaneously in several clusters.
2. A record in the catalog can only be used in one cluster; deleting or detaching a cluster frees up the record for use in other clusters.

The first option is suitable for reusable configuration. The second option is for using pre-prepared infrastructure. This can include dedicated subnets, pre-created load balancers, virtual machines, domain names, IP addresses, and so on. It is convenient to prepare such data in advance and track whether they are being used and, if so, in which clusters.

During catalog creation, the user specifies the name of the catalog, the schema, and the identifier. The identifier cannot be changed, while the catalog name can be changed at any time. The data schema can only be changed if there are no records in the catalog that are used in any cluster.

The data schema for the catalog is defined by the same syntax and visual constructor as the input parameters for the cluster template. An example of a catalog schema:

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

- key: ip
  type: string
  title: IP Address
  format: ipv4
  unique: true
  identifier: true

How to use a catalog in a cluster

In the cluster template, you need to indicate that the field is a selection from the catalog, for this, use its identifier. Example of a parameter:

- key: workerMachines     # parameter name in the template
  title: Workers
  catalog: worker-nodes   # the catalog identifier
  minItems: 1
  maxItems: 10

Even though specific catalog is defined in the template input parameters, when in cluster, the catalog might be switched to any other catalog accessible in the workspace.

Importing data for catalogs

Catalogs can be imported via API or through the interface by uploading a JSON file. If the identifier of an existing catalog is specified in this file, then records during import will be added to it regardless of compliance with the data schema. The data schema will not be overwritten if the catalog already exists. An example of a catalog file with records that can be imported:

{
  "name": "Worker nodes",
  "slug": "worker-nodes",
  "params": [
    {
      "key": "hostname",
      "type": "string",
      "title": "Hostname",
      "unique": true,
      "pattern": "^[a-z0-9.-]+$",
      "identifier": true
    },
    {
      "key": "ip",
      "type": "string",
      "title": "IP address",
      "format": "ipv4",
      "unique": true,
      "identifier": true
    }
  ],
  "resources": [
    { "values": { "ip": "10.128.0.39", "hostname": "worker-1" } },
    { "values": { "ip": "10.128.0.47", "hostname": "worker-2" } },
    { "values": { "ip": "10.128.0.24", "hostname": "worker-3" } },
    { "values": { "ip": "10.128.0.17", "hostname": "worker-4" } },
    { "values": { "ip": "10.128.0.55", "hostname": "worker-5" } },
    { "values": { "ip": "10.128.0.49", "hostname": "worker-6" } }
  ]
}

Projects

When using multitenancy in DKP clusters, this section allows you to work with projects created in clusters managed by Deckhouse Commander. For more information about the functionality, see DKP multitenancy.

By default, the section is off. Turning it on requires administrator setup: Enabling and disabling Deckhouse Commander capabilities.

All project functionality in target clusters is implemented by the built-in DKP multitenancy. Deckhouse Commander acts as a control plane on top of it: it creates and updates Project resources in target clusters, and the agent applies them in the cluster.

Deckhouse Commander distinguishes two kinds of projects:

• Projects of kind commander — created and managed from Deckhouse Commander. Only these projects can be edited and deleted through the web interface.
• Projects of kind deckhouse — DKP projects created directly in the target cluster and not managed by Deckhouse Commander. See Projects of kind deckhouse for details.

Project list

The “Projects” page shows all workspace projects that are visible to the user (see Section and project visibility).

The list has the following columns:

• project name — for deployed projects the name is a link that opens the project web UI in the target cluster;
• status — the current project state (see Project statuses);
• cluster — a link to the target cluster page. The link is active only for users who are allowed to view the Clusters section; other users see the cluster name as plain text;
• description.

Additional indicators or icons may appear next to the name:

• a flag icon — project of kind deckhouse, controlled by Deckhouse;
• a red icon — an error status; hovering over it reveals the error message;
• a gray info icon — additional information about synchronization with the cluster.

Filters above the list let you search by name and filter by cluster, project kind (commander / deckhouse), and status. The “Reset” button clears all filters.

For projects of kind commander the row actions are:

• “Create based on” — opens the project creation form with the parameters of the source project pre-filled (useful to resolve a name collision);
• “Edit” — opens the configuration form;
• “Delete” — deletes the project (confirmation is required).

The available actions depend on the user’s permissions. See Project access management for details.

Project statuses

The list and the project page show a combined status that reflects both the project’s own state and the state of its target cluster:

Creating and editing projects is only allowed in target clusters in an active stage (successfully created or attached). While the cluster is in the attach, detach, or destroy stage, project operations are blocked. Agent connectivity errors and cluster converge errors do not block project operations.

Creating a project

To create a project, follow these steps:

1. On the “Projects” page, click “Create project”.

2. Select a target cluster. Only clusters that are ready to accept projects (in an active stage) are listed. A project is created in a single cluster — the link is one-to-one.

3. Fill in the project parameters:

   • Administrators — users and groups that receive the Admin role in the project. They are selected from the accounts available in Deckhouse Commander (fed from the external IdP via Dex); a user or group name can also be entered manually if the account has not yet appeared in Commander.
   • Resource quotas — optional limit on the project resource requests (resourceQuota.requests): CPU (cores or millicores, for example 1 or 500m), memory (Mi, Gi, etc.), and storage (Mi, Gi, etc.). If no values are specified, no ResourceQuota is created in the cluster. Once at least one quota is set, every container in the project’s pods must explicitly declare resources.requests for the corresponding resources — pods without these values will not be created in the project.

4. Enter the project name. The name must follow the Kubernetes namespace naming rules (lowercase Latin letters, digits, and hyphens). Reserved system names (in particular, default and deckhouse) cannot be used. Uniqueness is checked within the selected cluster.

5. Click “Create”.

After creation, Commander labels the project with internal service labels and hands it off to the agent, which applies a Project resource in the target cluster. The agent.commander.deckhouse.io/prevent-tracking-adoption label protects a DKP project with the same name, if one already exists in the cluster, from being automatically taken over by Commander.

Editing a project

To edit a project, click the “Edit” icon on the list row or open the project page and switch to the “Configuration” tab.

The edit form allows changes to:

• project description;
• the list of administrators;
• resource quotas;
• project name.

Switching the project template is not supported in the current release and will be added in the later stages of this feature.

Editing is only available for projects of kind commander. For projects of kind deckhouse the edit form is not exposed: in a later release it will be possible to adopt a project created in DKP into Deckhouse Commander and manage it from Commander thereafter.

Viewing a project and the web UI

Clicking the name of a deployed project (in the “Deployed” status) in the list opens the project web UI in the target cluster. For projects that have not yet been applied in the cluster, the name is shown as plain text.

The project page provides two tabs:

• Configuration — the current project parameters (template, administrators, resource quotas) and, if any, project application error messages.
• Accesses — managing project membership (see “Accesses” tab). Available only to project administrators and system administrators. Only a system administrator can assign or revoke the project administrator role — through the “Administrators” field on the “Configuration” tab.

Deleting a project

To delete a project, click the “Delete” icon on the list row and confirm the action. Commander removes its internal labels from the project and asks the agent to delete the Project resource in the target cluster.

Deletion is only available for projects of kind commander. Projects of kind deckhouse are deleted directly in Deckhouse using the multitenancy-manager module.

Name collisions

A project name must be unique within its target cluster. A name collision may happen in two cases:

• when creating a project in Commander, another project (of kind commander or deckhouse) with the same name already exists in the selected cluster — the form returns a validation error and the project is not saved;
• a project with the same name appears in the target cluster after the Commander project was created (for example, it is created directly in DKP) — the agent cannot apply the project and, in Commander, the project switches to the Creation error status with the corresponding error message.

To resolve a name collision:

1. Use the “Create based on” action — it opens the project creation form with the parameters of the conflicting project pre-filled; enter a new name and save the project, then delete the original one.
2. Or delete the conflicting DKP project in the target cluster and wait for the next agent synchronization cycle.

The agent.commander.deckhouse.io/prevent-tracking-adoption label ensures that the agent does not silently adopt a DKP project with the same name under Commander’s management — the collision is reported explicitly.

Section and project visibility

The “Projects” section is shown to a user when both conditions are met:

• the projects feature is enabled in Deckhouse Commander;
• the user is granted a global role that allows at least the get verb on the projects resource.

The set of projects visible in the list is determined by the user’s permissions on the projects resource:

• with get only (including via the autogenerated-projects-user role), the user sees only projects where they are a member; projects of kind deckhouse are hidden;
• with update and/or delete (including *), the user sees all projects of the workspace, including projects of kind deckhouse.

The autogenerated-projects-user role is granted automatically to every project member, so the section appears as soon as the user is added to any project in the workspace. To create, update, or delete projects, use the preset projects-admin role or a custom global role with the required verbs. For details on the access model, see Project access management.

Project-level roles

Every project member gets one of four roles. The roles are cumulative: a higher role includes everything the lower roles can do and adds more. Permissions inside the target cluster are applied by the multitenancy-manager module via the AuthorizationRule manifest.

“Accesses” tab

The “Accesses” tab on the project page is available to:

• a system administrator with permissions on projectrolebindings in this project;
• a project administrator — a user assigned to the Admin role of the current project.

Users in the Editor, PrivilegedUser, or User role do not see the “Accesses” tab.

The tab shows the table of project members with their roles. Rows with the Admin role are marked with a lock icon and are changed only on the “Configuration” tab (the “Administrators” field) by the system administrator.

To add a member, follow these steps:

1. Click “Add member”.
2. Select a role: User, PrivilegedUser, or Editor.
3. Select one or more users or groups.
4. Click “Save”.

Users and groups on the “Accesses” tab are chosen from the accounts available in Deckhouse Commander (they come from the external IdP via Dex and are not created in Commander).

Projects of kind deckhouse

Projects of kind deckhouse are DKP projects created directly in the target cluster and are not managed by Deckhouse Commander. In the project list they are marked with a flag icon and a tooltip stating that the object is controlled by Deckhouse.

For such projects, the Deckhouse Commander web interface does not provide an edit form, a delete action, or an “Accesses” tab — these projects are managed directly in Deckhouse using the multitenancy-manager module and the AuthorizationRule manifest (see also DKP multitenancy).

Integration API and Tokens

The Deckhouse Commander API provides a limited set of actions:

1. Create, change, and delete clusters
2. Create, change and delete resources in catalogs
3. Read templates
4. Read resource catalogs
5. Create, change, and delete projects

To access the API in Deckhouse Commander, you can issue a token. The token can have either rights to all possible operations in the API or only read rights.

Details of the API implementation are described in the Integration API section.

Parameters

Default Cluster Settings

This section configures the reconciliation interval and change application mode values used when creating new clusters in the current Workspace. When these values are changed, you have the option to apply them to all existing clusters in the Workspace by using the checkbox “Override for all clusters in this Workspace” or use them as defaults for new clusters only.

Tokens

This section is intended for creating access tokens for Integration API.

Audit

For all entities, Deckhouse Commander keeps a history of changes. Clusters, templates, resources, catalogs, API access tokens - for all of them, a history of actions and changes is recorded, which can be used to track who, when and what actions were performed in Deckhouse Commander.

Currently, this functionality only relates to work related to the Deckhouse Commander API. In the future, an audit log from application clusters will be available in Deckhouse Commander.