Bring your own Kubernetes

BYOK8s is currently in early access. To enable BYOK8s for your organization, contact our support team.

The Bring Your Own Kubernetes (BYOK8s) plan lets you run RisingWave in your own Kubernetes cluster while RisingWave manages the database workloads. Unlike BYOC where RisingWave manages the entire data plane infrastructure, BYOK8s gives you full control over the underlying cloud resources — networking, IAM, storage, and the Kubernetes cluster itself — while RisingWave handles the Kubernetes-level workloads and cluster operations.

BYOC vs BYOK8s

Aspect	BYOC	BYOK8s
Infrastructure (VPC, K8s, networking)	RisingWave manages	Customer manages
IAM roles and policies	RisingWave provisions	Customer provisions
Security groups and firewalls	RisingWave manages	Customer manages
K8s workloads (Agent, Proxy, Operator)	RisingWave manages	RisingWave manages
RisingWave clusters	RisingWave manages	RisingWave manages
Object storage	RisingWave provisions	Customer provisions
Observability	RisingWave provisions	RisingWave deploys telemetry stack; customer provisions storage (S3 buckets)

Architecture overview

In a BYOK8s environment, RisingWave deploys and manages the following components in your Kubernetes cluster:

CloudAgent: Handles operations sent by the RisingWave control plane (cluster provisioning, scaling, upgrades).
RWProxy: Routes PostgreSQL protocol traffic from the control plane and user clients to the appropriate RisingWave instances.
RisingWave Operator: Manages RisingWave Custom Resource lifecycle in Kubernetes.
Self-hosted telemetry stack: VictoriaMetrics (metrics), Loki (logs), and Grafana Alloy (collection) — deployed automatically inside the BYOK8s cluster. No external observability services are required.

Communication between the RisingWave control plane and your BYOK8s cluster is established via private network connectivity (AWS PrivateLink), ensuring all traffic stays off the public internet.

Prerequisites

Before setting up a BYOK8s environment, you must provision the following resources in your cloud account.

Reference Terraform examples are available at risingwavelabs/risingwave-byok-terraform-example. They provision all of the prerequisites below and generate the config files used by the rwc CLI. Fork and adapt to your network/security requirements.

aws/base_env — VPC, EKS, S3, KMS, IAM, NLBs + VPC Endpoint Services
aws/k8s_addons — cert-manager and mode-specific node pools; standard EKS also installs the AWS Load Balancer Controller and Karpenter (emits byok_config.yaml)
aws/tenant_resources — per-cluster RDS metastore + IAM role (emits byok_tenant_config.yaml)

1. Kubernetes cluster

Provider: Amazon EKS
Version: Kubernetes 1.32 or higher
Region: Must be in the same AWS region as the RisingWave Cloud control plane
Cluster mode: Standard EKS or EKS Auto Mode

Choose the cluster mode before you register the BYOK8s environment. The aws.eks_auto_mode setting is stored when you run rwc byok create and cannot be changed with rwc byok update. RisingWave does not support an in-place migration between standard EKS and EKS Auto Mode; create a new BYOK8s environment to change modes.

The following Kubernetes namespaces are reserved for RisingWave-managed components. Do not create or use these namespaces for your own workloads — RisingWave will create and manage them during BYOK8s environment setup and cluster provisioning.

Namespace	Component
`rw-cloudagent`	CloudAgent
`rwproxy`	RWProxy
`risingwave-operator-system`	RisingWave Operator
`rw-victoria-metrics`	VictoriaMetrics (metrics storage)
`rw-loki`	Loki (log storage)
`rw-telemetry-collector`	Grafana Alloy
`rw-kube-state-metrics`	kube-state-metrics
`rw-kubernetes-event-exporter`	kubernetes-event-exporter
`rw-hcm-suppressor`	High cardinality metrics suppressor
`rwc-*`	RisingWave clusters (one namespace per cluster)

2. Cluster dependencies

Install cert-manager v1.19.2 or later in both cluster modes. The remaining dependencies differ by mode:

Cluster mode	Additional software dependencies
Standard EKS	AWS Load Balancer Controller Helm chart 1.17.0 or later and Amazon EBS CSI Driver v1.54.0 or later
EKS Auto Mode	None. Use the built-in load-balancing and EBS storage capabilities. Do not install the self-managed AWS Load Balancer Controller or Amazon EBS CSI Driver for this setup.

