ptah-operator

module
v0.2.10 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 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 published with each release as a kubectl plugin for the supported client platforms. Its read commands only read; kubectl ptah approve creates the approval of a plan you reviewed, as you, and needs create on the approval kinds. kubectl ptah suspend, resume and refresh patch a schema or a migration, as you, kubectl ptah set-source points one at another artifact pinned by digest, and kubectl ptah wait waits for the operator to act on a change. 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 images and executor version an installation pins, 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, and records the decisions a person makes about it.
Command kubectl-ptah reads what the Ptah operator stored, and records the decisions a person makes about it.
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.
chartpublish command
chartpublish is the release workflow's program for the chart it publishes to an OCI registry, one subcommand per workflow step.
chartpublish is the release workflow's program for the chart it publishes to an OCI registry, one subcommand per workflow step.
chartstamp
Package chartstamp derives the chart a release publishes to its OCI registry from the chart asset the acceptance matrix installed.
Package chartstamp derives the chart a release publishes to its OCI registry from the chart asset the acceptance matrix installed.
chartstamp/chartstamptest
Package chartstamptest serves the part of the OCI distribution API that a push and a helm pull use, so a test can run both against the bytes they would write to a real registry, with no daemon and no network.
Package chartstamptest serves the part of the OCI distribution API that a push and a helm pull use, so a test can run both against the bytes they would write to a real registry, with no daemon and no network.
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.
unparsableschemafixture command
Command unparsableschemafixture publishes a schema artifact the executor cannot parse.
Command unparsableschemafixture publishes a schema artifact the executor cannot parse.
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.
apipace
Package apipace bounds how fast one manager process sends requests to the Kubernetes API server.
Package apipace bounds how fast one manager process sends requests to the Kubernetes API server.
apirefusal
Package apirefusal reads what the API server's answer to a failed write says about it.
Package apirefusal reads what the API server's answer to a failed write says about it.
approve
Package approve turns a person's review of a stored plan into the approval the operator acts on.
Package approve turns a person's review of a stored plan into the approval the operator acts on.
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.
desiredspec
Package desiredspec decides which part of a PtahSchema's or a PtahMigration's spec is the desired state its plans come from: all of it but spec.suspend.
Package desiredspec decides which part of a PtahSchema's or a PtahMigration's spec is the desired state its plans come from: all of it but spec.suspend.
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.
lifecyclejournal
Package lifecyclejournal derives a resource's lifecycle journal from the status writes the controllers already make.
Package lifecyclejournal derives a resource's lifecycle journal from the status writes the controllers already make.
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.
operate
Package operate changes and waits on a PtahSchema or a PtahMigration the way kubectl ptah suspend, resume, refresh, set-source and wait do.
Package operate changes and waits on a PtahSchema or a PtahMigration the way kubectl ptah suspend, resume, refresh, set-source and wait do.
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 prints a plan for `kubectl ptah plan`.
Package planview prints a plan for `kubectl ptah plan`.
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.
sourcebinding
Package sourcebinding holds the comparisons every component makes about a resource's source: which plan contract a source gives, what a plan binds in place of an artifact digest, and whether an operation's access binding reads the content a plan names.
Package sourcebinding holds the comparisons every component makes about a resource's source: which plan contract a source gives, what a plan binds in place of an artifact digest, and whether an operation's access binding reads the content a plan names.
sourcecontent
Package sourcecontent defines the content digest of a delivered source: the files a schema or a migration directory is read from, whatever carried them.
Package sourcecontent defines the content digest of a delivered source: the files a schema or a migration directory is read from, whatever carried them.
sourcepolicy
Package sourcepolicy reads and applies a source policy: what a team refuses for every ConfigMap and Git source, held in an immutable ConfigMap a resource selects with sourcePolicyFrom.
Package sourcepolicy reads and applies a source policy: what a team refuses for every ConfigMap and Git source, held in an immutable ConfigMap a resource selects with sourcePolicyFrom.
sourcesnapshot
Package sourcesnapshot is the immutable ConfigMap a ConfigMap source is copied into.
Package sourcesnapshot is the immutable ConfigMap a ConfigMap source is copied into.
sourceview
Package sourceview reduces the source a PtahSchema or a PtahMigration last resolved to what `kubectl ptah` prints: which kind of source it is, where it was read from, and what it resolved to.
Package sourceview reduces the source a PtahSchema or a PtahMigration last resolved to what `kubectl ptah` prints: which kind of source it is, where it was read from, and what it resolved to.
statusview
Package statusview holds what `kubectl ptah schema` and `kubectl ptah migration` print the same way: the conditions the operator published, the ones a reader reads first, the decisions people made about a resource, and a list the reader was not allowed to read.
Package statusview holds what `kubectl ptah schema` and `kubectl ptah migration` print the same way: the conditions the operator published, the ones a reader reads first, the decisions people made about a resource, and a list the reader was not allowed to read.
targetfailure
Package targetfailure writes what the operator says about an operation that could not open its target database: the kind of failure Ptah reported, what that kind means, and the Secret key the operation read its URL from.
Package targetfailure writes what the operator says about an operation that could not open its target database: the kind of failure Ptah reported, what that kind means, and the Secret key the operation read its URL from.
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.
pkg
planread
Package planread reads a stored schema plan back the way the operator reads it, for programs outside this module.
Package planread reads a stored schema plan back the way the operator reads it, for programs outside this module.
planread/planreadtest
Package planreadtest holds stored plans in an in-memory API server, for tests of programs that read plans.
Package planreadtest holds stored plans in an in-memory API server, for tests of programs that read plans.
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/gitfixture
Package gitfixture is the Git repository and the keys a test serves through test/e2e/gitserver: the git-sources acceptance phase serves them on kind, and the runner harness (test/runnerharness) from a container.
Package gitfixture is the Git repository and the keys a test serves through test/e2e/gitserver: the git-sources acceptance phase serves them on kind, and the runner harness (test/runnerharness) from a container.
e2e/gitrefusal
Package gitrefusal holds the words of Ptah's Git pull refusals that tests read.
Package gitrefusal holds the words of Ptah's Git pull refusals that tests read.
e2e/gitrepo
Package gitrepo builds the Git repository the acceptance phase reads schemas and migrations from: a linear history described by a Spec, written into an in-memory object store with fixed authors and times, so the same Spec always gives the same commit ids.
Package gitrepo builds the Git repository the acceptance phase reads schemas and migrations from: a linear history described by a Spec, written into an in-memory object store with fixed authors and times, so the same Spec always gives the same commit ids.
e2e/gitserver command
Command e2e-git-server serves one Git repository for the acceptance phase that reads schemas and migration directories from Git: over smart HTTP behind TLS with a token, and over SSH with one authorized key.
Command e2e-git-server serves one Git repository for the acceptance phase that reads schemas and migration directories from Git: over smart HTTP behind TLS with a token, and over SSH with one authorized key.
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.
runnerharness
Package runnerharness runs the runner against the Ptah image support/ptah.json pins, without a cluster, and holds what Ptah printed to the committed captures.
Package runnerharness runs the runner against the Ptah image support/ptah.json pins, without a cluster, and holds what Ptah printed to the committed captures.
runnerharness/recorder command
Command runner-harness-recorder is the runner from this commit, in the form the harness runs inside the executor image.
Command runner-harness-recorder is the runner from this commit, in the form the harness runs inside the executor image.
runnerharness/recording
Package recording is what the runner harness keeps of a run inside the executor image: a runner.Executor that records every child it starts, and the transcript test/runnerharness/recorder prints for the harness to read.
Package recording is what the runner harness keeps of a run inside the executor image: a runner.Executor that records every child it starts, and the transcript test/runnerharness/recorder prints for the harness to read.
runnerharness/volumes
Package volumes writes and unpacks what the harness's stand-in for the kubelet puts on a Pod's volumes: the directories an emptyDir starts as, and the files a Secret or a ConfigMap projects, with their owners and modes.
Package volumes writes and unpacks what the harness's stand-in for the kubelet puts on a Pod's volumes: the directories an emptyDir starts as, and the files a Secret or a ConfigMap projects, with their owners and modes.

Jump to

Keyboard shortcuts

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