pgcopydb-operator

A Kubernetes operator that runs pgcopydb migrations: declare a Migration resource, get a supervised bulk clone, optional logical-replication follow with controlled cutover, verification, and cleanup. Source and target are plain libpq endpoints, managed, operator-run, or self-hosted, within the prerequisites each mode requires.

Documentation: ydixken.github.io/pgcopydb-operator

Important

In development, pre-1.0. One-shot clone, live migration with follow and controlled cutover, and verification have E2E specs in test/e2e/, which a release candidate runs against a cluster at E2E_SCALE=0.1.

Install

helm install pgcopydb-operator oci://ghcr.io/ydixken/pgcopydb-operator/charts/pgcopydb-operator \
  --namespace pgcopydb-system --create-namespace

The chart is also listed on Artifact Hub, with the values reference, the Migration CRD and example resources.

Then create a Migration (full examples with explanations in docs/examples/):

kubectl apply -f docs/examples/01-clone-minimal.yaml
kubectl get pgm -w

The quickstart walks through the first clone; live migration covers follow, cutover, and the runbook.

Structure

api/                       # Migration CRD types, v1beta1 storage + deprecated v1alpha1 (CEL validation, no webhooks)
charts/pgcopydb-operator/  # Helm chart (published as OCI to ghcr.io)
cmd/, internal/            # manager and controller (kubebuilder go/v4)
config/                    # kubebuilder-generated kustomize tree
docs/                      # user docs, rendered to a site by mkdocs (mkdocs.yml)
docs/examples/             # Migration resources with short explanations
images/pgcopydb-builder/   # publishes the pgcopydb binary the runner image copies in, keyed on its source commit
images/runner/             # worker image: pgcopydb + PostgreSQL 18 client tools, stripped of what it never runs
test/e2e/                  # e2e suite: local runs and release candidate CI
.claude/skills/            # vendored skills (ponytail, humanizer, brainstorming), mandatory per AGENTS.md
.github/workflows/         # CI, weekly candidate and manual promotion, ghcr publish, docs deploy, GitLab mirror, Artifact Hub metadata
Taskfile.yml               # task help | lint | test | e2e

Developing

task help   # list tasks
task lint   # the pre-commit gate (YAML, generated manifests, chart, docs links, alert rules, Go)
task test   # unit and envtest suites
task e2e    # e2e against your CURRENT kubectl context (local only; prompts first)
            # E2E_SCALE sizes the seeded fixtures (default 1 = ~12GB); task e2e:stress runs the ~120GB tier
            # task e2e:matrix runs the PG version combos 14->18, 18->18, 15->17 at scale 0.1
            # task e2e:external runs it against an existing database pair (docs/operations/e2e-external.md)

Documentation

• Quickstart, installation, configuration: getting a Migration running and tuned.
• Live migration, verification, lifecycle: the operations runbooks.
• Monitoring: the metric reference, Grafana dashboards, and alert rules.
• Troubleshooting: symptoms mapped to causes and fixes.
• Prerequisites: what your PostgreSQL endpoints and cluster must provide before a Migration can run.
• docs/examples/: Migration resources for common scenarios.
• CRD reference: every Migration field with defaults and validation, generated from the Go types (task docs).
• Authors: who wrote this.
• Option coverage: every pgcopydb clone/follow option mapped to the Migration spec.
• Chart README: values reference.
• CONTRIBUTING.md: how to work here.
• AGENTS.md: rules for AI agents, including the mandatory skills.
• LICENSE: Apache-2.0.