1. Pulsar Guidelines
  2. Planning Guides

Get Started with Multi-Tenancy

Multi-tenancy allows you to support multiple organizations (or sub-organizations) within your company on a single platform. Sharing a single deployment across the organization is cost effective because cluster servers are better utilized and capacity planning is more accurate.

Setting up multi-tenancy is hard to do in other messaging systems. Pulsar was created from the ground up as a multi-tenant system. A single cluster can support many tenants and use cases, streamlining operations and avoiding data silos. You can slice up a cluster in smaller pieces and hand everyone their share of the cluster. As a result, your data is more secure because you cannot see data in other tenants very easily.

Hierarchical structure

Multi-tenancy is one of the key benefits of using Pulsar. A single Pulsar cluster can support many tenants and allows you to map Pulsar topics to different teams, applications, or use cases. It serves as the foundation of security and allows for unified, global management of multiple clusters.

The hierarchical structure of the underlying, logical components for multi-tenancy are:

  • Instance
  • Cluster
  • Tenant
  • Namespace
  • Topic

For details on each component, see the glossary or watch a short video that steps you through how multi-tenancy works.

Manage Pulsar clusters with policies

You can manage Pulsar clusters by setting policies at different levels.

For tenants:

  • You can assign an authorization scheme.
  • You can specify the set of clusters to which the configuration applies.

For namespaces and topics:

  • Policies set on a namespace apply to all the topics in that namespace.
  • Retention policy and storage quota policies are only available at a namespace level.

Access control and message property enforcement policies

In most organizations, controlling access to data is critical. Pulsar includes a robust authorization system, which is core to the multi-tenancy model.

Beyond just access-control, ensuring that data matches organizational standards is important. Pulsar includes policies to control:

  • Permissions and control over subscription access
  • Encryption and schema enforcement


Setting up multi-tenancy for your organization is not hard to do in Pulsar. You map an organization to Pulsar tenants by creating a logical separation between different units or teams within your organization so that they can have their own isolated messaging environments.


To properly leverage Pulsar’s multi-tenancy model, it is important to decide on a design for how you will map your organization to Pulsar’s concept of tenants, namespaces, and topics.

Step 1: Design a map of your organizations needs using a defined hierarchy.

Identify the units or teams within your organization that need to be isolated from each other. This could be based on different applications, projects, or departments.

Example designs:

  • Tenant per team and namespace per application
  • Tenant per department, business unit, or product line and namespace per team
  • Tenant per application or function and namespace per customer

Step 2: Create tenants based on the design.

In Pulsar, a tenant is a logical container that encapsulates all the messaging resources needed by a unit or team. You can create tenants using the Pulsar CLI or the Pulsar Admin API. Assign each tenant a unique name and configure the resources required for that tenant, such as topics, namespaces, and permissions.

Step 3: Configure access and policies.

You can use various authentication and authorization mechanisms supported by Pulsar to control access to tenants. For example, you can use JWT tokens, OAuth 2.0, or LDAP to authenticate users, and then use roles and permissions to control access to specific tenants and resources.

You can then setup quotas and policies on the namespace and topic level.

Step 4: Deploy applications.

Once you have created tenants and configured access and policies, you can deploy your applications or services to each tenant. Each application or service should use the appropriate Pulsar client library and credentials to connect to its tenant.

Step 5: Monitor and manage.

You can use Pulsar's monitoring and management tools to monitor the health and performance of each tenant, track usage, and manage resources. This can help you optimize your messaging infrastructure and troubleshoot issues when they arise.

Planning Guides