# crunchydata/postgres-operator architecture

> Architecture diagram of the GitHub repository crunchydata/postgres-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crunchydata/postgres-operator
- Repository: https://github.com/crunchydata/postgres-operator

## Overview

PGO is a Kubernetes operator that turns declarative Postgres custom resources into managed clusters. The primary workflow is a user submitting a PostgresCluster; the operator reconciles Kubernetes resources and maintains the cluster’s desired state. The product also includes HA via Patroni, backup and restore, monitoring, connection pooling, pgAdmin, and PostgreSQL upgrade management. Source excerpts show controller setup and selected reconciliation behavior; README statements support the broader capabilities, but unsampled subsystem internals are not asserted in detail.

Main entry points: [`internal/controller/postgrescluster/controller.go`](https://github.com/crunchydata/postgres-operator/blob/main/internal/controller/postgrescluster/controller.go) (Cluster Reconciler), [`cmd/postgres-operator/main.go`](https://github.com/crunchydata/postgres-operator/blob/main/cmd/postgres-operator/main.go) (Operator Manager), [`pkg/apis/postgres-operator.crunchydata.com/v1beta1/postgrescluster_types.go`](https://github.com/crunchydata/postgres-operator/blob/main/pkg/apis/postgres-operator.crunchydata.com/v1beta1/postgrescluster_types.go) (Custom Resources), [`internal/controller/runtime`](https://github.com/crunchydata/postgres-operator/tree/main/internal/controller/runtime) (Reconcile Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Operator Control"]
  node_api["Custom Resources"]
  node_operator["Operator Manager<br/>[main.go]"]
  node_runtime["Reconcile Runtime"]
end

subgraph group_cluster["Cluster Lifecycle"]
  node_clusterctl["Cluster Reconciler<br/>[controller.go]"]
  node_postgres["PostgreSQL Config<br/>[reconcile.go]"]
  node_patroni["HA and Failover<br/>[reconcile.go]"]
  node_pki["TLS and Certificates<br/>[pki.go]"]
end

subgraph group_services["Cluster Services"]
  node_pool["Connection Pooling<br/>[reconcile.go]"]
  node_pgadmin["Cluster pgAdmin<br/>[reconcile.go]"]
  node_standalone["Standalone pgAdmin<br/>[controller.go]"]
end

subgraph group_operations["Operations"]
  node_upgrade["Version Upgrades"]
  node_backrest["Backup and Restore<br/>[reconcile.go]"]
  node_monitoring["Metrics and Logs<br/>[postgres.go]"]
  node_pgmonitor["Postgres Monitoring<br/>[exporter.go]"]
end

node_user(("Kubernetes User"))
node_kubernetes["Kubernetes API"]
node_clusterstate[("Postgres Cluster")]

node_user -->|"defines desired state"| node_api
node_api -->|"submits resources"| node_operator
node_operator -->|"starts manager"| node_runtime
node_operator -->|"registers controller"| node_clusterctl
node_operator -->|"registers controller"| node_upgrade
node_operator -.->|"registers controller"| node_standalone
node_runtime -.->|"watches and writes"| node_kubernetes
node_clusterctl -->|"reconciles resources"| node_kubernetes
node_clusterctl -.->|"configures database"| node_postgres
node_clusterctl -.->|"configures HA"| node_patroni
node_clusterctl -.->|"configures backups"| node_backrest
node_clusterctl -.->|"configures pooling"| node_pool
node_clusterctl -.->|"configures pgAdmin"| node_pgadmin
node_clusterctl -.->|"secures cluster"| node_pki
node_clusterctl -.->|"configures telemetry"| node_monitoring
node_monitoring -.->|"uses monitoring"| node_pgmonitor
node_clusterctl -->|"maintains desired state"| node_clusterstate
node_upgrade -->|"updates version"| node_clusterstate
node_backrest -->|"backs up data"| node_clusterstate
node_patroni -->|"manages failover"| node_clusterstate
node_standalone -->|"reconciles resources"| node_kubernetes

click node_api "https://github.com/crunchydata/postgres-operator/blob/main/pkg/apis/postgres-operator.crunchydata.com/v1beta1/postgrescluster_types.go"
click node_operator "https://github.com/crunchydata/postgres-operator/blob/main/cmd/postgres-operator/main.go"
click node_runtime "https://github.com/crunchydata/postgres-operator/tree/main/internal/controller/runtime"
click node_clusterctl "https://github.com/crunchydata/postgres-operator/blob/main/internal/controller/postgrescluster/controller.go"
click node_postgres "https://github.com/crunchydata/postgres-operator/blob/main/internal/postgres/reconcile.go"
click node_patroni "https://github.com/crunchydata/postgres-operator/blob/main/internal/patroni/reconcile.go"
click node_upgrade "https://github.com/crunchydata/postgres-operator/blob/main/internal/controller/pgupgrade/pgupgrade_controller.go"
click node_backrest "https://github.com/crunchydata/postgres-operator/blob/main/internal/pgbackrest/reconcile.go"
click node_monitoring "https://github.com/crunchydata/postgres-operator/blob/main/internal/collector/postgres.go"
click node_pgmonitor "https://github.com/crunchydata/postgres-operator/blob/main/internal/pgmonitor/exporter.go"
click node_pool "https://github.com/crunchydata/postgres-operator/blob/main/internal/pgbouncer/reconcile.go"
click node_pgadmin "https://github.com/crunchydata/postgres-operator/blob/main/internal/pgadmin/reconcile.go"
click node_standalone "https://github.com/crunchydata/postgres-operator/blob/main/internal/controller/standalone_pgadmin/controller.go"
click node_pki "https://github.com/crunchydata/postgres-operator/blob/main/internal/pki/pki.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_operator,node_runtime,node_user toneBlue
class node_clusterctl,node_postgres,node_patroni,node_pki,node_clusterstate toneAmber
class node_pool,node_pgadmin,node_standalone,node_kubernetes toneMint
class node_upgrade,node_backrest,node_monitoring,node_pgmonitor toneRose
```

## Components

### Operator Control

- [Custom Resources](https://github.com/crunchydata/postgres-operator/blob/main/pkg/apis/postgres-operator.crunchydata.com/v1beta1/postgrescluster_types.go): `pkg/apis/postgres-operator.crunchydata.com/v1beta1/postgrescluster_types.go`
- [Operator Manager](https://github.com/crunchydata/postgres-operator/blob/main/cmd/postgres-operator/main.go): `cmd/postgres-operator/main.go`
- [Reconcile Runtime](https://github.com/crunchydata/postgres-operator/tree/main/internal/controller/runtime): `internal/controller/runtime`

### Cluster Lifecycle

- [Cluster Reconciler](https://github.com/crunchydata/postgres-operator/blob/main/internal/controller/postgrescluster/controller.go): `internal/controller/postgrescluster/controller.go`
- [PostgreSQL Config](https://github.com/crunchydata/postgres-operator/blob/main/internal/postgres/reconcile.go): `internal/postgres/reconcile.go`
- [HA and Failover](https://github.com/crunchydata/postgres-operator/blob/main/internal/patroni/reconcile.go): `internal/patroni/reconcile.go`
- [TLS and Certificates](https://github.com/crunchydata/postgres-operator/blob/main/internal/pki/pki.go): `internal/pki/pki.go`

### Cluster Services

- [Connection Pooling](https://github.com/crunchydata/postgres-operator/blob/main/internal/pgbouncer/reconcile.go): `internal/pgbouncer/reconcile.go`
- [Cluster pgAdmin](https://github.com/crunchydata/postgres-operator/blob/main/internal/pgadmin/reconcile.go): `internal/pgadmin/reconcile.go`
- [Standalone pgAdmin](https://github.com/crunchydata/postgres-operator/blob/main/internal/controller/standalone_pgadmin/controller.go): `internal/controller/standalone_pgadmin/controller.go`

### Operations

- [Version Upgrades](https://github.com/crunchydata/postgres-operator/blob/main/internal/controller/pgupgrade/pgupgrade_controller.go): `internal/controller/pgupgrade/pgupgrade_controller.go`
- [Backup and Restore](https://github.com/crunchydata/postgres-operator/blob/main/internal/pgbackrest/reconcile.go): `internal/pgbackrest/reconcile.go`
- [Metrics and Logs](https://github.com/crunchydata/postgres-operator/blob/main/internal/collector/postgres.go): `internal/collector/postgres.go`
- [Postgres Monitoring](https://github.com/crunchydata/postgres-operator/blob/main/internal/pgmonitor/exporter.go): `internal/pgmonitor/exporter.go`

### Other components

- **Kubernetes User**
- **Kubernetes API**
- **Postgres Cluster**

## Connections

- Kubernetes User → Custom Resources: defines desired state (evidence: `README.md`)
- Custom Resources → Operator Manager: submits resources (evidence: `README.md`)
- Operator Manager → Reconcile Runtime: starts manager (evidence: `cmd/postgres-operator/main.go`)
- Operator Manager → Cluster Reconciler: registers controller (evidence: `cmd/postgres-operator/main.go`)
- Operator Manager → Version Upgrades: registers controller (evidence: `cmd/postgres-operator/main.go`)
- Operator Manager → Standalone pgAdmin: registers controller
- Reconcile Runtime → Kubernetes API: watches and writes
- Cluster Reconciler → Kubernetes API: reconciles resources (evidence: `internal/controller/postgrescluster/controller.go`)
- Cluster Reconciler → PostgreSQL Config: configures database
- Cluster Reconciler → HA and Failover: configures HA
- Cluster Reconciler → Backup and Restore: configures backups
- Cluster Reconciler → Connection Pooling: configures pooling
- Cluster Reconciler → Cluster pgAdmin: configures pgAdmin
- Cluster Reconciler → TLS and Certificates: secures cluster
- Cluster Reconciler → Metrics and Logs: configures telemetry
- Metrics and Logs → Postgres Monitoring: uses monitoring
- Cluster Reconciler → Postgres Cluster: maintains desired state (evidence: `README.md`)
- Version Upgrades → Postgres Cluster: updates version (evidence: `internal/controller/pgupgrade/pgupgrade_controller.go`)
- Backup and Restore → Postgres Cluster: backs up data (evidence: `README.md`)
- HA and Failover → Postgres Cluster: manages failover (evidence: `README.md`)
- Standalone pgAdmin → Kubernetes API: reconciles resources (evidence: `internal/controller/standalone_pgadmin/controller.go`)
