Importing an IBM Cloud Private cluster

After you install your IBM Cloud Private with IBM Multicloud Manager enabled, configure your file and run cloudctl mc cluster import to create a managed cluster.

Prerequisites
Prepare for import
Create your IBM Multicloud Manager config.yaml file
Importing a cluster
Post-import tasks

Required user type or access level: Cluster administrator

Prerequisites

You must have an IBM Multicloud Manager hub cluster, which is an IBM Cloud Private cluster with multicluster-hub management service enabled and single_cluster_mode set to false. For more details about IBM Cloud Private and setting up your environment, see Configuring IBM Multicloud Manager .
You need a target IBM Cloud Private cluster that you want to import and manage with the hub cluster.

Important: You cannot import a hub cluster. A hub cluster cannot manage another hub cluster.
You must install Docker. To install Docker, see Install Docker .
You need to install the Kubernetes CLI, kubectl. To install kubectl, see Installing the Kubernetes CLI (kubectl).
You must install the IBM Cloud Private CLI, cloudctl. For more information, see Installing the IBM Cloud Private CLI to install the CLI.

Note: Download the installation file for CLI tools from the IBM Cloud Private management console.

Prepare for import

You need to create an <import_config_directory> directory to store your import configuration files.

To learn more about the import command and see [options] that are available, see IBM Cloud Private CLI multicluster commands (mc).

Generating your `kubeconfig` file for the targeted managed cluster

From a terminal, go to your <import_config_directory> directory.
Set the KUBECONFIG environment variable with the following command:
```
export KUBECONFIG=kubeconfig
```
In a browser, as a cluster administrator, log in to the IBM Cloud Private management console for the targeted managed cluster.

Select the user icon , then click Configure client. The cluster configuration details display and resemble the following code:

kubectl config set-cluster {cluster_name} --server=<Cluster Master Host>:<Cluster Master API Port> --insecure-skip-tls-verify=true
kubectl config set-context {cluster_name}-context --cluster={cluster_name}
kubectl config set-credentials {username} --token={token}
kubectl config set-context {cluster_name}-context --user={username} --namespace=default
kubectl config use-context {cluster_name}-context

Click Copy to clipboard to copy the kubectl configuration commands.
Go back to the same terminal from Step 1 and paste the configuration commands. List the files in your directory and confirm that your kubeconfig file was created.

Verify the content of the kubeconfig file. Be sure that you have one value for clusters, one value for contexts, and one value for users. See the following example output:

apiVersion: v1
clusters:
- cluster:
   insecure-skip-tls-verify: true
   server: <targeted-managed cluster-kubernete-api-server>
 name: <cluster_name>
contexts:
- context:
   cluster: <cluster_name>
   namespace: default
   user: <username>
 name: <cluster_name>-context
current-context: <cluster_name>-context
kind: Config
preferences: {}
users:
- name: <username>
 user:
   token:  <authentication token>

Verify that you can connect to your targeted managed cluster with kubectl by using the kubeconfig. Run any kubectl command. If you receive an unable to connect error, delete the file and retry.
Unset the KUBECONFIG environment variable to avoid modifying the kubeconfig file as you proceed. Run the following command:
```
unset KUBECONFIG
```

Create your IBM Multicloud Manager `cluster-import.yaml` configuration file

From a terminal, go to your <import_config_directory> directory.

cloudctl login -a https://<Hub Cluster Master Host>:<Cluster Master API Port> --skip-ssl-validation

Run the following command to create the configuration template, cluster-import.yaml, where <cluster_name> is the name of the cluster resource on the hub and <cluster_namespace> is the namespace of the cluster resources on the hub cluster.
```
cloudctl mc cluster template <cluster_name> -n <cluster_namespace> > cluster-import.yaml
```
Optional: Open your cluster-import.yaml and configure the following section if you are targeting a cluster that does not have access to the public DockerHub. If you have access, skip this step:

For IBM Cloud Private EE, you can use the IBM Cloud Private private Docker registry.
```
inception_image: <cluster_CA_domain>:8500/ibmcom/icp-inception:3.2.0-ee
image_repo: <cluster_CA_domain>:8500/ibmcom
private_registry_enabled: true
docker_username: <username>
docker_password: <password>
```
Configure the following parameters in the cluster-import.yaml file:
- default_admin_user: The cluster administrator username for the target managed cluster
- container_runtime: The container runtime used in the cluster, currently supported options are docker and containerd
See the Multicluster-endpoint settings section of Customizing the cluster with the config.yaml file for more parameters.

You are now ready to import a cluster.

Importing the cluster

From a terminal, go to your <import_config_directory> directory.

cloudctl login -a https://<Cluster Master Host>:<Cluster Master API Port> --skip-ssl-validation

Run the following command to import to the targeted managed cluster:

cloudctl mc cluster import -f <cluster-import.yaml> -K kubeconfig | tee cluster-import.log

Verify that the cluster is successfully imported.
- Log in to your IBM Multicloud Manager hub cluster.
- From the navigation bar, click Clusters.
- Find your new imported managed cluster in the list.
- Ensure that the status is Ready. Depending on environment, it might take a few minutes to see the status.
Note: If the managed cluster cannot access the hub cluster external Kubernetes API server. You can add --kube-host option during cloudctl mc cluster import to override the Kubernetes host and port of the hub cluster. See the following procedure:

Remove the multicluster-endpoint with the following command:
```
 cloudctl mc cluster remove {cluster-name} -K kubeconfig | tee cluster-remove.log
```
Retry the import step by running the import command with the --kube-host option. See the following command:
```
 cloudctl mc cluster import -f <cluster-import.yaml> -K kubeconfig --kube-host https://<hub-api-address>:<hub-api-server-port> | tee cluster-import.log
```

Post-import tasks

Remove credentials

If you completed the optional step 4 in the Create your IBM Multicloud Manager cluster-import.yaml configuration file section to configure your private Docker in your cluster-import.yaml, you need to remove the credentials from the ConfigMap on the hub cluster.

cloudctl login -a https://<Hub Cluster Master Host>:<Cluster Master API Port> --skip-ssl-validation

Edit the bootstrap-config ConfigMap for the targeted managed cluster. Run the following command:
```
kubectl edit configmap -n <cluster_namespace> <cluster_name>-bootstrap-config
```
Remove the private Docker Registry authentication information, as it is displayed in the following example:
```
docker_username: <docker_username>
docker_password: <docker_password>
```
Save and exit.

Enable `multicluster-endpoint` in `config.yaml`

You need to record in your config.yaml file that multucluster-endpoint is enabled.

Use Secure Shell (SSH) to log in to the boot node of your IBM Cloud Private cluster.
Navigate to the /<installation_directory> that you created during the IBM Cloud Private installation process. Note: This is not the directory that you set up to import a cluster.
Open the IBM Cloud Private config.yaml and change the multicluster-endpoint in management_services to enabled, as you see in the following example:
```
management_services:
 multicluster-endpoint: enabled
```
Go to cluster-import.yaml. Find and copy the entire multicluster-endpoint stanza, which you created during the import process.
Return to your IBM Cloud Private config.yaml file and paste the stanza at the end of the file.
Save and exit.