Installation

The Deckhouse installer is available as a container image and is based on the dhctl utility, which is responsible for:

• Creating and configuring cloud infrastructure objects using Terraform;
• Installing necessary OS packages on nodes (including Kubernetes packages);
• Installing Deckhouse;
• Creating and configuring nodes for the Kubernetes cluster;
• Maintaining the cluster state according to the defined configuration.

Deckhouse installation options:

• In a supported cloud. The dhctl utility automatically creates and configures all necessary resources, including virtual machines, deploys the Kubernetes cluster, and installs Deckhouse. A full list of supported cloud providers is available in the Kubernetes Cluster section.

• On bare-metal servers or in unsupported clouds. In this option, dhctl configures the server or virtual machine, deploys the Kubernetes cluster with a single master node, and installs Deckhouse. Additional nodes can be added to the cluster using pre-existing setup scripts.

• In an existing Kubernetes cluster. If a Kubernetes cluster is already deployed, dhctl installs Deckhouse and integrates it with the existing infrastructure.

Preparing the Infrastructure

Before installation, ensure the following:

• For bare-metal clusters and unsupported clouds: The server is running an operating system from the supported OS list or a compatible version, and it is accessible via SSH using a key.

• For supported clouds: Ensure that necessary quotas are available for resource creation and that access credentials to the cloud infrastructure are prepared (these depend on the specific provider).

• For all installation options: Access to the container registry with Deckhouse images (registry.deckhouse.io or registry.deckhouse.ru) is configured.

Preparing the Configuration

Before starting the Deckhouse installation, you need to prepare the configuration files:

1. Installation configuration YAML file. This file contains the main parameters for setting up Deckhouse, including information about cluster components, network settings, and integrations.

2. Additional resources YAML file. This file is used to automatically create necessary resources after the successful installation of Deckhouse, such as custom modules, cluster node settings, or specific policies.

Make sure that the configuration files meet the requirements of your infrastructure and include all the necessary parameters for a correct deployment.

Installation config

The installation configuration YAML file contains parameters for several resources (manifests):

1. InitConfiguration — initial parameters for Deckhouse configuration, necessary for the proper startup of Deckhouse after installation.

   Key settings specified in this resource:

   • Component placement parameters;
   • The StorageClass (storage parameters);
   • Access parameters for the container registry;
   • Template for DNS names;
   • Other essential parameters required for Deckhouse to function correctly.
2. ClusterConfiguration — general cluster parameters, such as control plane version, network settings, CRI parameters, etc.

   This resource is needed only when Deckhouse is being installed with a pre-deployed Kubernetes cluster. If Deckhouse is being installed in an already existing cluster, this resource is not required.

3. StaticClusterConfiguration — parameters for Kubernetes clusters deployed on bare-metal servers or virtual machines in unsupported clouds.

   This resource is needed only when Deckhouse is being installed with a pre-deployed Kubernetes cluster. If Deckhouse is being installed in an already existing cluster, this resource is not required.

4. <CLOUD_PROVIDER>ClusterConfiguration — a set of resources containing configuration parameters for supported cloud providers. These include:
   • Cloud infrastructure access settings (authentication parameters);
   • Resource placement scheme type and parameters;
   • Network settings;
   • Node group creation settings.

   List of cloud provider configuration resources:

   • AWSClusterConfiguration — Amazon Web Services;
   • AzureClusterConfiguration — Microsoft Azure;
   • GCPClusterConfiguration — Google Cloud Platform;
   • OpenStackClusterConfiguration — OpenStack;
   • VsphereClusterConfiguration — VMware vSphere;
   • VCDClusterConfiguration — VMware Cloud Director;
   • YandexClusterConfiguration — Yandex Cloud;
   • ZvirtClusterConfiguration — zVirt.

5. ModuleConfig — a set of resources containing configuration parameters for Deckhouse built-in modules.

   If the cluster is initially created with nodes dedicated to specific types of workloads (e.g., system nodes or monitoring nodes), it is recommended to explicitly set the nodeSelector parameter in the configuration of modules that use persistent storage volumes.

   For example, for the prometheus module, the configuration is specified in the nodeSelector parameter.

apiVersion: deckhouse.io/v1
kind: ClusterConfiguration
clusterType: Cloud
cloud:
  provider: Azure
  prefix: cloud-demo
podSubnetCIDR: 10.111.0.0/16
serviceSubnetCIDR: 10.222.0.0/16
kubernetesVersion: "Automatic"
clusterDomain: cluster.local
---
apiVersion: deckhouse.io/v1
kind: AzureClusterConfiguration
layout: Standard
sshPublicKey: <SSH_PUBLIC_KEY>
vNetCIDR: 10.241.0.0/16
subnetCIDR: 10.241.0.0/24
masterNodeGroup:
  replicas: 3
  instanceClass:
    machineSize: Standard_D4ds_v4
    urn: Canonical:UbuntuServer:18.04-LTS:18.04.202010140
    enableExternalIP: true
provider:
  subscriptionId: <SUBSCRIPTION_ID>
  clientId: <CLIENT_ID>
  clientSecret: <CLIENT_SECRET>
  tenantId: <TENANT_ID>
  location: westeurope
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: cni-flannel
spec:
  enabled: true
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse
spec:
  enabled: true
  settings:
    releaseChannel: Stable
    bundle: Default
    logLevel: Info
  version: 1
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: global
spec:
  enabled: true
  settings:
    modules:
      publicDomainTemplate: "%s.k8s.example.com"
  version: 1
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: node-manager
spec:
  version: 1
  enabled: true
  settings:
    allowedBundles: ["ubuntu-lts"]
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: prometheus
spec:
  version: 2
  enabled: true
  # Specify, in case of using dedicated nodes for monitoring.
  # settings:
  #   nodeSelector:
  #     node.deckhouse.io/group: monitoring

