### Install Go Dependencies

Source: https://github.com/k0rdent/kcm/blob/main/CONTRIBUTING.md

Navigate into the kcm directory and run this command to install project dependencies.

```bash
go mod tidy
```

--------------------------------

### Install CLI Tools

Source: https://github.com/k0rdent/kcm/blob/main/CONTRIBUTING.md

Run this command to install the necessary command-line interface tools for development.

```bash
make cli-install
```

--------------------------------

### Install KCM using Helm

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Installs the KCM using the Helm chart. Ensure you have `helm` CLI installed and a management cluster ready. The version specified should be the desired KCM version.

```bash
helm install kcm oci://ghcr.io/k0rdent/kcm/charts/kcm --version 1.9.0 -n kcm-system --create-namespace
```

--------------------------------

### Build kcm Binaries

Source: https://github.com/k0rdent/kcm/blob/main/CONTRIBUTING.md

Build the project binaries after installing dependencies.

```bash
make build
```

--------------------------------

### Clone KCM Repository and Check Commands

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Clone the KCM repository and use 'make help' to view available commands for development setup.

```bash
git clone https://github.com/K0rdent/kcm.git && cd kcm
make help # Check available commands
```

--------------------------------

### Describe Cluster Deployment Conditions

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Use `clusterctl describe` to monitor the provisioning process and view conditions. This requires the `clusterctl` CLI to be installed.

```bash
clusterctl describe cluster <clusterdeployment-name> -n <clusterdeployment-namespace> --show-conditions all
```

--------------------------------

### Install KCM Skipping Default Management Object

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Installs KCM using Helm while skipping the automatic creation of the default `Management` object. This allows you to provide a custom `management.yaml` file after installation. Use `--set "controller.createManagement=false"` in your `helm install` command.

```bash
--set "controller.createManagement=false"
```

--------------------------------

### Configure Management Object for KCM Providers

Source: https://context7.com/k0rdent/kcm/llms.txt

Customizes the KCM installation by specifying active CAPI providers and KCM components. This example skips default Management creation and applies a custom one.

```yaml
# management.yaml – custom Management object skipping the auto-created default
apiVersion: k0rdent.mirantis.com/v1beta1
kind: Management
metadata:
  name: kcm
spec:
  release: kcm-1-9-0          # references a Release object
  core:
    kcm:
      config:                  # optional Helm values for the kcm chart
        controller:
          createManagement: true
    capi: {}
  providers:
    - name: cluster-api-provider-aws
    - name: cluster-api-provider-azure
    - name: cluster-api-provider-gcp
    - name: cluster-api-provider-k0sproject-k0smotron
    - name: projectsveltos

---
```

```bash
# Deploy KCM skipping the default Management creation, then apply the custom one
helm install kcm oci://ghcr.io/k0rdent/kcm/charts/kcm \
  --version 1.9.0 \
  -n kcm-system \
  --create-namespace \
  --set="controller.createManagement=false"

kubectl create -f management.yaml

# Check overall readiness and installed provider versions
kubectl get management kcm
# NAME   READY   RELEASE       AGE
# kcm    True    kcm-1-9-0     5m
```

--------------------------------

### Install KCM via Helm

Source: https://context7.com/k0rdent/kcm/llms.txt

Installs KCM using its OCI Helm chart. Ensure your KUBECONFIG is set to the management cluster before running.

```bash
# Set kubeconfig to the management cluster
export KUBECONFIG=<path-to-management-kubeconfig>

# Install KCM into its own namespace
helm install kcm oci://ghcr.io/k0rdent/kcm/charts/kcm \
  --version 1.9.0 \
  -n kcm-system \
  --create-namespace

# Verify the Management object was created and is ready
kubectl get management kcm -o yaml
# status.conditions should show Ready=True once all providers are up
```

--------------------------------

### Install KCM Required CLIs

Source: https://context7.com/k0rdent/kcm/llms.txt

Clone the KCM repository and use the provided Makefile to install necessary command-line interface tools for local development.

```bash
# Clone the repo and install required CLIs (kubectl, helm, clusterctl, kind, etc.)
git clone https://github.com/K0rdent/kcm.git && cd kcm
make cli-install
```

--------------------------------

### Install KCM with Custom Version using Helm

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Installs KCM using Helm, allowing specification of a custom KCM version. Set the KUBECONFIG environment variable to point to your management cluster's kubeconfig file.

```bash
export KUBECONFIG=<path-to-management-kubeconfig>

helm install kcm oci://ghcr.io/k0rdent/kcm/charts/kcm --version <kcm-version> -n kcm-system --create-namespace
```

--------------------------------

### Set AWS Provider Credentials for Development

Source: https://context7.com/k0rdent/kcm/llms.txt

Export AWS credentials as environment variables to configure KCM for local development with an AWS provider. Replace example values with your actual credentials.

```bash
# Set provider credentials (AWS example)
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_REGION=us-east-2
```

--------------------------------

### Inspect ClusterTemplate Default Config

Source: https://context7.com/k0rdent/kcm/llms.txt

Command to retrieve and display the default configuration values exposed by a ClusterTemplate, useful for starting custom configurations.

```bash
kubectl get clustertemplate aws-standalone-cp-1-0-29 -n kcm-system \
  -o jsonpath='{.status.config}' | jq .
```

--------------------------------

### Create Custom Management Object

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Applies a custom `Management` object configuration to KCM after installation, using a `management.yaml` file. Ensure the KUBECONFIG environment variable is set correctly.

```bash
kubectl --kubeconfig <path-to-management-kubeconfig> create -f management.yaml
```

--------------------------------

### Create a Scheduled Management Cluster Backup

Source: https://context7.com/k0rdent/kcm/llms.txt

Configure a scheduled backup for the KCM management cluster using ManagementBackup. This example schedules a nightly backup and enables automatic backups before KCM upgrades. Requires a configured Velero BackupStorageLocation named 's3-backup'.

```yaml
# Scheduled backup every night at 02:00 UTC
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ManagementBackup
metadata:
  name: nightly-backup
spec:
  storageLocation: s3-backup
  schedule: "0 2 * * *"
  performOnManagementUpgrade: true   # auto-backup before KCM upgrades
```

--------------------------------

### AWS Credential and Identity Setup

Source: https://context7.com/k0rdent/kcm/llms.txt

Defines an AWS secret for credentials and a CAPI AWSClusterStaticIdentity resource that references this secret. This allows KCM to manage AWS resources.

```yaml
# --- AWS secret holding access key / secret key
apiVersion: v1
kind: Secret
metadata:
  name: aws-cluster-identity-secret
  namespace: kcm-system
  labels:
    k0rdent.mirantis.com/component: "kcm"
type: Opaque
stringData:
  AccessKeyID: "AKIAIOSFODNN7EXAMPLE"
  SecretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  SessionToken: ""           # leave empty for long-term credentials
---
```

```yaml
# --- CAPI identity that references the secret
apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
kind: AWSClusterStaticIdentity
metadata:
  name: aws-cluster-identity
  namespace: kcm-system
  labels:
    k0rdent.mirantis.com/component: "kcm"
spec:
  secretRef: aws-cluster-identity-secret
  allowedNamespaces: {}      # {} means all namespaces are allowed
---
```

--------------------------------

### Default KCM Management Configuration

Source: https://github.com/k0rdent/kcm/blob/main/README.md

This is the default `Management` object configuration applied during KCM installation. It lists the default providers enabled. This configuration can be customized.

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: Management
metadata:
  name: kcm
spec:
  providers:
  - name: cluster-api-provider-k0sproject-k0smotron
  - name: cluster-api-provider-azure
  - name: cluster-api-provider-vsphere
  - name: cluster-api-provider-aws
  - name: cluster-api-provider-openstack
  - name: cluster-api-provider-docker
  - name: cluster-api-provider-gcp
  - name: cluster-api-provider-ipam
  - name: cluster-api-provider-infoblox
  - name: projectsveltos
  release: kcm-<dashed-kcm-version>
```

--------------------------------

### ClusterDeployment API - AWS

Source: https://context7.com/k0rdent/kcm/llms.txt

The ClusterDeployment resource is used to provision a Kubernetes cluster, with specific examples for AWS.

```APIDOC
## ClusterDeployment API - AWS

### Description
Provision a Kubernetes cluster on AWS. Set `spec.dryRun: true` first to validate configuration without provisioning.

### Usage
```yaml
# --- AWS standalone control-plane cluster
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: my-aws-cluster
  namespace: kcm-system
spec:
  template: aws-standalone-cp-1-0-29
  credential: aws-cluster-identity-cred
  dryRun: false
  propagateCredentials: true  # inject AWS creds into CCM pods
  config:
    region: us-east-2
    controlPlaneNumber: 3
    workersNumber: 2
    publicIP: false
    controlPlane:
      instanceType: m5.xlarge
      iamInstanceProfile: control-plane.cluster-api-provider-aws.sigs.k8s.io
      imageLookup:
        format: "amzn2-ami-hvm*-gp2"
        org: "137112412989"
    worker:
      instanceType: m5.large
      iamInstanceProfile: nodes.cluster-api-provider-aws.sigs.k8s.io
    k0s:
      version: v1.35.1+k0s.1
      network:
        provider: calico
    serviceSpec:
      services:
        - name: ingress-nginx
          namespace: ingress-nginx
          template: ingress-nginx-4-11-0
```

### Operations
```bash
# Apply and monitor
kubectl apply -f cluster.yaml
kubectl get clusterdeployment my-aws-cluster -n kcm-system -w

# Retrieve the managed cluster's kubeconfig
kubectl get secret -n kcm-system my-aws-cluster-kubeconfig \
  -o go-template='{{.data.value|base64decode}}' > my-aws-cluster.kubeconfig

# Describe the full CAPI cluster tree
clusterctl describe cluster my-aws-cluster -n kcm-system --show-conditions all
```

### Example Output
```
# NAME             READY   SERVICES   TEMPLATE                    MESSAGES   AGE
# my-aws-cluster   True    1/1        aws-standalone-cp-1-0-29               12m
```
```

--------------------------------

### Edit Management Object

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Edits the existing `Management` object for KCM directly using `kubectl`. This is an alternative method to customize KCM configuration after installation. Ensure the KUBECONFIG environment variable is set correctly.

```bash
kubectl --kubeconfig <path-to-management-kubeconfig> edit management
```

--------------------------------

### List ClusterTemplates

Source: https://context7.com/k0rdent/kcm/llms.txt

Command to list all available ClusterTemplate resources in the kcm-system namespace.

```bash
kubectl get clustertemplate -n kcm-system
```

--------------------------------

### List Available Cluster Templates

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Run this command to list all available ClusterTemplates in the kcm-system namespace. Ensure your KUBECONFIG is set to the management cluster.

```bash
export KUBECONFIG=<path-to-management-kubeconfig>

