As software and DevOps engineers, spinning up new PostgreSQL deployments for various applications, clusters, and environments is a straightforward task. However, these deployments inevitably require updates over time. Not all PostgreSQL deployments are managed by an operator, and upgrading these instances can involve significant manual effort.

The Importance of Updating PostgreSQL

Keeping your PostgreSQL deployments up-to-date is crucial for several reasons, primarily centered around security, performance, and new features.

Regular updates ensure that your database is protected against the latest vulnerabilities, safeguarding your data and maintaining the integrity of your applications. The PostgreSQL community considers not patching to be more risky than staying on an older version. Therefor it’s highly recommended to continously update your Postgres installations.

Beyond security and reliablity, updating PostgreSQL brings performance improvements and access to new features that can enhance your application’s functionality and efficiency. Each new release often includes optimizations that make the database faster and more reliable, as well as new tools and capabilities that can streamline your development process.

Keeping PostgreSQL installations up-to-date

In my experience with hundreds of PostgreSQL installations using the Bitnami PostgreSQL Helm chart and Docker Hub library PostgreSQL StatefulSets, major version upgrades are often performed using a tedious export and import process using pg_dump, coupled with manual labor. More advanced set-ups use replication, failovers and automation to handle the database upgrade proces. However for smaller installation, this could be overly complex.

To simplify this process for anyone running PostgreSQL, including smaller installations, on Kubernetes, I wanted to create a quick and easy upgrade solution. To address this need, I developed a CLI tool to facilitate running pg_upgrade on Kubernetes using a single command. This tool is designed for those utilizing Bitnami or Docker Hub library PostgreSQL images and builds upon the postgres-upgrade images from tianon/postgres-upgrade. It streamlines the upgrade process, reducing manual effort and ensuring smoother transitions between PostgreSQL versions.

kube-pg-upgrade

By using kube-pg-upgrade you can quickly upgrade a postgres installation running on Kubernetes. kube-pg-upgrade is a CLI tool developed in Golang designed to automate PostgreSQL upgrades on Kubernetes clusters utilizing pg_upgrade. The tool supports PostgreSQL container images sourced from both Bitnami and Docker Hub. Aimed primarily at DevOps engineers with PostgreSQL containers deployed in Kubernetes, this guide walks you through how to utilize this tool efficiently.

Installation

Install kube-pg-upgrade using any of the following method:

MacOS (Brew)

Install using Homebrew on MacOS. This is supported for both Intel Apple Silicon:

brew install containerinfra/cli/kube-pg-upgrade

GitHub releases

Alternatively, download the latest release binary on GitHub Releases. Binaries are available for Linux, Windows and MacOS.

How it works

The upgrade process followed by kube-pg-upgrade involves the following steps:

• Mount Existing Persistent Volume Claim (PVC): The tool mounts the existing PostgreSQL Persistent Volume Claim (PVC).
• Validation: Before proceeding, kube-pg-upgrade performs validations to ensure compatibility and readiness for the upgrade process.
• PVC Creation: A new PVC is created to host the upgraded PostgreSQL data.
• Copy the Postgres data using pg_upgrade: The tool employs pg_upgrade to copy and upgrade data from the old Postgres installation PVC to the new PVC.
• PVC Name Switch: Post-upgrade, the new PVC assumes the name of the old PVC ensuring application continuity without the need for configuration changes.
• Retention of Old PVC: Even after the upgrade, the old PVC isn’t discarded. Instead, it remains available within the cluster as a Persistent Volume (PV) using a “Retain” delete policy, safeguarding your older data.

Example Usage

kube-pg-upgrade postgres upgrade -n db-upgrade-test \
    --version=15 \
    --target-pvc-name=data-test-db-postgresql-primary-0 \
    test-db-postgresql-master