Managing Namespaces

Pulsar namespaces are logical groupings of topics.

Namespaces can be managed via:

The namespaces command of the pulsar-admin tool
The /admin/v2/namespaces endpoint of the admin REST API
The namespaces method of the PulsarAdmin object in the Java API

Namespaces resources

Create

You can create new namespaces under a given tenant.

pulsar-admin

Use the create subcommand and specify the namespace by name:

$ pulsar-admin namespaces create test-tenant/test-namespace

REST API

PUT /admin/v2/namespaces/:tenant/:namespace/createNamespace

Java

admin.namespaces().createNamespace(namespace);

Get policies

You can fetch the current policies associated with a namespace at any time.

pulsar-admin

Use the policies subcommand and specify the namespace:

$ pulsar-admin namespaces policies test-tenant/test-namespace
{
  "auth_policies": {
    "namespace_auth": {},
    "destination_auth": {}
  },
  "replication_clusters": [],
  "bundles_activated": true,
  "bundles": {
    "boundaries": [
      "0x00000000",
      "0xffffffff"
    ],
    "numBundles": 1
  },
  "backlog_quota_map": {},
  "persistence": null,
  "latency_stats_sample_rate": {},
  "message_ttl_in_seconds": 0,
  "retention_policies": null,
  "deleted": false
}

REST API

GET /admin/v2/namespaces/:tenant/:namespace/getPolicies

Java

admin.namespaces().getPolicies(namespace);

List namespaces within a tenant

You can list all namespaces within a given Pulsar tenant.

pulsar-admin

Use the list subcommand and specify the tenant:

$ pulsar-admin namespaces list test-tenant
test-tenant/ns1
test-tenant/ns2

REST API

GET /admin/v2/namespaces/:tenant/getTenantNamespaces

Java

admin.namespaces().getNamespaces(tenant);

Delete

You can delete existing namespaces from a tenant.

pulsar-admin

Use the delete subcommand and specify the namespace:

$ pulsar-admin namespaces delete test-tenant/ns1

REST

DELETE /admin/v2/namespaces/:tenant/:namespace/deleteNamespace

Java

admin.namespaces().deleteNamespace(namespace);

set replication cluster

It sets replication clusters for a namespace, so Pulsar can internally replicate publish message from one colo to another colo.

CLI

$ pulsar-admin namespaces set-clusters test-tenant/ns1 \
  --clusters cl1

REST

