Usage example | registry

The module lifecycle stage: Preview

If, during the switching process, the image of a module did not reload and the module did not reinstall, use the instructions to resolve the issue.

Switching to the `Direct` Mode

To switch an already running cluster to Direct mode, follow these steps:

The first switch from Unmanaged to Direct mode will result in a full restart of all DKP components.

Before switching, perform the migration to use the registry module.

Make sure the registry module is enabled and running. To do this, execute the following command:

d8 k get module registry -o wide

Example output:

NAME       WEIGHT ...  PHASE   ENABLED   DISABLED MESSAGE   READY
registry   38     ...  Ready   True                         True

Make sure all master nodes are in the Ready state and do not have the SchedulingDisabled status, using the following command:

d8 k get nodes

Example output:

NAME       STATUS   ROLES                 ...
master-0   Ready    control-plane,master  ...
master-1   Ready    control-plane,master  ...
master-2   Ready    control-plane,master  ...

Example of output when the master node (master-2 in the example) is in the SchedulingDisabled status:

NAME       STATUS                      ROLES                 ...
master-0   Ready    control-plane,master  ...
master-1   Ready    control-plane,master  ...
master-2   Ready,SchedulingDisabled    control-plane,master  ...

Ensure the Deckhouse job queue is empty and contains no errors:

d8 system queue list

Example output:

Summary:
- 'main' queue: empty.
- 107 other queues (0 active, 107 empty): 0 tasks.
- no tasks to handle.

Set the Direct mode configuration in the ModuleConfig deckhouse. If you’re using a registry other than registry.deckhouse.io, refer to the deckhouse module documentation for correct configuration.

Configuration example:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse
spec:
  version: 1
  enabled: true
  settings:
    registry:
      mode: Direct
      direct:
        imagesRepo: registry.deckhouse.io/deckhouse/ee
        scheme: HTTPS
        license: <LICENSE_KEY> # Replace with your license key

Check the registry switch status in the registry-state secret using this guide.

Example output:

conditions:
# ...
  - lastTransitionTime: "..."
    message: ""
    reason: ""
    status: "True"
    type: Ready
hash: ..
mode: Direct
target_mode: Direct

Switching to the `Proxy` Mode

To switch an already running cluster to Proxy mode, follow these steps:

The first switch from Unmanaged to Proxy mode will result in a full restart of all DKP components.
Switching from Local mode to Proxy mode is not available. To switch from Local mode, you must switch the registry to another available mode (for example: Direct).

Before switching, perform the migration to use the registry module.

Make sure the registry module is enabled and running. To do this, execute the following command:

d8 k get module registry -o wide

Example output:

NAME       WEIGHT ...  PHASE   ENABLED   DISABLED MESSAGE   READY
registry   38     ...  Ready   True                         True

Make sure all master nodes are in the Ready state and do not have the SchedulingDisabled status, using the following command:

d8 k get nodes

Example output:

NAME       STATUS   ROLES                 ...
master-0   Ready    control-plane,master  ...
master-1   Ready    control-plane,master  ...
master-2   Ready    control-plane,master  ...

Example of output when the master node (master-2 in the example) is in the SchedulingDisabled status:

NAME       STATUS                      ROLES                 ...
master-0   Ready    control-plane,master  ...
master-1   Ready    control-plane,master  ...
master-2   Ready,SchedulingDisabled    control-plane,master  ...

Ensure the Deckhouse job queue is empty and contains no errors:

d8 system queue list

Example output:

Summary:
- 'main' queue: empty.
- 107 other queues (0 active, 107 empty): 0 tasks.
- no tasks to handle.

Set the Proxy mode configuration in the ModuleConfig deckhouse. If you’re using a registry other than registry.deckhouse.io, refer to the deckhouse module documentation for correct configuration.

Configuration example:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse
spec:
  version: 1
  enabled: true
  settings:
    registry:
      mode: Proxy
      proxy:
        imagesRepo: registry.deckhouse.io/deckhouse/ee
        scheme: HTTPS
        license: <LICENSE_KEY> # Replace with your license key