In EKS Auto Mode, RisingWave creates native eks.amazonaws.com/v1 TargetGroupBinding resources. In a standard EKS cluster, RisingWave creates elbv2.k8s.aws/v1beta1 TargetGroupBinding resources that the self-managed AWS Load Balancer Controller reconciles.

3. Object storage

Provision two separate storage buckets in the same region as your Kubernetes cluster.

Bucket	Purpose
Data store	RisingWave state store (cluster data)
Log store	Loki log storage (self-hosted telemetry)

We recommend separate buckets so that data and logs can have independent lifecycle policies, access controls, and retention. The data store typically contains sensitive cluster state, while the log store contains observability data with different access and retention requirements.

Provide the S3 bucket ARNs for both buckets.

4. Encryption at rest

Provide a KMS key ARN for EBS encryption. This is used by VictoriaMetrics and Loki persistent volumes, RisingWave compute cache storage, and encrypted EKS worker-node storage.

The KMS key policy must allow the key to be used for EBS encryption. Otherwise, worker nodes can fail to join the cluster or become NotReady, persistent volume claims for VictoriaMetrics, Loki, and the RisingWave compute cache can remain Pending, and rwc byok apply will fail.

For standard EKS, grant the IAM principal used by the Amazon EBS CSI controller the required KMS permissions.For EKS Auto Mode, the key policy must grant:

Allow the EKS cluster IAM role and the AWSServiceRoleForAutoScaling service-linked role to encrypt, decrypt, and re-encrypt data; generate data keys; describe the key; and create grants for AWS resources.
Allow the EKS cluster IAM role to create, list, and revoke grants for AWS resources.
Allow principals in the same AWS account that are authorized to use EBS to use the key through EC2. Restrict this statement with kms:CallerAccount and kms:ViaService set to ec2.<region>.amazonaws.com.

The IAM role used by an Auto Mode NodeClass does not need to be an explicit key-policy principal when the account-scoped EBS condition is present. See the reference Terraform example for a working policy.

5. Terraform state backend

Provision an S3 bucket and a DynamoDB table for storing BYOK8s environment Terraform state and state locking. CloudAgent uses this backend to manage Terraform resources inside your Kubernetes cluster, and the IAM policy in the next step references both.

6. Identity and access management

You must create the following IAM roles:A. Setup IAM (user context)This role is used by the person or CI/CD pipeline running the BYOK8s setup commands. It is not used by any in-cluster workloads.

Must have eks:DescribeCluster permission on the target EKS cluster.
Must have an access entry in the EKS cluster with the AmazonEKSClusterAdminPolicy access policy attached.

B. CloudAgent IAM (service context)This role is assumed by CloudAgent via IRSA. CloudAgent needs access to both the data store bucket (for cluster state operations) and the Terraform state backend (S3 bucket plus DynamoDB lock table) that it uses to manage in-cluster resources. Minimum permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DataStore",
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::$DATA_STORE_BUCKET",
                "arn:aws:s3:::$DATA_STORE_BUCKET/*"
            ]
        },
        {
            "Sid": "TerraformStateBucket",
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::$TFSTATE_BUCKET",
                "arn:aws:s3:::$TFSTATE_BUCKET/*"
            ]
        },
        {
            "Sid": "TerraformStateLock",
            "Effect": "Allow",
            "Action": "dynamodb:*",
            "Resource": "arn:aws:dynamodb:$REGION:$ACCOUNT_ID:table/$TFLOCK_TABLE"
        }
    ]
}

Where $TFSTATE_BUCKET and $TFLOCK_TABLE correspond to the S3 bucket and DynamoDB table provisioned in Terraform state backend.C. Loki IAM (service context)This role is assumed by Loki via IRSA for reading and writing logs to S3. Minimum permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::$LOG_STORE_BUCKET",
                "arn:aws:s3:::$LOG_STORE_BUCKET/*"
            ]
        }
    ]
}

7. Network connectivity

Provision two internal Network Load Balancers with VPC Endpoint Services for PrivateLink connectivity from the RisingWave control plane.CloudAgent NLB — one target group per port:

Port	Protocol	Purpose
40001	TCP	Service port
40090	TCP	Metrics and status

RWProxy NLB — one target group per port. The webhook listener port differs from its target port (the control plane reaches it on 443 over TLS; the RWProxy pod listens on 4580); pgwire and metrics use the same port on both sides.

