pgedge-helm

README

pgEdge Helm

The pgEdge Helm chart supports deploying both pgEdge Enterprise Postgres and pgEdge Distributed Postgres in Kubernetes.

This chart leverages CloudNativePG to manage Postgres, providing flexible options for single-region and multi-region deployments.

Features

At a high level, this chart features support for:

• Postgres 16, 17, and 18 via pgEdge Enterprise Postgres Images.
• Flexible deployment options for both single-region and multi-region deployments
  • Deploy pgEdge Enterprise Postgres in a single region with optional standby replicas.
  • Deploy pgEdge Distributed Postgres across multiple regions with Spock active-active replication.
• Configuring Spock replication configuration across all nodes during helm install and upgrade processes.
• Best practice configuration defaults for deploying pgEdge Distributed Postgres in Kubernetes.
• Extending / overriding configuration for CloudNativePG across all nodes, or on specific nodes.
• Deploying additional Kubernetes resources (NetworkPolicies, PodMonitors, backups, etc.) alongside pgEdge using extraResources.
• Configuring standby instances with automatic failover, leveraging Spock's delayed feedback and failover slots worker to maintain active-active replication across failovers and promotions.
• Zero downtime node addition via Spock, or adding nodes from backups using CloudNativePG's bootstrap capabilities.
• Performing Postgres major and minor version upgrades.
• Client certificate authentication for managed users, including the pgedge replication user.
• Configuration options to support deployments across multiple Kubernetes clusters.

Prerequisites

In order for this chart to work, you must pre-install two operators into your Kubernetes clusters:

• CloudNativePG
• cert-manager

Installation

This chart is available from the pgEdge Helm repository:

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

For complete installation instructions, see the Installation Guide.

Local Development

Setup

Install all development dependencies (Helm, Go, Kind, chart-testing, changie, etc.):

make setup

pgedge-helm-utils Image

The pgedge-helm-utils image is a statically compiled Go binary that runs the init-spock job during Helm installation and upgrades. The job outputs structured JSON logs.

For local development and testing, you must build the image and load it into your local Kubernetes cluster (e.g., kind, minikube) prior to installing or upgrading the chart:

First, build the image locally using:

make docker-build-dev

Next, load the image into your local cluster. For example, with kind:

kind load docker-image pgedge-helm-utils:dev --name <your-cluster-name>

Finally, set the initSpockImageName value to use the local image when installing or upgrading the chart:

	helm install \
		--values examples/configs/single/values.yaml \
		--set pgEdge.initSpockImageName=pgedge-helm-utils:dev \
		--wait \
		pgedge .

Testing

This chart has a Go-based test framework in the test/ directory covering both unit tests (Helm template rendering) and integration tests (full Kubernetes cluster verification).

Unit Tests

Unit tests validate that helm template produces correct manifests for different configurations. No cluster required.

make test-unit

Integration Tests

Integration tests install the chart into a real Kubernetes cluster and verify cluster health, init-spock job completion, certificate provisioning, Spock replication, and node add/remove operations.

Against a local Kind cluster (creates cluster, installs prerequisites, runs tests, tears down):

make test-integration-kind

Against an existing cluster with CNPG and cert-manager pre-installed:

KUBECONTEXT=my-cluster make test-integration

With a published chart from the pgEdge Helm repository (for cross-project testing):

KUBECONTEXT=my-cluster \
  HELM_REPO=https://pgedge.github.io/charts \
  CHART_REF=pgedge/pgedge \
  CHART_VERSION=<chart-version> \
  make test-integration

See test/Makefile for additional targets including selective test runs (test-install, test-nodes).

Chart Testing (ct)

This chart supports chart-testing (ct), the standard Helm chart linting and installation testing tool used across the Helm ecosystem. If you're pulling this chart into your own project and want to validate it with your own values files, ct is the standard way to do that. Test values files are in the ci/ directory.

Lint (no cluster required):

make ct-lint

