A Kubernetes control plane that converges PostgreSQL and MySQL schemas from immutable OCI artifacts.
English · 日本語 · Deutsch · Français
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.
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.
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 sqlIt 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, kubectl ptah settle gives up the proof of a schema whose
database target moved, 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.
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 buildbuilds it from this checkout.
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.
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.
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.