Create PostgreSQL Cluster With Custom Password on KubeBlocks

This guide demonstrates how to deploy a PostgreSQL cluster in KubeBlocks with a custom root password stored in a Kubernetes Secret.

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 an example configuration for deploying a PostgreSQL cluster with 2 nodes (1 primary, 1 replicas) and a custom root password.

Step 1: Create a Secret for the Root Account

The custom root password is stored in a Kubernetes Secret. Create the Secret by applying the following YAML:

apiVersion: v1
data:
  password: Y3VzdG9tcGFzc3dvcmQ= # custompassword
  username: cm9vdA== #root
immutable: true
kind: Secret
metadata:
  name: custom-pg-secret
  namespace: demo

• password: Replace custompassword with your desired password and encode it using Base64 (echo -n "custompassword" | base64).
• username: The default PostgreSQL postgres user is 'root', encoded as 'cm9vdA=='.

Step 2: Deploy the PostgreSQL Cluster

Apply the following manifest to deploy the PostgreSQL cluster, referencing the Secret created in Step 1 for the root account:

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
      labels:
        apps.kubeblocks.postgres.patroni/scope: pg-cluster-postgresql
      disableExporter: true
      replicas: 2
      systemAccounts:
        - name: postgres
          secretRef:
            name: custom-pg-secret
            namespace: demo
      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

Explanation of Key Fields

• systemAccounts: Overrides system accounts defined in the referenced ComponentDefinition.

To get the of accounts:

kubectl get cmpd postgresql-16-1.0.0         -oyaml | yq '.spec.systemAccounts[].name'

Expected Output:

postgres
kbadmin
...

Verifying the Deployment

Monitor the cluster status until it transitions to 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

Once the cluster status becomes Running, your PostgreSQL cluster is ready for use.

Connecting to the PostgreSQL Cluster

KubeBlocks automatically creates a secret containing the PostgreSQL postgres credentials. Retrieve the credentials with the following commands:

kubectl get secrets -n demo pg-cluster-postgresql-account-postgres -o jsonpath='{.data.password}' | base64 -d
custompassword

To connect to the cluster's primary node, use the PostgreSQL client with the custom password:

kubectl exec -it -n demo pg-cluster-postgresql-0 -c postgresql -- env PGUSER=postgres PGPASSWORD=custompassword psql

Cleanup

To remove all created resources, delete the PostgreSQL cluster along with its namespace:

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

Summary

In this guide, you:

• Created a Kubernetes Secret to securely store a custom PostgreSQL postgres password.
• Deployed a PostgreSQL cluster in KubeBlocks with a custom root password.
• Verified the deployment and connected to the cluster's primary node using the PostgreSQL client.

Using Kubernetes Secrets ensures secure credential management for your PostgreSQL clusters, while KubeBlocks simplifies the deployment and management process.