kubectl get clustertemplate -n kcm-system
```

--------------------------------

### Run E2E Tests with Non-Hosted Templates

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Execute end-to-end tests locally using non-hosted templates. This command deploys necessary components to a local Kind cluster and pushes images. Ensure KIND_CLUSTER_NAME is set to 'kcm-test'.

```bash
make KIND_CLUSTER_NAME="kcm-test" CLUSTER_DEPLOYMENT_PREFIX="<your-cluster-name-prefix>" GINKGO_LABEL_FILTER="<optional>" REGISTRY_REPO="oci://127.0.0.1:5001/charts" VERSION=1.0.0 IMG=localhost/kcm/controller:1.0.0 IMG_TELEMETRY=localhost/kcm/telemetry:1.0.0 kind-deploy registry-deploy set-kcm-version dev-push test-e2e
```

--------------------------------

### Describe Cluster Deployment

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Use this command to observe the cluster deployment process and check its status. Ensure KUBECONFIG is set correctly.

```bash
export KUBECONFIG=~/.kube/config

./bin/clusterctl describe cluster <clusterdeployment-name> -n kcm-system --show-conditions all
```

--------------------------------

### Declare a Kustomize-backed ServiceTemplate

Source: https://context7.com/k0rdent/kcm/llms.txt

Define an add-on service using `ServiceTemplate` with Kustomize overlays from a Git repository. Specify the deployment type and path.

```yaml
# Kustomize-backed ServiceTemplate from a Git repository
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ServiceTemplate
metadata:
  name: my-kustomize-app-1-0-0
  namespace: kcm-system
spec:
  kustomize:
    remoteSourceSpec:
      git:
        url: https://github.com/my-org/my-app
        ref:
          tag: v1.0.0
    deploymentType: Remote
    path: ./deploy/overlays/production
```

--------------------------------

### Run E2E Tests with Hosted Templates

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Run end-to-end tests locally using hosted templates. This requires a prior CI run to ensure images and charts are available. Substitute placeholders with actual CI versions.

```bash
make KIND_CLUSTER_NAME="kcm-test" CLUSTER_DEPLOYMENT_PREFIX="<your-cluster-name-prefix>" GINKGO_LABEL_FILTER="<optional>" IMG="ghcr.io/k0rdent/kcm/controller-ci:<version-from-ci>" IMG_TELEMETRY="ghcr.io/k0rdent/kcm/telemetry-ci:<version-from-ci>" VERSION=<version-from-ci> REGISTRY_REPO="oci://ghcr.io/k0rdent/kcm/charts-ci" set-kcm-version test-e2e
```

--------------------------------

### Run Unit Tests

Source: https://context7.com/k0rdent/kcm/llms.txt

Execute unit tests for KCM using the provided Makefile.

```bash
# Run unit tests
make test
```

--------------------------------

### Deploy Kind Management Cluster and KCM Controller

Source: https://context7.com/k0rdent/kcm/llms.txt

Use the KCM Makefile to deploy a local 'kind' cluster and the KCM controller. Ensure ClusterDeployment parameters in 'config/dev/aws-clusterdeployment.yaml' are configured.

```bash
# Deploy the kind management cluster + KCM controller
make dev-apply

# Wait for management components to be ready, then apply credentials
make dev-creds-apply
```

--------------------------------

### List Available Upgrades for a Cluster Deployment

Source: https://context7.com/k0rdent/kcm/llms.txt

Retrieve the list of available upgrades for a specific cluster deployment using jsonpath.

```bash
kubectl get clusterdeployment my-aws-cluster -n kcm-system \
  -o jsonpath='{.status.availableUpgrades}'
```

--------------------------------

### Adopt Existing Cluster with KUBECONFIG

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Prepare to adopt an existing cluster by setting the DEV_PROVIDER to 'adopted' and exporting the kubeconfig data as a base64 encoded environment variable.

```bash
export DEV_PROVIDER="adopted"
export KUBECONFIG_DATA=$(cat kubeconfig | base64 -w 0)
```

--------------------------------

### Inspect Current Release

Source: https://context7.com/k0rdent/kcm/llms.txt

Inspect the current release information, including the KCM version and its corresponding component templates.

```bash
kubectl get release
```

```yaml
spec:
  version: 1.9.0
  kcm:
    template: kcm-1-9-0
  capi:
    template: cluster-api-1-9-0
  providers:
    - name: cluster-api-provider-aws
      template: cluster-api-provider-aws-1-9-0
    - name: cluster-api-provider-azure
      template: cluster-api-provider-azure-1-9-0
    ...
```

--------------------------------

### Verify AccessManagement Rules

Source: https://context7.com/k0rdent/kcm/llms.txt

Verify that the AccessManagement rules are applied correctly by inspecting the current status.

```bash
kubectl get accessmanagement kcm -o jsonpath='{.status.current}' | jq .
```

--------------------------------

### Run Linter and Tests

Source: https://github.com/k0rdent/kcm/blob/main/CONTRIBUTING.md

Execute linters and unit/environment tests to ensure code quality.

```bash
make lint test
```

--------------------------------

### Set OpenStack Provider and Credentials for Development

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Configure KCM for OpenStack development cluster deployment using Application Credentials. Specify machine flavors and image names.

```bash
export DEV_PROVIDER="openstack"
export OS_AUTH_URL="YOUR_AUTH_URL"
export OS_AUTH_TYPE="password"
export OS_APPLICATION_CREDENTIAL_ID="YOUR_APP_CREDENTIAL_ID"
export OS_APPLICATION_CREDENTIAL_SECRET="YOUR_APP_CREDENTIAL_SECRET"
export OS_REGION_NAME="YOUR_REGION"
export OS_INTERFACE="YOUR_INTERFACE"
export OS_IDENTITY_API_VERSION="3"
export OPENSTACK_CONTROL_PLANE_MACHINE_FLAVOR="flavor_name_for_control_plane"
export OPENSTACK_NODE_MACHINE_FLAVOR="flavor_name_for_worker_nodes"
export OPENSTACK_IMAGE_NAME="image_name"
```

--------------------------------

### Monitor Cluster Provisioning

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Watch the provisioning status of the cluster. The actual deployment begins only when `spec.dryRun` is disabled in the ClusterDeployment configuration.

```bash
kubectl -n <clusterdeployment-namespace> get cluster <clusterdeployment-name> -o=yaml
```

--------------------------------

### Run E2E Tests for AWS Provider

Source: https://context7.com/k0rdent/kcm/llms.txt

Execute end-to-end tests for the AWS provider using the KCM Makefile. This command deploys necessary components, pushes images, and runs the tests.

```bash
# Run E2E tests (AWS provider example)
make KIND_CLUSTER_NAME="kcm-test" \
     CLUSTER_DEPLOYMENT_PREFIX="my-test" \
     GINKGO_LABEL_FILTER="provider:aws" \
     REGISTRY_REPO="oci://127.0.0.1:5001/charts" \
     VERSION=1.0.0 \
     IMG=localhost/kcm/controller:1.0.0 \
     kind-deploy registry-deploy set-kcm-version dev-push test-e2e
