Announcing: The Pulsar PMC Published The 2020 Apache Pulsar User Survey Report!

Overview
Get started
Install and upgrade
Configure
Secure
Manage and monitor
Overview
Metrics
Pulsar Manager
pulsarctl
Overview
Use
Tutorial
Connect
Process
Release notes

Use

You can use pulsarctl in the following methods:

  • Command-line tool: use pulsarctl as an alternative of pulsar-admin in command-line tool. For more information, see here.

  • Go admin API: use pulsarctl in Go project and interact with Pulsar brokers. For more information, see here.

Command-line tool

Syntax

Use the following syntax to run pulsarctl commands from your terminal window.

pulsarctl [resource] [command] [name] [flags]

Tip

If you need help, run pulsarctl help command.

resource

resource specifies the operation performed on an object.

This argument is required.

resource Syntax Description
clusters pulsarctl clusters [command] [name] [flags] Operations on clusters
completion pulsarctl completion [command] [name] [flags] Operations on pulsarctl auto-completion script
functions pulsarctl functions [command] [name] [flags] Interface for managing Pulsar Functions
functions-worker pulsarctl functions-worker [command] [name] [flags] Collect function-worker statistics
namespaces pulsarctl namespaces [command] [name] [flags] Operations on namespaces
schemas pulsarctl schemas [command] [name] [flags] Operations on schemas
sinks pulsarctl sinks [command] [name] [flags] Operations on sinks
sources pulsarctl sources [command] [name] [flags] Operations on sources
tenants pulsarctl tenants [command] [name] [flags] Operations on tenants
topics pulsarctl topics [command] [name] [flags] Operations on topics
brokers pulsarctl brokers [command] [name] [flags] Operations on brokers
broker-stats pulsarctl broker-stats [command] [name] [flags] Collect broker statistics
subscriptions pulsarctl subscriptions [command] [name] [flags] Operations on subscriptions
resource-quotas pulsarctl resource-quotas [command] [name] [flags] Operations on resource quotas
ns-isolation-policy pulsarctl ns-isolation-policy [command] [name] [flags] Operations on namespace isolation policy
token pulsarctl token [command] [name] [flags] Operations on token
context pulsarctl context [command] [name] [flags] Operations on context
bookkeeper pulsarctl bookkeeper [command] [name] [flags] Operations on BookKeeper

command

command specifies the operation to be performed on one or more resources.

This argument is required.

Example

create, delete, get, list, and update are command.

pulsarctl clusters create (cluster-name)
pulsarctl clusters delete (cluster-name)
pulsarctl clusters get (cluster-name)
pulsarctl clusters list
pulsarctl clusters update --url http://example:8080 (cluster-name)

name

name specifies the name of the resource.

This argument is required.

Note

name is case-sensitive.

Example

This example creates a function named function-test.

pulsarctl functions create
--tenant public
--namespace default
--name function-test
--inputs test-input-topic
--output persistent://public/default/test-output-topic
--classname org.apache.pulsar.functions.api.examples.ExclamationFunction
--jar /examples/api-examples.jar

flags

flags specifies the properties for the resource.

This argument is optional.

Note

flags overrides the default values and corresponding environment variables.

Example

This example creates a sink named sink-test.

tenant, namespace, name, inputs, archive, sink-config-file, and parallelism are flags.

pulsarctl sink create
--tenant public
--namespace default
--name sink-test
--inputs test-jdbc
--archive connectors/pulsar-io-jdbc-2.4.0.nar
--sink-config-file connectors/mysql-jdbc-sink.yaml
--parallelism 1

Example

The following examples show how to use pulsarctl to perform operations on tenants.

pulsarctl tenants create tenant-technical-writer
// Create a new tenant named tenant-technical-writer.

pulsarctl tenants list
// List all existing tenants.

pulsarctl tenants get tenant-technical-writer
// Get the configuration of the tenant-technical-writer.

pulsarctl tenants update tenant-technical-writer
// Clear the tenant configuration of the tenant-technical-writer.

pulsarctl tenants update --admin-roles admin-role-writer tenant-technical-writer
// Update the admin roles for the tenant-technical-writer.

