OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Hosted control planes overview

You can deploy OpenShift Container Platform clusters by using two different control plane configurations: standalone or hosted control planes. The standalone configuration uses dedicated virtual machines or physical machines to host the control plane. With hosted control planes for OpenShift Container Platform, you create control planes as pods on a management cluster without the need for dedicated virtual or physical machines for each control plane.

Introduction to hosted control planes

Hosted control planes is available by using a supported version of multicluster engine for Kubernetes Operator on the following platforms:

  • Bare metal by using the Agent provider

  • Non-bare-metal Agent machines, as a Technology Preview feature

  • OpenShift Virtualization

  • Amazon Web Services (AWS)

  • IBM Z

  • IBM Power

The hosted control planes feature is enabled by default.

Architecture of hosted control planes

OpenShift Container Platform is often deployed in a coupled, or standalone, model, where a cluster consists of a control plane and a data plane. The control plane includes an API endpoint, a storage endpoint, a workload scheduler, and an actuator that ensures state. The data plane includes compute, storage, and networking where workloads and applications run.

The standalone control plane is hosted by a dedicated group of nodes, which can be physical or virtual, with a minimum number to ensure quorum. The network stack is shared. Administrator access to a cluster offers visibility into the cluster’s control plane, machine management APIs, and other components that contribute to the state of a cluster.

Although the standalone model works well, some situations require an architecture where the control plane and data plane are decoupled. In those cases, the data plane is on a separate network domain with a dedicated physical hosting environment. The control plane is hosted by using high-level primitives such as deployments and stateful sets that are native to Kubernetes. The control plane is treated as any other workload.

Diagram that compares the hosted control plane model against OpenShift with a coupled control plane and workers

Benefits of hosted control planes

With hosted control planes, you can pave the way for a true hybrid-cloud approach and enjoy several other benefits.

  • The security boundaries between management and workloads are stronger because the control plane is decoupled and hosted on a dedicated hosting service cluster. As a result, you are less likely to leak credentials for clusters to other users. Because infrastructure secret account management is also decoupled, cluster infrastructure administrators cannot accidentally delete control plane infrastructure.

  • With hosted control planes, you can run many control planes on fewer nodes. As a result, clusters are more affordable.

  • Because the control planes consist of pods that are launched on OpenShift Container Platform, control planes start quickly. The same principles apply to control planes and workloads, such as monitoring, logging, and auto-scaling.

  • From an infrastructure perspective, you can push registries, HAProxy, cluster monitoring, storage nodes, and other infrastructure components to the tenant’s cloud provider account, isolating usage to the tenant.

  • From an operational perspective, multicluster management is more centralized, which results in fewer external factors that affect the cluster status and consistency. Site reliability engineers have a central place to debug issues and navigate to the cluster data plane, which can lead to shorter Time to Resolution (TTR) and greater productivity.

Differences between hosted control planes and OpenShift Container Platform

Hosted control planes is a form factor of OpenShift Container Platform. Hosted clusters and the stand-alone OpenShift Container Platform clusters are configured and managed differently. See the following tables to understand the differences between OpenShift Container Platform and hosted control planes:

Cluster creation and lifecycle

OpenShift Container Platform Hosted control planes

You install a standalone OpenShift Container Platform cluster by using the openshift-install binary or the Assisted Installer.

You install a hosted cluster by using the hypershift.openshift.io API resources such as HostedCluster and NodePool, on an existing OpenShift Container Platform cluster.

Cluster configuration

OpenShift Container Platform Hosted control planes

You configure cluster-scoped resources such as authentication, API server, and proxy by using the config.openshift.io API group.

You configure resources that impact the control plane in the HostedCluster resource.

etcd encryption

OpenShift Container Platform Hosted control planes

You configure etcd encryption by using the APIServer resource with AES-GCM or AES-CBC. For more information, see "Enabling etcd encryption".

You configure etcd encryption by using the HostedCluster resource in the SecretEncryption field with AES-CBC or KMS for Amazon Web Services.

Operators and control plane

OpenShift Container Platform Hosted control planes

A standalone OpenShift Container Platform cluster contains separate Operators for each control plane component.

A hosted cluster contains a single Operator named Control Plane Operator that runs in the hosted control plane namespace on the management cluster.

etcd uses storage that is mounted on the control plane nodes. The etcd cluster Operator manages etcd.

etcd uses a persistent volume claim for storage and is managed by the Control Plane Operator.

The Ingress Operator, network related Operators, and Operator Lifecycle Manager (OLM) run on the cluster.

The Ingress Operator, network related Operators, and Operator Lifecycle Manager (OLM) run in the hosted control plane namespace on the management cluster.

The OAuth server runs inside the cluster and is exposed through a route in the cluster.

The OAuth server runs inside the control plane and is exposed through a route, node port, or load balancer on the management cluster.

Updates

OpenShift Container Platform Hosted control planes

The Cluster Version Operator (CVO) orchestrates the update process and monitors the ClusterVersion resource. Administrators and OpenShift components can interact with the CVO through the ClusterVersion resource. The oc adm upgrade command results in a change to the ClusterVersion.Spec.DesiredUpdate field in the ClusterVersion resource.

