Upgrade default Apache Pulsar version to 5.0.0

.ci/clusters/values-pulsar-previous-lts.yaml

@@ -17,45 +17,11 @@
 # under the License.
 #
 
-defaultPulsarImageTag: 3.0.17
-
-# Pulsar 3.0.x runs on JDK 17, which doesn't support -XX:+ZGeneration, therefore it's necessary to
-# override the PULSAR_GC options to use ZGC.
-
-zookeeper:
-  configData:
-    PULSAR_GC: >
-      -XX:+UseZGC
-      -XX:+AlwaysPreTouch
-      -XX:+UseTransparentHugePages
-      -XX:+ExitOnOutOfMemoryError
-      -XX:+DisableExplicitGC
-      -XX:+PerfDisableSharedMem
-bookkeeper:
-  configData:
-    PULSAR_GC: >
-      -XX:+UseZGC
-      -XX:+AlwaysPreTouch
-      -XX:+UseTransparentHugePages
-      -XX:+ExitOnOutOfMemoryError
-      -XX:+DisableExplicitGC
-      -XX:+PerfDisableSharedMem
-broker:
-  configData:
-    PULSAR_GC: >
-      -XX:+UseZGC
-      -XX:+AlwaysPreTouch
-      -XX:+UseTransparentHugePages
-      -XX:+ExitOnOutOfMemoryError
-      -XX:+DisableExplicitGC
-      -XX:+PerfDisableSharedMem
-
-proxy:
-  configData:
-    PULSAR_GC: >
-      -XX:+UseZGC
-      -XX:+AlwaysPreTouch
-      -XX:+UseTransparentHugePages
-      -XX:+ExitOnOutOfMemoryError
-      -XX:+DisableExplicitGC
-      -XX:+PerfDisableSharedMem
+# Previous LTS Pulsar version. This is also used in all upgrade tests that install a previously released
+# chart version so that Pulsar 5.0 is never deployed with an older chart version.
+# Pulsar 5.0.0 no longer publishes the apachepulsar/pulsar-all image. Set the repository explicitly since
+# previously released chart versions default to apachepulsar/pulsar-all.
+# Chart versions before 4.6.0 can't run the apachepulsar/pulsar 4.0.x image (they hard-code a BookKeeper
+# statsProviderClass that isn't included in it), so upgrade tests must start from 4.6.0 or later.
+defaultPulsarImageRepository: apachepulsar/pulsar
+defaultPulsarImageTag: 4.0.14

.ci/clusters/values-pulsar-v5-functions.yaml

@@ -20,16 +20,12 @@
 # Test Pulsar v5 together with Oxia and Pulsar Functions.
 #
 # This combines the examples/values-oxia.yaml and examples/values-functions-fs-storage.yaml scenarios on the
-# Pulsar 5.0.0-M1 image: it runs Functions on an Oxia-backed cluster (no ZooKeeper). Functions require the
+# Pulsar 5.0.0 image: it runs Functions on an Oxia-backed cluster (no ZooKeeper). Functions require the
 # broker-hosted Packages Management Service; its default BookKeeper package storage needs ZooKeeper, so
 # FileSystemPackagesStorage is enabled instead (no ZooKeeper dependency). The function smoke test
 # (ci::test_pulsar_function) creates a function from a JAR, which uploads the package via the broker's
 # FileSystem-backed Packages Management Service.
 
-# Use the slim apachepulsar/pulsar image (not the default apachepulsar/pulsar-all) at the v5 milestone tag.
-defaultPulsarImageRepository: apachepulsar/pulsar
-defaultPulsarImageTag: 5.0.0-M1
-
 # From examples/values-oxia.yaml and examples/values-functions-fs-storage.yaml.
 components:
   zookeeper: false

.github/workflows/pulsar-helm-chart-ci.yaml

@@ -106,7 +106,7 @@ jobs:
 
       - name: Set up Helm
         if: ${{ steps.check_changes.outputs.docs_only != 'true' }}
-        uses: azure/setup-helm@dda3372f752e03dde6b3237bc9431cdc2f7a02a2
+        uses: azure/setup-helm@9bc31f4ebc9c6b171d7bfbaa5d006ae7abdb4310 # v5.0.1
         with:
           version: v3.16.4
 
@@ -270,7 +270,7 @@ jobs:
             certmanager_version: v1.21.0
         testScenario:
           - name: Upgrade latest released version
-            values_file: .ci/clusters/values-upgrade.yaml
+            values_file: .ci/clusters/values-upgrade.yaml --values .ci/clusters/values-pulsar-previous-lts.yaml
             shortname: upgrade
             type: upgrade
           - name: Use previous LTS Pulsar Image