```

--------------------------------

### Apply and Monitor ClusterDeployment

Source: https://context7.com/k0rdent/kcm/llms.txt

Commands to apply a ClusterDeployment configuration and monitor its provisioning status.

```bash
kubectl apply -f cluster.yaml
kubectl get clusterdeployment my-aws-cluster -n kcm-system -w
```

--------------------------------

### Create a One-time Management Cluster Backup

Source: https://context7.com/k0rdent/kcm/llms.txt

Use this ManagementBackup resource to create an on-demand backup of the KCM management cluster state. Ensure a Velero BackupStorageLocation named 'default' is configured.

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ManagementBackup
metadata:
  name: pre-upgrade-backup
spec:
  storageLocation: default    # references a Velero BackupStorageLocation
```

--------------------------------

### Generate Code and Templates

Source: https://github.com/k0rdent/kcm/blob/main/CONTRIBUTING.md

Generate code and templates. Optionally specify base and head commits for diffing.

```bash
make generate-all
```

```bash
make BASE_COMMIT=origin/main HEAD_COMMIT=HEAD generate-all
```

--------------------------------

### Define ClusterDeployment Configuration

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Create a YAML file to define your ClusterDeployment. Substitute placeholders like <cluster-name>, <template-name>, and <credential-name> with your specific values. Enable `dryRun` for validation before actual deployment.

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: <cluster-name>
  namespace: <cluster-namespace>
spec:
  template: <template-name>
  credential: <credential-name>
  dryRun: <true/false>
  config:
    <cluster-configuration>
```

--------------------------------

### Run Cloud Provider E2E Tests

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Execute E2E tests for cloud providers (AWS, Azure) by applying the 'provider:cloud' Ginkgo label filter.

```bash
GINKGO_LABEL_FILTER="provider:cloud"
```

--------------------------------

### List Available Ginkgo Labels

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Execute this command to retrieve a list of all available labels for filtering E2E tests.

```bash
ginkgo labels ./test/e2e
```

--------------------------------

### Distribute Templates and Credentials with AccessManagement

Source: https://context7.com/k0rdent/kcm/llms.txt

Configure AccessManagement to control which templates and credentials are replicated into target namespaces based on labels or lists.

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: AccessManagement
metadata:
  name: kcm
spec:
  accessRules:
    # Give team-a access to AWS templates and their own credentials
    - targetNamespaces:
        list:
          - team-a
      clusterTemplateChains:
        - aws-standalone-cp
        - aws-eks
      serviceTemplateChains:
        - ingress-nginx
        - cert-manager
      credentials:
        - aws-cluster-identity-cred

    # Give all namespaces labelled env=staging access to Docker templates
    - targetNamespaces:
        selector:
          matchLabels:
            env: staging
      clusterTemplateChains:
        - docker-hosted-cp
      credentials:
        - docker-stub-credential
```

--------------------------------

### Set vSphere Environment Variables for Development

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Configure vSphere connection and deployment parameters for development clusters. Variable names correspond to 'ManagementCluster' parameters.

```bash
export VSPHERE_USER="your_username"
export VSPHERE_PASSWORD="your_password"
export VSPHERE_SERVER="your_vcenter_server"
export VSPHERE_THUMBPRINT="your_vcenter_thumbprint"
export VSPHERE_DATACENTER="your_datacenter"
export VSPHERE_DATASTORE="your_datastore"
export VSPHERE_RESOURCEPOOL="your_resource_pool"
export VSPHERE_FOLDER="your_folder"
export VSPHERE_CONTROL_PLANE_ENDPOINT="your_control_plane_ip"
export VSPHERE_VM_TEMPLATE="your_vm_template"
export VSPHERE_NETWORK="your_network"
export VSPHERE_SSH_KEY="your_ssh_public_key"
```

--------------------------------

### Clone kcm Repository

Source: https://github.com/k0rdent/kcm/blob/main/CONTRIBUTING.md

Clone the kcm project repository to your local machine.

```bash
git clone https://github.com/k0rdent/kcm.git
```

--------------------------------

### Run On-Premise Provider E2E Tests

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Run E2E tests for on-premise providers, such as VMWare vSphere, using the 'provider:onprem' Ginkgo label filter. These tests are executed on self-hosted Mirantis runners.

```bash
GINKGO_LABEL_FILTER="provider:onprem"
```

--------------------------------

### Adopt an existing cluster into KCM management

Source: https://context7.com/k0rdent/kcm/llms.txt

Import an existing Kubernetes cluster by base64-encoding its kubeconfig and using the 'adopted-cluster' template.

