Deploying a Cluster#

k0rdent is designed to simplify the process of deploying and managing Kubernetes clusters across various cloud platforms. It does this through the use of ClusterDeployment objects, which include all of the information k0rdent needs to know in order to create the cluster you're looking for. This ClusterDeployment system relies on predefined templates and credentials.

A cluster deployment typically involves:

Setting up credentials for the infrastructure provider (for example, AWS, vSphere).
Choosing a template that defines the desired cluster configuration (for example, number of nodes, instance types).
Submitting the configuration for deployment and monitoring the process.

Follow these steps to deploy a standalone Kubernetes cluster tailored to your specific needs:

Create the Credential object

Credentials are essential for k0rdent to communicate with the infrastructure provider (for example, AWS, Azure, vSphere). These credentials enable k0rdent to provision resources such as virtual machines, networking components, and storage.

Credential objects are generally created ahead of time and made available to users, so before you look into creating a new one be sure what you're looking for doesn't already exist. You can see all of the existing Credential objects by querying the management cluster:
```
kubectl get credentials --all-namespaces
```
If the Credential you need doesn't yet exist, go ahead and create it.

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

Note

A Credential may optionally specify the spec.region field. When set, all ClusterDeployment objects that reference this Credential will be deployed to the corresponding regional cluster. Learn more in Creating a Credential in a Region.

Tip

Double-check to make sure that your credentials have sufficient permissions to create resources on the target infrastructure.

Select a Template

Templates in k0rdent are predefined configurations that describe how to set up the cluster. Templates include details such as:

The number and type of control plane and worker nodes
Networking settings
Regional deployment preferences

Templates act as a blueprint for creating a cluster. To see the list of available templates, use the following command:

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

You can then get information on the actual template by describing it, as in:

kubectl describe clustertemplate aws-standalone-cp-1-0-16 -n kcm-system

Create a ClusterDeployment YAML Configuration

The ClusterDeployment object is the main configuration file that defines your cluster's specifications. It includes:
- The template to use
- The credentials for the infrastructure provider
- Optional customizations such as instance types, regions, and networking
Create a ClusterDeployment configuration in a YAML file, following this structure:
```
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: <cluster-name>
  namespace: <kcm-system-namespace>
spec:
  template: <template-name>
  credential: <infrastructure-provider-credential-name>
  dryRun: <"true" or "false" (default: "false")>
  cleanupOnDeletion: <"true" or "false" (default: "false")>
  config:
    <cluster-configuration>
```
You will of course want to replace the placeholders with actual values. (For more information about dryRun see Understanding the Dry Run.) For example, this is a simple AWS infrastructure provider ClusterDeployment:
```
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: my-cluster-deployment
  namespace: kcm-system
spec:
  template: aws-standalone-cp-1-0-16
  credential: aws-credential
  dryRun: false
  config:
    clusterLabels: {}
    region: us-west-2
    controlPlane:
      instanceType: t3.small
      rootVolumeSize: 32
    worker:
      instanceType: t3.small
      rootVolumeSize: 32
```
Note that the .spec.credential value should match the .metadata.name value of a created Credential object.

Tip

If automatic cleanup of potentially orphaned LoadBalancer Services and Storage devices during deletion of the ClusterDeployment object is required, set .spec.cleanupOnDeletion to true. This is a best-effort cleanup: if there is no possibility to acquire a managed cluster's kubeconfig, the cleanup will not happen.
Apply the Configuration

Once the ClusterDeployment configuration is ready, apply it to the k0rdent management cluster:
```
kubectl apply -f clusterdeployment.yaml
```
This step submits your deployment request to k0rdent. If you've set dryRun to true you can observe what would happen. Otherwise, k0rdent will go ahead and begin provisioning the necessary infrastructure.
Verify Deployment Status

After submitting the configuration, verify that the ClusterDeployment object has been created successfully:
```
kubectl -n <namespace> get clusterdeployment.kcm <cluster-name> -o=yaml
```
The output shows the current status and any errors.
Monitor Provisioning

k0rdent will now start provisioning resources (for example, VMs and networks) and setting up the cluster. To monitor this process, run:
```
kubectl -n <namespace> get cluster <cluster-name> -o=yaml
```
Tip

For a detailed view of the provisioning process, use the clusterctl describe command (note that this requires the clusterctl CLI):
```
clusterctl describe cluster <cluster-name> -n <namespace> --show-conditions all
```
Retrieve the Kubernetes Configuration

When provisioning is complete, retrieve the kubeconfig file for the new cluster. This file enables you to interact with the cluster using kubectl:
```
kubectl get secret -n <namespace> <cluster-name>-kubeconfig -o=jsonpath={.data.value} | base64 -d > kubeconfig
```
You can then use this file to access the cluster, as in:
```
export KUBECONFIG=kubeconfig
kubectl get pods -A
```
Store the kubeconfig file securely, as it contains authentication details for accessing the cluster.