pulsarctl tenants update --allowed-clusters cluster-writer tenant-technical-writer
// Update the allowed cluster list for the tenant-technical-writer.

pulsarctl tenants delete tenant-technical-writer
// Delete the tenant-technical-writer.

Comparison

pulsarctl is an alternative tool of pulsar-admin. However, compared with pulsar-admin, pulsarctl has the following advantages.

Add more features

pulsarctl adds more features, for example, it supports performing operations on context while pulsar-admin does not.

Simplify most commands

pulsarctl simplifies the usage for most commands.

Example 1 - functions

For special characters in sub-command (putstate) of function:

putstate pulsarctl pulsar-admin
json-string is not needed. json-string must be provided.
stringValue ./pulsarctl functions putstate --tenant public --namespace default --name word_count_1 pulsar-1 - hello bin/pulsar-admin functions putstate --tenant test --namespace test-namespace --name word_count --state "{\"key\":\"pulsar-1\", \"stringValue\":\"hello\"}"
byteValue ./pulsarctl functions putstate --tenant public --namespace default --name word_count_1 pulsar = README.md bin/pulsar-admin functions putstate --tenant test --namespace test-namespace --name word_count --state "{\"key\":\"pulsar-1\", \"byteValue\":\"README.md\"}"

Example 2 - topics

  • Create topics

    Creating partitioned topics in pulsarctl is much simpler than that in pulsar-admin.

    Operation pulsarctl pulsar-admin
    Create non-partitioned topics pulsarctl topics create (topic-name) 0 pulsar-admin topics create (topic-name)
    Create partitioned topics pulsarctl topics create (topic-name) (partition-num) pulsar-admin topics create-partitioned-topic (topic-name) -p (partition-num)
  • Get a list of topics

    Getting a list of all topics (partitioned and non-partitioned) in pulsarctl is much simpler than that in pulsar-admin.

    pulsarctl pulsar-admin
    Get a list of all topics (partitioned and non-partitioned). You can not get a list of all topics (partitioned and non-partitioned) using one command. Instead, you need to use two commands to get a list of partitioned topics and a list of non-partitioned topics separately.
    pulsarctl topics list public/default - Get a list of partitioned topics:
    pulsar/admin topics list-partitioned-topics public/default

    - Get a list of non-partitioned topics:
    pulsar/admin topics list public/default

Example 3 - subscriptions

pulsarctl moves subscription sub-commands from topic command and treats subscription as an independent command, which makes it easier and more convenient to use.

While in pulsar-admin, subscription commands are sub-commands of topic command.

pulsarctl pulsar-admin
pulsarctl subscriptions create pulsar-admin topics create-subscription
pulsarctl subscriptions delete pulsar-admin topics unsubscribe
pulsarctl subscriptions expire pulsar-admin topics expire-messages
pulsarctl subscriptions list pulsar-admin topics subscriptions
pulsarctl subscriptions peek pulsar-admin topics peek-messages
pulsarctl subscriptions seek pulsar-admin topics reset-cursor
pulsarctl subscriptions skip pulsar-admin topics skip

Increase processing speed

pulsarctl goes more quickly than pulsar-admin when querying all commands.

Go admin API

pulsarctl provides admin API based on Go, making it easier to interact with Pulsar Broker.

Interface

For all interfaces provided by pulsarctl Go admin API, see here.

Example

This example demonstrates how to get a list of standalone clusters using pulsarctl Go admin API.

config := &pulsar.Config{
	WebServiceURL: “http://localhost:8080”,
	HTTPClient:    http.DefaultClient,

	// If the server enable the TLSAuth
	// Auth: auth.NewAuthenticationTLS()

	// If the server enable the TokenAuth
	// TokenAuth: auth.NewAuthenticationToken()
}

// the default NewPulsarClient will use v2 APIs. If you need to request other version APIs,
// you can specified the API version like this:
// admin := cmdutils.NewPulsarClientWithAPIVersion(pulsar.V2)
admin, err := pulsar.New(config)
if err != nil {
	// handle the err
	return
}

// more APIs, you can find them in the pkg/pulsar/admin.go
// You can find all the method in the pkg/pulsar
clusters, err := admin.Clusters().List()
if err != nil {
	// handle the error
}

// handle the result
fmt.Println(clusters)