```bash
# Base64-encode the existing cluster's kubeconfig
export KUBECONFIG_DATA=$(cat existing-cluster.kubeconfig | base64 -w 0)
```

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: adopted-production
  namespace: kcm-system
spec:
  template: adopted-cluster-1-0-4   # or remote-cluster-*
  credential: adopted-credential
  config:
    clusterLabels:
      env: production
```

--------------------------------

### List KCM Credentials

Source: https://context7.com/k0rdent/kcm/llms.txt

Command to list all available KCM Credential resources in the kcm-system namespace.

```bash
kubectl get credential -n kcm-system
```

--------------------------------

### Cleanup Development Environment

Source: https://context7.com/k0rdent/kcm/llms.txt

Clean up resources created during local development. Use provider-specific commands like 'make dev-aws-nuke' or 'make dev-azure-nuke', and uninstall KCM Helm release.

```bash
# Cleanup
make dev-azure-nuke   # or dev-aws-nuke
helm uninstall kcm -n kcm-system
kubectl delete ns kcm-system
```

--------------------------------

### Set EKS Provider for Development

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Set the DEV_PROVIDER environment variable to 'eks' to configure KCM for EKS development cluster deployment.

```bash
export DEV_PROVIDER="eks"
```

--------------------------------

### Describe Cluster

Source: https://context7.com/k0rdent/kcm/llms.txt

Command to describe the full Cluster API cluster tree, including conditions.

```bash
clusterctl describe cluster my-aws-cluster -n kcm-system --show-conditions all
```

--------------------------------

### Set Azure Environment Variables for Development

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Configure Azure service principal credentials for deploying development clusters on Azure. Ensure all required variables are set before deployment.

```bash
export AZURE_SUBSCRIPTION_ID="YOUR_SUBSCRIPTION_ID"
export AZURE_TENANT_ID="YOUR_TENANT_ID"
export AZURE_CLIENT_ID="YOUR_CLIENT_ID"
export AZURE_CLIENT_SECRET="YOUR_CLIENT_SECRET"
```

--------------------------------

### Deploy Managed Cluster on AWS

Source: https://context7.com/k0rdent/kcm/llms.txt

Deploy a managed cluster on AWS using the KCM Makefile. Set the DEV_PROVIDER environment variable to 'aws' or another supported provider. This command initiates the cluster provisioning process.

```bash
# Deploy the managed cluster on AWS (change DEV_PROVIDER for other providers)
export DEV_PROVIDER=aws   # or azure, gcp, vsphere, openstack, etc.
make dev-mcluster-apply
```

--------------------------------

### Run Controller E2E Tests

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

This command runs E2E tests specifically for the controller component using the 'controller' Ginkgo label filter. These tests execute regardless of other E2E test label configurations.

```bash
GINKGO_LABEL_FILTER="controller"
```

--------------------------------

### Verify Template Validity

Source: https://context7.com/k0rdent/kcm/llms.txt

Check if a specific service template is valid.

```bash
kubectl get servicetemplate ingress-nginx-4-11-0 -n kcm-system
```

--------------------------------

### Create ClusterDeployment Object

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Apply the ClusterDeployment configuration to your cluster using kubectl create.

```bash
kubectl create -f clusterdeployment.yaml
```

--------------------------------

### Perform Cluster Upgrade

Source: https://context7.com/k0rdent/kcm/llms.txt

Perform a cluster upgrade by patching the cluster deployment to reference a new template version.

```bash
kubectl patch clusterdeployment my-aws-cluster -n kcm-system \
  --type merge -p '{"spec":{"template":"aws-standalone-cp-1-0-29"}}'
```

--------------------------------

### Set AWS Environment Variables for Development

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Configure AWS credentials and region for deploying development clusters on AWS. 'AWS_SESSION_TOKEN' is required for temporary credentials, and 'AWS_REGION' defaults to 'us-east-2' if not specified.

```bash
# Required
export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_ACCESS_KEY"

# Optional
export AWS_SESSION_TOKEN="YOUR_SESSION_TOKEN"
export AWS_REGION="us-east-2"
```

--------------------------------

### Declare a Helm-backed ServiceTemplate

Source: https://context7.com/k0rdent/kcm/llms.txt

Define an add-on service using `ServiceTemplate` with Helm chart specifications. Enforces Kubernetes version compatibility using `k8sConstraint`.

```yaml
# Helm-backed ServiceTemplate from the default kcm-templates HelmRepository
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ServiceTemplate
metadata:
  name: ingress-nginx-4-11-0
  namespace: kcm-system
spec:
  helm:
    chartSpec:
      chart: ingress-nginx
      version: "4.11.0"
      sourceRef:
        kind: HelmRepository
        name: kcm-templates
  k8sConstraint: ">=1.28.0"
```

--------------------------------

### Create Azure ClusterDeployment

Source: https://context7.com/k0rdent/kcm/llms.txt

Provisions an Azure standalone control-plane Kubernetes cluster with k0s. Requires specifying location, subscription ID, and VM sizes.

```yaml
# Azure standalone control-plane with k0s
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: my-azure-cluster
  namespace: kcm-system
spec:
  template: azure-standalone-cp-1-0-30
  credential: azure-cluster-identity-cred
  config:
    location: eastus
    subscriptionID: "00000000-0000-0000-0000-000000000000"
    controlPlaneNumber: 3
    workersNumber: 2
    controlPlane:
      vmSize: Standard_D4s_v3
    worker:
      vmSize: Standard_D2s_v3
    k0s:
      version: v1.35.1+k0s.1
```

--------------------------------

### Upgrade KCM Version

Source: https://context7.com/k0rdent/kcm/llms.txt

Upgrade KCM by patching the Management resource to reference a new Release.

```bash
kubectl patch management kcm --type merge \
  -p '{"spec":{"release":"kcm-1-10-0"}}'