Listener port	Target port	Protocol	Purpose
4566	4566	TCP	PostgreSQL protocol
443	4580	TCP	Webhook (HTTPS)
9099	9099	TCP	Metrics and status

For each NLB, create a VPC Endpoint Service and allow the RisingWave control plane AWS account (600598779918) as an allowed principal.

EKS Auto Mode load-balancing requirements

EKS Auto Mode reconciles the pre-created target groups through its native TargetGroupBinding API. In addition to the shared NLB requirements above:

Add the tag eks:eks-cluster-name=<cluster-name> to all five target groups.
Attach a target-traffic security group to both NLBs, and allow outbound TCP traffic from it to ports 40001, 40090, 4566, 4580, and 9099.
Allow inbound TCP traffic from the target-traffic security group to the EKS cluster primary security group on the same five ports.
If clients connect directly to the RWProxy NLB, attach a separate client-access security group only to that NLB and allow inbound TCP traffic on port 4566 from the approved client CIDRs or security groups.
Ensure every Auto Mode NodeClass selects the EKS cluster primary security group.
Set the NLB attribute enforce_security_group_inbound_rules_on_private_link_traffic to off for the PrivateLink traffic used by this setup.

The standard EKS bindings carry their own target network rules, so these NLB security-group resources are Auto Mode-only. The AWS reference example configures the control-plane PrivateLink path for both modes. In Auto Mode, it attaches the target-traffic security group to both NLBs and a dedicated client-access security group only to the RWProxy NLB. The client-access security group allows direct RWProxy connections from the VPC CIDR by default; set rwproxy_additional_client_cidrs for clients that arrive through peering, Transit Gateway, or another routed network.

Standard EKS Terraform example for NLBs and VPC Endpoint Services

# CloudAgent NLB
resource "aws_lb" "cloudagent" {
  name               = "${var.prefix}-ca"
  internal           = true
  load_balancer_type = "network"
  subnets            = var.private_subnet_ids
  enable_cross_zone_load_balancing = true
}

resource "aws_lb_target_group" "cloudagent" {
  name        = "${var.prefix}-ca"
  port        = 40001
  protocol    = "TCP"
  target_type = "ip"
  vpc_id      = var.vpc_id
}

resource "aws_lb_target_group" "cloudagent_zpage" {
  name        = "${var.prefix}-cazp"
  port        = 40090
  protocol    = "TCP"
  target_type = "ip"
  vpc_id      = var.vpc_id
}

resource "aws_lb_listener" "cloudagent" {
  load_balancer_arn = aws_lb.cloudagent.arn
  port              = 40001
  protocol          = "TCP"
  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.cloudagent.arn
  }
}

resource "aws_lb_listener" "cloudagent_zpage" {
  load_balancer_arn = aws_lb.cloudagent.arn
  port              = 40090
  protocol          = "TCP"
  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.cloudagent_zpage.arn
  }
}

resource "aws_vpc_endpoint_service" "cloudagent" {
  acceptance_required        = false
  network_load_balancer_arns = [aws_lb.cloudagent.arn]
  allowed_principals         = ["arn:aws:iam::600598779918:root"]
}

# RWProxy NLB
resource "aws_lb" "rwproxy" {
  name               = "${var.prefix}-rp"
  internal           = true
  load_balancer_type = "network"
  subnets            = var.private_subnet_ids
  enable_cross_zone_load_balancing = true
}

resource "aws_lb_target_group" "rwproxy_internal" {
  name        = "${var.prefix}-rpi"
  port        = 4566
  protocol    = "TCP"
  target_type = "ip"
  vpc_id      = var.vpc_id
}

resource "aws_lb_target_group" "rwproxy_metrics" {
  name        = "${var.prefix}-rpm"
  port        = 9099
  protocol    = "TCP"
  target_type = "ip"
  vpc_id      = var.vpc_id
}

resource "aws_lb_target_group" "rwproxy_webhook" {
  name        = "${var.prefix}-rpw"
  port        = 4580
  protocol    = "TCP"
  target_type = "ip"
  vpc_id      = var.vpc_id
}

resource "aws_lb_listener" "rwproxy_internal" {
  load_balancer_arn = aws_lb.rwproxy.arn
  port              = 4566
  protocol          = "TCP"
  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.rwproxy_internal.arn
  }
}

resource "aws_lb_listener" "rwproxy_metrics" {
  load_balancer_arn = aws_lb.rwproxy.arn
  port              = 9099
  protocol          = "TCP"
  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.rwproxy_metrics.arn
  }
}

