Node API Resource

Nodes are the compute infrastructure that runs your Kubernetes workloads. Rancher provides APIs to manage nodes, node pools, and node drivers across different cloud providers.

Node Resource

From pkg/apis/management.cattle.io/v3/machine_types.go:62

Node Spec

displayName

string

Human-readable name for the node

description

string

Optional description of the node

etcd

boolean

Whether this node runs etcd (immutable)

controlPlane

boolean

Whether this node is a control plane node (immutable)

worker

boolean

Whether this node is a worker node (immutable)

nodeTemplateName

string

Reference to the node template used to provision this node

nodePoolName

string

Reference to the node pool this node belongs to

requestedHostname

string

Desired hostname for the node (immutable, required)

customConfig

CustomConfig

Configuration for custom/imported nodes

address

string

IP or FQDN for SSH communication

internalAddress

string

Internal address for component communication

user

string

SSH user for node access

sshKey

string

SSH private key for authentication

desiredNodeTaints

array<Taint>

Taints to apply to the node

desiredNodeUnschedulable

string

Whether the node should be unschedulable

nodeDrainInput

NodeDrainInput

Configuration for draining the node

Node Status

conditions

array<NodeCondition>

Current state conditions of the node

nodeName

string

Name of the node in Kubernetes

requested

ResourceList

Total resources requested on the node

limits

ResourceList

Total resource limits on the node

internalNodeStatus

NodeStatus

Kubernetes node status information

nodeAnnotations

map<string, string>

Annotations applied to the node

nodeLabels

map<string, string>

Labels applied to the node

Node Conditions

From pkg/apis/management.cattle.io/v3/machine_types.go:131

Initialized

condition

Node has been initialized

Provisioned

condition

Node has been provisioned

Updated

condition

Node configuration has been updated

Registered

condition

Node is registered with Kubernetes

Ready

condition

Node is ready to accept workloads

Drained

condition

Node has been drained of workloads

List Nodes

Retrieve all nodes in a cluster:

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

Filter Nodes

Filter by labels:

curl -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  "https://rancher-server/v3/clusters/c-m-abc123/nodes?labelSelector=node-role.kubernetes.io/worker%3Dtrue"

Get Node

Retrieve a specific node:

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

Response Example

{
  "id": "c-m-abc123:m-xyz789",
  "type": "node",
  "metadata": {
    "name": "worker-1",
    "namespace": "c-m-abc123"
  },
  "spec": {
    "displayName": "Worker Node 1",
    "requestedHostname": "worker-1",
    "worker": true,
    "nodePoolName": "np-worker"
  },
  "status": {
    "conditions": [
      {
        "type": "Ready",
        "status": "True"
      }
    ],
    "nodeName": "worker-1",
    "requested": {
      "cpu": "2000m",
      "memory": "4Gi"
    },
    "internalNodeStatus": {
      "addresses": [
        {
          "type": "InternalIP",
          "address": "10.0.1.5"
        }
      ],
      "capacity": {
        "cpu": "4",
        "memory": "8Gi",
        "pods": "110"
      },
      "allocatable": {
        "cpu": "3800m",
        "memory": "7.5Gi",
        "pods": "110"
      }
    }
  }
}

Update Node

Update node configuration:

curl -X PUT \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Worker Node 1 - Updated",
    "desiredNodeTaints": [
      {
        "key": "dedicated",
        "value": "gpu",
        "effect": "NoSchedule"
      }
    ]
  }' \
  https://rancher-server/v3/clusters/c-m-abc123/nodes/m-xyz789

Delete Node

Delete a node from the cluster:

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

Node Actions

Cordon Node

Mark a node as unschedulable:

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

Uncordon Node

Mark a node as schedulable:

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

Drain Node

Drain all pods from a node:

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "force": false,
    "deleteLocalData": false,
    "gracePeriod": 30,
    "ignoreDaemonSets": true,
    "timeout": 300
  }' \
  https://rancher-server/v3/clusters/c-m-abc123/nodes/m-xyz789?action=drain

Node Pools

From pkg/apis/management.cattle.io/v3/machine_types.go:165 Node pools define groups of nodes with identical configurations.

Node Pool Spec

displayName

string

Human-readable name for the node pool

clusterName

string

required

Name of the cluster (immutable, required)

hostnamePrefix

string

required

Prefix for generated hostnames (required)

quantity

integer

default:1

Number of nodes in the pool (default: 1)

etcd

boolean

Nodes run etcd

controlPlane

boolean

Nodes are control plane nodes

worker

boolean

Nodes are worker nodes

nodeTemplateName

string

required

Reference to the node template (required)

nodeLabels

map<string, string>

Labels to apply to all nodes

nodeAnnotations

map<string, string>

Annotations to apply to all nodes

nodeTaints

array<Taint>

Taints to apply to all nodes

drainBeforeDelete

boolean

default:false

Drain nodes before deletion

deleteNotReadyAfterSecs

duration

Delete not-ready nodes after this duration (0 to disable)

