Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 8. Importing a target managed cluster to the hub cluster

You can import clusters from different Kubernetes cloud providers. After you import, the targeted cluster becomes a managed cluster for the Red Hat Advanced Cluster Management for Kubernetes hub cluster. Unless otherwise specified, complete the import tasks anywhere where you can access the hub cluster and the targeted managed cluster.

A hub cluster cannot manage any other hub cluster, but can manage itself. The hub cluster is configured to automatically be imported and self-managed. You do not need to manually import the hub cluster.

However, if you remove a hub cluster and try to import it again, you need to add the local-cluster:true label.

Choose from the following instructions to set up your managed cluster, either from the console or from the CLI:

Required user type or access level: Cluster administrator

After you install Red Hat Advanced Cluster Management for Kubernetes, you are ready to import a cluster to manage. You can import from both the console and the CLI. Follow this procedure to import from the console. You need your terminal for authentication during this procedure.

8.1.1. Prerequisites
Copy link

  • You need a Red Hat Advanced Cluster Management for Kubernetes hub cluster that is deployed. If you are importing bare metal clusters, you must have the hub cluster installed on Red Hat OpenShift Container Platform version 4.6 or later.
  • You need a cluster that you want to manage and Internet connectivity.
  • Install kubectl. To install kubectl, see Install and Set Up kubectl in the Kubernetes documentation.
  • You need the base64 command line tool.
  • If you are importing a cluster that was not created by Red Hat OpenShift Container Platform, you need a multiclusterhub.spec.imagePullSecret defined. This secret might have been created when Red Hat Advanced Cluster Management for Kubernetes was installed. See Installing from the OperatorHub for more information about defining the secret.

  • For importing in a Red Hat OpenShift Dedicated environment:

    • You must have the hub cluster deployed in a Red Hat OpenShift Dedicated environment.
    • The default permission in Red Hat OpenShift Dedicated is dedicated-admin, but that does not contain all of the permissions to create a namespace. You must have cluster-admin permissions to import and manage a cluster with Red Hat Advanced Cluster Management for Kubernetes.

Required user type or access level: Cluster administrator

8.1.2. Importing a cluster
Copy link

You can import existing clusters from the Red Hat Advanced Cluster Management for Kubernetes console for each of the available cloud providers.

