The deckhouse module implements the core of Deckhouse Kubernetes Platform (DKP), performing various platform management operations using a queueing mechanism. For more information about the module architecture, refer to the corresponding documentation section.

The Deckhouse controller implements addon-operator and marketplace queues.

Addon-operator queues

The addon-operator queues are the primary processing mechanism for built-in and external DKP modules. The queue is implemented in shell-operator and extended with addon-operator task types. The Deckhouse controller synchronizes ModuleConfig custom resources and updates global or module values for addon-operator.

Task types:

Task Function
GlobalHookRun Runs global hooks (onStartup, beforeAll, afterAll, kubernetes, schedule)
GlobalHookEnableKubernetesBindings Enables Kubernetes monitors from global hooks
GlobalHookWaitKubernetesSynchronization Blocks the queue until global hooks with executeHookOnSynchronization: true complete
GlobalHookEnableScheduleBindings Registers cron tasks in the addon-operator scheduler
DiscoverHelmReleases Finds “extra” Helm releases after the first converge
ApplyKubeConfigValues Applies changes from ModuleConfig
ConvergeModules Full converge cycle for all modules
ModuleRun Configures or updates a module, including subtasks: onStartup -> sync -> beforeHelm -> helm -> afterHelm
ParallelModuleRun Launches modules in batch and in parallel
ModuleDelete Removes a module (helm delete, afterDeleteHelm)
ModuleHookRun Runs a module hook on event
ModuleEnsureCRDs Installs module CRDs
ModulePurge Removes unknown Helm release

Addon-operator queue types:

Queue Name Purpose
Main main Runs global hooks at startup, installs critical modules, configures and deletes modules
Parallel parallel_queue_0 … parallel_queue_19 Parallel ModuleRun with module dependencies taken into account (20 queues)
Hook queues From task config (hook) Tasks for a specific module and global hooks

Each queue is a separate pipeline with one worker. The queue has the following properties:

  • Tasks can be inserted both at the tail (AddLast) and at the head (AddFirst) of the queue.
  • Tasks are executed from the head of the queue.
  • Multiphase operations are supported with the following operations:
    • AddHeadTasks: Insert subtasks before the current task.
    • AddTailTasks: Insert a subtask at the end of the queue after the current task succeeds.
    • AddAfterTasks: Insert a subtask right after the current task.
  • A task is executed until success unless allowFailure: true is set in task parameters.
  • On error, exponential restart (backoff) is applied, starting with a 5-second delay between retries.

If a task cannot complete successfully and allowFailure: true is not set in its parameters, that task blocks the queue it runs in. Tasks in different processing queues do not block each other.

At startup, the Deckhouse controller creates main and parallel_queue_0..19 queues and adds the following tasks to main in this order:

  • GlobalHookRun (onStartup): For each global hook.
  • GlobalHookEnableScheduleBindings: To enable cron scheduling.
  • GlobalHookEnableKubernetesBindings: To enable global tasks that watch Kubernetes resources.
  • GlobalHookWaitKubernetesSynchronization.
  • ConvergeModules (OperatorStartup): First converge of all modules.

After ConvergeModules, the controller adds the DiscoverHelmReleases task to clean up unknown Helm releases.

The module processing order in the ConvergeModules task is determined by several attributes:

  • Module criticality: The critical parameter in the module module.yaml configuration.
  • Module weight: Numeric module processing order. The higher the number, the later the module is processed. The weight is taken from the weight parameter in module module.yaml; if missing or set to 0, the default weight 900 is used. If no module config file exists, the weight is taken from the numeric prefix of the module directory name (for example, 040-node-manager means weight 40). If the weight cannot be obtained from the directory name, weight 100 is used.
  • Module dependencies: A list of modules that must be installed before the current module.

Based on these attributes, the Deckhouse controller scheduler defines processing order according to the following principles:

  • For critical modules, module weight is considered in ascending order and tasks are put into the main queue.
  • For non-critical modules, module weight is not considered and tasks are put into parallel_queue_0..19.
  • For all modules, dependencies on other modules are considered.

If critical modules can be processed in parallel, the Deckhouse controller scheduler places the ParallelModuleRun task into the main queue with the list of modules. The ParallelModuleRun task starts a ModuleRun task for each module in parallel_queue_0..19 and waits for completion, thereby blocking the main queue. If an error occurs while processing a ModuleRun task, the scheduler moves this task to the end of the queue and starts the next queue task.

The process of installing critical modules is shown in the following diagram:

Sequence diagram for installing critical modules

The process of installing non-critical (functional) modules is shown in the following diagram:

Sequence diagram for installing functional modules

If more than one identical task is added to a queue, all duplicates are removed when such a task starts, as part of deduplication.

To view addon-operator queues, use the d8 system queue list command.

Marketplace queues

The Marketplace queues are a queue implementation used by Marketplace functionality.

Each queue served by the Deckhouse controller for Marketplace has the following properties:

  • FIFO (First In First Out): Defines strict task execution order. The first task in queue is executed first.
  • Strict sequential execution of tasks, one task at a time.
  • Tasks are started only on events (event-driven), without polling any resources.
  • Restart on errors with exponential backoff between retries, starting at 15 seconds and capped at 1 minute, with no limit on retry attempts.
  • Supports cascading task cancellation on version changes or package deletion.

Queue types:

Name Purpose
{packageName} Lifecycle: Deploy, Load, Configure, Enable, Run, Disable, Undeploy
{packageName}/{hookQueue} Running hooks triggered by Kubernetes or schedule events (queue from hook binding)
{packageName}/{hookQueue}/sync Hook synchronization at startup (WaitForSynchronization)

Task types:

Task Function
Deploy Downloads or mounts the package image
Load Parses configuration, creates Application or Module, registers in scheduler
Configure Applies Application or Module settings using the parameter store
Enable Enables hooks, performs parameter synchronization, runs OnStartup hook
Run Runs subtasks when installing Application or Module: BeforeHelm -> helm Upgrade -> AfterHelm
HookRun Runs a hook on event
HookSync Performs initial synchronization of Kubernetes binding
Disable Removes Helm, disables hooks, clears hook queues
Undeploy Removes the package from disk

Task execution in one queue does not block task execution in another queue.

To view Marketplace queues, run the following command:

When performing module installation or configuration tasks in addon-operator, the Deckhouse controller pauses Marketplace queue processing.

Additional resources