This guide will walk you through the process of deploying PostgreSQL on a Statehub registered Kubernetes cluster, using Statehub as a data service enabling cross-region and multicloud continuity.

The Deployments will be executed using the Helm Chart bitnami/postgresql .
Further information about the chart and the Parameters configured within it can be found here.

Among the resources that are created through the chart, are StatefulSets, Services, PVCs (which will use Statehub as a volume provisioner) and etc.

That means, that in the event of a failure of your cluster, or the entire cloud region where it is deployed, you’ll be able to start your PostgreSQL Processes, with all of its latest data intact, on another cluster at a different location in just a few seconds.


Deploying PostgreSQL on K8s - Statehub


Before You Begin

Before you begin, it might be useful to familiarize yourself with Statehub concepts such as Clusters, States, Volumes, and the Default State.


The following is necessary to use Statehub with your Kubernetes clusters:

  1. A Statehub account. Sign up here
  2. A UNIX-compatible command-line interface (Linux or Mac terminal, WSL or CygWin for Windows)
  3. The kubectl command-line utility to control your clusters
  4. The helm command-line utility to deploy Helm charts on your clusters (Helm 3.1.0 +)

Initial Setup

This guide assumes you have two Kubernetes clusters in two distinct cloud locations, similar to the diagram below:


Deploying PostgreSQL on K8s - Statehub

Step 1: Set Up the Statehub CLI

Go to Get-Statehub to download and install the Statehub CLI.

Setting up your Kubernetes clusters to use Statehub requires using the Statehub CLI. After installation is complete, a link will be displayed to log you into your Statehub account. Copy the link to your browser and go to the Statehub login page.

If you don’t already have a Statehub account, you can create one by clicking a link on the Statehub login page.

Once you’ve logged in to your Statehub account, you should be automatically redirected to the tokens page and prompted to create a token for your CLI. Click “Yes” to create a token. Copy the token to the CLI prompt and press Enter.

Your Statehub CLI installation should now be configured.



Step 2: Register Your Clusters with Statehub

Register the Clusters Using the Statehub CLI

The following command will register the cluster associated with your current context:

kubectl config use-context my-cluster
statehub register-cluster

To register another cluster, switch to its context, and then run register it:

kubectl config use-context another-cluster
statehub register-cluster

For further information about the cluster register process go to Statehub – Cluster Registration.

💡 Please Note:
In certain scenarios, you might not have a second cluster in place at another location, but still want your data to be replicated to another location, and create a cluster on-demand in the event of your primary location’s failure. In this case, follow the procedure to add a location to a state. This will allow you to add another replication location for your application’s state without having a cluster deployed there in advance.


What We’ve Done

To use Statehub with your Kubernetes clusters, register them using the Statehub CLI. The Statehub CLI makes use of your Kubernetes configuration contexts to identify your clusters and is aware of the current context.

To register another cluster, either switch to the appropriate context or run the above command. You need to register all the clusters between which you want to move your stateful applications.

This operation will:

  1. Make Statehub aware of your clusters
  2. Identify your clusters’ location(s) and report them to Statehub
  3. Generate a cluster token for your cluster and save it in your cluster’s secrets, so that your cluster can access the Statehub REST API.
  4. Install the Statehub Controller components and the Statehub CSI driver on your cluster
  5. Add the cluster’s location(s) to the default state, if the default state doesn’t span this location yet
  6. Configure the default state’s corresponding storage class (``) as the default storage class.
  7. Once you’ve registered all of your clusters, you should be able to start stateful applications and fail them over between your clusters.


At this point, your topology will look as follows:


Deploying PostgreSQL on K8s - Statehub




Step 3: Deploy the PostgreSQL Helm Chart

Using the bitnami/postgresql helm Chart, deploy the needed resources for your PostgreSQL.

Start with Adding/Updating the Helm repository:

helm repo add bitnami

Install the Helm Chart using the following command, make sure you update the needed parameters according to the example below:

You may change the values:

  • Demo-release – Given name to the Helm release
  • bestpassword – It is highly advised to configure a secured Password through this setting.
  • YourStatehubOrgId – Update this value to your Statehub Organization ID


helm install demo-release bitnami/postgresql --set global.postgresql.postgresqlPassword="bestpassword" --set postgresqlPostgresPassword="bestpassword" --set --set

💡 Please Note:
The following parameters are crucial for a a successful Fail-Over between clusters in case of a need.
It is crucial to define the PostgreSQL password during the launch of the helm chart, this is due the fact that the Helm Chart generates a default password that will not sync while launching the environment on the back-up cluster during the Fail-Over.
setting this Parameter will override the default password and will guarantee access at the back-up clusters in case of need.
Make sure the password configured is matching on both parameters

ℹ️  Further info about the Helm chart and the available parameters can be found here:
Helm Chart Parameters


To access the PostgreSQL from outside the cluster follow the instructions given upon the launch of the chart.


Example steps to access PostgreSQL for Demo-release:

Obtain the password for Postgres – (The password obtained should be equivalent to the password set during the launch (in this example – “bestpassword”)

export POSTGRES_PASSWORD=$(kubectl get secret --namespace default demo-release-postgresql -o jsonpath="{.data.postgresql-password}" | base64 --decode)

Connecting to the Database:

kubectl run demo-release-postgresql-client --rm --tty -i --restart='Never' --namespace default --image --env="PGPASSWORD=$POSTGRES_PASSWORD" --command -- psql --host demo-release-postgresql -U postgres -d postgres -p 5432

After the last step, you should be connected to the command prompt and you’re officially connected to your PostgreSQL running on Kubernetes.

Creating Data

An example for Table creating on PostgreSQL for a switch-over test:

Once you’re inside the command prompt:

\c employees
CREATE TABLE employees (
employee_num integer,
name text,
birthday numeric

Insert test values as you please:

SELECT * FROM employees;

Once you’ve created a table its info will safely be moved from one region to the other in case of a failure – thus keeping your database stateful across regions and cross-cloud using Statehub.


Deploying PostgreSQL on K8s - Statehub




Step 4: Failing Over Between Clusters in Different Locations

When you need to switch over your application to another cluster, set the other cluster as the owner of the state and apply the configuration to it.

Deploying PostgreSQL on K8s - Statehub


Delete the Helm chart:

helm delete demo-release

Delete the Client pod launched at step 3:

1.Get the pod’s name:

kubectl get pods

2.Delete the pod:

kubectl delete pod PodName

To start your application on the other cluster,

  1. Choose the cluster on which you want your application and switch to its context
    kubectl config use-context another-cluster
  2. Make sure this cluster is the owner of the default state by running
    statehub set-owner default another-cluster
  3. Re-launch the Helm Chart in the new cluster context
    helm install demo-release bitnami/postgresql --set global.postgresql.postgresqlPassword="bestpassword" --set postgresqlPostgresPassword="bestpassword" --set --set

    💡 Please Note:
    Make sure you use the same password as configured in the Main cluster, follow the guide according to step 3

    Once you have connected to the Postgres command prompt:

> \c
> \l

You should be able to see your new table “employees” with the data inserted at the end of step 3.





While failures might happen anytime, there is a simple solution for preventing data loss and managing stateful data and applications, especially with DataBases such as PostgreSQL, using the features of Statehub.

In this guide, we went through the basic steps of Deploying PostgreSQL on Kubernetes with a Cross-Region or multicloud Business Continuity using Statehub, giving you the freedom of running stateful databases without worrying about Data lost in a case of a failure or in a need for a change.

As always, feel free to ping us back with any questions at or book a demo with us