This page applies only to Managed Kubernetes clusters. Registry management through the registry module is not available in these clusters.

For clusters fully managed by Deckhouse Platform (DP), registry settings are configured using the registry module (or, in clusters still running its previous implementation, in the registry section of the deckhouse module configuration). For configuration examples and descriptions of the implementations, see “Managing the registry in DP-managed clusters”.

The information on this page applies to clusters that use containerd v1 or containerd v2 as their primary container runtime. However, containerd v2 is the current standard for DP. If you need to migrate to containerd v2, refer to the section “Migrating container runtime to containerd v2” to verify availability and perform the migration.

Using registries other than registry.deckhouse.io and registry.deckhouse.ru is only available in commercial editions of the Deckhouse Platform.

The methods for adding a configuration for a registry are described in the section “Adding a configuration for an additional registry”.

To switch the cluster to use an external registry, follow these steps:

  1. Run the deckhouse-controller helper change-registry command from the DP pod with the parameters of the new registry.
    Example:

    d8 k -n d8-system exec -ti svc/deckhouse-leader -c deckhouse -- deckhouse-controller helper change-registry --user MY-USER --password MY-PASSWORD registry.example.com/deckhouse/ee

  2. If the registry uses self-signed certificates, place the corresponding root certificate in the file /tmp/ca.crt inside the DP pod and add the --ca-file /tmp/ca.crt option to the command. Alternatively, insert the CA content into a variable, as shown below:

    CA_CONTENT=$(cat <<EOF
-----BEGIN CERTIFICATE-----
CERTIFICATE
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
CERTIFICATE
-----END CERTIFICATE-----
EOF
)
d8 k -n d8-system exec svc/deckhouse-leader -c deckhouse -- bash -c "echo '$CA_CONTENT' > /tmp/ca.crt && deckhouse-controller helper change-registry --ca-file /tmp/ca.crt --user MY-USER --password MY-PASSWORD registry.example.com/deckhouse/ee"

    To view the list of available flags for the deckhouse-controller helper change-registry command, run:

    d8 k -n d8-system exec -ti svc/deckhouse-leader -c deckhouse -- deckhouse-controller helper change-registry --help

    Example output:

    usage: deckhouse-controller helper change-registry [<flags>] <new-registry>
Change registry for deckhouse images.
Flags:
  --help               Show context-sensitive help (also try --help-long and --help-man).
  --user=USER          User with pull access to registry.
  --password=PASSWORD  Password/token for registry user.
  --ca-file=CA-FILE    Path to registry CA.
  --scheme=SCHEME      Used scheme while connecting to registry, http or https.
  --dry-run            Don't change deckhouse resources, only print them.
  --new-deckhouse-tag=NEW-DECKHOUSE-TAG
                      New tag that will be used for deckhouse deployment image (by default
                       current tag from deckhouse deployment will be used).
Args:
  <new-registry>  Registry that will be used for deckhouse images (example:
                  registry.deckhouse.io/deckhouse/ce). By default, https will be used, if you need
                  http - provide '--scheme' flag with http value
  3. Wait until the registry Pod reaches the Ready status. If the Pod is in the ImagePullBackoff state, restart it.

  4. Wait for bashible to apply the new settings on the master node.

    Check the bashible system service log on the master node, for example, using the following command:

    journalctl -u bashible -n 20

    The log should contain the message Configuration is in sync, nothing to do.

    Example of output when viewing the bashible service log:

    Aug 13 05:03:08 kube-master-0 systemd[1]: Started Bashible service.
Aug 13 05:03:10 kube-master-0 bash[1847265]: Configuration is in sync, nothing to do.   <--
Aug 13 05:03:10 kube-master-0 systemd[1]: bashible.service: Deactivated successfully.
Aug 13 05:03:10 kube-master-0 systemd[1]: bashible.service: Consumed 1.075s CPU time.
  5. If you need to disable automatic DP upgrades through the external registry, remove the releaseChannel parameter from the deckhouse module configuration. After that, automatic platform upgrades will be disabled, and you will need to manage the DP version manually.

  6. Check if any pods in the cluster are still using the original registry address:

    d8 k get pods -A -o json | jq -r '.items[] | select(.spec.containers[]
  | select(.image | startswith("registry.deckhouse"))) | .metadata.namespace + "\t" + .metadata.name' | sort | uniq

If a module’s image wasn’t pulled and the module wasn’t reinstalled during the switch, follow the instructions to resolve the issue.

Additional resources