Install RisingWave Console

Deploy RisingWave Console v0.8.0, configure its metadata store, and grant optional Kubernetes permissions incrementally.

RisingWave Console is a self-hosted service. It stores users, cluster connections, tasks, and settings in its own PostgreSQL database. This Console metadata database is separate from both the RisingWave metadata store and the object store used for RisingWave state.

Production builds require a signed RisingWave license key. Provide it with RW_LICENSE_KEY or, preferably, mount it as a file and set RW_LICENSE_KEY_PATH. For an older license-free evaluation, see the v0.5.1 trial steps. Features documented for v0.8.0 are not necessarily available in that trial version.

Choose a deployment target

Target	Console metadata PostgreSQL	Best for
Docker with v0.8.0-pgbundle	Runs inside the Console container	Quick starts and disposable tests
Docker with v0.8.0	External PostgreSQL	Durable single-host deployments
Kubernetes with v0.8.0-pgbundle	Runs inside the Console pod	Small, self-contained tests
Kubernetes with v0.8.0	External PostgreSQL	Production and restricted clusters

Prefer external PostgreSQL for durable Console metadata. Use a strong root password, protect the Console endpoint, and back up the metadata database.

Key configuration

Setting	Required	Description
RW_LICENSE_KEY	Unless RW_LICENSE_KEY_PATH is set	Signed license token. Avoid putting it in manifests or shell history.
RW_LICENSE_KEY_PATH	Unless RW_LICENSE_KEY is set	Path to the mounted license file.
RCONSOLE_ROOT_PASSWORD	Recommended	Password synchronized to the explicit root configuration at startup. The unsafe default is root. If you later change the password in the UI, update this deployment value too; otherwise a restart can restore the configured value.
RCONSOLE_SERVER_PG_DSN	For non-pgbundle deployments	Console metadata PostgreSQL DSN. Preserve its database, schema or search_path, and TLS options during upgrades.
RCONSOLE_SERVER_PORT	Optional	Console HTTP port. The default is 8020.
RCONSOLE_SERVER_METRICSPORT	Optional	Console metrics port. The default is 9020.
RCONSOLE_NOINTERNET	Optional	Prevents downloads when set to true.
RCONSOLE_RISECTLDIR	Optional	Directory containing versioned risectl binaries.
RCONSOLE_HELM_CHART_DIR	Optional	Directory containing Helm archives for optional Environment installation.

Docker quick start

The bundled-PostgreSQL image is convenient for a quick start:

export RW_LICENSE_KEY="<your-signed-license-token>"

docker run -d -p 8020:8020 --name risingwave-console \
  -e RCONSOLE_ROOT_PASSWORD="<strong-password>" \
  -e RW_LICENSE_KEY="$RW_LICENSE_KEY" \
  risingwavelabs/risingwave-console:v0.8.0-pgbundle

Open http://localhost:8020 and sign in as root.

For a durable deployment, use external PostgreSQL and mount the license:

docker-compose.yaml

services:
  risingwave-console:
    image: risingwavelabs/risingwave-console:v0.8.0
    ports:
      - "8020:8020"
    environment:
      RCONSOLE_ROOT_PASSWORD: <strong-password>
      RCONSOLE_SERVER_PG_DSN: postgres://<user>:<password>@<host>:5432/<database>?sslmode=require
      RW_LICENSE_KEY_PATH: /etc/rconsole/license.jwt
    volumes:
      - ./license.jwt:/etc/rconsole/license.jwt:ro

Start it with docker compose up -d. The PostgreSQL user must be able to create and migrate Console metadata tables.

Kubernetes deployment

The v0.8.0 starter manifests create only Console runtime resources: a Namespace, ServiceAccount, Secret, StatefulSet, Service, and, where applicable, storage. They do not grant optional RisingWave CR or Environment-management privileges.

The human or platform identity applying a starter manifest must already be allowed to create those runtime resources. Download and review the manifest that matches your metadata deployment:

• External PostgreSQL manifest (v0.8.0)
• Bundled PostgreSQL manifest (v0.8.0)

Replace every placeholder in the Secret before applying a manifest. Do not commit rendered Secrets.

The external-PostgreSQL manifest runs Console as a non-root process with the runtime-default seccomp profile, disables privilege escalation, and drops Linux capabilities. Use this path for OpenShift restricted-v2. The bundled PostgreSQL process has different runtime requirements; do not weaken a restricted cluster’s security policy merely to use pgbundle.

The pgbundle image runs as UID/GID 1001 and creates /risingwave-console-data/.risectl during startup. Its starter sets fsGroup: 1001 so storage drivers that support Kubernetes volume ownership management make the mounted PVC writable. If your driver does not support this mechanism, have the platform provide equivalent write permission before startup. A root-owned 0755 volume can otherwise prevent .risectl creation. Do not run Console as root or add privileged access to work around volume permissions.

