CLI reference

Tables list the registered flags for the public commands and operational components below. Grouped sections identify which subcommand takes each flag; hidden conformance commands are excluded. Required conditions include runtime validation, not just CLI annotations. Defaults show registered values; descriptions identify effective fallbacks and conditional requirements.

The c8s binary also responds to the symlink aliases get-cert, armtls-mesh, and nri-image-policy (each auto-prepends the matching subcommand). Installed as c8s-runc, it is the measured OCI runtime wrapper of the node image; pass runc commands and flags directly, without a c8s command prefix.

--image-policy-file takes a complete JSON image policy. A CDS pin binds both its image and the exact measured launch file (cds-pin.json). Node and router policies, such as server.json, identify those targets independently. Flat measurement flags exist only where listed.

c8s install

Install the C8s operator, CRDs, attestation-api, and component charts via Helm. Flags are registered with cobra/pflag. node.baked=false is the chart default; node.baked=true selects chart artifacts baked into the measured node image and settings from its signed launch file. router.enabled=true (the default) enables the router and its routing listener.

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). The consuming chart defaults to node.baked=false and needs cds.address and cds.measurementsConfig; supply the flags here or layer these values in the consuming Helm configuration. node.baked=true selects measured-image artifacts with signed launch inputs. router.enabled=true (default) enables routing; its keys come from launch inputs, cds.operatorKeys, or the verified CDS. Route manifests are not Helm values: store them with c8s routes.

c8s operator

Run the C8s controller-manager and admission webhook.

c8s cds

Run the Certificate Distribution Service (CDS) from a measured c8s-cds/v1 configuration. A verified self-report must bind its exact bytes. The host-readable configuration holds public inputs, including operator keys, configured node pins and policy; it carries no private keys or secrets. Subcommands are ca, config new, ha, and verify (see c8s verify).

A singleton holds its mesh CA and secrets in memory. An HA configuration selects replicated volatile state and requires explicit Genesis. A replica restart need not lose cluster state; losing all replica memory does. Surviving memory is retained when quorum loss stops serving. CA certificates renew under the same key after half their lifetime; certificate fingerprint changes alone do not establish a new CA key.

c8s cds config

new takes no positional arguments and writes cds-config.yaml and cds-pin.json to a new directory. The pin binds the exact configuration bytes and CDS guest image; all HA replicas boot those same bytes. Generate the release/options-matched component seed first with install --allowlist-seed-out, then generate and verify the external CDS before installation.

HA discovery reaches distinct replica identities on their client port and peer port 8444. Up to 16 nonvoters can join. Replicated state has a 256 MiB bound with headroom; this is not available secret capacity. Workloads and voter count initialize live state. Configuration node pins supply the default for HA Genesis; signed Genesis selects the initial admitted node set. Signed changes can update live state. Pinning the configuration does not freeze the live node policy forever.

c8s cds ha

Inspect and administer the replicated CDS. All leaf commands take no positional arguments. Reads verify each reached CDS against --cds-pin. Decrees are signed under an operator key in the measured configuration and posted to POST /ha/decrees.

status exits unsuccessfully for an unreachable, nonserving or wrong-cluster replica, or version/CA disagreement. Not every printed alarm changes its exit status. Only roll_safe and divergence are leader-specific; followers also report voters and checkpoints. Diagnostics remain reachable when ordinary APIs return 503 because a replica lacks a valid leader-confirmed serving lease or applied state.

Decree delivery reports held, applied at version, or refused. A successful CLI exit for a held decree proves acceptance only. Production held-decree consumers handle Genesis and Admit; Recover has no operational consumer or automatic Doubt/fencing proposer. Preserve surviving VMs when permanent quorum loss halts service. Recover acceptance is not a recovery procedure, and total memory loss cannot restore secrets or the CA key.