Note: A hub cluster cannot manage a different hub cluster. A hub cluster is set up to automatically import and manage itself, so you do not have to manually import a hub cluster to manage itself.

  1. From the navigation menu, select Infrastructure > Clusters.
  2. Click Add a cluster.
  3. Click Import an existing cluster.
  4. Provide a name for the cluster. By default, the namespace is used for the cluster name and namespace.

  5. Optional: Add any Additional labels.

    Note: If you import a Red Hat OpenShift Dedicated cluster and do not specify a vendor by adding a label for vendor=OpenShiftDedicated, or if you add a label for vendor=auto-detect, a managed-by=platform label is automatically added to the cluster. You can use this added label to identify the cluster as a Red Hat OpenShift Dedicated cluster and retrieve the Red Hat OpenShift Dedicated clusters as a group.

  6. Select the import mode that you want to use to identify the cluster that you are importing from the following options:

    • Run import commands manually: Generate import commands that you can copy and run, based on the information that you provided. Click Save import and generate code to generate the command that you use to deploy the open-cluster-management-agent-addon. A confirmation message is displayed.

      1. In the Import an existing cluster window, select Copy command to copy the generated command and token to the clipboard.

        Important: The command contains pull secret information that is copied to each of the imported clusters. Anyone who can access the imported clusters can also view the pull secret information. Consider creating a secondary pull secret at https://cloud.redhat.com/ or create a service account to protect your personal credentials. See Using image pull secrets or Understanding and creating service accounts for more information about pull secrets.

      2. Log in to the managed cluster that you want to import.

      3. For the Red Hat OpenShift Dedicated environment only Complete the following steps:

        1. Create the open-cluster-management-agent and open-cluster-management namespaces or projects on the managed cluster.
        2. Find the klusterlet operator in the OpenShift Container Platform catalog.

        3. Install it in the open-cluster-management namespace or project that you created.

          Important: Do not install the operator in the open-cluster-management-agent namespace.

        4. Extract the bootstrap secret from the import command by completing the following steps:

          1. Generate the import command:

            1. Select Infrastructure > Clusters from the Red Hat Advanced Cluster Management console main navigation.
            2. Select Add a cluster > Import an existing cluster.
            3. Add the cluster information, and select Save import and generate code.
          2. Copy the import command.
          3. Paste the import command into a file that you create named import-command.

          4. Run the following command to insert the content into the new file: 

            cat import-command | awk '{split($0,a,"&&"); print a[3]}' | awk '{split($0,a,"|"); print a[1]}' | sed -e "s/^ echo //" | base64 -d
            Copy to Clipboard Toggle word wrap
          5. Find and copy the secret with the name bootstrap-hub-kubeconfig in the output.
          6. Apply the secret to the open-cluster-management-agent namespace on the managed cluster.

          7. Create the klusterlet resource using the example in the installed operator, the clusterName should be changed the same name as cluster name that was set during the import.

            Note: When the managedcluster resource is successfully registered to the hub, there are two klusterlet operators installed. One klusterlet operator is in the open-cluster-management namespace, and the other is in the open-cluster-management-agent namespace. Multiple operators does not affect the function of the klusterlet.

      4. For cluster imports that are not in the Red OpenShift Dedicated environment Complete the following steps:

        1. If necessary, configure your kubectl commands for your managed cluster.

          See Supported clouds to learn how to configure your kubectl command line interface.

        2. To deploy the open-cluster-management-agent-addon to the managed cluster, run the command and token that you copied.
      5. Select View cluster to view a summary of your cluster in the Overview page.
    • Enter your server URL and API token for the existing cluster: Provide the server URL and API token of the cluster that you are importing.
    • Kubeconfig: Copy and paste the content of the kubeconfig file of the cluster that you are importing.

  7. Optional: Configure the Cluster API address that is on the cluster details page by configuring the URL that is displayed in the table when you run the oc get managedcluster command.

    1. Log in to your hub cluster with an ID that has cluster-admin permissions.

    2. Configure your kubectl for your targeted managed cluster.

      See Supported clouds to learn how to configure your kubectl.

    3. Edit the managed cluster entry for the cluster that you are importing by entering the following command: 

      oc edit managedcluster <cluster-name>
      Copy to Clipboard Toggle word wrap

      Replace cluster-name with the name of the managed cluster.

    4. Add the ManagedClusterClientConfigs section to the ManagedCluster spec in the YAML file, as shown in the following example: 

      spec:
  hubAcceptsClient: true
  managedClusterClientConfigs:
  - url: https://multicloud-console.apps.new-managed.dev.redhat.com
      Copy to Clipboard Toggle word wrap

      Replace the value of the URL with the URL that provides external access to the managed cluster that you are importing.

Your cluster is imported. You can import another by selecting Import another.

8.1.3. Removing an imported cluster
Copy link

Complete the following procedure to remove an imported cluster and the open-cluster-management-agent-addon that was created on the managed cluster.

  1. From the Clusters page, find your imported cluster in the table.
  2. Click Actions > Detach cluster to remove your cluster from management.

Note: If you attempt to detach the hub cluster, which is named local-cluster, be aware that the default setting of disableHubSelfManagement is false. This setting causes the hub cluster to reimport itself and manage itself when it is detached and it reconciles the MultiClusterHub controller. It might take hours for the hub cluster to complete the detachment process and reimport. If you want to reimport the hub cluster without waiting for the processes to finish, you can enter the following command to restart the multiclusterhub-operator pod and reimport faster: 

oc delete po -n open-cluster-management `oc get pod -n open-cluster-management | grep multiclusterhub-operator| cut -d' ' -f1`
Copy to Clipboard Toggle word wrap

You can change the value of the hub cluster to not import automatically by changing the disableHubSelfManagement value to true, as described in Installing while connected online.

8.2. Importing a managed cluster with the CLI
Copy link

After you install Red Hat Advanced Cluster Management for Kubernetes, you are ready to import a cluster to manage. You can import from both the console and the CLI. Follow this procedure to import from the CLI.

