Introduction to Pulsarctl

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.

<script>
// 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
    }
<script> 

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.

<script>
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)
<script> 

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 unifies partitioned-topics and topics commands, and delivers clear and detailed output.

• 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.

• 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.

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

Query all commands

Create non-partitioned topic

Create partitioned topic

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

Query non-partitioned topic

Query partitioned topics

Query topics with Pulsarctl

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.

• Github: https://github.com/streamnative/pulsarctl
• Contribution Guide: https://github.com/streamnative/pulsarctl/blob/master/CONTRIBUTING.md
• Developer Guide: https://github.com/streamnative/pulsarctl/blob/master/docs/en/developer-guide.md

‍