kubectl apply -f console-external-pg.yaml
kubectl -n risingwave-console get pods

The starter Service exposes Console on NodePort 30020 and its Prometheus metrics on 30090. Adjust the Service or put an authenticated TLS proxy in front of it for production.

The Kubernetes pgbundle starter persists Console files under /risingwave-console-data, but it does not persist the bundled PostgreSQL metadata directory. Export that database before replacing or rescheduling the pod. Custom Docker volume layouts can behave differently.

Grant Kubernetes permissions incrementally

Connecting SQL, Meta, and metrics endpoints does not require a RisingWave CR grant. Add Kubernetes access only for the workflows that an administrator approves.

Workflow	Additional Kubernetes grants
Connect existing SQL, Meta, and metrics endpoints	No CR grants. Each endpoint still needs connectivity, credentials, and any required tools or configuration.
Observe one known CR	get on the single named risingwaves resource in its namespace.
Find the connected CR	Observation plus get on the exact SQL and Meta Services. No CR or Service collection listing.
Delegate replica, CPU/memory, or image changes	Retain observation; add patch on the same named CR and get on the exact Services.
Install a full Environment	A separate, broader opt-in Environment-manager and cluster-installer profile.

These grants are additive. Applying a narrow profile does not revoke older bindings, so inventory dependent workflows before removing broad permissions.

Register the same-cluster target

A platform administrator registers trusted targets in Console deployment configuration. Console organization administrators can use targets assigned to their organization; they cannot supply arbitrary credentials or namespaces.

config.yaml

kubernetes:
  consoleNamespace: risingwave-console
  targets:
    - id: production
      organizationID: 1 # Example only: replace with the intended Console organization ID.
      displayName: Production cluster
      connectionMode: inClusterServiceAccount
      allowedNamespaces: [risingwave-prod]

Sign in to Console with an account in the intended organization. Open your browser’s developer tools, select Network, and reload the page. Find the request to GET /api/v1/me, open its Response, and read the orgId value. Use that value as organizationID in the target configuration. Run these steps in the target organization’s login context; a platform administrator’s current organization is not necessarily the target. Do not assume organization 1.

You do not need to copy or share the session token. Do not copy the Authorization header, export a HAR file, or paste a token into a command line, issue, or chat. Do not open the API endpoint directly in the address bar because it might not use the same authentication as the Console frontend.

Release images run in /app, and Console loads config.yaml from its working directory. With the standard image, mount the complete configuration at /app/config.yaml:

spec:
  template:
    spec:
      containers:
        - name: console
          image: risingwavelabs/risingwave-console:v0.8.0
          workingDir: /app
          volumeMounts:
            - name: console-config
              mountPath: /app/config.yaml
              subPath: config.yaml
      volumes:
        - name: console-config
          configMap:
            name: risingwave-console-config

Merge the kubernetes section into your existing complete configuration and preserve any environment-based overrides. Do not replace a pgbundle image’s bundled configuration with a targets-only file.

Save the resulting complete file locally as config.yaml, then create or update the ConfigMap:

kubectl -n risingwave-console create configmap risingwave-console-config \
  --from-file=config.yaml=./config.yaml \
  --dry-run=client -o yaml | kubectl apply -f -

Add the volumeMounts and volumes entries above to the existing StatefulSet without replacing its Secrets, environment settings, or other mounts. Then apply the updated workload and perform a normal rollout:

kubectl -n risingwave-console apply -f path/to/console-statefulset.yaml
kubectl -n risingwave-console rollout restart statefulset/risingwave-console
kubectl -n risingwave-console rollout status statefulset/risingwave-console

The walkthrough in Connect to your RisingWave clusters uses this same-cluster target. A separately registered remote target can provide observation, but an in-cluster ServiceAccount binding does not authorize a remote identity, and v0.8.0 does not support delegated remote writes.

Apply named-object RBAC

The samples use:

• Console Namespace and ServiceAccount: risingwave-console / risingwave-console
• RisingWave namespace: risingwave-prod
• RisingWave CR: rw-prod
• SQL Service: rw-prod-frontend
• Meta Service: rw-prod-meta

Service names are examples, not a naming rule. Substitute the actual Services. Meta RPC and HTTP can use the same Service.

All samples create a namespace-scoped Role and RoleBinding in the RisingWave namespace. The RoleBinding subject is the Console pod’s actual ServiceAccount and can be in a different namespace.

