Install Percona Distribution for PostgreSQL on Kubernetes¶

Following steps will allow you to install the Operator and use it to manage Percona Distribution for PostgreSQL in a Kubernetes-based environment.

First of all, clone the percona-postgresql-operator repository:
```
$ git clone -b v2.7.0 https://github.com/percona/percona-postgresql-operator
$ cd percona-postgresql-operator
```
Note

It is crucial to specify the right branch with -b option while cloning the code on this step. Please be careful.
The Custom Resource Definition for Percona Distribution for PostgreSQL should be created from the deploy/crd.yaml file. Custom Resource Definition extends the standard set of resources which Kubernetes “knows” about with the new items (in our case ones which are the core of the Operator). Apply it as follows:
```
$ kubectl apply --server-side -f deploy/crd.yaml
```
This step should be done only once; it does not need to be repeated with any other Operator deployments.
Create the Kubernetes namespace for your cluster if needed (for example, let’s name it postgres-operator):
```
$ kubectl create namespace postgres-operator
```
Note

To use a different namespace, specify another name instead of postgres-operator in the above command, and modify the -n postgres-operator parameter with it in the following two steps. You can also omit this parameter completely to deploy everything in the default namespace.
The role-based access control (RBAC) for Percona Distribution for PostgreSQL is configured with the deploy/rbac.yaml file. Role-based access is based on defined roles and the available actions which correspond to each role. The role and actions are defined for Kubernetes resources in the yaml file. Further details about users and roles can be found in Kubernetes documentation .
```
$ kubectl apply -f deploy/rbac.yaml -n postgres-operator
```
Note

Setting RBAC requires your user to have cluster-admin role privileges. For example, those using Google Kubernetes Engine can grant user needed privileges with the following command:
```
$ kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud config get-value core/account)
```
Start the Operator within Kubernetes:
```
$ kubectl apply -f deploy/operator.yaml -n postgres-operator
```
Optionally, you can add PostgreSQL Users secrets and TLS certificates to Kubernetes. If you don’t, the Operator will create the needed users and certificates automatically, when you create the database cluster. You can see documentation on Users and TLS certificates if still want to create them yourself.
After the Operator is started Percona Distribution for PostgreSQL cluster can be created at any time with the following command:
```
$ kubectl apply -f deploy/cr.yaml -n postgres-operator
```
The creation process may take some time. When the process is over your cluster will obtain the ready status. You can check it with the following command:
```
$ kubectl get pg -n postgres-operator
```
Expected output
```
NAME       ENDPOINT                         STATUS   POSTGRES   PGBOUNCER   AGE
cluster1   cluster1-pgbouncer.default.svc   ready    3          3           30m
```

Verifying the cluster operation¶

When creation process is over, the output of the kubectl get pg command shows the cluster status as ready. You can now 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.5.2 --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.5.2)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.
pgdb=>

Deleting the cluster¶

If you need to delete the cluster (for example, to clean up the testing deployment before adopting it for production use), check this HowTo.

Last update: 2025-07-18