Important: A hub cluster cannot manage a different hub cluster. A hub cluster is set up to automatically import and manage itself. You do not have to manually import a hub cluster to manage itself.

However, if you remove a hub cluster and try to import it again, you need to add the local-cluster:true label.

8.2.1. Prerequisites
Copy link

  • You need a Red Hat Advanced Cluster Management for Kubernetes hub cluster that is deployed. If you are importing bare metal clusters, you must have the hub cluster installed on Red Hat OpenShift Container Platform version 4.6 or later.
  • You need a separate cluster that you want to manage and Internet connectivity.
  • You need the Red Hat OpenShift Container Platform CLI version 4.6 or later, to run oc commands. See Getting started with the OpenShift CLI for information about installing and configuring the Red Hat OpenShift CLI, oc.

  • You need to install the Kubernetes CLI, kubectl. To install kubectl, see Install and Set Up kubectl in the Kubernetes documentation.

    Note: Download the installation file for CLI tools from the console.

  • If you are importing a cluster that was not created by Red Hat OpenShift Container Platform, you need a multiclusterhub.spec.imagePullSecret defined. This secret might have been created when Red Hat Advanced Cluster Management for Kubernetes was installed. See Installing from the OperatorHub for more information about defining the secret.

8.2.2. Supported architectures
Copy link

  • Linux (x86_64, s390x, ppc64le)
  • macOS

8.2.3. Prepare for import
Copy link

  1. Log in to your hub cluster. Run the following command: 

    oc login
    Copy to Clipboard Toggle word wrap

  2. Run the following command on the hub cluster to create the namespace. Note: The cluster name that is defined in cluster_name is also used as the cluster namespace in the YAML file and commands: 

    oc new-project ${CLUSTER_NAME}
oc label namespace ${CLUSTER_NAME} cluster.open-cluster-management.io/managedCluster=${CLUSTER_NAME}
    Copy to Clipboard Toggle word wrap

Continue with Importing the cluster.

8.2.4. Importing the cluster
Copy link

Import the cluster by completing one of the following procedures:

  • To use automatic importing, you must create a secret containing either the kubeconfig or the server and token pair of the cluster to import.

    1. Create a YAML file that contains content that is similar to the following template: 

      apiVersion: v1
kind: Secret
metadata:
  name: auto-import-secret
  namespace: <cluster_name>
stringData:
  autoImportRetry: 5
  # If you are using the kubeconfig file, add the following value for the kubeconfig file
  # that has the current context set to the cluster to import:
  kubeconfig: |- <kubeconfig_file>
  # If you are using the token/server pair, add the following two values:
  token: <Token to access the cluster>
  server: <cluster_api_url>
type: Opaque
      Copy to Clipboard Toggle word wrap
    2. Save the file as auto-import-secret.yaml.

    3. Apply the YAML file with the following command: 

      oc apply -f auto-import-secret.yaml
      Copy to Clipboard Toggle word wrap

  • To use the manual import process, complete the following procedure:

    1. Edit the example ManagedCluster with the following sample of YAML: 

      apiVersion: cluster.open-cluster-management.io/v1
kind: ManagedCluster
metadata:
  name: <cluster_name>
  labels:
    cloud: auto-detect
    vendor: auto-detect
spec:
  hubAcceptsClient: true
      Copy to Clipboard Toggle word wrap

      When the values for cloud and vendor are set to auto-detect, Red Hat Advanced Cluster Management detects the cloud and vendor types automatically from the cluster that you are importing. You can optionally replace the values for auto-detect with with the cloud and vendor values for your cluster. See the following example: 

      cloud: Amazon
vendor: OpenShift
      Copy to Clipboard Toggle word wrap
    2. Save the file as managed-cluster.yaml.

    3. Apply the YAML file with the following command: 

      oc apply -f managed-cluster.yaml
      Copy to Clipboard Toggle word wrap

Continue with Importing the klusterlet.

8.2.5. Importing the klusterlet
Copy link

You can create and apply the klusterlet add-on configuration file by completing the following procedure:

  1. Create a YAML file that is similar to the following example: 

    apiVersion: agent.open-cluster-management.io/v1
kind: KlusterletAddonConfig
metadata:
  name: <cluster_name>
  namespace: <cluster_name>
