Important
This page only shows some frequently used operations.
For the latest and complete information about
Pulsar admin
, including commands, flags, descriptions, and more, see Pulsar admin doc.For the latest and complete information about
REST API
, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.For the latest and complete information about
Java admin API
, including classes, methods, descriptions, and more, see Java admin API doc.
Pulsar namespaces are logical groupings of topics.
Namespaces can be managed via:
namespaces
command of the pulsar-admin
tool/admin/v2/namespaces
endpoint of the admin {@inject: rest:REST:/} APInamespaces
method of the PulsarAdmin
object in the Java APIYou can create new namespaces under a given tenant.
Use the create
subcommand and specify the namespace by name:
$ pulsar-admin namespaces create test-tenant/test-namespace
{@inject: endpoint|PUT|/admin/v2/namespaces/:tenant/:namespace|operation/createNamespace?version=[[pulsar:version_number]]}
admin.namespaces().createNamespace(namespace);
You can fetch the current policies associated with a namespace at any time.
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 }
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace|operation/getPolicies?version=[[pulsar:version_number]]}
admin.namespaces().getPolicies(namespace);
You can list all namespaces within a given Pulsar tenant.
Use the list
subcommand and specify the tenant:
$ pulsar-admin namespaces list test-tenant test-tenant/ns1 test-tenant/ns2
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant|operation/getTenantNamespaces?version=[[pulsar:version_number]]}
admin.namespaces().getNamespaces(tenant);
You can delete existing namespaces from a tenant.
Use the delete
subcommand and specify the namespace:
$ pulsar-admin namespaces delete test-tenant/ns1
{@inject: endpoint|DELETE|/admin/v2/namespaces/:tenant/:namespace|operation/deleteNamespace?version=[[pulsar:version_number]]}
admin.namespaces().deleteNamespace(namespace);
You can set replication clusters for a namespace to enable Pulsar to internally replicate the published messages from one colocation facility to another.
$ pulsar-admin namespaces set-clusters test-tenant/ns1 \ --clusters cl1
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/replication|operation/setNamespaceReplicationClusters?version=[[pulsar:version_number]]}
admin.namespaces().setNamespaceReplicationClusters(namespace, clusters);
You can get the list of replication clusters for a given namespace.
$ pulsar-admin namespaces get-clusters test-tenant/cl1/ns1
cl2
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/replication|operation/getNamespaceReplicationClusters?version=[[pulsar:version_number]]}
admin.namespaces().getNamespaceReplicationClusters(namespace)
Backlog quota helps the broker to restrict bandwidth/storage of a namespace once it reaches a certain threshold limit. Admin can set the limit and take corresponding action after the limit is reached.
producer_request_hold: broker holds but not persists produce request payload
producer_exception: broker disconnects with the client by giving an exception
consumer_backlog_eviction: broker starts discarding backlog messages
Backlog quota restriction can be taken care by defining restriction of backlog-quota-type: destination_storage.
$ pulsar-admin namespaces set-backlog-quota --limit 10G --limitTime 36000 --policy producer_request_hold test-tenant/ns1
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/backlogQuota|operation/setBacklogQuota?version=[[pulsar:version_number]]}
admin.namespaces().setBacklogQuota(namespace, new BacklogQuota(limit, limitTime, policy))
You can get a configured backlog quota for a given namespace.
$ pulsar-admin namespaces get-backlog-quotas test-tenant/ns1
{ "destination_storage": { "limit": 10, "policy": "producer_request_hold" } }
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/backlogQuotaMap|operation/getBacklogQuotaMap?version=[[pulsar:version_number]]}
admin.namespaces().getBacklogQuotaMap(namespace);
You can remove backlog quota policies for a given namespace.
$ pulsar-admin namespaces remove-backlog-quota test-tenant/ns1
{@inject: endpoint|DELETE|/admin/v2/namespaces/:tenant/:namespace/backlogQuota|operation/removeBacklogQuota?version=[[pulsar:version_number]]}
admin.namespaces().removeBacklogQuota(namespace, backlogQuotaType)
Persistence policies allow users 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
$ 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
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/persistence|operation/setPersistence?version=[[pulsar:version_number]]}
admin.namespaces().setPersistence(namespace,new PersistencePolicies(bookkeeperEnsemble, bookkeeperWriteQuorum,bookkeeperAckQuorum,managedLedgerMaxMarkDeleteRate))
You can get the configured persistence policies of a given namespace.
$ pulsar-admin namespaces get-persistence test-tenant/ns1
{ "bookkeeperEnsemble": 3, "bookkeeperWriteQuorum": 2, "bookkeeperAckQuorum": 2, "managedLedgerMaxMarkDeleteRate": 0 }
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/persistence|operation/getPersistence?version=[[pulsar:version_number]]}
admin.namespaces().getPersistence(namespace)
The namespace bundle is a virtual group of topics which belong to the same namespace. If the broker gets overloaded with the number of bundles, this command can help unload a bundle from that broker, so it can be served by some other less-loaded brokers. The namespace bundle ID ranges from 0x00000000 to 0xffffffff.
$ pulsar-admin namespaces unload --bundle 0x00000000_0xffffffff test-tenant/ns1
{@inject: endpoint|PUT|/admin/v2/namespaces/:tenant/:namespace/{bundle}/unload|operation/unloadNamespaceBundle?version=[[pulsar:version_number]]}
admin.namespaces().unloadNamespaceBundle(namespace, bundle)
One namespace bundle can contain multiple topics but can be served by only one broker. If a single bundle is creating an excessive load on a broker, an admin can split the bundle using the command below, permitting one or more of the new bundles to be unloaded, thus balancing the load across the brokers.
$ pulsar-admin namespaces split-bundle --bundle 0x00000000_0xffffffff test-tenant/ns1
{@inject: endpoint|PUT|/admin/v2/namespaces/:tenant/:namespace/{bundle}/split|operation/splitNamespaceBundle?version=[[pulsar:version_number]]}
admin.namespaces().splitNamespaceBundle(namespace, bundle)
You can configure the time to live (in seconds) duration for messages. In the example below, the message-ttl is set as 100s.
$ pulsar-admin namespaces set-message-ttl --messageTTL 100 test-tenant/ns1
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/messageTTL|operation/setNamespaceMessageTTL?version=[[pulsar:version_number]]}
admin.namespaces().setNamespaceMessageTTL(namespace, messageTTL)
When the message-ttl for a namespace is set, you can use the command below to get the configured value. This example comtinues the example of the command set message-ttl
, so the returned value is 100(s).
$ pulsar-admin namespaces get-message-ttl test-tenant/ns1
100
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/messageTTL|operation/getNamespaceMessageTTL?version=[[pulsar:version_number]]}
100
admin.namespaces().getNamespaceMessageTTL(namespace)
100
Remove a message TTL of the configured namespace.
$ pulsar-admin namespaces remove-message-ttl test-tenant/ns1
{@inject: endpoint|DELETE|/admin/v2/namespaces/:tenant/:namespace/messageTTL|operation/removeNamespaceMessageTTL?version=[[pulsar:version_number]]}
admin.namespaces().removeNamespaceMessageTTL(namespace)
It clears all message backlog for all the topics that belong to a specific namespace. You can also clear backlog for a specific subscription as well.
$ pulsar-admin namespaces clear-backlog --sub my-subscription test-tenant/ns1
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/clearBacklog|operation/clearNamespaceBacklogForSubscription?version=[[pulsar:version_number]]}
admin.namespaces().clearNamespaceBacklogForSubscription(namespace, subscription)
It clears all message backlog for all the topics that belong to a specific NamespaceBundle. You can also clear backlog for a specific subscription as well.
$ pulsar-admin namespaces clear-backlog --bundle 0x00000000_0xffffffff --sub my-subscription test-tenant/ns1
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/{bundle}/clearBacklog|operation?version=[[pulsar:version_number]]/clearNamespaceBundleBacklogForSubscription}
admin.namespaces().clearNamespaceBundleBacklogForSubscription(namespace, bundle, subscription)
Each namespace contains multiple topics and the retention size (storage size) of each topic should not exceed a specific threshold or it should be stored for a certain period. This command helps configure the retention size and time of topics in a given namespace.
$ pulsar-admin namespaces set-retention --size 100 --time 10 test-tenant/ns1
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/retention|operation/setRetention?version=[[pulsar:version_number]]}
admin.namespaces().setRetention(namespace, new RetentionPolicies(retentionTimeInMin, retentionSizeInMB))
It shows retention information of a given namespace.
$ pulsar-admin namespaces get-retention test-tenant/ns1
{ "retentionTimeInMinutes": 10, "retentionSizeInMB": 100 }
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/retention|operation/getRetention?version=[[pulsar:version_number]]}
admin.namespaces().getRetention(namespace)
It sets message dispatch rate for all the topics under a given namespace. The dispatch rate can be restricted by the number of messages per X seconds (msg-dispatch-rate
) or by the 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.
Note
If neither
clusterDispatchRate
nortopicDispatchRate
is configured, dispatch throttling is disabled.If
topicDispatchRate
is not configured,clusterDispatchRate
takes effect.If
topicDispatchRate
is configured,topicDispatchRate
takes effect.
$ pulsar-admin namespaces set-dispatch-rate test-tenant/ns1 \ --msg-dispatch-rate 1000 \ --byte-dispatch-rate 1048576 \ --dispatch-rate-period 1
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/dispatchRate|operation/setDispatchRate?version=[[pulsar:version_number]]}
admin.namespaces().setDispatchRate(namespace, new DispatchRate(1000, 1048576, 1))
It shows configured message-rate for the namespace (topics under this namespace can dispatch this many messages per second)
$ pulsar-admin namespaces get-dispatch-rate test-tenant/ns1
{ "dispatchThrottlingRatePerTopicInMsg" : 1000, "dispatchThrottlingRatePerTopicInByte" : 1048576, "ratePeriodInSecond" : 1 }
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/dispatchRate|operation/getDispatchRate?version=[[pulsar:version_number]]}
admin.namespaces().getDispatchRate(namespace)
It sets message dispatch rate for all the subscription of topics under a given namespace. The dispatch rate can be restricted by the number of messages per X seconds (msg-dispatch-rate
) or by the 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.
$ pulsar-admin namespaces set-subscription-dispatch-rate test-tenant/ns1 \ --msg-dispatch-rate 1000 \ --byte-dispatch-rate 1048576 \ --dispatch-rate-period 1
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/subscriptionDispatchRate|operation/setDispatchRate?version=[[pulsar:version_number]]}
admin.namespaces().setSubscriptionDispatchRate(namespace, new DispatchRate(1000, 1048576, 1))
It shows configured message-rate for the namespace (topics under this namespace can dispatch this many messages per second)
$ pulsar-admin namespaces get-subscription-dispatch-rate test-tenant/ns1
{ "dispatchThrottlingRatePerTopicInMsg" : 1000, "dispatchThrottlingRatePerTopicInByte" : 1048576, "ratePeriodInSecond" : 1 }
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/subscriptionDispatchRate|operation/getDispatchRate?version=[[pulsar:version_number]]}
admin.namespaces().getSubscriptionDispatchRate(namespace)
It sets message dispatch rate for all the replicator between replication clusters under a given namespace. The dispatch rate can be restricted by the number of messages per X seconds (msg-dispatch-rate
) or by the 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.
$ pulsar-admin namespaces set-replicator-dispatch-rate test-tenant/ns1 \ --msg-dispatch-rate 1000 \ --byte-dispatch-rate 1048576 \ --dispatch-rate-period 1
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/replicatorDispatchRate|operation/setDispatchRate?version=[[pulsar:version_number]]}
admin.namespaces().setReplicatorDispatchRate(namespace, new DispatchRate(1000, 1048576, 1))
It shows configured message-rate for the namespace (topics under this namespace can dispatch this many messages per second)
$ pulsar-admin namespaces get-replicator-dispatch-rate test-tenant/ns1
{ "dispatchThrottlingRatePerTopicInMsg" : 1000, "dispatchThrottlingRatePerTopicInByte" : 1048576, "ratePeriodInSecond" : 1 }
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/replicatorDispatchRate|operation/getDispatchRate?version=[[pulsar:version_number]]}
admin.namespaces().getReplicatorDispatchRate(namespace)
It shows configured deduplicationSnapshotInterval
for a namespace (Each topic under the namespace will take a deduplication snapshot according to this interval)
$ pulsar-admin namespaces get-deduplication-snapshot-interval test-tenant/ns1
{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/deduplicationSnapshotInterval?version=[[pulsar:version_number]]}
admin.namespaces().getDeduplicationSnapshotInterval(namespace)
Set configured deduplicationSnapshotInterval
for a namespace. Each topic under the namespace will take a deduplication snapshot according to this interval. brokerDeduplicationEnabled
must be set to true
for this property to take effect.
$ pulsar-admin namespaces set-deduplication-snapshot-interval test-tenant/ns1 --interval 1000
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/deduplicationSnapshotInterval?version=[[pulsar:version_number]]}
{ "interval": 1000 }
admin.namespaces().setDeduplicationSnapshotInterval(namespace, 1000)
Remove configured deduplicationSnapshotInterval
of a namespace (Each topic under the namespace will take a deduplication snapshot according to this interval)
$ pulsar-admin namespaces remove-deduplication-snapshot-interval test-tenant/ns1
{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/deduplicationSnapshotInterval?version=[[pulsar:version_number]]}
admin.namespaces().removeDeduplicationSnapshotInterval(namespace)
You can use the Pulsar isolation policy to allocate resources (broker and bookie) for a namespace.
You can unload a namespace, or a namespace bundle, from the Pulsar broker that is currently responsible for it.
Use the unload
subcommand of the namespaces
command.
$ pulsar-admin namespaces unload my-tenant/my-ns
{@inject: endpoint|PUT|/admin/v2/namespaces/:tenant/:namespace/unload|operation/unloadNamespace?version=[[pulsar:version_number]]}
admin.namespaces().unload(namespace)