Clusters API - Apache Pulsar

Overview

Clusters represent physical Pulsar deployments in different data centers or regions. The Clusters API allows you to create, configure, and manage cluster settings including service URLs, replication, and namespace isolation policies. Base Path: /admin/v2/clusters

List Clusters

Get the list of all Pulsar clusters.

GET /admin/v2/clusters

Response

clusters

array

Set of cluster names (excludes the “global” cluster)

Example

curl -X GET http://localhost:8080/admin/v2/clusters \
  -H "Authorization: Bearer <token>"

Response Example

[
  "us-west",
  "us-east",
  "eu-central"
]

Get Cluster Configuration

Retrieve the configuration for a specific cluster.

GET /admin/v2/clusters/{cluster}

Path Parameters

cluster

string

required

The cluster name

Response

serviceUrl

string

HTTP service URL for the broker

serviceUrlTls

string

HTTPS service URL for the broker

brokerServiceUrl

string

Pulsar protocol URL for the broker

brokerServiceUrlTls

string

Pulsar protocol URL with TLS

peerClusterNames

array

List of peer cluster names for replication

Example

curl -X GET http://localhost:8080/admin/v2/clusters/us-west \
  -H "Authorization: Bearer <token>"

Response Example

{
  "serviceUrl": "http://pulsar-us-west.example.com:8080",
  "serviceUrlTls": "https://pulsar-us-west.example.com:8443",
  "brokerServiceUrl": "pulsar://pulsar-us-west.example.com:6650",
  "brokerServiceUrlTls": "pulsar+ssl://pulsar-us-west.example.com:6651",
  "peerClusterNames": ["us-east", "eu-central"]
}

Create Cluster

Create a new cluster with the specified configuration.

PUT /admin/v2/clusters/{cluster}

Path Parameters

cluster

string

required

The cluster name to create. Cannot contain ’/’ characters.

Request Body

serviceUrl

string

required

HTTP service URL (e.g., http://broker.example.com:8080)

serviceUrlTls

string

HTTPS service URL (e.g., https://broker.example.com:8443)

brokerServiceUrl

string

required

Binary protocol URL (e.g., pulsar://broker.example.com:6650)

brokerServiceUrlTls

string

Binary protocol URL with TLS (e.g., pulsar+ssl://broker.example.com:6651)

peerClusterNames

array

List of peer clusters for replication

Example

curl -X PUT http://localhost:8080/admin/v2/clusters/us-west \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceUrl": "http://pulsar-us-west.example.com:8080",
    "serviceUrlTls": "https://pulsar-us-west.example.com:8443",
    "brokerServiceUrl": "pulsar://pulsar-us-west.example.com:6650",
    "brokerServiceUrlTls": "pulsar+ssl://pulsar-us-west.example.com:6651"
  }'

Response Codes

Code	Description
200	Cluster created successfully
400	Bad request (invalid URL format)
403	Don’t have super-user privileges
409	Cluster already exists
412	Cluster name is not valid
500	Internal server error

Update Cluster

Update an existing cluster’s configuration.

POST /admin/v2/clusters/{cluster}

Path Parameters

cluster

string

required

The cluster name to update

Request Body

serviceUrl

string

required

HTTP service URL

serviceUrlTls

string

HTTPS service URL

brokerServiceUrl

string

required

Binary protocol URL

brokerServiceUrlTls

string

Binary protocol URL with TLS

peerClusterNames

array

Updated list of peer clusters

Example

curl -X POST http://localhost:8080/admin/v2/clusters/us-west \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceUrl": "http://new-broker.example.com:8080",
    "brokerServiceUrl": "pulsar://new-broker.example.com:6650",
    "peerClusterNames": ["us-east", "eu-central", "ap-south"]
  }'

Response Codes

Code	Description
204	Cluster updated successfully
403	Don’t have super-user privileges
404	Cluster doesn’t exist
412	Invalid configuration

Delete Cluster

Delete a cluster.

DELETE /admin/v2/clusters/{cluster}

Path Parameters

cluster

string

required

The cluster name to delete

Example

curl -X DELETE http://localhost:8080/admin/v2/clusters/us-west \
  -H "Authorization: Bearer <token>"

Response Codes

Code	Description
204	Cluster deleted successfully
403	Don’t have super-user privileges
404	Cluster doesn’t exist
412	Cluster has active tenants

You cannot delete a cluster if tenants are still using it. Remove the cluster from all tenant configurations first.

Namespace Isolation Policies

Namespace isolation policies allow you to dedicate specific brokers to certain namespaces.

Create Namespace Isolation Policy

POST /admin/v2/clusters/{cluster}/namespaceIsolationPolicies/{policyName}

Path Parameters

cluster

string

required

The cluster name

policyName

string

required

Name for the isolation policy

Request Body

namespaces

array

required

List of namespace patterns (regex supported)

primary

array

required

Primary broker patterns

secondary

array

Secondary broker patterns

auto_failover_policy

object

required

Auto-failover configuration

Example

curl -X POST http://localhost:8080/admin/v2/clusters/us-west/namespaceIsolationPolicies/policy1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "namespaces": ["my-tenant/critical-.*"],
    "primary": ["broker-[0-3].*"],
    "secondary": ["broker-[4-7].*"],
    "auto_failover_policy": {
      "policy_type": "min_available",
      "parameters": {
        "min_limit": 2,
        "usage_threshold": 80
      }
    }
  }'

Get Namespace Isolation Policies

GET /admin/v2/clusters/{cluster}/namespaceIsolationPolicies

Delete Namespace Isolation Policy

DELETE /admin/v2/clusters/{cluster}/namespaceIsolationPolicies/{policyName}

Failure Domains

Failure domains group brokers for rack-aware placement.

Create Failure Domain

POST /admin/v2/clusters/{cluster}/failureDomains/{domainName}

Request Body

brokers

array

required

List of broker names in this domain

Example

curl -X POST http://localhost:8080/admin/v2/clusters/us-west/failureDomains/rack1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "brokers": [
      "broker-1.us-west.example.com",
      "broker-2.us-west.example.com"
    ]
  }'

