Outputs

A contract is written once, by the app's SDK, and everything else is generated from it. That is what keeps every tool in agreement: the Helm schema, the CUE validation, the rendered pod and the SDK's boot check all read the same document, so none of them can drift from the code.

Generation targets

Contract (CUE) Implemented

Plain data that unifies with #Contract: kind ConfigContract, apiVersion docuconf.dev/v1alpha1. Deterministic, sorted by name.

Contract (JSON) Implemented

A lossless JSON form of the same contract.

Validation report Implemented

Checks values, file sources and platform policy together. Secret values are never printed.

Pod configuration Implemented

Values in each app’s wire encoding, $ escaped, files projected with items (never subPath), inline content as content-hashed ConfigMaps, and the pod-template annotations and labels injectors need.

Helm values schema Implemented

JSON Schema draft-07: types, ranges, enums, required inputs, unknown names, secrets only as references, config-file content.

Helm library chart Implemented

Renders the same env, volumes and mounts as #Render; tested for parity on Helm 3 and 4.

Boot-time violation report Implemented

Covers what the platform cannot see: secret contents, certificate expiry and key match, file contents.

Config-file overlay Implemented

Values are placed at each variable’s configKey in native types, mounted at the overlay’s path; reload: watch maps to the host’s reload-on-change.

OCI contract artifact Specified, not built

Prevents validating image B against contract A. Signable with cosign.

Compatibility report Specified, not built

Blocks unacknowledged breaking changes, such as a new required variable.

Crossplane composition function Specified, not built

Validates at composition time and injects the rendered configuration into the composed workload.

Configuration docs Implemented

Rendered from the docs model, which is built from the contract, so docs cannot drift from code. Each input’s description and details come from its doc comment in the app.

Docs model Implemented

Every fact a renderer shows, already phrased, checked against #DocsModel. Secrets never have a value in it.

Standalone values JSON Schema Planned

The Helm schema without the chart wrapper.

Knative Service template Planned

Respects Knative’s reserved variables (PORT, K_SERVICE…) and reserved mount paths.

Kubernetes OpenAPI v3 schema Planned

Rejects a bad claim at kubectl apply.

Admission policy Planned

Catches edits that bypass CI, such as kubectl set env.

KCL schema Planned

For platforms that chose KCL over CUE.

.env.example Planned

Secrets appear as placeholders, never values.

The contract

contract.cue is the one output an SDK must produce. It is plain data — no CUE expressions — that unifies with the meta-schema's #Contract:

• kind: ConfigContract, apiVersion: docuconf.dev/v1alpha1, metadata.name (a DNS label), metadata.generator (language, SDK, version).
• Header // Code generated by docuconf. DO NOT EDIT., a package clause and import "docuconf.dev/contract".
• Deterministic: variables and files sorted by name, so the same code always exports the same bytes and diffs stay readable.
• Canonical durations: units in the order h m s ms us ns, each at most once, zero units omitted (1h30m, never 90m or 1h30m0s).
• contract.json is the same document as JSON (cue export), for tools without CUE.

Validation reports

docuconf vet (and the meta-schema's #Validate) checks a platform's values, file sources and policy against the contract and prints one line per problem:

$ docuconf vet -contract contract.cue -values values.yaml -files files.yaml -policy prod.cue
DATABASE_URL: is secret, so it must come from a secretKeyRef, never a literal or another reference
LOG_LEVL: is not declared in the contract (check the spelling)
PAYMENTS_TIMEOUT: "2 seconds" is not a duration such as 1m30s
TRACE_SAMPLE_RATIO: 1.5 is not allowed by policy
serving-tls: certificate does not cover orders.internal
tax-rates: inline content does not match its schema: default: invalid value 20 (out of bound <=1)

It exits 1 when there is any problem, and never prints a secret value — including one wrongly written as a literal.

Pod configuration

docuconf render (and #Render) turns valid values into the pod's configuration:

• env — each value in the app's wire encoding, $ escaped, secrets as valueFrom.secretKeyRef, plus every file's pathEnv.
• volumes and volumeMounts — one per file input, projected with items (never subPath), read-only, mode 0400 for secrets and 0444 otherwise.
• configMaps — immutable ConfigMaps for inline content, named with a hash of their content so any change rolls the pods.
• restartTriggers — Secrets and ConfigMaps whose change must roll the pods (inputs with reload: restart).
• podAnnotations and podLabels — what injectors need on the pod template, from injected sources and the values document's shared maps, with placeholders expanded. Empty without injectors. See Enabling the injector.

Helm

docuconf helm -contract contract.cue -chart . writes the chart's files/docuconf/contract.json and values.schema.json. Helm then enforces the contract on every lint, template, install and upgrade, and the docuconf library chart renders the same env, volumes and mounts as #Render, and the same pod annotations and labels through its docuconf.podAnnotations and docuconf.podLabels helpers. JSON Schema cannot compare durations, see the cluster or apply policy, so docuconf vet still runs in CI for those.

Generated docs

docuconf docs builds a docs model from the contract and renders CONFIG.md for developers and CONFIG.agents.md for coding and ops agents, from each input's description and details. See Generated docs.

Boot-time reports

Every SDK checks the real environment and files when the process starts and reports all violations together, each with a stable error code, to stderr and to /dev/termination-log so kubectl describe pod shows why it stopped. This is the only check that sees secret contents, injected values and certificate details. For a program in a language without an SDK, docuconf check runs the same checks against a contract, and docuconf exec runs them and then starts the program with the environment it checked.