Installation

System requirements

To start using Deckhouse Commander, you need a cluster based on Deckhouse Kubernetes Platform. If you don’t have a cluster yet, refer to the installation instructions.

Deckhouse Commander is a module of Deckhouse Kubernetes Platform, so it does not need a dedicated cluster. You can enable it in any DKP cluster — either one dedicated to Commander (typically alongside other Deckhouse system modules), or one that also runs application workloads. In the latter case Commander runs by default on dedicated or system nodes, so it does not compete for resources with user workloads. See Component placement and networking for details.

We recommend creating a fault-tolerant management cluster that will include the following node sets (NodeGroup):

• PostgreSQL in HighAvailability mode in two replicas requires 1 core and 1 GB of memory on 2 separate nodes.
• The API server in HighAvailability mode for two replicas needs 1 core and 1GB of memory on two separate nodes.
• Service components used for rendering configurations and connecting to application clusters require 0.5 cores and 128 MB of memory per cluster.
• Cluster manager and dhctl server together require resources based on the number of clusters they serve and the number of DKP versions they serve simultaneously.
• Up to 2 cores per node can be occupied by DKP service components (for example: runtime-audit-engine, istio, cilium, log-shipper).

Prepare DBMS

Deckhouse Commander works with the PostgreSQL database management system. PostgreSQL extensions plpgsql and pgcrypto are required for Deckhouse Commander to function properly. PostgreSQL versions 12, 13, 14, 15, 16, and 17 are supported.

Option 1: External DBMS

This is the recommended way to use Deckhouse Commander in production environments. To use Deckhouse Commander, you need to prepare the connection parameters to the database.

Option 2: operator-postgres module

This is not a recommended method for use in production environments. However, the use of operator-postgres is convenient for quick start with Deckhouse Commander or for environments where there are no high availability and support requirements.

It is important to enable Deckhouse Commander after CRDs from the operator-postgres module have appeared in the cluster.

The operator-postgres module uses the PostgreSQL operator. You can use your own postgres-operator installation version v1.10.0 or later.

Step 1: Enabling operator-postgres

First, you need to enable the postgres operator module and wait for it to be enabled.

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: operator-postgres
spec:
  enabled: true

Step 2: Complete the installation

To make sure that the module is enabled, wait for the Deckhouse task queue to become empty:

d8 system queue main

Check for the necessary CRDs in the cluster:

d8 k get crd | grep postgresqls.acid.zalan.do

Enabling Deckhouse Commander

If you are using your own PostgreSQL database installation

To enable Deckhouse Commander, create a ModuleConfig:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: commander
spec:
  enabled: true
  version: 1
  settings:
    postgres:
      mode: External
      external:
        host: "..."     # Mandatory field
        port: "..."     # Mandatory field
        user: "..."     # Mandatory field
        password: "..." # Mandatory field
        db: "..."       # Mandatory field

Alternatively, you can store database credentials in a secret and reference it with postgres.external.credentials.secretName instead of user and password.

Specify the secret name in the module configuration:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: commander
spec:
  enabled: true
  version: 1
  settings:
    postgres:
      mode: External
      external:
        host: "..."   # Mandatory field
        port: "..."   # Mandatory field
        db: "..."     # Mandatory field
        credentials:
          secretName: postgres-secret # Mandatory field

Then create the secret in the d8-commander namespace:

d8 k -n d8-commander create secret generic postgres-secret \
  --from-literal=username=postgres \
  --from-literal=password=postgres

Wait until the pods in the d8-commander namespace are running and ready.

If certificate authentication is used instead of a password on the PostgreSQL server, set the ssl.secretName parameter value to the name of the secret in the d8-commander namespace which contains the client certificate.

Example of creating a secret: d8 k -n d8-commander create secret generic postgres-ssl --from-file=tls.crt=client.crt --from-file=tls.key=client.key --from-file=ca.crt=ca.crt

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: commander
spec:
  enabled: true
  version: 1
  settings:
    postgres:
      mode: External
      external:
        host: "..." # Mandatory field
        port: "..." # Mandatory field
        user: "..." # Mandatory field
        db: "..."   # Mandatory field
        ssl:
          secretName: "postgres-ssl" # Mandatory field

If you are using the operator-postgres module

It is enough to enable the commander module in the Internal database connection mode. Deckhouse Commander will independently configure the database in the PostgreSQL operator.

Please note that the default storage class (StorageClass) will be used for the database. For Deckhouse Commander the storage class can be set explicitly:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: commander
spec:
  enabled: true
  version: 1
  settings:
    postgres:
      mode: Internal
      internal:
        storageClass: my-storage-class  # optional setting

Initial access setup

After installation, when no administrator permissions have been assigned yet, Deckhouse Commander redirects the first authenticated user to the initial access setup page (/bootstrap). There you enter the initial setup token — a one-time, time-limited value generated at deployment and stored in the bootstrap-token secret in the d8-commander namespace.

To read the token value, run:

$ d8 k -n d8-commander get secret bootstrap-token -o jsonpath='{.data.token}' | base64 -d

Enter the value on the initial access setup page and click “Get access” — administrator rights are granted immediately, and the token is invalidated after use.

For a detailed description of the process, the token behavior, and the lost administrator access recovery scenario, see Initial Access Setup.