Streamline PostgreSQL deployments on Amazon EKS by using PGO - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsBest practicesEpicsTroubleshootingRelated resources

Streamline PostgreSQL deployments on Amazon EKS by using PGO

Created by Shalaka Dengale (AWS)

Summary

This pattern integrates the Postgres Operator from Crunchy Data (PGO) with Amazon Elastic Kubernetes Service (Amazon EKS) to streamline PostgreSQL deployments in cloud-native environments. PGO provides automation and scalability for managing PostgreSQL databases in Kubernetes. When you combine PGO with Amazon EKS, it forms a robust platform for deploying, managing, and scaling PostgreSQL databases efficiently.

This integration provides the following key benefits:

  • Automated deployment: Simplifies PostgreSQL cluster deployment and management.

  • Custom resource definitions (CRDs): Uses Kubernetes primitives for PostgreSQL management.

  • High availability: Supports automatic failover and synchronous replication.

  • Automated backups and restores: Streamlines backup and restore processes.

  • Horizontal scaling: Enables dynamic scaling of PostgreSQL clusters.

  • Version upgrades: Facilitates rolling upgrades with minimal downtime.

  • Security: Enforces encryption, access controls, and authentication mechanisms.

Prerequisites and limitations

Prerequisites

Product versions

  • Kubernetes versions 1.21–1.24 or later (see the PGO documentation).

  • PostgreSQL version 10 or later. This pattern uses PostgreSQL version 16.

Limitations

Architecture

Target technology stack

  • Amazon EKS

  • Amazon Virtual Private Cloud (Amazon VPC)

  • Amazon Elastic Compute Cloud (Amazon EC2)

Target architecture

Architecture for using PGO with three Availability Zones and two replicas, PgBouncer, and PGO operator.

This pattern builds an architecture that contains an Amazon EKS cluster with three nodes. Each node runs on a set of EC2 instances in the backend. This PostgreSQL setup follows a primary replica architecture, which is particularly effective for read-heavy use cases. The architecture includes the following components:

  • Primary database container (pg-primary) hosts the main PostgreSQL instance where all write operations are directed.

  • Secondary replica containers (pg-replica) host the PostgreSQL instances that replicate the data from the primary database and handle read operations.

  • PgBouncer is a lightweight connection pooler for PostgreSQL databases that's included with PGO. It sits between the client and the PostgreSQL server, and acts as an intermediary for database connections.

  • PGO automates the deployment and management of PostgreSQL clusters in this Kubernetes environment.

  • Patroni is an open-source tool that manages and automates high availability configurations for PostgreSQL. It's included with PGO. When you use Patroni with PGO in Kubernetes, it plays a crucial role in ensuring the resilience and fault tolerance of a PostgreSQL cluster. For more information, see the Patroni documentation.

The workflow includes these steps:

  • Deploy the PGO operator. You deploy the PGO operator on your Kubernetes cluster that runs on Amazon EKS. This can be done by using Kubernetes manifests or Helm charts. This pattern uses Kubernetes manifests.

  • Define PostgreSQL instances. When the operator is running, you create custom resources (CRs) to specify the desired state of PostgreSQL instances. This includes configurations such as storage, replication, and high availability settings.

  • Operator management. You interact with the operator through Kubernetes API objects such as CRs to create, update, or delete PostgreSQL instances.

  • Monitoring and maintenance. You can monitor the health and performance of the PostgreSQL instances running on Amazon EKS. Operators often provide metrics and logging for monitoring purposes. You can perform routine maintenance tasks such as upgrades and patching as necessary. For more information, see Monitor your cluster performance and view logs in the Amazon EKS documentation.

  • Scaling and backup: You can use the features provided by the operator to scale PostgreSQL instances and manage backups.

This pattern doesn't cover monitoring, maintenance, and backup operations.

Automation and scale

  • You can use AWS CloudFormation to automate the infrastructure creation. For more information, see Create Amazon EKS resources with AWS CloudFormation in the Amazon EKS documentation.

  • You can use GitVersion or Jenkins build numbers to automate the deployment of database instances.