1. For exact-name observation, apply observe-rbac.yaml. It grants only get on rw-prod. Reading CR status does not require a separate risingwaves/status rule.
2. To use Find connected CR, also apply discovery-rbac.yaml. It grants only get on the exact SQL and Meta Services.
3. For approved writes, keep the observer grant and apply delegated-rbac.yaml. It grants only patch on the named CR and get on the exact Services. Because it includes the Service reads, applying the discovery profile first is optional.

kubectl apply -f observe-rbac.yaml
kubectl apply -f discovery-rbac.yaml # Optional unless using Find connected CR.

RoleBinding additions normally take effect without restarting Console or redeploying RisingWave or its Operator.

RBAC is only one authorization layer. The Console image must support the workflow, the target and organization must match, the Console user must be authorized, and execution-time identity and precondition checks must pass. Kubernetes RBAC cannot restrict which CR fields a patch request changes; Console’s operation APIs restrict v0.8.0 operations to supported fields.

Upgrade from v0.7.9 to v0.8.0

The following procedure uses external PostgreSQL. Do not apply a starter manifest over an existing deployment or replace existing Secrets and configuration wholesale.

1. Inventory the deployment. Record the exact image or digest, Console PostgreSQL database, schema or search_path, DSN and TLS options, license, certificates, SSO settings, ServiceAccount, configuration, initialization files, and persistent files.
2. Prepare a tested recovery point. Arrange a maintenance window, stop Console writers and scheduled work, and resolve in-flight or uncertain operations. Back up Console PostgreSQL, restore it to an independent database, and start the old image against that restored copy. A successful dump alone is not a recovery test. Browser-local SQL drafts and RisingWave data are not in this backup.
3. Review initialization. RCONSOLE_INIT and initialization files can overwrite later UI edits on restart. Preserve the schema or search_path and PostgreSQL TLS files and options. Keep shared-workspace mode disabled for this ordinary upgrade; this procedure is not an organization migration.
4. Upgrade one compatible instance. Replace only the Console image and configuration that must change. Preserve its metadata database, license, identity, network settings, and storage. Let one v0.8.0 instance run startup migrations; do not run old and new Console versions concurrently against a migrating database. This does not upgrade RisingWave or its Operator and does not grant or revoke Kubernetes RBAC.
5. Verify Console. Test normal login or SSO, ownership and existing settings, a read-only SQL query, configured metrics, Risectl > Check CLI, and a permitted read-only Meta command where configured. Check CLI checks the selected executable; it is not a cluster health or compatibility test.
6. Opt into CR workflows separately. Register a target and apply observe, discovery, or delegated RBAC only after the base upgrade is healthy. Applying RBAC does not add v0.8.0 APIs or UI to a v0.7.9 image.
7. Roll back by restoring, not downgrading in place. Stop v0.8.0, preserve its current audit and metadata state, and run the old image with a separately restored pre-upgrade database and compatible configuration. Do not assume an in-place down migration. Restoring Console metadata does not undo CR changes or SQL writes.

Binary deployment

If your organization provides a Console binary, run it on a compatible Linux host with external PostgreSQL and the same environment settings described above:

export RCONSOLE_SERVER_PG_DSN="postgres://<user>:<password>@<host>:5432/<database>?sslmode=require"
export RCONSOLE_ROOT_PASSWORD="<strong-password>"
export RW_LICENSE_KEY_PATH="/etc/rconsole/license.jwt"
./risingwave-console

This documentation does not define a new public standalone-binary download channel. Obtain the artifact through your existing authorized distribution process.

Verify the installation

1. Open Console and sign in.
2. Configure a strong RCONSOLE_ROOT_PASSWORD. If you change it in the UI, update the deployment value so a later restart does not restore an older configured password.
3. Confirm the Console metadata database is reachable and backed up.
4. Connect an existing cluster with Connect to your RisingWave clusters.
5. If applicable, verify SQL TLS, metrics, and a read-only Meta command independently.

Troubleshooting startup

Symptom	Check
Console exits with a license error	Verify the mounted file or RW_LICENSE_KEY and confirm the token is valid.
PostgreSQL connection fails	Check DNS, port, credentials, database, schema or search_path, TLS files, and sslmode.
Kubernetes pod is pending	Check the StorageClass, PVC, node resources, security context, and image pull access.
Target is missing	Confirm the complete /app/config.yaml was mounted, the organization ID and namespace are correct, and Console was rolled out after the change.
CR access is denied	Verify the Role is in the CR namespace and the RoleBinding subject matches the Console pod ServiceAccount and namespace.
Console starts but a Meta command fails across namespaces	Check every advertised Meta leader and member address, not only the initial Service endpoint. See Air-gapped deployment troubleshooting.