How to start module in the DKP cluster?

This section covers the process of running a configured module in a cluster managed by Deckhouse Kubernetes Platform (DKP).

Follow these steps to run the module in a cluster:

• Define ModuleSource (the ModuleSource resource).
• (optional) Define the module update policy (the ModuleUpdatePolicy resource).
• Enable the module in the cluster (the ModuleConfig resource).

Module source

Create a ModuleSource resource to set the source to fetch module information from. This resource will contain the address of the container registry to pull modules from, authentication parameters, and other settings.

An example of a ModuleSource resource:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleSource
metadata:
  name: example
spec:
  registry:
    repo: registry.example.com/deckhouse/modules
    dockerCfg: <base64 encoded credentials>

After the ModuleSource resource is created, DKP will start to perform periodic (every three minutes) data synchronization with the module source (fetching information about the modules available in the source).

Use the following command to check the synchronization status:

kubectl get ms

If the synchronization is successful, you will see output similar to the one below:

$ kubectl get ms
NAME        COUNT   SYNC   MSG
example     2       16s

If there are synchronization errors, the MSG column will contain a general description of the error, e.g.:

$ kubectl get ms
NAME        COUNT   SYNC   MSG
example     2       16s    Some errors occurred. Inspect status for details

Detailed error information can be found in the status.moduleErrors field of the ModuleSource resource.

For example, here’s how you can get detailed error description from the example module source:

$ kubectl  get ms example -o jsonpath='{range .status.moduleErrors[*]}{.name}{" module error:\n\t"}{.error}{"\n"}{end}'
module-1 module error:
  fetch image error: GET https://registry.example.com/v2/deckhouse/modules/module-1/release/manifests/stable: MANIFEST_UNKNOWN: manifest unknown; map[Tag:stable]
module-2 module error:
  fetch image error: GET https://registry.example.com/v2/deckhouse/modules/module-2/release/manifests/stable: MANIFEST_UNKNOWN: manifest unknown; map[Tag:stable]

If synchronization is successful, the .status.modules field of the ModuleSource resource will contain a list of modules ready to be enabled in the cluster.

Here is an example of how you can get a list of modules available from the example module source:

$ kubectl get ms example -o jsonpath='{.status.modules[*].name}'
module-1 module-2

The complete list of modules available from all module sources created in the cluster can be retrieved using the following command:

kubectl get ms  -o jsonpath='{.items[*].status.modules[*].name}'

After creating the ModuleSource resource and successful synchronization, module releases, i. e., ModuleRelease resources will begin to be created in the cluster (DKP creates them automatically, you don’t need to do it manually). Use the following command to print the list of releases:

kubectl get mr

An example of retrieving the list of module releases:

$ kubectl get mr
NAME                       PHASE        UPDATE POLICY   TRANSITIONTIME   MESSAGE
module-one-v1.21.3         Superseded   deckhouse       33h              
module-one-v1.22.0         Deployed     deckhouse       33h              
module-two-v1.2.0          Superseded   deckhouse       48d              
module-two-v1.2.1          Superseded   deckhouse       48d              
module-two-v1.2.3          Deployed     deckhouse       48d              
module-two-v1.2.4          Superseded   deckhouse       44d              
module-two-v1.2.5          Pending      deckhouse       44d              Waiting for the 'release.deckhouse.io/approved: \"true\"' annotation

If there is a module release in Deployed status, this module can be enabled in the cluster. If a module release is in Superseded status, it means that the module release is out of date, and there is a newer release to replace it.

kubectl annotate mr <module_release_name> modules.deckhouse.io/approved="true"

Switching the module to a different module source

Follow these steps to deploy a module from a different module source:

1. Find out what update policy is used for the module:

   kubectl get mr
   

   Look up the UPDATE POLICY for the module releases.

2. Before dropping this update policy, make sure there are no releases awaiting to be deployed (in Pending state) that fall under the policy being dropped or modified (or the labelSelector used by the policy no longer matches your module):

   kubectl delete mup <POLICY_NAME>
   

3. Create a new ModuleSource resource.

4. Create a new ModuleUpdatePolicy resource with the correct labels (source) for the new ModuleSource.

5. Confirm that new ModuleReleases for a module are created from a new ModuleSource according to the update policy.

   kubectl get mr
   

Module update policy

The module update policy refers to the rules that DKP uses to update modules in the cluster. It is set by the ModuleUpdatePolicy resource with the following settings:

• module update mode (automatic, manual, updates are disabled);
• the release channel to use for updates;
• time windows for automatic updates during which the module update is permitted.