Tools

AWS services

Other tools

  • eksctl is a simple command line tool for creating clusters on Amazon EKS.

  • kubectl is a command line utility for running commands against Kubernetes clusters.

  • PGO automates and scales the management of PostgreSQL databases in Kubernetes.

Best practices

Follow these best practices to ensure a smooth and efficient deployment:

  • Secure your EKS cluster. Implement security best practices for your EKS cluster, such as using AWS Identity and Access Management (IAM) roles for service accounts (IRSA), network policies, and VPC security groups. Limit access to the EKS cluster API server, and encrypt communications between nodes and the API server by using TLS.

  • Ensure version compatibility between PGO and Kubernetes running on Amazon EKS. Some PGO features might require specific Kubernetes versions or introduce compatibility limitations. For more information, see Components and Compatibility in the PGO documentation.

  • Plan resource allocation for your PGO deployment, including CPU, memory, and storage. Consider the resource requirements of both PGO and the PostgreSQL instances it manages. Monitor resource usage and scale resources as needed.

  • Design for high availability. Design your PGO deployment for high availability to minimize downtime and ensure reliability. Deploy multiple replicas of PGO across multiple Availability Zones for fault tolerance.

  • Implement backup and restore procedures for your PostgreSQL databases that PGO manages. Use features provided by PGO or third-party backup solutions that are compatible with Kubernetes and Amazon EKS.

  • Set up monitoring and logging for your PGO deployment to track performance, health, and events. Use tools such as Prometheus for monitoring metrics and Grafana for visualization. Configure logging to capture PGO logs for troubleshooting and auditing.

  • Configure networking properly to allow communications between PGO, PostgreSQL instances, and other services in your Kubernetes cluster. Use Amazon VPC networking features and Kubernetes networking plugins such as Calico or Amazon VPC CNI for network policy enforcement and traffic isolation.

  • Choose appropriate storage options for your PostgreSQL databases, considering factors such as performance, durability, and scalability. Use Amazon Elastic Block Store (Amazon EBS) volumes or AWS managed storage services for persistent storage. For more information, see Store Kubernetes volumes with Amazon EBS in the Amazon EKS documentation.

  • Use infrastructure as code (IaC) tools such as AWS CloudFormation to automate the deployment and configuration of PGO on Amazon EKS. Define infrastructure components—including the EKS cluster, networking, and PGO resources—as code for consistency, repeatability, and version control.

Epics

TaskDescriptionSkills required

Create an IAM role.

  1. Create an IAM role by using the following command in the AWS CLI:

    aws iam create-role \
    --role-name {YourRoleName} \
    --assume-role-policy-document '{
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": {
                    "Service": "eks.amazonaws.com"
                },
                "Action": "sts:AssumeRole"
            }
        ]
    }' && \
aws iam attach-role-policy \
    --role-name {YourRoleName}\
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSClusterPolicy && \
aws iam attach-role-policy \
    --role-name {YourRoleName}\
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSServicePolicy && \
aws iam attach-role-policy \
    --role-name {YourRoleName}\
	    --policy-arn arn:aws:iam::aws:policy/CloudWatchFullAccess

  2. Review the role in the AWS Management Console:

    1. Open the IAM console.

    2. Choose Roles, and search for the role name you created.

    3. Validate that the following policies are attached:

      AmazonEKSClusterPolicy

      AmazonEKSServicePolicy

      CloudWatchFullAccess

AWS administrator
TaskDescriptionSkills required

Create an Amazon EKS cluster.

If you've already deployed a cluster, skip this step. Otherwise, deploy an Amazon EKS cluster in your current AWS account by using eksctl, Terraform, or AWS CloudFormation. This pattern uses eksctl for cluster deployment.

Note

This pattern uses Amazon EC2 as a node group for Amazon EKS. If you want to use AWS Fargate, see the managedNodeGroups configuration in the eksctl documentation.

  1. Use the following eksctl input file to generate the cluster.

    sample-cluster.yaml:

    apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
  name: postgresql
  region: us-east-1
  version: "1.29"
