Quick Start Guide to Using Zalando Postgres Operator on a Local Kubernetes Cluster

Prerequisites

Postgres Operator runs on Kubernetes. For local testing use one of:

minikube – single‑node cluster in a VM (requires KVM or VirtualBox). URL: https://github.com/kubernetes/minikube/releases

kind and k3d – multi‑node clusters on Docker. URLs: https://kind.sigs.k8s.io/ and https://k3d.io

Install the Kubernetes CLI kubectl. Installation guide: https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-curl

Assume a running minikube or kind cluster, or Docker Desktop’s built‑in Kubernetes.

Configuration Options

Configuration must be applied before creating a Postgres cluster. Supply it via a ConfigMap or an OperatorConfiguration custom resource. Reference: https://postgres-operator.readthedocs.io/en/latest/reference/operator_parameters/

Deployment Options

The operator can be installed by:

Manual YAML deployment

Kustomization

Helm chart

Kubernetes manual deployment

Clone the repository and apply the manifests in order:

# Clone repository
git clone https://github.com/zalando/postgres-operator.git
cd postgres-operator

# Apply manifests
kubectl create -f manifests/configmap.yaml
kubectl create -f manifests/operator-service-account-rbac.yaml
kubectl create -f manifests/postgres-operator.yaml
kubectl create -f manifests/api-service.yaml

A combined Kustomization (excluding CRDs) works with kubectl 1.14 or newer:

kubectl apply -k github.com/zalando/postgres-operator/manifests

The helper script run_operator_locally.sh starts the operator on minikube and applies the acid-minimal-cluster manifest.

./run_operator_locally.sh

OpenShift manual deployment

Set the parameter kubernetes_use_configmaps=true to avoid using unsupported Endpoints for leader and key storage.

oc create -f manifests/operator-service-account-rbac-openshift.yaml

Helm chart deployment

After cloning the repo, install the chart with Helm 3:

helm install postgres-operator ./charts/postgres-operator

The chart also works with Helm 2; when using Helm 3 the crd-install hook is skipped with a warning. Chart repository: https://opensource.zalando.com/postgres-operator/charts/postgres-operator/

Verify operator is running

Wait a few seconds after starting the operator, then check the pod:

# For YAML deployment
kubectl get pod -l name=postgres-operator

# For Helm deployment
kubectl get pod -l app.kubernetes.io/name=postgres-operator

If the pod is not Running, inspect the deployment or pod events with kubectl describe and view logs:

kubectl logs "$(kubectl get pod -l name=postgres-operator -o name)"

Deploy the Operator UI

Apply the UI manifests or use its Helm chart:

# Manual deployment
kubectl apply -f ui/manifests/

# Kustomization
kubectl apply -k github.com/zalando/postgres-operator/ui/manifests

# Helm chart
helm install postgres-operator-ui ./charts/postgres-operator-ui

Check the UI pod is Running (same label selectors as the operator) and port‑forward to access the UI at localhost:8081:

kubectl port-forward svc/postgres-operator-ui 8081:80

Create a Postgres cluster

With the operator pod running, submit a cluster manifest (example: manifests/minimal-postgres-manifest.yaml).

kubectl create -f manifests/minimal-postgres-manifest.yaml

The operator creates a Service, Endpoint, and a StatefulSet that launches Pods named with numeric suffixes (e.g., -0) using the Spilo container image. Verify resources:

# List Postgresql custom resources
kubectl get postgresql

# List database pods
kubectl get pods -l application=spilo -L spilo-role

# List services
kubectl get svc -l application=spilo -L spilo-role

Connect with psql

Port‑forward the service to obtain host and port, export the password from the generated secret, and enforce SSL:

export HOST_PORT=$(minikube service acid-minimal-cluster --url | sed 's,.*/,,' )
export PGHOST=$(echo $HOST_PORT | cut -d: -f1)
export PGPORT=$(echo $HOST_PORT | cut -d: -f2)

export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials -o jsonpath='{.data.password}' | base64 -d)
export PGSSLMODE=require
psql -U postgres

Delete the Postgres cluster

Remove the custom resource:

kubectl delete postgresql acid-minimal-cluster

This deletes the associated StatefulSet, Pods, Services, Endpoints, and releases the PersistentVolume and PodDisruptionBudget. Secrets remain and backups are retained. If deletion occurs while the cluster is still starting, orphaned components may remain; in that case delete the local minikube or kind cluster and start over. Issue reference: https://github.com/zalando/postgres-operator/issues/551