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

# Kubernetes (Helm)

> This guide walks you through the process of deploying RisingWave in a single Kubernetes cluster with [Helm](https://helm.sh/).

## Prerequisites

* Ensure you have Helm 3.7 + installed in your environment. For details about how to install Helm, see the [Helm documentation](https://helm.sh/docs/intro/install/).
* Ensure you have [Kubernetes](https://kubernetes.io/) 1.24 or higher installed in your environment.
* Ensure you allocate enough resources for the deployment. For details, see [Hardware requirements](/deploy/hardware-requirements).

## Step 1: Start Kubernetes

Start a Kubernetes cluster. For details about starting a Kubernetes cluster, see Kubernetes' [Getting started guide](https://kubernetes.io/docs/setup/).

## Step 2: Start RisingWave

Now start a RisingWave cluster with Helm.

<Steps>
  <Step>
    Add the RisingWave Helm chart repository:

    ```bash theme={null}
    helm repo add risingwavelabs https://risingwavelabs.github.io/helm-charts/ --force-update
    ```
  </Step>

  <Step>
    Update your Helm chart repositories to ensure that you are using the RisingWave Helm chart:

    ```bash theme={null}
    helm repo update
    ```

    If you are using AWS EKS, you also need to update the local configuration for kubectl and Helm to access your EKS cluster:

    ```bash theme={null}
    aws eks update-kubeconfig --name <your_eks_cluster_name>
    ```
  </Step>

  <Step>
    Create a RisingWave namespace. We recommend creating a dedicated namespace for RisingWave resources.

    ```bash theme={null}
    kubectl create namespace risingwave
    ```
  </Step>

  <Step>
    Customize your configuration for the RisingWave deployment by editing the [values.yaml](https://github.com/risingwavelabs/helm-charts/blob/main/charts/risingwave/values.yaml) file.

    * **Customize meta store**: The meta store in RisingWave holds metadata for cluster operations. See [Configuration](https://github.com/risingwavelabs/helm-charts/blob/main/docs/CONFIGURATION.md#customize-meta-store) for all the available options and [Examples](https://github.com/risingwavelabs/helm-charts/tree/main/examples/meta-stores) for detailed usage of meta stores.
          <Note>
            If using PostgreSQL as the meta store, make sure the PostgreSQL user configured in your Helm values has at least `USAGE` permission on the `public` schema.
          </Note>
    * **Customize state store**: The state store in RisingWave serves as a fault-tolerant storage system for preserving system state. See [Configuration](https://github.com/risingwavelabs/helm-charts/blob/main/docs/CONFIGURATION.md#customize-state-store) for all the available options and [Examples](https://github.com/risingwavelabs/helm-charts/tree/main/examples/state-stores) for detailed usage of state stores.
    * **Bundled PostgreSQL and MinIO**: If you want to use `PostgreSQL` as the meta store and `MinIO` as the state store, the Helm chart for RisingWave offers the option to bundle them together. This allows for a quick and easy setup of the Helm chart. See [Configuration](https://github.com/risingwavelabs/helm-charts/blob/main/docs/CONFIGURATION.md#bundled-etcdpostgresqlminio-as-stores) for more details. To enable this feature, set `tags.bundle=true`.
          <Note>
            Before using the bundled `PostgreSQL` and `MinIO`, and any local stores, ensure that you have implemented the [Dynamic Volume Provisioning](https://kubernetes.io/docs/concepts/storage/dynamic-provisioning/).
          </Note>
  </Step>

  <Step>
    Install the latest RisingWave Helm chart:

    ```bash theme={null}
    helm install -n risingwave --create-namespace --set wait=true -f values.yaml <my-risingwave> risingwavelabs/risingwave
    ```

    Where `<my-risingwave>` is the release name you choose to use for your RisingWave deployment. This command will install the latest stable version of RisingWave.
    If you want to install a particular version, you can specify the version via the `image-tag` attribute. Remember to replace `<version_number>` with the desired version, for example `v1.7.0`.

    ```bash theme={null}
    helm install -n risingwave --create-namespace --set wait=true --set image.tag=<version_number> <my-risingwave> -f values.yaml risingwavelabs/risingwave
    ```

    You may get an output message like this:

    ```yaml theme={null}
    NAME: my-risingwave
    LAST DEPLOYED: Wed Aug 16 15:35:19 2023
    NAMESPACE: default
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    ```
  </Step>

  <Step>
    Use the following command to check the deployment status:

    ```bash theme={null}
    kubectl -n risingwave get pods -l app.kubernetes.io/instance=<my-risingwave>
    ```

    When your status looks like below, it means the RisingWave cluster starts successfully:

    ```bash theme={null}
    NAME                                   READY   STATUS    RESTARTS        AGE
    risingwave-compactor-8dd799db6-hdjjz   1/1     Running   1 (8m33s ago)   11m
    risingwave-compute-0                   2/2     Running   0               11m
    risingwave-postgresql-0                1/1     Running   0               11m
    risingwave-frontend-7bd7b8c856-czdgd   1/1     Running   1 (8m33s ago)   11m
    risingwave-meta-0                      1/1     Running   0               11m
    risingwave-minio-5cfd8f5f64-6msqm      1/1     Running   0               11m
    ```
  </Step>
</Steps>

## Step 3: Access RisingWave

By default, the RisingWave Helm Chart will deploy a ClusterIP service that enables the cluster-local communication.

Once deployed, you can forward your local machine's port **`4567`** to the service's port via:

```bash theme={null}
kubectl -n risingwave port-forward svc/my-risingwave 4567:svc
```

You can then connect to RisingWave using a PostgreSQL client on port 4567. For example:

```bash theme={null}
psql -h localhost -p 4567 -d dev -U root
```

## Step 4: Monitor performance

You can monitor the RisingWave cluster using the monitoring stack. For details, see [Monitoring a RisingWave cluster](/operate/monitor-risingwave-cluster).

## Optional: Resize a node

By editing the configurations in [values.yaml](https://github.com/risingwavelabs/helm-charts/blob/main/charts/risingwave/values.yaml), you can resize a worker node. The Compactor Node configurations are in the `compactorComponent` section. Configurations for the Meta Node and Serving / Streaming Node are in `metaComponent` and `computeComponent` sections respectively. See [Customize pods of different components](https://github.com/risingwavelabs/helm-charts/blob/main/docs/CONFIGURATION.md#customize-pods-of-different-components) for details.

<Warning>
  **Always set resource `requests` and `limits` to the same values for each component.** Mismatched values place pods in the `Burstable` QoS class, which makes scheduling less predictable and leaves pods more vulnerable to eviction under resource pressure — especially in on-premises deployments.
</Warning>

Setting `requests` equal to `limits` places pods in the Kubernetes **Guaranteed** QoS class, which provides:

* **Predictable scheduling**: Kubernetes can more accurately schedule pods on nodes with sufficient resources.
* **Eviction protection**: Guaranteed pods are the last to be evicted under resource pressure.
* **Consistent performance**: More predictable CPU and memory availability for RisingWave pods.
* **Resource isolation**: Better protection from noisy neighbors in multi-tenant clusters.

### Recommended minimum sizes

RisingWave is memory-intensive. When sizing components, use a **1:4 CPU:memory ratio** (for example, 1 CPU core to 4 GiB memory). The recommended minimum sizes for each component in distributed mode are:

| Component                          | Minimum resources          |
| :--------------------------------- | :------------------------- |
| Compute (Streaming / Serving Node) | 4 CPU cores, 16 GiB memory |
| Compactor Node                     | 2 CPU cores, 8 GiB memory  |
| Meta Node                          | 1 CPU core, 4 GiB memory   |
| Frontend Node                      | 1 CPU core, 4 GiB memory   |

### Example configuration

The following example shows how to set equal `requests` and `limits` with a 1:4 CPU:memory ratio:

```yaml theme={null}
# To resize other types of node, replace the section name with
# computeComponent, metaComponent, or frontendComponent.
compactorComponent:
  resources:
    limits:
      cpu: 2
      memory: 8Gi
    requests:
      cpu: 2
      memory: 8Gi
```

Please note that increasing the CPU resource will not automatically increase the parallelism of existing materialized views. When scaling up (adding more CPU cores) a Streaming Node, you should perform the scaling by following the instructions in [Cluster scaling](/deploy/k8s-cluster-scaling).

## Set up RisingWave Console

After deploying your RisingWave cluster with Helm, we recommend setting up RisingWave Console. The Console provides a web interface for managing and monitoring your cluster. It simplifies daily operations and helps you quickly collect and share diagnostic information when contacting RisingWave support team.

For detailed instructions, see [RisingWave Console setup guide](/web-ui/introduction).

<head>
  <script type="application/ld+json">
    {`
          {
            "@context": "https://schema.org",
            "@type": "HowTo",
            "name": "How to deploy RisingWave on Kubernetes with Helm",
            "description": "Deploy a RisingWave streaming database cluster on Kubernetes using Helm charts. Includes cluster setup, configuration, connecting via psql, and monitoring.",
            "step": [
              {
                "@type": "HowToStep",
                "name": "Start Kubernetes",
                "text": "Ensure you have a running Kubernetes cluster. You can use minikube, kind, EKS, GKE, or AKS."
              },
              {
                "@type": "HowToStep",
                "name": "Install RisingWave with Helm",
                "text": "Add the RisingWave Helm repo, update repos, create a namespace, customize values.yaml, and run helm install to deploy the RisingWave cluster."
              },
              {
                "@type": "HowToStep",
                "name": "Connect to RisingWave",
                "text": "Use kubectl port-forward to expose the frontend service, then connect with psql: psql -h localhost -p 4566 -d dev -U root"
              },
              {
                "@type": "HowToStep",
                "name": "Monitor and scale",
                "text": "Access the Grafana dashboard to monitor performance metrics. Resize compute and compactor nodes by updating resource configurations in values.yaml."
              }
            ]
          }
          `}
  </script>
</head>