Get Failure Domains

GET /admin/v2/clusters/{cluster}/failureDomains

Delete Failure Domain

DELETE /admin/v2/clusters/{cluster}/failureDomains/{domainName}

Best Practices

Cluster Setup

Use descriptive cluster names (e.g., region-based)
Configure both HTTP and binary protocol URLs
Always set up TLS URLs for production
Document cluster locations and purposes

Multi-Region Deployment

Create separate clusters for each region
Configure peer clusters for geo-replication
Use failure domains for rack awareness
Monitor cross-cluster latency

Namespace Isolation

Isolate critical workloads on dedicated brokers
Use regex patterns for flexible namespace matching
Configure appropriate failover policies
Monitor broker utilization

High Availability

Deploy multiple brokers per cluster
Configure failure domains across racks/zones
Set up automatic failover policies
Test disaster recovery procedures

Tenants API

Assign tenants to clusters

Brokers API

Monitor and manage broker nodes

REST API

CLI Tools

​Overview

​List Clusters

​Response

​Example

​Response Example

​Get Cluster Configuration

​Path Parameters

​Response

​Example

​Response Example

​Create Cluster

​Path Parameters

​Request Body

​Example

​Response Codes

​Update Cluster

​Path Parameters

​Request Body

​Example

​Response Codes

​Delete Cluster

​Path Parameters

​Example

​Response Codes

​Namespace Isolation Policies

​Create Namespace Isolation Policy

​Path Parameters

​Request Body

​Example

​Get Namespace Isolation Policies

​Delete Namespace Isolation Policy

​Failure Domains

​Create Failure Domain

​Request Body

​Example

​Get Failure Domains

​Delete Failure Domain

​Best Practices

​Cluster Setup

​Multi-Region Deployment

​Namespace Isolation

​High Availability

​Related Resources

Tenants API

Brokers API

Build docs developers (and LLMs) love

Overview

List Clusters

Response

Example

Response Example

Get Cluster Configuration

Path Parameters

Response

Example

Response Example

Create Cluster

Path Parameters

Request Body

Example

Response Codes

Update Cluster

Path Parameters

Request Body

Example

Response Codes

Delete Cluster

Path Parameters

Example

Response Codes

Namespace Isolation Policies

Create Namespace Isolation Policy

Path Parameters

Request Body

Example

Get Namespace Isolation Policies

Delete Namespace Isolation Policy

Failure Domains

Create Failure Domain

Request Body

Example

Get Failure Domains

Delete Failure Domain

Best Practices

Cluster Setup

Multi-Region Deployment

Namespace Isolation

High Availability

Related Resources