This is unreleased documentation for SUSE® Rancher Manager v2.15 (Unreleased).

Configuring a Global Default Private Registry

This page describes how to configure a global default private registry from the Rancher UI, after Rancher is already installed.

For instructions on how to set up a private registry during Rancher installation, refer to the air-gapped installation guide.

A private registry provides a consistent, centralized source of truth for container images across your clusters. You can use a private registry to share custom images within your organization or to avoid rate limits when pulling from public registries.

There are two main ways to set up a private registry in Rancher:

Set up a global system default registry in the Settings tab in the global view.
Set up a cluster-level system default private registry in Advanced Options when provisioning or updating a downstream cluster.

Use the global system default registry in air-gapped environments or other setups where all clusters share the same default registry host. Rancher uses this registry to pull core images required for system components and configures downstream clusters to do the same by default.

Use a cluster-level default registry when a downstream cluster needs a different registry than the global default or requires different credentials for the same registry.

Set a Private Registry with No Credentials as the Default Registry

Log into Rancher and configure the default administrator password.
Select ☰ > Global Settings.
Go to system-default-registry and choose ⋮ > Edit Setting.
Enter your registry’s hostname and port (e.g. registry.yourdomain.com:port). Do not prefix the text with http:// or https://.

Result: Rancher pulls system images from your private registry.

Set an Authenticated Private Registry as the Default Registry

If your registry requires authentication (such as .dockerconfigjson), perform the following steps:

Log in to Rancher and configure the default administrator password.
Create a new registry secret in the cattle-system namespace using kubectl, Terraform, or the Rancher UI.
If you create the secret outside the Rancher UI, ensure that backup labels are set
Select ☰ > Global Settings.
Find system-default-registry-pull-secrets and select ⋮ > Edit Setting.
Enter the name of the registry pull secret in the cattle-system namespace created in step 2 (such as my-reg-cred).
Find system-default-registry and select ⋮ > Edit Setting.
Enter your registry hostname and port (such as registry.yourdomain.com:port). Do not prefix the text with http:// or https://.

Result: Rancher propagates the pull secret into the required Rancher-managed namespaces in the local cluster and configures Rancher-managed workloads to use it. Rancher automatically configures new and existing downstream clusters to point to the registry. All Rancher system images across all clusters then pull from your private registry.

For details on how Rancher works with authenticated default registries, see Authenticated Private Registries.

Reconfiguring registry details globally can trigger the redeployment of system components in the local cluster and downstream clusters that do not define cluster-level registry configurations. This can temporarily prevent access to downstream clusters through the Rancher UI.

Configure a Cluster Level Private Registry

In addition to global registry configurations, Rancher supports cluster-scoped registry configurations. Specify registry details in Advanced Options when creating or updating a cluster.

Reconfiguring registry details on an existing cluster can trigger the redeployment of system components in that cluster. This can temporarily prevent access to the cluster through the Rancher UI.

Using a Cluster Level Private Registry with Provisioned Clusters

Select ☰ > Cluster Management.
On the Clusters* page, click Create.
Choose a cluster type.
In Cluster Configuration, select the Registries tab.
Select Enable cluster-scoped container registry for Rancher system container images.
Enter the registry hostname.
Optional: Under Authentication, select Create an HTTP Basic Auth Secret and enter the credentials.
Click Create.

Result: The new cluster pulls images from the private registry.

Follow this same process when updating an existing cluster configuration.

Namespaced Private Registry with SUSE® Rancher Prime: RKE2 Downstream Clusters

Most private registries should work, by default, with RKE2 downstream clusters.

However, you’ll need to do some additional steps if you’re trying to set a namespaced private registry whose URL is formated like this: website/subdomain:portnumber.

Select ☰ > Cluster Management.
Find the RKE2 cluster in the list and click ⋮ >Edit Config.
From the Cluster config menu, select Registries.
In the Registries pane, select the Configure advanced containerd mirroring and registry authentication options option.
In the text fields under Mirrors, enter the Registry Hostname and Mirror Endpoints.
Click Save.
Repeat as necessary for each downstream RKE2 cluster.

Configure a Private Registry with Credentials when Creating a Cluster

Select ☰ > Cluster Management.
On the Clusters page, click Create.
Choose a cluster type.
In the Cluster Configuration go to the Registries tab.
Check the box next to Enable cluster scoped container registry for Rancher system container images.
Enter the registry hostname.
Under Authentication select Create a HTTP Basic Auth Secret and fill in the credential fields.
Click Create.

Result: The new cluster pulls images from the private registry. You can change this setting later by editing the cluster configuration.

Configure a Private Registry with Credentials When Importing a Cluster

Select ☰ > Cluster Management.
On the Clusters page, click Import Existing.
Choose a cluster type.
Select the Registries tab.
Select Enable cluster-scoped container registry for Rancher system container images.
Enter the registry hostname.
Optional: Select an image pull secret to authenticate with the registry.
Click Create.

Working with Private Registry Credentials

When working with private registries, it is important to ensure that any secrets created for these registries are properly backed up. When you add a private registry credential secret through the Rancher GUI and select Create a HTTP Basic Auth Secret, the secret is included in backup operations using Rancher Backups.

However, if you create a credential secret outside of the Rancher GUI, such as by using kubectl or Terraform, you must add the fleet.cattle.io/managed=true label to indicate that the secret should be included in backups created by Rancher Backups.

For example, if you have a custom private registry named "my-private-registry" and create a secret called "my-reg-creds" for it, apply the fleet.cattle.io/managed=true label to this secret. This ensures that your backup process captures the secret, providing easy restoration if needed.

By following this guidance, you can ensure that all of your private registry credentials are backed up and easily accessible in the event of a restore or migration.