Removing the global system-default-registry value

This document (000020658) is provided subject to the disclaimer at the end of this document.


When removing the global system-default-registry setting in order to use a cluster-level private registry with authentication, the order in which you make these changes is important. If you remove the global system-default-registry setting first, this could cause downstream clusters to go into an error state showing the following error in the Rancher UI:
Cluster must have at least one etcd plane host: failed to connect to the following etcd host(s) [IP Address]


Set the private registry at the cluster-level first and wait for the downstream cluster to finish updating before removing the value from the global system-default registry.

If the value for the global system-default-registry was removed first and the downstream cluster is in an error state, the following should resolve the issue:
  • From the Rancher (local) management cluster edit each of the control plane/etcd nodes in the downstream cluster with the following command:
kubectl edit -n <clusterID> <machineID>
  • Locate the nodePlan field, to find the image field and append the proper registry to the start of the value
  • Update the cluster-level private registry


If the global system-default-registry value is removed, the downstream cluster will begin updating and may not be able to pull the rancher/rancher-agent image causing the downstream cluster to not be able to communicate with the local Rancher cluster. Therefore, the downstream cluster should have the proper private registry set at the cluster-level before the global system-default-registry value is removed.

Additional Information

Global registry:
Cluster-level registry:


This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.

  • Document ID:000020658
  • Creation Date: 11-Nov-2022
  • Modified Date:17-Mar-2023
    • SUSE Rancher

< Back to Support Search

For questions or concerns with the SUSE Knowledgebase please contact: tidfeedback[at]

SUSE Support Forums

Get your questions answered by experienced Sys Ops or interact with other SUSE community experts.

Join Our Community

Support Resources

Learn how to get the most from the technical support you receive with your SUSE Subscription, Premium Support, Academic Program, or Partner Program.

SUSE Customer Support Quick Reference Guide SUSE Technical Support Handbook Update Advisories
Support FAQ

Open an Incident

Open an incident with SUSE Technical Support, manage your subscriptions, download patches, or manage user access.

Go to Customer Center