Installation

This page provides an overview of installing Deckhouse Platform.

Installation methods

You can install Deckhouse Platform using a CLI installer, which is available as a container image and based on the dhctl utility.

Installation options

You can install Deckhouse Platform in the following ways::

• In a supported cloud. The installer automatically creates and configures all required resources (including virtual machines, network objects, etc.), deploys a Kubernetes cluster, and installs Deckhouse Platform. A full list of supported cloud providers is available in the Integration with IaaS section.

• On bare-metal servers (including hybrid clusters) or in unsupported clouds. The installer configures the servers or virtual machines specified in the configuration, deploys a Kubernetes cluster, and installs Deckhouse Platform. Step-by-step instructions for bare metal are available in Getting started → Deckhouse Platform for bare metal.

• In an existing Kubernetes cluster. The installer deploys Deckhouse Platform and integrates it with the current infrastructure. Step-by-step instructions for an existing cluster are available in Getting started → Deckhouse Platform in existing cluster.

Installation requirements

Before starting the installation, review the Deckhouse Platform deployment scenarios and installation requirements in the “System Requirements” section.

Preparing the Configuration

Before installation, you need to prepare the installation configuration file and, if needed, a post-bootstrap script.

Installation configuration file

The installation configuration file is a set of YAML documents that contains Deckhouse Platform settings and manifests for cluster objects and resources to be created after installation. The configuration file is used by the CLI installer and is passed via the --config parameter (see below).

Required and optional objects/resources that may be needed in the installation configuration file:

1. InitConfiguration (required): Initial configuration parameters necessary to start Deckhouse Platform.

   Starting with Deckhouse Platform 1.75, use the ModuleConfig deckhouse to configure access to the Deckhouse Platform container registry. Configuring access with InitConfiguration (via imagesRepo, registryDockerCfg, registryScheme, and registryCA parameters) is considered a legacy method.

2. ClusterConfiguration: General cluster parameters, such as Kubernetes (control plane components) version, network settings, CRI parameters, etc. Required, except when Deckhouse Platform is installed into an already existing Kubernetes cluster.

3. StaticClusterConfiguration: Parameters for a cluster deployed on bare-metal servers (including hybrid clusters) or in unsupported clouds. Required, except when Deckhouse Platform is installed into an already existing Kubernetes cluster.

   To add worker node groups (the NodeGroup object), you may also need StaticInstance and SSHCredentials.

4. <PROVIDER>ClusterConfiguration: Parameters for integration with a cloud provider. Required when integrating Deckhouse Platform with a supported cloud infrastructure.

   The DVPClusterConfiguration, YandexClusterConfiguration, and ZvirtClusterConfiguration resources are deprecated. The parameters for integration with built-in virtualization, Yandex Cloud, and zVirt are set in the ModuleConfig of the cloud-provider-dvp, cloud-provider-yandex, and cloud-provider-zvirt modules and in the related resources. These resources are described in Layouts and configuration in built-in virtualization, Layouts and configuration in Yandex Cloud, and Layouts and configuration in zVirt.

   Examples of resources configuring integration with a cloud provider:

   • AWSClusterConfiguration: Amazon Web Services
   • AzureClusterConfiguration: Microsoft Azure
   • ModuleConfig cloud-provider-dvp: Deckhouse Virtualization Platform (together with the d8-credentials Secret and DVPInstanceClass / NodeGroup resources)
   • GCPClusterConfiguration: Google Cloud Platform
   • HuaweiCloudClusterConfiguration: Huawei Cloud
   • OpenStackClusterConfiguration: OpenStack, OVHcloud, Selectel, VK Cloud
   • VsphereClusterConfiguration: VMware vSphere
   • VCDClusterConfiguration: VMware Cloud Director
   • ModuleConfig cloud-provider-yandex: Yandex Cloud (together with the d8-credentials Secret and YandexInstanceClass / NodeGroup resources)
   • ModuleConfig cloud-provider-zvirt: zVirt (together with the d8-credentials Secret and ZvirtInstanceClass / NodeGroup resources)

   To add cloud nodes, you also need <PROVIDER>InstanceClass objects (for example YandexInstanceClass for Yandex Cloud) that describe VM configuration in the node group (the NodeGroup object).