Check the registry switch status in the registry-state secret using this guide.

Example output:

conditions:
# ...
  - lastTransitionTime: "..."
    message: ""
    reason: ""
    status: "True"
    type: Ready
hash: ..
mode: Proxy
target_mode: Proxy

Switching to the `Local` Mode

To switch an already running cluster to Local mode, follow these steps:

The first switch from Unmanaged to Local mode will result in a full restart of all DKP components.
Switching from Proxy mode to Local mode is not available. To switch from Proxy mode, you must switch the registry to another available mode (for example: Direct).

Before switching, perform the migration to use the registry module.

Make sure the registry module is enabled and running. To do this, execute the following command:

d8 k get module registry -o wide

Example output:

NAME       WEIGHT ...  PHASE   ENABLED   DISABLED MESSAGE   READY
registry   38     ...  Ready   True                         True

Make sure all master nodes are in the Ready state and do not have the SchedulingDisabled status, using the following command:

d8 k get nodes

Example output:

NAME       STATUS   ROLES                 ...
master-0   Ready    control-plane,master  ...
master-1   Ready    control-plane,master  ...
master-2   Ready    control-plane,master  ...

Example of output when the master node (master-2 in the example) is in the SchedulingDisabled status:

NAME       STATUS                      ROLES                 ...
master-0   Ready    control-plane,master  ...
master-1   Ready    control-plane,master  ...
master-2   Ready,SchedulingDisabled    control-plane,master  ...

Ensure the Deckhouse job queue is empty and contains no errors:

d8 system queue list

Example output:

Summary:
- 'main' queue: empty.
- 107 other queues (0 active, 107 empty): 0 tasks.
- no tasks to handle.

Prepare archives with DKP images of the current version. To do this, use the d8 mirror command.

Example:

TAG=$(
 d8 k -n d8-system get deployment/deckhouse -o yaml \
 | yq -r '.spec.template.spec.containers[] | select(.name == "deckhouse").image | split(":")[-1]'
) && echo "TAG: $TAG"

EDITION=$(
 d8 k -n d8-system exec -it svc/deckhouse-leader -- deckhouse-controller global values -o yaml \
 | yq .deckhouseEdition
) && echo "EDITION: $EDITION"

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

Set the Local mode configuration in the ModuleConfig deckhouse.

Configuration example:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse
spec:
  version: 1
  enabled: true
  settings:
    registry:
      mode: Local

Check the registry switch status in the registry-state secret using this guide. In the status, you need to wait for the RegistryContainsRequiredImages check to start. The condition will show the absence or presence of images in the running local registry.

Example output:

conditions:
# ...
- lastTransitionTime: "..."
  message: |-
    Mode: Default
    master-1: 0 of 166 items processed, 166 items with errors:
    - source: module/control-plane-manager/control-plane-manager133
      image: 10.128.0.5:5001/system/deckhouse@sha256:00202db19b40930f764edab5695f450cf709d50736e012055393447b3379414a
      error: HEAD https://10.128.0.5:5001/v2/system/deckhouse/manifests/sha256:00202db19b40930f764edab5695f450cf709d50736e012055393447b3379414a: unexpected status code 404 Not Found (HEAD responses have no body, use GET for details)
    - source: module/cloud-provider-yandex/cloud-metrics-exporter
      image: 10.128.0.5:5001/system/deckhouse@sha256:05517a86fcf0ec4a62d14ed7dc4f9ffd91c05716b8b0e28263da59edf11f0fad
      error: HEAD https://10.128.0.5:5001/v2/system/deckhouse/manifests/sha256:05517a86fcf0ec4a62d14ed7dc4f9ffd91c05716b8b0ed86d6a1f465f4556fb8: unexpected status code 404 Not Found (HEAD responses have no body, use GET for details)
    - source: module/control-plane-manager/kube-controller-manager132
      image: 10.128.0.5:5001/system/deckhouse@sha256:13f24cc717698682267ed2b428e7399b145a4d8ffe96ad1b7a0b3269b17c7e61
      error: HEAD https://10.128.0.5:5001/v2/system/deckhouse/manifests/sha256:13f24cc717698682267ed2b428e7399b145a4d8ffe96ad1b7a0b3269b17c7e61: unexpected status code 404 Not Found (HEAD responses have no body, use GET for details)

      ...and more
  reason: Processing
  status: "False"
  type: RegistryContainsRequiredImages

