Setting up the Advanced Cluster Management add-on (select regions only)

Before you begin

Review the following prerequisite steps and information before you install the ACM add-on.

1. Review the ACM plan types and decide which plan you want to use. Note that for ACM for Virtualization, it is recommended that your managed clusters run bare metal worker nodes.
2. Make sure that your clusters meet the following requirements.
   • Your hub cluster must be a VPC cluster with at least 3 worker nodes that run RHCOS and a minimum of 6 VCPU and 64GB RAM. For high availability, make sure that your cluster has at least one worker node per zone across 3 zones.
   • Each managed cluster must have at least 3 worker nodes that run RHCOS and a minimum of 6 VCPU and 64GB RAM.
   • In addition, if you want to use the ACM for Virtualization plan, it is recommended that you use bare metal worker nodes. For the ACM for Kubernetes plan, managed clusters can run either bare metal nodes or VSIs.
3. Review the operators that are automatically installed by the ACM add-on and the optional operators that you can install as enhancements.
4. You must have the Administrator platform access role and the Manager service access role for the cluster in IBM Cloud Kubernetes Service.
5. You must have a VPC cluster with at least 3 worker nodes. Each worker node must have a minimum of 4 CPUs and 16GB RAM. For high availability, make sure that your cluster has at least one worker node per zone across 3 zones.
6. Create a trusted profile on your cluster to use for ACM.
7. For each cluster you want to manage with ACM, you must create a secret on the hub cluster with the managed cluster's access token and server URL. This step can be completed before or after installation. See Preparing secrets for ACM.
8. Install or update the CLI.

Create a trusted profile for ACM

Follow the steps to create a trusted profile to use for ACM.

1. Follow the steps to create a trusted profile. In the Conditions for the profile, be sure to specify the following access.

   • Allow access when Namespace equals kube-system
   • Satellite Service Roles - Satellite Link Administrator, Reader
   • Kubernetes Service Roles - Manager, Editor
   • Billing Service Roles - Reader, Operator

2. After you create your trusted profile, copy the ID from the Trusted profiles page in the console.

3. Create the following secret by using the ID for the trusted profile. Save the following text and enter your credentials. You can follow the steps to create the secret manually or you can use the shell script to automatically create the secret in your cluster.

   IBMCLOUD_AUTHTYPE=pod-identity
   IBMCLOUD_PROFILEID=<TRUSTED-PROFILE-ID>
   

4. Create a secret in your cluster that contains the credentials for the trusted profile. Save the following YAML to a file called ibm-cloud-credentials.yaml. In the ibm-credentials.env: field, enter the ID of trusted profile.

   apiVersion: v1
   data:
     ibm-credentials.env: # Trusted profile ID
   kind: Secret
   metadata:
     name: ibm-cloud-credentials
     namespace: kube-system
   type: Opaque
   

5. Log in to your account. If applicable, target the appropriate resource group. Set the context for your cluster.

6. Create the secret in your cluster.

   kubectl apply -f ibm-cloud-credentials.yaml
   

Preparing secrets for ACM

For each cluster that you want to manage with ACM, you must create a secret on the hub cluster that includes the managed cluster's access token and server URL.

If you want to import managed clusters during the ACM add-on installation process, complete these steps before you begin the installation. If you choose to create the secrets and import managed clusters after the add-on is installed on the hub cluster, you can do so by completing additional steps with the CLI.

Complete the following steps for each cluster that you want to manage.

1. On the cluster that you want to manage with ACM, run the command to find the server URL. In the output, find and note the Master URL value. This is the server URL to reference in the secret. You also use this URL in the following steps.

   ibmcloud oc cluster get -c <cluster_name_or_ID>
   

   Example output.

   NAME:                           mycluster
   ID:                             1234567
   State:                          normal
   Created:                        2025-01-22T19:22:16+0000
   Location:                       dal10
   Master URL:                     https://c100-e.<region>.containers.cloud.ibm.com:<port>
   ...
   

2. Get the token endpoint of the Red Hat OpenShift oauth server. Replace <master_URL> with the URL found in the previous step. Note that the value in the output is not the access token.

   curl <master_URL>/.well-known/oauth-authorization-server | jq -r .token_endpoint
   

   Example output.

   <token_endpoint>/oauth/token
   

3. Log in to the cluster with the endpoint that you previously retrieved. Replace <URL> with the <token_endpoint> of the oauth server that you found in the previous step. In the output, find the <access_token> contained in the Location response. This is the access token to include in the secret.

   Example curl request:

   curl -u 'apikey:<API_key>' -H "X-CSRF-Token: a" '<URL>/oauth/authorize?client_id=openshift-challenging-client&response_type=token' -vvv
   

   Example output. The <access_token> is included in the Location response string.

   < HTTP/1.1 302 Found
   < Cache-Control: no-cache, no-store, max-age=0, must-revalidate
   < Cache-Control: no-cache, no-store, max-age=0, must-revalidate
   < Expires: 0
   < Expires: Fri, 01 Jan 2030 00:00:00 GMT
   < Location: <token_endpoint>/oauth/token/implicit#access_token=<access_token>&expires_in=86400&scope=user%3Afull&token_type=Bearer
   ...
   

4. On the hub cluster, create a secret that contains the cluster access token and server URL. For information on creating secrets, see Working with secrets in the Kubernetes documentation.

   Example secret.

   apiVersion: v1
   kind: Secret
   metadata:
     name: <secret_name>
     namespace: <secret_namespace>  # The namespace that the secret is to be created in
   type: Opaque
   stringData:
     token: <access_token>
     server: <server_url>
   

ACM operators

Review the operators that are automatically installed by the ACM add-on and the optional operators that you can install as enhancements.

Importing managed clusters after ACM is installed

There are several ways to import clusters to manage with ACM. Before you can import a cluster, make sure you have created the required secret for ACM.

All clusters mangaged by ACM must belong to a cluster set. You can create a new cluster set, or you can add clusters to the Default cluster set. If no cluster set is specified, managed clusters are added to the Default option.

Updating or removing a managed cluster

To remove or update managed cluster from an ACM instance, you must edit the managedClusters section of the ACM custom resource on the hub cluster.

1. Run the command to edit the ACM resource.

   oc edit acmhub <resource_name>
   

2. In the managedClusters section of the resource, add the cluster ID, the name of the cluster secret created for ACM, the namespace for the secret, and the action you want to implement for the cluster. See the example below for formatting. For the action, specify, Delete or Update. Note that to delete a cluster, you do not need the secret or the secret namespace.

   The following example deletescluster_id_1 and updates cluster_id_2.

   managedclusters:
     - clusterid: "cluster_id_1"
       action: "Delete"
     - clusterid: "cluster_id_2"
       secretname: "managed-secret-2"
       secretnamespace: "managed-namespace-2" # The namespace that the secret was created in
       action: "Update"  
   

3. Save and apply the changes.

Upgrading the ACM version

Run the command to upgrade the add-on to a new version.

ibmcloud oc cluster addon update acm --cluster <cluster_id> --version <add-on_version>

To check that the add-on updated, list your cluster add-ons. In the output, look for the ACM add-on details.

ibmcloud oc cluster addon ls --cluster <cluster_id>

Deleting the ACM add-on

Follow the steps to delete the ACM add-on.

1. Delete the ACM resource from the hub cluster.

   oc delete acmhub <resource_name>
   

2. After the resource is deleted, remove the ACM add-on. Specify the same cluster ID.

   ibmcloud oc cluster addon disable acm -f --cluster <cluster_id>