Before planned removal and between replacements, require the leader's roll_safe result. A VM already known destroyed may be replaced first while a majority serves; its dead vote itself makes the roll gate false. Unreachability does not prove destruction. Image rolls require overlap, per-process Admit and majority preservation. rotate-key changes mesh CA authority only; operator authorization keys stay launch-bound. Clients can adopt an independently signed, strictly newer provisional pin decree over unverified transport; an initial refresh failure keeps the launch pins. New connections fail across changed CA keys; established streams are not guaranteed to terminate immediately.

Flags shared by the read commands and/or decree commands are listed once with their scope:

c8s cds ca

Read the mesh CA bundle CDS serves at GET /ca and write it as PEM to --out, or to stdout. It is the anchor c8s secrets put --mesh-ca, c8s volume create --mesh-ca and c8s verify --mesh-ca take. The read travels the attested connection those commands use and requires endpoint pins. A launch measurement identifies the image, not the instance, so the SHA-256 of each certificate is printed on stderr for comparison on a later read. A singleton restart or loss of all replica memory replaces the mesh CA key. A surviving HA cluster retains it across individual restarts. Same-key certificate renewal also changes certificate fingerprints; compare the key separately when judging cluster continuity. The router front door does not relay /ca, and a URL that serves a router discovery document is refused; point --url at CDS directly.

c8s allowlist

Read and mutate the CDS-served allowlist that nri-image-policy enforces on every node. It is a set of named entries, each pinning an init/main container set with per-container argv, mount, environment and path policy. An image admitted under any command line is an entry whose command and args policy are both any; add writes one. Reads are unauthenticated; writes are signed with the operator EC private key whose public half is in the CDS measured configuration. See The Allowlist for usage.

For add, <digest> is sha256: plus 64 hexadecimal digits; <image> is a nonempty informational label (* is refused) (such as a tagged image reference), not a registry lookup. For example, this prints a dry run:

c8s allowlist add sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef example/app:1 --url https://cds.example:8443 --dry-run

The router front door relays /allowlist; commands that contact CDS can use that route.

Entry edits (add, apply, edit, delete) canonicalize and sign a complete policy and use conditional whole-document writes with bounded conflict retries. upload refuses a racing write for review. Exact canonical bytes retain the signature; seed and noncanonical policies may be unsigned. derive prints a bare name-to-entry map and has no egress flag.

Signed egress policy admits at most eight unique TCP exits per workload: masked IPv4 /16 or narrower, or IPv6 /48 or narrower, excluding protected ranges. It requires pinned argv and mounts plus a unique, complete sandbox main-container match. Environment follows the selected policy, which may be any. Exits remain unavailable until observed containers satisfy every main-container policy of the matching workload entry. Exits bypass capture without encrypting payloads; changed or removed exits require pod recreation. See The Allowlist.

HA allowlist history is periodically pruned toward 1000 entries and 64 MiB, preserving the current document; these targets can be exceeded before pruning. Removed objects and signatures become unavailable. HA writes can fail with 503 or 507 state_capacity.

Persistent flags, registered on every subcommand:

Per-subcommand flags:

For a bare-metal node, use upload --cvm-mode bare-metal to check the appropriate component set. --force bypasses the missing-component check and requires a separate review of the policy.

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 apply. Values are held in singleton memory or replicated HA memory. A singleton restart or loss of all replica memory empties the store; preserve operator escrow for restoration. 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 in its measured configuration. The router front door does not relay /secrets or /ca, and both subcommands refuse a URL that serves a router discovery document before they send anything: point --url at the external CDS client address and pin its image and exact launch file with cds-pin.json.

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 operator provisioning process generates the key outside the TEE and writes escrow before publishing it to CDS memory. A key path is create-only: CDS refuses a --path that already holds a value. See Volumes.

attach and detach require a Linux node with LIO support and root; the C8s node image does not support LIO attachment. A QEMU/KVM node receives a disk with the required serial from its hypervisor.

Persistent flags, registered on every subcommand:

create flags:

attach and detach flags:

c8s routes