Upload the images to the local registry using the d8 mirror command. Image upload to the local registry is performed via Ingress at registry.${PUBLIC_DOMAIN}.

Get the password for the read-write user of the local registry:

$ d8 k -n d8-system get secret/registry-user-rw -o json | jq -r '.data | to_entries[] | "\(.key): \(.value | @base64d)"'
name: rw
password: KFVxXZGuqKkkumPz
passwordHash: $2a$10$Phjbr6iinLf00ZZDD2Y7O.p9H3nDOgYzFmpYKW5eydGvIsdaHQY0a

Upload images to the local registry:

d8 mirror push \
--registry-login="rw" \
--registry-password="KFVxXZGuqKkkumPz" \
/home/user/d8-bundle \
registry.${PUBLIC_DOMAIN}/system/deckhouse

Check the registry switch status in the registry-state secret using this guide. After uploading the images, the RegistryContainsRequiredImages status should be in the Ready state.

Example output:

conditions:
# ...
- lastTransitionTime: "..."
  message: |-
    Mode: Default
    master-1: all 166 items are checked
  reason: Ready
  status: "True"
  type: RegistryContainsRequiredImages
hash: ..
mode: Direct
target_mode: Local

Wait for the switch to complete. To check the switch status, use this guide.

Example output:

conditions:
# ...
  - lastTransitionTime: "..."
    message: ""
    reason: ""
    status: "True"
    type: Ready
hash: ..
mode: Local
target_mode: Local

Switching to the `Unmanaged` Mode

To switch an already running cluster to Unmanaged mode, follow these steps:

Changing the registry in Unmanaged mode will result in a full restart of all DKP components.

Before switching, perform the migration to use the registry module.

Make sure the registry module is enabled and running. To do this, execute the following command:

d8 k get module registry -o wide

Example output:

NAME       WEIGHT ...  PHASE   ENABLED   DISABLED MESSAGE   READY
registry   38     ...  Ready   True                         True

Ensure the Deckhouse job queue is empty and contains no errors:

d8 system queue list

Example output:

Summary:
- 'main' queue: empty.
- 107 other queues (0 active, 107 empty): 0 tasks.
- no tasks to handle.

Set the Unmanaged mode configuration in the ModuleConfig deckhouse. If you’re using a registry other than registry.deckhouse.io, refer to the deckhouse module documentation for correct configuration.

Configuration example:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: deckhouse
spec:
  version: 1
  enabled: true
  settings:
    registry:
      mode: Unmanaged
      unmanaged:
        imagesRepo: registry.deckhouse.io/deckhouse/ee
        scheme: HTTPS
        license: <LICENSE_KEY> # Replace with your license key

Check the registry switch status in the registry-state secret using this guide.

Example output:

conditions:
# ...
  - lastTransitionTime: "..."
    message: ""
    reason: ""
    status: "True"
    type: Ready
hash: ..
mode: Unmanaged
target_mode: Unmanaged

If you need to switch back to the old registry management method, refer to the instruction.

This is a deprecated format for registry management.

Module registry: usage example

Switching to the `Direct` Mode

Switching to the `Proxy` Mode

Switching to the `Local` Mode

Switching to the `Unmanaged` Mode

An error has occurred

Tell us what you didn’t like.

Module registry: usage example

Switching to the Direct Mode

Switching to the Proxy Mode

Switching to the Local Mode

Switching to the Unmanaged Mode

An error has occurred

Tell us what you didn’t like.

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC Compliance Report

Thank you

Error

Switching to the `Direct` Mode

Switching to the `Proxy` Mode

Switching to the `Local` Mode

Switching to the `Unmanaged` Mode