development

Developer Documentation

Internal documentation for contributors and operators. For user-facing documentation, see the README.

Architecture & Design

Document	Description
API Design (v1alpha1)	CRD structure, field definitions, templates, overrides, and lifecycle management
Admission Controller & Defaults	Hybrid admission control strategy: CRD schema, CEL validation, webhook mutating/validating
Pod Management Architecture	Direct pod management design, drain state machine, rolling updates
Pod Management Design	Detailed design for transitioning from StatefulSets to direct pod management

Implementation Details

Document	Description
Controller Patterns	Performance tuning (QPS, workers), event filtering (GenerationChangedPredicate), SSA idempotency
Phase Lifecycle	Phase values, computation per resource, crash-loop detection, periodic re-reconciliation
Caching Strategy	Informer filtering, secret access patterns (Option A/B/C), IRSA
Certificate Management	pkg/cert module, webhook TLS, pgBackRest TLS, consumer extensibility
Naming Strategy	Hierarchical names, hash collision prevention, character constraints
PVC Lifecycle	Deletion policy, hierarchical merging, caveats for developers
Backup Architecture	Shared PVC design rationale, replica selection logic, cell isolation
Template Propagation	Template update behavior, proposed update policy (Auto/Manual/Window)
Cell Topology	Local TopoServer design, failure domains, zone/region scheduling implementation
PostgreSQL Image Strategy	Bundled pgctld image, future custom image support plan
Observability Internals	Metrics registration, tracing lifecycle, traceparent bridge, log-trace correlation, alerts & dashboards
Known Behaviors	Documented quirks (e.g., "configured" loop with CSA + mutating webhooks)

Testing

Document	Description
Upstream Test Patterns	Research on upstream Multigres test patterns for informing E2E tests