spec:
  clusterName: <cluster_name>
  clusterNamespace: <cluster_name>
  applicationManager:
    enabled: true
  certPolicyController:
    enabled: true
  clusterLabels:
    cloud: auto-detect
    vendor: auto-detect
  iamPolicyController:
    enabled: true
  policyController:
    enabled: true
  searchCollector:
    enabled: true
  version: 2.3.0
    Copy to Clipboard Toggle word wrap
  2. Save the file as klusterlet-addon-config.yaml.

  3. Apply the YAML by running the following command: 

    oc apply -f klusterlet-addon-config.yaml
    Copy to Clipboard Toggle word wrap

    Note: If you import a Red Hat OpenShift Dedicated cluster and do not specify a vendor by adding a label for vendor=OpenShiftDedicated, or if you add a label for vendor=auto-detect, a managed-by=platform label is automatically added to the cluster. You can use this added label to identify the cluster as a Red Hat OpenShift Dedicated cluster and retrieve the Red Hat OpenShift Dedicated clusters as a group.

The ManagedCluster-Import-Controller will generate a secret named ${CLUSTER_NAME}-import. The ${CLUSTER_NAME}-import secret contains the import.yaml that the user applies to a managed cluster to install klusterlet.

Your cluster is now imported.

8.2.6. Removing an imported cluster with the CLI
Copy link

To remove a cluster, run the following command: 

oc delete managedcluster <cluster_name>
Copy to Clipboard Toggle word wrap

Replace cluster_name with the name of the cluster.

Your cluster is now removed.

You can modify the settings of KlusterletAddonConfig to change your configuration using the hub cluster.

The KlusterletAddonConfig controller manages the functions that are enabled and disabled according to the settings in the klusterletaddonconfigs.agent.open-cluster-management.io Kubernetes resource. View the following example of the KlusterletAddonConfig: 

apiVersion: agent.open-cluster-management.io/v1
kind: KlusterletAddonConfig
metadata:
  name: <cluster-name>
  namespace: <cluster-name>
spec:
  clusterName: <cluster-name>
  clusterNamespace: <cluster-name>
  clusterLabels:
    cloud: auto-detect
    vendor: auto-detect
  applicationManager:
    enabled: true
  certPolicyController:
    enabled: true
  iamPolicyController:
    enabled: true
  policyController:
    enabled: true
  searchCollector:
    enabled: false
  version: 2.3.0
Copy to Clipboard Toggle word wrap

8.3.1. Description of klusterlet add-ons settings
Copy link

The following settings can be updated in the klusterletaddonconfigs.agent.open-cluster-management.io Kubernetes resource:

Expand
Table 8.1. Table list of klusterlet add-ons settings
Setting nameValueDescription

applicationmanager

true or false

This controller manages the application subscription lifecycle on the managed cluster.

certPolicyController

true or false

This controller enforces certificate-based policies on the managed cluster.

iamPolicyController

true or false

This controller enforces the IAM-based policy lifecycle on the managed cluster.

policyController

true or false

This controller enforces all other policy rules on the managed cluster.

searchCollector

true or false

This controller is used to periodically push the resource index data back to the hub cluster.

8.3.2. Modify using the console on the hub cluster
Copy link

You can modify the settings of the klusterletaddonconfigs.agent.open-cluster-management.io resource by using the hub cluster. Complete the following steps to change the settings:

  1. Log in to the Red Hat Advanced Cluster Management for Kubernetes console of the hub cluster.
  2. From the header menu of the hub cluster console, select the Search icon.
  3. In the search parameters, enter the following value: kind:klusterletaddonconfigs
  4. Select the endpoint resource that you want to update.
  5. Find the spec section and select Edit to edit the content.
  6. Modify your settings.
  7. Select Save to apply your changes.

You must have access to the cluster-name namespace to modify your settings by using the hub cluster. Complete the following steps:

  1. Log in to the hub cluster.

  2. Enter the following command to edit the resource: 

    kubectl edit klusterletaddonconfigs.agent.open-cluster-management.io <cluster-name> -n <cluster-name>
    Copy to Clipboard Toggle word wrap
  3. Find the spec section.
  4. Modify your settings, as necessary.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top