PtahApprove a plan
With apply set to OnApproval, nothing runs until a person approves that exact plan.
What it shows. What an approval is bound to, and how much of that binding you never type.
A replay of a verified run, not a live cluster. 14 checks held while it was recorded. Play types it out in the frame below; the transcript is the same session, already there.
# Same resource, one field different -- apply is OnApproval, which is the default.$ APPLY=OnApproval demo/bin/lab manifest storefront "$(cat demo/.lab/digest)" | tee demo/.lab/storefront.yaml# The desired state of one database, as a Kubernetes resource.## Nothing here is a credential. The database URL and the registry password are# named, and read by the operator from Secrets this namespace holds; what the# resource carries is which artifact, which database, and what the operator is# allowed to do about the difference.apiVersion: operator.ptah.run/v1alpha1kind: PtahSchemametadata: name: storefront namespace: demospec: target: engine: PostgreSQL # Every resource that can reach this physical database, through any alias # or credential, has to use this exact key. It is how two of them are kept # from planning against each other. coordinationKey: demo/storefront/primary urlFrom: name: demo-database key: url desired: # A digest, not a tag: what was reviewed is what runs. ociRef: oci://e2e-registry.demo.svc.cluster.local:5000/schemas/demo@sha256:65970c1ecd30ab6c34d2a60e96f86eba9d66ac8f866c4b759c81eafb1d8a7f02 registryAuthFrom: name: demo-registry mode: Environment usernameKey: username passwordKey: password verificationPolicyFrom: name: demo-verification-policy key: policy.yaml transport: plainHTTP: true policy: apply: OnApproval allowDestructive: false driftSeverity: all interval: 1m suspend: false execution: activeDeadlineSeconds: 300 failureRetryInterval: 10s connectTimeout: 30s # Apply it, and the operator plans but stops.$ kubectl apply -f demo/.lab/storefront.yamlptahschema.operator.ptah.run/storefront created # It has a plan and it is waiting. The database has not been touched.$ kubectl -n "$NAMESPACE" get ptahschema storefront -o json \ | jq -r '.status.phase, (.status.conditions[] | select(.type == "ApprovalRequired") | .message)'AwaitingApprovalCreate an approval bound to the current plan fingerprint # Nothing was created. This is what waiting looks like from the database.$ kubectl -n "$NAMESPACE" exec deploy/demo-psql -- psql -c "\dt"Did not find any relations. # Read the plan before approving it. This is what would run.$ kubectl ptah plan storefront --current -n "$NAMESPACE" -o json \ | jq -r '.statements[] | "\(.severity)\t\(.sql)"'safe -- POSTGRES TABLE: customers --CREATE TABLE "customers" ( "id" bigint PRIMARY KEY NOT NULL, "email" text NOT NULL) # An approval names the schema, the plan, and the fingerprint of that plan.$ kubectl -n "$NAMESPACE" get ptahschema storefront -o json > demo/.lab/schema.jsonkubectl -n "$NAMESPACE" get ptahschemaplan \ "$(jq -r .status.plan.name demo/.lab/schema.json)" -o json > demo/.lab/plan.jsonjq -n --slurpfile schema demo/.lab/schema.json --slurpfile plan demo/.lab/plan.json ' { apiVersion: "operator.ptah.run/v1alpha1", kind: "PtahSchemaApproval", metadata: {name: "storefront-v1"}, spec: { schemaRef: {name: $schema[0].metadata.name, uid: $schema[0].metadata.uid}, planRef: {name: $plan[0].metadata.name, uid: $plan[0].metadata.uid}, planFingerprint: $plan[0].spec.fingerprint } }' | tee demo/.lab/approval.json | jq -c .spec{"schemaRef":{"name":"storefront","uid":"<uid>"},"planRef":{"name":"ptah-plan-668d861e896d227fd3fe192d","uid":"<uid>"},"planFingerprint":"sha256:668d861e896d227fd3fe192d97eebd31e8887bd0d7bce47985476d492f54276f"} # Create it. The webhook stamps who you are and holds the three to the live plan.$ kubectl -n "$NAMESPACE" create -f demo/.lab/approval.jsonptahschemaapproval.operator.ptah.run/storefront-v1 created # Who approved, and when, was stamped from the request. The rest stays on the plan.$ kubectl -n "$NAMESPACE" get ptahschemaapproval storefront-v1 -o json \ | jq -r '.spec | {approver: .approver.username, approvedAt, planFingerprint}'{ "approver": "kubernetes-admin", "approvedAt": "<time>", "planFingerprint": "sha256:668d861e896d227fd3fe192d97eebd31e8887bd0d7bce47985476d492f54276f"} # With the decision recorded, the plan runs and convergence is proved.$ kubectl -n "$NAMESPACE" exec deploy/demo-psql -- psql -c "\dt" List of relations Schema | Name | Type | Owner--------+-----------+-------+--------------- public | customers | table | ptah_external(1 row) # It was dispatched once, and is already stale. Retiring a used approval shows why.$ kubectl -n "$NAMESPACE" get ptahschemaapproval storefront-v1 -o json \ | jq -r '.status.conditions[] | "\(.type)\t\(.status)\t\(.reason)"'Accepted False PlanNoLongerCurrentStale True PlanNoLongerCurrentConsumed True DispatchCommitted
What was checked
Every step states what has to hold before its output may be published. A condition is read as its type, status and reason on the live object, never as a phrase in a message.
| Step | Claim | Held |
|---|---|---|
| 1 | exits 0, prints "apply: OnApproval" | yes |
| 2 | exits 0, prints "created" | yes |
| 3 | ptahschema/storefront: ApprovalRequired=True (Waiting) | yes |
| 3 | exits 0, prints "AwaitingApproval" | yes |
| 4 | exits 0, reports "Did not find any relations" | yes |
| 5 | exits 0, prints "CREATE TABLE \"customers\"", prints "safe" | yes |
| 6 | exits 0, prints "\"planFingerprint\":\"sha256:" | yes |
| 7 | exits 0, prints "created" | yes |
| 8 | exits 0, prints "approver", prints "approvedAt", prints "planFingerprint" | yes |
| 8 | ptahschemaapproval/storefront-v1: spec.approver.username is set, spec.approvedAt is set, spec.mutationRequestUID is set | yes |
| 9 | ptahschema/storefront: InSync=True (ScopedConverged) | yes |
| 9 | exits 0, prints "customers" | yes |
| 10 | exits 0, prints "Consumed", prints "DispatchCommitted" | yes |
| 10 | ptahschemaapproval/storefront-v1: Consumed=True (DispatchCommitted) | yes |
What it ran against
- Kubernetes1.37.0
- Operatorb98f92bed240
- Ptahv0.13.0
- Executorsha256:f68968558f06
- Recorded2026-10-10
- Scenarios at0f7a06595d8b
What the commands read
A session is repeated, not admired, so every name in it is one your own environment can carry. There is nothing else: no helper of ours stands between a command and the cluster, and the recorder refuses a step that reads a name this list does not hold. The commands arekubectl, ptah and kubectl ptah, each of which you install once; the last one is the operator’s own read-only client.
- KUBECONFIGthe cluster the commands run against
- NAMESPACEthe namespace the schema and its database credentials live in
- OPERATOR_NAMESPACEwhere the chart installed the operator
- CONTROLLERthe controller Deployment’s name, from that release
- REGISTRY_IN_CLUSTERthe registry address a Pod in the cluster resolves
- PTAH_OCI_REGISTRYthe registry address the push goes to
- PTAH_OCI_USERNAMEthe account that push uses
- PTAH_OCI_PASSWORDits password, which no command prints
A session also uses demo/bin/lab in two places, and both are the lab handing over what it generated rather than doing the demonstration’s work:lab credentials prints the three registry values above, and lab manifestfills the published template with values the step states. Rundemo/acceptance/reproduce.sh to watch the same scenario repeated from a directory where neither exists, by an account that may not create a Job, with the plan approved by a second account that may create neither a schema nor a Job.
The scenario is demo/scenarios/manual-approval.yaml, and make demo replays the whole set against a lab of your own. All recorded runs.