Skip to content

Latest commit

 

History

797 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

The Ptah mark: an amber capstone above two sky-blue courses on a dark rounded square

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, 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.

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.