resource "aws_lb_listener" "rwproxy_webhook" {
  load_balancer_arn = aws_lb.rwproxy.arn
  port              = 443 # externally exposed listener port; target group still forwards to pod port 4580
  protocol          = "TCP"
  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.rwproxy_webhook.arn
  }
}

resource "aws_vpc_endpoint_service" "rwproxy" {
  acceptance_required        = false
  network_load_balancer_arns = [aws_lb.rwproxy.arn]
  allowed_principals         = ["arn:aws:iam::600598779918:root"]
}

Create a BYOK8s environment

BYOK8s uses the rwc CLI to provision and manage environments. Before continuing, install and authenticate the CLI by following Install the RisingWave Cloud CLI.

Step 1: Prepare the configuration file

Create a YAML configuration file with your infrastructure details:

cloud_provider: aws
region: us-west-2

aws:
  account_id: "123456789012"
  eks_cluster_name: my-eks-cluster
  eks_auto_mode: false # Set to true for an EKS Auto Mode cluster.

  s3_buckets:
    data_store_arn: arn:aws:s3:::my-risingwave-data
    log_store_arn: arn:aws:s3:::my-risingwave-logs

  ebs_encryption_key_arn: arn:aws:kms:us-west-2:123456789012:key/...

  iam_roles:
    cloudagent_role_arn: arn:aws:iam::123456789012:role/RisingWaveCloudAgent
    loki_role_arn: arn:aws:iam::123456789012:role/RisingWaveLoki

  network_load_balancers:
    cloudagent_target_group_arn: arn:aws:elasticloadbalancing:...
    cloudagent_zpage_target_group_arn: arn:aws:elasticloadbalancing:...
    rwproxy_target_group_arn: arn:aws:elasticloadbalancing:...
    rwproxy_webhook_target_group_arn: arn:aws:elasticloadbalancing:...
    rwproxy_metrics_target_group_arn: arn:aws:elasticloadbalancing:...
    cloudagent_subnet_cidrs:
      - 10.0.1.0/24
      - 10.0.2.0/24
    rwproxy_subnet_cidrs:
      - 10.0.3.0/24
      - 10.0.4.0/24
    cloudagent_vpc_endpoint_service_name: com.amazonaws.vpce.us-west-2.vpce-svc-...
    rwproxy_vpc_endpoint_service_name: com.amazonaws.vpce.us-west-2.vpce-svc-...

  terraform_state:
    s3_bucket_name: my-risingwave-byok-tfstate
    dynamodb_table_name: my-risingwave-byok-tflock

For a standard EKS cluster, leave aws.eks_auto_mode set to false. For EKS Auto Mode, set it to true. The value defaults to false when omitted, must match the existing cluster mode when you register the environment, and cannot be changed later with rwc byok update.

Optional: pod scheduling and custom settings

You can optionally configure pod scheduling for different workload types and add custom tags:

customized_settings:
  scheduling:
    system_workload:
      tolerations:
        - key: dedicated
          operator: Equal
          value: risingwave-system
          effect: NoSchedule
      nodeAffinity:
        requiredDuringSchedulingIgnoredDuringExecution:
          nodeSelectorTerms:
            - matchExpressions:
                - key: node-type
                  operator: In
                  values:
                    - risingwave-system
    cluster_workload:
      tolerations:
        - key: dedicated
          operator: Equal
          value: risingwave
          effect: NoSchedule
    telemetry_workload:
      tolerations:
        - key: dedicated
          operator: Equal
          value: telemetry
          effect: NoSchedule
    update_workload:
      tolerations:
        - key: dedicated
          operator: Equal
          value: update
          effect: NoSchedule
  tags:
    team: data-platform
    cost-center: engineering
  metrics_settings:
    hcm_suppressor_replicas: 1
    scraping_interval_secs: 30
    discarded_metrics_regex:
      - "^rw_connector_.*"

See Node pool resource requirements for sizing guidance on each workload category.

Step 2: Register the environment

rwc byok create --name <env-name> --config <path-to-config.yaml>

Step 3: Deploy resources

rwc byok apply --name <env-name>

This deploys all RisingWave-managed components to your EKS cluster via Terraform. The control plane then establishes PrivateLink connectivity and verifies the environment. Once complete, the environment status transitions to Ready.

