Configure the Operator environment variables

You can configure the Percona Operator for PostgreSQL behavior by setting environment variables in the Operator Deployment. You can set them when you install the Operator in the following ways:

• For installations via kubectl, edit the Operator Deployment manifest deploy/operator.yaml or deploy/cw-operator.yaml. Alternatively you can modify the Deployment resource in deploy/bundle.yaml, or deploy/cw-bundle.yaml files.
• For Helm installations you can set environment variables through Helm values when you install the percona/pg-operator chart.
• For installations on OpenShift, you can edit the manifests and aplly them with the oc apply command. If you installed via the Operator Lifecycle Manager (OLM), you can configure environment variables through the OLM subscription.

Available environment variables

LOG_LEVEL

Controls the verbosity of the operator’s logging output. This helps with debugging and monitoring the Operator behavior.

Value type	Default	Example
string	"INFO"	"DEBUG"

Accepted values are:

• "DEBUG" – Most verbose, includes detailed debugging information
• "INFO" – Standard informational messages (default)
• "WARN" – Warning messages only
• "ERROR" – Error messages only

Example configuration:

spec:
  containers:
  - name: percona-postgresql-operator
    env:
    - name: LOG_LEVEL
      value: "DEBUG"

DISABLE_TELEMETRY

Controls whether the Operator sends anonymous telemetry data to Percona. Telemetry helps Percona understand usage patterns and improve the Operator.

Value type	Default	Example
string	"false"	"true"

When set to true, the Operator does not send anonymous telemetry data to Percona.

Learn more about Telemetry.

Example configuration:

spec:
  containers:
  - name: percona-postgresql-operator
    env:
    - name: DISABLE_TELEMETRY
      value: "true"

PGO_FEATURE_GATES

Enables experimental or advanced features in the Operator. Feature gates allow you to opt into specific functionality that may not be enabled by default.

The value needs to be a key-value with comma-separated list of feature gates. By default this variable is not set in the Operator.

Value type	Default	Example
string	"" (empty)	"AutoGrowVolumes=true"

Following feature gates are present as of Operator version 2.8.1:

1. AutoGrowVolumes=true - Enables automatic PVC resize when the storage usage reaches a threshold. The Operator can trigger volume expansion for database data volumes. To learn more, refer to the Scale your cluster chapter.

Example configuration:

spec:
  containers:
  - name: percona-postgresql-operator
    env:
    - name: PGO_FEATURE_GATES
      value: "AutoGrowVolumes=true"

LOG_STRUCTURED

Controls whether the Operator outputs logs in a structured JSON format instead of the plain text. Structured logging is useful for log aggregation tools.

Value type	Default	Example
string	"false"	"true"

When set to "true", the logs are produced in JSON format. When set to "false" or not set at all, the Operator outputs plain text logs. This is the default behavior.

Example configuration:

spec:
  containers:
  - name: percona-postgresql-operator
    env:
    - name: LOG_STRUCTURED
      value: "true"

PGO_WORKERS

Specifies the number of worker threads the Operator uses to process events and reconcile resources. This controls the Operator’s concurrency. Default value is 1.

Value type	Default	Example
string	"1"	"2"

Keep in mind that concurrent reconciliations are done only on different objects. For the same object reconciliation is always done serially, regardless of the value set in PGO_WORKERS. This is defined by how the controller runtime works with the queue to avoid any race conditions or incorrect modification of objects.

To illustrate how it works:

• If you have two PerconaPGCluster objects (A and B) and set PGO_WORKERS=1, a single worker thread will reconcile the clusters serially, one after another.
• If you set PGO_WORKERS=4 but only have one PerconaPGCluster object, the operator still reconciles this object serially.
• If you set PGO_WORKERS=4 and have two PerconaPGCluster objects (A and B), the operator uses two separate threads to reconcile each object in parallel; however, it always processes events for each individual object sequentially.

Example configuration:

spec:
  containers:
  - name: percona-postgresql-operator
    env:
    - name: PGO_WORKERS
      value: "4"

WATCH_NAMESPACE

Specifies which namespaces the Operator watches for Custom Resources (PerconaPGCluster and related resources). This is a critical configuration for determining the Operator’s scope of operation.

Value type	Default	Example
string	Operator’s namespace (from fieldRef)	"pg-operator,percona-db-1" or ""

Accepted values:

• If set to a comma-separated list, the Operator watches those specific namespaces. The namespace list must include the namespace where the Operator itself is deployed. Use this approach for the cluster-wide mode.
• If set to an empty string (""), the Operator watches all namespaces in the Kubernetes cluster (cluster-wide mode).
• If not set explicitly, the value is retrieved from the Deployment’s namespace via fieldRef. In this case, the Operator watches only its own namespace.

When you deploy the Operator in cluster-wide mode, it should be associated with the appropriate ClusterRole.

Example configuration:

spec:
  containers:
  - name: percona-postgresql-operator
    env:
    - name: WATCH_NAMESPACE
      value: "pg-operator,percona-db-1,percona-db-2"

PGO_NAMESPACE

Specifies the Kubernetes namespace where the Operator itself is deployed and runs. The value is set set automatically by Kubernetes from metadata.namespace via a downward API fieldRef.

This variable is used by the Operator to refer objects like Secrets for the normal functioning of the operator.

This is particularly important in cluster-wide deployment scenarios where the Operator manages resources across multiple namespaces.

Example configuration:

spec:
  containers:
  - name: percona-postgresql-operator
    env:
    - name: PGO_NAMESPACE
      value: "pg-operator"

Update environment variables

Using kubectl patch

You can update environment variables in an existing Operator Deployment by applying a patch. To keep existing variables, include the full list in your patch.

1. Get the current environment variables:

   kubectl get deployment percona-postgresql-operator -o jsonpath='{.spec.template.spec.containers[0].env}'
   

2. Edit the output to add or change a variable (for example PGO_WORKERS), then apply a patch with the full env list. Alternatively, patch a single entry by index (see Configure concurrency for a cluster reconciliation).

Using Helm

For Helm installations, set or change environment variables through Helm values (for example logLevel, logStructured, disableTelemetry, watchNamespace, watchAllNamespaces). Refer to the pg-operator chart documentation for the exact value names and syntax. To add variables not exposed by the chart, use a chart value that merges extra env entries if supported, or switch to patching the Deployment after install.

After the update

After you change environment variables, the Operator Pod is restarted so the new configuration takes effect.

---

Last update: February 13, 2026
Created: February 13, 2026