@@ -327,7 +327,7 @@ jobs:
               kind_image_tag: v1.25.16@sha256:6110314339b3b44d10da7d27881849a87e092124afab5956f2e10ecdb463b025
             testScenario:
               name: "Upgrade TLS"
-              values_file: .ci/clusters/values-tls.yaml
+              values_file: .ci/clusters/values-tls.yaml --values .ci/clusters/values-pulsar-previous-lts.yaml
               shortname: tls
               type: upgrade
           - k8sVersion:
@@ -338,7 +338,7 @@ jobs:
               values_file: .ci/clusters/values-victoria-metrics-grafana.yaml --values .ci/clusters/values-pulsar-previous-lts.yaml
               shortname: victoria-metrics-grafana
               type: upgrade
-              upgradeFromVersion: 3.2.0
+              upgradeFromVersion: 4.6.0
           - k8sVersion:
               version: "1.25.16"
               kind_image_tag: v1.25.16@sha256:6110314339b3b44d10da7d27881849a87e092124afab5956f2e10ecdb463b025

README.md

@@ -364,6 +364,58 @@ kubectl port-forward svc/$(kubectl get svc -l component=dekaf -o jsonpath='{.ite
 
 - Open <http://localhost:8090> in browser.
 
+## Choosing the metadata store: use Oxia for new clusters
+
+Pulsar stores its metadata in a metadata store. This chart can deploy either
+[Apache ZooKeeper](https://zookeeper.apache.org/) or [Oxia](https://github.com/oxia-db/oxia) as the metadata
+store.
+
+**For new production clusters, Oxia is the recommended metadata store.** Use Oxia to get the full feature
+set of the [scalable topics](https://pulsar.apache.org/docs/concepts-scalable-topics/) introduced in Pulsar
+5.0. ZooKeeper remains supported.
+
+The chart currently defaults to ZooKeeper (`components.zookeeper: true`, `components.oxia: false`). The
+default will change to Oxia in a future chart version.
+
+### Deploying a new cluster with Oxia
+
+Choose the metadata store when you first install the cluster. Disable ZooKeeper and enable Oxia in your
+`values.yaml`:
+
+```yaml
+components:
+  zookeeper: false
+  oxia: true
+```
+
+[`examples/values-oxia.yaml`](examples/values-oxia.yaml) contains a ready-made example. The chart deploys
+an Oxia coordinator and an Oxia server StatefulSet with 3 replicas, and configures the brokers and bookies to
+use Oxia. Size Oxia for your workload with the `oxia` values, such as `oxia.server.replicas`,
+`oxia.server.cpuLimit`, `oxia.server.memoryLimit`, `oxia.server.dbCacheSizeMb`, `oxia.server.storageSize`,
+`oxia.initialShardCount` and `oxia.replicationFactor`.
+
+If you run Pulsar Functions on Oxia, you must also enable `FileSystemPackagesStorage`. See
+[Pulsar Functions package storage](#pulsar-functions-package-storage-required-for-oxia).
+
+### Existing ZooKeeper-based installations
+
+Don't switch an existing release from ZooKeeper to Oxia by changing `components.zookeeper` and
+`components.oxia`. The chart doesn't migrate metadata, so the brokers and bookies would start with an empty
+metadata store, and the cluster would lose all its topics, subscriptions and ledger metadata.
+
+Pulsar supports migrating an existing cluster from ZooKeeper to Oxia with a special procedure. See
+[Migrate metadata store from ZooKeeper to Oxia](https://pulsar.apache.org/docs/administration-metadata-store-migration/).
+This Helm chart doesn't support that migration yet.
+
+To keep an existing installation on ZooKeeper when a future chart version changes the default to Oxia, set
+the components explicitly in your `values.yaml` now:
+
+```yaml
+components:
+  zookeeper: true
+  oxia: false
+```
+
 ## Pulsar Functions package storage (required for Oxia)
 
 The Pulsar **Packages Management Service** — which stores uploaded function packages
@@ -477,6 +529,77 @@ For more detailed information, see our [Upgrading](http://pulsar.apache.org/docs
 
 ## Upgrading to Helm chart version 4.8.0
 
+### Default Apache Pulsar version is now 5.0.0
+
+The chart now deploys Apache Pulsar 5.0.0 by default, using the `apachepulsar/pulsar:5.0.0` image. Before
+upgrading, read the [Upgrading to Pulsar 5.0.x](https://pulsar.apache.org/docs/administration-upgrade-to-5.0.x/)
+guide. It recommends first upgrading to the latest Pulsar 4.0.x or 4.2.x release and running it as a stable
+baseline that you can roll back to.
+
+To keep running Pulsar 4.x with this chart version, pin the image tag in your `values.yaml`:
+
+```yaml
+defaultPulsarImageTag: 4.0.14
+```
+
+#### `apachepulsar/pulsar-all` is no longer used
+
+Pulsar 5.0.0 no longer publishes the `apachepulsar/pulsar-all` image, so `defaultPulsarImageRepository` now
+defaults to `apachepulsar/pulsar`. If your `values.yaml` sets `defaultPulsarImageRepository`,
+`images.<component>.repository` or `pulsar_metadata.image.repository` to `apachepulsar/pulsar-all`, change it
+to `apachepulsar/pulsar` or remove the key.
+
+The `apachepulsar/pulsar` 5.0.0 image includes the tiered-storage offloader for AWS S3 (and S3-compatible
+storage), Google Cloud Storage, Azure Blob Storage and Aliyun OSS, so `broker.storageOffload` keeps working.
+The filesystem offloader and the Pulsar IO connector NARs are no longer bundled. If you use them, build a
+custom image that adds the required NAR files.
+
+#### `PULSAR_GC` defaults have been removed
+
+Pulsar 5.0.0 runs on Java 25 with ZGC, and the Pulsar launcher selects the garbage collector options for the
+Java version in the image. The chart no longer sets `PULSAR_GC` in the `configData` of any component.
+`-XX:+AlwaysPreTouch`, `-XX:+UseTransparentHugePages` and `-XX:+ExitOnOutOfMemoryError` were moved to the
+default `PULSAR_MEM` values.
+
+If your `values.yaml` sets `PULSAR_GC` for any component, remove it, and also remove garbage collector
+selection options from `PULSAR_MEM` and `PULSAR_EXTRA_OPTS`. If you override `PULSAR_MEM`, add the flags
+listed above to your value if you want to keep them.
+
+`-XX:+UseTransparentHugePages` only lets the JVM request Transparent Huge Pages (THP). Pulsar benefits from
+them only when the Linux kernel on the Kubernetes nodes that run the Pulsar pods is configured in a specific
+way. Pod settings can't change the node's kernel settings. For example, ZGC keeps its heap in shared memory,
+so the node's `/sys/kernel/mm/transparent_hugepage/shmem_enabled` must allow huge pages (`advise`). With `never`, which is the
+Linux kernel default, the heap doesn't use huge pages even though the flag is set. Configure the nodes as
+described in
+[Configure Linux hosts and Kubernetes nodes](https://pulsar.apache.org/docs/performance-broker/#configure-linux-hosts-and-kubernetes-nodes),
+and make the settings part of the node image or provisioning so that replaced and autoscaled nodes get them
+too.
+
+#### Other Pulsar 5.0 changes to review
+
+- **Metadata store:** Oxia is recommended for new production clusters. Existing installations stay on
+  ZooKeeper. See [Choosing the metadata store](#choosing-the-metadata-store-use-oxia-for-new-clusters).
+- **Package management rollback:** if you set `broker.packageManagement.enabled: true` and may need to roll
+  back to Pulsar 4.x, keep package metadata in the format that 4.x can read. Set these values before the first
+  Pulsar 5.0 broker starts:
+
+  ```yaml
+  broker:
+    configData:
+      PULSAR_PREFIX_packagesManagementJsonSerializationEnabled: "false"
+      PULSAR_PREFIX_packagesManagementAllowLegacyJavaSerialization: "true"
+  ```
+
+- **TLS hostname verification** is now enabled by default for outbound TLS connections from brokers,
+  proxies and Functions workers. The certificates issued by the chart include the service hostnames.
+  If you provide your own certificates, check that they include matching subject alternative names.
+- **BookKeeper metrics provider:** if you set `statsProviderClass` in `bookkeeper.configData`, replace
+  `org.apache.pulsar.metrics.prometheus.bookkeeper.PrometheusMetricsProvider` with
+  `org.apache.bookkeeper.stats.prometheus.PrometheusMetricsProvider`. Otherwise bookies fail to start.
+- Review your `configData` overrides against the
+  [configuration default changes](https://pulsar.apache.org/docs/administration-upgrade-to-5.0.x-configuration/).
+  Some settings have been removed, and explicit values keep their old behavior.
+
 ### Pulsar Manager support has been removed
 
 **Pulsar Manager support has been removed from this Helm chart.** The upstream

charts/pulsar/Chart.yaml

@@ -18,7 +18,7 @@
 #
 
 apiVersion: v2
-appVersion: "4.0.12"
+appVersion: "5.0.0"
 description: Apache Pulsar Helm chart for Kubernetes
 name: pulsar
 version: 4.7.0

charts/pulsar/values.yaml

@@ -150,7 +150,7 @@ components:
   dekaf: false
 
 # default image repository for pulsar images
-defaultPulsarImageRepository: apachepulsar/pulsar-all
+defaultPulsarImageRepository: apachepulsar/pulsar
 
 # default image tag for pulsar images
 # uses chart's appVersion when unspecified
@@ -661,14 +661,11 @@ zookeeper:
   configData:
     PULSAR_MEM: >
       -Xms64m -Xmx128m
-    PULSAR_GC: >
-      -XX:+UseZGC
-      -XX:+ZGenerational
       -XX:+AlwaysPreTouch
       -XX:+UseTransparentHugePages
       -XX:+ExitOnOutOfMemoryError
-      -XX:+DisableExplicitGC
-      -XX:+PerfDisableSharedMem
+    # PULSAR_GC is intentionally unset so that the Pulsar launcher selects the garbage collector options
+    # appropriate for the Java version in the image.
   ## Add a custom command to the start up process of the zookeeper pods (e.g. update-ca-certificates, jvm commands, etc)
   additionalCommand:
   ## Zookeeper service
@@ -990,14 +987,11 @@ bookkeeper:
       -Xms128m
       -Xmx256m
       -XX:MaxDirectMemorySize=256m
-    PULSAR_GC: >
-      -XX:+UseZGC
-      -XX:+ZGenerational
       -XX:+AlwaysPreTouch
       -XX:+UseTransparentHugePages
       -XX:+ExitOnOutOfMemoryError
-      -XX:+DisableExplicitGC
-      -XX:+PerfDisableSharedMem
+    # PULSAR_GC is intentionally unset so that the Pulsar launcher selects the garbage collector options
+    # appropriate for the Java version in the image.
     #
     # Bookkeeper configuration reference: https://bookkeeper.apache.org/docs/reference/config
     #
@@ -1284,9 +1278,8 @@ standalone:
   configData:
     PULSAR_MEM: >
       -Xms256m -Xmx512m -XX:MaxDirectMemorySize=512m
-    PULSAR_GC: >
-      -XX:+UseG1GC
-      -XX:MaxGCPauseMillis=10
+    # PULSAR_GC is intentionally unset so that the Pulsar launcher selects the garbage collector options
+    # appropriate for the Java version in the image.
 
 ## Pulsar: Broker cluster
 ## templates/broker-statefulset.yaml
@@ -1413,14 +1406,11 @@ broker:
   configData:
     PULSAR_MEM: >
       -Xms128m -Xmx256m -XX:MaxDirectMemorySize=256m
-    PULSAR_GC: >
-      -XX:+UseZGC
-      -XX:+ZGenerational
       -XX:+AlwaysPreTouch
       -XX:+UseTransparentHugePages
       -XX:+ExitOnOutOfMemoryError
-      -XX:+DisableExplicitGC
-      -XX:+PerfDisableSharedMem
+    # PULSAR_GC is intentionally unset so that the Pulsar launcher selects the garbage collector options
+    # appropriate for the Java version in the image.
     managedLedgerDefaultEnsembleSize: "2"
     managedLedgerDefaultWriteQuorum: "2"
     managedLedgerDefaultAckQuorum: "2"
@@ -1732,8 +1722,8 @@ function_worker:
   configData:
     PULSAR_MEM: >
       -Xms128m -Xmx256m -XX:MaxDirectMemorySize=256m
-    PULSAR_GC: >
-      -XX:+UseG1GC
+    # PULSAR_GC is intentionally unset so that the Pulsar launcher selects the garbage collector options
+    # appropriate for the Java version in the image.
 
 ## Pulsar: Proxy Cluster
 ## templates/proxy-statefulset.yaml
@@ -1847,14 +1837,11 @@ proxy:
   configData:
     PULSAR_MEM: >
       -Xms64m -Xmx128m -XX:MaxDirectMemorySize=128m
-    PULSAR_GC: >
-      -XX:+UseZGC
-      -XX:+ZGenerational
       -XX:+AlwaysPreTouch
       -XX:+UseTransparentHugePages
       -XX:+ExitOnOutOfMemoryError
-      -XX:+DisableExplicitGC
-      -XX:+PerfDisableSharedMem
+    # PULSAR_GC is intentionally unset so that the Pulsar launcher selects the garbage collector options
+    # appropriate for the Java version in the image.
     httpNumThreads: "8"
   ## Add a custom command to the start up process of the proxy pods (e.g. update-ca-certificates, jvm commands, etc)
   additionalCommand:

scripts/pulsar/common_auth.sh

@@ -24,7 +24,7 @@ if [ -z "$PULSAR_VERSION" ]; then
         PULSAR_VERSION=$(yq .appVersion charts/pulsar/Chart.yaml)
     else
         # use a default version if yq is not installed
-        PULSAR_VERSION="4.0.3"
+        PULSAR_VERSION="5.0.0"
     fi
 fi
 # shellcheck disable=SC2034