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

# Configure Oxia

<Warning>
  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.
</Warning>

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.

<Note>
  This page applies to Private Cloud v1 Helm deployments.
</Note>

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

```yaml theme={null}
pulsar_metadata:
  provider: oxia
```

Optional Oxia settings:

```yaml theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
kubectl get oxiacluster,oxianamespace -n <k8s_namespace>
kubectl get pods -n <k8s_namespace>
```

Run a broker health check from the toolset pod:

```bash theme={null}
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`.