This page is under active development and may contain incomplete information. It provides an overview of the steps required to install Deckhouse. Please refer to the Getting Started guide section for detailed step-by-step instructions.

The Deckhouse installer is available as a container image. It is based on the dhctl tool which is responsible for:

  • Creating and configuring objects in the cloud infrastructure using Terraform;
  • Installing the required OS packages on the nodes (including Kubernetes packages);
  • Installing Deckhouse;
  • Creating and configuring Kubernetes cluster nodes;
  • Keeping the cluster in (or bringing it to) the state described in the configuration.

Deckhouse installation options:

  • Supported cloud: In this case, dhctl creates and configures all the required resources (including virtual machines), deploys the Kubernetes cluster and installs Deckhouse. For information on supported cloud providers, see the Kubernetes Cluster section.
  • Bare metal cluster or unsupported cloud: In this case, dhctl configures the server (virtual machine), deploys a Kubernetes cluster with a single master node and installs Deckhouse. You can then manually add more nodes to the cluster using the pre-made configuration scripts.
  • Existing Kubernetes cluster: In this case, dhctl installs Deckhouse to the existing cluster.

Preparing the infrastructure

Before installing, ensure that:

  • (for bare metal clusters and clusters in unsupported clouds) the server’s OS is in the list of supported OS (or compatible with them) and SSH access to the server with key-based authentication is configured;
  • (for supported clouds) you have the quotas needed to create resources as well as cloud access credentials (the exact set depends on the specific cloud infrastructure or cloud provider);
  • you have access to the container registry with Deckhouse images (default is

Preparing the configuration

To install Deckhouse, you have to create a YAML file containing the installation configuration and, if necessary, a YAML config for the resources that must be created after a successful Deckhouse installation.

Installation config

The YAML installation config contains multiple resource configurations (manifests):

  • InitConfiguration — the initial Deckhouse configuration. Deckhouse will use it to start after the installation.

    This resource contains the parameters Deckhouse needs to start or run smoothly, such as the placement-related parameters for Deckhouse components, the storageClass used, the container registry credentials, the DNS naming template, and more.

  • ClusterConfiguration — general cluster parameters, such as network parameters, CRI parameters, control plane version, etc.

    The ClusterConfiguration resource is only required if a Kubernetes cluster has to be pre-deployed when installing Deckhouse. That is, ClusterConfiguration is not required if Deckhouse is installed into an existing Kubernetes cluster.

  • StaticClusterConfiguration — parameters of a Kubernetes cluster deployed to bare metal servers or virtual machines in an unsupported clouds.

    As with the ClusterConfiguration resource, the StaticClusterConfiguration resource is not required if Deckhouse is installed into an existing Kubernetes cluster.

  • <CLOUD_PROVIDER>ClusterConfiguration — a set of resources with the configuration parameters for the supported cloud providers.

    These resources contain parameters required to access the cloud infrastructure (authentication credentials), resource layout type and configuration, network settings, parameters of node groups to be created, etc.

    Below is the list of configuration resources for supported cloud providers:

An example of the installation config…

kind: ClusterConfiguration
clusterType: Cloud
  provider: Azure
  prefix: cloud-demo
kubernetesVersion: "Automatic"
clusterDomain: cluster.local
kind: InitConfiguration
  releaseChannel: Stable
        publicDomainTemplate: ""
kind: AzureClusterConfiguration
layout: Standard
sshPublicKey: <SSH_PUBLIC_KEY>
  replicas: 3
    machineSize: Standard_D4ds_v4
    urn: Canonical:UbuntuServer:18.04-LTS:18.04.202010140
    enableExternalIP: true
  subscriptionId: <SUBSCRIPTION_ID>
  clientId: <CLIENT_ID>
  clientSecret: <CLIENT_SECRET>
  tenantId: <TENANT_ID>
  location: westeurope

Installation resource config

The optional YAML installation resource config contains the Kubernetes resource manifests that will be applied after a successful Deckhouse installation.

This file can help you with the additional cluster configuration once Deckhouse is installed: deploying the Ingress controller, creating additional node groups and configuration resources, assigning permissions and managing users, etc.

An example of the resource config…

kind: IngressNginxController
  name: main
  ingressClass: "nginx"
  controllerVersion: "1.1"
  inlet: "LoadBalancer"
  nodeSelector: worker
kind: AzureInstanceClass
  name: worker
  machineSize: Standard_F4
kind: NodeGroup
  name: worker
      kind: AzureInstanceClass
      name: worker
    maxPerZone: 3
    minPerZone: 1
    zones: ["1"]
  nodeType: CloudEphemeral
kind: ClusterAuthorizationRule
  name: admin
  - kind: User
  accessLevel: SuperAdmin
  portForwarding: true
kind: User
  name: admin
  password: '$2a$10$isZrV6uzS6F7eGfaNB1EteLTWky7qxJZfbogRs1egWEPuT1XaOGg2'

Post-bootstrap script

After successfully installing Deckhouse, the installer provides an option to run the script on one of the master nodes. This script can be used for additional customization, collecting configuration information, etc.

To take advantage of this feature, create the script and specify the path to it using the --post-bootstrap-script-path flag when when you start the installation (see below).

Example: a script that retrieves the IP address of the load balancer…

This sample script retrieves the IP address of the load balancer after the cluster is deployed in the cloud and Deckhouse is installed:

#!/usr/bin/env bash

set -e
set -o pipefail


echo_err() { echo "$@" 1>&2; }

# declare the variable

# get the load balancer IP
for i in {0..100}
  if lb_ip="$(kubectl -n d8-ingress-nginx get svc "${INGRESS_NAME}-load-balancer" -o jsonpath='{.status.loadBalancer.ingress[0].ip}')"; then
    if [ -n "$lb_ip" ]; then


  sleep 5

if [ -n "$lb_ip" ]; then
  echo_err "The load balancer external IP: $lb_ip"
  echo_err "Could not get the external IP of the load balancer"
  exit 1


if [ -z "$OUTPUT" ]; then
  echo_err "The OUTPUT env is empty. The result was not saved to the output file."
  echo "$outContent" > "$OUTPUT"

Installing Deckhouse

When you install Deckhouse Enterprise Edition from the official container registry, you must first log in with your license key:

docker login -u license-token

The command to pull the installer container from the Deckhouse public registry and run it looks as follows:

docker run --pull=always -it [<MOUNT_OPTIONS>]<DECKHOUSE_REVISION>/install:<RELEASE_CHANNEL> bash

, where:

  • <DECKHOUSE_REVISION> — edition of Deckhouse: ee for Enterprise Edition and ce for Community Edition;
  • <MOUNT_OPTIONS> — options for mounting files in the installer container, such as:
    • SSH authentication keys;
    • config file;
    • resource file, etc.

Here is an example of a command to run the installer container for Deckhouse CE:

docker run -it --pull=always \
  -v "$PWD/config.yaml:/config.yaml" \
  -v "$PWD/resources.yml:/resources.yml" \
  -v "$PWD/dhctl-tmp:/tmp/dhctl" \
  -v "$HOME/.ssh/:/tmp/.ssh/" bash

The installation of Deckhouse in the installer container can be started using the dhctl command:

  • Use the dhctl bootstrap command, to start a Deckhouse installation including cluster deployment (these are all cases, except for installation Deckhouse in an existing cluster);
  • Use the dhctl bootstrap-phase install-deckhouse command, to start a Deckhouse installation in an existing cluster;

Run dhctl bootstrap -h to learn more about the parameters available.

This command will start the Deckhouse installation in a cloud:

dhctl bootstrap \
  --ssh-user=<SSH_USER> --ssh-agent-private-keys=/tmp/.ssh/id_rsa \
  --config=/config.yml --resources=/resources.yml

, where:

  • /config.yml — installation config;
  • /resources.yml — file with the resource manifests;
  • <SSH_USER> — SSH user on the server;
  • --ssh-agent-private-keys — file with the private SSH key for connecting via SSH.

Aborting the installation and uninstalling Deckhouse

When installing in a supported cloud, the resources created may remain in the cloud if the installation is interrupted or there are problems during the installation. Use the dhctl bootstrap-phase abort command to delete those resources. Note that the configuration file passed via the --config flag must be the same as the one used for the installation.

To delete a cluster running in a supported cloud and deployed after the Deckhouse installation, use the dhctl destroy command. In this case, dhctl will connect to the master node, retrieve the terraform state, and delete the resources created in the cloud in the correct fashion.