Skip to Content

Quick Guide to Create PostgreSQL pod in Kubernetes

To create a PostgreSQL pod in Kubernetes, you’ll need to define a pod configuration in a YAML file that specifies the PostgreSQL image and any necessary configurations such as environment variables for setting up the database.

Create PostgreSQL pod in Kubernetes

Here’s a basic guide to creating a PostgreSQL pod:

Create a PostgreSQL Pod Configuration File

Create a YAML file, let’s say postgres-pod.yaml, with the following content. This configuration sets up a basic PostgreSQL pod:

apiVersion: v1
kind: Pod
  name: postgres-pod
    app: postgres
    - name: postgres-container
      image: postgres:latest
        - name: POSTGRES_DB
          value: mydatabase
        - name: POSTGRES_USER
          value: myuser
        - name: POSTGRES_PASSWORD
          value: mypassword
        - containerPort: 5432

In this configuration:

  • image: postgres:latest specifies the PostgreSQL image from Docker Hub. You can specify a particular version by replacing latest with the desired version tag.
  • env section is used to set environment variables for the PostgreSQL server. POSTGRES_DB, POSTGRES_USER, and POSTGRES_PASSWORD are common variables used to set up the initial database, user, and password, respectively.
  • containerPort: 5432 exposes PostgreSQL’s default port inside the cluster.

Create the PostgreSQL Pod

With the postgres-pod.yaml file ready, apply it using kubectl:

kubectl apply -f postgres-pod.yaml

This command will create the pod based on the specifications in the YAML file.

Verify the Pod Status

Check if the PostgreSQL pod is running:

kubectl get pods

You should see your postgres-pod listed in the output. Initially, it might be in the ContainerCreating state, but it should soon change to Running.

Additional Considerations

  • Persistence: Pods are ephemeral, and restarting a pod will lose the data unless you use persistent storage. Consider using a PersistentVolume (PV) and PersistentVolumeClaim (PVC) to ensure data persistence.
  • Security: Avoid using hardcoded sensitive data (like POSTGRES_PASSWORD) in the YAML file. Use Kubernetes Secrets instead.
  • Deployment: For production environments, instead of directly creating a pod, consider using higher-level objects like Deployments or StatefulSets, which provide features like self-healing, scalability, and easier management.
  • Service: To access the PostgreSQL database from other pods within the Kubernetes cluster, you should create a Kubernetes Service that points to your PostgreSQL pod.

This example provides a basic setup. Depending on your requirements, you might need to customize the configuration, for instance, by adjusting resource limits, setting up volumes for data persistence, or configuring network policies for security.

Verify the Postgres access in Kubernetes

Verifying database access, especially in a Kubernetes environment, involves several steps. For a PostgreSQL database running in a pod, you would typically:

  1. Ensure the Pod is Running: First, make sure that the PostgreSQL pod is running by using kubectl get pods.
  2. Access the PostgreSQL Pod: Use kubectl exec to access the PostgreSQL pod and connect to the database using the PostgreSQL command-line tool psql.
  3. Verify Connection and Access Inside the Pod: Once inside the pod, use psql to connect to your database and perform operations like listing tables to verify access.

Here’s a step-by-step guide to verify database access:

Step 1: Check Pod Status

Make sure the PostgreSQL pod is running:

kubectl get pods

Look for your PostgreSQL pod (e.g., postgres-pod) and ensure its status is Running.

Step 2: Access the PostgreSQL Pod

Use kubectl exec to start an interactive shell session inside your PostgreSQL pod:

kubectl exec -it postgres-pod -- bash

Replace postgres-pod with the name of your PostgreSQL pod. This command opens a Bash session inside the pod.

Step 3: Connect to the PostgreSQL Database

Within the pod, connect to your PostgreSQL database using the psql command-line tool. Use the environment variables you set up (like POSTGRES_DB, POSTGRES_USER).

psql -U myuser -d mydatabase

Replace myuser with your PostgreSQL username and mydatabase with the name of your database. If you didn’t set a specific database and user, you might use the default ones provided by the PostgreSQL image.

Step 4: Verify Access and Perform Operations

