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

# Release Note v0.21

> StreamNative Operator Helm chart 0.21.2 release notes.

StreamNative Operator Helm chart **0.21.2** deploys Operator **v0.21.17**. This release adds virtual Kafka clusters, SQL workspace management, and new Pulsar storage and authentication options.

These notes cover changes from Operator **v0.20.18** (Helm chart **0.20.6**) to **v0.21.17**. For the release package, see the [Helm chart 0.21.2 release](https://github.com/streamnative/private-cloud/releases/tag/sn-operator-0.21.2).

## New features

### Virtual Kafka clusters

* Added the `VirtualKafkaCluster` resource to expose logical Kafka clusters through a shared `KafkaCluster`. Each virtual cluster supports a canonical cluster ID, tenant identity, topic defaults, and Ursa storage settings.
* The Operator manages virtual cluster metadata in Oxia and publishes connection endpoints and readiness in resource status.
* Added Kafka authorization configuration under `KafkaCluster.spec.config.authorization`, including `authorizerClass` and superusers.

Virtual Kafka cluster management is an alpha feature that defaults to off. Enable `VKC_KAFKA_ENABLE` on the Operator only after configuring Istio, Oxia metadata storage, and compatible Kafka broker authentication and routing. The backing `KafkaCluster` must also enable virtual clusters through the `cloud.streamnative.io/kafka-vkc-enabled` annotation.

### Workspace and catalog management

* Added a `SQLWorkspace` controller to manage RisingWave runtimes, component resources, storage, and SQL superusers. Workspaces support OAuth authentication and publish HTTP and PostgreSQL wire protocol endpoints.
* Added the `SQLCatalog` resource to discover Pulsar or Kafka topics and synchronize supported schemas into RisingWave sources. Protocol and Schema Registry endpoints can use separate credentials, including Kubernetes Secret references.
* Added the `SQLGateway` resource for shared PostgreSQL wire protocol and WebSocket access, TLS termination, workspace routing, and horizontal pod scaling.

SQL workspace management is an alpha feature that defaults to off. Enable `SQL_WORKSPACE_ENABLE` only after installing the RisingWave Operator and its CRDs and configuring workspace storage and credentials. Shared gateway access also requires Istio and TLS configuration. For production workspaces, pin the RisingWave image to a release tag or digest.

### Pulsar tiered storage

Configure Pulsar tiered storage through `PulsarBroker.spec.config.managedLedgerOffloadConfig` with `type: pulsar-tiered-storage-v2`. The `pulsarTieredStorage` settings support Amazon S3, [GCS](https://cloud.google.com/storage), and Azure Blob Storage, with a bucket prefix to isolate each cluster's offloaded objects.

This configuration requires the v2 configuration generator and a StreamNative Pulsar image in the `4.0` series at **4.0.12.2 or later**, or **4.2.1.10 or later**. Existing Ursa Lakehouse offload configurations retain `ursa-lakehouse` as the default type. The new mode doesn't apply when you enable legacy `tieredStorageConfig` or classic-engine Ursa stream backed tables.

### Metadata store connections

* **Oxia configuration files:** Added `BookKeeperCluster.spec.metadataStoreConfig` and `PulsarBroker.spec.bkMetadataStoreConfig` for authenticated and TLS-enabled Oxia connections. Configure an explicit metadata service URI alongside the corresponding Oxia settings. The Operator mounts the configuration files for BookKeeper, AutoRecovery, and the broker's BookKeeper client.
* **Native ZooKeeper TLS:** Set `PulsarBroker.spec.configurationStoreConfig.zk.tlsMode` to `native` to connect directly to a shared ZooKeeper configuration store over TLS. This requires a Pulsar image that supports separate configuration-store TLS settings. For mutual TLS, the referenced Secret must contain `keystore.p12` and `truststore.p12`, both using the password `changeit`. The default TLS mode remains `istio`.
* **Oxia endpoints:** `OxiaCluster.status.publicAddress` now reports the public bootstrap address for clusters with an Istio gateway.

### Authentication and observability

* **OpenID Connect federation:** Added `spec.config.authentication.oidc` to load the OpenID Connect (OIDC) federation authentication provider. It requires `authentication.apiKey` and a compatible Pulsar image. Configure identity providers and identity pools through the broker's OIDC management API after enabling the provider.
* **Detector CA certificates:** Added `spec.detector.tlsTrustCertsSecret` on Coordinator resources to verify Pulsar, Kafka, and Schema Registry server certificates with a custom CA. When you configure a CA Secret with mTLS client credentials, the Operator no longer adds the insecure TLS fallback. The detector image must support the corresponding CA certificate flags.
* **Schema Registry connections:** Kafka `Connection` resources now accept a Schema Registry URL with OAuth 2.0 or Secret-based basic authentication.
* **Full metrics authorization:** Added `PulsarCoordinator.spec.fullMetrics.authorizationMode: ControlPlaneRBAC` to delegate authorization to a separately managed Istio authorization policy while retaining JWT authentication. Configure that policy before selecting this mode. The default remains `Scope`.

### Function and agent API configuration

* Added `PulsarFunctionsWorker.spec.config.enableCompute` and `enableAgents` to control the compute and managed agent APIs independently. Both fields default to `true`.
* Added `spec.config.managedAgentCredit` to reference a ConfigMap name and key in the job namespace. The value must be `true` to allow managed agent requests when you configure this gate.

## Improvements

### Istio resilience

Pulsar Broker and Proxy routing now supports `spec.istio.resilience`:

* **Outlier detection:** Enabled by default to temporarily remove failing endpoints from load balancing. Defaults are two consecutive gateway errors, a 5-second analysis interval, a 30-second base ejection time, and a maximum ejection percentage of 50. Set `outlierDetection.disabled: true` to turn it off.
* **HTTP retries:** Disabled by default. Set `retries.disabled: false` to enable retries on HTTP routes. The default policy allows one retry with a 10-second timeout per attempt. Review retry conditions before enabling retries for operations that can have duplicate effects.

### Oxia resource defaults

The Operator fills missing CPU and memory requests and limits using these defaults:

| Component | CPU request | Memory request | CPU limit | Memory limit |
| - | - | - | - | - |
| Server | 1 | 4 GiB | 2 | 8 GiB |
| Coordinator | 500m | 1 GiB | 1 | 2 GiB |

The Operator preserves explicit nonzero settings. When filling a missing value, it adjusts the default to keep the request within the limit. The default server persistent volume size remains 4 GiB.

### Topic policies and function images

* Added a metadata-store topic policy backend default for eligible clusters using the v2 configuration generator. It applies to StreamNative Pulsar **4.0.10.5 or later in the 4.0 series**, or **4.2.1.2 or later**, at rollout level **20 or higher** through the `cloud.streamnative.io/rollout-level` annotation. It preserves custom backend settings and excludes Ursa-enabled clusters.
* Function Mesh function pods now use `imagePullPolicy: Always` so newly started pods check for updates to their runner images.

## Bug fixes and security updates

### Updates since Helm chart 0.21.0

* Added chart role-based access control (RBAC) permissions to manage Istio `RequestAuthentication` resources, create and patch Kubernetes Events, and update `sqlgateways/finalizers`.
* Updated the CA trust store in Alpine-based Operator images to remove trust in compromised certificate chains.
* Updated the Operator build to Go **1.26.10** to address **CVE-2026-111943** and the compression dependency to **1.18.7** for a security fix.

### Other fixes in the 0.21 series

* Fixed connectivity and metrics scraping during Istio sidecar removal by retaining mesh resources until the rollout completes and removing stale TLS-mode labels.
* Fixed Oxia metadata store URL handling to preserve explicit URLs and include namespaces in generated URLs. Broker initialization and metadata cleanup jobs now receive the required metadata configuration files and authentication Secrets.
* Fixed PfSQL authentication propagation from structured broker API key and JWT settings, including Secret-based tokens and OAuth 2.0 scope settings.
* Fixed the full metrics kube-state ServiceMonitor to preserve scraped labels.
* Fixed missing Oxia diagnostic context in generated logging configurations.
* Updated OpenTelemetry dependencies to **1.45.0** to address **CVE-2026-81870**. Updated Go cryptography and networking dependencies and the build image for additional security fixes.

## Upgrade notes

1. Apply the CRDs from Helm chart **0.21.2** before upgrading the Operator. Helm upgrades don't update existing CRDs automatically. This release includes new `VirtualKafkaCluster`, `SQLCatalog`, and `SQLGateway` definitions and updated schemas for existing resources.
2. Upgrade to Helm chart **0.21.2**, which installs Operator **v0.21.17**, and retain your existing Helm configuration. Apply the CRDs and upgrade the Operator before upgrading the platform chart.
3. Plan a maintenance window for changes to generated workload configuration. Review Oxia resource requests and limits before the upgrade, especially when existing manifests omit them. Confirm that nodes can accommodate the new defaults.
4. Review Istio outlier detection and function image pull behavior. Ensure that function pods can reach their image registry when they start.
5. Keep the SQL workspace and virtual Kafka cluster feature gates off until you configure their dependencies. Custom Operator RBAC must include the new resources and, for SQL workspaces, permissions to manage RisingWave resources and gateway scaling. Include the chart permissions for Istio `RequestAuthentication` resources, Kubernetes Events, and `sqlgateways/finalizers` when maintaining custom RBAC.

Use the CRDs and chart from the [0.21.2 release package](https://github.com/streamnative/private-cloud/releases/tag/sn-operator-0.21.2) together. For license and namespace prerequisites, see [Upgrade StreamNative Operator](https://docs.streamnative.io/private-cloud/v2/operate-private-cloud/upgrade/upgrade-sn-operator.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.