The deckhouse module implements the core of Deckhouse Kubernetes Platform (DKP), performing the following operations:

  • Platform updates
  • Module configuration management
  • Module installation and updates
  • Module documentation build triggering
  • Validation of custom resources managed by DKP modules

The module manages the following custom resources in the deckhouse.io API group:

  • Module management:
  • Platform management:
    • DeckhouseRelease: An object that defines the DKP release (version) and platform update policy.
  • Package management (Marketplace):
  • Utility management:
  • Management of custom resources controlled by DKP modules:

Module architecture

The following simplifications are made in the diagram:

  • The diagram shows containers in different pods interacting directly with each other. In reality, they communicate via the corresponding Kubernetes Services (internal load balancers). Service names are omitted if they are obvious from the context. Otherwise, the Service name is shown above the arrow.
  • Pods may run multiple replicas. However, each pod is shown as a single replica in the diagram.

The Level 2 C4 architecture of the deckhouse module and its interaction with other DKP components are shown in the following diagram:

Deckhouse module architecture

Module components

The module consists of the following components:

  1. Deckhouse (Deployment): A controller that implements platform management operations.

    The controller coordinates platform management tasks using the queueing mechanism.

    The Deckhouse controller can run in standard mode or in hook isolation mode. To enable it, create the chroot-mode ConfigMap in the d8-system namespace. In isolation mode, shell hooks and module enable scripts run in a chroot environment with a limited set of mounted directories, isolating them from the controller container file system.

    If High Availability (HA) mode is enabled, multiple Deckhouse controller instances are started. To ensure correct behavior, Deckhouse controllers perform leader election using the deckhouse-leader-election Lease resource. The controller elected as leader performs all platform management operations.

    In addition, you can set the following parameters using the Deckhouse controller:

    Module configuration parameter Description
    logLevel Logging level
    bundle Set of modules enabled by default
    releaseChannel Release channel
    update.mode Update mode
    update.windows.days Update windows

    For details about module settings, refer to the module documentation section.

    It consists of the following containers:

    • init-downloaded-modules: Init container that prepares the directory structure required for module operations.
    • deckhouse: Main container.
    • kube-rbac-proxy: Sidecar container with an authorization proxy based on Kubernetes RBAC that provides secure access to the main container component debug interface.

  2. Webhook-handler (Deployment): Consists of a single handler container and implements a generic webhook for conversion and validation of custom resources managed by DKP.

    The component watches ConversionWebhook and ValidationWebhook custom resources and, based on them, generates hook Python files for shell-operator from templates. When kube-apiserver sends resource validation or conversion requests, shell-operator runs the required hook and returns the processing result.

  3. Cni-migration-manager (Deployment): An optional component running on control plane nodes, consisting of a single manager container. The component manages the network plugin (CNI) switching process in the DKP cluster and records the current state in the CNIMigration custom resource. Migration to Flannel, Simple bridge, and Cilium is supported. For details on switching CNI in the cluster, refer to the corresponding guide.

    The component is created by the detect-cni-migration global hook when the CNIMigration custom resource exists. The CNIMigration resource is created manually by an administrator or by running the d8 network cni-migration switch --to-cni <target cni> command.

  4. Cni-migration-agent (DaemonSet): An optional component running on all cluster nodes, consisting of a single agent container. The component watches the CNIMigration custom resource and manages the CNINodeMigration custom resource that reflects migration state for a specific node.

    The component is created by the detect-cni-migration global hook when the CNIMigration custom resource exists. The CNIMigration resource is created manually by an administrator or by running the d8 network cni-migration switch --to-cni <target cni> command.

Module interactions

The module interacts with the following components:

  1. Kube-apiserver:
    • Working with custom resources in the deckhouse.io API group.
    • Watching Pod and DaemonSet resources, as well as restarting Pods when the network plugin is changed.
    • Watching resources described in the ObjectKeeper custom resource.
    • Creating and updating Lease resources.
    • Creating, deleting, modifying, and watching resources described in DKP modules.
    • Authorizing requests.

  2. Documentation: Updating documentation when a DKP module is added or updated.

  3. Image registry: Retrieving module component images along with metadata when the registry module is installed in Unmanaged mode.

  4. registry module: Retrieving module component images along with metadata when the registry module is installed in one of the following modes: Direct, Proxy, or Local.

The module is interacted with by the following external components:

  • Kube-apiserver: Validation and conversion of DKP custom resources.
  • Prometheus-main: Collecting metrics from the deckhouse and webhook-handler containers.

Additional resources