Red Hat Advanced Cluster Management for Kubernetes (RHACM) is a powerful tool that lets you manage multiple OpenShift and Kubernetes clusters from one place. In this beginner-friendly guide, we will walk through installing RHACM version 2.4.x (or higher) on a bare metal OpenShift cluster using the OperatorHub, and then importing an existing cluster for management. The steps are straightforward and use the OpenShift web console for ease of use.

Prerequisites

Before we begin, make sure you have the following:

• OpenShift Cluster (Hub): A running OpenShift Container Platform cluster (bare metal) where RHACM will be installed. RHACM 2.4+ requires OpenShift 4.6 or later on the hub cluster.
• Cluster Admin Access: You should have cluster-admin privileges on the OpenShift hub cluster and on the cluster you plan to import. This is required to install operators and manage clusters.
• CLI Tools: Access to the OpenShift command-line tool (oc) or Kubernetes CLI (kubectl) on your workstation. This is needed to run the import command on the target cluster.
• Managed Cluster: An existing Kubernetes/OpenShift cluster that you want to import, with network connectivity such that it can reach the hub’s API.
• Internet Access: The clusters should be able to pull container images from Red Hat’s registries (or from your mirrored registry if in a restricted network).

Installing the RHACM Operator via OperatorHub

Installing RHACM is done through the OperatorHub in the OpenShift web console. The OperatorHub provides a catalog of operators, including RHACM, which we can easily install. Follow these steps to install the RHACM operator:

1. Navigate to OperatorHub: Log in to the OpenShift Web Console as a cluster administrator. In the left-hand menu, go to Operators > OperatorHub. In the OperatorHub catalog, search for “Advanced Cluster Management”. You should see the Red Hat Advanced Cluster Management for Kubernetes operator listed, as shown above. This is the operator that will install and manage RHACM on your cluster.

2. Install the RHACM Operator: Click the Advanced Cluster Management for Kubernetes operator tile to open its details, then click the Install button. You will be prompted to choose the installation scope and approval strategy. For a standard installation, select the open-cluster-management namespace (the operator will be installed there; if it doesn’t exist, the console will create it) and choose an update approval strategy (either Automatic or Manual). In our example, we used the default namespace and set updates to manual (meaning we would manually approve new versions). After confirming the settings, click Install to deploy the operator. The Operator Lifecycle Manager (OLM) will pull the RHACM operator image and install it. Within a few minutes, the operator’s status should become Installed (you can check under Operators > Installed Operators in the target namespace).

3. Create the MultiClusterHub resource: Once the RHACM operator is installed, there is an additional step required to fully deploy the RHACM components. RHACM uses a custom resource called MultiClusterHub (MCH) as the central orchestrator for all its services. In the OpenShift console, navigate to Operators > Installed Operators and select the Advanced Cluster Management for Kubernetes operator. You’ll see a prompt indicating an operand (the MultiClusterHub) is required. Click the Create MultiClusterHub button (as shown in the screenshot above). In the creation form, you typically only need to provide a name (for example, multiclusterhub) and ensure the namespace is open-cluster-management. You can leave other settings at default for a basic installation. Submit the form to create the MultiClusterHub custom resource.

What does this do? The RHACM operator will now deploy all the necessary components (controllers, APIs, UI, etc.) for the Hub. This includes creating several pods in the open-cluster-management and related namespaces. It may take a few minutes for all pods to come up and reach a Running state. You can monitor the progress under Workloads > Pods in the open-cluster-management namespace, or by running oc get pods -n open-cluster-management on the command line. Wait until the MultiClusterHub status is healthy and all components are ready. Once ready, the RHACM hub (sometimes called the “Hub cluster”) is fully operational. The OpenShift cluster where RHACM is installed is automatically registered as a managed cluster named local-cluster by default (you will notice it listed in the RHACM console without any manual import – this represents the hub itself).

Accessing the ACM Console

After installing RHACM and the MultiClusterHub, you can access the ACM console (also known as Advanced Cluster Management UI) through the OpenShift web console. In OpenShift 4.x, the ACM console is integrated, so you can find it by navigating the menus:

• In the OpenShift console, click on Infrastructure > Clusters (or in some versions, Advanced Cluster Management > Clusters). This opens the ACM Clusters view, where you can see and manage cluster inventory.

When the ACM console opens, you should see a cluster list that includes local-cluster (the hub). Now you are ready to import your external cluster.

Importing an Existing Cluster

One of RHACM’s key features is the ability to import an existing Kubernetes/OpenShift cluster so that it can be managed alongside others. We will import a cluster named managed-cluster. The import process involves generating an import command in the ACM console, then running that command on the cluster to be imported. Here’s how to do it step-by-step:

