Apache Pulsar: a multi-tenant pub-sub platform for teams that outgrew a single broker

What Apache Pulsar solves, and for whom

The problem Pulsar targets is stated plainly in its README: it is a distributed pub-sub messaging platform designed for deployment as a hosted service. The feature list names multi-tenancy, authentication, authorization, quotas, and support for mixing very different workloads, with optional hardware isolation. That is a service-provider problem, not a single-application problem. If one team owns one broker and one set of topics, most of that list is dead weight.

The intended user is an organisation running messaging for several internal teams or external customers, where one tenant's backlog must not starve another's, and where topic counts run into the millions. The README claims horizontal scalability to millions of independent topics and millions of messages published per second, and strong ordering and consistency guarantees. Those are the two properties that pull people away from simpler brokers: topic count at scale, and strong ordering and consistency guarantees.

Pulsar also carries queue semantics alongside topic semantics, so a single system covers both the fan-out case and the work-queue case. Teams that currently run two systems for those two patterns are the clearest fit.

How Pulsar splits serving from storage

The repository layout is the fastest way to understand the architecture. At the top level there is pulsar-broker, managed-ledger, pulsar-client-api, pulsar-client-admin, pulsar-broker-common, and a set of auth modules: pulsar-broker-auth-athenz, pulsar-broker-auth-oidc, pulsar-broker-auth-sasl. The broker module is the serving layer. The managed-ledger module is the storage abstraction that sits underneath it.

Consumer cursor position is tracked by the system rather than by the application. Geo replication is listed as a feature. Transparent batching and transparent handling of partitioned topics mean the client does not have to know whether a logical topic is split into partitions.

Administration is exposed through a REST API for provisioning, admin and stats, with a separate pulsar-client-admin module for Java callers. The README also points to Pulsar Manager and Dekaf UI as dashboard and management tools, both in separate repositories, so neither is part of this codebase. Note what is not in this repository: connectors are bundled under pulsar-io, and the README marks the standalone Pulsar Connectors repository as archived, with the code now living inside this tree.

Installing Pulsar and publishing a first message

The README points at https://pulsar.apache.org for downloads, and the repository ships a docker/ directory and a docker-compose/ directory, plus a Docker Hub badge for the apachepulsar/pulsar image. For a running broker, the container image is the path the project itself advertises.

docker pull apachepulsar/pulsar

The README states that Pulsar Docker images come with the most recent Java version at the time of release, and the compatibility table lists the Docker image Java runtime as 21 for Pulsar 3.3 through 4.0 and for 4.1 and later. So the image is self-contained; you do not pick the JDK yourself.

For a source build, the requirements section gives the JDK per version. The master branch accepts JDK 21, 25 or 26. Release 4.0 and later needs JDK 21. 2.11 and later needs JDK 17. The build instructions themselves live in CONTRIBUTING.md under Building, and the Gradle infrastructure is documented in ARCHITECTURE.md under Build infrastructure. The wrapper scripts gradlew and gradlew.bat are at the repository root, and the README points to CONTRIBUTING.md for the full build and lint commands.

On the client side, the README recommends setting specific system properties and JVM options when using the Java client, and links to the client-libraries-java-setup page for that. It does not reproduce those properties here, so read that page before tuning. Java client compatibility is broad across releases: 8, 11, 17 or 21 for Pulsar 3.3 through 4.0, and 17 or 21 for 4.1 and later. The README also warns about JDK-8351933, a JVM bug that can cause stability issues in Pulsar, fixed in Java 17.0.17+ and Java 21.0.8+. Pin your JDK above those patch levels.

Where Pulsar is the wrong tool

The clearest limitation is operational surface. The repository contains a broker, a managed-ledger storage layer, a REST admin service, several authentication modules, a CLI, and separate client implementations for .NET, C++, Go, NodeJS, Python and reactive Java, each in its own repository. Running a production cluster means running the broker tier and the storage tier. If your workload fits on one machine, this is a large amount of infrastructure for the problem.

The Java version table is a second real constraint. Pulsar 4.1 and later requires JDK 21 for the broker, functions and IO. If your organisation standardises on JDK 17 for server software, the runtime table points you to Pulsar 3.0 or earlier, since the broker needs JDK 21 from 3.3 onwards. Releases 2.8 through 2.10 build with JDK 11. Upgrading Pulsar can therefore force a JVM upgrade across your whole deployment, and the README's own bug note about JDK-8351933 shows that running an older patch of a supported major version is a stability risk, not a neutral choice.

Release lines are another choice to make deliberately. The recent release list shows v5.0.1 on 2026-10-26 alongside v4.2.5 and v4.0.14, both dated 2026-10-05, so more than one line receives releases at once.

Pulsar against Kafka and NATS

Apache Kafka is the obvious comparison. Kafka's storage is tied to the broker that owns a partition: a partition lives on a broker, and moving it means replicating it. Kafka's ecosystem is larger and its operational literature is deeper; the Pulsar README does not make a comparison claim, and it should not be read as one.

NATS takes the opposite approach from both. It is a lightweight messaging system with a much smaller deployment footprint, and its JetStream layer adds persistence. If your topic count is in the hundreds and your team is small, NATS is the smaller commitment. Pulsar's advantage only materialises when multi-tenancy, quotas and geo replication are requirements you actually have.

A more relevant internal comparison is Pulsar against its own client surface. The README lists six language clients in separate repositories, plus the Java client in this one. Adopting Pulsar means adopting a client matrix, and a feature that exists in the Java client is not automatically present in the Go or NodeJS client. Check the client repository you will actually use before committing to a language.

Maintenance, release cadence and licence

The repository is not archived, and the last push was on 2026-11-02. Three releases appear in the recent list: v5.0.1 on 2026-10-26, and v4.2.5 and v4.0.14 both on 2026-10-05. That pattern, a release on the 5.0 line plus simultaneous patch releases on two older lines, indicates parallel maintenance of more than one branch. It also means upgrade planning has to pick a line deliberately rather than following the highest version number.

Upgrade cost is dominated by the Java version table. Moving from the 4.0 line to 4.1 or later keeps the broker on JDK 21, so that step is comparatively contained. Moving from 2.x to 4.x crosses JDK 11 to JDK 17 to JDK 21, and the client compatibility window narrows at the same time: the Java client supports 8, 11, 17 or 21 on 3.3 through 4.0, but only 17 or 21 on 4.1 and later. Any service still compiled against Java 8 has to move before the broker does.

The licence is Apache-2.0, held by the Apache Software Foundation. The README's header carries the standard ASF notice and points to the LICENSE and NOTICE files, and the repository root contains both. Apache-2.0 includes an explicit patent grant and permits commercial use and redistribution. This is a description of the licence text, not legal advice; if you redistribute Pulsar inside a product, read the NOTICE file and your own legal review, not this article.

Editorial conclusion

Adopt Pulsar when several teams need isolated namespaces, quotas and geo replication on one cluster, and when you can staff a broker plus BookKeeper plus metadata store. Do not adopt it as a drop-in replacement for a single-node broker on one machine; the README's own feature list assumes a hosted-service deployment. Before committing, verify the Java version your target release requires against the compatibility table, confirm the release you plan to run is not a milestone build, and read the SECURITY.md and CONTRIBUTING.md files at the repository root for the project's own process.

Frequently asked questions

Official sources

1. apache/pulsar on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases