Create an encrypted volume

Build the image and store the key

c8s volume create builds the image, generates a key, encrypts, and PUTs the key blob to the CDS secret store. It modifies no workload. Every flag is in the CLI reference.

Immutable (the default). --source is packaged into an erofs image with a dm-verity tree inside the encryption, and the image sizes itself to its contents:

c8s volume create \
  --name weights \
  --source ./llama-3.1-8b \
  --out ./weights.img \
  --path /tenant-a/volumes/weights \
  --escrow-out ./weights.escrow.json \
  --node node-1 \
  --url https://cds.example \
  --measurements-file ./measurements.txt \
  --operator-key ./operator.key

+ ./weights.img (26214400 data blocks)
+ key stored at /tenant-a/volumes/weights
+ key escrowed to ./weights.escrow.json — keep it; a CDS restart needs it

Attach ./weights.img to the node as a raw block device with serial c8s-vol-weights.

Pod annotations:
  confidential.ai/cw: <workload-id>
  confidential.ai/c8s-volumes: "weights=/tenant-a/volumes/weights"

Pod nodeSelector (the device is on one node):
  kubernetes.io/hostname: node-1

Allowlist grant for the workload entry (read-only, exact path):
  "secrets": {"policy": "allow", "read": ["/tenant-a/volumes/weights"]}

A subtree grant would cover every volume beneath it, so this names one path.

Mutable. --mutable builds a writable ext4 filesystem of --size bytes. --source is optional here: with it the tree is preloaded, without it the volume starts empty:

c8s volume create --mutable \
  --name scratch \
  --size 50Gi \
  --out ./scratch.img \
  --path /tenant-a/volumes/scratch \
  --escrow-out ./scratch.escrow.json \
  --node node-1 \
  --url https://cds.example \
  --measurements-file ./measurements.txt \
  --operator-key ./operator.key

+ ./scratch.img (50Gi, mutable, read-write)
  mutable volumes have no integrity protection: the host can flip bits or roll back undetected
+ key stored at /tenant-a/volumes/scratch
+ key escrowed to ./scratch.escrow.json — keep it; a CDS restart needs it
…

The rest of the output is the same: the serial to attach with, the pod annotations, the nodeSelector from --node, and the exact-path allowlist grant.

--size takes a byte count or a quantity — 50Gi, 500M, 2Ti. Give --source without --size and the size is inferred from the tree and printed back; pin that value with --size next time so a rebuild is predictable. The floor is 16 MiB. --size outside --mutable is refused: an immutable image sizes itself.

The store write is create-only. A path that already holds a value is refused: a volume's key and its ciphertext are one unit, so replacing the key at a path some volume already uses strands that volume rather than rotating anything. Choose another path.

Keep the escrow file

CDS keeps secrets in process memory and nowhere else. A CDS restart makes every volume in the cluster unopenable until its key is written back, and the escrow file is what you write it back from:

c8s secrets put /tenant-a/volumes/weights \
  --from-file ./weights.escrow.json \
  --url https://cds.example \
  --operator-key ./operator.key \
  --mesh-ca ./mesh-ca.pem

--mesh-ca names the CDS you trust: the mesh CA the endpoint serves must chain to that bundle, or the write is refused. It is the same anchor c8s verify --mesh-ca takes. Against an https endpoint the write needs it, or --force to write without the check.

Present the image to a node

The image is ciphertext. Copy it to the node by any means, including through the untrusted host — that the host holds the bytes is the premise, not a compromise of it.

The node finds a volume by disk serial c8s-vol-<name>, read from sysfs, so no udev rules are needed. A confidential node has no persistent writable storage — the root overlay is reformatted on every boot — so a volume has to be its own device rather than a file on the node's filesystem. For a mutable volume that device is where the writes persist.

How the device gets that serial depends on the hypervisor:

• QEMU/KVM. Attach the image in the VM spec: -device virtio-blk,drive=<DRIVE>,serial=c8s-vol-weights. The node reads it from /sys/block/<DEV>/serial. Nothing else is needed.
• Azure, Hyper-V, or any cloud disk. There is no virtio bus to set a serial on, and a cloud disk's serial belongs to the provider. Run c8s volume attach on the node, as root — it builds a local SCSI disk from the image whose unit serial (SCSI VPD page 0x80) is the one c8s asks for, and the node matches on /sys/block/<DEV>/device/vpd_pg80:

sudo c8s volume attach weights --image /var/lib/c8s/weights.img

+ weights attached as a disk with serial c8s-vol-weights
  confirm: grep -l c8s-vol-weights /sys/block/*/device/vpd_pg80

c8s volume detach weights removes the disk again. It removes the device, not the image: the ciphertext stays where it is and the key stays in CDS. Detach refuses while something still holds the disk, and names the holder — release a mounted volume by deleting the pod that has it first.

The serial is a selector, not a trust input. The host chooses it and answers the query per read. Pointing a pod at the wrong device fails closed: the key will not decrypt it into anything that mounts, and for an immutable volume verity refuses it as well. Two devices claiming the same serial are refused outright rather than resolved by scan order.

Because the device lives on one node, the pod must be scheduled there. create emits the matching nodeSelector. The node agent opens the device for the scheduled pod.

Grant the workload the key path

Release is gated on the workload entry's secrets grant in the allowlist:

"secrets": { "policy": "allow", "read": ["/tenant-a/volumes/weights"] }

Name the exact path, not a subtree. /tenant-a/volumes/** grants every volume beneath it, and the annotation naming which volume to open is host-written. create prints an exact-path grant for this reason.

read only, for both kinds. The grant governs who may obtain the key blob; whether the volume mounts writable is a property of the blob itself.

Request the volume from the pod

A pod names its volumes in an annotation:

metadata:
  annotations:
    confidential.ai/cw: llama-infer
    confidential.ai/c8s-volumes: "weights=/tenant-a/volumes/weights"
    confidential.ai/c8s-volume-dir: "/models"    # optional

Each entry is NAME=/store/path, comma-separated. NAME is a DNS-1123 label of at most 12 characters — it selects the node's device by its c8s-vol-<NAME> serial and names the directory the plaintext appears in under the volume dir, above /models/weights. Without confidential.ai/c8s-volume-dir the default is /run/c8s/volumes. The annotation is the same for both kinds: nothing in the pod says which one it is.

For a pod carrying confidential.ai/cw, the webhook then injects:

• a c8s-volume native sidecar, ordered after c8s-cert-wait — it authenticates with the leaf that sidecar writes;
• per volume, an emptyDir named c8s-volume-<NAME>, mounted into every container with mountPropagation: HostToContainer. The emptyDir uses the default medium.

Writability comes from the mount volumed makes over that directory: read-only for an immutable volume, read-write for a mutable one.

Both names are reserved. A pod may not declare its own container called c8s-volume, and a volume it pre-declares under the c8s-volume- prefix must be an emptyDir of the default medium, or be omitted entirely — a hostPath or a PVC is rejected at admission. See Workload annotations.

Verify the mount landed

The volume appears after the workload starts: release waits for every main container to be running, so the sidecar retries and the mount lands shortly after startup. An empty directory right at startup is expected; an empty directory that stays empty is not — check the c8s-volume sidecar's logs.

For an immutable volume, the files are the check:

kubectl exec -n <NAMESPACE> <POD> -- ls /models/weights

For a mutable volume, check that a write survives the pod. The commands below assume a pod annotated confidential.ai/c8s-volumes: "scratch=/tenant-a/volumes/scratch" with confidential.ai/c8s-volume-dir: "/data". Write a marker:

kubectl exec -n <NAMESPACE> <POD> -- sh -c 'date > /data/scratch/marker'

Delete the pod, let it come back on the same node, and read it again:

kubectl exec -n <NAMESPACE> <POD> -- cat /data/scratch/marker

The marker is still there. That is what separates a volume from the emptyDir underneath it.