[POST /admin/v2/namespaces/:tenant/:namespace/replication](https://pulsar.apache.org/admin-rest-api?version=2.3.0/setNamespaceReplicationClusters&apiversion=v2#operation)

Java

admin.namespaces().setNamespaceReplicationClusters(namespace, clusters);

get replication cluster

It gives a list of replication clusters for a given namespace.

CLI

$ pulsar-admin namespaces get-clusters test-tenant/cl1/ns1

cl2

REST

[GET /admin/v2/namespaces/:tenant/:namespace/replication](https://pulsar.apache.org/admin-rest-api?version=2.3.0/getNamespaceReplicationClusters&apiversion=v2#operation)

Java

admin.namespaces().getNamespaceReplicationClusters(namespace)

set backlog quota policies

Backlog quota helps broker to restrict bandwidth/storage of a namespace once it reach certain threshold limit . Admin can set this limit and one of the following action after the limit is reached.

producer_request_hold: broker will hold and not persist produce request payload
producer_exception: broker will disconnects with client by giving exception
consumer_backlog_eviction: broker will start discarding backlog messages

Backlog quota restriction can be taken care by defining restriction of backlog-quota-type: destination_storage

CLI

$ pulsar-admin namespaces set-backlog-quota --limit 10 --policy producer_request_hold test-tenant/ns1

N/A

REST

[POST /admin/v2/namespaces/:tenant/:namespace/backlogQuota/setBacklogQuota](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/setBacklogQuota)

Java

admin.namespaces().setBacklogQuota(namespace, new BacklogQuota(limit, policy))

get backlog quota policies

It shows a configured backlog quota for a given namespace.

CLI

$ pulsar-admin namespaces get-backlog-quotas test-tenant/ns1

{
  "destination_storage": {
    "limit": 10,
    "policy": "producer_request_hold"
  }
}

REST

[GET /admin/v2/namespaces/:tenant/:namespace/backlogQuotaMap/getBacklogQuotaMap](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/getBacklogQuotaMap)

Java

admin.namespaces().getBacklogQuotaMap(namespace);

remove backlog quota policies

It removes backlog quota policies for a given namespace

CLI

$ pulsar-admin namespaces remove-backlog-quota test-tenant/ns1

N/A

REST

[DELETE /admin/v2/namespaces/:tenant/:namespace/backlogQuota/removeBacklogQuota](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/removeBacklogQuota)

Java

admin.namespaces().removeBacklogQuota(namespace, backlogQuotaType)

set persistence policies

Persistence policies allow to configure persistency-level for all topic messages under a given namespace.

Bookkeeper-ack-quorum: Number of acks (guaranteed copies) to wait for each entry, default: 0
Bookkeeper-ensemble: Number of bookies to use for a topic, default: 0
Bookkeeper-write-quorum: How many writes to make of each entry, default: 0
Ml-mark-delete-max-rate: Throttling rate of mark-delete operation (0 means no throttle), default: 0.0

CLI

$ pulsar-admin namespaces set-persistence --bookkeeper-ack-quorum 2 --bookkeeper-ensemble 3 --bookkeeper-write-quorum 2 --ml-mark-delete-max-rate 0 test-tenant/ns1

N/A

REST

[POST /admin/v2/namespaces/:tenant/:namespace/persistence/setPersistence](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/setPersistence)

Java

admin.namespaces().setPersistence(namespace,new PersistencePolicies(bookkeeperEnsemble, bookkeeperWriteQuorum,bookkeeperAckQuorum,managedLedgerMaxMarkDeleteRate))

get persistence policies

It shows configured persistence policies of a given namespace.

CLI

$ pulsar-admin namespaces get-persistence test-tenant/ns1

{
  "bookkeeperEnsemble": 3,
  "bookkeeperWriteQuorum": 2,
  "bookkeeperAckQuorum": 2,
  "managedLedgerMaxMarkDeleteRate": 0
}

REST

[GET /admin/v2/namespaces/:tenant/:namespace/persistence/getPersistence](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/getPersistence)

Java

admin.namespaces().getPersistence(namespace)

unload namespace bundle

Namespace bundle is a virtual group of topics which belong to same namespace. If broker gets overloaded with number of bundles then this command can help to unload heavy bundle from that broker, so it can be served by some other less loaded broker. Namespace bundle is defined with it’s start and end range such as 0x00000000 and 0xffffffff.

CLI

$ pulsar-admin namespaces unload --bundle 0x00000000_0xffffffff test-tenant/ns1

N/A

REST

[PUT /admin/v2/namespaces/:tenant/:namespace/{bundle](https://pulsar.apache.org/admin-rest-api?version=master&apiversion=v2#)/unload|operation/unloadNamespaceBundle?version=2.3.0}

Java

admin.namespaces().unloadNamespaceBundle(namespace, bundle)

set message-ttl

It configures message’s time to live (in seconds) duration.

CLI

$ pulsar-admin namespaces set-message-ttl --messageTTL 100 test-tenant/ns1

N/A

REST

[POST /admin/v2/namespaces/:tenant/:namespace/messageTTL/setNamespaceMessageTTL](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/setNamespaceMessageTTL)

Java

admin.namespaces().setNamespaceMessageTTL(namespace, messageTTL)

get message-ttl

It gives a message ttl of configured namespace.

CLI

$ pulsar-admin namespaces get-message-ttl test-tenant/ns1

100

REST

[GET /admin/v2/namespaces/:tenant/:namespace/messageTTL/getNamespaceMessageTTL](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/getNamespaceMessageTTL)

Java

admin.namespaces().getNamespaceMessageTTL(namespace)

split bundle

Each namespace bundle can contain multiple topics and each bundle can be served by only one broker. If bundle gets heavy with multiple live topics in it then it creates load on that broker and in order to resolve this issue, admin can split bundle using this command.

CLI

$ pulsar-admin namespaces split-bundle --bundle 0x00000000_0xffffffff test-tenant/ns1

N/A

REST

[PUT /admin/v2/namespaces/:tenant/:namespace/{bundle](https://pulsar.apache.org/admin-rest-api?version=master&apiversion=v2#)/split|operation/splitNamespaceBundle?version=2.3.0}

Java

admin.namespaces().splitNamespaceBundle(namespace, bundle, unloadSplitBundles)

clear backlog

It clears all message backlog for all the topics those belong to specific namespace. You can also clear backlog for a specific subscription as well.

CLI

$ pulsar-admin namespaces clear-backlog --sub my-subscription test-tenant/ns1

N/A

REST

[POST /admin/v2/namespaces/:tenant/:namespace/clearBacklog](https://pulsar.apache.org/admin-rest-api?version=2.3.0/clearNamespaceBacklogForSubscription&apiversion=v2#operation)

Java

admin.namespaces().clearNamespaceBacklogForSubscription(namespace, subscription)

clear bundle backlog

It clears all message backlog for all the topics those belong to specific NamespaceBundle. You can also clear backlog for a specific subscription as well.

CLI

$ pulsar-admin namespaces clear-backlog  --bundle 0x00000000_0xffffffff  --sub my-subscription test-tenant/ns1

N/A

REST

[POST /admin/v2/namespaces/:tenant/:namespace/{bundle](https://pulsar.apache.org/admin-rest-api?version=master&apiversion=v2#)/clearBacklog|operation?version=2.3.0/clearNamespaceBundleBacklogForSubscription}

Java

admin.namespaces().clearNamespaceBundleBacklogForSubscription(namespace, bundle, subscription)

set retention

Each namespace contains multiple topics and each topic’s retention size (storage size) should not exceed to a specific threshold or it should be stored till certain time duration. This command helps to configure retention size and time of topics in a given namespace.

CLI

$ pulsar-admin set-retention --size 10 --time 100 test-tenant/ns1

N/A

REST

[POST /admin/v2/namespaces/:tenant/:namespace/retention/setRetention](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/setRetention)

Java

admin.namespaces().setRetention(namespace, new RetentionPolicies(retentionTimeInMin, retentionSizeInMB))

get retention

It shows retention information of a given namespace.

CLI

$ pulsar-admin namespaces get-retention test-tenant/ns1

{
  "retentionTimeInMinutes": 10,
  "retentionSizeInMB": 100
}

REST

[GET /admin/v2/namespaces/:tenant/:namespace/retention/getRetention](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/getRetention)

Java

admin.namespaces().getRetention(namespace)

set dispatch throttling

It sets message dispatch rate for all the topics under a given namespace. Dispatch rate can be restricted by number of message per X seconds (msg-dispatch-rate) or by number of message-bytes per X second (byte-dispatch-rate). dispatch rate is in second and it can be configured with dispatch-rate-period. Default value of msg-dispatch-rate and byte-dispatch-rate is -1 which disables the throttling.

CLI

$ pulsar-admin namespaces set-dispatch-rate test-tenant/ns1 \
  --msg-dispatch-rate 1000 \
  --byte-dispatch-rate 1048576 \
  --dispatch-rate-period 1

REST

[POST /admin/v2/namespaces/:tenant/:namespace/dispatchRate/setDispatchRate](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/setDispatchRate)

Java

admin.namespaces().setDispatchRate(namespace, 1000, 1048576, 1)

get configured message-rate

It shows configured message-rate for the namespace (topics under this namespace can dispatch this many messages per second)

CLI

$ pulsar-admin namespaces get-dispatch-rate test-tenant/ns1

{
  "dispatchThrottlingRatePerTopicInMsg" : 1000,
  "dispatchThrottlingRatePerTopicInByte" : 1048576,
  "ratePeriodInSecond" : 1
}

REST

[GET /admin/v2/namespaces/:tenant/:namespace/dispatchRate/getDispatchRate](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/getDispatchRate)

Java

admin.namespaces().getDispatchRate(namespace)

Unloading from a broker

You can unload a namespace, or a namespace bundle, from the Pulsar broker that is currently responsible for it.

pulsar-admin

Use the unload subcommand of the namespaces command.

CLI

$ pulsar-admin namespaces unload my-tenant/my-ns

REST

[PUT /admin/v2/namespaces/:tenant/:namespace/unload/unloadNamespace](https://pulsar.apache.org/admin-rest-api?version=2.3.0&apiversion=v2#operation/unloadNamespace)

Java

admin.namespaces().unload(namespace)

Namespaces resources​

Create​

pulsar-admin​

REST API​

Java​

Get policies​

pulsar-admin​

REST API​

Java​

List namespaces within a tenant​

pulsar-admin​

REST API​

Java​

Delete​

pulsar-admin​

REST​

Java​

set replication cluster​

CLI​

REST​

Java​

get replication cluster​

CLI​

REST​

Java​

set backlog quota policies​

CLI​

REST​

Java​

get backlog quota policies​

CLI​

REST​

Java​

remove backlog quota policies​

CLI​

REST​

Java​

set persistence policies​

CLI​

REST​

Java​

get persistence policies​

CLI​

REST​

Java​

unload namespace bundle​

CLI​

REST​

Java​

set message-ttl​

CLI​

REST​

Java​

get message-ttl​

CLI​

REST​

Java​

split bundle​

CLI​

REST​

Java​

clear backlog​

CLI​

REST​

Java​

clear bundle backlog​

CLI​

REST​

Java​

set retention​

CLI​

REST​

Java​

get retention​

CLI​

REST​

Java​

set dispatch throttling​

CLI​

REST​

Namespaces resources

Create

pulsar-admin

REST API

Java

Get policies

pulsar-admin

REST API

Java

List namespaces within a tenant

pulsar-admin

REST API

Java

Delete

pulsar-admin

REST

Java

set replication cluster

CLI

REST

Java

get replication cluster

CLI

REST

Java

set backlog quota policies

CLI

REST

Java

get backlog quota policies

CLI

REST

Java

remove backlog quota policies

CLI

REST

Java

set persistence policies

CLI

REST

Java

get persistence policies

CLI

REST

Java

unload namespace bundle

CLI

REST

Java

set message-ttl

CLI

REST

Java

get message-ttl

CLI

REST

Java

split bundle

CLI

REST

Java

clear backlog

CLI

REST

Java

clear bundle backlog

CLI

REST

Java

set retention

CLI

REST

Java

get retention

CLI

REST

Java

set dispatch throttling

CLI

REST