5. Deckhouse Platform module configurations.

   Each module is configured (and can be enabled or disabled) with its own ModuleConfig (for example, ModuleConfig user-authn for the user-authn module). Parameters that are allowed in the ModuleConfig object are described in the respective module documentation under “Configuration” (for example, configuration of the user-authn module).

   A list of all Deckhouse Platform modules is available in the Modules section.

   Some modules may be enabled and preconfigured automatically depending on the selected installation option and cluster configuration (for example, modules that provide control plane and networking functionality).

   Modules often configured during installation:

   • global: Global Deckhouse Platform settings for parameters used by default by all modules and components (DNS name template, StorageClass, module component placement settings, etc.).
   • deckhouse: Container registry access settings, the desired release channel, and other parameters.
   • user-authn: Unified authentication.
   • cni-cilium: Cluster networking (for example, used when installing Deckhouse Platform on bare metal or in an air-gapped environment);
   • virtualization: Running virtual machines in the cluster, enabled during the installation or later.

   If the cluster is created with nodes dedicated to specific workload types (for example, system or monitoring nodes), it is recommended to explicitly set the nodeSelector parameter in module configurations that use persistent storage volumes (for example, in the nodeSelector parameter of the prometheus ModuleConfig for the prometheus module).

6. IngressNginxController: Parameters of the HTTP/HTTPS load balancer (Ingress controller).

7. NodeGroup: Node group parameters. Required to add worker nodes.

8. Objects for authentication and authorization such as ClusterAuthorizationRule, AuthorizationRule, User, Group, and DexProvider.

   See authentication and authorization documentation for details.

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: deckhouse
spec:
  enabled: true
  settings:
    releaseChannel: Stable
    bundle: Default
    logLevel: Info
    registry:
      mode: Unmanaged
      unmanaged:
        imagesRepo: test-registry.io/some/path
        scheme: HTTPS
        username: <username>
        password: <password>
        ca: <CA>
  version: 1
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: global
spec:
  settings:
    modules:
      publicDomainTemplate: "%s.k8s.example.com"
  version: 2
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 2
  enabled: true
  settings:
    controlPlaneConfigurator:
      dexCAMode: DoNotNeed
    publishAPI:
      enabled: true
      https:
        mode: Global
        global:
          kubeconfigGeneratorMasterCA: ""
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: node-manager
spec:
  version: 1
  enabled: true
  settings: {}
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: prometheus
spec:
  version: 2
  enabled: true
  # Specify if you plan to use dedicated nodes for monitoring.
  # settings:
  #   nodeSelector:
  #     node.deckhouse.io/group: monitoring
---
apiVersion: deckhouse.io/v1
kind: IngressNginxController
metadata:
  name: main
spec:
  ingressClass: "nginx"
  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/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: InitConfiguration
deckhouse:
  imagesRepo: registry.deckhouse.io/deckhouse/ee
  registryDockerCfg: eyJhdXRocyI6IHsgInJlZ2zzzmRlY2tob3Vxxcxxxc5ydSI6IsssfX0K
---
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: deckhouse
spec:
  enabled: true
  settings:
    releaseChannel: Stable
    bundle: Default
    logLevel: Info
  version: 1
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: global
spec:
  settings:
    modules:
      publicDomainTemplate: "%s.k8s.example.com"
  version: 2
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: user-authn
spec:
  version: 2
  enabled: true
  settings:
    controlPlaneConfigurator:
      dexCAMode: DoNotNeed
    publishAPI:
      enabled: true
      https:
        mode: Global
        global:
          kubeconfigGeneratorMasterCA: ""
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: node-manager
spec:
  version: 1
  enabled: true
  settings: {}
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: prometheus
spec:
  version: 2
  enabled: true
  # Specify if you plan to use dedicated nodes for monitoring.
  # settings:
  #   nodeSelector:
  #     node.deckhouse.io/group: monitoring
---
apiVersion: deckhouse.io/v1
kind: IngressNginxController
metadata:
  name: main
spec:
  ingressClass: "nginx"
  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'

Post-bootstrap script

The installer allows you to run a custom script on one of the master nodes after installation (post-bootstrap script). This script can be used for:

• Additional cluster configuration
• 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 when running the CLI installer.

#!/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 address.
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

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

The command to run the installer container from the public Deckhouse container registry:

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

Where:

1. <DECKHOUSE_REVISION>: Deckhouse Platform edition. For example, 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>: Release channel in kebab-case format:
   • alpha: Alpha channel
   • beta: Beta channel
   • early-access: Early Access channel
   • stable: Stable channel
   • rock-solid: Rock Solid channel

Here is an example of a command to run the Deckhouse Platform Community Edition/Open installer container from the Stable release channel:

docker run -it --pull=always \
  -v "$PWD/config.yaml:/config.yaml" \
  -v "$PWD/dhctl-tmp:/tmp/dhctl" \
  -v "$HOME/.ssh/:/tmp/.ssh/" registry.deckhouse.io/deckhouse/ce/install:stable bash

Deckhouse Platform installation is performed within the installer container using the dhctl command:

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

Example of running a Deckhouse Platform installation with cloud cluster deployment:

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

Where:

• /config.yml: Installation configuration file.
• <SSH_USER>: Username for SSH connection to the server.
• --ssh-agent-private-keys: Private SSH key file for SSH connection.
• <SSH_PRIVATE_KEY_FILE>: Name of private key. For example, for a key with RSA encryption it can be id_rsa, and for a key with ED25519 encryption it can be id_ed25519.

If the server accepts only keys signed by an SSH certificate authority, put the certificate next to the private key as <SSH_PRIVATE_KEY_FILE>-cert.pub, for example id_ed25519-cert.pub. dhctl uses it automatically.

Pre-installation checks

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

1. General checks:
   • The values of the parameters publicDomainTemplate and clusterDomain (or the deprecated ClusterConfiguration.clusterDomain) do not match.
   • The authentication data for the container 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) has a supported container runtime (containerd) installed.
   • The host name is unique within the cluster.
   • The server’s system time is correct.
   • The address spaces for Pods (podSubnetCIDR) and services (serviceSubnetCIDR) do not intersect.
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) selected for the master node installation has the minimum resources listed in the Resource requirements section. The same section lists the node resources for each deployment option.
   • Python (Python 3 or Python 2) must be available on the server (VM) intended for the master node. The standard Python modules used by the installer must also be available:
     • For HTTP request handling: urllib.request (Python 3) or urllib2 (Python 2)
     • For HTTP error handling: urllib.error (Python 3) or urllib2 (Python 2)
     • For working with configuration files: configparser (Python 3) or ConfigParser (Python 2)
     • For HTTP server: http.server (Python 3) or SimpleHTTPServer (Python 2)
     • For TCP server: http.server (Python 3) or SocketServer (Python 2)
   • The container registry is accessible through a proxy (if proxy settings are specified in the installation configuration).
   • On the server (VM) intended for the master node and on the host from which the installer is launched, port 22/TCP (network access from a personal computer) must be accessible, as it is required for the installation process. For details, see the Network interaction of the platform components section.
   • DNS must resolve localhost to IP address 127.0.0.1.
   • The user has sudo privileges on the server (VM).
   • Required ports for the installation must be open:
     • Port 22/TCP between the host running the installer and the server.
     • No port conflicts with those used by the installation process.
   • The server (VM) has the correct time.
   • The server (VM) has no conflicts with the local deckhouse system user and group: the user and group are either absent, or the user has UID and primary GID 64535, the group has GID 64535, the user has no sudo privileges, and UID/GID 64535 are not assigned to other accounts. For details, see The local deckhouse system user.
   • The address spaces for Pods (podSubnetCIDR), services (serviceSubnetCIDR), and internal network (internalNetworkCIDRs) do not intersect.
