Cluster API Resource

The Cluster resource represents a Kubernetes cluster managed by Rancher. Clusters can be provisioned by Rancher (RKE, RKE2, K3s) or imported from existing infrastructure.

Cluster Resource

From pkg/apis/management.cattle.io/v3/cluster_types.go:97

Cluster Spec

string

required

Human-readable name displayed in the Rancher UI

string

Optional description of the cluster’s purpose

string

Desired Kubernetes version (for RKE2/K3s clusters)

Rke2Config

Configuration for RKE2 clusters. See RKE2 Configuration

K3sConfig

Configuration for K3s clusters

ImportedConfig

Configuration for imported clusters

string

Base64-encoded kubeconfig for cluster access

AKSClusterConfigSpec

Azure Kubernetes Service configuration

EKSClusterConfigSpec

Amazon Elastic Kubernetes Service configuration

GKEClusterConfigSpec

Google Kubernetes Engine configuration

boolean

default:false

Enable project network isolation using Kubernetes NetworkPolicy

LocalClusterAuthEndpoint

Configuration for local cluster authentication endpoint

boolean

Enable local authentication endpoint

string

Fully qualified domain name for the endpoint

string

CA certificates for the endpoint

array<EnvVar>

Environment variables for the cluster agent

AgentDeploymentCustomization

Customization options for cluster agent deployment

AgentDeploymentCustomization

Customization options for fleet agent deployment

string

Name of the Pod Security Admission configuration template

Cluster Status

array<ClusterCondition>

Current state conditions of the cluster

string

Cluster driver type: imported, rancherKubernetesEngine, rke2, k3s, AKS, EKS, GKE

string

Cloud provider: aws, azure, gcp, vsphere, etc.

string

Kubernetes API server endpoint URL

string

Base64-encoded CA certificate for the cluster

version.Info

Kubernetes version information

integer

Total number of nodes in the cluster

ResourceList

Total cluster capacity (CPU, memory, pods)

ResourceList

Allocatable resources in the cluster

string

Container image used for the cluster agent

Cluster Conditions

From pkg/apis/management.cattle.io/v3/cluster_types.go:39

condition

Cluster is ready to serve API requests (healthy when true)

condition

Cluster provisioning is in progress

condition

Cluster infrastructure has been provisioned

condition

Cluster configuration has been updated

condition

Cluster agent has been deployed successfully

condition

All nodes have sufficient disk space

condition

All nodes have sufficient memory

Create Cluster

Create a new Kubernetes cluster.

RKE2 Cluster

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @- << 'EOF'
{
  "type": "cluster",
  "name": "production-cluster",
  "displayName": "Production Cluster",
  "description": "Production workload cluster",
  "rke2Config": {
    "kubernetesVersion": "v1.28.5+rke2r1",
    "networking": {
      "plugin": "calico"
    }
  }
}
EOF
  https://rancher-server/v3/clusters

import requests

response = requests.post(
    'https://rancher-server/v3/clusters',
    headers={
        'Authorization': f'Bearer {RANCHER_TOKEN}',
        'Content-Type': 'application/json'
    },
    json={
        'type': 'cluster',
        'name': 'production-cluster',
        'displayName': 'Production Cluster',
        'description': 'Production workload cluster',
        'rke2Config': {
            'kubernetesVersion': 'v1.28.5+rke2r1',
            'networking': {
                'plugin': 'calico'
            }
        }
    }
)

cluster = response.json()
print(f"Cluster ID: {cluster['id']}")

Import Existing Cluster

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cluster",
    "name": "imported-prod",
    "displayName": "Imported Production",
    "importedConfig": {
      "kubeConfig": "<base64-encoded-kubeconfig>"
    }
  }' \
  https://rancher-server/v3/clusters

List Clusters

Retrieve all clusters:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/clusters

Filter Clusters

Filter by labels:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  "https://rancher-server/v3/clusters?labelSelector=environment%3Dproduction"

Get Cluster

Retrieve a specific cluster:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/clusters/c-m-abc123

Response Example

