Skip to main content
Feature gates let you enable or disable individual capabilities of PGO that are not yet generally available. Each gate has a maturity stage — Alpha or Beta — which determines whether it is on or off by default. You can override any gate at operator startup without recompiling the binary.

​
How feature gates work

PGO follows the Kubernetes feature gate convention:
  • Alpha gates are disabled by default. They may have incomplete implementations, lack tests, or change behavior in future releases. Enable them explicitly when you want to try them.
  • Beta gates are enabled by default. They have been tested more broadly and are considered stable enough for most environments, but their behavior or API may still change before they graduate to stable.
The operator reads the gate configuration once at startup. Changing the value requires restarting the operator pod.

​
Configuring feature gates

Set the PGO_FEATURE_GATES environment variable on the operator deployment. The value is a comma-separated list of FeatureName=true or FeatureName=false pairs.
You can also confirm what is active at runtime by inspecting the operator logs immediately after startup. PGO logs two values:
  • PGO_FEATURE_GATES — the gates you explicitly set.
  • enabled — all gates that are currently active, including those that are on by default.

​
Feature gate table

Enabling an Alpha feature in production carries risk. Alpha features may be removed, renamed, or changed in a breaking way in any subsequent release.

​
Feature-by-feature notes

​
AppendCustomQueries

When disabled (the default), supplying a queries.yml file through spec.monitoring.pgmonitor.exporter.configuration replaces the built-in pgMonitor query set. When this gate is enabled, custom queries are appended to the defaults instead. See monitoring for how to supply custom query files.

​
AutoCreateUserSchema

When this Beta gate is enabled (default), PGO creates a schema matching the username whenever it provisions a new database user. Disable it if your application expects to manage schemas itself or if your security policy prohibits automatic DDL execution.

​
AutoGrowVolumes

Requires that the StorageClass backing your PVCs has allowVolumeExpansion: true. When enabled, PGO detects usage thresholds and patches the PVC resources.requests.storage field to trigger an online resize. See resize cluster for manual resize steps.

​
InstanceSidecars

Exposes spec.instances[].sidecars in the PostgresCluster API. Use it to inject logging agents, proxy sidecars, or other tooling that needs to run alongside the PostgreSQL process. Container ports, volume mounts, and environment variables can all be configured on the sidecar spec.

​
OpenTelemetryLogs and OpenTelemetryMetrics

Both gates depend on the crunchy-collector image, which bundles the OpenTelemetry Collector Contrib distribution (version 0.147.0 at build time). Enable OpenTelemetryLogs to ship structured logs and OpenTelemetryMetrics to emit Prometheus-compatible metrics through the collector pipeline. Configure the pipeline via spec.instrumentation.

​
PGBouncerSidecars

Mirrors InstanceSidecars for the pgBouncer proxy pods. Enable it when you need to run a custom sidecar — for example a metrics adapter or network proxy — alongside each pgBouncer instance.

​
PGUpgradeCPUConcurrency

When this Beta gate is enabled (default), PGO calculates the --jobs argument for pg_upgrade based on the CPU request or limit set on the PGUpgrade pod. Disable it to let pg_upgrade use its default single-job mode regardless of available CPU.

​
TablespaceVolumes

Enables the spec.tablespaces field on PostgresCluster. Each tablespace entry creates a dedicated PVC and mounts it at the correct path inside the PostgreSQL container. See tablespaces for the full workflow.

​
VolumeSnapshots

Integrates PGO backup scheduling with the Kubernetes VolumeSnapshot API. Requires that your cluster has a CSI driver that supports the VolumeSnapshot CRD. This feature is independent of the pgBackRest backup integration.

Monitoring guide

Configure pgMonitor, custom queries, and OpenTelemetry metrics.

Tablespaces guide

Set up dedicated volumes for PostgreSQL tablespaces.

Resize cluster

Manually adjust storage and enable AutoGrowVolumes.

Components reference

Container image inventory and component versions.