Kubernetes (Helm)

This guide walks you through the process of deploying RisingWave in a single Kubernetes cluster with Helm.

Prerequisites

• Ensure you have Helm 3.7 + installed in your environment. For details about how to install Helm, see the Helm documentation.
• Ensure you have Kubernetes 1.24 or higher installed in your environment.
• Ensure you allocate enough resources for the deployment. For details, see Hardware requirements.

Step 1: Start Kubernetes

Start a Kubernetes cluster. For details about starting a Kubernetes cluster, see Kubernetes’ Getting started guide.

Step 2: Start RisingWave

Now start a RisingWave cluster with Helm.

1. Add the RisingWave Helm chart repository:

   helm repo add risingwavelabs https://risingwavelabs.github.io/helm-charts/ --force-update
   
2. Update your Helm chart repositories to ensure that you are using the RisingWave Helm chart:

   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:

   aws eks update-kubeconfig --name <your_eks_cluster_name>
   
3. Create a RisingWave namespace. We recommend creating a dedicated namespace for RisingWave resources.

   kubectl create namespace risingwave
   
4. Customize your configuration for the RisingWave deployment by editing the values.yaml file.

   • Customize meta store: The meta store in RisingWave holds metadata for cluster operations. See Configuration for all the available options and Examples for detailed usage of meta stores.
     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.

   • Customize state store: The state store in RisingWave serves as a fault-tolerant storage system for preserving system state. See Configuration for all the available options and Examples 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 for more details. To enable this feature, set tags.bundle=true.
     Before using the bundled PostgreSQL and MinIO, and any local stores, ensure that you have implemented the Dynamic Volume Provisioning.

5. Install the latest RisingWave Helm chart:

   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.

   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:

   NAME: my-risingwave
   LAST DEPLOYED: Wed Aug 16 15:35:19 2023
   NAMESPACE: default
   STATUS: deployed
   REVISION: 1
   TEST SUITE: None
   
6. Use the following command to check the deployment status:

   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:

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

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:

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.

Optional: Resize a node

By editing the configurations in 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 for details.

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.

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:

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

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.