3. Checks for cloud cluster installation:
   • The configuration of the virtual machine for the master node has the minimum resources listed in the Resource requirements section.
   • The cloud provider API is accessible from the cluster nodes.
   • The configuration for Yandex Cloud with NAT Instance is verified.

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

The local deckhouse system user

Deckhouse Platform components use UID/GID 64535 to run unprivileged processes and access their files on the node. The local deckhouse user and group reserve these identifiers for Deckhouse Platform and let the OS display the deckhouse name instead of numeric UID/GID values in tools such as ps, top, and ls. Processes owned by deckhouse in ps or top output are expected: they belong to Deckhouse Platform components, not to user sessions.

If the account does not exist, bashible creates it with the /sbin/nologin shell, without a password or sudo privileges. /etc/passwd lists the system default home directory for the user (usually /home/deckhouse). Bashible creates this directory separately as the base directory for the home directories of users defined by NodeUser resources; the deckhouse system account itself is not intended for login or storing user files. The account must not be provided through AD or LDAP.

The deckhouse name and UID/GID 64535 are reserved for Deckhouse Platform and are not configurable. Do not delete or rename the user or group, change their UID/GID, or grant the user sudo privileges. The preflight check accepts an absent user and group, or an existing pair where the user has UID and primary GID 64535, the group has GID 64535, and the user has no sudo privileges. Installation fails if the name is used with different IDs or UID/GID 64535 are assigned to other accounts.

The --preflight-skip-check=deckhouse-user flag disables the check but does not resolve the conflict. If the deckhouse user or group exists with different IDs, bashible does not modify it and logs a warning. If UID/GID 64535 are assigned to another account, bashible cannot create the deckhouse user or group. Nor does bashible revoke sudo privileges from an existing user.

If the conflict was left by a previous Deckhouse Platform installation on a static node, perform manual cleanup of the static node. This is a destructive operation: the cleanup script removes the services, configuration, and local Kubernetes, containerd, and etcd data created by Deckhouse Platform, as well as Deckhouse Platform accounts, and then reboots the server. Run the cleanup only on a node prepared for redeployment. In all other cases, resolve the conflict manually or recreate the node.

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, run the following command within the installer container:

dhctl bootstrap-phase abort

Installing virtualization

Virtualization is enabled by the virtualization ModuleConfig resource and deploys its components to the d8-virtualization namespace. You can either include the resource in the installation configuration file or apply it in a ready cluster.

A minimal configuration defines the image storage size and the subnets that virtual machines get addresses from:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: virtualization
spec:
  enabled: true
  version: 1
  settings:
    dvcr:
      storage:
        type: PersistentVolumeClaim
        persistentVolumeClaim:
          size: 50G
    virtualMachineCIDRs:
      - 10.66.10.0/24

The other parameters are covered in the module settings reference.

To check if virtualization is ready, run the following command:

d8 k get modules virtualization

Example output:

NAME             WEIGHT   SOURCE      PHASE   ENABLED   READY
virtualization   900      deckhouse   Ready   True      True

The module phase should be Ready.

Placement of virtualization components across nodes

How components are distributed across nodes depends on the cluster configuration. A cluster may have only master nodes running both control plane components and workloads; master and worker nodes; master, system, and worker nodes; or other combinations. Worker nodes here are the nodes without restrictions (taints) that would prevent regular workloads from running.

Deckhouse Platform distributes the components by priority, and if the cluster has a suitable node type, the component lands on it. What each component is responsible for is described in Virtualization subsystem.

