Skip to main content
A Node represents a physical or virtual machine managed by a cara-agent instance. Caravanserai uses Nodes as scheduling targets: the Scheduler assigns Projects only to Nodes in the Ready state.
cara-agent self-registers its Node with the control plane on startup using the NODE_NAME environment variable. You only need to write a Node manifest manually when you want to pre-register a node before the agent starts, or to update node configuration such as labels or schedulability.

​
Schema

​
Top-level fields

​
string
required
Must be caravanserai/v1.
​
string
required
Must be Node.
​
object
required
Identity metadata for the resource.
​
string
required
Unique identifier for the Node within the cluster. This is the name the agent registers under and the name you use in caractrl commands. Typically matches the machine hostname or a descriptive label such as edge-node-01.
​
object
Arbitrary key/value pairs for grouping and selection. Common uses include zone or region labels, for example caravanserai.io/zone: ed312.

​
spec

​
string
The OS-level hostname of the machine, for example pve-03 or edge-01.local. Used for informational purposes and audit trails.
​
boolean
default:"false"
When true, prevents the scheduler from assigning new Projects to this Node. Projects already running on the Node continue to run. Set this field to true before draining a node for maintenance.

​
Example

node.yaml

​
Marking a node unschedulable

Set spec.unschedulable: true to cordon a node. The control plane stops scheduling new Projects onto it while existing workloads continue running.
1

Edit your node manifest

Set unschedulable to true in your manifest:
node.yaml
2

Apply the change

The control plane marks the node unschedulable immediately. The scheduler will not place new Projects on this node until you set unschedulable: false and reapply.
3

Verify the node state

The node remains visible and its existing Projects continue to run. Only new scheduling is blocked.
Setting unschedulable: true does not evict Projects already running on the node. To migrate workloads away, delete and reapply each Project after cordoning the node.

​
Status fields (read-only)

The following fields are written by the system — by cara-agent (heartbeat data) and the Controller Manager (aggregated state). Do not include them in your manifests.
High-level health summary of the Node. One of:
Overlay-network connectivity reported by the Headscale/Tailscale integration.
Resource totals reported by the agent.
RFC 3339 timestamp of the most recent heartbeat received from the agent. The control plane uses this to detect unresponsive nodes and transition them to NotReady.
A list of granular observable conditions on the Node. Each condition has: