Deploying a PostgreSQL Cluster with TLS on KubeBlocks

This guide demonstrates how to deploy a PostgreSQL cluster with TLS encryption using KubeBlocks. Transport Layer Security (TLS) ensures secure communication between PostgreSQL clients and servers by encrypting data in transit, protecting sensitive information from interception. You'll learn how to:

• Deploy a PostgreSQL cluster with TLS enabled
• Establish secure connections using different TLS modes
• Verify the TLS configuration
• Clean up resources after testing

Prerequisites

Before proceeding, ensure the following:

• Environment Setup:
  • A Kubernetes cluster is up and running.
  • The kubectl CLI tool is configured to communicate with your cluster.
  • KubeBlocks CLI and KubeBlocks Operator are installed. Follow the installation instructions here.
• Namespace Preparation: To keep resources isolated, create a dedicated namespace for this tutorial:

kubectl create ns demo
namespace/demo created

Deploying the PostgreSQL Replication Cluster

KubeBlocks uses a declarative approach for managing PostgreSQL clusters. Below is a configuration example for deploying a PostgreSQL cluster with TLS enabled (1 primary, 1 replica):

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: pg-cluster
  namespace: demo
spec:
  terminationPolicy: Delete
  clusterDef: postgresql
  topology: replication
  componentSpecs:
    - name: postgresql
      serviceVersion: 16.4.0
      tls: true  # Enable TLS encryption
      issuer:
        name: KubeBlocks  # Use KubeBlocks' built-in certificate authority
      labels:
        apps.kubeblocks.postgres.patroni/scope: pg-cluster-postgresql
      disableExporter: true
      replicas: 2
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 20Gi

Key Configuration Fields:

• tls: true: Enables TLS encryption for all connections
• issuer: KubeBlocks: Uses KubeBlocks' built-in certificate authority (alternatively: UserProvided for custom certificates)

Verifying the Deployment

Monitor the cluster status until it reaches the Running state:

kubectl get cluster pg-cluster -n demo -w

Expected Output:

NAME         CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS     AGE
pg-cluster   postgresql           Delete               Creating   50s
pg-cluster   postgresql           Delete               Running    4m2s

Verify TLS configuration on PostgreSQL instances:

postgres=# show ssl;
 ssl
-----
 on
(1 row)

postgres=# show ssl_ca_file;
     ssl_ca_file
---------------------
 /etc/pki/tls/ca.pem
(1 row)

postgres=# show ssl_cert_file;
     ssl_cert_file
----------------------
 /etc/pki/tls/cert.pem
(1 row)

postgres=# show ssl_key_file;
     ssl_key_file
---------------------
 /etc/pki/tls/key.pem
(1 row)

Verify TLS certificates generated by KubeBlocks:

kubectl get secret -l app.kubernetes.io/instance=pg-cluster -n demo | grep tls

Expected Output:

pg-cluster-postgresql-tls-certs                  Opaque   3      24m

Accessing PostgreSQL Cluster Securely

Step 1: Retrieve Credentials

KubeBlocks creates a Secret containing PostgreSQL credentials:

NAME=$(kubectl get secret -n demo pg-cluster-postgresql-account-postgres -o jsonpath='{.data.username}' | base64 --decode)
PASSWD=$(kubectl get secret -n demo pg-cluster-postgresql-account-postgres -o jsonpath='{.data.password}' | base64 --decode)

Step 2: Connect Using TLS

Forward PostgreSQL port locally:

kubectl port-forward svc/pg-cluster-postgresql-postgresql 5432:5432 -n demo

psql "host=127.0.0.1 dbname=postgres user=${NAME} password=${PASSWD} sslmode=require"

SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: none)
Type "help" for help.

postgres=#

kubectl get -n demo secrets pg-cluster-postgresql-tls-certs -oyaml | yq '.data."ca.pem"' | base64 -d > /tmp/ca.crt

psql "host=127.0.0.1 dbname=postgres user=${NAME} password=${PASSWD} sslmode=verify-full sslrootcert=/tmp/ca.crt"

SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: none)
Type "help" for help.

postgres=#

Cleanup

Remove all tutorial resources:

kubectl delete cluster pg-cluster -n demo
kubectl delete ns demo

Summary

In this guide, you learned how to:

1. Deploy a PostgreSQL cluster with TLS encryption using KubeBlocks
2. Verify TLS configuration and certificate generation
3. Establish secure connections using different TLS modes:
   • require: Basic encryption
   • verify-full: Full certificate validation