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

Introduction to Pulsarctl

head img
sharetwitterlinkedIn

Learn how to use Pulsar Go Admin API and use Pulsarctl in the command line.

We're excited to announce that StreamNative open sourced Pulsarctl: an awesome admin tool in Apache Pulsar.

Apache Pulsar is a distributed pub-sub messaging system designed for scalability, flexibility, and no data loss, and it is a top-level project of the Apache Software Foundation. Currently, Apache Pulsar enjoys rapid growth and development. To make it better and more user-friendly, we’ve designed Pulsarctl for Go users.

Introduction to Pulsarctl

Pulsarctl is an alternative tool of pulsar-admin, used to manage clients in Apache Pulsar. Pulsarctl is written in Go, based on Pulsar REST API. It provides Go developer with API interface and user-friendly commands, making it easier to interact with Pulsar Broker.

Compared with pulsar-admin, Pulsarctl is more user-friendly: Pulsarctl requires less dependencies to use commands, and provides more comprehensive description and usage for commands. With Pulsarctl, users can find and resolve issues faster when errors occur.

You can use Pulsarctl in the following two ways:

  1. Use it in Go project and interact with Pulsar brokers. The Admin API is developed by Go.
  2. Use it as pulsar-admin in the command line.

How to use Pulsar Go Admin API

Pulsarctl provides Admin API based on Go, and make it easier to interact with Pulsar Broker. Pulsarctl Admin API provides the following interface.

// Client provides a client to the Pulsar Restful API
	type Client interface {
		Clusters() Clusters
		Functions() Functions
		Tenants() Tenants
		Topics() Topics
		Subscriptions() Subscriptions
		Sources() Sources
		Sinks() Sinks
		Namespaces() Namespaces
		Schemas() Schema
		Brokers() Brokers
		BrokerStats() BrokerStats
	}

Note: For more information on Admin API interfaces, refer to https://godoc.org/github.com/streamnative/pulsarctl.

The following example demonstrates how to use Pulsarctl 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)

How to use Pulsarctl in the command line

Pulsarctl commands provide comprehensive description and usage.

Take create topic as an example, the following is the output of create topic.

pulsarctl-commands-doc

Pulsarctl unifies partitioned-topics and topics commands, and delivers clear and detailed output.

topic-list-show

  • In Pulsarctl, all commands related to subscription is grouped in subscription commands. In pulsar-admin, all commands related to subscription is used as subcommands of topics, which is not convenient to use.

sub-commands-list

  • Pulsarctl improves the usage of special characters. In pulsar-admin, users are required to enter json-string in shell, which complicates the usage. Take functions putstate as an example, the following table lists the output comparison between pulsar-admin and pulsarctl.
putstate pulsar-admin pulsarctl
stringValue bin/pulsar-admin functions putstate --tenant test --namespace test-namespace --name word_count --state "{"key":"pulsar-1", "stringValue":"hello"}" ./pulsarctl functions putstate --tenant public --namespace default --name word_count_1 pulsar-1 - hello
byteValue bin/pulsar-admin functions putstate --tenant test --namespace test-namespace --name word_count --state "{"key":"pulsar-1", "byteValue":"README.md"}" ./pulsarctl functions putstate --tenant public --namespace default --name word_count_1 pulsar = README.md

The following examples illustrate differences in using pulsar-admin and pulsarctl.

Query all commands

pulsarctl-commands-list

Create non-partitioned topic

pulsarctl-create-non-partitioned-topic

Create partitioned topic

pulsarctl-create-partitioned-topic

To query topics with pulsar-admin, you have to separate partitioned topic and non-partitioned topic.

Query non-partitioned topic

pulsar-admin-list-non-partitioned-topics

Query partitioned topics

pulsar-admin-list-partitioned-topics

Query topics with Pulsarctl

pulsarctl-list-topics

Contribute to Pulsarctl

If you have any issues with Pulsarctl, feel free to contact us. Any of your contributions to code or documentation is highly appreciated. The more you give, the more you get. In the contribution journey, you will learn more about Pulsarctl and Apache Pulsar.