clusterdatabase-as-a-servicedata-infrastructuregolangkubernetesmanaged-servicesoperatorpostgrespostgres-operatorpostgresql
29168ca0bc
Upgrading to v2.0.0 fails at the CRD apply step. The apiserver rejects the
OperatorConfiguration CRD:
CustomResourceDefinition "operatorconfigurations.acid.zalan.do" is invalid:
...oauth_token_secret_name.default: Invalid value: "string": in body must
be of type object
Root cause: these CRDs are generated by controller-gen from the Go types.
spec.NamespacedName is a struct {Namespace, Name}, so controller-gen emits an
object schema for every NamespacedName field. But NamespacedName has custom
MarshalJSON/UnmarshalJSON that (de)serialize it as a plain JSON string
("namespace/name"). The generated object schema therefore never matched how
the operator actually reads and writes these fields (it did in 1.15.x, where
they were type: string).
For oauth_token_secret_name this is a hard failure: it also carries
`// +kubebuilder:default=postgres-operator`, and a scalar string default on an
object-typed property is rejected by the apiserver, blocking the whole
1.15.x -> 2.0.0 upgrade before the operator Deployment is touched.
Fix at the source by annotating the NamespacedName type with
`// +kubebuilder:validation:Type=string` and regenerating the CRDs. This makes
controller-gen emit `type: string` for all NamespacedName fields
(oauth_token_secret_name, infrastructure_roles_secret_name,
pod_environment_configmap, and the nested infrastructure role secretname),
matching their runtime serialization and restoring 1.15.x behaviour. A
field-level Type override cannot be used here: it conflicts with the
struct-derived schema ("object vs string in allOf") and fails generation.
Regenerated manifests/operatorconfiguration.crd.yaml and its two synced
copies (pkg/apis/... embed source and charts/.../crds). Verified with a
server-side dry-run apply: the unpatched CRD is rejected, the regenerated CRD
is accepted.
Fixes #3143
|
||
|---|---|---|
| .github | ||
| charts | ||
| cmd | ||
| docker | ||
| docs | ||
| e2e | ||
| hack | ||
| logical-backup | ||
| manifests | ||
| mocks | ||
| pkg | ||
| pooler | ||
| ui | ||
| .flake8 | ||
| .gitignore | ||
| .golangci.yml | ||
| .zappr.yaml | ||
| CODEOWNERS | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| MAINTAINERS | ||
| Makefile | ||
| README.md | ||
| SECURITY.md | ||
| build-ci.sh | ||
| delivery.yaml | ||
| go.mod | ||
| go.sum | ||
| mkdocs.yml | ||
| run_operator_locally.sh | ||
README.md
Postgres Operator
The Postgres Operator delivers an easy to run highly-available PostgreSQL clusters on Kubernetes (K8s) powered by Patroni. It is configured only through Postgres manifests (CRDs) to ease integration into automated CI/CD pipelines with no access to Kubernetes API directly, promoting infrastructure as code vs manual operations.
Operator features
- Rolling updates on Postgres cluster changes, incl. quick minor version updates
- Live volume resize without pod restarts (AWS EBS, PVC)
- Database connection pooling with PGBouncer
- Support fast in place major version upgrade. Supports global upgrade of all clusters.
- Pod protection during bootstrap phase and configurable maintenance windows
- Restore and cloning Postgres clusters on AWS, GCS and Azure
- Additionally logical backups to S3 or GCS bucket can be configured
- Standby cluster from S3 or GCS WAL archive or remote host
- Configurable for non-cloud environments
- Basic credential and user management on K8s, eases application deployments
- Support for custom TLS certificates
- UI to create and edit Postgres cluster manifests
- Compatible with OpenShift
- Multi-arch support
PostgreSQL features
- Supports PostgreSQL 18, starting from 14+
- Streaming replication cluster via Patroni
- Point-In-Time-Recovery with pg_basebackup / WAL-G or WAL-E via Spilo
- Preload libraries: bg_mon, pg_stat_statements, pgextwlist, pg_auth_mon
- Incl. popular Postgres extensions such as decoderbufs, hypopg, pg_cron, pg_repack, pg_partman, pg_stat_kcache, pg_audit, pgfaceting, pgq, pgvector, plpgsql_check, plproxy, postgis, roaringbitmap, set_user and timescaledb
The Postgres Operator has been developed at Zalando and is being used in production for over five years.
Supported Postgres & K8s versions
| Release | Postgres versions | K8s versions | Golang |
|---|---|---|---|
| v2.0.0 | 14 → 18 | 1.27+ | 1.26.4 |
| v1.15.1 | 13 → 17 | 1.27+ | 1.25.3 |
| v1.14.0 | 13 → 17 | 1.27+ | 1.23.4 |
| v1.13.0 | 12 → 16 | 1.27+ | 1.22.5 |
| v1.12.0 | 11 → 16 | 1.27+ | 1.22.3 |
| v1.11.0 | 11 → 16 | 1.27+ | 1.21.7 |
Getting started
For a quick first impression follow the instructions of this tutorial.
Migrating from v1 to v2 operator
If you have been using Postgres Operator since v1.x (thank you), make sure you have read the migration docs before deploying a v2 operator.
Documentation
There is a browser-friendly version of this documentation at postgres-operator.readthedocs.io