How to Create, Connect, and Delete a PostgreSQL Cluster with CrunchyData PGO (Cloud‑Native)

Prerequisites

Fork the Postgres Operator example repository at https://github.com/CrunchyData/postgres-operator-examples and clone it locally. Install the PGO components into the postgres-operator namespace:

kubectl apply -k kustomize/install

Create a PostgreSQL Cluster

Apply the example manifest in kustomize/postgres: kubectl apply -k kustomize/postgres This creates a PostgresCluster custom resource named hippo in the postgres-operator namespace. Track its status with:

kubectl -n postgres-operator describe postgresclusters.postgres-operator.crunchydata.com hippo

The underlying postgres.yaml includes:

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
spec:
  image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres:centos8-13.5-0
  postgresVersion: 13
  instances:
  - name: instance1
    dataVolumeClaimSpec:
      accessModes:
      - "ReadWriteOnce"
      resources:
        requests:
          storage: 1Gi
  backups:
    pgbackrest:
      image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbackrest:centos8-2.36-0
      repos:
      - name: repo1
        volume:
          volumeClaimSpec:
            accessModes:
            - "ReadWriteOnce"
            resources:
              requests:
                storage: 1Gi

PGO reads metadata.name to name the cluster, uses spec.image and spec.backups.pgbackrest.image for the PostgreSQL and pgBackRest container images, and respects spec.postgresVersion to select the major PostgreSQL version.

Storage Configuration

The dataVolumeClaimSpec defines the persistent volume for each instance. If spec.instances.dataVolumeClaimSpec.storageClassName is omitted, the default storage class of the Kubernetes environment is used.

Backups

PGO configures pgBackRest for TB‑scale backups. The spec.backups section can target Amazon S3, Google GCS, or Azure Blob storage.

Connecting to the Cluster

PGO creates several Kubernetes services. List them with:

kubectl -n postgres-operator get svc --selector=postgres-operator.crunchydata.com/cluster=hippo

The primary service ( hippo-primary) is the stable endpoint for client connections. Credentials are stored in a secret named hippo-pguser-hippo with the following keys: user: database user name password: user password dbname: default database host: service name of the primary instance port: listening port (5432) uri: full PostgreSQL connection URI jdbc-uri: JDBC connection URI

All connections use TLS with the verify‑full SSL mode. PGO supplies its own Certificate Authority, protecting against MITM attacks; a custom CA can be provided later.

Modifying Service Type

By default services are ClusterIP. To expose the primary service externally, edit the spec.service.type field, for example to NodePort, and re‑apply the manifest:

spec:
  service:
    type: NodePort

Connecting an Application (Keycloak Example)

The tutorial deploys Keycloak, an open‑source identity provider, using the generated secret values. The deployment manifest includes environment variables that reference the secret keys:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: keycloak
  namespace: postgres-operator
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: keycloak
  template:
    metadata:
      labels:
        app.kubernetes.io/name: keycloak
    spec:
      containers:
      - name: keycloak
        image: quay.io/keycloak/keycloak:latest
        env:
        - name: DB_VENDOR
          value: "postgres"
        - name: DB_ADDR
          valueFrom:
            secretKeyRef:
              name: hippo-pguser-hippo
              key: host
        - name: DB_PORT
          valueFrom:
            secretKeyRef:
              name: hippo-pguser-hippo
              key: port
        - name: DB_DATABASE
          valueFrom:
            secretKeyRef:
              name: hippo-pguser-hippo
              key: dbname
        - name: DB_USER
          valueFrom:
            secretKeyRef:
              name: hippo-pguser-hippo
              key: user
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: hippo-pguser-hippo
              key: password
        - name: KEYCLOAK_USER
          value: "admin"
        - name: KEYCLOAK_PASSWORD
          value: "admin"
        - name: PROXY_ADDRESS_FORWARDING
          value: "true"
        ports:
        - name: http
          containerPort: 8080
        - name: https
          containerPort: 8443
        readinessProbe:
          httpGet:
            path: /auth/realms/master
            port: 8080
        restartPolicy: Always

All database connection details are injected from the secret, so no credentials appear in the manifest.

Deleting the Cluster

When the cluster is no longer needed, remove it with: kubectl delete -k kustomize/postgres PGO deletes every object it created. Persistent volume reclamation follows the PVC's reclaimPolicy. For more information on CRDs see https://access.crunchydata.com/documentation/postgres-operator/5.0.4/references/crd/ and on persistent volumes see https://kubernetes.io/docs/concepts/storage/persistent-volumes/.