Skip to main content
Version: Next

Get started

Pulsar admin interfaces let you administer clusters: create, update, delete and inspect every entity of a Pulsar instance (clusters, tenants, namespaces, topics, schemas, functions, connectors, packages, transactions) and set the policies for data, resources and security. Every way of administering Pulsar goes through the admin REST API that the brokers serve; the command-line tool and the client libraries are clients of it. Pick the interface that fits how you work:

InterfaceReferenceUse it when
Command line: pulsar-adminpulsar-admin CLI referenceYou administer a cluster interactively or from shell scripts. It ships in the bin folder of the Pulsar installation and needs no extra setup, but each invocation starts a JVM. Pulsar shell is an interactive shell around the same commands that starts the JVM once.
REST APIREST APIs and OpenAPI specifications, endpoint referenceYou automate from any language or tool that speaks HTTP, for example an operator, a controller or a curl call in a script. Since Pulsar 5.0 the API has OpenAPI 3 specifications from which you can generate a client for your language.
Java LibraryJava admin API JavadocYou manage Pulsar from Java applications or tests. The client is the org.apache.pulsar:pulsar-client-admin artifact.
Go Librarypulsaradmin package of the Go clientYou manage Pulsar from Go applications, for example a Kubernetes operator.

Pulsar admin interfaces

The REST API deserves a closer look, because it is what the other interfaces are built on and the right choice when the CLI or the Java client does not fit:

The rest of this page walks you through the quickest way to get started with the command line, the REST API and the Java API by managing a topic with each of them, including the setup each interface needs when authentication is enabled.

pulsar-admin CLI is a command-line tool and is available in the bin folder of your Pulsar installation.

Check the detailed steps below.

To manage topics using pulsar-admin CLI, complte the following steps.

  1. Set the service URL.

  2. Create a partitioned topic.

  3. Update the number of a partition.

  4. Produce messages to the topic.

  5. Check the stats of the topic.

  6. Delete the topic.

Prerequisites

  • Install and start Pulsar standalone. This tutorial runs Pulsar 2.11 as an example.

Steps

Step 1: Set the service URLs to point to the broker service in client.conf.

webServiceUrl=http://localhost:8080/
brokerServiceUrl=pulsar://localhost:6650/

If authentication is enabled in your cluster, configure the authentication plugin and its parameters in the same file, and the TLS settings when the web service uses TLS:

NameDescriptionDefault
webServiceUrlThe web URL for the cluster.http://localhost:8080/
brokerServiceUrlThe Pulsar protocol URL for the cluster.pulsar://localhost:6650/
authPluginThe authentication plugin.
authParamsThe authentication parameters for the cluster, as a comma-separated string.
useTlsWhether or not TLS authentication will be enforced in the cluster.false
tlsAllowInsecureConnectionAccept untrusted TLS certificate from client.false
tlsTrustCertsFilePathPath for the trusted TLS certificate file.

See the client configuration reference for all settings.

Step 2: Create a persistent topic named test-topic-1 with 6 partitions.

Input

bin/pulsar-admin topics create-partitioned-topic \
persistent://public/default/test-topic-1 \
--partitions 6

Output

There is no output. You can check the status of the topic in Step 5.

Step 3: Update the number of the partition to 8.

Input

bin/pulsar-admin topics update-partitioned-topic \
persistent://public/default/test-topic-1 \
--partitions 8

Output

There is no output. You can check the number of partitions in Step 5.

Step 4: Produce some messages to the partitioned topic test-topic-1.

Input

bin/pulsar-perf produce -u pulsar://localhost:6650 -r 1000 -i 1000 persistent://public/default/test-topic-1

Output

