Essential reference
Launch artifacts, measured fields, disk and network interfaces, workload annotations, and authoritative command help.
These contracts apply to the worker deployment in Prepare launch inputs.
The examples use c8s source 640b2d64afacb5696e66752eb5c834433336e4ed.
Use that CLI's help for every command's complete flags and defaults.
Artifacts and generated files
| Input or output | Consumer |
|---|---|
| Approved worker/CDS OCI digest | ORAS pull and deployment approval record |
manifest.json from each exact publication | Image measurement derivation and the substrate's boot recipe |
disk.raw and matching firmware/IGVM/boot files | TEE VM launcher; root disk attached read-only |
operator.key / operator.pub | Private policy/decree signing key / admitted public operator authority |
render/allowlist-seed.json | Initial platform workload policy in CDS config |
cds/cds-config.yaml | Exact shared launch document for all CDS replicas |
cds/cds-pin.json | Locally approved CDS image and configuration pin |
worker.yaml | Exact worker launch document admitted by Genesis |
worker-image.json | Derived worker image measurements, before Genesis adds its launch binding |
genesis.json | Signed cluster initialization/admission record |
mesh-ca.pem | Approved cluster CA for client mesh verification |
approved-allowlist.json, approved-routes.json | Reviewed policy and route inputs for client verification |
Worker tags for this release are v0.99.1-tdx and v0.99.1-sev-snp under
ghcr.io/confidential-dot-ai/guests/worker. CDS uses
ghcr.io/confidential-dot-ai/guests/cds:sha-640b2d6.
Resolve and approve immutable digests. Tags ending in -kubevirt are CDI
import images, distinct from the ORAS artifact bundles used by this journey.
The matching release chart supplies the operator/get-cert and mesh container digests; these are distinct from guest OCI digests. Keep the chart, verified release statement and manifests with the launch record. Follow artifact acquisition.
Worker launch document
worker.yaml is strict c8s-worker/v1 YAML, limited to 1 MiB. Its whole
bytes form the measured launch input. Generate it with c8s worker new;
editing it changes the identity that CDS must admit.
| Field | Contract |
|---|---|
schemaVersion | c8s-worker/v1 |
cds.address | Reachable CDS host:port |
cds.measurements | Measurements JSON encoded as a YAML string, binding the CDS image to its exact configuration bytes |
cds.pinFloor | Minimum accepted cluster version for signed CDS pin decrees |
tlsSAN | Router DNS name allowed by the pinned CDS configuration |
kubernetes.apiServer | External Kubernetes API host:port |
kubernetes.caCertificate | One PEM CA certificate authenticating that API server |
kubernetes.podCIDR / serviceCIDR | Non-overlapping IPv4 cluster ranges, distinct from worker address ranges |
kubernetes.clusterDNS | DNS Service IPv4 inside serviceCIDR |
router.hostnames | Optional public DNS names enabling in-guest ACME issuance |
router.acmeEmail / acmeDirectoryURL | Optional contact and HTTPS ACME directory; require hostnames |
router.maxRequestBodyBytes | Ordinary HTTP body limit; omitted or zero selects 1 MiB |
The worker document carries no launch signature or launch key. The file named
pubkey holds the whole document. The separate bootstrap-token is outside
that document and must be protected as a control-plane credential. See
Start a worker.
Source: worker document, router fields.
Measured fields and pins
| Manifest field | Meaning |
|---|---|
version | Build manifest schema; this journey uses version 3 |
snp_variants[].smp | Available SEV-SNP vCPU variant |
snp_variants[].igvm.path | IGVM file for that variant |
snp_variants[].measurement.snp_launch_digest | Variant's SHA-384 launch digest |
tdx.firmware.path | TDX firmware for this build |
tdx.mrtd, tdx.rtmr1, tdx.rtmr2 | Complete TDX image tuple from one build |
- MRTD alone identifies firmware. Approve RTMR[1] and RTMR[2] with it to pin the full measured guest.
- Match SNP's IGVM file, launch digest, and vCPU count.
- Derivation reads a producer manifest; independent build approval remains a separate step.
For rebuild/recomputation details, use the measurement source documentation.
CDS and workers each bind their own exact pubkey contents: SEV-SNP uses
HOST_DATA = SHA-256(file bytes); TDX's measured initrd extends SHA-384 of
those bytes into RTMR[3]. Worker policy-history verification starts from that
launch-file seed and replays subsequent policy extensions.
Verify a connection provides the TDX calculation and client checks.
Preserve each approved input for its consumer:
- CDS image/config pins bind CDS identity and launch configuration.
- Worker admission pins bind admitted worker images and launch documents.
- Workload policies constrain admitted workloads.
- Client acceptance pins constrain the verified connection.
A signed policy or a successful fetch establishes its authority or origin; it does not establish independent approval.
Disk interfaces
| Disk | Guest interface | Behavior |
|---|---|---|
| Root | Matching published disk.raw, read-only | Measured immutable guest filesystem |
| CDS launch | ISO9660 label opkeydata, root file pubkey | Exact CDS configuration; all replicas share its bytes |
| Worker launch | ISO9660 label opkeydata, root files pubkey and bootstrap-token | Exact worker document plus API bootstrap credential |
| Worker scratch | Virtio-blk serial confai-scratch, at least 64 GiB | Required encrypted writable state; boot fails if its encryption gate fails |
| Optional container cache | Serial confai-containerd or filesystem label containerd | Ephemeral encrypted cache; absence/failure uses tmpfs capped at 32G |
| Optional public models | Serial confai-models | Read-only ext4 at /var/lib/models; workloads must authenticate content digests |
| Encrypted workload volume | Serial c8s-vol-<NAME> | Device opened only after authorized key release |
- CDS state stays in guest memory and needs no scratch disk.
- Worker scratch and cache encryption use per-boot keys; this is volatile runtime storage.
- Plain dm-crypt protects confidentiality without authenticated storage integrity.
- Host-controlled public model storage remains untrusted even when mounted read-only.
See mount rules.
Network paths
| Path | Purpose |
|---|---|
Workers/operators → CDS TCP 8443 | Attested client API; load balancers preserve TLS |
CDS replicas/operators → replicas TCP 8444 | Direct attested peer and HA administration traffic |
CDS → workers TCP 1019 | Admission inventory |
| Workers → external API server's configured TCP port | Kubernetes API/bootstrap |
Control plane → workers TCP 10250 | Authenticated kubelet API; debugging/log handlers disabled |
Workers ↔ workers UDP 8473 | Cilium VXLAN |
Clients → router workers TCP 443 | Application front door |
Internet → router TCP 80, when ACME HTTP-01 is enabled | Certificate challenge |
| Guests → configured DNS, time, registry and endorsement services | Name resolution, clock synchronization, image pulls and attestation collateral |
Replica discovery DNS resolves directly to individual CDS replicas. Use
HTTPS GET /readyz for membership at the client load balancer. Allow only the
paths needed by the selected substrate and deployment.
Selected workload annotations
Set annotations on the pod template. The namespace scope controls webhook
injection; confidential.ai/cw names the workload and requests its mesh SAN
and managed Service. It does not authorize image execution or secret release.
| Annotation | Contract |
|---|---|
confidential.ai/cw | Workload ID; for a suitable DNS label, derives headless Service c8s-<ID> and SAN c8s-<ID>.<namespace>.svc |
confidential.ai/c8s-san | Optional valid DNS SAN override; requires cw |
confidential.ai/c8s-renew-interval | Go duration; zero uses operator default, negative rejected; requires cw |
confidential.ai/c8s-secrets | Comma-separated NAME=/store/path; releases files on the memory-backed secrets volume; requires cw |
confidential.ai/c8s-secret-dir | Fixed /run/c8s/secrets |
confidential.ai/c8s-volumes | Comma-separated NAME=/store/path; name is a DNS-1123 label of at most 12 characters; requires cw |
confidential.ai/c8s-volume-dir | Default /mnt/c8s-data/c8s-volumes; must remain at or below /mnt/c8s-data |
Secret and volume release also require a matching allowlist grant and admitted mount policy. Author grants deliberately; ordinary host mounts prevent secret release. See the current secret-release contract and encrypted-volume contract. Applications must tolerate files arriving after container startup.
Mesh private credentials belong to injected platform containers. Applications
cannot mount the reserved c8s-certs volume. The
webhook source
owns the full annotation, probe, reserved-name and admission contracts.
Command help and client libraries
Run help from the matching CLI build:
c8s worker new --help
c8s worker control-plane --help
c8s node-image render --help
c8s cds config new --help
c8s cds ha decree --help
c8s allowlist --help
c8s routes --help
c8s secrets --help
c8s volume --help
c8s measurements --help
c8s verify --helpEach subcommand's --help lists its own inputs. Use
TEErminator for the verified
application proxy in this journey. Custom JavaScript consumers use the
JavaScript verifier's configuration and channel examples.
Keep requests on the verified channel and approve the complete image tuple,
mesh/policy anchor, route and expected workload identity.