The hosted control planes update results in a change to the .spec.release.image field in the HostedCluster and NodePools resources. Any changes to the ClusterVersion resource are ignored.

After you update an OpenShift Container Platform cluster, both the control plane and compute machines are updated.

After you update the hosted cluster, only the control plane is updated. You perform node pool updates separately.

Machine configuration and management

OpenShift Container Platform Hosted control planes

The MachineSets resource manages machines in the openshift-machine-api namespace.

The NodePool resource manages machines on the management cluster.

A set of control plane machines are available.

A set of control plane machines do not exist.

You enable a machine health check by using the MachineHealthCheck resource.

You enable a machine health check through the .spec.management.autoRepair field in the NodePool resource.

You enable autoscaling by using the ClusterAutoscaler and MachineAutoscaler resources.

You enable autoscaling through the spec.autoScaling field in the NodePool resource.

Machines and machine sets are exposed in the cluster.

Machines, machine sets, and machine deployments from upstream Cluster CAPI Operator are used to manage machines but are not exposed to the user.

All machine sets are upgraded automatically when you update the cluster.

You update your node pools independently from the hosted cluster updates.

Only an in-place upgrade is supported in the cluster.

Both replace and in-place upgrades are supported in the hosted cluster.

The Machine Config Operator manages configurations for machines.

The Machine Config Operator does not exist in hosted control planes.

You configure machine Ignition by using the MachineConfig, KubeletConfig, and ContainerRuntimeConfig resources that are selected from a MachineConfigPool selector.

You configure the MachineConfig, KubeletConfig, and ContainerRuntimeConfig resources through the config map referenced in the spec.config field of the NodePool resource.

The Machine Config Daemon (MCD) manages configuration changes and updates on each of the nodes.

For an in-place upgrade, the node pool controller creates a run-once pod that updates a machine based on your configuration.

You can modify the machine configuration resources such as the SR-IOV Operator.

You cannot modify the machine configuration resources.

Networking

OpenShift Container Platform Hosted control planes

The Kube API server communicates with nodes directly, because the Kube API server and nodes exist in the same Virtual Private Cloud (VPC).

The Kube API server communicates with nodes through Konnectivity. The Kube API server and nodes exist in a different Virtual Private Cloud (VPC).

Nodes communicate with the Kube API server through the internal load balancer.

Nodes communicate with the Kube API server through an external load balancer or a node port.

Web console

OpenShift Container Platform Hosted control planes

The web console shows the status of a control plane.

The web console does not show the status of a control plane.

You can update your cluster by using the web console.

You cannot update the hosted cluster by using the web console.

The web console displays the infrastructure resources such as machines.

The web console does not display the infrastructure resources.

You can configure machines through the MachineConfig resource by using the web console.

You cannot configure machines by using the web console.
Additional resources

Relationship between hosted control planes, multicluster engine Operator, and RHACM

You can configure hosted control planes by using the multicluster engine for Kubernetes Operator. The multicluster engine is an integral part of Red Hat Advanced Cluster Management (RHACM) and is enabled by default with RHACM. The multicluster engine Operator cluster lifecycle defines the process of creating, importing, managing, and destroying Kubernetes clusters across various infrastructure cloud providers, private clouds, and on-premises data centers.

The multicluster engine Operator is the cluster lifecycle Operator that provides cluster management capabilities for OpenShift Container Platform and RHACM hub clusters. The multicluster engine Operator enhances cluster fleet management and supports OpenShift Container Platform cluster lifecycle management across clouds and data centers.

Cluster life cycle and foundation
Figure 1. Cluster life cycle and foundation

You can use the multicluster engine Operator with OpenShift Container Platform as a standalone cluster manager or as part of a RHACM hub cluster.

A management cluster is also known as the hosting cluster.

You can deploy OpenShift Container Platform clusters by using two different control plane configurations: standalone or hosted control planes. The standalone configuration uses dedicated virtual machines or physical machines to host the control plane. With hosted control planes for OpenShift Container Platform, you create control planes as pods on a management cluster without the need for dedicated virtual or physical machines for each control plane.

RHACM and the multicluster engine Operator introduction diagram
Figure 2. RHACM and the multicluster engine Operator introduction diagram

Discovering multicluster engine Operator hosted clusters in RHACM

If you want to bring hosted clusters to a Red Hat Advanced Cluster Management (RHACM) hub cluster to manage them with RHACM management components, see the instructions in the Red Hat Advanced Cluster Management official documentation.

Versioning for hosted control planes

The hosted control planes feature includes the following components, which might require independent versioning and support levels:

  • Management cluster

  • HyperShift Operator

  • Hosted control planes (hcp) command-line interface (CLI)

  • hypershift.openshift.io API

  • Control Plane Operator

Management cluster

