ops-mason/docs/kubernetes-plane.md

Guarded Kubernetes plane automation

ops-mason plane constructs small security foundations from an immutable, reviewed bundle. It is not a general Kubernetes deployment wrapper.

Safety model

Every bundle declares its exact object identities, source revisions, expected cluster context, namespace, dependency assertions, forbidden kinds, manifest hashes, approved construction plan, and evidence destination.

Read-only commands (render, preflight, verify, rollback-plan) do not require approval. apply refuses unless all of these hold:

1. the construction plan is status: approved and names its approver/date;
2. --confirm exactly matches the plan ID;
3. --expect-digest exactly matches the freshly rendered bundle digest;
4. the repository is committed and clean;
5. the Kubernetes context, create RBAC, live-object drift, dependency assertions, client validation, and available server validation pass;
6. the bundle contains exactly the allowlisted objects, no Pod or Secret, no data/stringData, no cross-namespace object, and no token-bearing ServiceAccount.

The executor applies one pinned manifest at a time with server-side apply and field manager ops-mason. Namespaced manifests receive server dry-run after the Namespace exists and before they are persisted. A failed partial apply is reported; the executor does not automatically delete a Namespace.

Successful apply immediately performs metadata-only verification, checks that no Pod or Secret exists in the plane namespace, and writes JSON evidence with object UIDs/resource versions and generated rollback commands. It never reads or records a Secret value.

Commands

ops-mason plane render --bundle bundles/<id>.yaml
ops-mason plane preflight --bundle bundles/<id>.yaml
ops-mason plane apply --bundle bundles/<id>.yaml \
  --confirm <approved-plan-id> \
  --expect-digest <digest-from-preflight>
ops-mason plane verify --bundle bundles/<id>.yaml
ops-mason plane rollback-plan --bundle bundles/<id>.yaml

Rollback output is a plan, never an action. Review live inventory immediately before using it.