Pulsar Shell

Pulsar shell is a fast and flexible shell for Pulsar cluster management, messaging, and more. It’s great for quickly switching between different clusters, and can modify cluster or tenant configurations in an instant.

Use case

  • Administration: find all the Admin API features under the admin command.
  • Client: find all the pulsar-client features under the client command.

Install Pulsar Shell

Download the tarball from the download page and extract it.

  1. wget https://archive.apache.org/dist/pulsar/pulsar-3.0.1/apache-pulsar-shell-3.0.1-bin.tar.gz
  2. tar xzvf apache-pulsar-shell-3.0.1-bin.tar.gz
  3. cd apache-pulsar-shell-3.0.1-bin.tar.gz

Now you can enter Pulsar shell’s interactive mode:

  1. ./bin/pulsar-shell
  2. Welcome to Pulsar shell!
  3.   Service URL: pulsar://localhost:6650/
  4.   Admin URL: http://localhost:8080/
  6. Type help to get started or try the autocompletion (TAB button).
  7. Type exit or quit to end the shell session.
  9. default(localhost)>

Connect to your cluster

By default, the shell tries to connect to a local Pulsar instance. To connect to a different cluster, you have to register the cluster with Pulsar shell. You can do this in a few different ways depending on where your config file is located:

Pulsar Shell - 图1note

The configuration file must be a valid client.conf file, the same one you use for pulsar-admin, pulsar-client and other client tools.

  • Remote URL
  • File
  • Inline

The --url value must point to a valid remote file.

  1. default(localhost)> config create --url https://<url_to_my_client.conf> mycluster

If the file is on your local machine, use the --file option.

  1. default(localhost)> config create --file ./my-cluster-my-client.conf mycluster

You can encode the content of the config to base64 and specify it with the --value option.

  1. default(localhost)> config create --value "base64:<client.conf_base64_encoded>" mycluster

Once you’ve configured your cluster, set it as current:

  1. default(localhost)> config use mycluster
  2. Welcome to Pulsar shell!
  3.   Service URL: pulsar+ssl://mycluster:6651/
  4.   Admin URL: https://mycluster:8443/
  6. Type help to get started or try the autocompletion (TAB button).
  7. Type exit or quit to end the shell session.
  9. my-cluster(mycluster)>

Run commands sequentially

To run a bunch of admin commands sequentially, you can use Pulsar shell’s non-interactive mode. For example, to set up a new tenant with policies, you would normally need to run multiple pulsar-admin commands.

Let’s say you want to create a new tenant new-tenant with a namespace new-namespace in it. There are multiple ways to do this with Pulsar shell non-interactive mode:

  • Single command
  • File
  • Unix pipe

Specify a multi-line command with the -e option.

  1. ./bin/pulsar-shell -e "
  2. config use my-cluster
  3. admin tenants create new-tenant
  4. admin namespaces create new-tenant/new-namespace
  5. " --fail-on-error

Specify a file command with the -f option.

  1. echo "
  2. # First use my-cluster config
  3. config use my-cluster
  4. # Now it creates a new tenant
  5. admin tenants create new-tenant
  6. # And then it creates a new namespace inside the tenant
  7. admin namespaces create new-tenant/new-namespace
  8. " > setup-shell.txt
  10. ./bin/pulsar-shell -f ./setup-shell.txt --fail-on-error

Make the shell read from the standard input - option.

  2. echo "
  3. # First use my-cluster config
  4. config use my-cluster
  5. # Now it creates a new tenant
  6. admin tenants create new-tenant
  7. # And then it creates a new namespace inside the tenant
  8. admin namespaces create new-tenant/new-namespace
  9. " > ./bin/pulsar-shell --fail-on-error -