Create Node Pool

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "nodePool",
    "clusterName": "c-m-abc123",
    "hostnamePrefix": "worker",
    "quantity": 3,
    "worker": true,
    "nodeTemplateName": "nt-xyz789",
    "nodeLabels": {
      "environment": "production",
      "workload-type": "general"
    },
    "drainBeforeDelete": true
  }' \
  https://rancher-server/v3/nodepools

Scale Node Pool

Update the quantity field:

curl -X PUT \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 5
  }' \
  https://rancher-server/v3/nodepools/c-m-abc123:np-worker

Node Templates

From pkg/apis/management.cattle.io/v3/machine_types.go:17 Node templates define the configuration for provisioning nodes from a cloud provider.

Node Template Spec

displayName

string

Human-readable name for the template

description

string

Description of the template

driver

string

Node driver name (immutable)

cloudCredentialName

string

Reference to cloud credentials

nodeTaints

array<Taint>

Taints to apply to nodes created from this template

Create Node Template

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "nodeTemplate",
    "name": "aws-worker-template",
    "displayName": "AWS Worker Template",
    "driver": "amazonec2",
    "cloudCredentialName": "cc-aws-prod",
    "amazonec2Config": {
      "region": "us-west-2",
      "instanceType": "t3.large",
      "ami": "ami-0c55b159cbfafe1f0",
      "sshUser": "ubuntu",
      "volumeType": "gp3",
      "rootSize": "50"
    }
  }' \
  https://rancher-server/v3/nodetemplates

Node Drivers

From pkg/apis/management.cattle.io/v3/machine_types.go:278 Node drivers enable Rancher to provision nodes on different cloud providers.

Node Driver Spec

displayName

string

Public name shown in the UI (max 57 chars)

description

string

Short explanation of the driver

url

string

required

Location of the driver binary (required)

builtin

boolean

Whether the driver is built into Rancher

active

boolean

required

Whether the driver can provision clusters (required)

checksum

string

Expected checksum of the driver binary (md5, sha1, sha256, sha512)

List Node Drivers

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

Activate Node Driver

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/nodedrivers/digitalocean?action=activate

Deactivate Node Driver

curl -X POST \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  https://rancher-server/v3/nodedrivers/digitalocean?action=deactivate

Best Practices

Use Node Pools for Scaling

Manage groups of similar nodes with node pools rather than individual nodes:

Easier scaling
Consistent configuration
Automated replacement

Label Nodes Appropriately

Use labels to identify node characteristics:

node-role.kubernetes.io/worker=true
workload-type=cpu-intensive
environment=production

Apply Taints for Dedicated Nodes

Use taints to dedicate nodes for specific workloads:

GPU nodes: dedicated=gpu:NoSchedule
Database nodes: dedicated=database:NoSchedule
High-priority workloads: priority=high:PreferNoSchedule

Enable Drain Before Delete

Set drainBeforeDelete: true on node pools to gracefully migrate workloads before node removal.

Monitor Node Health

Regularly check node conditions and resource usage:

Watch for DiskPressure, MemoryPressure conditions
Monitor resource allocation (requested vs allocatable)
Set up alerts for node not-ready states

Node Autoscaling

For RKE2/K3s clusters using the provisioning API:

curl -X PUT \
  -H "Authorization: Bearer ${RANCHER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "machinePools": [
      {
        "name": "worker-pool",
        "quantity": 3,
        "autoscalingMinSize": 2,
        "autoscalingMaxSize": 10,
        "workerRole": true
      }
    ]
  }' \
  https://rancher-server/v1/provisioning.cattle.io.clusters/fleet-default/my-cluster

Autoscaling requires the Kubernetes Cluster Autoscaler to be installed.

Next Steps

Workloads

Deploy applications to nodes

Clusters

Manage clusters

Node Scaling

Configure cluster autoscaling

​Node Resource

​Node Spec

​Node Status

​Node Conditions

​List Nodes

​Filter Nodes

​Get Node

​Response Example

​Update Node

​Delete Node

​Node Actions

​Cordon Node

​Uncordon Node

​Drain Node

​Node Pools

​Node Pool Spec

​Create Node Pool

​Scale Node Pool

​Node Templates

​Node Template Spec

​Create Node Template

​Node Drivers

​Node Driver Spec

​List Node Drivers

​Activate Node Driver

​Deactivate Node Driver

​Best Practices

​Node Autoscaling

​Next Steps

Workloads

Clusters

Node Scaling

Node Resource

Node Spec

Node Status

Node Conditions

List Nodes

Filter Nodes

Get Node

Response Example

Update Node

Delete Node

Node Actions

Cordon Node

Uncordon Node

Drain Node

Node Pools

Node Pool Spec

Create Node Pool

Scale Node Pool

Node Templates

Node Template Spec

Create Node Template

Node Drivers

Node Driver Spec

List Node Drivers

Activate Node Driver

Deactivate Node Driver

Best Practices

Node Autoscaling

Next Steps