```

--------------------------------

### AccessManagement API

Source: https://context7.com/k0rdent/kcm/llms.txt

The AccessManagement API, a cluster-scoped singleton, controls the replication of ClusterTemplateChains, ServiceTemplateChains, and Credentials into target namespaces, facilitating multi-tenant cluster provisioning.

```APIDOC
## AccessManagement API

### Description

The cluster-scoped singleton `AccessManagement` (name: `kcm`) controls which `ClusterTemplateChain`s, `ServiceTemplateChain`s, and `Credential`s are replicated into target namespaces, enabling multi-tenant cluster provisioning.

### Resource Definition

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: AccessManagement
metadata:
  name: kcm
spec:
  accessRules:
    # Give team-a access to AWS templates and their own credentials
    - targetNamespaces:
        list:
          - team-a
      clusterTemplateChains:
        - aws-standalone-cp
        - aws-eks
      serviceTemplateChains:
        - ingress-nginx
        - cert-manager
      credentials:
        - aws-cluster-identity-cred

    # Give all namespaces labelled env=staging access to Docker templates
    - targetNamespaces:
        selector:
          matchLabels:
            env: staging
      clusterTemplateChains:
        - docker-hosted-cp
      credentials:
        - docker-stub-credential
```

### Usage Example

Verify the rules are applied:
```bash
kubectl get accessmanagement kcm -o jsonpath='{.status.current}' | jq .
```
```

--------------------------------

### Release API

Source: https://context7.com/k0rdent/kcm/llms.txt

A Release is a cluster-scoped manifest that pins a KCM version and its corresponding component templates. It records which Helm chart templates align with a specific KCM release.

```APIDOC
## Release API

### Description

A `Release` is a cluster-scoped, version-stamped manifest that records which Helm chart templates correspond to a given KCM release. `Management.spec.release` points to a `Release` by name. KCM ships one `Release` object per published version.

### Resource Definition

```yaml
# Example Release object
apiVersion: k0rdent.mirantis.com/v1beta1
kind: Release
metadata:
  name: kcm-1-9-0
spec:
  version: 1.9.0
  kcm:
    template: kcm-1-9-0
  capi:
    template: cluster-api-1-9-0
  providers:
    - name: cluster-api-provider-aws
      template: cluster-api-provider-aws-1-9-0
    - name: cluster-api-provider-azure
      template: cluster-api-provider-azure-1-9-0
```

### Usage Examples

Inspect the current release:
```bash
kubectl get release
# NAME          READY   AGE
# kcm-1-9-0    true    2d
```

Get detailed release information:
```bash
kubectl get release kcm-1-9-0 -o yaml
```

Upgrade KCM by updating the Management resource to reference a new Release:
```bash
kubectl patch management kcm --type merge \
  -p '{"spec":{"release":"kcm-1-10-0"}}'
# KCM controller rolls out the new provider versions; status.release updates
```
```

--------------------------------

### Define Allowed Upgrade Paths with ClusterTemplateChain

Source: https://context7.com/k0rdent/kcm/llms.txt

Define allowed upgrade paths for cluster templates. This specifies which template versions are available and the permitted upgrade sequences.

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterTemplateChain
metadata:
  name: aws-standalone-cp
  namespace: kcm-system
spec:
  supportedTemplates:
    - name: aws-standalone-cp-1-0-27
      availableUpgrades:
        - name: aws-standalone-cp-1-0-28
        - name: aws-standalone-cp-1-0-29
    - name: aws-standalone-cp-1-0-28
      availableUpgrades:
        - name: aws-standalone-cp-1-0-29
    - name: aws-standalone-cp-1-0-29   # latest, no further upgrades defined
```

--------------------------------

### Check MultiClusterService Deployment Status

Source: https://context7.com/k0rdent/kcm/llms.txt

Verify the deployment status of a MultiClusterService across all matching clusters.

```bash
kubectl get multiclusterservice platform-observability
```

```bash
kubectl get multiclusterservice platform-observability -o jsonpath='{.status.matchingClusters}'
```

--------------------------------

### Deploy Services to Many Clusters with MultiClusterService

Source: https://context7.com/k0rdent/kcm/llms.txt

Use MultiClusterService to deploy specified services to clusters matching the clusterSelector. Configure service details, templates, and Helm options.

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: MultiClusterService
metadata:
  name: platform-observability
spec:
  clusterSelector:
    matchLabels:
      environment: production       # targets all prod ClusterDeployments
  serviceSpec:
    services:
      - name: prometheus-stack
        namespace: monitoring
        template: kube-prometheus-stack-67-2-0
        values: |
          grafana:
            enabled: true
          alertmanager:
            enabled: true
        helmOptions:
          wait: true
          timeout: 10m0s
      - name: loki
        namespace: monitoring
        template: loki-6-6-2
        dependsOn:
          - name: prometheus-stack
            namespace: monitoring
```

--------------------------------

### Deploy a managed EKS cluster on AWS

Source: https://context7.com/k0rdent/kcm/llms.txt

Configure a ClusterDeployment to create a managed EKS cluster on AWS. Set cluster name, region, worker count, and labels.

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: my-eks-cluster
  namespace: kcm-system
spec:
  template: aws-eks-1-0-9
  credential: aws-cluster-identity-cred
  config:
    eksClusterName: my-eks-cluster
    region: us-east-2
    workersNumber: 2
    clusterLabels:
      environment: production
```

--------------------------------

### ClusterTemplateChain / ServiceTemplateChain API

Source: https://context7.com/k0rdent/kcm/llms.txt

Template chains define allowed upgrade paths for templates and specify permitted upgrade sequences. They are used by AccessManagement for distribution and by KCM to populate available upgrades on ClusterDeployment objects.

```APIDOC
## ClusterTemplateChain / ServiceTemplateChain API