You can run rwc byok prepare --name <env-name> to download the Terraform modules without applying them — useful for reviewing changes before deployment.

Create a RisingWave cluster

Creating a RisingWave cluster in a BYOK8s environment uses a two-phase provisioning flow. This is because the IRSA trust policy for the cluster’s IAM role requires the Kubernetes namespace and service account name, which are only allocated after the cluster is initially created.

Cluster creation in a BYOK8s environment is currently available only via the rwc CLI. RisingWave Cloud portal support is planned but not yet implemented. Once the cluster is provisioned, you can manage it (including rescaling components and adjusting replicas) from the RisingWave Cloud portal as usual.

Phase 1: Create the cluster

Create the cluster via the rwc CLI. A BYOK8s cluster must use --tier BYOK together with per-component sizing flags, and the --env flag must point to the BYOK8s environment registered with rwc byok create. The metastore is not configured at this step — the customer-managed PostgreSQL connection details are supplied in Phase 2 via rwc cluster byok-config.

rwc cluster create \
  --name <cluster-name> \
  --tier BYOK \
  --env <byok-env-name> \
  --compute p-4c16g    --compute-replica 1 \
  --compactor p-2c8g   --compactor-replica 1 \
  --frontend p-2c8g    --frontend-replica 1 \
  --meta p-2c8g        --meta-replica 1

Where:

--name — name of the new RisingWave cluster.
--tier BYOK — required tier for clusters running in a BYOK8s environment.
--env — name of the BYOK8s environment registered with rwc byok create.
--compute / --compactor / --frontend / --meta — component-type IDs that match instance shapes available in your Kubernetes cluster. Component IDs follow the pattern p-<X>c<Y>g, where X is the number of CPU cores and Y is the amount of memory in GiB (for example, p-4c16g means 4 CPU and 16 GiB memory). The values above are a small example sizing (1 replica each at p-4c16g for compute and p-2c8g for the rest); replace them to match your workload. Run rwc cluster create --help for the full flag list.
--*-replica — replica count for each component.

The cluster starts in AwaitingConfig status. The success message from rwc cluster create includes the cluster’s UUID and the exact rwc cluster byok-config command to run next; you can also list existing clusters and their UUIDs with rwc cluster list. At this point, the control plane has allocated the Kubernetes namespace and service account name. Retrieve them with:

rwc cluster describe --uuid <cluster-uuid>

Look for the Resource Namespace and Service Account fields in the output. You will need these values for the IAM trust policy in the next step.

Phase 2: Provision IAM and metastore, then configure

Create an IAM role for the RisingWave cluster with an IRSA trust policy. Use the Resource Namespace and Service Account values from the rwc cluster describe output in Phase 1:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::$ACCOUNT_ID:oidc-provider/$OIDC_PROVIDER"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "$OIDC_PROVIDER:aud": "sts.amazonaws.com",
          "$OIDC_PROVIDER:sub": "system:serviceaccount:$RESOURCE_NAMESPACE:$SERVICE_ACCOUNT"
        }
      }
    }
  ]
}

Grant S3 access to the cluster’s data and backup prefixes in the data store bucket. RisingWave stores cluster state under data-$RESOURCE_NAMESPACE/ and meta backups under data-$RESOURCE_NAMESPACE-backup/, so both prefixes must be included:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::$DATA_STORE_BUCKET",
                "arn:aws:s3:::$DATA_STORE_BUCKET/data-$RESOURCE_NAMESPACE/*",
                "arn:aws:s3:::$DATA_STORE_BUCKET/data-$RESOURCE_NAMESPACE-backup/*"
            ]
        }
    ]
}

Provision a PostgreSQL database as the metadata store. We recommend using Amazon RDS. Ensure connectivity from the EKS cluster pods to the database.
Choose the metastore password using only these characters: uppercase and lowercase letters (A-Z, a-z), digits (0-9), and the four symbols underscore (_), tilde (~), period (.), and hyphen (-). No other characters are allowed — in particular, spaces and symbols such as @, /, and : are not. RisingWave Cloud embeds this password in the metastore connection URL, so a password containing unsupported characters is rejected by rwc cluster byok-config with an HTTP 400 error, even though your database may accept it. Fixing that means rotating the password and reconfiguring the database, so pick a compliant one before you create the database.

Submit the configuration via CLI:

rwc cluster byok-config --uuid <cluster-uuid> --config <path-to-config.yaml>

Config file format:

aws:
  iam_role_arn: "arn:aws:iam::123456789012:role/MyRisingWaveRole"
metastore:
  host: "my-rds-instance.abc123.us-west-2.rds.amazonaws.com"
  port: 5432
  database: "risingwave_meta"
  username: "postgres"
  password: "..."

You can set the RWC_BYOK_METASTORE_PASSWORD environment variable instead of including the password in the YAML file. The environment variable takes precedence.

This transitions the cluster to Creating status and triggers provisioning. The metastore password is encrypted at rest.

Connect to a RisingWave cluster

There are two ways to connect to a RisingWave cluster running in a BYOK8s environment.

Option 1: RisingWave Cloud Console (recommended)

Use the in-portal SQL console — no network setup is required. See Console overview for details.

Option 2: Direct connection via RWProxy NLB

For programmatic access (e.g., from your own applications, BI tools, or psql), connect to the RWProxy NLB you provisioned in the prerequisites.

The RWProxy NLB is internal-only. Clients must be inside the same VPC as the BYOK8s environment, or reach the NLB via VPC peering / Transit Gateway.

For EKS Auto Mode, attach a client-access security group only to the RWProxy NLB before using direct connections. Allow inbound TCP traffic on port 4566 from the approved client CIDRs or security groups. The reference Terraform example allows its VPC CIDR by default and accepts additional routed CIDRs through rwproxy_additional_client_cidrs. Disabling NLB security-group enforcement for PrivateLink traffic does not allow direct VPC client traffic.

Because a single RWProxy NLB serves multiple clusters in the BYOK8s environment, you must include the cluster identifier (the Kubernetes namespace allocated to your cluster in Phase 1) in the connection. Retrieve it via:

rwc cluster describe --uuid <cluster-uuid>
# Look for: Resource Namespace: rwc-xxxxxxxxxxxx-<cluster-name>

The cluster identifier can be passed via the options field, the host (SNI), or the username. See Connection errors → Tenant identifier methods for all three methods. Example using the options field:

psql "postgresql://<username>:<password>@<rwproxy-nlb-dns>:4566/<database>?options=--tenant%3D<cluster-namespace>"

%3D is the URL-encoded form of =. If your client does not require URL encoding, use --tenant=<cluster-namespace> directly. Where:

<rwproxy-nlb-dns> — DNS name of the RWProxy NLB (the load balancer behind rwproxy_target_group_arn)
4566 — RWProxy PostgreSQL port
<database> — database name (default: dev)
<cluster-namespace> — the Resource Namespace from rwc cluster describe
<username> / <password> — credentials created via rwc cluster dbuser create

Node pool resource requirements

If you use dedicated node pools for different workload types (via the customized_settings.scheduling configuration), the following minimum resources are required: The same workload categories and minimum sizing apply to both standard EKS and EKS Auto Mode:

Category	Components	Minimum node pool resources
`system_workload`	CloudAgent, RWProxy, Operator, high cardinality metrics suppressor	3x `m7g.large` (or machines with equivalent combined resources)
`cluster_workload`	RisingWave cluster pods (meta, frontend, compute, compactor)	Depends on your RisingWave cluster size
`telemetry_workload`	VictoriaMetrics, Loki	1x `m7g.xlarge` (or a machine with equivalent resources). The workload cannot be split across machines smaller than `m7g.xlarge`.
`update_workload`	Terraform apply task pods	1x `m7g.2xlarge` (or a machine with equivalent resources). Same constraint: `m7g.2xlarge` is the minimum individual machine size.

DaemonSet scheduling (Grafana Alloy) is automatically derived from the union of all workload tolerations — no separate configuration is needed.

Manage a BYOK8s environment

List environments

rwc byok list

View environment details

rwc byok describe --name <env-name>

Update an environment

To update a BYOK8s environment (e.g., to apply a new version or change custom settings):

rwc byok update --name <env-name> [--version <version>] [--custom-settings-path <path>]
rwc byok apply --name <env-name>

The cluster mode cannot be updated. To switch between standard EKS and EKS Auto Mode, create a new BYOK8s environment configured for the target mode.

Delete a BYOK8s environment

Delete all RisingWave clusters running in the environment.
Terminate the environment (control plane side):
rwc byok terminate --name <env-name>
Delete the Kubernetes resources and control plane record:
rwc byok delete --name <env-name>
Clean up the cloud resources you provisioned (NLBs, VPC Endpoint Services, IAM roles, storage buckets, etc.).

