Chapter 9. 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
9.1. Importing an existing cluster with the console
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.
9.1.1. Prerequisites
- 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.4, or later.
- You need a cluster that you want to manage and Internet connectivity.
-
Install
kubectl
. To installkubectl
, see Install and Set Up kubectl in the Kubernetes documentation.
-
You need the
base64
command line tool.
Required user type or access level: Cluster administrator
9.1.2. Importing a cluster
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.
- From the navigation menu, hover over Automate infrastructure and click Clusters.
- Click Add cluster.
- Click Import an existing cluster.
- Provide a cluster name. By default, the namespace is set to the same value as your cluster name. Best practice: Leave the namespace value and do not edit.
Optional: Click to expand Edit cluster import YAML file and modify the endpoint configuration.
See Table 1. YAML file parameters and descriptions for details about each parameter.
- Optional: After you import, you can add labels by clicking Configure advanced parameters and use these labels to search.
Optional: Configure the
MANAGED CLUSTER URLS
. By configuring theMANAGED CLUSTER URLS
, the URLs display in the table when you run theoc get managedcluster
command.-
If it is not already on, turn on the
YAML
content using the switch in the web console so you can view the content. Add the
manageClusterClientConfigs
section to theManagedCluster
spec in theimport.yaml
file, as shown in the following example:apiVersion: cluster.open-cluster-management.io/v1 kind: ManagedCluster metadata: labels: cloud: auto-detect vendor: auto-detect name: cluster-test name: cluster-test spec: hubAcceptsClient: true managedClusterClientConfigs: - url: https://multicloud-console.apps.new-managed.dev.redhat.com --- apiVersion: agent.open-cluster-management.io/v1 ...
Replace the URL value is the external access URL address of the managed cluster.
-
If it is not already on, turn on the
-
Click Generate Command to retrieve the command to deploy the
open-cluster-management-agent-addon
. - From the Import an existing cluster window, hover and click the Copy command icon to copy the import command and the token that you are provided. You must click the Copy icon to receive the accurate copy. 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 by creating a service account so your personal credentials are not compromised. See Using image pull secrets or Understanding and creating service accounts for more information.
From your terminal, authenticate to your managed cluster. Configure your
kubectl
for your targeted managed cluster.See Supported clouds to learn how to configure your
kubectl
.-
To deploy the
open-cluster-management-agent-addon
to the managed cluster, run the command that you generated and copied from step 8. - Click View cluster to view the Overview page and a summary of your cluster.
Note: You can continue to import more clusters. Click Import another to repeat the process.
9.1.2.1. YAML parameters and descriptions
Table 1: The following table lists the parameters and descriptions that are available in the YAML file:
Parameter | Description | Default value |
---|---|---|
clusterLabels | Provide cluster labels; you can add labels to your file | none |
clusterLabels.cloud | The provider label for your cluster | auto-detect |
clusterLabels.vendor | The Kubernetes vendor label for your cluster | auto-detect |
clusterLabels.environment | The environment label for your cluster | none |
clusterLabels.region | The region where your cluster is set up | none |
applicationManager.enabled | Enables multicluster manager application deployment, deploys subscription controller and deployable controller | true |
searchCollector.enabled | Enables search collection and indexing | true |
policyController.enabled | Enable the Governance and risk dashboard policy feature | true, updateInterval: 15 |
certPolicyController.enabled | Monitors certificate expiration based on distributed policies | true |
iamPolicyController | Monitors identity controls based on distributed policies | true |
serviceRegistry.enabled | Service registry that is used to discover services that are deployed by Application Deployable among managed clusters. | false |
serviceRegistry.dnsSuffix | The suffix of the registry DNS name, which is added to the end of the target clusters dns domain name. | mcm.svc |
serviceRegistry.plugins |
Comma-separated list of enabled plugins. Supported plugins: | kube-service |
version |
Version of | 2.1.0 |
9.1.3. Removing an imported cluster
Complete the following procedure to remove an imported cluster and the open-cluster-management-agent-addon
that was created on the managed cluster.
- From the Clusters page, find your imported cluster in the table.
- 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`
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.
9.2. Importing a managed cluster with the CLI
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.
9.2.1. Prerequisites
- 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.5, 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.3, or later, to run
oc
commands. See Getting started with the CLI for information about installing and configuring the Red Hat OpenShift CLI,oc
. You need to install the Kubernetes CLI,
kubectl
. To installkubectl
, see Install and Set Up kubectl in the Kubernetes documentation.Note: Download the installation file for CLI tools from the console.
9.2.2. Supported architecture
- Linux
- macOS
9.2.3. Prepare for import
Log in to your hub cluster. Run the following command:
oc login
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 file and commands:oc new-project ${CLUSTER_NAME} oc label namespace ${CLUSTER_NAME} cluster.open-cluster-management.io/managedCluster=${CLUSTER_NAME}
Edit the example ManagedCluster with the following sample of YAML:
apiVersion: cluster.open-cluster-management.io/v1 kind: ManagedCluster metadata: name: <cluster_name> spec: hubAcceptsClient: true
-
Save the file as
managed-cluster.yaml
. Apply the YAML file with the following command:
oc apply -f managed-cluster.yaml
Create the klusterlet addon configuration file. Enter the following example YAML:
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.1.0
-
Save the file as
klusterlet-addon-config.yaml
. Apply the YAML. Run the following command:
oc apply -f klusterlet-addon-config.yaml
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.
9.2.4. Importing the klusterlet
Important: The import 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.
Obtain the
klusterlet-crd.yaml
that was generated by the managed cluster import controller.Run the following command:
oc get secret ${CLUSTER_NAME}-import -n ${CLUSTER_NAME} -o jsonpath={.data.crds\\.yaml} | base64 --decode > klusterlet-crd.yaml
Obtain the
import.yaml
that was generated by the managed cluster import controller. Run the following command:oc get secret ${CLUSTER_NAME}-import -n ${CLUSTER_NAME} -o jsonpath={.data.import\\.yaml} | base64 --decode > import.yaml
- Log in to your target managed cluster.
Apply the
klusterlet-crd.yaml
that was generated in step 1. Run the following command:kubectl apply -f klusterlet-crd.yaml
Apply the
import.yaml
file that was generated in step 2. Run the following command:kubectl apply -f import.yaml
Validate the pod status on the target managed cluster. Run the following command:
kubectl get pod -n open-cluster-management-agent
Validate
JOINED
andAVAILABLE
status for your imported cluster. Run the following command from the hub cluster:kubectl get managedcluster ${CLUSTER_NAME}
Addons will be installed after the managed cluster is
AVAILABLE
. Validate the pod status of addons on the target managed cluster. Run the following command:kubectl get pod -n open-cluster-management-agent-addon
9.3. Modifying the klusterlet addons settings of your cluster
You can modify the settings of klusterlet addon
to change your configuration using the hub cluster.
The klusterlet addon
controller manages the functions that are enabled and disabled according to the settings in the klusterletaddonconfigs.agent.open-cluster-management.io
Kubernetes resource.
The following settings can be updated in the klusterletaddonconfigs.agent.open-cluster-management.io
Kubernetes resource:
Setting name | Value |
---|---|
applicationmanager |
|
policyController |
|
searchCollector |
|
certPolicyController |
|
iamPolicyController |
|
9.3.1. Modify using the console on the hub cluster
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:
- Authenticate into the Red Hat Advanced Cluster Management for Kubernetes console of the hub cluster.
- From the main menu of the hub cluster console, select Search.
-
In the search parameters, enter the following value:
kind:klusterletaddonconfigs
- Select the endpoint resource that you want to update.
-
Find the
spec
section and select Edit to edit the content. - Modify your settings.
- Select Save to apply your changes.
9.3.2. Modify using the command line on the hub cluster
You must have access to the <cluster-name> namespace to modify your settings by using the hub cluster. Complete the following steps:
- Authenticate into the hub cluster.
Enter the following command to edit the resource:
kubectl edit klusterletaddonconfigs.agent.open-cluster-management.io <cluster-name> -n <cluster-name>
-
Find the
spec
section. - Modify your settings, as necessary.