---
title: Kubernetes
description: Run ParadeDB in an existing Kubernetes cluster
canonical: https://www.paradedb.com/docs/operate/deploy/self-hosted/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](#deploying-with-the-helm-chart) to install CloudNativePG and deploy your ParadeDB cluster.
- **If you already use CloudNativePG**, use the [ParadeDB extension image](#using-the-extension-image-with-cloudnativepg) to add ParadeDB to your existing cluster.

---

## Deploying with the Helm Chart

The [ParadeDB Helm Chart](https://github.com/paradedb/charts) is based on [CloudNativePG](https://cloudnative-pg.io/) and is also available on [Artifact Hub](https://artifacthub.io/packages/helm/paradedb/paradedb).

### Prerequisites

This guide assumes you have installed [Helm](https://helm.sh/docs/intro/install/) and have a Kubernetes cluster running v1.29+.
For local testing, we recommend [Minikube](https://minikube.sigs.k8s.io/docs/start/).

Create the `paradedb` namespace.

```bash
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.

```bash 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:

```bash
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.

```bash
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`](https://github.com/paradedb/charts/blob/dev/charts/paradedb/values.yaml) for available configuration options and their defaults. Here is a basic example:

<CodeGroup>

```yaml ParadeDB Community
type: paradedb
mode: standalone

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

monitoring:
  grafanaDashboard:
    create: true
```

```yaml ParadeDB Enterprise
type: paradedb-enterprise
mode: standalone

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

monitoring:
  grafanaDashboard:
    create: true
```

</CodeGroup>

Finally, launch the ParadeDB cluster.

```bash
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`:

```bash
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:

```bash
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](https://cloudnative-pg.io/docs/1.30/monitoring).

---

## Using the Extension Image with CloudNativePG

The ParadeDB extension image uses CloudNativePG's [image volume support](https://cloudnative-pg.io/docs/1.28/imagevolume_extensions/) 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](https://cloudnative-pg.io/docs/1.28/imagevolume_extensions/) 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.

```bash 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](https://github.com/pgvector/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`:

<CodeGroup>

```yaml ParadeDB Community
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
```

```yaml ParadeDB Enterprise
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
```

</CodeGroup>

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

```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:

```bash
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`.