accessConfig:
  authenticationMode: API_AND_CONFIG_MAP
availabilityZones:
- us-east-1a
- us-east-1b
- us-east-1c
nodeGroups:
  - name: ng-1
    instanceType: m5.16xlarge
    desiredCapacity: 2
  - name: ng-2
    instanceType: m5.16xlarge
    desiredCapacity: 2
  - name: ng-3
    instanceType: m5.16xlarge
    desiredCapacity: 2
vpc:
  cidr: 192.168.0.0/16
  clusterEndpoints:
    publicAccess: true
  nat:
    gateway: HighlyAvailable
iamIdentityMappings:
  - arn: arn:aws:iam::<account-id>:role/<role-name> # update the IAM role ARN created in step 1
    username: <user-name> # Enter the user name per your choice
    noDuplicateARNs: false

  2. Run the following command to create the cluster (provide the file path to your sample-cluster.yaml file):

    eksctl create cluster -f sample-cluster.yaml
AWS administrator, Terraform or eksctl administrator, Kubernetes administrator

Validate the status of the cluster.

Run the following command to see the current status of nodes in the cluster:

kubectl get nodes

If you encounter errors, see the troubleshooting section of the Amazon EKS documentation.

AWS administrator, Terraform or eksctl administrator, Kubernetes administrator
TaskDescriptionSkills required

Enable the IAM OIDC provider.

As a prerequisite for the Amazon EBS Container Storage Interface (CSI) driver, you must have an existing IAM OpenID Connect (OIDC) provider for your cluster.

Enable the IAM OIDC provider by using the following command:

eksctl utils associate-iam-oidc-provider --region={region} --cluster={YourClusterNameHere} --approve

For more information about this step, see the Amazon EKS documentation.

AWS administrator

Create an IAM role for the Amazon EBS CSI driver.

Use the following eksctl command to create the IAM role for the CSI driver:

eksctl create iamserviceaccount \
  --region {RegionName} \
  --name ebs-csi-controller-sa \
  --namespace kube-system \
  --cluster {YourClusterNameHere} \
  --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy \
  --approve \
  --role-only \
  --role-name AmazonEKS_EBS_CSI_DriverRole

If you use encrypted Amazon EBS drives, you have to configure the policy further. For instructions, see the Amazon EBS SCI driver documentation.

AWS administrator

Add the Amazon EBS CSI driver.

Use the following eksctl command to add the Amazon EBS CSI driver:

eksctl create addon \
  --name aws-ebs-csi-driver \
  --cluster <YourClusterName> service-account-role-arn arn:aws:iam::$(aws sts get-caller-identity \
  --query Account \
  --output text):role/AmazonEKS_EBS_CSI_DriverRole \
  --force
AWS administrator
TaskDescriptionSkills required

Clone the PGO repository.

Clone the GitHub repository for PGO:

git clone https://github.com/CrunchyData/postgres-operator-examples.git
AWS DevOps

Provide the role details for service account creation.

To grant the Amazon EKS cluster access to the required AWS resources, specify the Amazon Resource Name (ARN) of the OIDC role that you created earlier in the service_account.yaml file. This file is located in the namespace folder of the repository. 

cd postgres-operator-examples
---
metadata:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::<accountId>:role/<role_name> # Update the OIDC role ARN created earlier
AWS administrator, Kubernetes administrator

Create the namespace and PGO prerequisites.

  1. Run the following command to create the namespace:

    kubectl apply -k kustomize/install/namespace

    This establishes a dedicated namespace for PGO. If necessary, you can modify the namespace.yml file and assign the namespace  a different name.

  2. Run the following command to apply the default configuration to the cluster:

    kubectl apply --server-side -k kustomize/install/default

    kustomize/install/default provides the default configuration for the Kubernetes role-based access control (RBAC), custom resource definition (CRD), and Kubernetes Manager files.