You do not have to create the ModuleUpdatePolicy resource. If the update policy for a module is not defined (there is no corresponding ModuleUpdatePolicy resource), the update settings match the update settings of DKP (the update parameter of the deckhouse module).

The following is an example of the ModuleUpdatePolicy resource that defines the update policy for the module-1 module of the example module source (the example ModuleSource). The update policy enables automatic module updates on Mondays and Wednesdays between 13:30 and 14:00 UTC:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleUpdatePolicy
metadata:
  name: example-update-policy
spec:
  moduleReleaseSelector:
    labelSelector:
      matchLabels:
        source: example
        module: module-1
  releaseChannel: Alpha
  update:
    mode: Auto
    windows:
    - days:
      - "Mon"
      - "Wed"
      from: "13:30"
      to: "14:00"

moduleReleaseSelector — usage examples

• Apply the policy to all ModuleSource deckhouse modules:

  moduleReleaseSelector:
    labelSelector:
      matchLabels:
        source: deckhouse
  

• Apply the policy to the deckhouse-admin module independently of ModuleSource:

  moduleReleaseSelector:
    labelSelector:
      matchLabels:
        module: deckhouse-admin
  

• Apply the policy to the deckhouse-admin module from the deckhouse ModuleSource:

  moduleReleaseSelector:
    labelSelector:
      matchLabels:
        module: deckhouse-admin
        source: deckhouse
  

• Apply the policy only to the deckhouse-admin and secrets-store-integration modules in the deckhouse ModuleSource:

  moduleReleaseSelector:
    labelSelector:
      matchExpressions:
      - key: module
        operator: In
        values:
        - deckhouse-admin
        - secrets-store-integration
      matchLabels:
        source: deckhouse
  

• Apply the policy to all deckhouse ModuleSource modules except for deckhouse-admin:

  moduleReleaseSelector:
    labelSelector:
      matchExpressions:
      - key: module
        operator: NotIn
        values:
        - deckhouse-admin
      matchLabels:
        source: deckhouse
  

Enabling the module

Before enabling the module, make sure that it can be enabled. Run the following command to list all the available DKP modules:

kubectl get modules

The module must be in the list.

Below is an example of the output:

$ kubectl get modules
NAME                                  WEIGHT   STATE      SOURCE
...
module-test                           900      Disabled   example
...

It shows that the module-test module can be enabled.

If the module is not in the list, check that module source is defined and the module is listed in the module source. Also check the update policy of the module (if defined). If the module update policy is not defined, it matches the DKP update policy (the releaseChannel parameter and the update section of the deckhouse module parameters).

You can enable the module similarly to built-in DKP modules using any of the following methods:

• Run the command below (specify the name of the module):

  kubectl -ti -n d8-system exec svc/deckhouse-leader -c deckhouse -- deckhouse-controller module enable <MODULE_NAME>
  

• Create a ModuleConfig resource containing the enabled: true parameter and module settings..

  Below is an example of a ModuleConfig that enables and configures the module-1 module in the cluster:

  apiVersion: deckhouse.io/v1alpha1
  kind: ModuleConfig
  metadata:
    name: module-1
  spec:
    enabled: true
    settings:
      parameter: value
    version: 1
  

Troubleshooting

If there were errors while enabling a module in the cluster, you can learn about them as follows:

• View the DKP log:

  kubectl -n d8-system logs -l app=deckhouse
  

• View the ModuleConfig resource of the module:

  Here is an example of the error message for module-1:

  $ kubectl get moduleconfig module-1
  NAME        ENABLED   VERSION   AGE   MESSAGE
  module-1    true                7s    Ignored: unknown module name
  

Similar to DeckhouseRelease (a DKP release resource), modules have a ModuleRelease resource. DKP creates ModuleRelease resources based on what is stored in the container registry. When troubleshooting module issues, check the module releases available in the cluster as well:

kubectl get mr

Output example:

$ kubectl get mr
NAME                 PHASE        UPDATE POLICY          TRANSITIONTIME   MESSAGE
module-1-v1.23.2     Pending      example-update-policy  3m               Waiting for the 'release.deckhouse.io/approved: "true"' annotation

The example output above illustrates ModuleRelease message when the update mode (update.mode of the ModuleUpdatePolicy resource is set to Manual. In this case, you must manually confirm the installation of the new module version by adding the modules.deckhouse.io/approved="true" annotation to the release:

kubectl annotate mr module-1-v1.23.2 modules.deckhouse.io/approved="true"