### Description

Template chains define which template versions are available and what upgrade sequences are permitted. Used by `AccessManagement` for distribution and by KCM to populate `status.availableUpgrades` on `ClusterDeployment` objects.

### Resource Definition

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterTemplateChain
metadata:
  name: aws-standalone-cp
  namespace: kcm-system
spec:
  supportedTemplates:
    - name: aws-standalone-cp-1-0-27
      availableUpgrades:
        - name: aws-standalone-cp-1-0-28
        - name: aws-standalone-cp-1-0-29
    - name: aws-standalone-cp-1-0-28
      availableUpgrades:
        - name: aws-standalone-cp-1-0-29
    - name: aws-standalone-cp-1-0-29   # latest, no further upgrades defined
```

### Usage Examples

List available upgrades for a running cluster deployment:
```bash
kubectl get clusterdeployment my-aws-cluster -n kcm-system \
  -o jsonpath='{.status.availableUpgrades}'
# ["aws-standalone-cp-1-0-29"]
```

Perform an upgrade by updating the template reference:
```bash
kubectl patch clusterdeployment my-aws-cluster -n kcm-system \
  --type merge -p '{"spec":{"template":"aws-standalone-cp-1-0-29"}}'
```
```

--------------------------------

### Uninstall KCM Helm Release

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Remove the kcm Helm release from the kcm-system namespace.

```bash
helm uninstall kcm -n kcm-system
```

--------------------------------

### Filter E2E Tests with Ginkgo Labels

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Use the GINKGO_LABEL_FILTER environment variable with `make test-e2e` to run specific E2E tests. This helps in isolating tests for providers like AWS.

```bash
make GINKGO_LABEL_FILTER="provider:aws" REST_OF_THE=VARIABLES test-e2e
```

--------------------------------

### Monitor Management Backup Status

Source: https://context7.com/k0rdent/kcm/llms.txt

Use kubectl to monitor the status of ManagementBackup resources and retrieve the phase of the last backup.

```bash
# Monitor backup status
kubectl get managementbackup
# NAME                  LASTBACKUPSTATUS   NEXTBACKUP             AGE
# nightly-backup        Completed          2025-08-15T02:00:00Z   7d
# pre-upgrade-backup    Completed                                  1h

kubectl get managementbackup nightly-backup \
  -o jsonpath='{.status.lastBackup.phase}'
# Completed
```

--------------------------------

### Create AWS ClusterDeployment

Source: https://context7.com/k0rdent/kcm/llms.txt

Provisions an AWS standalone control-plane Kubernetes cluster. Set `spec.dryRun: true` initially to validate configuration without provisioning.

```yaml
# --- AWS standalone control-plane cluster
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: my-aws-cluster
  namespace: kcm-system
spec:
  template: aws-standalone-cp-1-0-29
  credential: aws-cluster-identity-cred
  dryRun: false
  propagateCredentials: true  # inject AWS creds into CCM pods
  config:
    region: us-east-2
    controlPlaneNumber: 3
    workersNumber: 2
    publicIP: false
    controlPlane:
      instanceType: m5.xlarge
      iamInstanceProfile: control-plane.cluster-api-provider-aws.sigs.k8s.io
      imageLookup:
        format: "amzn2-ami-hvm*-gp2"
        org: "137112412989"
    worker:
      instanceType: m5.large
      iamInstanceProfile: nodes.cluster-api-provider-aws.sigs.k8s.io
    k0s:
      version: v1.35.1+k0s.1
      network:
        provider: calico
    serviceSpec:
      services:
        - name: ingress-nginx
          namespace: ingress-nginx
          template: ingress-nginx-4-11-0
```

--------------------------------

### Watch Cluster Provisioning Status

Source: https://context7.com/k0rdent/kcm/llms.txt

Monitor the provisioning status of a managed cluster using 'clusterctl'. This command displays conditions related to the ClusterDeployment.

```bash
# Watch cluster provisioning
./bin/clusterctl describe cluster <clusterdeployment-name> \
  -n kcm-system --show-conditions all
```

--------------------------------

### Nuke AWS Test Resources

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Manually clean up AWS test resources by running the `dev-aws-nuke` target. Ensure CLUSTER_NAME is set if necessary.

```bash
CLUSTER_NAME=example-e2e-test make dev-aws-nuke
```

--------------------------------

### Inspect Controller Logs

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

If errors occur during cluster deployment, inspect the logs of the capa-controller-manager for detailed insights. This is particularly useful for AWS infrastructure issues.

```bash
kubectl logs -n kcm-system deploy/capa-controller-manager
```

--------------------------------

### Nuke Azure Test Resources

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

Manually clean up Azure test resources by running the `dev-azure-nuke` target. This is typically done in CI environments.

```bash
make dev-azure-nuke
```

--------------------------------

### ClusterDeployment API - Azure

Source: https://context7.com/k0rdent/kcm/llms.txt

The ClusterDeployment resource for provisioning a Kubernetes cluster on Azure.

```APIDOC
## ClusterDeployment API - Azure

### Description
Deploy a cluster on Azure AKS or standalone.

### Usage
```yaml
# Azure standalone control-plane with k0s
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: my-azure-cluster
  namespace: kcm-system
spec:
  template: azure-standalone-cp-1-0-30
  credential: azure-cluster-identity-cred
  config:
    location: eastus
    subscriptionID: "00000000-0000-0000-0000-000000000000"
    controlPlaneNumber: 3
    workersNumber: 2
    controlPlane:
      vmSize: Standard_D4s_v3
    worker:
      vmSize: Standard_D2s_v3
    k0s:
      version: v1.35.1+k0s.1
