ptah-operator

module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: MIT

README

Ptah Operator

A Kubernetes control plane that converges PostgreSQL and MySQL schemas from immutable OCI artifacts.

English · 日本語 · Deutsch · Français

Status of the CI workflow on the master branch, which verifies the source, runs the race detector and drives the full Kubernetes lifecycle Status of the weekly demonstration workflow on the master branch, which re-records every scenario against a real cluster Status of the documentation workflow on the master branch The license badge, reading MIT The lowest Go version this module compiles against, declared in go.mod

Install · First schema · Recorded runs · Documentation · Ptah compatibility

Ptah Operator is a Kubernetes-native control plane for continuously converging PostgreSQL and MySQL schemas from immutable OCI artifacts. Database work runs in short-lived, hardened Jobs; the controller itself has no permission to read database Secrets.

PtahSchema converges the database structure and the reference rows a declaration names. PtahMigration executes a prepared migration sequence and holds the recorded history to the artifact it selected, including a checkpoint bootstrap. Both run on PostgreSQL and MySQL.

The API is currently v1alpha1. The end-to-end matrix is green -- every supported Kubernetes minor, both engines, both artifact formats -- so what is still missing before this stops being an implementation preview is a published release. What a run measured, and against which Ptah build, is recorded in support/ptah.json.

Reconciliation model

resolve tag to digest -> verify artifact -> observe database -> publish plan
          ^                                                          |
          |                 approval (when required) <---------------+
          |                                                          |
          +--- verify convergence <- apply exact approved plan <-----+

The controller records a claim before creating each Job, permits at most one active Job per PtahSchema, and resumes that claim after a restart. A process exit is never treated as proof of convergence: every apply is followed by a new read-only observation.

Key safety properties:

  • OCI tags are resolved once and all later artifact access uses the digest.
  • Plans bind exact bytes to artifact, target, observed state, policy, and what decides how they run: controller-state semantics, Ptah version, executor image, and runner protocol. The manager's own image and revision are recorded, not bound, so an operator patch release keeps pending approvals.
  • Approvals are separate immutable resources stamped with authenticated admission identity.
  • Destructive plans are disabled by default and still require an exact-plan approval when enabled.
  • A plan that grants, revokes or delegates authority -- privileges, roles, owners, row-security policies, definer rights -- requires an exact-plan approval even under apply: Always.
  • Database and registry credentials are isolated from each other and are never placed in status, Events, plan resources, or command arguments.
  • Deletion and suspension never execute cleanup SQL.
  • An uncertain apply outcome always returns to observation instead of replay.

Reading what it applied

The SQL lives in immutable PtahSchemaPlanChunk objects a plan binds by index, size and digest, never in a status field or the manager's log. kubectl ptah reads it back the way the operator does:

kubectl ptah plan storefront --applied -n application -o sql

It is a read-only client, published with each release as a kubectl plugin for the supported client platforms. Read a plan carries the installation and the namespace-scoped RBAC it needs.

Install and first schema

The guide lives on its own site: operator.ptah.run. It carries installation, the three values the chart refuses to guess, a first worked schema, configuration, operations, the security model, the condition reasons and the support windows.

cd docs/site && npm ci && npm run build

builds it from this checkout.

See it run

Recorded runs are terminal sessions captured while the operator ran against a real cluster: applying a schema, changing it, approving a plan, refusing a destructive change, closing drift, failing and recovering. Each one is checked while it is recorded -- the conditions the session claims are read off the live objects -- and published only if every check held.

The demonstration badge above is the weekly re-recording on master, not the sessions the site plays. Green means every scenario still holds against a cluster built from master; what a reader watches is the recording committed in demo/recordings/runs.json, which changes only when somebody records it. A red badge is therefore a demonstration that has stopped being true, which is worth knowing before somebody reads it as current.

demo/ is how it is built and how to run it yourself.

Documentation

The user guide is published at operator.ptah.run and its pages live in docs/site/src/content/docs. One of them is written for somebody changing this code rather than for somebody running it:

  • Architecture -- the pieces, where they live, and which invariant each one holds.

