Kubernetes

Both ParadeDB Community and Enterprise can be deployed on Kubernetes. There are two deployment options:

If you don’t already use CloudNativePG, follow the ParadeDB Helm Chart setup to install CloudNativePG and deploy your ParadeDB cluster.
If you already use CloudNativePG, use the ParadeDB extension image to add ParadeDB to your existing cluster.

Deploying with the Helm Chart

The ParadeDB Helm Chart is based on CloudNativePG and is also available on Artifact Hub.

Prerequisites

This guide assumes you have installed Helm and have a Kubernetes cluster running v1.29+. For local testing, we recommend Minikube. Create the paradedb namespace.

kubectl create namespace paradedb

If you are using ParadeDB Enterprise, create a Kubernetes secret with the registry credentials provided by ParadeDB to pull the Enterprise image. If you are using Community, you can skip this step.

ParadeDB Enterprise

kubectl create secret docker-registry paradedb-enterprise-registry-cred \
--namespace paradedb \
--docker-server="https://index.docker.io/v1/" \
--docker-username="<username>" \
--docker-password="<access_token>"

Installing the Prometheus Stack

The ParadeDB Helm chart supports monitoring via Prometheus and Grafana. To enable this, you need to have the Prometheus CRDs installed before installing the CloudNativePG operator. If you do not yet have the Prometheus CRDs installed on your Kubernetes cluster, you can install them with:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm upgrade --atomic --install prometheus-community \
--create-namespace \
--namespace prometheus-community \
--values https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/samples/monitoring/kube-stack-config.yaml \
prometheus-community/kube-prometheus-stack

Installing the CloudNativePG Operator

Skip this step if the CloudNativePG operator is already installed in your cluster. If you do not wish to monitor your cluster, omit the --set commands.

helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --atomic --install cnpg \
--create-namespace \
--namespace cnpg-system \
--set monitoring.podMonitorEnabled=true \
--set monitoring.grafanaDashboard.create=true \
cnpg/cloudnative-pg

Starting the ParadeDB Cluster

Create a values.yaml and configure it to your requirements. See the chart’s default values.yaml for available configuration options and their defaults. Here is a basic example:

type: paradedb
mode: standalone

cluster:
  instances: 1
  storage:
    size: 10Gi
  walStorage:
    enabled: true
    size: 1Gi

monitoring:
  grafanaDashboard:
    create: true

type: paradedb-enterprise
mode: standalone

cluster:
  instances: 3
  storage:
    size: 10Gi
  walStorage:
    enabled: true
    size: 1Gi

monitoring:
  grafanaDashboard:
    create: true

Finally, launch the ParadeDB cluster.

helm repo add paradedb https://paradedb.github.io/charts
helm upgrade --atomic --install paradedb \
--namespace paradedb \
--values values.yaml \
--set cluster.monitoring.enabled=true \
paradedb/paradedb

Connecting to the Cluster

Connect to the cluster via kubectl exec:

kubectl exec service/paradedb-rw -n paradedb -it -- psql

Connecting to the Grafana Dashboard

The ParadeDB Helm Chart includes a Grafana dashboard to help you monitor your cluster. To access the dashboard, forward the Grafana service to localhost:

kubectl --namespace prometheus-community port-forward svc/prometheus-community-grafana 3000:80

The dashboard will be accessible at localhost:3000 under username admin and password prom-operator. A more detailed guide on configuring the monitoring stack can be found in the CloudNativePG documentation.

Using the Extension Image with CloudNativePG

The ParadeDB extension image uses CloudNativePG’s image volume support to load ParadeDB into your existing Postgres cluster.

Prerequisites

This requires Postgres 18+ and Kubernetes support for image volumes. See the CloudNativePG extension image guide for requirements and configuration details. If you are using ParadeDB Enterprise, create a Kubernetes secret with the registry credentials provided by ParadeDB to pull the Enterprise image. If you are using Community, you can skip this step. Use your cluster’s namespace in place of paradedb if it differs.

ParadeDB Enterprise

kubectl create secret docker-registry paradedb-enterprise-registry-cred \
--namespace paradedb \
--docker-server="https://index.docker.io/v1/" \
--docker-username="<username>" \
--docker-password="<access_token>"

Configuring the Extension Image

The pg_search extension requires pgvector, which is not bundled in the ParadeDB extension image. Add both extension images to spec.postgresql.extensions in your CloudNativePG Cluster resource and save it as cluster.yaml:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: paradedb
spec:
  imageName: ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie
  instances: 1

  storage:
    size: 1Gi

  postgresql:
    shared_preload_libraries:
      - "pg_search"
    extensions:
      # You can omit this if pgvector is already installed on your cluster
      - name: vector
        image:
          reference: ghcr.io/cloudnative-pg/pgvector:0.8.6-18-trixie
      - name: pg_search
        image:
          reference: docker.io/paradedb/paradedb-extension:0.26.0-18-trixie
        extension_control_path:
          - share
        dynamic_library_path:
          - lib
        ld_library_path:
          - system

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: paradedb
spec:
  imageName: ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie
  instances: 3
  imagePullSecrets:
    - name: paradedb-enterprise-registry-cred

  storage:
    size: 1Gi

  postgresql:
    shared_preload_libraries:
      - "pg_search"
    extensions:
      # You can omit this if pgvector is already installed on your cluster
      - name: vector
        image:
          reference: ghcr.io/cloudnative-pg/pgvector:0.8.6-18-trixie
      - name: pg_search
        image:
          reference: docker.io/paradedb/paradedb-enterprise-extension:0.26.0-18-trixie
        extension_control_path:
          - share
        dynamic_library_path:
          - lib
        ld_library_path:
          - system

Configure your database to enable pgvector and pg_search using a Database resource and save it as database.yaml:

apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: paradedb
spec:
  name: app
  owner: app
  cluster:
    name: paradedb
  extensions:
    - name: vector
      version: "0.8.6"
    - name: pg_search
      version: "0.26.0"

Installing the Extension Image

Apply the resources in your cluster’s namespace:

kubectl apply --namespace <namespace> -f cluster.yaml -f database.yaml

Once the cluster is ready, connect to your database as usual. CloudNativePG enables vector and pg_search automatically, so you do not need to run CREATE EXTENSION.

Deployment

Replication

Index Maintenance

Performance

Administration

Continuous Integration

Deploying with the Helm Chart

Prerequisites

Installing the Prometheus Stack

Installing the CloudNativePG Operator

Starting the ParadeDB Cluster

Connecting to the Cluster

Connecting to the Grafana Dashboard

Using the Extension Image with CloudNativePG

Prerequisites

Configuring the Extension Image

Installing the Extension Image

​Deploying with the Helm Chart

​Prerequisites

​Installing the Prometheus Stack

​Installing the CloudNativePG Operator

​Starting the ParadeDB Cluster

​Connecting to the Cluster

​Connecting to the Grafana Dashboard

​Using the Extension Image with CloudNativePG

​Prerequisites

​Configuring the Extension Image

​Installing the Extension Image

Deploying with the Helm Chart

Prerequisites

Installing the Prometheus Stack

Installing the CloudNativePG Operator

Starting the ParadeDB Cluster

Connecting to the Cluster

Connecting to the Grafana Dashboard

Using the Extension Image with CloudNativePG

Prerequisites

Configuring the Extension Image

Installing the Extension Image