pulsar-admin - Apache Pulsar

The pulsar-admin tool is the administrative CLI for Apache Pulsar. It provides commands to manage and monitor all aspects of a Pulsar cluster.

Usage

pulsar-admin [options] [command] [command options]

Global Options

Option	Description
`--admin-url`	Admin Service URL to connect to
`--auth-plugin`	Authentication plugin class name
`--auth-params`	Authentication parameters in key:value format
`--request-timeout`	Request timeout in seconds (default: 300)
`--tls-allow-insecure`	Allow insecure TLS connections
`--tls-trust-cert-path`	Path to TLS trust certificates
`--tls-enable-hostname-verification`	Enable TLS hostname verification
`--tls-provider`	TLS provider (OPENSSL or JDK)
`-h, --help`	Display help information
`-v`	Display version information

Available Commands

Cluster Management

clusters

Manage Pulsar clusters.

pulsar-admin clusters list

Subcommands:

list - List all clusters
get - Get cluster configuration
create - Create a new cluster
update - Update cluster configuration
delete - Delete a cluster
update-peer-clusters - Update peer cluster list
get-peer-clusters - Get peer clusters
get-failure-domain - Get failure domain configuration
create-failure-domain - Create failure domain
update-failure-domain - Update failure domain
delete-failure-domain - Delete failure domain
list-failure-domains - List all failure domains

Tenant Management

tenants

Manage Pulsar tenants (formerly called properties).

pulsar-admin tenants list

Subcommands:

list - List all tenants
get - Get tenant configuration
create - Create a new tenant
update - Update tenant configuration
delete - Delete a tenant

Namespace Management

namespaces

Manage Pulsar namespaces.

pulsar-admin namespaces list my-tenant

Subcommands:

list - List namespaces for a tenant
topics - Get list of topics in a namespace
policies - Get namespace policies
create - Create a namespace
delete - Delete a namespace
set-retention - Set retention policy
get-retention - Get retention policy
set-message-ttl - Set message TTL
get-message-ttl - Get message TTL
set-backlog-quota - Set backlog quota
get-backlog-quotas - Get backlog quotas
set-persistence - Set persistence policies
get-persistence - Get persistence policies
set-replication-clusters - Set replication clusters
get-replication-clusters - Get replication clusters
set-deduplication - Enable/disable deduplication
set-auto-topic-creation - Configure auto topic creation
set-auto-subscription-creation - Configure auto subscription creation
unload - Unload a namespace
clear-backlog - Clear backlog

Topic Management

topics

Manage Pulsar topics (persistent and non-persistent).

pulsar-admin topics list my-tenant/my-namespace

Subcommands:

list - List all topics in namespace
list-partitioned-topics - List partitioned topics
permissions - Get topic permissions
grant-permission - Grant permission to a role
revoke-permission - Revoke permission from a role
lookup - Lookup topic owner broker
partitioned-lookup - Lookup partitioned topic
bundle-range - Get bundle range of a topic
delete - Delete a topic
unload - Unload a topic
subscriptions - List subscriptions
unsubscribe - Delete a subscription
create-subscription - Create a subscription
stats - Get topic stats
stats-internal - Get internal stats
info-internal - Get internal metadata info
partitioned-stats - Get partitioned topic stats
skip - Skip messages for a subscription
clear-backlog - Clear backlog for a subscription
expire-messages - Expire messages
expire-messages-all-subscriptions - Expire messages for all subscriptions
create-partitioned-topic - Create partitioned topic
create - Create non-partitioned topic
update-partitioned-topic - Update partitioned topic
get-partitioned-topic-metadata - Get partitioned topic metadata
delete-partitioned-topic - Delete partitioned topic
peek-messages - Peek messages
examine-messages - Examine messages
get-message-by-id - Get message by ID
reset-cursor - Reset subscription cursor
terminate - Terminate topic
compact - Trigger compaction
compaction-status - Get compaction status
offload - Trigger offload
offload-status - Get offload status
last-message-id - Get last message ID
get-backlog-quotas - Get backlog quotas
set-backlog-quota - Set backlog quota
get-message-ttl - Get message TTL
set-message-ttl - Set message TTL
get-retention - Get retention policy
set-retention - Set retention policy

Broker Management

brokers

Manage Pulsar brokers.

pulsar-admin brokers list my-cluster

Subcommands:

list - List active brokers
leader-broker - Get leader broker
namespaces - List namespaces owned by broker
update-dynamic-config - Update dynamic configuration
get-all-dynamic-config - Get all dynamic configs
list-dynamic-config - List dynamic config names
get-internal-config - Get internal configuration
get-runtime-config - Get runtime configuration
healthcheck - Perform health check

broker-stats

Get broker statistics.

pulsar-admin broker-stats monitoring-metrics

Schema Management

schemas

Manage topic schemas.

pulsar-admin schemas get \
  persistent://my-tenant/my-namespace/my-topic

Subcommands:

get - Get latest schema
get-all-versions - Get all schema versions
delete - Delete schema
upload - Upload a new schema
extract - Extract schema definition
test-compatibility - Test schema compatibility

Functions Management

functions

Manage Pulsar Functions.

pulsar-admin functions create \
  --tenant my-tenant \
  --namespace my-namespace \
  --name my-function \
  --jar my-function.jar \
  --classname org.example.MyFunction \
  --inputs input-topic \
  --output output-topic

Subcommands:

