Skip to main content
XenonStack

DevOps

XenonStack Blog PostgreSQL Deployment on Kubernetes: A Practical Guide

and | Published | Updated

PostgreSQL Deployment on Kubernetes: A Practical Guide
12:55

Key takeaway

  • Deploy PostgreSQL on Kubernetes with a StatefulSet, Secrets and storage, and learn when to move to an operator such as CloudNativePG for failover.

Running PostgreSQL on Kubernetes is a decision about operations, not just packaging. A single pod with a volume is enough to learn on. Production needs a stable identity, durable storage, replication, backups and a tested failover path, and the choice is between building those yourself with a StatefulSet or using a PostgreSQL operator such as CloudNativePG.

This guide shows the minimal manifest pattern, explains what it does not give you, and sets out when to move to an operator. For the wider cluster picture, see our guides to Kubernetes architecture components and Kubernetes deployment tools and practices.

Should you run PostgreSQL on Kubernetes at all?

Kubernetes suits PostgreSQL when your platform team already runs stateful workloads, has a storage class with reliable persistent volumes, and wants one deployment model for applications and data. It suits less well when nobody owns backup, restore and failover testing. A managed database service removes that burden; a self-run database moves it onto your team.

PostgreSQL itself is open source and, according to its about page, has been ACID-compliant since 2001, supports write-ahead logging, asynchronous, synchronous and logical replication, and point-in-time recovery. Those are features of the database; Kubernetes does not add them. It schedules the pods and attaches storage.

Which PostgreSQL version should you deploy?

Deploy a supported major version. According to the PostgreSQL versioning policy, a major version is supported for 5 years after its first release, and each version receives minor releases at least once every three months. The page, read on 13 November 2026, lists these versions:

Major versionFirst releaseFinal releaseStatus when read
1825 September 202514 November 2030Supported
1726 September 20248 November 2029Supported
1614 September 20239 November 2028Supported
1513 October 202211 November 2027Supported
1430 September 202112 November 2026Final release date reached; plan the upgrade
9.6 (older release)29 September 201611 November 2021Unsupported

Older releases such as 9.6 are out of support, so new deployments should use a current major version. The project recommends running the current minor release of whichever major version you choose.

How do you deploy PostgreSQL with a StatefulSet?

A StatefulSet runs a group of pods and, according to the Kubernetes documentation, maintains a sticky identity for each pod, which suits applications that need persistent storage or a stable, unique network identity. That is why a database belongs in a StatefulSet rather than a plain Deployment. Confirm the details of headless Services and volume claim templates on that page for your Kubernetes version.

Step 1. Use the official image

Instead of building your own image from a base operating system, start from the official postgres image on Docker Hub. According to its page, POSTGRES_PASSWORD is required, POSTGRES_USER is optional and defaults to postgres, and PGDATA became version specific from PostgreSQL 18. For version 17 and below the page says to mount the data volume at /var/lib/postgresql/data; from 18 the declared volume is /var/lib/postgresql. Check the tag page for the exact tag you pin.

Step 2. Keep the password in a Secret

Do not put the superuser password in the manifest. Create a Secret and reference it from the pod.

kubectl create secret generic postgres-credentials \
  --namespace production \
  --from-literal=POSTGRES_PASSWORD="$(openssl rand -base64 24)"

Step 3. Create a headless Service and a StatefulSet

The manifest below is an illustrative single-instance pattern for PostgreSQL 18. Replace the storage class and size for your cluster. It uses the stable apps/v1 API; older beta workload APIs such as extensions/v1beta1 are no longer current (confirm on the Kubernetes deprecation guide).

apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: production
spec:
  clusterIP: None
  selector:
    app: postgres
  ports:
    - port: 5432
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
  namespace: production
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:18
          ports:
            - containerPort: 5432
          envFrom:
            - secretRef:
                name: postgres-credentials
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        storageClassName: YOUR_STORAGE_CLASS
        resources:
          requests:
            storage: 20Gi

Step 4. Apply and check

kubectl apply -f postgres.yaml
kubectl -n production get pods -l app=postgres
kubectl -n production exec -it postgres-0 -- psql -U postgres -c "select version();"

Keep the database off public addresses. Avoid a NodePort and avoid allowing connections from 0.0.0.0/0; a ClusterIP or headless Service plus a NetworkPolicy limits access to the applications that need it.

What does a StatefulSet not give you?

A single StatefulSet replica is one database server. It restarts and reattaches its volume, but it has no standby, no automated failover and no backup schedule. PostgreSQL provides the replication building blocks: according to its high availability documentation, a standby that cannot accept connections until promoted is a warm standby, and one that serves read-only queries is a hot standby, and synchronous and asynchronous replication trade data-loss risk against performance. Wiring these together on Kubernetes, and promoting a standby safely, is the work an operator automates.

Two-column diagram comparing a hand-written StatefulSet (identity, Secret, single instance, manual backups) with an operator (failover, replicas, rolling updates, backups)

For a replicated example of a stateful application on Kubernetes, the Kubernetes tutorial on a replicated MySQL StatefulSet shows the pattern, with the note that it is not a production configuration.

When should you use a PostgreSQL operator?