Read and write the signed route manifest (c8s.routes/v1) CDS stores at /routes. The router routes application requests by this manifest alone, and c8s install --upstream writes the first one for an adopted workload. A write must carry a revision greater than the stored one, and is signed with the operator key, as for c8s allowlist. add and rm fetch the stored manifest, verify it against --operator-keys, change one route, and write the next revision: the later of the stored revision plus one and the current Unix time, or --revision. They set notBefore to now, or keep a later stored value, and print every route the new revision carries before signing. The router does not relay /routes: point --url at CDS itself, with no path. The route digest show and digest print is the value c8s verify --route-digest takes.

Persistent flags, registered on every subcommand:

Per-subcommand flags:

After a CDS reset that lost its database, put the last manifest rather than starting a new one.

c8s cds-attest

Run the router routing, attestation and over-encryption sidecar (the c8s-verify/v1 server side). It always runs in the router pod. It polls the operator-signed route manifest from CDS (GET /routes) over RA-TLS, verifies it under the operator keys, and routes by it: plain application requests nginx hands to its loopback routing listener, and requests decrypted from the tunnel. With the attestation endpoints on (chart value 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); both bind the digest of the applied manifest into their evidence. Until it applies a manifest, routed requests get 503 and handshakes are refused with 503 routes_unavailable; once maxAgeSeconds passes without a successful poll, handshakes are refused with routes_stale while routing goes on. A request whose host is not a manifest host, or whose path matches no route, gets 404; a backend TLS failure gets 502. It's a chart-managed component, not normally run by hand — see Consumer Verification for the protocol.

Mesh identity credentials are fixed at /etc/c8s/certs/tls.crt, tls.key and ca.crt. Applications serve ordinary TCP/HTTP; the injected endpoint holds their private mesh credentials. Workload backends must present the expected name and the same allowlist digest as the router leaf; mismatches fail routing. The ordinary nginx-routed HTTP body cap defaults to 1048576 bytes (oversize requests return 413). The attest-pq tunnel instead caps the encoded sealed record at 8 MiB, including overhead, so usable application payload is smaller. Decoded requests go directly to the backend without that ordinary HTTP cap. Backend limits, tunnel response buffering, and aggregate/per-client memory limits also apply.

c8s acme

Run the router's in-guest ACME sidecar (acme front-door mode). It runs beside nginx in the router pod and keeps the full chain at /etc/c8s-acme-tls/cert.pem, with private and account keys under /etc/c8s-acme-key, issued over ACME HTTP-01: nginx's :80 server proxies /.well-known/acme-challenge/ to the loopback challenge listener. Configured domains whose challenge paths do not yet reach this router are added once they do, without blocking the others. The certificate renews at 2/3 of its lifetime; nginx reads renewed credentials on subsequent handshakes, while open connections retain their negotiated leaf. On a node image the inputs come from the signed launch file through the *-file flags; an empty domains file means no ACME, and nginx serves the mesh leaf from --standby-cert-dir instead. A chart-managed component, not run by hand.

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 attest-proxy

Expose the pod-loopback attestation API through a node-local Unix socket. Socket ownership and mode restrict reachability; the socket is not a routable attestation endpoint. With no subcommand, serve until stopped. healthcheck performs one GET /health over its socket with a 3s timeout and exits 0 only on success; it registers only --socket. Both accept no positional arguments.

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; 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) or --url; one target is required unless --from-file supplies evidence. If both target forms are given, the positional argument wins. With --from-file, evidence is read from the file even if a target is supplied. c8s cds verify is the same command with CDS presets (--kind cds, default port 8443); --mode stays auto, which resolves to armtls-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, a responder-chosen chain anchor, or unjudged policy history). Policy measurement is optional and TDX-only; the stock baked image disables it, so its policy-history verification is not guaranteed. --pin-policy and --trust-operator fail when replayed history is absent. Certificate, discovery, or offline history alone is at best partial even after policy checks; fresh nonce-bound attest-pq or attest-lb evidence is needed to establish current history. History objects have bounded retention.

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; one policy document cannot mix the two platforms.

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.