{
  "id": "c-m-abc123",
  "type": "cluster",
  "links": {
    "self": "https://rancher-server/v3/clusters/c-m-abc123",
    "nodes": "https://rancher-server/v3/clusters/c-m-abc123/nodes",
    "projects": "https://rancher-server/v3/clusters/c-m-abc123/projects"
  },
  "metadata": {
    "name": "production-cluster",
    "creationTimestamp": "2024-01-01T00:00:00Z"
  },
  "spec": {
    "displayName": "Production Cluster",
    "description": "Production workload cluster",
    "rke2Config": {
      "kubernetesVersion": "v1.28.5+rke2r1"
    }
  },
  "status": {
    "driver": "rke2",
    "provider": "aws",
    "conditions": [
      {
        "type": "Ready",
        "status": "True",
        "lastUpdateTime": "2024-01-01T00:10:00Z"
      }
    ],
    "apiEndpoint": "https://api.cluster.example.com:6443",
    "nodeCount": 5,
    "version": {
      "gitVersion": "v1.28.5"
    }
  }
}

Update Cluster

Update cluster configuration:

curl -X PUT \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Production Cluster - Updated",
    "description": "Updated description"
  }' \
  https://rancher-server/v3/clusters/c-m-abc123

Delete Cluster

Delete a cluster:

curl -X DELETE \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/clusters/c-m-abc123

Deleting a cluster is irreversible and will remove all associated resources.

Cluster Actions

Generate Kubeconfig

Generate a kubeconfig file for cluster access:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/clusters/c-m-abc123?action=generateKubeconfig

string

Base64-encoded kubeconfig file content

Backup ETCD

Create an ETCD snapshot:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/clusters/c-m-abc123?action=backupEtcd

Restore from ETCD Backup

Restore cluster from an ETCD snapshot:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "etcdBackupName": "backup-20240101-000000",
    "restoreRkeConfig": "all"
  }' \
  https://rancher-server/v3/clusters/c-m-abc123?action=restoreFromEtcdBackup

Rotate Certificates

Rotate cluster certificates:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "caCertificates": true,
    "services": ["etcd", "kubelet", "kube-apiserver"]
  }' \
  https://rancher-server/v3/clusters/c-m-abc123?action=rotateCertificates

Cluster Drivers

From pkg/apis/management.cattle.io/v3/cluster_types.go:76

Cluster imported from existing infrastructure

Local cluster running Rancher

Legacy RKE1 cluster (deprecated)

RKE2 cluster

K3s lightweight cluster

Azure Kubernetes Service

Amazon Elastic Kubernetes Service

Google Kubernetes Engine

Best Practices

Use Descriptive Names

Set meaningful displayName and description fields to identify cluster purpose and environment.

Monitor Cluster Conditions

Regularly check cluster conditions to ensure health and catch issues early.

Enable Network Policies

Set enableNetworkPolicy: true for production clusters to enable project isolation.

Configure Resource Quotas

Define resource quotas at the project level to prevent resource exhaustion.

Regular Backups

Schedule automated ETCD backups for disaster recovery.

Next Steps

Projects

Create multi-tenant projects

Nodes

Manage cluster nodes

Workloads

Deploy applications

APIs

Resources

Cloud Providers

Cluster API Resource

Cluster Resource

Cluster Spec

Cluster Status

Cluster Conditions

Create Cluster

RKE2 Cluster

Import Existing Cluster

List Clusters

Filter Clusters

Get Cluster

Response Example

Update Cluster

Delete Cluster

Cluster Actions

Generate Kubeconfig

Backup ETCD

Restore from ETCD Backup

Rotate Certificates

Cluster Drivers

Best Practices

Next Steps

Projects

Nodes

Workloads

​Cluster Resource

​Cluster Spec

​Cluster Status

​Cluster Conditions

​Create Cluster

​RKE2 Cluster

​Import Existing Cluster

​List Clusters

​Filter Clusters

​Get Cluster

​Response Example

​Update Cluster

​Delete Cluster

​Cluster Actions

​Generate Kubeconfig

​Backup ETCD

​Restore from ETCD Backup

​Rotate Certificates

​Cluster Drivers

​Best Practices

​Next Steps

Projects

Nodes

Workloads

Cluster Resource

Cluster Spec

Cluster Status

Cluster Conditions

Create Cluster

RKE2 Cluster

Import Existing Cluster

List Clusters

Filter Clusters

Get Cluster

Response Example

Update Cluster

Delete Cluster

Cluster Actions

Generate Kubeconfig

Backup ETCD

Restore from ETCD Backup

Rotate Certificates

Cluster Drivers

Best Practices

Next Steps