The virt-handler-* component runs only on the nodes where Deckhouse Platform detected KVM support and set the virtualization.deckhouse.io/kvm-enabled label, and the virtualization-dra-* component runs only on nodes labeled with virtualization.deckhouse.io/usbip.

The components that create and upload virtual machine images and disks run only while that work is in progress:

Cluster with taints on all nodes

Sometimes taints are configured on every cluster node, which is how an administrator explicitly controls where workloads land. In such a configuration, keep the following in mind:

1. When creating a VirtualDisk, pay attention to the volumeBindingMode of the StorageClass. With Immediate, the PersistentVolume is created right after the disk is created, before the virtual machine is scheduled. Make sure the storage can create volumes on the nodes allowed for virtual machines by the placement parameters, including nodeSelector, tolerations, and the settings in the spec of the virtual machine or the VirtualMachineClass. Otherwise, the disk may end up on a node where the virtual machine can’t start. With WaitForFirstConsumer, the volume is created on the node the virtual machine is scheduled to, and the problem doesn’t occur.

2. VirtualImage and ClusterVirtualImage rely on the temporary components from the table above. They have a toleration for the dedicated.deckhouse.io=system taint.

3. The cluster has to have a system NodeGroup, or the administrator adds the dedicated.deckhouse.io=system taint to selected nodes without creating a NodeGroup. Without such nodes, these components won’t be scheduled, and images won’t reach the Ready phase.

Air-gapped environment, working via proxy and using external registries

Installing from an external (third-party) registry

Deckhouse Platform can be installed from an external container registry or via a proxy registry inside an air-gapped environment.

There are several options for configuring access to external container registries during cluster installation:

• Starting from Deckhouse Platform version 1.75 — using the deckhouse ModuleConfig.
• Prior to Deckhouse Platform version 1.75 — using InitConfiguration (considered a legacy method, refer to the example below).

To configure access using the deckhouse ModuleConfig, specify the external registry access parameters in the settings.registry section.

Specify the parameters for accessing a third-party registry in the settings.registry section of the ModuleConfig deckhouse.

Example:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse
spec:
  version: 1
  enabled: true
  settings:
    registry:
      mode: Direct
      direct:
        imagesRepo: test-registry.io/some/path
        scheme: HTTPS
        username: <username>
        password: <password>
        ca: <CA>

{"auths": { "<PROXY_REGISTRY>": {}}}

{"auths": { "<PROXY_REGISTRY>": {"username":"<PROXY_USERNAME>","password":"<PROXY_PASSWORD>","auth":"<AUTH_BASE64>"}}}

declare MYUSER='<PROXY_USERNAME>'
declare MYPASSWORD='<PROXY_PASSWORD>'
declare MYREGISTRY='<PROXY_REGISTRY>'

MYAUTH=$(echo -n "$MYUSER:$MYPASSWORD" | base64 -w0)
MYRESULTSTRING=$(echo -n "{\"auths\":{\"$MYREGISTRY\":{\"username\":\"$MYUSER\",\"password\":\"$MYPASSWORD\",\"auth\":\"$MYAUTH\"}}}" | base64 -w0)

echo "$MYRESULTSTRING"

Nexus configuration notes

When using the Nexus repository manager, the following requirements must be met:

• A proxy Docker repository must be created (“Administration” → “Repository” → “Repositories”):
  • The Maximum metadata age parameter is set to 0.
• Access control must be configured:
  • Create a role named Nexus (“Administration” → “Security” → “Roles”) with the following privileges:
    • nx-repository-view-docker-<repository>-browse
    • nx-repository-view-docker-<repository>-read
  • Create a user (“Administration” → “Security” → “Users”) and assign them the Nexus role.

To configure Nexus, follow these steps:

1. Create a proxy Docker repository (“Administration” → “Repository” → “Repositories”) that points to the public Deckhouse container registry.

