Version:

Quickstart

This quickstart guide shows you how to install the pgEdge Helm chart to deploy Postgres in a Kubernetes cluster. You can choose between a distributed setup with three nodes or a single-node configuration.

The guide covers basic usage of the Helm chart and its features, using either an existing Kubernetes cluster or a local cluster on your laptop.

Prerequisites

Access to a Kubernetes cluster:
- To run a cluster locally, we recommend using kind.
- To use kind, you can initialize a local Kubernetes cluster using this command:
```
kind create cluster --config examples/configs/single/kind.yaml
```
The following tools must be installed on your laptop to deploy and interact with Kubernetes and CloudNativePG:
- helm: The package manager for Kubernetes, used to install, upgrade, and manage Kubernetes applications via Helm charts.
- kubectl: The Kubernetes command-line tool, used to interact with and manage your Kubernetes clusters.
- kubectl cnpg plugin: A plugin for kubectl that provides additional commands for managing CloudNativePG clusters. Download the appropriate binary for your platform from the pgEdge distribution releases.

Installation

Add the pgEdge Helm repository:

helm repo add pgedge https://pgedge.github.io/charts
helm repo update

Set your kubectl context and namespace to ensure you will deploy the chart to the correct cluster. For example:
```
kubectl config use-context <cluster-context> --namespace <desired-namespace>
```
If you are using kind, your context will be called kind-single.

Install chart dependencies.

pgEdge Helm requires the CloudNativePG and cert-manager operators to be installed into your cluster:

# Install CloudNativePG operator
helm install cnpg pgedge/cloudnative-pg \
  --namespace cnpg-system \
  --create-namespace

# Install cert-manager
kubectl apply -f \
  https://github.com/cert-manager/cert-manager/releases/download/v1.19.3/cert-manager.yaml

kubectl wait --for=condition=Available deployment \
  -n cert-manager cert-manager cert-manager-cainjector cert-manager-webhook --timeout=120s

Customize your chart configuration (optional).

Create a values.yaml file with your configuration. For a distributed setup with three nodes:

pgEdge:
  appName: pgedge
  nodes:
    - name: n1
      hostname: pgedge-n1-rw
      clusterSpec:
        instances: 3
        postgresql:
          synchronous:
            method: any
            number: 1
            dataDurability: required
    - name: n2
      hostname: pgedge-n2-rw
    - name: n3
      hostname: pgedge-n3-rw
  clusterSpec:
    storage:
      size: 1Gi

For a single region deployment with just one node:

pgEdge:
  appName: pgedge
  nodes:
    - name: n1
      hostname: pgedge-n1-rw
      clusterSpec:
        instances: 3
        postgresql:
          synchronous:
            method: any
            number: 1
            dataDurability: required
  clusterSpec:
    storage:
      size: 1Gi

If you want to change your configuration later to use a distributed architecture, see Adding Nodes.

You can also reference the example configuration at examples/configs/single/values.yaml.

Install the chart.

From pgEdge Helm Repository (recommended):
```
helm install pgedge pgedge/pgedge \
  --values values.yaml \
  --wait
```
From local chart:

Alternatively, download the latest release from pgEdge Helm Releases, extract it, and install from the local directory:
```
helm install pgedge ./ \
  --values values.yaml \
  --wait
```
Once the deployment is complete, you should see a confirmation message, and your database is ready to use:
```
NAME: pgedge
LAST DEPLOYED: Thu Oct 30 10:41:07 2025
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
```

Connecting to each Database Instance

If you have the kubectl cnpg plugin installed on your machine, you can access each instance as follows:

# The 'n1' node's primary instance
kubectl cnpg psql pgedge-n1 -- -U app app

# The first available read replica for the  'n1' node
kubectl cnpg psql pgedge-n1 --replica -- -U app app

# The 'n2' node's primary instance, if deploying a distributed database
kubectl cnpg psql pgedge-n2 -- -U app app

# The 'n3' node's primary instance, if deploying a distributed database
kubectl cnpg psql pgedge-n3 -- -U app app

Trying out Replication

Create a table on the first node:

kubectl cnpg psql pgedge-n1 -- -U app app -c "create table example (id int primary key, data text);"

Insert a row into our new table on the second node:

kubectl cnpg psql pgedge-n2 -- -U app app -c "insert into example (id, data) values (1, 'Hello, pgEdge!');"

See that the new row has replicated back to the first node:

kubectl cnpg psql pgedge-n1 -- -U app app -c "select * from example;"

Loading the Northwind Sample dataset

The Northwind sample dataset is a PostgreSQL database dump that you can use to try replication with a more realistic database. To load the Northwind dataset into your pgEdge database, run:

curl https://downloads.pgedge.com/platform/examples/northwind/northwind.sql \
    | kubectl cnpg psql pgedge-n1 -- -U app app

Now, try querying one of the new tables from the another node:

kubectl cnpg psql pgedge-n2 -- -U app app -c "select * from northwind.shippers"

Uninstalling the Helm Chart

If you wish to uninstall the pgEdge Helm chart, you can perform a helm uninstall with the following command:

helm uninstall pgedge

All resources will be removed, with the exception of secrets which were created to store generated client certificates by cert-manager. This is a safety mechanism which aligns with cert-manager's default behavior, and ensures that dependent services are not brought down by an accidental update.

If you wish to delete these secrets, you can identify then via kubectl:

kubectl get secrets

NAME                 TYPE                DATA   AGE
admin-client-cert    kubernetes.io/tls   3      3m43s
app-client-cert      kubernetes.io/tls   3      3m43s
client-ca-key-pair   kubernetes.io/tls   3      3m46s
pgedge-client-cert   kubernetes.io/tls   3      3m45s

Then, you can delete each secret using the following command:

kubectl delete secret <name>