Skip to content

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.

Adopting a 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:

  1. 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).

  2. 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.

  3. 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

  4. 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/v1beta1
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-1-0-1           true
aws-eks-1-0-3                   true
aws-hosted-cp-1-0-16             true
aws-standalone-cp-1-0-16         true
azure-aks-1-0-1                 true
azure-hosted-cp-1-0-19           true
azure-standalone-cp-1-0-17       true
docker-hosted-cp-1-0-4          true
gcp-gke-1-0-6                   true
gcp-hosted-cp-1-0-16             true
gcp-standalone-cp-1-0-15         true
openstack-standalone-cp-1-0-17   true
remote-cluster-1-0-17            true
vsphere-hosted-cp-1-0-15         true
vsphere-standalone-cp-1-0-15     true

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

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

  5. 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.

  6. 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.

Self-Adopting the Management Cluster#

k0rdent makes it easy to manage Kubernetes clusters, but it only manages child clusters represented by a ClusterDeployment. So in order for k0rdent to manage itself, you must adopt the management cluster. Fortunately, because you're using the target cluster's kubeconfig, this is pretty straightforward.

For example, adopting a k0s-based management cluster might look like this:

  1. Get the IP address of the control plane:

    kubectl get nodes -o wide

    NAME             STATUS   ROLES           AGE   VERSION       INTERNAL-IP   EXTERNAL-IP   OS-IMAGE             KERNEL-VERSION   CONTAINER-RUNTIME
ip-172-31-8-77   Ready    control-plane   9d    v1.33.2+k0s   172.31.8.77   <none>        Ubuntu 24.04.2 LTS   6.8.0-1029-aws   containerd://1.7.27

    Because the cluster will be accessing itself, the INTERNAL-IP (in this example, 172.21.8.77), is sufficient.

  2. Edit the kubeconfig:

    Make sure that the kubeconfig file references the IP address, rather than localhost. You can do this by editing the file directly:

    apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: LS0tLS1CR...tLQo=
    server: https://172.21.8.77:6443
  name: local
contexts:
...

  3. Get the base64-encoded kubeconfig:

    base64 /path/to/kubeconfig

    YXBpVmVyc2lvbjogdjEKY2x1c3RlcnM6Ci0gY2x1c3RlcjoKICAgIGNlcnRpZmljYXRlLWF1dGhv
cml0eS1kYXRhOiBMUzB0TFMxQ1JVZEpUaUJEUlZKVVNVWkpRMEZVUlMwdExTMHRDazFKU1VSQlJF
...
dFZjVlphZVVWWlUyMDVlRFF4UVVoMlpYSnhWVGxvQ2kwdExTMHRSVTVFSUZKVFFTQlFVa2xXUVZS
RklFdEZXUzB0TFMwdENnPT0K

  4. Create the Credential to access the cluster:

    Create a file with the Secret and Credential objects, such as adopt-creds.yaml:

    apiVersion: v1
kind: Secret
metadata:
  name: self-adopt-cluster-kubeconfig
  namespace: kcm-system
type: Opaque
data:
  value: <BASE64_KUBECONFIG>
---
apiVersion: k0rdent.mirantis.com/v1beta1
kind: Credential
metadata:
  name: self-adopt-cluster-credential
  namespace: kcm-system
spec:
  description: "Credential For Self Adoption of Management Cluster"
  identityRef:
    apiVersion: v1
    kind: Secret
    name: self-adopt-cluster-kubeconfig
    namespace: kcm-system

    Make sure to remove the line feeds from the encoded kubeconfig.

  5. Add the credential objects:

    kubectl apply -f adopt-creds.yaml

    secret/self-adopt-cluster-kubeconfig created
credential.k0rdent.mirantis.com/self-adopt-cluster-credential created

  6. Define the ClusterDeployment:

    First determine the ClusterTemplate:

    kubectl get ClusterTemplate -n kcm-system

    NAME                            VALID
adopted-cluster-0-2-0           true
adopted-cluster-1-0-0           true
adopted-cluster-1-0-1           true
aws-eks-0-2-0                   true
...

    Create the definition file, such as self-adopt-cluster.yaml:

    apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: self-adopted-mgmt
  namespace: kcm-system
spec:
  template: adopted-cluster-1-0-1
  credential: self-adopt-cluster-credential
  dryRun: False
  config: {}

  7. Add the ClusterDeployment:

    kubectl apply -f self-adopt-cluster.yaml

    clusterdeployment.k0rdent.mirantis.com/self-adopted-mgmt created

  8. Verify the ClusterDeployment:

    kubectl get clusterdeployment -A

    NAMESPACE    NAME                READY   SERVICES   TEMPLATE                MESSAGES          AGE
kcm-system   self-adopted-mgmt   True    0/0        adopted-cluster-1-0-1   Object is ready   14s

Now you can manage the k0rdent management cluster just as you'd manage any other child cluster.

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.