2. Fill out the repository creation form with the following values:
   • Name: the desired repository name, e.g., d8-proxy.
   • Repository Connectors / HTTP or HTTPS: a dedicated port for the new repository, e.g., 8123 or another.
   • Remote storage: must be set to https://registry.deckhouse.io/.
   • Auto blocking enabled and Not found cache enabled: can be disabled for debugging; otherwise, enable them.
   • Maximum Metadata Age: must be set to 0.
   • If using a commercial edition of Deckhouse Platform, enable the Authentication checkbox and fill in the following:
     • Authentication Type: Username.
     • Username: license-token.
     • Password: Your Deckhouse Platform license key.

   
   
   

3. Configure Nexus access control to allow Deckhouse Platform to access the created repository:

   • Create a Nexus role (“Administration” → “Security” → “Roles”) with the following privileges: nx-repository-view-docker-<repository>-browse and nx-repository-view-docker-<repository>-read.

     

   • Create a user (“Administration” → “Security” → “Users”) and assign them the role created above.

     

   • Enable Docker Bearer Token Realm (“Administration” → “Security” → “Realms”):

     • The Docker Bearer Token Realm must be in the Active list (on the right), not in Available (on the left).
     • If it is not in Active:
       1. Find it in the Available list.
       2. Move it to Active using the arrow button.
       3. Click Save.
       4. Restart Nexus (it is required for the changes to take effect).

     

As a result, Deckhouse Platform images will be available at a URL as follows: https://<NEXUS_HOST>:<REPOSITORY_PORT>/deckhouse/ee:<d8s-version>.

Harbor configuration notes

Use the Harbor Proxy Cache feature.

1. Configure the registry access:
   • In the side menu, navigate to “Administration” → “Registries” and click “New Endpoint” to add a new endpoint for the registry.
   • In the “Provider” dropdown list, select “Docker Registry”.
   • In the “Name” field, enter an endpoint name of your choice.
   • In the “Endpoint URL” field, enter https://registry.deckhouse.io.
   • In the “Access ID” field, enter license-token.
   • In the “Access Secret” field, enter your Deckhouse Platform license key.
   • Set any remaining parameters as necessary.
   • Click “OK” to confirm creation of a new endpoint for the registry.

   

2. Create a new project:
   • In the side menu, navigate to “Projects” and click “New Project” to add a project.
   • In the “Project Name” field, enter a project name of your choice (for example, d8s). This name will be a part of the URL.
   • In the “Access Level” field, select “Public”.
   • Enable “Proxy Cache” and in the dropdown list, select the registry created earlier.
   • Set any remaining parameters as necessary.
   • Click “OK” to confirm creation of a new project.

   

Once Harbor is configured, Deckhouse Platform images will be available at a URL as follows: https://your-harbor.com/d8s/deckhouse/ee:{d8s-version}.

Manual loading of Deckhouse Platform images and vulnerability DB into a private registry

• Download and install the Deckhouse CLI utility.

