Percona Operator for PostgreSQL single-namespace and multi-namespace deployment¶

There are two design patterns that you can choose from when deploying Percona Operator for PostgreSQL and PostgreSQL clusters in Kubernetes:

Namespace-scope - one Operator per Kubernetes namespace,
Cluster-wide - one Operator can manage clusters in multiple namespaces.

This how-to explains how to configure Percona Operator for PostgreSQL for each scenario.

Namespace-scope¶

By default, Percona Operator for PostgreSQL functions in a specific Kubernetes namespace. You can create one during the installation (like it is shown in the installation instructions) or just use the default namespace. This approach allows several Operators to co-exist in one Kubernetes-based environment, being separated in different namespaces:

Normally this is a recommended approach, as isolation minimizes impact in case of various failure scenarios. This is the default configuration of our Operator.

Let’s say you will use a Kubernetes Namespace called percona-db-1.

Clone percona-postgresql-operator repository:

$ git clone -b v2.6.0 https://github.com/percona/percona-postgresql-operator
$ cd percona-postgresql-operator

Create your percona-db-1 Namespace (if it doesn’t yet exist) as follows:
```
$ kubectl create namespace percona-db-1
```

Deploy the Operator using the following command:

$ kubectl apply --server-side -f deploy/bundle.yaml -n percona-db-1

Once Operator is up and running, deploy the database cluster itself:
```
$ kubectl apply -f deploy/cr.yaml -n percona-db-1
```

You can deploy multiple clusters in this namespace.

Add more namespaces¶

What if there is a need to deploy clusters in another namespace? The solution for namespace-scope deployment is to have more than one Operator. We will use the percona-db-2 namespace as an example.

Create your percona-db-2 namespace (if it doesn’t yet exist) as follows:
```
$ kubectl create namespace percona-db-2
```

Deploy the Operator:

$ kubectl apply --server-side -f deploy/bundle.yaml -n percona-db-2

Once Operator is up and running deploy the database cluster itself:
```
$ kubectl apply -f deploy/cr.yaml -n percona-db-2
```
Note

Cluster names may be the same in different namespaces.

Install the Operator cluster-wide¶

Sometimes it is more convenient to have one Operator watching for Percona Distribution for PostgreSQL custom resources in several namespaces.

We recommend running Percona Operator for PostgreSQL in a traditional way, limited to a specific namespace, to limit the blast radius. But it is possible to run it in so-called cluster-wide mode, one Operator watching several namespaces, if needed:

To use the Operator in such cluster-wide mode, you should install it with a different set of configuration YAML files, which are available in the deploy folder and have filenames with a special cw- prefix: e.g. deploy/cw-bundle.yaml.

While using this cluster-wide versions of configuration files, you should set the following information there:

subjects.namespace option should contain the namespace which will host the Operator,
WATCH_NAMESPACE key-value pair in the env section should have value equal to a comma-separated list of the namespaces to be watched by the Operator, and the namespace in which the Operator resides. If this key is set to a blank string, the Operator will watch only the namespace it runs in, which would be the same as single-namespace deployment.

Note

Installing the Operator cluster-wide on OpenShift via the the Operator Lifecycle Manager (OLM) requires making different selections in the OLM web-based UI instead of patching YAML files.

The following simple example shows how to install Operator cluster-wide on Kubernetes.

Clone percona-postgresql-operator repository:

$ git clone -b v2.6.0 https://github.com/percona/percona-postgresql-operator
$ cd percona-postgresql-operator

Let’s say you will use pg-operator namespace for the Operator, and percona-db-1 namespace for the cluster. Create these namespaces, if needed:
```
$ kubectl create namespace pg-operator
$ kubectl create namespace percona-db-1
```

Edit the deploy/cw-bundle.yaml configuration file to make sure it contains proper namespace name for the Operator:

...
subjects:
- kind: ServiceAccount
  name: percona-postgresql-operator
  namespace: pg-operator
...
spec:
  containers:
  - env:
    - name: WATCH_NAMESPACE
      value: "pg-operator,percona-db-1"
...

Apply the deploy/cw-bundle.yaml file with the following command:
```
$ kubectl apply --server-side -f deploy/cw-bundle.yaml -n pg-operator
```
Right now the operator deployed in cluster-wide mode will monitor all namespaces in the cluster, either already existing or newly created ones.

Deploy the cluster in the namespace of your choice:

$ kubectl apply -f deploy/cr.yaml -n percona-db-1

Verifying the cluster operation¶

When creation process is over, you can try to connect to the cluster.

During the installation, the Operator has generated several secrets , including the one with password for default PostgreSQL user. This default user has the same login name as the cluster name.

Use kubectl get secrets command to see the list of Secrets objects. The Secrets object you are interested in is named as <cluster_name>-pguser-<cluster_name> (substitute <cluster_name> with the name of your Percona Distribution for PostgreSQL Cluster). The default variant will be cluster1-pguser-cluster1.

Use the following command to get the password of this user. Replace the <cluster_name> and <namespace> placeholders with your values:

$ kubectl get secret <cluster_name>-<user_name>-<cluster_name> -n <namespace> --template='{{.data.password | base64decode}}{{"\n"}}'

Create a pod and start Percona Distribution for PostgreSQL inside. The following command will do this, naming the new Pod pg-client:
```
$ kubectl run -i --rm --tty pg-client --image=perconalab/percona-distribution-postgresql:17.4 --restart=Never -- bash -il
```
Executing it may require some time to deploy the corresponding Pod.

Run a container with psql tool and connect its console output to your terminal. The following command will connect you as a cluster1 user to a cluster1 database via the PostgreSQL interactive terminal.

[postgres@pg-client /]$ PGPASSWORD='pguser_password' psql -h cluster1-pgbouncer.postgres-operator.svc -p 5432 -U cluster1 cluster1

Sample output

psql (17.4)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.
pgdb=>

Last update: 2025-06-17