derive takes one or more <image-dir|manifest.json> arguments. lint <measurements.json> checks a config for problems and takes no flags.

derive flags:

c8s get-cert

Obtain a CDS-signed certificate over RA-TLS using a fresh ECDSA P-256 private key per issuance. The chain, key and CA form one validated generation on the private credential volume. Resolve current once and read its directory for a coherent generation; stable file paths are replaced individually. All three output paths are required and must share a directory. Workload claims are enabled by default. Select exactly one of --san, --san-file, or --no-san.

Renewal follows CA certificate renewal under the same key. A replacement CA key requires pod recreation because each pod binds its issuer key for its lifetime. Private credentials are for platform consumers; ordinary applications use their injected mesh endpoint.

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 is lost with singleton restart or total replica memory loss. Publication replaces each file atomically, not the whole set. A 404 can mean a denied read or missing value; secrets explain diagnoses release, and secrets put or escrow restore supplies operator values. 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. The node agent's socket directory is compiled in (/run/c8s/workload-claims), so a pod cannot point the key handoff elsewhere. 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. CDS checks release grants; volumed checks the key blob and target. Writer exclusion is node-local. Verity authenticates immutable content, not freshness; mutable dm-crypt provides neither integrity nor rollback protection.

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. The same key may instead request a log-reader certificate (pods and their logs, nothing else) to hand on to someone who should not hold the operator role. Authorization is the cluster's RBAC on the issued group: the C8s node image bakes ClusterRoleBindings for the default --cert-org and --log-cert-org; elsewhere, create them or pass groups the cluster already binds. 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 seeds RTMR[3] as SHA-384(0x00*48 ‖ SHA-384(pubkey)), followed by the measured-policy journal replay, checked against 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 or log-reader 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] replay from the operator-key seed, measured-policy history and any explicitly expected --workload-image digest extensions. Fresh response runtime extensions feed replay; 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. New --out files are created with mode 0600; existing files are overwritten with their permissions preserved. Verification runs in-process with attestation-go, including the RA-TLS check on the cred-release dial; fresh attestation is operator-authenticated over the cred-release endpoint, so the guest's raw attester can stay on loopback. Requires --operator-key, --image-manifest, and --out, plus either --node, --vmi, or both --release-url and --apiserver-url.

c8s keys

Manage the operator EC keypair (P-256). The private key signs allowlist, secret, volume and route writes, and authenticates c8s get-kubeconfig; CDS pins its operator public keys in its measured launch configuration. Helm operator keys configure router verification. Changing CDS authority requires a new measured configuration and pin; HA rotate-key changes the mesh CA key only.

c8s launch-config

Create, extend and stage a measured node's signed c8s-launch/v2 configuration. c8s node launch-config is the same command. Node documents reject workloads; the generator uses --tenant-workloads for CDS policy. Signed node fields include registry mirrors, optional nodePassword, and router body limits. See the node CVM launch contract.

new writes:

Attach each node directory as its opkeydata disk: an ISO with volume label opkeydata, or a KubeVirt Secret volume with volumeLabel: opkeydata. On SEV-SNP, also set HOST_DATA to the SHA-256 of that node's pubkey file.

c8s node-image

Build measured node-image integration artifacts at image build time. node-services (prepare, node-ip) is its in-guest counterpart: baked units that prepare the image's authenticated bootstrap inputs, with no flags.

c8s armtls-mesh

Run one pod's injected TCP mesh endpoint. Applications serve ordinary TCP/HTTP inside the pod; the endpoint handles TLS 1.3 using a CDS-issued chain, purpose, ALPN and sandbox identity. It performs certificate validation, not hardware attestation on each connection, and supplies no generic destination-workload ACL. Covered pods are injected whether or not they have a cw name; the name expresses workload/service intent.

Credentials stay on the platform's private volume at /etc/c8s/certs in injected pods. Nonempty credential path/volume overrides and application credential mounts are refused by injection.

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 check rejects directories and zero-length files; a nonempty file can still be incomplete.