create - Create a function
update - Update a function
delete - Delete a function
get - Get function info
list - List all functions
status - Get function status
stats - Get function stats
restart - Restart function instance
stop - Stop function instance
start - Start function instance
trigger - Trigger function
upload - Upload function package
download - Download function package
querystate - Query function state
putstate - Put function state

sources

Manage Pulsar IO sources.

pulsar-admin sources create \
  --tenant my-tenant \
  --namespace my-namespace \
  --name my-source \
  --archive pulsar-io-kafka-3.0.0.nar \
  --destination-topic-name output-topic

sinks

Manage Pulsar IO sinks.

pulsar-admin sinks create \
  --tenant my-tenant \
  --namespace my-namespace \
  --name my-sink \
  --archive pulsar-io-jdbc-3.0.0.nar \
  --inputs input-topic

Resource Management

resourcegroups

Manage resource groups.

pulsar-admin resourcegroups create my-rg

resource-quotas

Manage resource quotas for namespaces.

pulsar-admin resource-quotas get

BookKeeper Management

bookies

Manage BookKeeper bookies.

pulsar-admin bookies list-bookies

Subcommands:

list-bookies - List all bookies
racks-placement - Get rack placement info
get-bookie-info - Get bookie info
delete-bookie-rack - Delete bookie rack info
set-bookie-rack - Set bookie rack info

Namespace Isolation

ns-isolation-policy

Manage namespace isolation policies.

pulsar-admin ns-isolation-policy set \
  --cluster my-cluster \
  --policy my-policy \
  --namespaces "my-tenant/my-ns.*" \
  --primary "broker1.*"

Transaction Management

transactions

Manage transactions.

pulsar-admin transactions coordinator-stats

Package Management

packages

Manage function/connector packages.

pulsar-admin packages upload \
  --path function://public/default/[email protected] \
  --jar my-function.jar

Proxy Statistics

proxy-stats

Get proxy statistics.

pulsar-admin proxy-stats connections

Examples

Complete Workflow: Create and Configure a Topic

# Create a tenant
pulsar-admin tenants create my-company \
  --admin-roles admin \
  --allowed-clusters cluster1

# Create a namespace
pulsar-admin namespaces create my-company/applications

# Configure namespace retention
pulsar-admin namespaces set-retention my-company/applications \
  --size 100G \
  --time 7d

# Set message TTL
pulsar-admin namespaces set-message-ttl my-company/applications \
  --messageTTL 86400

# Create a partitioned topic
pulsar-admin topics create-partitioned-topic \
  persistent://my-company/applications/events \
  --partitions 4

# Grant permissions
pulsar-admin topics grant-permission \
  persistent://my-company/applications/events \
  --role app-role \
  --actions produce,consume

# Get topic stats
pulsar-admin topics stats \
  persistent://my-company/applications/events

Monitor and Troubleshoot

# Check broker health
pulsar-admin brokers healthcheck

# Get topic internal stats
pulsar-admin topics stats-internal \
  persistent://my-company/applications/events

# List subscriptions
pulsar-admin topics subscriptions \
  persistent://my-company/applications/events

# Check subscription backlog
pulsar-admin topics stats \
  persistent://my-company/applications/events

# Clear backlog for a subscription
pulsar-admin topics clear-backlog \
  persistent://my-company/applications/events \
  --subscription my-sub

# Peek messages
pulsar-admin topics peek-messages \
  persistent://my-company/applications/events \
  --subscription my-sub \
  --count 10

Configuration

Create a configuration file at conf/client.conf:

webServiceUrl=http://localhost:8080
authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
authParams=token:eyJhbGciOiJIUzI1NiJ9...
tlsAllowInsecureConnection=false
tlsEnableHostnameVerification=true
tlsTrustCertsFilePath=/path/to/ca.cert.pem

Use the configuration:

pulsar-admin --admin-url http://pulsar.example.com:8080 \
  --auth-plugin org.apache.pulsar.client.impl.auth.AuthenticationToken \
  --auth-params token:eyJhbGciOiJIUzI1NiJ9... \
  tenants list

pulsar-client - Produce and consume messages
pulsar - Run Pulsar components

REST API

CLI Tools

​Usage

​Global Options

​Available Commands

​Cluster Management

​clusters

​Tenant Management

​tenants

​Namespace Management

​namespaces

​Topic Management

​topics

​Broker Management

​brokers

​broker-stats

​Schema Management

​schemas

​Functions Management

​functions

​sources

​sinks

​Resource Management

​resourcegroups

​resource-quotas

​BookKeeper Management

​bookies

​Namespace Isolation

​ns-isolation-policy

​Transaction Management

​transactions

​Package Management

​packages

​Proxy Statistics

​proxy-stats

​Examples

​Complete Workflow: Create and Configure a Topic

​Monitor and Troubleshoot

​Configuration

​Related Commands

Build docs developers (and LLMs) love

Usage

Global Options

Available Commands

Cluster Management

clusters

Tenant Management

tenants

Namespace Management

namespaces

Topic Management

topics

Broker Management

brokers

broker-stats

Schema Management

schemas

Functions Management

functions

sources

sinks

Resource Management

resourcegroups

resource-quotas

BookKeeper Management

bookies

Namespace Isolation

ns-isolation-policy

Transaction Management

transactions

Package Management

packages

Proxy Statistics

proxy-stats

Examples

Complete Workflow: Create and Configure a Topic

Monitor and Troubleshoot

Configuration

Related Commands