> ## Documentation Index
> Fetch the complete documentation index at: https://www.paradedb.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes

> How to deploy ParadeDB as a Kubernetes cluster into production

For Kubernetes deployments, we recommend running ParadeDB with [CloudNativePG](https://cloudnative-pg.io/). Both ParadeDB Community and Enterprise binaries can be deployed on Kubernetes.

<Note>
  ParadeDB Community can run on Kubernetes as a single-node deployment. Use
  [ParadeDB Enterprise](/docs/operate/deploy/enterprise) when ParadeDB indexes need
  physical replication for [high
  availability](/docs/operate/deploy/self-hosted/high-availability), failover, or
  read replicas that can serve ParadeDB queries.
</Note>

This guide uses the [ParadeDB Helm Chart](https://github.com/paradedb/charts). The chart 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/).

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

```bash theme={null}
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.

```bash theme={null}
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:

<CodeGroup>
  ```yaml ParadeDB Community theme={null}
  type: paradedb
  mode: standalone

  cluster:
    instances: 1
    storage:
      size: 256Mi
  ```

  ```yaml ParadeDB Enterprise theme={null}
  type: paradedb-enterprise
  mode: standalone

  cluster:
    instances: 1
    storage:
      size: 256Mi
  ```
</CodeGroup>

<Note>
  If you are using ParadeDB Enterprise for high availability, set `instances` to
  a number greater than `1`.
</Note>

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

```bash theme={null}
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.

```bash ParadeDB Enterprise theme={null}
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.

```bash theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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`](https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/samples/monitoring/kube-stack-config.yaml)
file used as the `values.yaml` file in [Install the Prometheus Stack](#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](https://cloudnative-pg.io/docs/1.30/monitoring).