2023-03-07T15:33:56,832+0800 [main] INFO  org.apache.pulsar.testclient.PerformanceProducer - Starting Pulsar perf producer with config: {
  "confFile" : "/Users/yu/apache-pulsar-2.11.0/conf/client.conf",
  "serviceURL" : "pulsar://localhost:6650",
  "authPluginClassName" : "",
  "authParams" : "",
  "tlsTrustCertsFilePath" : "",
  "tlsAllowInsecureConnection" : false,
  "tlsHostnameVerificationEnable" : false,
  "maxConnections" : 1,
  "statsIntervalSeconds" : 1000,
  "ioThreads" : 1,
  "enableBusyWait" : false,
  "listenerName" : null,
  "listenerThreads" : 1,
  "maxLookupRequest" : 50000,
  "topics" : [ "persistent://public/default/test-topic-1" ],
  "numTestThreads" : 1,
  "msgRate" : 1000,
  "msgSize" : 1024,
  "numTopics" : 1,
"numProducers" : 1,
  "separator" : "-",
  "sendTimeout" : 0,
  "producerName" : null,
  "adminURL" : "http://localhost:8080/",

...

2023-03-07T15:35:03,769+0800 [Thread-0] INFO  org.apache.pulsar.testclient.PerformanceProducer - Aggregated latency stats --- Latency: mean:   8.931 ms - med:   3.775 - 95pct:  32.144 - 99pct:  98.432 - 99.9pct: 216.088 - 99.99pct: 304.807 - 99.999pct: 349.391 - Max: 351.235

Step 5: Check the internal stats of the partitioned topic test-topic-1.

Input

bin/pulsar-admin topics partitioned-stats-internal \
persistent://public/default/test-topic-1

Output

Below is a part of the output. For detailed explanations of topic stats, see Pulsar statistics.

{
  "metadata" : {
    "partitions" : 8
  },
  "partitions" : {
    "persistent://public/default/test-topic-1-partition-1" : {
      "entriesAddedCounter" : 4213,
      "numberOfEntries" : 4213,
      "totalSize" : 8817693,
      "currentLedgerEntries" : 4212,
      "currentLedgerSize" : 8806289,
      "lastLedgerCreatedTimestamp" : "2023-03-07T15:33:59.367+08:00",
      "waitingCursorsCount" : 0,
      "pendingAddEntriesCount" : 0,
      "lastConfirmedEntry" : "65:4211",
      "state" : "LedgerOpened",
      "ledgers" : [ {
        "ledgerId" : 49,
        "entries" : 1,
        "size" : 11404,
        "offloaded" : false,
        "underReplicated" : false
      }, {
        "ledgerId" : 65,
        "entries" : 0,
        "size" : 0,
        "offloaded" : false,
        "underReplicated" : false
      } ],
      "cursors" : {
        "test-subscriptio-1" : {
          "markDeletePosition" : "49:-1",
          "readPosition" : "49:0",
          "waitingReadOp" : false,
          "pendingReadOps" : 0,
          "messagesConsumedCounter" : 0,
          "cursorLedger" : -1,
          "cursorLedgerLastEntry" : -1,
  "individuallyDeletedMessages" : "[]",
          "lastLedgerSwitchTimestamp" : "2023-03-06T16:41:32.801+08:00",
          "state" : "NoLedger",
          "numberOfEntriesSinceFirstNotAckedMessage" : 1,
          "totalNonContiguousDeletedMessagesRange" : 0,
          "subscriptionHavePendingRead" : false,
          "subscriptionHavePendingReplayRead" : false,
          "properties" : { }
        },
        "test-subscription-1" : {
          "markDeletePosition" : "49:-1",
          "readPosition" : "49:0",
          "waitingReadOp" : false,
          "pendingReadOps" : 0,
          "messagesConsumedCounter" : 0,
          "cursorLedger" : -1,
          "cursorLedgerLastEntry" : -1,
          "individuallyDeletedMessages" : "[]",
          "lastLedgerSwitchTimestamp" : "2023-03-06T16:41:32.801+08:00",
          "state" : "NoLedger",
          "numberOfEntriesSinceFirstNotAckedMessage" : 1,
          "totalNonContiguousDeletedMessagesRange" : 0,
          "subscriptionHavePendingRead" : false,
          "subscriptionHavePendingReplayRead" : false,
          "properties" : { }
        }
      },
      "schemaLedgers" : [ ],
      "compactedLedger" : {
        "ledgerId" : -1,
        "entries" : -1,
        "size" : -1,
        "offloaded" : false,
        "underReplicated" : false
      }
    },
...

Step 6: Delete the topic test-topic-1.

Input

bin/pulsar-admin topics delete-partitioned-topic persistent://public/default/test-topic-1

Output

There is no output. You can verify whether the test-topic-1 exists or not using the following command.

Input

List topics in public/default namespace.

bin/pulsar-admin topics list public/default
Was this helpful?
💡 Suggest changes🛟 Get support