Problem & Reasoning

• Our control plane components are currently using LabelTopologyZone for anti-affinity, this makes sense where there is a concrete definition for a “zone” as an availability domain, this is true for cloud environments. However, for on-prem environments such as bare-metal or KubeVirt environments, this is not the case. 
• There is a risk of inadvertently charging customers extra due to the deployment of the control plane as a workload, lack of documentation can lead to this being a potential issue and unexpected UX. 
• There is a risk in allowing customers to re-use the management cluster to deploy workloads (that are not control planes). This risk can be mitigated with proper guidance with node labeling.

The above cases can be managed with proper node labeling, but the necessary steps for this are not sufficiently documented or communicated today. Also, these labeling guidelines need to be identified as a prerequisite for using Hosted Control Planes (HCP) in self-managed environments.

Goal

The goal is to develop in-depth and easy-to-understand documentation that instructs customers on how to correctly label their nodes for self-managed environments. This is to:

• Ensure High Availability (HA) and proper workload deployment while avoiding extra charges for customers. 
• Ensure control-planes are well contained, or recommend dedicated management clusters for hosting control planes. 
• This documentation should also clearly state that these labeling steps are a prerequisite for deploying HCP in self-managed environments.

Definition of Done

The Epic will be considered complete when:

1. We have produced documentation that details how to label nodes to avoid the risks highlighted above for self-managed environments.
2. This documentation includes explicit instructions on labeling nodes used for HCP with node-role.kubernetes.io/infra, topology.kubernetes.io/zone (with a possible hostname) for HA, hypershift.openshift.io/hypershift.openshift.io/control-plane: true. Furthermore, it explains how to taint them with hypershift.openshift.io/control-plane to prevent other workloads from scheduling themselves on control-plane (infra nodes).
3. We provide a clear explanation of the implications of each label and taint, to ensure users understand their necessity.
4. The guidelines on how to use zone versus hostname for spread are introduced and explained clearly.
5. A section in the documentation explicitly states that these labelling steps are a prerequisite for using HCP in self-managed environments.
6. The new documentation is integrated into the existing product documentation, ensuring that the information about topologyKey is clear in the self-hosted product documents.

Additional References

• Distribute Hosted Cluster workloads - HyperShift