Additional resource config

The additional resources YAML file contains Kubernetes resource manifests that the installer applies immediately after the successful installation of Deckhouse.

This file is useful for performing additional cluster configurations, such as:

• Deploying the Ingress controller;
• Creating additional node groups;
• Adding configuration resources;
• Setting up roles and users.

apiVersion: deckhouse.io/v1
kind: IngressNginxController
metadata:
  name: main
spec:
  ingressClass: "nginx"
  controllerVersion: "1.1"
  inlet: "LoadBalancer"
  nodeSelector:
    node.deckhouse.io/group: worker
---
apiVersion: deckhouse.io/v1
kind: AzureInstanceClass
metadata:
  name: worker
spec:
  machineSize: Standard_F4
---
apiVersion: deckhouse.io/v1
kind: NodeGroup
metadata:
  name: worker
spec:
  cloudInstances:
    classReference:
      kind: AzureInstanceClass
      name: worker
    maxPerZone: 3
    minPerZone: 1
    zones: ["1"]
  nodeType: CloudEphemeral
---
apiVersion: deckhouse.io/v1
kind: ClusterAuthorizationRule
metadata:
  name: admin
spec:
  subjects:
  - kind: User
    name: admin@deckhouse.io
  accessLevel: SuperAdmin
  portForwarding: true
---
apiVersion: deckhouse.io/v1
kind: User
metadata:
  name: admin
spec:
  email: admin@deckhouse.io
  password: '$2a$10$isZrV6uzS6F7eGfaNB1EteLTWky7qxJZfbogRs1egWEPuT1XaOGg2'
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse-admin
spec:
  enabled: true

Post-bootstrap script

After Deckhouse installation is complete, the installer offers the option to run a custom script on one of the master nodes. This script can be used for:

• Performing additional cluster configurations;
• Collecting diagnostic information;
• Integrating with external systems or other tasks.

The path to the post-bootstrap script can be specified using the --post-bootstrap-script-path parameter during the installation process.

#!/usr/bin/env bash

set -e
set -o pipefail


INGRESS_NAME="nginx"


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

# declare the variable
lb_ip=""

# get the load balancer IP
for i in {0..100}
do
  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
      break
    fi
  fi

  lb_ip=""

  sleep 5
done

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

outContent="{\"frontend_ips\":[\"$lb_ip\"]}"

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

Installing Deckhouse

docker login -u license-token registry.deckhouse.io

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>] registry.deckhouse.io/deckhouse/<DECKHOUSE_REVISION>/install:<RELEASE_CHANNEL> bash

Where:

1. <DECKHOUSE_REVISION> — the Deckhouse edition, such as ee for Enterprise Edition, ce for Community Edition, etc.
2. <MOUNT_OPTIONS> — parameters for mounting files into the installer container, such as:
   • SSH access keys;
   • Configuration file;
   • Resource file, etc.
3. <RELEASE_CHANNEL> — the update channel in kebab-case format, which must match the one specified in config.yml:
   • alpha — for the Alpha update channel;
   • beta — for the Beta update channel;
   • early-access — for the Early Access update channel;
   • stable — for the Stable update channel;
   • rock-solid — for the Rock Solid update channel.

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/" registry.deckhouse.io/deckhouse/ce/install:stable bash

Deckhouse installation is performed within the installer container using the dhctl utility:

• To start the installation of Deckhouse with the deployment of a new cluster (for all cases except installing into an existing cluster), use the command dhctl bootstrap.
• To install Deckhouse into an already existing cluster, use the command dhctl bootstrap-phase install-deckhouse.

Example of running the Deckhouse installation with cloud cluster deployment:

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

Where:

• /config.yml — the installation configuration file;
• /resources.yml — the resource manifests file;
• <SSH_USER> — the username for SSH connection to the server;
• --ssh-agent-private-keys — the private SSH key file for SSH connection.

Pre-Installation Checks

List of checks performed by the installer before starting Deckhouse installation:

1. General checks:
   • The values of the parameters PublicDomainTemplate and clusterDomain do not match.
   • The authentication data for the container image registry specified in the installation configuration is correct.
   • The host name meets the following requirements:
     • The length does not exceed 63 characters;
     • It consists only of lowercase letters;
     • It does not contain special characters (hyphens - and periods . are allowed, but they cannot be at the beginning or end of the name).
   • The server (VM) does not have a CRI (containerd) installed.
   • The host name must be unique within the cluster.
2. Checks for static and hybrid cluster installation:
   • Only one --ssh-host parameter is specified. For static cluster configuration, only one IP address can be provided for configuring the first master node.
   • SSH connection is possible using the specified authentication data.
   • SSH tunneling to the master node server (or VM) is possible.
   • The server (VM) meets the minimum requirements for setting up the master node.
   • Python and required libraries are installed on the master node server (VM).
   • The container image registry is accessible through a proxy (if proxy settings are specified in the installation configuration).
   • Required installation ports are free on the master node server (VM) and the installer host.
   • DNS must resolve localhost to IP address 127.0.0.1.
   • The user has sudo privileges on the server (VM).
3. Checks for cloud cluster installation:
   • The configuration of the virtual machine for the master node meets the minimum requirements.

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

Aborting the installation

If the installation was interrupted or issues occurred during the installation process in a supported cloud, there might be leftover resources created during the installation. To remove them, use the dhctl bootstrap-phase abort command within the installer container.