In management clusters for production use, you need multicluster engine for Kubernetes Operator, which is available through OperatorHub. The multicluster engine Operator bundles a supported build of the HyperShift Operator. For your management clusters to remain supported, you must use the version of OpenShift Container Platform that multicluster engine Operator runs on. In general, a new release of multicluster engine Operator runs on the following versions of OpenShift Container Platform:

  • The latest General Availability version of OpenShift Container Platform

  • Two versions before the latest General Availability version of OpenShift Container Platform

The full list of OpenShift Container Platform versions that you can install through the HyperShift Operator on a management cluster depends on the version of your HyperShift Operator. However, the list always includes at least the same OpenShift Container Platform version as the management cluster and two previous minor versions relative to the management cluster. For example, if the management cluster is running 4.17 and a supported version of multicluster engine Operator, the HyperShift Operator can install 4.17, 4.16, 4.15, and 4.14 hosted clusters.

With each major, minor, or patch version release of OpenShift Container Platform, two components of hosted control planes are released:

  • The HyperShift Operator

  • The hcp command-line interface (CLI)

HyperShift Operator

The HyperShift Operator manages the lifecycle of hosted clusters that are represented by the HostedCluster API resources. The HyperShift Operator is released with each OpenShift Container Platform release. The HyperShift Operator creates the supported-versions config map in the hypershift namespace. The config map contains the supported hosted cluster versions.

You can host different versions of control planes on the same management cluster.

Example supported-versions config map object
    apiVersion: v1
    data:
      supported-versions: '{"versions":["4.17"]}'
    kind: ConfigMap
    metadata:
      labels:
        hypershift.openshift.io/supported-versions: "true"
      name: supported-versions
      namespace: hypershift

hosted control planes CLI

You can use the hcp CLI to create hosted clusters. You can download the CLI from multicluster engine Operator. When you run the hcp version command, the output shows the latest OpenShift Container Platform that the CLI supports against your kubeconfig file.

hypershift.openshift.io API

You can use the hypershift.openshift.io API resources, such as, HostedCluster and NodePool, to create and manage OpenShift Container Platform clusters at scale. A HostedCluster resource contains the control plane and common data plane configuration. When you create a HostedCluster resource, you have a fully functional control plane with no attached nodes. A NodePool resource is a scalable set of worker nodes that is attached to a HostedCluster resource.

The API version policy generally aligns with the policy for Kubernetes API versioning.

Updates for hosted control planes involve updating the hosted cluster and the node pools. For more information, see "Updates for hosted control planes".

Control Plane Operator

The Control Plane Operator is released as part of each OpenShift Container Platform payload release image for the following architectures:

  • amd64

  • arm64

  • multi-arch

Additional resources

Glossary of common concepts and personas for hosted control planes

When you use hosted control planes for OpenShift Container Platform, it is important to understand its key concepts and the personas that are involved.

Concepts

hosted cluster

An OpenShift Container Platform cluster with its control plane and API endpoint hosted on a management cluster. The hosted cluster includes the control plane and its corresponding data plane.

hosted cluster infrastructure

Network, compute, and storage resources that exist in the tenant or end-user cloud account.

hosted control plane

An OpenShift Container Platform control plane that runs on the management cluster, which is exposed by the API endpoint of a hosted cluster. The components of a control plane include etcd, the Kubernetes API server, the Kubernetes controller manager, and a VPN.

hosting cluster

See management cluster.

managed cluster

A cluster that the hub cluster manages. This term is specific to the cluster lifecycle that the multicluster engine for Kubernetes Operator manages in Red Hat Advanced Cluster Management. A managed cluster is not the same thing as a management cluster. For more information, see Managed cluster.

management cluster

An OpenShift Container Platform cluster where the HyperShift Operator is deployed and where the control planes for hosted clusters are hosted. The management cluster is synonymous with the hosting cluster.

management cluster infrastructure

Network, compute, and storage resources of the management cluster.

node pool

A resource that manages a set of compute nodes that are associated with a hosted cluster. The compute nodes run applications and workloads within the hosted cluster.

Personas

cluster instance administrator

Users who assume this role are the equivalent of administrators in standalone OpenShift Container Platform. This user has the cluster-admin role in the provisioned cluster, but might not have power over when or how the cluster is updated or configured. This user might have read-only access to see some configuration projected into the cluster.

cluster instance user

Users who assume this role are the equivalent of developers in standalone OpenShift Container Platform. This user does not have a view into OperatorHub or machines.

cluster service consumer

Users who assume this role can request control planes and worker nodes, drive updates, or modify externalized configurations. Typically, this user does not manage or access cloud credentials or infrastructure encryption keys. The cluster service consumer persona can request hosted clusters and interact with node pools. Users who assume this role have RBAC to create, read, update, or delete hosted clusters and node pools within a logical boundary.

cluster service provider

Users who assume this role typically have the cluster-admin role on the management cluster and have RBAC to monitor and own the availability of the HyperShift Operator as well as the control planes for the tenant’s hosted clusters. The cluster service provider persona is responsible for several activities, including the following examples:

  • Owning service-level objects for control plane availability, uptime, and stability

  • Configuring the cloud account for the management cluster to host control planes

  • Configuring the user-provisioned infrastructure, which includes the host awareness of available compute resources