Skip to main content
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

​
displayName
string
required
Human-readable name displayed in the Rancher UI
​
description
string
Optional description of the cluster’s purpose
​
kubernetesVersion
string
Desired Kubernetes version (for RKE2/K3s clusters)
​
rke2Config
Rke2Config
Configuration for RKE2 clusters. See RKE2 Configuration
​
k3sConfig
K3sConfig
Configuration for K3s clusters
​
importedConfig
ImportedConfig
Configuration for imported clusters
​
kubeConfig
string
Base64-encoded kubeconfig for cluster access
​
aksConfig
AKSClusterConfigSpec
Azure Kubernetes Service configuration
​
eksConfig
EKSClusterConfigSpec
Amazon Elastic Kubernetes Service configuration
​
gkeConfig
GKEClusterConfigSpec
Google Kubernetes Engine configuration
​
enableNetworkPolicy
boolean
default:false
Enable project network isolation using Kubernetes NetworkPolicy
​
localClusterAuthEndpoint
LocalClusterAuthEndpoint
Configuration for local cluster authentication endpoint
​
enabled
boolean
Enable local authentication endpoint
​
fqdn
string
Fully qualified domain name for the endpoint
​
caCerts
string
CA certificates for the endpoint
​
agentEnvVars
array<EnvVar>
Environment variables for the cluster agent
​
clusterAgentDeploymentCustomization
AgentDeploymentCustomization
Customization options for cluster agent deployment
​
fleetAgentDeploymentCustomization
AgentDeploymentCustomization
Customization options for fleet agent deployment
​
defaultPodSecurityAdmissionConfigurationTemplateName
string
Name of the Pod Security Admission configuration template

​
Cluster Status

​
conditions
array<ClusterCondition>
Current state conditions of the cluster
​
driver
string
Cluster driver type: imported, rancherKubernetesEngine, rke2, k3s, AKS, EKS, GKE
​
provider
string
Cloud provider: aws, azure, gcp, vsphere, etc.
​
apiEndpoint
string
Kubernetes API server endpoint URL
​
caCert
string
Base64-encoded CA certificate for the cluster
​
version
version.Info
Kubernetes version information
​
nodeCount
integer
Total number of nodes in the cluster
​
capacity
ResourceList
Total cluster capacity (CPU, memory, pods)
​
allocatable
ResourceList
Allocatable resources in the cluster
​
agentImage
string
Container image used for the cluster agent

​
Cluster Conditions

From pkg/apis/management.cattle.io/v3/cluster_types.go:39
​
Ready
condition
Cluster is ready to serve API requests (healthy when true)
​
Pending
condition
Cluster provisioning is in progress
​
Provisioned
condition
Cluster infrastructure has been provisioned
​
Updated
condition
Cluster configuration has been updated
​
AgentDeployed
condition
Cluster agent has been deployed successfully
​
NoDiskPressure
condition
All nodes have sufficient disk space
​
NoMemoryPressure
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 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
​
config
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
​
imported
Cluster imported from existing infrastructure
​
local
Local cluster running Rancher
​
rancherKubernetesEngine
Legacy RKE1 cluster (deprecated)
​
rke2
RKE2 cluster
​
k3s
K3s lightweight cluster
​
AKS
Azure Kubernetes Service
​
EKS
Amazon Elastic Kubernetes Service
​
GKE
Google Kubernetes Engine

​
Best Practices

Set meaningful displayName and description fields to identify cluster purpose and environment.
Regularly check cluster conditions to ensure health and catch issues early.
Set enableNetworkPolicy: true for production clusters to enable project isolation.
Define resource quotas at the project level to prevent resource exhaustion.
Schedule automated ETCD backups for disaster recovery.

​
Next Steps

Projects

Create multi-tenant projects

Nodes

Manage cluster nodes

Workloads

Deploy applications

Build docs developers (and LLMs) love

Get started for freeTalk to us