Install test against the current kubecontext (installs and uninstalls the chart with each ci/*-values.yaml):

make ct-install

Releasing

See docs/releasing.md for the complete release process.

Quick reference:

# Add changelog entries as you work
changie new

# Create a release
make minor-release  # or patch-release / major-release

Documentation

The documentation for this chart uses MkDocs with the Material theme to generate styled static HTML documentation from Markdown files in the docs directory.

The documentation can be accessed locally at http://localhost:8000 using:

make docs

helm-docs

helm-docs is used to generate values.yaml reference documentation dynamically from values.yaml.

This is in use in the following files:

• README.md.gotmpl
  • generates README.md
• docs/configuration.md.gotmpl
  • generates docs/configuration.md

You can run make gen-docs after updating the templates to generate the associated markdown file.

Values

Key	Type	Default	Description
pgEdge.adminUser	string	"admin"	The name of the admin role used for database management and init-spock connections.
pgEdge.appName	string	"pgedge"	Determines the name of resources in the pgEdge cluster. Many other values are derived from this name, so it must be less than or equal to 26 characters in length.
pgEdge.clusterSpec	object	{"bootstrap":{"initdb":{"database":"app","encoding":"UTF8","owner":"app","postInitApplicationSQL":["CREATE EXTENSION spock;"],"postInitSQL":[],"postInitTemplateSQL":[]}},"certificates":{"clientCASecret":"client-ca-key-pair","replicationTLSSecret":"streaming-replica-client-cert"},"imageName":"ghcr.io/pgedge/pgedge-postgres:18-spock5-standard","imagePullPolicy":"Always","instances":1,"managed":{"roles":[{"comment":"Admin role","ensure":"present","login":true,"name":"admin","superuser":true}]},"postgresql":{"parameters":{"checkpoint_completion_target":"0.9","checkpoint_timeout":"15min","dynamic_shared_memory_type":"posix","hot_standby_feedback":"on","spock.allow_ddl_from_functions":"on","spock.conflict_log_level":"DEBUG","spock.conflict_resolution":"last_update_wins","spock.enable_ddl_replication":"on","spock.include_ddl_repset":"on","spock.save_resolutions":"on","track_commit_timestamp":"on","track_io_timing":"on","wal_level":"logical","wal_sender_timeout":"5s"},"pg_hba":["hostssl app pgedge 0.0.0.0/0 cert","hostssl app admin 0.0.0.0/0 cert","hostssl app app 0.0.0.0/0 cert","hostssl all streaming_replica all cert map=cnpg_streaming_replica"],"pg_ident":["local postgres admin","local postgres app"],"shared_preload_libraries":["pg_stat_statements","snowflake","spock"]},"projectedVolumeTemplate":{"sources":[{"secret":{"items":[{"key":"tls.crt","mode":384,"path":"pgedge/certificates/tls.crt"},{"key":"tls.key","mode":384,"path":"pgedge/certificates/tls.key"},{"key":"ca.crt","mode":384,"path":"pgedge/certificates/ca.crt"}],"name":"pgedge-client-cert"}}]}}	Default CloudNativePG Cluster specification applied to all nodes, which can be overridden on a per-node basis using the clusterSpec field in each node definition.
pgEdge.externalNodes	list	[]	Configuration for nodes that are part of the pgEdge cluster, but managed externally to this Helm chart. This can be leveraged for multi-cluster deployments or to wire up existing CloudNativePG Clusters to a pgEdge cluster.
pgEdge.extraResources	list	[]	Array of extra Kubernetes resources to deploy alongside pgEdge (evaluated as templates). Useful for deploying NetworkPolicies, PodMonitors, ConfigMaps, etc.
pgEdge.initSpock	bool	true	Whether or not to run the init-spock job to initialize the pgEdge nodes and subscriptions In multi-cluster deployments, this should only be set to true on the last cluster to be deployed.
pgEdge.initSpockImageName	string	""	Docker image for the init-spock job. If not set, defaults to ghcr.io/pgedge/pgedge-helm-utils:v. Override this for local development or to use a custom image.
pgEdge.initSpockJobConfig.containerSecurityContext	object	{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"readOnlyRootFilesystem":true}	Container Security context for the init-spock job. Set to a Restricted profile by default. Learn more at https://kubernetes.io/docs/concepts/security/pod-security-standards/
pgEdge.initSpockJobConfig.podSecurityContext	object	{"fsGroup":65532,"runAsNonRoot":true,"seccompProfile":{"type":"RuntimeDefault"}}	Pod Security context for the init-spock job. Set to a Restricted profile by default. Learn more at https://kubernetes.io/docs/concepts/security/pod-security-standards/
pgEdge.initSpockJobConfig.resetSpock	bool	false	When true, the init-spock job will drop and recreate all Spock state on every node before reconciling. Use this when bootstrapping from a Barman backup that contains stale Spock configuration. Remove after successful initialization.
pgEdge.initSpockJobConfig.timeout	int	7200	Maximum time (in seconds) for the init-spock job to complete. Increase for large databases where initial sync may take longer.
pgEdge.nodes	list	[]	Configuration for each node in the pgEdge cluster. Each node will be deployed as a separate CloudNativePG Cluster.
pgEdge.provisionCerts	bool	true	Whether to deploy cert-manager to manage TLS certificates for the cluster. If false, you must provide your own TLS certificates by creating the secrets defined in clusterSpec.certificates.clientCASecret and clusterSpec.certificates.replicationTLSSecret.

---

Autogenerated from chart metadata using helm-docs v1.14.2