Kunernetes administrator

Verify the creation of pods.

Verify that the namespace and default configuration were created:

kubectl get pods -n postgres-operator
AWS administrator, Kubernetes administrator

Verify PVCs.

Use the following command to verify persistent volume claims (PVCs):

kubectl describe pvc -n postgres-operator
AWS administrator, Kubernetes administrator
TaskDescriptionSkills required

Create an operator.

Revise the contents of the file located at /kustomize/postgres/postgres.yaml to match the following:

spec:
  instances:
    - name: pg-1
      replicas: 3
  patroni:
    dynamicConfiguration:
      postgresql:
      pg_hba:
        - "host all all 0.0.0.0/0 trust" # this line enabled logical replication with programmatic access
        - "host all postgres 127.0.0.1/32 md5"
      synchronous_mode: true
  users:
  - name: replicator
    databases:
      - testdb
    options: "REPLICATION"

These updates do the following:

  • Adjust the PostgreSQL configuration settings to facilitate access to the PostgreSQL instance.

  • Include configurations for replication user, database user, and superuser to enable streaming replication, database access, and cluster management.

AWS administrator, DBA, Kubernetes administrator

Deploy the operator.

Deploy the PGO operator to enable the streamlined management and operation of PostgreSQL databases in Kubernetes environments:

kubectl apply -k kustomize/postgres
AWS administrator, DBA, Kubernetes administrator

Verify the deployment.

  1. Validate that the operator has been deployed:

    kubectl get pods -n postgres-operator --selector=postgres-operator.crunchydata.com/instance-set \   -L postgres-operator.crunchydata.com/role

  2. Verify that the service resource associated with the operator pod has been created:

    kubectl get svc -n postgres-operator

From the command output, note the primary replica (primary_pod_name) and read replica (read_pod_name). You will uses these in the next steps.

AWS administrator, DBA, Kubernetes administrator
TaskDescriptionSkills required

Write data to the primary replica.

Use the following commands to connect to the PostgreSQL primary replica and write data to the database:

kubectl exec -it <primary_pod_name> bash -n postgres-operator
psql
CREATE TABLE customers (firstname text, customer_id serial, date_created timestamp);
\dt
AWS administrator, Kubernetes administrator

Confirm that the read replica has the same data.

Connect to the PostgreSQL read replica and check whether the streaming replication is working correctly:

kubectl exec -it {read_pod_name} bash -n postgres-operator
psql
\dt

The read replica should have the table that you created in the primary replica in the previous step.

AWS administrator, Kubernetes administrator

Troubleshooting

IssueSolution

The pod doesn’t start.

  • Use the following command to inspect pod status:

    kubectl get pods -n your-namespace

  • Inspect the logs for any errors:

    kubectl logs your-pod-name -n your-namespace

  • Check pod events for any abnormal events related to your pods:

    kubectl describe pod your-pod-name -n your-namespace

Replicas are significantly behind the primary database.

  • Check for replication lag:

    SELECT * FROM pg_stat_replication;

  • Make sure that replicas have enough CPU and memory resources. Check resource limits:

    kubectl describe pod your-replica-pod -n your-namespace

  • Verify that the storage backend is performing optimally. Slow disk I/O can cause replication lag.

You don’t have visibility into the performance and health of the PostgreSQL cluster.

  • Enable Amazon CloudWatch Logs and make sure that logs are being sent to Amazon CloudWatch for analysis. For more information, see the Amazon EKS documentation.

  • Check pg_stat_activity:

    SELECT * FROM pg_stat_activity;

Replication doesn’t work.

  • Check the primary configuration by viewing the replication settings in postgresql.conf:

    wal_level = replica
    max_wal_senders = 10
    wal_keep_size = 64  # or wal_keep_segments in older versions

  • Verify that pg_hba.conf includes replication permissions:

    host replication replica_user all md5

  • Check replica configuration. Make sure that recovery.conf or equivalent settings (standby.signal and primary_conninfo) are correctly set up on replicas.

Related resources