Skip to main content
A manifest is a YAML (or JSON) file that describes the desired state of a Caravanserai resource. The API follows the same structure as Kubernetes: every manifest has a apiVersion, a kind, a metadata block, and a spec block. When you apply a manifest, Caravanserai stores the desired state and reconciles it continuously until the cluster matches what you declared.

​
Structure

Every manifest shares a common top-level shape:
manifest.yaml
apiVersion: caravanserai/v1
kind: <Kind>
metadata:
  name: <name>
  labels:
    <key>: <value>
spec:
  # resource-specific fields

​
Common fields

TypeMeta — present in every resource:
FieldValue
apiVersionAlways caravanserai/v1
kindNode or Project
ObjectMeta — identity and classification:
FieldTypeDescription
metadata.namestringUnique identifier within the resource kind. Required.
metadata.labelsmapArbitrary key/value pairs for selection and grouping. Optional.

​
Supported kinds

Node

Register and configure a physical or virtual machine in your cluster.

Project

Define one or more containers (services) to run as a co-located workload.

​
Applying manifests

Use caractrl apply to create or update a resource from a manifest file.
1

Write your manifest

Save your manifest to a file, for example manifest.yaml.
2

Apply the manifest

Pass the file path with the -f flag:
caractrl apply -f manifest.yaml
You can also pipe a manifest from stdin:
cat manifest.yaml | caractrl apply -f -
3

Verify the result

Check the resource state after applying:
# List all projects
caractrl get projects

# List all nodes
caractrl get nodes

​
Format support

caractrl apply accepts both YAML and JSON manifests. The following two manifests are equivalent:
manifest.yaml
apiVersion: caravanserai/v1
kind: Project
metadata:
  name: nginx-demo
spec:
  services:
    - name: web
      image: nginx:alpine
The status block is read-only and set by the system. You do not need to include it in your manifests — Caravanserai ignores any status fields you submit.