CLI Reference

One section per command, mirroring the flag definitions in the c8s source. Each table lists every flag of the command above it.

The c8s binary also responds to the symlink aliases get-cert, ratls-mesh, and nri-image-policy (each auto-prepends the matching subcommand).

c8s install

Install the c8s operator, CRDs, attestation-api, and component charts via Helm. Flags are registered with cobra/pflag.

c8s uninstall

Uninstall the c8s Helm release and sweep c8s host artifacts, including image-policy and mesh state. Requires Helm and kubectl on PATH.

c8s render-values

Print the resolved Helm values an install would apply, to stdout — without contacting a cluster. Useful for feeding a GitOps consumer (e.g. a Flux HelmRelease's valuesFrom) instead of recomputing digests and device mappings. Unlike install, the host distro is not autodetected — pass --distro to pin it. Still needs the registry reachable for the default digest resolution (--resolve-digests=true).

c8s operator

Run the c8s controller-manager and admission webhook.

c8s cds

Run the Certificate Distribution Service (CDS). Requires --ratls-platform, --attestation-api-url, and --allowlist-db.

c8s allowlist

Read and mutate the CDS-served allowlist that nri-image-policy enforces. It has two layers: a floor of image digests admitted by digest alone, and named workload entries that pin an init/main container set with per-container argv and path policy. Reads are unauthenticated; writes are signed with the operator EC private key whose public half the CDS pins (cds.operatorKeys, set by install --operator-keys). See The Allowlist for usage.

Persistent flags, registered on every subcommand:

Per-subcommand flags:

c8s secrets

Write operator-supplied values into the CDS secret store, and report why a sandbox does or does not receive them. CDS releases a value to a pod when the containers running in that pod's sandbox match a workload entry whose secrets grant covers the path; the grant is written with c8s allowlist workload apply. Values are held in the CDS process and nowhere else, so a CDS restart empties the store. See Secrets.

put sends the bytes exactly as read, including any trailing newline, and prints the byte count. Both subcommands sign their request with the operator EC private key whose public half the CDS pins (cds.operatorKeys, set by install --operator-keys).

Persistent flags, registered on every subcommand:

Per-subcommand flags:

c8s volume

Build an encrypted volume, store its key in the CDS secret store, and present the image to a node as a disk. create packages --source into an erofs image, formats a dm-verity tree over it, encrypts the pair to --out, writes the key blob to --escrow-out, and puts the key at --path in the store; with --mutable it builds a writable ext4 of --size instead, with no integrity protection. It then prints the pod annotations and the allowlist grant to apply; it modifies no workload. The image is ciphertext and can reach the node by any route, including through the untrusted host, attached as a raw block device with disk serial c8s-vol-<name>. create needs mkfs.erofs and veritysetup on PATH, or mkfs.ext4 with --mutable. The key exists in exactly two places — the CDS process and the escrow file — and a key path is create-only: CDS refuses a --path that already holds a value. See Volumes.

attach and detach run on the node as root, and are needed only where the hypervisor cannot give a disk a serial of its own — a QEMU/KVM node attaches the image with virtio-blk instead.

Persistent flags, registered on every subcommand:

create flags:

attach and detach flags:

c8s cds-attest

Run the router attestation + over-encryption sidecar (the c8s-verify/v1 server side). Fronted by the router nginx (chart flag router.attest.enabled), it serves the LB's attestation at /.well-known/c8s/attest-pq (encrypted session) and /.well-known/c8s/attest-lb (ordinary TLS), runs the post-quantum handshake, and forwards decrypted tunnel traffic to the backend. It's a chart-managed component, not normally run by hand — see Consumer Verification for the protocol.

c8s allowlist-proxy

Publish the CDS allowlist API through router. Public TLS terminates at the router nginx; this process makes the second trust hop, verifying CDS's RA-TLS serving certificate before forwarding the request. Path, query, and Authorization header are forwarded byte-for-byte, so the operator token's method/path/body binding survives the hop. It routes /allowlist and /allowlist/ to CDS, answers /healthz itself, and binds loopback only. A chart-managed component, not run by hand — see c8s allowlist for the client side.

c8s verify

Verify a deployed component's TEE attestation evidence (AMD SEV-SNP or Intel TDX) against the hardware signature chain plus a measurement, TCB, and policy check. Verification runs in-process with attestation-go (the Go port of the attestation-rs engine the cluster runs) — no container runtime is needed; a bare SEV-SNP report needs outbound HTTPS to AMD KDS (kdsintf.amd.com) to fetch its VCEK, bounded by --timeout. Takes a [target] (a URL or host:port) as its positional argument, or --url. c8s cds verify is the same command with CDS presets (--kind cds, default port 8443); --mode stays auto, which resolves to ratls-cert for a CDS target. See the verification guide for the end-to-end workflow.

Exit codes are a CI contract: 0 verified · 1 usage · 2 verification/policy failed · 3 evidence unavailable (unreachable / unparseable) · 4 partially verified — the evidence verified, but a property it presents is not proven (a serving key the evidence does not attest, no observable handshake, or a responder-chosen chain anchor).

c8s measurements

Work with measurements config files. A measurements config pins the VM images a cluster accepts; each entry is one image, matched as a whole — a launch digest together with the runtime registers measured from the same build. One file describes one platform: tee is either sev-snp or tdx, and a cluster mixing SNP and TDX images is not supported.

derive reads the manifest.json of each built confidential-os-builder image and writes the config. An SEV-SNP image contributes one entry per vCPU variant, named <image>-smp<N>, because the launch digest covers one VMSA page per vCPU — so even a single-image SNP cluster needs a multi-entry config. A TDX image contributes one entry: its MRTD with RTMR[1] and RTMR[2]. RTMR[0] is never pinned, since it varies with the vCPU and memory shape.

lint loads a config, reports the platform and the entry count, and takes no flags.

derive flags:

c8s get-cert

Obtain a signed certificate via the CDS attestation flow. Generates an ECDSA P-256 key (or loads --key), builds a CSR for --san, and exchanges it for a signed chain over RA-TLS. Requires --cds-url, --attestation-api-url, and --san.

c8s get-secret

Fetch the secrets this pod is granted and write each one to a file under --out-dir. Injected by the webhook as a native sidecar. It authenticates to CDS with the pod's CDS-issued certificate and a sandbox token redeemed from the node's admission inventory at a compiled-in endpoint, and CDS releases only once every main container in the sandbox is running — earlier attempts are refused and retried, so the files appear shortly after the workload starts and a consumer must wait for them. A path the store does not hold yet is created with a CDS-generated value, which does not survive a CDS restart. After writing, the process idles until the pod is torn down. See Secrets.

c8s get-volume

Fetch the key for each encrypted volume this pod is granted and hand it to c8s volumed, which opens the device and mounts it into this pod — read-only for an immutable volume, read-write for a mutable one. Injected by the webhook as a native sidecar, with the same authentication, release rule, and retry behavior as c8s get-secret: the volume appears shortly after the workload starts. The key must already be in the store, put there by c8s volume create; nothing here creates one. Linux only — the subcommand is registered only in Linux builds of the CLI. See Volumes.

c8s volumed

Agent that opens encrypted volumes for the pods it serves. An injected c8s get-volume sidecar hands it a key over volumed.sock, created inside the admission inventory's socket directory; the daemon resolves the calling pod from kernel peer credentials, opens dm-crypt, stacks dm-verity for an immutable volume, and mounts the result into that pod and no other — read-only erofs when verified, read-write ext4 when mutable. The mount target is never taken from what the caller reports about itself. Teardown is driven by the pod's cgroup slice disappearing.

c8s cred-release

Issue a short-lived kube client certificate to a caller that proves possession of the operator key whose public half was bound into the CVM's launch identity. It serves POST /release-credential over RA-TLS — the endpoint c8s get-kubeconfig consumes — signing the caller's CSR with the cluster's client CA and returning a kubeconfig anchored to the serving CA. Both TEE platforms are served, and only the binding differs: on TDX the staged operator public key must hash to the RTMR[3] the measured initrd extended, SHA-384(0x00*48 ‖ SHA-384(pubkey)), read back from the guest's own tdx_guest sysfs; on SEV-SNP it must equal the HOSTDATA the launcher committed at launch, SHA-256(pubkey), taken from a self-report the local attestation-api verified. Startup fails closed on a mismatch, and --platform is required because RA-TLS is mandatory here. Baked as a systemd unit in the c8s node image; not run by hand. The CA defaults are the RKE2 paths — on kubeadm, set all three to /etc/kubernetes/pki/ca.crt and ca.key.

c8s get-kubeconfig

Obtain an operator kubeconfig from a measured c8s CVM. The --image-manifest shape selects the platform and the gate pins every value it carries: on TDX the image tuple (MRTD, RTMR[1], RTMR[2]) plus RTMR[3] as the operator-key seed extended by each --workload-image digest in first-extend order; on SEV-SNP the reported launch digest must be one of the manifest's per-vCPU-count snp_variants digests and HOSTDATA must equal SHA-256 of the operator public key. SEV-SNP has no runtime-extend register, so --workload-image is rejected there. A locally generated CSR is then exchanged for a short-lived kube client certificate over the node's cred-release endpoint, and the kubeconfig is written to --out with mode 0600. Verification runs in-process with attestation-go, including the RA-TLS check on the cred-release dial. Requires --operator-key, --image-manifest, and --out, plus either --node, --vmi, or all of --attest-url, --release-url, and --apiserver-url.

c8s ratls-mesh

Run the RA-TLS L4 mesh proxy or its iptables side commands.

c8s ratls-mesh iptables-sync

Watch Kubernetes pods and maintain the iptables/ipset rules that redirect mesh traffic.

c8s ratls-mesh iptables-cleanup

Remove the iptables NAT rules and ipsets the mesh created.

c8s nri-image-policy

Run the nri-image-policy plugin. Uses the standard Go flag package, so the help output prints single-dash forms and both -config and --config parse; most configuration comes from the YAML config file rather than CLI flags.

c8s probe-file

Exit 0 if <path> exists and is a non-empty file — a file-existence helper for distroless containers, where /bin/test is not available. One-shot by default (for a kubelet exec probe); with --wait it blocks until the path passes (or --timeout elapses), so it can be the entrypoint of an init container that gates a workload on a file another container writes — the exec-free equivalent of a startup probe when exec probes are denied by policy. The non-empty check rules out passing on a half-written file.