1. Start the Import Process: In the ACM console (on the Clusters page under Infrastructure), click the Add cluster button and choose Import cluster. (In ACM 2.4+, the console may show a Create cluster dropdown — select Import cluster from the options.) You will be prompted to enter some details for the cluster you want to import. In the Import Cluster wizard, provide a name for the cluster. Enter managed-cluster as the cluster name. You can also add optional labels (for example, to indicate environment or cloud provider), but labels are not required for the import. Once you’ve entered the name (and any labels), proceed to the next step in the wizard.

2. Generate and Copy the Import Command: After naming the cluster, ACM will present you with an import command. Make sure the import mode is set to “Run import commands manually”, which is the default for a regular import. Then click the option to Generate import code (often labeled “Save import and generate code”). The console will display a command that contains a token and instructions for importing the cluster. In our example screenshot above, the console shows a command for OpenShift 4 / Kubernetes 1.16+ clusters, along with a copy-to-clipboard icon. Click the copy icon to copy the entire import command (which includes an embedded secret token) to your clipboard.

The import command is essentially a one-line script that, when run on the managed cluster, will deploy the necessary agents (the klusterlet agent) and register the cluster with the hub. For security, the command is time-limited and tied to the cluster name you provided. Tip: If you ever lose the command or the token expires, you can always regenerate a new import command from the ACM console for that cluster.

3. Run the Import Command on the Managed Cluster: Now, switch to your terminal to run the command on the cluster you are importing. Make sure your kubectl or oc context is set to the managed-cluster (the cluster being imported). You should log in as a cluster-admin on that cluster. Paste the copied command into your terminal and execute it. This command will create the necessary projects and components on the managed cluster to establish a connection back to the hub. For example, it will create the namespaces open-cluster-management-agent and open-cluster-management-agent-addon, deploy the cluster registration agent (klusterlet), and set up other required resources. The output of running the command will look similar to the following:

   $ oc apply -f https://<hub_cluster_address>/cluster-import?cluster=managed-cluster\&token=<...>
   namespace/open-cluster-management-agent created
   namespace/open-cluster-management-agent-addon created
   serviceaccount/klusterlet created
   clusterrolebinding.rbac.authorization.k8s.io/klusterlet created
   deployment.apps/klusterlet created
   secret/bootstrap-hub-kubeconfig created
   ...

(The actual command and output may differ slightly, but the key is that the klusterlet agent and related resources get created on the managed cluster.) This step deploys the open-cluster-management-agent components to your cluster. The agent will reach out to the hub cluster and complete the registration.

4. Verify the Cluster Import: After running the import command, the managed cluster will take a short time to register with the hub. You can verify the progress in a couple of ways:

• On the managed-cluster (target cluster), check that the klusterlet agent pods are running. For example:

$ oc get pods -n open-cluster-management-agent
NAME                                        READY   STATUS    RESTARTS   AGE
klusterlet-578df8f8f5-nxm2s                 1/1     Running   0          1m
work-agent-89c6cfd97-lsk2b                  1/1     Running   0          1m

• The above shows that the klusterlet (registration agent) and work agent pods are running on the managed cluster.
• Back on the hub cluster (ACM console), the new cluster should appear in the cluster list. You might initially see its status as Importing or Pending. Give it a couple of minutes, and then refresh the ACM Clusters page.

5. Completed Import – Check Cluster Status: Once the managed cluster finishes registering, it will show up in the ACM console with a status of Ready (green check mark). In our example (as shown above), the cluster managed-cluster is now listed alongside local-cluster in the ACM console’s cluster list. This indicates that the import was successful – the hub is now actively managing the cluster.

At this point, you have successfully installed RHACM on your hub OpenShift cluster and imported an existing cluster into management. The imported cluster’s details can be viewed by clicking on its name in the ACM console, and from there you can perform various management tasks (like observing its metrics, deploying applications to it, enforcing governance policies, and so on) just as you would for any cluster managed by RHACM.

Conclusion

In this tutorial, we installed Red Hat Advanced Cluster Management for Kubernetes on a bare metal OpenShift cluster using the OperatorHub, and we imported an external cluster named managed-cluster. We went through the process step-by-step: installing the operator, creating the MultiClusterHub instance, accessing the ACM console, and using the provided import command to register a new cluster. RHACM greatly simplifies multi-cluster management by providing a single pane of glass for all your clusters. Now that your setup is complete, you can explore RHACM’s features — from deploying applications across clusters to setting up governance policies and cluster monitoring.

Managing multiple Kubernetes clusters doesn’t have to be intimidating. With RHACM up and running, you are well-equipped to handle clusters at scale in an organized and efficient way.