• Download Deckhouse Platform images to a dedicated directory using the d8 mirror pull command.

  By default, d8 mirror pull downloads only the current versions of Deckhouse Platform, vulnerability scanner databases (if included in the Deckhouse Platform edition), and officially delivered modules. For example, for Deckhouse Platform 1.59, only version 1.59.12 will be downloaded, as it is sufficient for upgrading the platform from 1.58 to 1.59.

  Run the following command (specify the edition code and license key) to download the current version images:

  d8 mirror pull \
    --source='registry.deckhouse.io/deckhouse/<EDITION>' \
    --license='<LICENSE_KEY>' /home/user/d8-bundle
  

  Where:

  • --source: Address of the Deckhouse container registry.
  • <EDITION>: Deckhouse Platform edition code (for example, ee, se, se-plus). By default, the --source parameter refers to the Enterprise Edition (ee) and can be omitted.
  • --license: Parameter for specifying the Deckhouse Platform license key for authentication in the official container registry.
  • <LICENSE_KEY>: Deckhouse Platform license key.
  • /home/user/d8-bundle: Directory where the image packages will be placed. It will be created if it does not exist.

  If the image download is interrupted, rerunning the command will resume the download, provided no more than one day has passed since the interruption.

  Example command to download all Deckhouse Platform EE versions starting from version 1.59 (specify your license key):

  d8 mirror pull \
  --license='<LICENSE_KEY>' \
  --since-version=1.59 /home/user/d8-bundle
  

  Example command to download the current Deckhouse Platform SE versions (specify your license key):

  d8 mirror pull \
  --license='<LICENSE_KEY>' \
  --source='registry.deckhouse.io/deckhouse/se' \
  /home/user/d8-bundle
  

  Example command to download Deckhouse Platform images from an external registry:

  d8 mirror pull \
  --source='corp.company.com:5000/sys/deckhouse' \
  --source-login='<USER>' --source-password='<PASSWORD>' /home/user/d8-bundle
  

  Example command to download the vulnerability scanner database package:

  d8 mirror pull \
  --license='<LICENSE_KEY>' \
  --no-platform --no-modules /home/user/d8-bundle
  

  Example command to download all available additional module packages:

  d8 mirror pull \
  --license='<LICENSE_KEY>' \
  --no-platform --no-security-db /home/user/d8-bundle
  

  Example command to download module packages stronghold and secrets-store-integration:

  d8 mirror pull \
  --license='<LICENSE_KEY>' \
  --no-platform --no-security-db \
  --include-module stronghold \
  --include-module secrets-store-integration \
  /home/user/d8-bundle
  

  Example command to download stronghold module with semver ^ constraint (allows updates that don’t change the leftmost non-zero digit) from version 1.2.0:

  d8 mirror pull \
  --license='<LICENSE_KEY>' \
  --no-platform --no-security-db \
  --include-module stronghold@1.2.0 \
  /home/user/d8-bundle
  

  Example command to download secrets-store-integration module with semver ~ constraint (allows updates that don’t change the last specified digit’s place) from version 1.1.0:

  d8 mirror pull \
  --license='<LICENSE_KEY>' \
  --no-platform --no-security-db \
  --include-module secrets-store-integration@~1.1.0 \
  /home/user/d8-bundle
  

  Quote the --include-module flag value when it contains >= or <=. Unquoted, the shell treats it as an input/output redirection.

  Example command to download the console module with semver >= constraint (any version from the specified one and above) from version 1.43.2:

  d8 mirror pull \
  --license='<LICENSE_KEY>' \
  --no-platform --no-security-db \
  --include-module "console@>=1.43.2" \
  /home/user/d8-bundle
  

  Example command to download exact version of stronghold module 1.2.5 and publish to all release channels:

  d8 mirror pull \
  --license='<LICENSE_KEY>' \
  --no-platform --no-security-db \
  --include-module stronghold@=v1.2.5 \
  /home/user/d8-bundle
  

• On the host with access to the container registry where Deckhouse Platform images should be uploaded, copy the downloaded Deckhouse Platform image bundle and install the Deckhouse CLI.

• Upload Deckhouse Platform images to the registry using the d8 mirror push command.

  The d8 mirror push command uploads images from all packages located in the specified directory. If you only want to push specific packages, you can either run the command separately for each TAR image bundle by specifying the direct path to it, or temporarily remove the .tar extension from unwanted files or move them out of the directory.

  Example command to upload image packages from the /mnt/MEDIA/d8-images directory (provide authentication data if required):

  d8 mirror push /mnt/MEDIA/d8-images 'corp.company.com:5000/sys/deckhouse' \
    --registry-login='<USER>' --registry-password='<PASSWORD>'
  

  Before uploading the images, make sure that the target path in the container registry exists (in the example, /sys/deckhouse) and that the account used has write permissions.

  If you’re using Harbor, you won’t be able to upload images to the root of a project. Use a dedicated repository within the project to store Deckhouse Platform images.