Once connected to the database, you can perform various operations to verify access. For example, list all databases:


Or list tables in the current database:


If you can successfully list databases and tables, your database access is verified.

Step 5: Exit

After verification, you can exit psql by typing:


And then exit the pod’s shell session by typing exit.

Additional Tips

  • Use Kubernetes Secrets: For production environments, it’s better to use Kubernetes Secrets for sensitive data like database passwords, and inject them into your pods as environment variables.
  • Persistent Storage: Ensure your database data is stored on a PersistentVolume to survive pod restarts.
  • Database Client: If you have a PostgreSQL client installed locally, you can also port-forward the PostgreSQL service from Kubernetes to your local machine and connect using the local client for verification.
  • Networking and Policies: Ensure network policies and pod security policies allow the necessary communication and access levels you need.

This approach helps verify that the database is running correctly within Kubernetes and that you have the necessary access to perform database operations.

The PostgreSQL image, when used in Kubernetes, is a containerized representation of the PostgreSQL database server. This image is typically pulled from a container registry like Docker Hub and deployed within a pod in a Kubernetes cluster. Using the PostgreSQL image in Kubernetes offers flexibility, scalability, and ease of deployment for database services. Here are some key points about using the PostgreSQL image in Kubernetes:

Understanding Official PostgreSQL Image

  • The official PostgreSQL image on Docker Hub (postgres) is widely used for deploying PostgreSQL databases in containerized environments, including Kubernetes.
  • The image is maintained by the PostgreSQL Docker Community and is regularly updated with the latest security patches and versions of PostgreSQL.

Configuration through Environment Variables

  • The PostgreSQL Docker image supports initialization and configuration through environment variables. Common variables include:
    • POSTGRES_DB: Specifies the name of the default database that is created when the image is first started.
    • POSTGRES_USER: Sets up the user who will have superuser access to the PostgreSQL server.
    • POSTGRES_PASSWORD: Sets the password for the POSTGRES_USER. This variable is mandatory for you to connect to the PostgreSQL server.
  • Kubernetes allows you to pass these environment variables to the container using the pod definition YAML file.

Data Persistence

  • In a containerized environment, it’s important to manage data persistence separately from the lifecycle of the container. Kubernetes addresses this by using Persistent Volumes (PV) and Persistent Volume Claims (PVC).
  • When deploying a PostgreSQL container in Kubernetes, it’s common practice to mount a PVC to the container’s data directory (/var/lib/postgresql/data) to ensure that the database data persists across pod restarts and deployments.

Networking and Accessibility

  • Kubernetes services are used to expose the PostgreSQL pod to other pods within the cluster or to the external world.
  • A ClusterIP service type is commonly used for internal communication, while a LoadBalancer or NodePort service type might be used for external access.

Security Considerations

  • It’s a best practice to use Kubernetes Secrets to manage sensitive information like the PostgreSQL user’s password (POSTGRES_PASSWORD).
  • Network policies can be defined to restrict who can access the PostgreSQL pod, enhancing the security within a Kubernetes cluster.

Deployment Strategies

  • While you can deploy a standalone PostgreSQL pod for development or testing, production environments often use StatefulSets or Deployments for database workloads. These controllers provide additional capabilities like stable network identifiers, persistent storage management, and automated rollouts and rollbacks.
  • Using a StatefulSet ensures that each replica of the PostgreSQL database maintains a sticky identity and that the order and uniqueness of these instances are guaranteed, which is important for database workloads that require stable, persistent storage.


  • PostgreSQL scalability in Kubernetes can be approached in several ways, including read replicas and partitioning. However, scaling stateful applications like databases is more complex than scaling stateless applications and often involves application-level changes or using additional tools and services.

Backup and Recovery

  • Managing backups and recovery is crucial for database workloads. Kubernetes does not provide native database backup solutions, so you need to integrate external tools or scripts to manage PostgreSQL backups, such as pg_dump, pgBackRest, or third-party cloud solutions.

Using the PostgreSQL image in Kubernetes combines the robust features of PostgreSQL with Kubernetes’ orchestration and management capabilities, providing a powerful solution for deploying and managing database workloads in a cloud-native environment.