```
```

--------------------------------

### Validate cluster configuration with dry run

Source: https://context7.com/k0rdent/kcm/llms.txt

Perform a dry run of a ClusterDeployment to validate configuration without creating cloud resources. Check status and then disable dryRun to provision.

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: my-aws-cluster
  namespace: kcm-system
spec:
  template: aws-standalone-cp-1-0-29
  credential: aws-cluster-identity-cred
  dryRun: true          # validate only; no cloud resources created
  config:
    region: us-east-2
    controlPlane:
      instanceType: m5.xlarge
    controlPlaneNumber: 3
    workersNumber: 2
```

```bash
# After applying, check if the template validation passed
kubectl get clusterdeployment my-aws-cluster -n kcm-system \
  -o jsonpath='{.status.conditions[?(@.type=="TemplateReady")]}'
# {"type":"TemplateReady","status":"True","reason":"..."}
```

```bash
# When config is valid, disable dryRun to start provisioning
kubectl patch clusterdeployment my-aws-cluster -n kcm-system \
  --type merge -p '{"spec":{"dryRun":false}}'
```

--------------------------------

### Deploy a standalone GCP cluster

Source: https://context7.com/k0rdent/kcm/llms.txt

Use ClusterDeployment to provision a managed Kubernetes cluster on Google Cloud Platform. Specify instance types, images, and network configurations.

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterDeployment
metadata:
  name: my-gcp-cluster
  namespace: kcm-system
spec:
  template: gcp-standalone-cp-1-0-27
  credential: gcp-credential
  config:
    project: my-gcp-project
    region: us-east4
    network:
      name: default
    controlPlaneNumber: 1
    workersNumber: 1
    controlPlane:
      instanceType: n1-standard-2
      image: projects/ubuntu-os-cloud/global/images/ubuntu-2004-focal-v20250213
      publicIP: true
    worker:
      instanceType: n1-standard-2
      image: projects/ubuntu-os-cloud/global/images/ubuntu-2004-focal-v20250213
      publicIP: true
```

--------------------------------

### Create Custom ClusterTemplate

Source: https://context7.com/k0rdent/kcm/llms.txt

Defines a custom ClusterTemplate pointing to a private Helm registry. This allows for versioned Helm charts to declare cluster topologies.

```yaml
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterTemplate
metadata:
  name: my-aws-template-1-0-0
  namespace: kcm-system
spec:
  helm:
    chartSpec:
      chart: my-aws-cluster
      version: "1.0.0"
      sourceRef:
        kind: HelmRepository
        name: my-private-repo
  k8sVersion: "1.35.1"
  providerContracts:
    infrastructure-aws: v1beta2
    control-plane-k0sproject-k0smotron: v1beta1
    bootstrap-k0sproject-k0smotron: v1beta1
```

--------------------------------

### ClusterTemplate API

Source: https://context7.com/k0rdent/kcm/llms.txt

The ClusterTemplate resource defines a versioned cluster topology, typically pointing to a Helm chart.

```APIDOC
## ClusterTemplate API

### Description
Declares a cluster topology as a versioned Helm chart. `ClusterTemplate` is immutable after creation.

### Usage
```yaml
# Example custom ClusterTemplate pointing to a private Helm registry
apiVersion: k0rdent.mirantis.com/v1beta1
kind: ClusterTemplate
metadata:
  name: my-aws-template-1-0-0
  namespace: kcm-system
spec:
  helm:
    chartSpec:
      chart: my-aws-cluster
      version: "1.0.0"
      sourceRef:
        kind: HelmRepository
        name: my-private-repo
  k8sVersion: "1.35.1"
  providerContracts:
    infrastructure-aws: v1beta2
    control-plane-k0sproject-k0smotron: v1beta1
    bootstrap-k0sproject-k0smotron: v1beta1
```

### Operations
```bash
# List all available ClusterTemplates in kcm-system
kubectl get clustertemplate -n kcm-system

# Inspect the default config exposed by a template
kubectl get clustertemplate aws-standalone-cp-1-0-29 -n kcm-system \
  -o jsonpath='{.status.config}' | jq .
```

### Example Output
```
# NAME                         VALID   AGE
# aws-standalone-cp-1-0-29     true    2d
# azure-standalone-cp-1-0-30   true    2d
# gcp-standalone-cp-1-0-27     true    2d
# docker-hosted-cp-1-0-10      true    2d
```
```

--------------------------------

### Retrieve Cluster Kubeconfig

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Fetch the kubeconfig for your deployed cluster. This command retrieves the secret containing the kubeconfig and decodes it.

```bash
kubectl get secret -n kcm-system <clusterdeployment-name>-kubeconfig -o go-template='{{.data.value|base64decode}}' > kubeconfig
```

--------------------------------

### Delete KCM System Namespace

Source: https://github.com/k0rdent/kcm/blob/main/README.md

Remove the kcm-system namespace from your cluster.

```bash
kubectl delete ns kcm-system
```

--------------------------------

### Generated OpenStack cloud.conf

Source: https://github.com/k0rdent/kcm/blob/main/docs/dev.md

This INI format represents the cloud configuration file generated by KCM from a Kubernetes Secret. It's mounted into CCM and CSI pods for managing OpenStack resources.

```ini
[Global]
auth-url=<your_auth_url>
application-credential-id=<your_credential_id>
application-credential-secret=<your_credential_secret>
region=<your_region>
domain-name=<your_domain_name>

[LoadBalancer]
floating-network-id=<your_floating_network_id>

[Networking]
public-network-name=<your_network_name>
```