• After uploading the images to the registry, you can proceed with installing Deckhouse Platform. Use the getting-started guide.

  When running the installer, use the address of your own image registry (where the images were uploaded earlier) instead of the official public Deckhouse Platform container registry. For the example above, the installer image address will be corp.company.com:5000/sys/deckhouse/install:stable instead of registry.deckhouse.io/deckhouse/ee/install:stable.

  In the registry section of ModuleConfig deckhouse, use your registry address and authorization data (starting with Deckhouse Platform 1.75). The legacy method is to use InitConfiguration (parameters imagesRepo, registryDockerCfg).

Creating a cluster and running Deckhouse Platform without using release channels

If you need to install Deckhouse Platform with automatic updates disabled:

1. Use the installer image tag corresponding to the desired version. For example, to install release v1.44.3, use the image your.private.registry.com/deckhouse/install:v1.44.3.

2. Specify the appropriate version number in the deckhouse.devBranch parameter of InitConfiguration.

   Do not specify the deckhouse.releaseChannel parameter in InitConfiguration.

If you want to disable automatic updates in an already running Deckhouse Platform installation (including patch updates), remove the releaseChannel parameter from the deckhouse module configuration.

Using a proxy server

To configure Deckhouse Platform to work with a proxy server, use the proxy parameter of the ClusterConfiguration resource.

Example:

apiVersion: deckhouse.io/v1
kind: ClusterConfiguration
clusterType: Cloud
cloud:
  provider: OpenStack
  prefix: main
podSubnetCIDR: 10.111.0.0/16
serviceSubnetCIDR: 10.222.0.0/16
kubernetesVersion: "Automatic"
cri: "Containerd"
clusterDomain: "cluster.local"
proxy:
  httpProxy: "http://user:password@proxy.company.my:3128"
  httpsProxy: "https://user:password@proxy.company.my:8443"

Automatic proxy variable loading for users in CLI

Starting from version 1.67, the /etc/profile.d/d8-system-proxy.sh file is no longer configured in Deckhouse Platform to set proxy variables for users.
To automatically load proxy variables for users in CLI, use the NodeGroupConfiguration resource:

apiVersion: deckhouse.io/v1alpha1
kind: NodeGroupConfiguration
metadata:
  name: profile-proxy.sh
spec:
  bundles:
    - '*'
  nodeGroups:
    - '*'
  weight: 99
  content: |
    {{- if .proxy }}
      {{- if .proxy.httpProxy }}
    export HTTP_PROXY={{ .proxy.httpProxy | quote }}
    export http_proxy=${HTTP_PROXY}
      {{- end }}
      {{- if .proxy.httpsProxy }}
    export HTTPS_PROXY={{ .proxy.httpsProxy | quote }}
    export https_proxy=${HTTPS_PROXY}
      {{- end }}
      {{- if .proxy.noProxy }}
    export NO_PROXY={{ .proxy.noProxy | join "," | quote }}
    export no_proxy=${NO_PROXY}
      {{- end }}
    bb-sync-file /etc/profile.d/profile-proxy.sh - << EOF
    export HTTP_PROXY=${HTTP_PROXY}
    export http_proxy=${HTTP_PROXY}
    export HTTPS_PROXY=${HTTPS_PROXY}
    export https_proxy=${HTTPS_PROXY}
    export NO_PROXY=${NO_PROXY}
    export no_proxy=${NO_PROXY}
    EOF
    {{- else }}
    rm -rf /etc/profile.d/profile-proxy.sh
    {{- end }}

Additional resources

• Getting started
• Supported Kubernetes and OS versions
• Integration with IaaS providers
• Installing Deckhouse Platform in a private environment
• Going to Production
• Global custom resources
• Global parameters