diff --git a/client-libraries/java-dependency-configuration.md b/client-libraries/java-dependency-configuration.md new file mode 100644 index 000000000000..de150a5b22f4 --- /dev/null +++ b/client-libraries/java-dependency-configuration.md @@ -0,0 +1,345 @@ +--- +id: java-dependency-configuration +title: Java dependency configuration +sidebar_label: "Dependency configuration" +description: Copy complete Maven and Gradle configurations for the Pulsar Java client, align dependencies with BOMs, and avoid conflicting client libraries. +--- + +:::tip One dependency for v4, v5, and admin clients + +**`pulsar-client-v5-all`** provides the v4 client, v5 client, and Pulsar admin client through one unshaded dependency, with its libraries resolved transitively. Migrating applications can use this same dependency while keeping the v4 API; using v5 is optional, and separate client dependencies are unnecessary. + +::: + +The clients require **JDK 17 or newer**. **Choose Java 25 LTS for running new applications when you have the choice.** The examples below target Java 17 bytecode and configure both BOMs and checks or exclusions for conflicting client libraries. Use JDK 25 to run Maven; the Gradle example selects a Java 25 toolchain. + +The version values below use the latest published Pulsar 5-or-later client release and the Netty version used by the current Pulsar documentation. Set the Pulsar version to your chosen release. When updating versions or adding dependencies, [verify the resolved runtime graph](#verify-netty-alignment). + +## Complete Maven example {#maven} + +Copy this into `pom.xml` for a new project. For an existing project, merge the properties, dependency management, dependency, and plugin configuration into your existing POM. + +```xml title="pom.xml" + + 4.0.0 + com.example + pulsar-client-example + 1.0-SNAPSHOT + + + 17 + UTF-8 + @pulsar:version:latest-v5plus@ + + @pulsar:version:netty@ + + + + + + io.netty + netty-bom + ${netty.version} + pom + import + + + org.apache.pulsar + pulsar-bom + ${pulsar.version} + pom + import + + + + + + + org.apache.pulsar + pulsar-client-v5-all + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.16.0 + + + org.apache.maven.plugins + maven-enforcer-plugin + 3.6.3 + + + reject-conflicting-pulsar-clients + + enforce + + + + + + org.apache.pulsar:pulsar-client + org.apache.pulsar:pulsar-client-admin + org.apache.pulsar:pulsar-client-all + org.apache.pulsar:pulsar-client-v5-shaded + + true + Remove conflicting Pulsar clients or exclude them from the dependencies that introduce them. + + + + + + + + + +``` + +Run `mvn verify` to build and check the dependencies. The [Maven Enforcer rule](https://maven.apache.org/enforcer/enforcer-rules/bannedDependencies.html) fails the build if a conflicting client is present, including through transitive dependencies. It does not remove dependencies: use the [exclusions below](#replace-existing-dependencies) on each dependency that introduces a banned artifact. + +## Complete Gradle example {#gradle} + +Create these three files in the project root. For an existing project, merge them into your current configuration. Use your project's Gradle Wrapper to run the build. + +```kotlin title="settings.gradle.kts" +rootProject.name = "pulsar-client-example" +``` + +```properties title="gradle.properties" +pulsarVersion=@pulsar:version:latest-v5plus@ +# Match the Netty version used by this Pulsar release, or use a newer compatible version. +# See https://github.com/apache/pulsar/blob/v@pulsar:version:latest-v5plus@/gradle/libs.versions.toml +nettyVersion=@pulsar:version:netty@ +``` + +```kotlin title="build.gradle.kts" +plugins { + java +} + +repositories { + mavenCentral() +} + +java { + toolchain { + languageVersion = JavaLanguageVersion.of(25) + } +} + +tasks.withType().configureEach { + options.release = 17 +} + +val pulsarVersion = providers.gradleProperty("pulsarVersion").get() +val nettyVersion = providers.gradleProperty("nettyVersion").get() + +configurations.configureEach { + exclude(group = "org.apache.pulsar", module = "pulsar-client") + exclude(group = "org.apache.pulsar", module = "pulsar-client-admin") + exclude(group = "org.apache.pulsar", module = "pulsar-client-all") + exclude(group = "org.apache.pulsar", module = "pulsar-client-v5-shaded") +} + +dependencies { + implementation(platform("org.apache.pulsar:pulsar-bom:$pulsarVersion")) + implementation(platform("io.netty:netty-bom:$nettyVersion")) + implementation("org.apache.pulsar:pulsar-client-v5-all") +} +``` + +Run `./gradlew build` to build the project. If you are starting a new project without a wrapper, generate one with `gradle wrapper` using your installed Gradle distribution. The exclusions apply to this project's configurations; check the runtime graph of the final application, especially when publishing a library for other applications to consume. + +### Internal libraries: separate API and implementation {#gradle-library-dependencies} + +Gradle's `java-library` plugin provides separate **`api` and `implementation`** configurations. Use `api` only for dependencies whose types appear in your library's public API, such as method parameters or return types. Use `implementation` for internal dependencies. See [Gradle's API and implementation separation](https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separation). + +**Do not add the Pulsar client implementation to an internal library's `api` configuration.** If your library exposes Pulsar types, expose the corresponding public API artifact: `pulsar-client-api` for v4, or `pulsar-client-api-v5` for v5. Add only the API artifacts your public signatures use. + +For a library exposing both v4 and v5 types, replace the complete Gradle example's plugin and dependency declarations with the following. Keep its repositories, Java toolchain, values in `gradle.properties`, and conflict exclusions: + +```kotlin +plugins { + `java-library` +} + +val pulsarVersion = providers.gradleProperty("pulsarVersion").get() +val nettyVersion = providers.gradleProperty("nettyVersion").get() + +dependencies { + api(platform("org.apache.pulsar:pulsar-bom:$pulsarVersion")) + api("org.apache.pulsar:pulsar-client-api") + api("org.apache.pulsar:pulsar-client-api-v5") + + implementation(platform("io.netty:netty-bom:$nettyVersion")) + implementation("org.apache.pulsar:pulsar-client-v5-all") +} +``` + +The API dependencies are available on consumers' compile classpaths. The client implementation remains a runtime dependency of consumers, so the application's BOM alignment and conflict exclusions still matter. If your library exposes no Pulsar types, declare its Pulsar dependencies with `implementation` instead. + +## How the configuration works + +- **Version properties** select the client release and compatible Netty version. They do not select the v4 or v5 API. +- **Both BOMs** manage dependency versions. They do not add the client or remove conflicting implementations. +- **`pulsar-client-v5-all`** brings in the unshaded v4 client, v5 client, and admin implementations. +- **Conflict handling** keeps separately shaded clients off the classpath. Gradle excludes them; Maven detects them and requires exclusions on the dependencies that introduce them. + +## Pulsar and Netty BOMs {#pulsar-bom} + +Import `pulsar-bom` to align Pulsar artifacts and `io.netty:netty-bom` to align Netty modules. A BOM manages versions; it does not replace artifacts or remove duplicate implementations. + +Set the Netty version to the version used by your chosen Pulsar release or a newer compatible version. Check the `netty` entry in [Pulsar's version catalog](https://github.com/apache/pulsar/blob/v@pulsar:version:latest-v5plus@/gradle/libs.versions.toml). If you choose a different Pulsar version, update the version tag in the URL accordingly. + +The recommended unshaded client uses **Netty 4.2.x**, currently **@pulsar:version:netty@**. Applications using Netty 4.1.x should upgrade their Netty dependencies to 4.2.x together. Netty 4.2 is largely backward compatible with 4.1, but the two lines cannot coexist on the same classpath. Review the [Netty migration guide](https://netty.io/wiki/netty-4.2-migration-guide.html), particularly TLS hostname verification, allocator defaults, and libraries that use Netty internally. + +### Maven {#pulsar-bom-maven} + +The [complete Maven example](#maven) imports the Netty BOM before the Pulsar BOM. Remove older explicit Netty versions and reconcile dependency management inherited from frameworks or parent POMs. When imported BOMs manage the same artifact, Maven gives precedence to the first import; direct dependency-management entries take precedence over imports. See [Maven dependency management](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#dependency-management). + +### Gradle {#pulsar-bom-gradle} + +The [complete Gradle example](#gradle) uses `platform` to import both BOMs. This allows normal dependency conflict resolution; inspect the resolved graph to confirm that Pulsar and Netty versions remain aligned. Avoid `enforcedPlatform` as a general default, especially for published libraries, because its enforced versions propagate to consumers. See [Gradle platform guidance](https://docs.gradle.org/current/userguide/platforms.html#sec:enforced-platform). + +### Verify Netty alignment + +Inspect the resolved runtime graph after applying the BOMs: + +```shell +mvn dependency:tree -Dscope=runtime '-Dincludes=io.netty:*' +./gradlew dependencyInsight --dependency io.netty --configuration runtimeClasspath +``` + +Ensure the resolved Netty core modules use one consistent 4.2.x version and that the packaged application contains no leftover 4.1.x or duplicate Netty JARs. Requested versions shown as replaced in a dependency report are not additional runtime copies. Netty components with independent version schemes, such as `netty-tcnative`, should use the versions managed by the Netty BOM rather than being assigned the core version manually. + +## Replace existing dependencies {#replace-existing-dependencies} + +When adopting a combined dependency, replace separately declared `pulsar-client`, `pulsar-client-admin`, and the older `pulsar-client-all` aggregate. `pulsar-client-admin` is the Java artifact; `pulsar-admin` is the CLI name. Exclude older artifacts from dependencies that introduce them transitively. Keeping the separately shaded client/admin JARs alongside the combined dependency duplicates implementations and bundled libraries on the classpath. For the shaded fallback, also remove separately declared unshaded implementations. + +For the unshaded `pulsar-client-v5-all` setup, also exclude and ban `pulsar-client-v5-shaded`. The complete examples above include this rule. For the shaded setup, use the [opposite exclusions and bans below](#shaded-fallback). + +For Gradle, apply exclusions to application configurations: + +```kotlin +configurations.configureEach { + exclude(group = "org.apache.pulsar", module = "pulsar-client") + exclude(group = "org.apache.pulsar", module = "pulsar-client-admin") + exclude(group = "org.apache.pulsar", module = "pulsar-client-all") + exclude(group = "org.apache.pulsar", module = "pulsar-client-v5-shaded") +} +``` + +In Maven, add exclusions to **each dependency** that introduces those artifacts. Maven exclusions apply to that dependency's subtree, not globally: + +```xml + + + org.apache.pulsar + pulsar-client + + + org.apache.pulsar + pulsar-client-admin + + + org.apache.pulsar + pulsar-client-all + + + org.apache.pulsar + pulsar-client-v5-shaded + + +``` + +Inspect the resolved runtime dependency graph: + +```shell +mvn dependency:tree -Dscope=runtime '-Dincludes=org.apache.pulsar:*' +./gradlew dependencies --configuration runtimeClasspath +``` + +Verify that the replaced artifacts are gone and Pulsar versions agree. The unshaded aggregate resolves implementation modules such as `pulsar-client-v5`, `pulsar-client-original`, and `pulsar-client-admin-original`. The shaded fallback instead exposes the external APIs and intentionally non-bundled libraries through its dependency-reduced publication. Code that directly imports relocated implementation or third-party classes must move to public APIs or use the unshaded aggregate. + +## Shaded fallback + +If you need the shaded fallback due to classpath conflicts in your application dependency graph, use `pulsar-client-v5-shaded` as an ordinary dependency, without a classifier, variant attributes, or implementation exclusions on this dependency. Despite its name, it includes the v4 client and admin implementation too. + +**The Pulsar BOM and dependency exclusions still apply when using the shaded fallback.** Keep importing `pulsar-bom` to align the external Pulsar API dependencies, and keep excluding the older `pulsar-client`, `pulsar-client-admin`, and `pulsar-client-all` artifacts from dependencies that introduce them transitively. + +When adapting either complete example, replace `pulsar-client-v5-all` with `pulsar-client-v5-shaded`. Reverse the conflict rules: allow `pulsar-client-v5-shaded`, and exclude and ban `pulsar-client-v5-all` and its unshaded implementation modules (`pulsar-client-v5`, `pulsar-client-original`, and `pulsar-client-admin-original`). Retain the exclusions and bans for the older client artifacts. Do not exclude the external API modules required by the shaded client. + +```xml + + org.apache.pulsar + pulsar-client-v5-shaded + ${pulsar.version} + +``` + +```kotlin +val pulsarVersion = providers.gradleProperty("pulsarVersion").get() + +dependencies { + implementation("org.apache.pulsar:pulsar-client-v5-shaded:$pulsarVersion") +} +``` + +For Maven, replace the complete example's `bannedDependencies` rule with: + +```xml + + + org.apache.pulsar:pulsar-client + org.apache.pulsar:pulsar-client-admin + org.apache.pulsar:pulsar-client-all + org.apache.pulsar:pulsar-client-v5-all + org.apache.pulsar:pulsar-client-v5 + org.apache.pulsar:pulsar-client-original + org.apache.pulsar:pulsar-client-admin-original + + true + Remove conflicting Pulsar clients or exclude them from the dependencies that introduce them. + +``` + +Apply Maven dependency exclusions for these same artifacts to each dependency that introduces them, using the [exclusion syntax above](#replace-existing-dependencies). The Enforcer rule detects conflicts; it does not exclude dependencies automatically. + +For Gradle, replace the complete example's `configurations.configureEach` block with: + +```kotlin +configurations.configureEach { + exclude(group = "org.apache.pulsar", module = "pulsar-client") + exclude(group = "org.apache.pulsar", module = "pulsar-client-admin") + exclude(group = "org.apache.pulsar", module = "pulsar-client-all") + exclude(group = "org.apache.pulsar", module = "pulsar-client-v5-all") + exclude(group = "org.apache.pulsar", module = "pulsar-client-v5") + exclude(group = "org.apache.pulsar", module = "pulsar-client-original") + exclude(group = "org.apache.pulsar", module = "pulsar-client-admin-original") +} +``` + +The shaded artifact has its own dependency-reduced POM. A Maven classifier shares the original artifact's POM and dependency graph: selecting a shaded classifier on an unshaded aggregate would still pull in its unshaded implementations. No `shaded` classifier is published for `pulsar-client-v5-all`. + +The shaded artifact keeps `pulsar-client-api`, `pulsar-client-api-v5`, `pulsar-client-admin-api`, `pulsar-tls-factory-api`, and `pulsar-http-client-api` as unshaded external dependencies. Logging, Bouncy Castle, and other intentionally non-bundled libraries also remain external. Resolve the published metadata with Maven or Gradle instead of copying only the client JAR. For provider replacement and packaging requirements, see [Bouncy Castle providers](pathname:///docs/next/security-bouncy-castle). + +Applications using protobuf schemas must also provide `com.google.protobuf:protobuf-java`. The client artifacts neither bundle it nor declare it transitively. Align generated Protobuf classes and dependency overrides with the resolved runtime. Applications using reflective Avro schemas should also review [Java Avro class trust](pathname:///docs/next/schema-get-started#java-avro-class-trust). + +## Spring Boot + +When a framework supplies Pulsar dependencies, align its managed Pulsar and Netty versions with the [BOMs above](#pulsar-bom), apply the [transitive exclusions](#replace-existing-dependencies), and inspect the resulting runtime graph. Adding a combined dependency alone does not remove the framework's existing client dependency. + +### Spring Boot using Maven {#spring-boot-maven} + +Set Spring Boot's `pulsar.version` Maven property to the same target client version used above. Set `netty.version` to `@pulsar:version:netty@` as well. Add the combined dependency and exclude the replaced artifacts from dependencies that introduce them, such as the Pulsar starter. See [Spring Boot's Pulsar support](https://docs.spring.io/spring-boot/reference/messaging/pulsar.html) for its dependency management. + +### Spring Boot using Gradle {#spring-boot-gradle} + +When using the Spring Dependency Management plugin (`io.spring.dependency-management`), set its `pulsar.version` property to the same `pulsarVersion`, for example `extra["pulsar.version"] = pulsarVersion`. Also set `extra["netty.version"] = "@pulsar:version:netty@"` to align Spring's managed Netty dependencies. Apply the combined dependency and exclusions above. See [Spring Boot's dependency version properties](https://docs.spring.io/spring-boot/appendix/dependency-versions/properties.html) for managed versions. diff --git a/client-libraries/java-migrate-to-v5.md b/client-libraries/java-migrate-to-v5.md index 334fdb31f8dc..8b1f65e28927 100644 --- a/client-libraries/java-migrate-to-v5.md +++ b/client-libraries/java-migrate-to-v5.md @@ -27,11 +27,11 @@ The two APIs can run **side by side in the same JVM**, so you can move one produ - **Java 17 or later.** The combined Java client artifacts require this runtime for both APIs. - **Pulsar 5.x brokers with scalable topics enabled.** The v5 client requires the scalable-topic protocol even when accessing existing `persistent://` topics. It cannot connect through this API to older brokers or brokers with `scalableTopicsEnabled=false`. These v5 connection requirements do not apply merely because a v4 application uses a combined dependency. -- **Aligned dependencies.** Complete the [dependency setup and runtime graph checks](java-setup.md#pulsar-bom) before migrating API usage. +- **Aligned dependencies.** Complete the [dependency setup and runtime graph checks](java-dependency-configuration.md#pulsar-bom) before migrating API usage. ## Dependencies -Follow [Java client setup](java-setup.md) for Maven and Gradle declarations, [Pulsar and Netty BOMs](java-setup.md#pulsar-bom), and [transitive exclusions](java-setup.md#replace-existing-dependencies). It is the canonical dependency guide, including runtime graph checks and the shaded fallback for unresolved conflicts. +Follow [Java client setup](java-setup.md) for Maven and Gradle declarations, [Pulsar and Netty BOMs](java-dependency-configuration.md#pulsar-bom), and [transitive exclusions](java-dependency-configuration.md#replace-existing-dependencies). The dependency configuration page is the canonical dependency guide, including runtime graph checks and the shaded fallback for unresolved conflicts. Changing dependencies does not require changing v4 application code. Continue with the API migration below when you are ready to adopt v5. diff --git a/client-libraries/java-setup.md b/client-libraries/java-setup.md index 2f38185204f7..4c912dbe6f78 100644 --- a/client-libraries/java-setup.md +++ b/client-libraries/java-setup.md @@ -5,7 +5,7 @@ sidebar_label: "Set up" description: Learn how to set up Java client library in Pulsar. --- -Use the combined Java dependency for applications using the v4 client, v5 client, the admin API, or any combination of them. The combined artifacts require **Java 17 or later**. +Use the combined Java dependency for applications using the v4 client, v5 client, the admin API, or any combination of them. The combined artifacts require **Java 17 or later**. **Choose Java 25 LTS for running new applications when you have the choice.** Changing dependencies and changing client APIs are separate choices. Both combined artifacts support the existing v4 API (`org.apache.pulsar.client.api`), the v5 API (`org.apache.pulsar.client.api.v5`), and the admin API. You can update the dependency while keeping your v4 application code. Existing v4 applications using regular topics do not need to change their API or dependencies for a broker upgrade. Use this setup when configuring or updating application dependencies. @@ -18,181 +18,23 @@ Use **`pulsar-client-v5-all`** by default for new dependency configurations. It | `pulsar-client-v5-all` | Unshaded v4 client, v5 client, and admin implementations, with their transitive dependencies | | `pulsar-client-v5-shaded` | One JAR containing relocated v4 client, v5 client, and admin implementations and bundled third-party dependencies | -Set `pulsar.version` in Maven or `pulsarVersion` in Gradle to your target client release from Pulsar 5 or later that publishes the chosen combined artifact. Use the same version for all Pulsar dependencies. These variables identify the dependency version; they do not select the v4 or v5 API. +:::info Strongly recommended: align dependencies and exclude conflicting clients -### Maven +To avoid classpath conflicts and incompatible libraries: -Add the following dependency to your `pom.xml`. The `${pulsar.version}` value comes from your Maven properties. +- **Import both the [Pulsar and Netty BOMs](java-dependency-configuration.md#pulsar-bom)** to align dependency versions. +- **[Remove and exclude conflicting clients](java-dependency-configuration.md#replace-existing-dependencies).** BOMs do not remove duplicate implementations. Never combine `pulsar-client-v5-all` with `pulsar-client-v5-shaded`. +- **[Verify the runtime dependency graph](java-dependency-configuration.md#verify-netty-alignment)**, including dependencies supplied by frameworks. -```xml - - org.apache.pulsar - pulsar-client-v5-all - ${pulsar.version} - -``` - -### Gradle - -In Gradle Kotlin DSL, define the `pulsarVersion` project property and use it in `build.gradle.kts`: - -```kotlin -val pulsarVersion: String by project - -dependencies { - implementation("org.apache.pulsar:pulsar-client-v5-all:$pulsarVersion") -} -``` - -### Shaded fallback - -If you need the shaded fallback, use `pulsar-client-v5-shaded` as an ordinary dependency, without a classifier, variant attributes, or implementation exclusions on this dependency. Despite its name, it includes the v4 client and admin implementation too. - -```xml - - org.apache.pulsar - pulsar-client-v5-shaded - ${pulsar.version} - -``` - -```kotlin -val pulsarVersion: String by project - -dependencies { - implementation("org.apache.pulsar:pulsar-client-v5-shaded:$pulsarVersion") -} -``` - -The shaded artifact has its own dependency-reduced POM. A Maven classifier shares the original artifact's POM and dependency graph: selecting a shaded classifier on an unshaded aggregate would still pull in its unshaded implementations. No `shaded` classifier is published for `pulsar-client-v5-all`. - -The shaded artifact keeps `pulsar-client-api`, `pulsar-client-api-v5`, `pulsar-client-admin-api`, `pulsar-tls-factory-api`, and `pulsar-http-client-api` as unshaded external dependencies. Logging, Bouncy Castle, and other intentionally non-bundled libraries also remain external. Resolve the published metadata with Maven or Gradle instead of copying only the client JAR. For provider replacement and packaging requirements, see [Bouncy Castle providers](pathname:///docs/next/security-bouncy-castle). - -Applications using protobuf schemas must also provide `com.google.protobuf:protobuf-java`. The client artifacts neither bundle it nor declare it transitively. Align generated Protobuf classes and dependency overrides with the resolved runtime. Applications using reflective Avro schemas should also review [Java Avro class trust](pathname:///docs/next/schema-get-started#java-avro-class-trust). - -### Replace existing dependencies {#replace-existing-dependencies} - -When adopting a combined dependency, replace separately declared `pulsar-client`, `pulsar-client-admin`, and the older `pulsar-client-all` aggregate. `pulsar-client-admin` is the Java artifact; `pulsar-admin` is the CLI name. Exclude older artifacts from dependencies that introduce them transitively. Keeping the separately shaded client/admin JARs alongside the combined dependency duplicates implementations and bundled libraries on the classpath. For the shaded fallback, also remove separately declared unshaded implementations. - -For Gradle, apply exclusions to application configurations: - -```kotlin -configurations.configureEach { - exclude(group = "org.apache.pulsar", module = "pulsar-client") - exclude(group = "org.apache.pulsar", module = "pulsar-client-admin") - exclude(group = "org.apache.pulsar", module = "pulsar-client-all") -} -``` - -In Maven, add exclusions to **each dependency** that introduces those artifacts. Maven exclusions apply to that dependency's subtree, not globally: - -```xml - - - org.apache.pulsar - pulsar-client - - - org.apache.pulsar - pulsar-client-admin - - - org.apache.pulsar - pulsar-client-all - - -``` - -Inspect the resolved runtime dependency graph: - -```shell -mvn dependency:tree -Dscope=runtime '-Dincludes=org.apache.pulsar:*' -./gradlew dependencies --configuration runtimeClasspath -``` - -Verify that the replaced artifacts are gone and Pulsar versions agree. The unshaded aggregate resolves implementation modules such as `pulsar-client-v5`, `pulsar-client-original`, and `pulsar-client-admin-original`. The shaded fallback instead exposes the external APIs and intentionally non-bundled libraries through its dependency-reduced publication. Code that directly imports relocated implementation or third-party classes must move to public APIs or use the unshaded aggregate. - -### Pulsar and Netty BOMs {#pulsar-bom} - -Import `pulsar-bom` to align Pulsar artifacts and `io.netty:netty-bom` to align Netty modules. A BOM manages versions; it does not replace artifacts or remove duplicate implementations. - -The recommended unshaded client uses **Netty 4.2.x**, currently **@pulsar:version:netty@**. Applications using Netty 4.1.x should upgrade their Netty dependencies to 4.2.x together. Netty 4.2 is largely backward compatible with 4.1, but the two lines cannot coexist on the same classpath. Review the [Netty migration guide](https://netty.io/wiki/netty-4.2-migration-guide.html), particularly TLS hostname verification, allocator defaults, and libraries that use Netty internally. - -#### Maven {#pulsar-bom-maven} - -Add the Netty version property and import both BOMs in `pom.xml`, using your existing `pulsar.version` property: - -```xml - - @pulsar:version:netty@ - - - - - - io.netty - netty-bom - ${netty.version} - pom - import - - - org.apache.pulsar - pulsar-bom - ${pulsar.version} - pom - import - - - - - - - org.apache.pulsar - pulsar-client-v5-all - - -``` - -Remove older explicit Netty versions and reconcile dependency management inherited from frameworks or parent POMs. When imported BOMs manage the same artifact, Maven gives precedence to the first import; direct dependency-management entries take precedence over imports. - -#### Gradle {#pulsar-bom-gradle} - -Use `platform` to import the BOMs. It allows normal dependency conflict resolution; inspect the resolved graph to confirm that Pulsar and Netty versions remain aligned. Avoid `enforcedPlatform` as a general default, especially for published libraries, because its enforced versions propagate to consumers. See [Gradle platform guidance](https://docs.gradle.org/current/userguide/platforms.html#sec:enforced-platform). - -```kotlin -val pulsarVersion: String by project -val nettyVersion = "@pulsar:version:netty@" - -dependencies { - implementation(platform("org.apache.pulsar:pulsar-bom:$pulsarVersion")) - implementation(platform("io.netty:netty-bom:$nettyVersion")) - implementation("org.apache.pulsar:pulsar-client-v5-all") -} -``` - -#### Verify Netty alignment - -Inspect the resolved runtime graph after applying the BOMs: - -```shell -mvn dependency:tree -Dscope=runtime '-Dincludes=io.netty:*' -./gradlew dependencyInsight --dependency io.netty --configuration runtimeClasspath -``` - -Ensure the resolved Netty core modules use one consistent 4.2.x version and that the packaged application contains no leftover 4.1.x or duplicate Netty JARs. Requested versions shown as replaced in a dependency report are not additional runtime copies. Netty components with independent version schemes, such as `netty-tcnative`, should use the versions managed by the Netty BOM rather than being assigned the core version manually. - -### Spring Boot - -When a framework supplies Pulsar dependencies, align its managed Pulsar and Netty versions with the [BOMs above](#pulsar-bom), apply the [transitive exclusions](#replace-existing-dependencies), and inspect the resulting runtime graph. Adding a combined dependency alone does not remove the framework's existing client dependency. - -#### Spring Boot using Maven {#spring-boot-maven} +::: -Set Spring Boot's `pulsar.version` Maven property to the same target client version used above. Set `netty.version` to `@pulsar:version:netty@` as well. Add the combined dependency and exclude the replaced artifacts from dependencies that introduce them, such as the Pulsar starter. See [Spring Boot's Pulsar support](https://docs.spring.io/spring-boot/reference/messaging/pulsar.html) for its dependency management. +### Complete dependency configuration {#pulsar-bom} -#### Spring Boot using Gradle {#spring-boot-gradle} +For copyable build files with both BOMs and conflict handling, see [Java dependency configuration](java-dependency-configuration.md): -When using the Spring Dependency Management plugin (`io.spring.dependency-management`), set its `pulsar.version` property to the same `pulsarVersion`, for example `extra["pulsar.version"] = pulsarVersion`. Also set `extra["netty.version"] = "@pulsar:version:netty@"` to align Spring's managed Netty dependencies. Apply the combined dependency and exclusions above. See [Spring Boot's dependency version properties](https://docs.spring.io/spring-boot/appendix/dependency-versions/properties.html) for managed versions. +- [Complete Maven example](java-dependency-configuration.md#maven) +- [Complete Gradle example](java-dependency-configuration.md#gradle) +- [Replace existing dependencies](java-dependency-configuration.md#replace-existing-dependencies), [shaded fallback](java-dependency-configuration.md#shaded-fallback), and [Spring Boot](java-dependency-configuration.md#spring-boot) ## Step 2: Connect to Pulsar cluster diff --git a/client-libraries/java-v5.md b/client-libraries/java-v5.md index b9d8f22ec25b..029d7a6c267a 100644 --- a/client-libraries/java-v5.md +++ b/client-libraries/java-v5.md @@ -17,7 +17,7 @@ The v5 client requires **Java 17** and Pulsar 5.x brokers with `scalableTopicsEn ## Install -Use **`pulsar-client-v5-all`** and follow [Java client setup](java-setup.md#step-1-install-java-client-library) for the Maven and Gradle dependency examples, [Pulsar and Netty BOMs](java-setup.md#pulsar-bom), and transitive dependency exclusions. The setup page also covers external dependencies and the shaded fallback for unresolved dependency conflicts. +Use **`pulsar-client-v5-all`** and follow [Java client setup](java-setup.md#step-1-install-java-client-library) for the Maven and Gradle dependency examples, [Pulsar and Netty BOMs](java-dependency-configuration.md#pulsar-bom), and transitive dependency exclusions. The dependency configuration page also covers external dependencies and the shaded fallback for unresolved dependency conflicts. The v5 API lives under [`org.apache.pulsar.client.api.v5`](@pulsar:javadoc:client-v5@/org/apache/pulsar/client/api/v5/package-summary.html). Choosing a combined dependency does not switch an application from v4 to v5; changing the API is a separate [source migration](java-migrate-to-v5.md). diff --git a/docs/about.md b/docs/about.md index 276bb3be83a9..1b39f43f101e 100644 --- a/docs/about.md +++ b/docs/about.md @@ -15,7 +15,11 @@ import { docUrl } from "@site/src/utils/index"; This portal holds a variety of topics, tutorials, guides, and reference material to help you work with Pulsar. -Preparing to upgrade? Start with the [release highlights](release-highlights.md) and the [cluster upgrade guide](administration-upgrade.md). +:::tip Preparing to upgrade to Pulsar @pulsar:version:major@? + +Start with the [release highlights](release-highlights.md) and the [cluster upgrade guide](administration-upgrade.md). + +::: ## Choose your path Select one of the content blocks below to begin your Pulsar journey. If you ... @@ -59,4 +63,4 @@ The Pulsar community on GitHub is active, passionate, and knowledgeable. Join d * Please go to [the community page](pathname:///community/#section-discussions) to find the contact information for joining various communication channels. * The main communication channel for the Apache Pulsar project are [the mailing lists](pathname:///contact/). -* There's a separate page for Apache Pulsar [Security advisories and Security policy](pathname:///security/). \ No newline at end of file +* There's a separate page for Apache Pulsar [Security advisories and Security policy](pathname:///security/). diff --git a/docs/administration-upgrade-to-5.0.x-applications.md b/docs/administration-upgrade-to-5.0.x-applications.md index 1f6d16b3e268..4da5f03a1748 100644 --- a/docs/administration-upgrade-to-5.0.x-applications.md +++ b/docs/administration-upgrade-to-5.0.x-applications.md @@ -23,7 +23,7 @@ Dependency migration is separate from v5 API adoption. An application using eith When adopting the unshaded `pulsar-client-v5-all` dependency, upgrade application dependencies from Netty 4.1.x to **Netty 4.2.x**. Pulsar uses **@pulsar:version:netty@**. Netty 4.2 is largely backward compatible with 4.1, but both lines cannot coexist on the same classpath. This dependency alignment is part of updating the application; it is not required merely to upgrade brokers while retaining an existing v4 client dependency. -Import `io.netty:netty-bom` alongside `pulsar-bom`, update framework-managed Netty versions, and verify that the resolved runtime graph and packaged application contain a consistent set of Netty modules without old or duplicate JARs. See the [Maven and Gradle setup examples](pathname:///docs/client-libraries/java-setup#pulsar-bom) and the [Netty migration guide](https://netty.io/wiki/netty-4.2-migration-guide.html). +Import `io.netty:netty-bom` alongside `pulsar-bom`, update framework-managed Netty versions, and verify that the resolved runtime graph and packaged application contain a consistent set of Netty modules without old or duplicate JARs. See the [Maven and Gradle setup examples](pathname:///docs/client-libraries/java-dependency-configuration#pulsar-bom) and the [Netty migration guide](https://netty.io/wiki/netty-4.2-migration-guide.html). ## Check schema dependencies diff --git a/docs/functions-package-python.md b/docs/functions-package-python.md index 8653b73e2650..4696c1966b34 100644 --- a/docs/functions-package-python.md +++ b/docs/functions-package-python.md @@ -40,11 +40,7 @@ To package a Python function into **one Python file**, complete the following st pip install 'pulsar-client==@pulsar:version:python@' ``` - And install protobuf tools to generate the proto files: - - ```bash - pip install 'protobuf==3.20.*' - ``` + This example does not require generating Protocol Buffers files or installing `protobuf` separately. The Pulsar Docker image already includes the Python function runtime's dependencies. 3. Copy the Python function file to the Pulsar image. diff --git a/docs/functions-runtime-kubernetes.md b/docs/functions-runtime-kubernetes.md index bcbf21a68cbe..17bbda4794fb 100644 --- a/docs/functions-runtime-kubernetes.md +++ b/docs/functions-runtime-kubernetes.md @@ -5,6 +5,15 @@ sidebar_label: "Configure Kubernetes runtime" description: Configure Kubernetes runtime for functions in Pulsar. --- +:::warning Run only fully trusted code + +Pulsar Functions and connectors execute user-provided code by design. This intended capability is not itself a remote code execution (RCE) vulnerability. **Run only code that you fully trust**, because it can modify its execution environment: + +- **Thread and process runtimes** can read or modify any files and state accessible to the process they run in. +- **The Kubernetes runtime** does not, on its own, restrict access to Kubernetes cluster resources. Pulsar provides hooks for custom hardening, but the hardening itself is outside the project. + +::: + The Kubernetes runtime works when a function worker generates and applies Kubernetes manifests. The manifests generated by a function worker include: * a `StatefulSet` By default, the `StatefulSet` manifest has a single pod with a number of replicas. The number is determined by the [parallelism](functions-deploy-cluster-parallelism.md) of the function. The pod downloads the function payload (via the function worker REST API) on pod boot. The pod's container image is configurable if the function runtime is configured. diff --git a/docs/functions-runtime-process.md b/docs/functions-runtime-process.md index e1649e78c497..12219b9587d2 100644 --- a/docs/functions-runtime-process.md +++ b/docs/functions-runtime-process.md @@ -5,6 +5,15 @@ sidebar_label: "Configure process runtime" description: Configure process runtime for functions in Pulsar. --- +:::warning Run only fully trusted code + +Pulsar Functions and connectors execute user-provided code by design. This intended capability is not itself a remote code execution (RCE) vulnerability. **Run only code that you fully trust**, because it can modify its execution environment: + +- **Thread and process runtimes** can read or modify any files and state accessible to the process they run in. +- **The Kubernetes runtime** does not, on its own, restrict access to Kubernetes cluster resources. Pulsar provides hooks for custom hardening, but the hardening itself is outside the project. + +::: + You can use the default configurations of process runtime in the `conf/functions_worker.yml` file. If you want to customize more parameters, refer to the following example. diff --git a/docs/functions-runtime-thread.md b/docs/functions-runtime-thread.md index 8994677bb902..6c8ddde64496 100644 --- a/docs/functions-runtime-thread.md +++ b/docs/functions-runtime-thread.md @@ -5,6 +5,15 @@ sidebar_label: "Configure thread runtime" description: Configure thread runtime for functions in Pulsar. --- +:::warning Run only fully trusted code + +Pulsar Functions and connectors execute user-provided code by design. This intended capability is not itself a remote code execution (RCE) vulnerability. **Run only code that you fully trust**, because it can modify its execution environment: + +- **Thread and process runtimes** can read or modify any files and state accessible to the process they run in. +- **The Kubernetes runtime** does not, on its own, restrict access to Kubernetes cluster resources. Pulsar provides hooks for custom hardening, but the hardening itself is outside the project. + +::: + You can use the default configurations of thread runtime in the `conf/functions_worker.yml` file. If you want to customize more parameters, such as thread group name, refer to the following example. diff --git a/docs/functions-worker-corun.md b/docs/functions-worker-corun.md index 6168e3efa962..a563d4ccb68e 100644 --- a/docs/functions-worker-corun.md +++ b/docs/functions-worker-corun.md @@ -5,6 +5,15 @@ sidebar_label: "Run function workers with brokers" description: Run Pulsar function workers with brokers. --- +:::warning Run only fully trusted code + +Pulsar Functions and connectors execute user-provided code by design. This intended capability is not itself a remote code execution (RCE) vulnerability. **Run only code that you fully trust**, because it can modify its execution environment: + +- **Thread and process runtimes** can read or modify any files and state accessible to the process they run in. +- **The Kubernetes runtime** does not, on its own, restrict access to Kubernetes cluster resources. Pulsar provides hooks for custom hardening, but the hardening itself is outside the project. + +::: + The following diagram illustrates the deployment of function workers running along with brokers. ![Deployment of function workers in Pulsar](/assets/function-workers-corun.svg) diff --git a/docs/functions-worker-run-separately.md b/docs/functions-worker-run-separately.md index f6424d0fd48b..cc1bf913bbcd 100644 --- a/docs/functions-worker-run-separately.md +++ b/docs/functions-worker-run-separately.md @@ -5,6 +5,15 @@ sidebar_label: "Run function workers separately" description: Run Pulsar function workers separately. --- +:::warning Run only fully trusted code + +Pulsar Functions and connectors execute user-provided code by design. This intended capability is not itself a remote code execution (RCE) vulnerability. **Run only code that you fully trust**, because it can modify its execution environment: + +- **Thread and process runtimes** can read or modify any files and state accessible to the process they run in. +- **The Kubernetes runtime** does not, on its own, restrict access to Kubernetes cluster resources. Pulsar provides hooks for custom hardening, but the hardening itself is outside the project. + +::: + The following diagram illustrates how function workers run as a separate process in separate machines. ![Function workers run separately in Pulsar](/assets/function-workers-separated.svg) diff --git a/docs/release-highlights.md b/docs/release-highlights.md index 9d63f9357733..fa291830a1f8 100644 --- a/docs/release-highlights.md +++ b/docs/release-highlights.md @@ -90,7 +90,7 @@ The [v5 Java client API](pathname:///docs/client-libraries/java-v5) gives applic The API supports Scalable Topics and existing persistent topics. Applications can also [subscribe across a namespace](pathname:///docs/client-libraries/java-v5#consume-a-namespace), selecting topics by properties. Producer and receive-buffer backpressure, non-blocking asynchronous receives, and reduced acknowledgment overhead help applications handle bursts efficiently. -For new applications or dependency updates, **`org.apache.pulsar:pulsar-client-v5-all`** brings the v4 client, v5 client, and admin implementation together through unshaded dependencies. You can adopt the combined dependency while continuing to use the v4 API. See [Java client setup](pathname:///docs/client-libraries/java-setup) for Maven and Gradle configuration, and the [API migration guide](pathname:///docs/client-libraries/java-migrate-to-v5) when you are ready to use the new consumer models. +**One dependency for the v4, v5, and admin clients.** For new applications or dependency updates, `org.apache.pulsar:pulsar-client-v5-all` provides all three through a single unshaded dependency with transitive dependencies. You can adopt it while continuing to use only the v4 API. See [Pulsar Java client dependency configuration](pathname:///docs/client-libraries/java-dependency-configuration) for complete Maven and Gradle examples, BOM alignment, and conflict exclusions, and the [API migration guide](pathname:///docs/client-libraries/java-migrate-to-v5) when you are ready to use the new consumer models. The v5 API requires scalable-topic services to be enabled on the brokers, including for regular topics. The v4 API works whether those services are enabled or disabled, so application migration can follow the cluster upgrade on its own schedule. diff --git a/sidebarsClientLibraries.js b/sidebarsClientLibraries.js index 4cb968c1bc09..e8170feade4c 100644 --- a/sidebarsClientLibraries.js +++ b/sidebarsClientLibraries.js @@ -13,7 +13,12 @@ module.exports = { label: "Java client", link: {type: "doc", id: "java"}, items: [ - "java-setup", + { + type: "category", + label: "Set up", + link: {type: "doc", id: "java-setup"}, + items: ["java-dependency-configuration"], + }, "java-initialize", "java-use", "java-tracing", diff --git a/src/config/pulsarVariables.ts b/src/config/pulsarVariables.ts index 3a7de47833d6..3cc78b88516d 100644 --- a/src/config/pulsarVariables.ts +++ b/src/config/pulsarVariables.ts @@ -292,6 +292,7 @@ export function resolveTokens(versionKey: string, referenceLatest = false): Map< ["version:latest", latestVersion], ["version:latest-v5plus", latestV5PlusRelease], ["version:lts", ltsVersion], + ["version:major", originVersion.split(".").slice(0, 2).join(".")], ["version:python", clientPythonVersion(pythonArg)], ["version:netty", nettyVersion], ["version", resolvedVersion], diff --git a/versioned_docs/version-5.0.x/about.md b/versioned_docs/version-5.0.x/about.md index 276bb3be83a9..1b39f43f101e 100644 --- a/versioned_docs/version-5.0.x/about.md +++ b/versioned_docs/version-5.0.x/about.md @@ -15,7 +15,11 @@ import { docUrl } from "@site/src/utils/index"; This portal holds a variety of topics, tutorials, guides, and reference material to help you work with Pulsar. -Preparing to upgrade? Start with the [release highlights](release-highlights.md) and the [cluster upgrade guide](administration-upgrade.md). +:::tip Preparing to upgrade to Pulsar @pulsar:version:major@? + +Start with the [release highlights](release-highlights.md) and the [cluster upgrade guide](administration-upgrade.md). + +::: ## Choose your path Select one of the content blocks below to begin your Pulsar journey. If you ... @@ -59,4 +63,4 @@ The Pulsar community on GitHub is active, passionate, and knowledgeable. Join d * Please go to [the community page](pathname:///community/#section-discussions) to find the contact information for joining various communication channels. * The main communication channel for the Apache Pulsar project are [the mailing lists](pathname:///contact/). -* There's a separate page for Apache Pulsar [Security advisories and Security policy](pathname:///security/). \ No newline at end of file +* There's a separate page for Apache Pulsar [Security advisories and Security policy](pathname:///security/). diff --git a/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x-applications.md b/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x-applications.md index 1f6d16b3e268..4da5f03a1748 100644 --- a/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x-applications.md +++ b/versioned_docs/version-5.0.x/administration-upgrade-to-5.0.x-applications.md @@ -23,7 +23,7 @@ Dependency migration is separate from v5 API adoption. An application using eith When adopting the unshaded `pulsar-client-v5-all` dependency, upgrade application dependencies from Netty 4.1.x to **Netty 4.2.x**. Pulsar uses **@pulsar:version:netty@**. Netty 4.2 is largely backward compatible with 4.1, but both lines cannot coexist on the same classpath. This dependency alignment is part of updating the application; it is not required merely to upgrade brokers while retaining an existing v4 client dependency. -Import `io.netty:netty-bom` alongside `pulsar-bom`, update framework-managed Netty versions, and verify that the resolved runtime graph and packaged application contain a consistent set of Netty modules without old or duplicate JARs. See the [Maven and Gradle setup examples](pathname:///docs/client-libraries/java-setup#pulsar-bom) and the [Netty migration guide](https://netty.io/wiki/netty-4.2-migration-guide.html). +Import `io.netty:netty-bom` alongside `pulsar-bom`, update framework-managed Netty versions, and verify that the resolved runtime graph and packaged application contain a consistent set of Netty modules without old or duplicate JARs. See the [Maven and Gradle setup examples](pathname:///docs/client-libraries/java-dependency-configuration#pulsar-bom) and the [Netty migration guide](https://netty.io/wiki/netty-4.2-migration-guide.html). ## Check schema dependencies diff --git a/versioned_docs/version-5.0.x/functions-package-python.md b/versioned_docs/version-5.0.x/functions-package-python.md index 8653b73e2650..4696c1966b34 100644 --- a/versioned_docs/version-5.0.x/functions-package-python.md +++ b/versioned_docs/version-5.0.x/functions-package-python.md @@ -40,11 +40,7 @@ To package a Python function into **one Python file**, complete the following st pip install 'pulsar-client==@pulsar:version:python@' ``` - And install protobuf tools to generate the proto files: - - ```bash - pip install 'protobuf==3.20.*' - ``` + This example does not require generating Protocol Buffers files or installing `protobuf` separately. The Pulsar Docker image already includes the Python function runtime's dependencies. 3. Copy the Python function file to the Pulsar image. diff --git a/versioned_docs/version-5.0.x/functions-runtime-kubernetes.md b/versioned_docs/version-5.0.x/functions-runtime-kubernetes.md index bcbf21a68cbe..17bbda4794fb 100644 --- a/versioned_docs/version-5.0.x/functions-runtime-kubernetes.md +++ b/versioned_docs/version-5.0.x/functions-runtime-kubernetes.md @@ -5,6 +5,15 @@ sidebar_label: "Configure Kubernetes runtime" description: Configure Kubernetes runtime for functions in Pulsar. --- +:::warning Run only fully trusted code + +Pulsar Functions and connectors execute user-provided code by design. This intended capability is not itself a remote code execution (RCE) vulnerability. **Run only code that you fully trust**, because it can modify its execution environment: + +- **Thread and process runtimes** can read or modify any files and state accessible to the process they run in. +- **The Kubernetes runtime** does not, on its own, restrict access to Kubernetes cluster resources. Pulsar provides hooks for custom hardening, but the hardening itself is outside the project. + +::: + The Kubernetes runtime works when a function worker generates and applies Kubernetes manifests. The manifests generated by a function worker include: * a `StatefulSet` By default, the `StatefulSet` manifest has a single pod with a number of replicas. The number is determined by the [parallelism](functions-deploy-cluster-parallelism.md) of the function. The pod downloads the function payload (via the function worker REST API) on pod boot. The pod's container image is configurable if the function runtime is configured. diff --git a/versioned_docs/version-5.0.x/functions-runtime-process.md b/versioned_docs/version-5.0.x/functions-runtime-process.md index e1649e78c497..12219b9587d2 100644 --- a/versioned_docs/version-5.0.x/functions-runtime-process.md +++ b/versioned_docs/version-5.0.x/functions-runtime-process.md @@ -5,6 +5,15 @@ sidebar_label: "Configure process runtime" description: Configure process runtime for functions in Pulsar. --- +:::warning Run only fully trusted code + +Pulsar Functions and connectors execute user-provided code by design. This intended capability is not itself a remote code execution (RCE) vulnerability. **Run only code that you fully trust**, because it can modify its execution environment: + +- **Thread and process runtimes** can read or modify any files and state accessible to the process they run in. +- **The Kubernetes runtime** does not, on its own, restrict access to Kubernetes cluster resources. Pulsar provides hooks for custom hardening, but the hardening itself is outside the project. + +::: + You can use the default configurations of process runtime in the `conf/functions_worker.yml` file. If you want to customize more parameters, refer to the following example. diff --git a/versioned_docs/version-5.0.x/functions-runtime-thread.md b/versioned_docs/version-5.0.x/functions-runtime-thread.md index 8994677bb902..6c8ddde64496 100644 --- a/versioned_docs/version-5.0.x/functions-runtime-thread.md +++ b/versioned_docs/version-5.0.x/functions-runtime-thread.md @@ -5,6 +5,15 @@ sidebar_label: "Configure thread runtime" description: Configure thread runtime for functions in Pulsar. --- +:::warning Run only fully trusted code + +Pulsar Functions and connectors execute user-provided code by design. This intended capability is not itself a remote code execution (RCE) vulnerability. **Run only code that you fully trust**, because it can modify its execution environment: + +- **Thread and process runtimes** can read or modify any files and state accessible to the process they run in. +- **The Kubernetes runtime** does not, on its own, restrict access to Kubernetes cluster resources. Pulsar provides hooks for custom hardening, but the hardening itself is outside the project. + +::: + You can use the default configurations of thread runtime in the `conf/functions_worker.yml` file. If you want to customize more parameters, such as thread group name, refer to the following example. diff --git a/versioned_docs/version-5.0.x/functions-worker-corun.md b/versioned_docs/version-5.0.x/functions-worker-corun.md index 6168e3efa962..a563d4ccb68e 100644 --- a/versioned_docs/version-5.0.x/functions-worker-corun.md +++ b/versioned_docs/version-5.0.x/functions-worker-corun.md @@ -5,6 +5,15 @@ sidebar_label: "Run function workers with brokers" description: Run Pulsar function workers with brokers. --- +:::warning Run only fully trusted code + +Pulsar Functions and connectors execute user-provided code by design. This intended capability is not itself a remote code execution (RCE) vulnerability. **Run only code that you fully trust**, because it can modify its execution environment: + +- **Thread and process runtimes** can read or modify any files and state accessible to the process they run in. +- **The Kubernetes runtime** does not, on its own, restrict access to Kubernetes cluster resources. Pulsar provides hooks for custom hardening, but the hardening itself is outside the project. + +::: + The following diagram illustrates the deployment of function workers running along with brokers. ![Deployment of function workers in Pulsar](/assets/function-workers-corun.svg) diff --git a/versioned_docs/version-5.0.x/functions-worker-run-separately.md b/versioned_docs/version-5.0.x/functions-worker-run-separately.md index f6424d0fd48b..cc1bf913bbcd 100644 --- a/versioned_docs/version-5.0.x/functions-worker-run-separately.md +++ b/versioned_docs/version-5.0.x/functions-worker-run-separately.md @@ -5,6 +5,15 @@ sidebar_label: "Run function workers separately" description: Run Pulsar function workers separately. --- +:::warning Run only fully trusted code + +Pulsar Functions and connectors execute user-provided code by design. This intended capability is not itself a remote code execution (RCE) vulnerability. **Run only code that you fully trust**, because it can modify its execution environment: + +- **Thread and process runtimes** can read or modify any files and state accessible to the process they run in. +- **The Kubernetes runtime** does not, on its own, restrict access to Kubernetes cluster resources. Pulsar provides hooks for custom hardening, but the hardening itself is outside the project. + +::: + The following diagram illustrates how function workers run as a separate process in separate machines. ![Function workers run separately in Pulsar](/assets/function-workers-separated.svg) diff --git a/versioned_docs/version-5.0.x/release-highlights.md b/versioned_docs/version-5.0.x/release-highlights.md index 9d63f9357733..fa291830a1f8 100644 --- a/versioned_docs/version-5.0.x/release-highlights.md +++ b/versioned_docs/version-5.0.x/release-highlights.md @@ -90,7 +90,7 @@ The [v5 Java client API](pathname:///docs/client-libraries/java-v5) gives applic The API supports Scalable Topics and existing persistent topics. Applications can also [subscribe across a namespace](pathname:///docs/client-libraries/java-v5#consume-a-namespace), selecting topics by properties. Producer and receive-buffer backpressure, non-blocking asynchronous receives, and reduced acknowledgment overhead help applications handle bursts efficiently. -For new applications or dependency updates, **`org.apache.pulsar:pulsar-client-v5-all`** brings the v4 client, v5 client, and admin implementation together through unshaded dependencies. You can adopt the combined dependency while continuing to use the v4 API. See [Java client setup](pathname:///docs/client-libraries/java-setup) for Maven and Gradle configuration, and the [API migration guide](pathname:///docs/client-libraries/java-migrate-to-v5) when you are ready to use the new consumer models. +**One dependency for the v4, v5, and admin clients.** For new applications or dependency updates, `org.apache.pulsar:pulsar-client-v5-all` provides all three through a single unshaded dependency with transitive dependencies. You can adopt it while continuing to use only the v4 API. See [Pulsar Java client dependency configuration](pathname:///docs/client-libraries/java-dependency-configuration) for complete Maven and Gradle examples, BOM alignment, and conflict exclusions, and the [API migration guide](pathname:///docs/client-libraries/java-migrate-to-v5) when you are ready to use the new consumer models. The v5 API requires scalable-topic services to be enabled on the brokers, including for regular topics. The v4 API works whether those services are enabled or disabled, so application migration can follow the cluster upgrade on its own schedule.