If you are reading this blog post, chances are you’re either curious about Kubernetes Operators, or you’ve specifically decided to install the Percona Operator for PostgreSQL, which I am glad to know!
Suppose your environment isn’t set up yet. In that case, you can use this blog post, Setting Up Your Environment for Kubernetes Operators Using Docker, kubectl, and k3d, to have an environment ready in easy steps.
For this tutorial, we use Percona Operator for PostgreSQL, which automates the management of your PostgreSQL environment, handling creation, modification, and deletion tasks. It uses Kubernetes best practices to save time and ensure a consistent, reliable setup.
In this tutorial, we will install the Percona PostgreSQL Operator and connect it to a PostgreSQL instance.
Install Percona Operator for PostgreSQL
1. First, let’s create the Kubernetes namespace for our cluster. It’s good practice to isolate workloads in Kubernetes by installing the Operator in a custom namespace. For example, let’s name it postgres-operator:
1 | kubectl create namespace postgres-operator |
2. Let’s deploy the Percona PostgreSQL Operator version 2.3.1 into the postgres-operator namespace of our Kubernetes cluster, using the server-side apply method to ensure a smooth and accurate deployment process.
1 | kubectl apply --server-side -f https://raw.githubusercontent.com/percona/percona-postgresql-operator/v2.3.1/deploy/bundle.yaml -n postgres-operator |
At this point, the Operator Pod is up and running. Let’s list the pods. We will see it with “running” status.
1 2 3 4 | kubectl get pods -n postgres-operator NAME READY STATUS RESTARTS AGE percona-postgresql-operator-55fff7dd8b-4pz54 1/1 Running 0 5m43s |
3. Now, it is time to deploy Percona Distribution for the PostgreSQL cluster. For this, we will use the cr.yaml
1 | kubectl apply -f https://raw.githubusercontent.com/percona/percona-postgresql-operator/v2.3.1/deploy/cr.yaml -n postgres-operator |
Check the operator and replica set the Pods’ status.
1 | kubectl get pg -n postgres-operator |
It may take some time to create the Operator. The creation process is over when reporting the ready status:
1 2 | NAME ENDPOINT STATUS POSTGRES PGBOUNCER AGE cluster1 cluster1-pgbouncer.postgres-operator.svc ready 3 3 143m |
We have successfully installed and deployed the Operator in three easy steps. Now, we will connect to the PostgreSQL cluster to begin using our database as usual.
Connect to the PostgreSQL cluster
1 | kubectl get secrets -n postgres-operator |
The Secrets object we target is named cluster1-pguser-cluster1
We will retrieve the pgBouncer URI from your secret, decode it, and pass it as the PGBOUNCER_URI environment variable.
The following example shows how to pass the pgBouncer URI from the default Secret object cluster1-pguser-cluster1:
1 | PGBOUNCER_URI=$(kubectl get secret cluster1-pguser-cluster1 --namespace postgres-operator -o jsonpath='{.data.pgbouncer-uri}' | base64 --decode) |
Now, let’s create a Pod where you start a container with Percona Distribution for PostgreSQL and connect to the database.
The following command does it, naming the Pod pg-client and connecting you to the cluster1 database:
1 | kubectl run -i --rm --tty pg-client --image=perconalab/percona-distribution-postgresql:16 --restart=Never -- psql $PGBOUNCER_URI |
It may take some time to create the Pod and connect to the database.
As a result, you should see the following sample output:
1 2 3 4 5 6 | If you don't see a command prompt, try pressing enter. psql (16.2 - Percona Distribution, server 16.1 - Percona Distribution) SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off) Type "help" for help. cluster1=> |
Congratulations! You have connected to your PostgreSQL cluster. Now, you are ready to create tables and insert data.
We also have the flexibility to connect not only through command-line tools but also using graphical user interface (GUI) clients like pgAdmin. To connect using pgAdmin or similar tools, use the pgBouncer URI you obtained from the secrets in your Kubernetes cluster as your connection endpoint.
For more advanced steps, visit the Quickstart guide: Insert data.
Did you know that our operators are certified by Red Hat? Yes, all our Percona Kubernetes Operators are certified! Check out this advanced tutorial on how to deploy and manage a highly available PostgreSQL cluster on OpenShift.
Learn More About Percona Kubernetes Operators