Shared responsibility

BYOK8s is a shared responsibility model. The table below outlines what each party is responsible for.

RisingWave responsibilities

All cluster and project-level operations available on the RisingWave Cloud portal.
24/7 monitoring backed by the RisingWave support and on-call teams.
Version and configuration management of all deployed workloads (CloudAgent, RWProxy, Operator, telemetry stack).

Customer responsibilities

Kubernetes cluster and worker nodes (including upgrades to the minimum supported version).
Firewall and security group rules.
IAM roles / service accounts used by BYOK8s environments and clusters.
Object storage buckets for data storage and log storage.
Network connectivity resources (NLBs and VPC Endpoint Services on AWS).
PostgreSQL databases serving as metadata stores.
Terraform state backend.
Encryption keys (KMS on AWS).

Features not available in BYOK8s

BYOK8s uses AWS PrivateLink for control plane connectivity (customer provisions the VPC Endpoint Services, control plane creates the VPC Endpoints). The features below refer to RisingWave-managed capabilities that are available in BYOC but not in BYOK8s.

Feature	Reason
RisingWave-managed PrivateLink for data access	In BYOC, RisingWave can provision PrivateLink endpoints for connecting your applications to RisingWave clusters. In BYOK8s, you manage your own network connectivity.
Cluster IAM customization via portal	In BYOC, you can add or modify IAM roles for RisingWave clusters through the portal. In BYOK8s, you provision and manage all IAM roles directly.

Get started

Work with data

Install & Operate

Performance

Troubleshooting

Reference

Cloud

Bring your own Kubernetes

BYOC vs BYOK8s

Architecture overview

Prerequisites

1. Kubernetes cluster

2. Cluster dependencies

3. Object storage

4. Encryption at rest

5. Terraform state backend

6. Identity and access management

7. Network connectivity

EKS Auto Mode load-balancing requirements

Create a BYOK8s environment

Step 1: Prepare the configuration file

Step 2: Register the environment

Step 3: Deploy resources

Create a RisingWave cluster

Phase 1: Create the cluster

Phase 2: Provision IAM and metastore, then configure

Connect to a RisingWave cluster

Option 1: RisingWave Cloud Console (recommended)

Option 2: Direct connection via RWProxy NLB

Node pool resource requirements

Manage a BYOK8s environment

List environments

View environment details

Update an environment

Delete a BYOK8s environment

Shared responsibility

RisingWave responsibilities

Customer responsibilities

Features not available in BYOK8s

​BYOC vs BYOK8s

​Architecture overview

​Prerequisites

​1. Kubernetes cluster

​2. Cluster dependencies

​3. Object storage

​4. Encryption at rest

​5. Terraform state backend

​6. Identity and access management

​7. Network connectivity

​EKS Auto Mode load-balancing requirements

​Create a BYOK8s environment

​Step 1: Prepare the configuration file

​Step 2: Register the environment

​Step 3: Deploy resources

​Create a RisingWave cluster

​Phase 1: Create the cluster

​Phase 2: Provision IAM and metastore, then configure

​Connect to a RisingWave cluster

​Option 1: RisingWave Cloud Console (recommended)

​Option 2: Direct connection via RWProxy NLB

​Node pool resource requirements

​Manage a BYOK8s environment

​List environments

​View environment details

​Update an environment

​Delete a BYOK8s environment

​Shared responsibility

​RisingWave responsibilities

​Customer responsibilities

​Features not available in BYOK8s

BYOC vs BYOK8s

Architecture overview

Prerequisites

1. Kubernetes cluster

2. Cluster dependencies

3. Object storage

4. Encryption at rest

5. Terraform state backend

6. Identity and access management

7. Network connectivity

EKS Auto Mode load-balancing requirements

Create a BYOK8s environment

Step 1: Prepare the configuration file

Step 2: Register the environment

Step 3: Deploy resources

Create a RisingWave cluster

Phase 1: Create the cluster

Phase 2: Provision IAM and metastore, then configure

Connect to a RisingWave cluster

Option 1: RisingWave Cloud Console (recommended)

Option 2: Direct connection via RWProxy NLB

Node pool resource requirements

Manage a BYOK8s environment

List environments

View environment details

Update an environment

Delete a BYOK8s environment

Shared responsibility

RisingWave responsibilities

Customer responsibilities

Features not available in BYOK8s