Ptah itself -- the schema formats, the OCI artifact layout, the CLI -- is documented at docs.ptah.run. Which Ptah builds have been verified with this operator is published in the user guide, as the compatibility matrix.

PtahMigration is deliberately not folded into PtahSchema. A declared row set describes desired rows and a migration sequence describes a transition between states, so the two keep their own APIs and their own state machines while sharing the OCI transport, the credential isolation, the execution protocol and the target coordination.

License and help

Ptah Operator is published under the MIT license.

For questions and bug reports, open an issue in stokaro/ptah-operator. Anything the Ptah CLI does on its own belongs in stokaro/ptah instead. CONTRIBUTING.md covers what makes a report actionable and what a change has to pass, and participation is covered by the Code of Conduct. Commercial enquiries go to ask@stokaro.com.

Directories

Path Synopsis
api
v1alpha1
Package v1alpha1 contains the first public API for the Ptah operator.
Package v1alpha1 contains the first public API for the Ptah operator.
cmd
kubectl-ptah command
Command kubectl-ptah reads what the Ptah operator stored.
Command kubectl-ptah reads what the Ptah operator stored.
manager command
ptah-runner command
demo
cmd/record command
Command record runs the demonstration scenarios against a live lab and writes what happened.
Command record runs the demonstration scenarios against a live lab and writes what happened.
reference/v1
Package catalog is the storefront's reference data: the tables whose rows the application reads and never writes, declared beside the tables themselves.
Package catalog is the storefront's reference data: the tables whose rows the application reads and never writes, declared beside the tables themselves.
reference/v2
Package catalog is the storefront's reference data: the tables whose rows the application reads and never writes, declared beside the tables themselves.
Package catalog is the storefront's reference data: the tables whose rows the application reads and never writes, declared beside the tables themselves.
reference/v3
Package catalog is the storefront's reference data: the tables whose rows the application reads and never writes, declared beside the tables themselves.
Package catalog is the storefront's reference data: the tables whose rows the application reads and never writes, declared beside the tables themselves.
acceptancecoverage command
Package main derives the acceptance coverage table from the catalogs and the driver, rather than from a list written beside them.
Package main derives the acceptance coverage table from the catalogs and the driver, rather than from a list written beside them.
capacity command
Command capacity measures what the operator costs under a declared workload.
Command capacity measures what the operator costs under a declared workload.
capacityplancheck command
capacityplancheck applies the operator's SQL safety classification to a capacity fixture before the native verifier executes it.
capacityplancheck applies the operator's SQL safety classification to a capacity fixture before the native verifier executes it.
chartpackage command
chartpolicies command
Command chartpolicies generates the chart templates that ship the admission policies defined in Go.
Command chartpolicies generates the chart templates that ship the admission policies defined in Go.
crdreference command
crdreference renders the field reference for every custom resource this operator ships.
crdreference renders the field reference for every custom resource this operator ships.
crdschemadigest command
crdschemahistory
Package crdschemahistory verifies that the generated CRD schema identity advances monotonically relative to an exact Git commit.
Package crdschemahistory verifies that the generated CRD schema identity advances monotonically relative to an exact Git commit.
e2etiming command
e2etiming publishes what a lifecycle run spent its time on.
e2etiming publishes what a lifecycle run spent its time on.
imagecopy command
imagecopy copies a digest-pinned image, index and all, into another registry without changing a byte of it.
imagecopy copies a digest-pinned image, index and all, into another registry without changing a byte of it.
ptahdriftcategories command
Command ptahdriftcategories keeps support/ptah-drift-categories.json equal to the drift finding categories the pinned Ptah build can emit.
Command ptahdriftcategories keeps support/ptah-drift-categories.json equal to the drift finding categories the pinned Ptah build can emit.
releaseverify command
unknownlayerfixture command
Command unknownlayerfixture publishes a migration artifact carrying one layer whose media type the pinned executor does not accept.
Command unknownlayerfixture publishes a migration artifact carrying one layer whose media type the pinned executor does not accept.
updatekubernetessupport command
Command updatekubernetessupport performs the live half of Kubernetes support maintenance.
Command updatekubernetessupport performs the live half of Kubernetes support maintenance.
upgradealert command
upgradealert observes one declared upgrade from outside the Helm release.
upgradealert observes one declared upgrade from outside the Helm release.
verifyptahsupport command
Command verify-ptah-support validates the Ptah compatibility catalog and exports the one value the pipeline reads from it.
Command verify-ptah-support validates the Ptah compatibility catalog and exports the one value the pipeline reads from it.
verifyrunnerprotocol command
Command verifyrunnerprotocol holds runner.ProtocolVersion to the runner's source.
Command verifyrunnerprotocol holds runner.ProtocolVersion to the runner's source.
internal
admission
Package admission implements the independently authorized approval boundary.
Package admission implements the independently authorized approval boundary.
controller
Package controller reconciles credential-isolated desired schema state.
Package controller reconciles credential-isolated desired schema state.
controllerstate
Package controllerstate defines the manager-side durable-state contract.
Package controllerstate defines the manager-side durable-state contract.
controllerwrite
Package controllerwrite validates the narrow set of workload and plan writes issued by the operator manager identity, and protects reserved result credentials against writes from any principal.
Package controllerwrite validates the narrow set of workload and plan writes issued by the operator manager identity, and protects reserved result credentials against writes from any principal.
coordination
Package coordination names the database realm a desired-state resource claims.
Package coordination names the database realm a desired-state resource claims.
dataplane
Package dataplane defines the narrow machine-readable contracts consumed by the controller.
Package dataplane defines the narrow machine-readable contracts consumed by the controller.
fingerprint
Package fingerprint creates canonical content identities for reconciliation inputs.
Package fingerprint creates canonical content identities for reconciliation inputs.
jobclaim
Package jobclaim decides whether a Job is the one a claim built.
Package jobclaim decides whether a Job is the one a claim built.
managercache
Package managercache says what the manager keeps in memory from the resources it watches.
Package managercache says what the manager keeps in memory from the resources it watches.
migrationplan
Package migrationplan publishes and re-derives the immutable manifest of one planned migration sequence.
Package migrationplan publishes and re-derives the immutable manifest of one planned migration sequence.
migrationview
Package migrationview reads what the operator stored about one migration.
Package migrationview reads what the operator stored about one migration.
mutationlifecycle
Package mutationlifecycle holds the obligations both resource families carry when an operation may have changed a database.
Package mutationlifecycle holds the obligations both resource families carry when an operation may have changed a database.
ocireference
Package ocireference parses and binds the OCI references crossing the controller/data-plane trust boundary.
Package ocireference parses and binds the OCI references crossing the controller/data-plane trust boundary.
plancontract
Package plancontract defines the byte-size contract shared by plan execution, transport, storage, and reconstruction.
Package plancontract defines the byte-size contract shared by plan execution, transport, storage, and reconstruction.
planseal
Package planseal seals the Plan payload to a per-process manager key.
Package planseal seals the Plan payload to a per-process manager key.
planstore
Package planstore publishes immutable executable plans without placing SQL in a custom-resource status or controller log.
Package planstore publishes immutable executable plans without placing SQL in a custom-resource status or controller log.
planview
Package planview reads a stored plan back the way the operator reads it.
Package planview reads a stored plan back the way the operator reads it.
podintent
Package podintent resolves and validates the bounded set of safe PodSpec mutations performed by Kubernetes admission and scheduling.
Package podintent resolves and validates the bounded set of safe PodSpec mutations performed by Kubernetes admission and scheduling.
policy
Package policy binds verification policy bytes to plans and approvals.
Package policy binds verification policy bytes to plans and approvals.
resultauthority
Package resultauthority checks live Kubernetes authority for result delivery.
Package resultauthority checks live Kubernetes authority for result delivery.
resultcleanup
Package resultcleanup retires and collects runner evidence through direct API reads.
Package resultcleanup retires and collects runner evidence through direct API reads.
resultconsumer
Package resultconsumer loads durable evidence outside reconciliation workers.
Package resultconsumer loads durable evidence outside reconciliation workers.
resultcredentials
Package resultcredentials binds delivery to an operation's first Pod.
Package resultcredentials binds delivery to an operation's first Pod.
resultcredentials/binding
Package binding describes public credential metadata and Pod references.
Package binding describes public credential metadata and Pod references.
resultdelivery
Package resultdelivery implements authenticated, bounded delivery of an already executed operation.
Package resultdelivery implements authenticated, bounded delivery of an already executed operation.
resultdelivery/jobconfig
Package jobconfig fixes the runner's durable-delivery inputs in its immutable Job template.
Package jobconfig fixes the runner's durable-delivery inputs in its immutable Job template.
resultdelivery/resulttest
Package resulttest shares production Job fixtures for delivery component tests.
Package resulttest shares production Job fixtures for delivery component tests.
resultretention
Package resultretention protects operation evidence independently of Jobs, certificate validity, and the currently elected manager.
Package resultretention protects operation evidence independently of Jobs, certificate validity, and the currently elected manager.
resultservice
Package resultservice connects durable delivery to the manager lifecycle.
Package resultservice connects durable delivery to the manager lifecycle.
resultstore
Package resultstore persists an already authenticated and validated runner payload.
Package resultstore persists an already authenticated and validated runner payload.
schemaselector
Package schemaselector validates the bounded lexical contract shared by the API and the execution boundary for schema scope selectors.
Package schemaselector validates the bounded lexical contract shared by the API and the execution boundary for schema scope selectors.
schemaview
Package schemaview reads where one PtahSchema stands.
Package schemaview reads where one PtahSchema stands.
targetlock
Package targetlock serializes database operations in the same user-declared physical coordination realm.
Package targetlock serializes database operations in the same user-declared physical coordination realm.
telemetry
Package telemetry defines bounded-cardinality Prometheus telemetry for the reconciliation state machines of both resource families.
Package telemetry defines bounded-cardinality Prometheus telemetry for the reconciliation state machines of both resource families.
workload
Package workload builds the bounded Kubernetes Jobs used by the schema controller.
Package workload builds the bounded Kubernetes Jobs used by the schema controller.
test
e2e
Package e2e holds the acceptance phases the Go harness runs against the cluster hack/e2e-kind.sh stands up.
Package e2e holds the acceptance phases the Go harness runs against the cluster hack/e2e-kind.sh stands up.
e2e/alertsink command
Command alertsink is the receiver the alerting phase points Alertmanager at.
Command alertsink is the receiver the alerting phase points Alertmanager at.
e2e/delayproxy command
Command delayproxy stands in front of a database and holds every new connection for a declared delay before reaching it.
Command delayproxy stands in front of a database and holds every new connection for a declared delay before reaching it.
e2e/handcraftoci command
Command handcraftoci publishes one intentionally unvalidated schema layer.
Command handcraftoci publishes one intentionally unvalidated schema layer.
e2e/harness
Package harness runs the acceptance phases test/e2e carries, inside the cluster hack/e2e-kind.sh stands up.
Package harness runs the acceptance phases test/e2e carries, inside the cluster hack/e2e-kind.sh stands up.
e2e/logstall command
Command logstall serves one deliberately unfinished kubelet log response.
Command logstall serves one deliberately unfinished kubelet log response.
e2e/phases
Package phases declares the acceptance phases the Go harness carries.
Package phases declares the acceptance phases the Go harness carries.
e2e/resultframe
Package resultframe extracts one exact, integrity-bound runner result from an acceptance Pod's log.
Package resultframe extracts one exact, integrity-bound runner result from an acceptance Pod's log.
e2e/runnerprotocolfixture command
Command runnerprotocolfixture prepares a Go build overlay for an explicitly incompatible runner.
Command runnerprotocolfixture prepares a Go build overlay for an explicitly incompatible runner.
envtest/internal/harness
Package harness starts the envtest control plane the suites under test/envtest share: one kube-apiserver and one etcd per package, and nothing else.
Package harness starts the envtest control plane the suites under test/envtest share: one kube-apiserver and one etcd per package, and nothing else.
envtest/internal/policyenv
Package policyenv installs the chart's admission policies into an envtest API server in the state a completed install leaves them, and decides requests against them: which policy refused a request, and with what.
Package policyenv installs the chart's admission policies into an envtest API server in the state a completed install leaves them, and decides requests against them: which policy refused a request, and with what.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL