Kubernetes

For Kubernetes deployments, we recommend running ParadeDB with CloudNativePG. Both ParadeDB Community and Enterprise binaries can be deployed on Kubernetes.

ParadeDB Community can run on Kubernetes as a single-node deployment. Use ParadeDB Enterprise when ParadeDB indexes need physical replication for high availability, failover, or read replicas that can serve ParadeDB queries.

This guide uses the ParadeDB Helm Chart. The chart 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.

Install 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

Install 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

Start a ParadeDB CNPG Cluster

Create a values.yaml and configure it to your requirements. Here is a basic example:

type: paradedb
mode: standalone

cluster:
  instances: 1
  storage:
    size: 256Mi

type: paradedb-enterprise
mode: standalone

cluster:
  instances: 1
  storage:
    size: 256Mi

If you are using ParadeDB Enterprise for high availability, set instances to a number greater than 1.

Next, create a namespace for this step or use an existing namespace. The namespace can be any value.

kubectl create namespace <your-namespace>

For ParadeDB Enterprise, you should have received an enterprise Docker username and personal access token. The following step passes these credentials to Kubernetes and should be skipped if you are deploying ParadeDB Community.

ParadeDB Enterprise

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

Finally, launch the ParadeDB cluster.

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

Use the Extension Image with CloudNativePG

If you already run a CloudNativePG cluster and want to add ParadeDB to an existing Postgres image, use the ParadeDB extension image instead of the full paradedb/paradedb image. Extension images require Postgres 18+ because they depend on extension_control_path. Add the pg_search extension image to the postgresql.extensions section of your CloudNativePG Cluster resource:

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:
      - name: pg_search
        image:
          reference: docker.io/paradedb/paradedb-extension:{version}-18-trixie
        extension_control_path:
          - /share
        dynamic_library_path:
          - /lib

Then enable the extension in a database:

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

The extension image tag format is <paradedb-version>-<postgres-major>-trixie. For example, use {version}-18-trixie for ParadeDB {version} on Postgres 18.

Connect to the Cluster

The command to connect to the primary instance of the cluster will be printed in your terminal. If you do not modify any settings, it will be:

kubectl --namespace paradedb exec --stdin --tty services/paradedb-rw -- bash

This will launch a Bash shell inside the instance. You can connect to the ParadeDB database via psql with:

psql -d paradedb

Connect to the Grafana Dashboard

To connect to the Grafana dashboard for your cluster, we suggested port forwarding the Kubernetes service running Grafana to localhost:

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

You can then access the Grafana dashboard at localhost:3000 using admin as the username and prom-operator as the password. These default credentials are defined in the kube-stack-config.yaml file used as the values.yaml file in Install the Prometheus Stack and can be modified by providing your own values.yaml file. A more detailed guide on monitoring the cluster can be found in the CloudNativePG documentation.

Deployment

Index Maintenance

Performance

Administration

Continuous Integration

Prerequisites

Install the Prometheus Stack

Install the CloudNativePG Operator

Start a ParadeDB CNPG Cluster

Use the Extension Image with CloudNativePG

Connect to the Cluster

Connect to the Grafana Dashboard

​Prerequisites

​Install the Prometheus Stack

​Install the CloudNativePG Operator

​Start a ParadeDB CNPG Cluster

​Use the Extension Image with CloudNativePG

​Connect to the Cluster

​Connect to the Grafana Dashboard

Prerequisites

Install the Prometheus Stack

Install the CloudNativePG Operator

Start a ParadeDB CNPG Cluster

Use the Extension Image with CloudNativePG

Connect to the Cluster

Connect to the Grafana Dashboard