Adopting an Existing Cluster#

Creating a new cluster isn't the only way to use k0rdent. Adopting an existing Kubernetes cluster enables you to bring it under k0rdent's management. This process is useful when you already have a running cluster but want to centralize management and leverage k0rdent's capabilities, such as unified monitoring, configuration, and automation, but you don't want to redeploy your cluster.

To adopt a cluster, k0rdent establishes communication between the management cluster (where kcm is installed) and the target cluster. This requires proper credentials, network connectivity, and a standardized configuration.

Follow these steps to adopt an existing cluster:

Prerequisites

Before you start, make sure you have the following:
- A kubeconfig file for the cluster you want to adopt (this file provides access credentials and configuration details for the cluster).
- A management cluster with k0rdent installed and running. See the installation instructions if you need to set it up.
- Network connectivity between the management cluster and the cluster to be adopted (for example, ensure firewall rules and VPNs allow communication).
Create a Credential

Start by creating a Credential object that includes all required authentication details for your chosen infrastructure provider. Follow the instructions in the Credential System, as well as the specific instructions for your target infrastructure.

Tip

Double-check that your credentials have sufficient permissions to create resources on the target infrastructure.
Configure the management cluster kubeconfig

Set the KUBECONFIG environment variable to the path of your management cluster's kubeconfig file so you can execute commands against the management cluster.

For example:
```
export KUBECONFIG=/path/to/management-cluster-kubeconfig
```

Create the ClusterDeployment YAML Configuration

The ClusterDeployment object is used to define how k0rdent should manage the adopted cluster. Create a YAML file for the ClusterDeployment object, as shown below:

apiVersion: k0rdent.mirantis.com/v1alpha1
kind: ClusterDeployment
metadata:
  name: <CLUSTER_NAME>
  namespace: <NAMESPACE>
spec:
  template: adopted-cluster-<VERSION>
  credential: <CREDENTIAL_NAME>
  dryRun: <BOOLEAN>
  config:
    <CONFIGURATION>

Replace placeholders such as <CLUSTER_NAME>, <NAMESPACE>, <VERSION>, <CREDENTIAL_NAME>, and <CONFIGURATION> with actual values. The dryRun flag is useful for testing the configuration without making changes to the cluster. For more details, see the Dry Run section.

You can also get a list of the available templates with:

kubectl get clustertemplate -n kcm-system

NAME                            VALID
adopted-cluster-0-1-0           true
aws-eks-0-1-0                   true
aws-hosted-cp-0-1-0             true
aws-standalone-cp-0-1-0         true
azure-aks-0-1-0                 true
azure-hosted-cp-0-1-0           true
azure-standalone-cp-0-1-0       true
openstack-standalone-cp-0-1-0   true
vsphere-hosted-cp-0-1-0         true
vsphere-standalone-cp-0-1-0     true

Putting it all together, your YAML would look something like this:

apiVersion: k0rdent.mirantis.com/v1alpha1
kind: ClusterDeployment
metadata:
  name: my-cluster
  namespace: kcm-system
spec:
  template: adopted-cluster-0-1-0
  credential: my-cluster-credential
  dryRun: false
  config: {}

Apply the ClusterDeployment configuration

Once your configuration file is ready, apply it to the management cluster using kubectl:
```
kubectl apply -f clusterdeployment.yaml
```
This step submits the ClusterDeployment object to k0rdent, initiating the adoption process.
Check the Status of the ClusterDeployment Object

To ensure the adoption process is progressing as expected, check the status of the ClusterDeployment object:
```
kubectl -n <namespace> get clusterdeployment.kcm <cluster-name> -o=yaml
```
The output includes the current state and any conditions (for example, errors or progress updates). Review this information to confirm that the adoption is successful.

What's Happening Behind the Scenes?#

When you adopt a cluster, k0rdent performs several actions: 1. It validates the credentials and configuration provided in the ClusterDeployment object. 2. It ensures network connectivity between the management cluster and the adopted cluster. 3. It registers the adopted cluster within the k0rdent system, enabling it to be monitored and managed like any k0rdent-deployed cluster.

This process doesn't change the adopted cluster's existing workloads or configurations. Instead, it enhances your ability to manage the cluster through k0rdent.

Additional Tips#

If you encounter issues, double-check that kubeconfig file you used for the adopted cluster is valid and matches the cluster you're trying to adopt.
Use the dryRun option during the first attempt to validate the configuration without making actual changes.