Configure Oxia

Oxia support is experimental in StreamNative Private Cloud v1. Use it only when your StreamNative Platform version, Pulsar image, Oxia image, and support guidance require it.

Private Cloud v1 uses the Helm-based sn-platform and sn-platform-slim charts. ZooKeeper is the default metadata store. To deploy a new Pulsar cluster with Oxia instead of ZooKeeper, set pulsar_metadata.provider to oxia in your Helm values file.

This page applies to Private Cloud v1 Helm deployments.

Before you begin

Before you enable Oxia, confirm the following:

The StreamNative Platform chart version supports pulsar_metadata.provider: oxia.
The Pulsar image and Oxia image versions are supported together. For Oxia-based clusters, use a StreamNative Platform 4.2.x image. Earlier 3.3.x images do not include the Oxia schema storage classes required by this configuration.
The StreamNative Operator version installed in the cluster supports the Oxia resources and Private Cloud metadata wiring resources generated by the chart.
SQL worker is not supported yet with Oxia. The chart rejects components.sql_worker: true when pulsar_metadata.provider is oxia.
Function package management is not supported yet with Oxia. Do not rely on Pulsar package upload workflows for functions in Oxia-backed clusters.
The deployment does not use ZooKeeper-only metadata settings such as metadataPrefix, pulsar_metadata.userProvidedZookeepers, or pulsar_metadata.configurationStoreServers.

Do not switch an existing production cluster from ZooKeeper to Oxia by only changing the Helm value. Metadata migration changes the backing store for cluster state and requires a separate migration plan.

Configure Helm values

Create or update your Pulsar cluster values file with the Oxia metadata provider. Minimal configuration:

pulsar_metadata:
  provider: oxia

Optional Oxia settings:

oxia:
  replicaCount: 3
  dataserver:
    resources:
      requests:
        cpu: "0.5"
        memory: "1Gi"
  coordinator:
    resources:
      requests:
        cpu: "0.25"
        memory: "512Mi"

images:
  oxia:
    repository: oxia/oxia
    tag: <supported-oxia-version>

Supported values:

Field	Description
`pulsar_metadata.provider`	Set to `oxia` to render Oxia-backed metadata resources instead of ZooKeeper metadata wiring. Valid values are `zookeeper` and `oxia`.
`oxia.replicaCount`	Number of Oxia server replicas. The chart defaults to `3` and rejects values lower than `3` for Oxia metadata deployments.
`oxia.labels`	Labels added to generated Oxia resources and propagated to the `OxiaCluster` spec.
`oxia.annotations`	Annotations added to the generated `OxiaCluster` resource.
`oxia.dataserver.resources`	Resource requests and limits for Oxia server pods.
`oxia.coordinator.resources`	Resource requests and limits for the Oxia coordinator.
`oxia.istio.authRules`	Optional Istio authorization rules for Oxia traffic when global Istio is enabled. If omitted, the chart generates rules for Oxia ports.
`images.oxia.repository`	Oxia image repository.
`images.oxia.tag`	Oxia image tag. Choose the Oxia image tag validated for your StreamNative Platform and Pulsar image version.
`images.oxia.pullPolicy`	Kubernetes image pull policy for the Oxia image.

The chart sets OxiaCluster.spec.monitoringEnabled automatically. It is true only when Prometheus monitoring is enabled and the cluster has Prometheus Operator PodMonitor CRDs; otherwise the chart renders it as false.

Deploy the cluster

Install the cluster with your values file:

helm install -f /path/to/pulsar-oxia-values.yaml <release_name> streamnative/sn-platform-slim --set initialize=true -n <k8s_namespace>

Use streamnative/sn-platform instead if your deployment requires the full chart. To update an existing non-production test cluster, update the values file and run:

helm upgrade -f /path/to/pulsar-oxia-values.yaml <release_name> streamnative/sn-platform-slim -n <k8s_namespace>

When pulsar_metadata.provider is oxia, the chart renders the Oxia resources needed by the Pulsar cluster, including:

OxiaCluster for the Oxia server cluster.
OxiaNamespace resources for broker, BookKeeper, Pulsar schema, Kafka schema, and function metadata.
Private Cloud metadata wiring for Oxia-backed broker and schema metadata URLs.
Broker and BookKeeper configuration that points metadata traffic to Oxia.

In Private Cloud v1, configure Oxia through Helm values instead of editing the generated resources directly. The generated broker configuration sets the metadata store, configuration metadata store, schema storage, Kafka schema registry, and topic policy service settings for Oxia. You do not need to configure Oxia metadata URLs separately unless you are building custom chart templates or overriding the generated wiring.

Verify the deployment

After the Helm release is deployed, verify that the Oxia resources and Pulsar components are ready:

kubectl get oxiacluster,oxianamespace -n <k8s_namespace>
kubectl get pods -n <k8s_namespace>

Run a broker health check from the toolset pod:

kubectl exec -n <k8s_namespace> <toolset-pod-name> -- \
  bin/pulsar-admin --admin-url http://<broker-service-name>:8080 brokers healthcheck

The health check should return ok.

Overview

Quick Start

Streamnative Console

Clients

Connectors

Monitor

References

Operating Streamnative Platform

Tools

Before you begin

Configure Helm values

Deploy the cluster

Verify the deployment

​Before you begin

​Configure Helm values

​Deploy the cluster

​Verify the deployment

Before you begin

Configure Helm values

Deploy the cluster

Verify the deployment