An operator adds a custom resource and a controller that manage the database lifecycle. According to the CloudNativePG project page, CloudNativePG is an open-source operator for PostgreSQL on Kubernetes, a CNCF Incubating project, dedicated to vanilla Kubernetes and vanilla PostgreSQL. It promotes a new primary when the current one fails, creates and removes replicas with their volumes and secrets, keeps service endpoints current, and runs rolling updates by updating replicas first and then switching over the primary. It also manages backup, scheduled backup and pooler resources. For the pattern behind this, see our guide to Kubernetes operators.

OptionFits whenWhat you ownCurrent status
Managed database serviceYou want the least operational workSchema, queries and accessVendor service; confirm features on the vendor page
StatefulSet you writeDevelopment, tests, single non-critical instanceBackups, failover, upgrades, monitoringPlain Kubernetes; no HA by itself
PostgreSQL operator (for example CloudNativePG)Production on Kubernetes with a platform teamStorage class, backup target, restore drills, policyCNCF Incubating project; confirm release and support on its site

How do blue-green deployments apply to a database?

A blue-green strategy uses two environments, one live, the other receiving the new release, with a switch after verification. This works well for stateless application pods. For a database the hard part is the data. Both environments need compatible schemas, so teams usually make schema changes backward compatible first, deploy the application change next, and remove old columns later. For major PostgreSQL upgrades, test the upgrade and a restore on a copy before switching traffic.

What should you check before going to production?

  • Restore a backup into a clean namespace and time it. A backup you have not restored is an assumption.
  • Pin the image tag to a supported major and minor version and plan upgrades before the final release date of your version.
  • Store credentials in Secrets or an external secret manager, and rotate them.
  • Restrict network access with NetworkPolicy and enable TLS between applications and the database.
  • Set resource requests and limits, and alert on replication lag, disk use and failed backups.
  • Test a primary failure on purpose, in a non-production cluster, and record what happens to open connections.

How does governed context help with database operations?

Database changes made by people and by AI agents need the same controls: who may change a schema, which policy applied, and what trace remains. ElixirData keeps governed context, versioned policy and decision traces in one decision layer above AI agents. If teams use plain-language access to data, AgentAnalyst lets teams ask questions of enterprise data in plain language and get real-time insights. For database choice before deployment, read SQL vs NoSQL vs NewSQL.

To map one database decision your agents should make, and the context and policy it depends on, book a Context Workshop. See what happens in the workshop.

Frequently asked questions

Can you run PostgreSQL in Kubernetes?

Yes. A StatefulSet with persistent volumes runs a single instance, and an operator such as CloudNativePG adds failover, replicas and backups. Whether it is the right choice depends on who owns backup, restore and upgrades.

Should PostgreSQL use a Deployment or a StatefulSet?

A StatefulSet, because according to the Kubernetes documentation it maintains a sticky identity for each pod, which suits applications needing persistent storage or a stable network identity.

Which PostgreSQL version should I deploy?

A supported major version. The PostgreSQL project supports each major version for 5 years after first release; versions 14 to 18 were listed as supported when read on 13 November 2026, and 9.6 is unsupported.

Does a StatefulSet give me high availability?

No. One replica has no standby or automated failover. PostgreSQL replication or an operator provides those.

What does CloudNativePG do?

According to its project page it is an open-source Kubernetes operator that handles failover, replica scaling, rolling updates, service endpoints and backup resources for PostgreSQL.

Where should the database password be stored?

In a Kubernetes Secret or an external secret manager, not in the manifest. The official image requires POSTGRES_PASSWORD to be set.

Related reading: Kubernetes architecture and components, Kubernetes consulting services and Kubernetes deployment.

Follow XenonStack on LinkedIn: XenonStack on LinkedIn for new guides on agentic AI, data and platform engineering.

Ready to put AI agents to work? Explore ElixirClaw, the agentic OS platform to build, orchestrate and govern AI agents.

Table of Contents

navdeep-singh-gill

Navdeep Singh Gill

Global CEO and Founder of XenonStack

LinkedIn profile

Navdeep Singh Gill is serving as Chief Executive Officer and Product Architect at XenonStack. He holds expertise in building SaaS Platform for Decentralised Big Data management and Governance, AI Marketplace for Operationalising and Scaling. His incredible experience in AI Technologies and Big Data Engineering thrills him to write about different use cases and its approach to solutions.

Get the latest articles in your inbox

Subscribe Now

Interested in solving your challenges with the XenonStack team?
Get Started

Tell us about you and your priorities so we can prepare the right conversation. It takes about 2 minutes.

Please Select your Industry
Banking
Fintech
Payment Providers
Wealth Management
Discrete Manufacturing
Semiconductor
Machinery Manufacturing / Automation
Appliances / Electrical / Electronics
Elevator Manufacturing
Defense & Space Manufacturing
Computers & Electronics / Industrial Machinery
Motor Vehicle Manufacturing
Food and Beverages
Distillery & Wines
Beverages
Shipping
Logistics
Mobility (EV / Public Transport)
Energy & Utilities
Hospitality
Digital Gaming Platforms
SportsTech with AI
Public Safety - Explosives
Public Safety - Firefighting
Public Safety - Surveillance
Public Safety - Others
Media Platforms
City Operations
Airlines & Aviation
Defense Warfare & Drones
Robotics Engineering
Drones Manufacturing
AI Labs for Colleges
AI MSP / Quantum / AGI Institutes
Retail Apparel and Fashion

Continue