# percona/percona-postgresql-operator architecture

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

- Interactive diagram: https://gitdiagram.com/percona/percona-postgresql-operator
- Repository: https://github.com/percona/percona-postgresql-operator

## Overview

Percona Operator for PostgreSQL turns Kubernetes custom resources into managed PostgreSQL clusters and related services. The primary workflow is a user submitting a cluster request, the operator reconciling it, and Kubernetes resources implementing the desired database state. Separate controllers handle backups, restores, upgrades, and supporting integrations. The graph includes both the upstream-style and Percona API controller paths, plus documented high availability, replication, monitoring, and user-management capabilities. Relationships are limited to README statements and SOURCE INDEX references; unsampled wiring is not inferred.

Main entry points: [`percona/controller/pgcluster/controller.go`](https://github.com/percona/percona-postgresql-operator/blob/main/percona/controller/pgcluster/controller.go) (PerconaPGCluster reconcile), [`internal/controller/postgrescluster/controller.go`](https://github.com/percona/percona-postgresql-operator/blob/main/internal/controller/postgrescluster/controller.go) (PostgresCluster reconcile), [`cmd/postgres-operator/main.go`](https://github.com/percona/percona-postgresql-operator/blob/main/cmd/postgres-operator/main.go) (Operator process), [`percona/controller/pgbackup/controller.go`](https://github.com/percona/percona-postgresql-operator/blob/main/percona/controller/pgbackup/controller.go) (Backup controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Operator control plane"]
  node_operator["Operator process<br/>[main.go]"]
  node_api["Custom resources"]
end

subgraph group_cluster["Cluster lifecycle"]
  node_legacy_cluster["PostgresCluster reconcile<br/>[controller.go]"]
  node_percona_cluster["PerconaPGCluster reconcile<br/>[controller.go]"]
  node_postgres["PostgreSQL configuration<br/>[reconcile.go]"]
  node_patroni["HA orchestration<br/>[reconcile.go]"]
  node_logical_replica["Logical replication<br/>[postgres.go]"]
end

subgraph group_operations["Data operations"]
  node_pgupgrade["Cluster upgrade"]
  node_percona_upgrade["Percona upgrade<br/>[controller.go]"]
  node_backup["Backup controller<br/>[controller.go]"]
  node_restore["Restore controller<br/>[controller.go]"]
  node_pgbackrest["Backup tooling<br/>[reconcile.go]"]
end

subgraph group_integrations["Cluster integrations"]
  node_pgadmin["PGAdmin management<br/>[controller.go]"]
  node_monitoring["Monitoring exporter<br/>[exporter.go]"]
  node_pmm["PMM integration<br/>[pmm.go]"]
  node_certs["Certificate management<br/>[certmanager.go]"]
  node_bridge["Crunchy Bridge integration"]
end

node_user(("Kubernetes user"))
node_kube[("Kubernetes API")]
node_bridge_api{{"Crunchy Bridge API"}}

node_user -->|"submits"| node_api
node_api -->|"stored in"| node_kube
node_operator -->|"watches resources"| node_kube
node_operator -->|"registers controller"| node_legacy_cluster
node_operator -->|"registers controller"| node_percona_cluster
node_legacy_cluster -->|"uses"| node_postgres
node_legacy_cluster -->|"uses"| node_patroni
node_legacy_cluster -->|"uses"| node_logical_replica
node_percona_cluster -->|"uses"| node_postgres
node_percona_cluster -.->|"watches upgrades"| node_pgupgrade
node_percona_upgrade -->|"updates cluster"| node_percona_cluster
node_backup -->|"reads cluster"| node_percona_cluster
node_backup -.->|"uses"| node_pgbackrest
node_restore -->|"reads cluster"| node_percona_cluster
node_restore -.->|"uses"| node_pgbackrest
node_percona_cluster -.->|"configures alongside"| node_pgadmin
node_percona_cluster -.->|"configures alongside"| node_monitoring
node_percona_cluster -->|"integrates"| node_pmm
node_percona_cluster -->|"uses"| node_certs
node_operator -->|"registers controller"| node_bridge
node_bridge -->|"creates clusters"| node_bridge_api
node_legacy_cluster -->|"reconciles resources"| node_kube
node_percona_cluster -->|"reconciles resources"| node_kube

click node_operator "https://github.com/percona/percona-postgresql-operator/blob/main/cmd/postgres-operator/main.go"
click node_api "https://github.com/percona/percona-postgresql-operator/blob/main/pkg/apis/pgv2.percona.com/v2/perconapgcluster_types.go"
click node_legacy_cluster "https://github.com/percona/percona-postgresql-operator/blob/main/internal/controller/postgrescluster/controller.go"
click node_percona_cluster "https://github.com/percona/percona-postgresql-operator/blob/main/percona/controller/pgcluster/controller.go"
click node_postgres "https://github.com/percona/percona-postgresql-operator/blob/main/internal/postgres/reconcile.go"
click node_patroni "https://github.com/percona/percona-postgresql-operator/blob/main/internal/patroni/reconcile.go"
click node_logical_replica "https://github.com/percona/percona-postgresql-operator/blob/main/internal/logicalreplica/postgres.go"
click node_pgupgrade "https://github.com/percona/percona-postgresql-operator/blob/main/internal/controller/pgupgrade/pgupgrade_controller.go"
click node_percona_upgrade "https://github.com/percona/percona-postgresql-operator/blob/main/percona/controller/pgupgrade/controller.go"
click node_backup "https://github.com/percona/percona-postgresql-operator/blob/main/percona/controller/pgbackup/controller.go"
click node_restore "https://github.com/percona/percona-postgresql-operator/blob/main/percona/controller/pgrestore/controller.go"
click node_pgbackrest "https://github.com/percona/percona-postgresql-operator/blob/main/internal/pgbackrest/reconcile.go"
click node_pgadmin "https://github.com/percona/percona-postgresql-operator/blob/main/internal/controller/standalone_pgadmin/controller.go"
click node_monitoring "https://github.com/percona/percona-postgresql-operator/blob/main/internal/pgmonitor/exporter.go"
click node_pmm "https://github.com/percona/percona-postgresql-operator/blob/main/percona/pmm/pmm.go"
click node_certs "https://github.com/percona/percona-postgresql-operator/blob/main/percona/certmanager/certmanager.go"
click node_bridge "https://github.com/percona/percona-postgresql-operator/blob/main/internal/bridge/crunchybridgecluster/crunchybridgecluster_controller.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_operator,node_api,node_user toneBlue
class node_legacy_cluster,node_percona_cluster,node_postgres,node_patroni,node_logical_replica,node_kube toneAmber
class node_pgupgrade,node_percona_upgrade,node_backup,node_restore,node_pgbackrest,node_bridge_api toneMint
class node_pgadmin,node_monitoring,node_pmm,node_certs,node_bridge toneRose
```

## Components

### Operator control plane

- [Operator process](https://github.com/percona/percona-postgresql-operator/blob/main/cmd/postgres-operator/main.go): `cmd/postgres-operator/main.go`
- [Custom resources](https://github.com/percona/percona-postgresql-operator/blob/main/pkg/apis/pgv2.percona.com/v2/perconapgcluster_types.go): `pkg/apis/pgv2.percona.com/v2/perconapgcluster_types.go`

### Cluster lifecycle

- [PostgresCluster reconcile](https://github.com/percona/percona-postgresql-operator/blob/main/internal/controller/postgrescluster/controller.go): `internal/controller/postgrescluster/controller.go`
- [PerconaPGCluster reconcile](https://github.com/percona/percona-postgresql-operator/blob/main/percona/controller/pgcluster/controller.go): `percona/controller/pgcluster/controller.go`
- [PostgreSQL configuration](https://github.com/percona/percona-postgresql-operator/blob/main/internal/postgres/reconcile.go): `internal/postgres/reconcile.go`
- [HA orchestration](https://github.com/percona/percona-postgresql-operator/blob/main/internal/patroni/reconcile.go): `internal/patroni/reconcile.go`
- [Logical replication](https://github.com/percona/percona-postgresql-operator/blob/main/internal/logicalreplica/postgres.go): `internal/logicalreplica/postgres.go`

### Data operations

- [Cluster upgrade](https://github.com/percona/percona-postgresql-operator/blob/main/internal/controller/pgupgrade/pgupgrade_controller.go): `internal/controller/pgupgrade/pgupgrade_controller.go`
- [Percona upgrade](https://github.com/percona/percona-postgresql-operator/blob/main/percona/controller/pgupgrade/controller.go): `percona/controller/pgupgrade/controller.go`
- [Backup controller](https://github.com/percona/percona-postgresql-operator/blob/main/percona/controller/pgbackup/controller.go): `percona/controller/pgbackup/controller.go`
- [Restore controller](https://github.com/percona/percona-postgresql-operator/blob/main/percona/controller/pgrestore/controller.go): `percona/controller/pgrestore/controller.go`
- [Backup tooling](https://github.com/percona/percona-postgresql-operator/blob/main/internal/pgbackrest/reconcile.go): `internal/pgbackrest/reconcile.go`

### Cluster integrations

- [PGAdmin management](https://github.com/percona/percona-postgresql-operator/blob/main/internal/controller/standalone_pgadmin/controller.go): `internal/controller/standalone_pgadmin/controller.go`
- [Monitoring exporter](https://github.com/percona/percona-postgresql-operator/blob/main/internal/pgmonitor/exporter.go): `internal/pgmonitor/exporter.go`
- [PMM integration](https://github.com/percona/percona-postgresql-operator/blob/main/percona/pmm/pmm.go): `percona/pmm/pmm.go`
- [Certificate management](https://github.com/percona/percona-postgresql-operator/blob/main/percona/certmanager/certmanager.go): `percona/certmanager/certmanager.go`
- [Crunchy Bridge integration](https://github.com/percona/percona-postgresql-operator/blob/main/internal/bridge/crunchybridgecluster/crunchybridgecluster_controller.go): `internal/bridge/crunchybridgecluster/crunchybridgecluster_controller.go`

### Other components

- **Kubernetes user**
- **Kubernetes API**
- **Crunchy Bridge API**

## Connections

- Kubernetes user → Custom resources: submits
- Custom resources → Kubernetes API: stored in
- Operator process → Kubernetes API: watches resources
- Operator process → PostgresCluster reconcile: registers controller (evidence: `cmd/postgres-operator/main.go`)
- Operator process → PerconaPGCluster reconcile: registers controller (evidence: `cmd/postgres-operator/main.go`)
- PostgresCluster reconcile → PostgreSQL configuration: uses (evidence: `internal/controller/postgrescluster/controller.go`)
- PostgresCluster reconcile → HA orchestration: uses (evidence: `internal/controller/postgrescluster/controller.go`)
- PostgresCluster reconcile → Logical replication: uses (evidence: `internal/controller/postgrescluster/controller.go`)
- PerconaPGCluster reconcile → PostgreSQL configuration: uses (evidence: `percona/controller/pgcluster/controller.go`)
- PerconaPGCluster reconcile → Cluster upgrade: watches upgrades
- Percona upgrade → PerconaPGCluster reconcile: updates cluster (evidence: `percona/controller/pgupgrade/controller.go`)
- Backup controller → PerconaPGCluster reconcile: reads cluster (evidence: `percona/controller/pgbackup/controller.go`)
- Backup controller → Backup tooling: uses
- Restore controller → PerconaPGCluster reconcile: reads cluster (evidence: `percona/controller/pgrestore/controller.go`)
- Restore controller → Backup tooling: uses
- PerconaPGCluster reconcile → PGAdmin management: configures alongside
- PerconaPGCluster reconcile → Monitoring exporter: configures alongside
- PerconaPGCluster reconcile → PMM integration: integrates (evidence: `percona/controller/pgcluster/controller.go`)
- PerconaPGCluster reconcile → Certificate management: uses (evidence: `percona/certmanager/certmanager.go`)
- Operator process → Crunchy Bridge integration: registers controller (evidence: `cmd/postgres-operator/main.go`)
- Crunchy Bridge integration → Crunchy Bridge API: creates clusters (evidence: `internal/bridge/crunchybridgecluster/crunchybridgecluster_controller.go`)
- PostgresCluster reconcile → Kubernetes API: reconciles resources (evidence: `internal/controller/postgrescluster/controller.go`)
- PerconaPGCluster reconcile → Kubernetes API: reconciles resources (evidence: `percona/controller/pgcluster/controller.go`)