Tutorials: Manage Pulsar resources using pulsarctl

A tenant is an administrative unit for allocating capacity and enforcing an authentication or authorization scheme. After creating a cluster, you can create one or more tenants for the organization.

A namespace is a logical grouping of topics. After creating a tenant, you can create one or more namespaces for the tenant.

A topic is a named channel used to deliver messages published by producers to consumers. After creating a namespace, you can create one or more topics for the namespace.

Work with tenants

You can create, update, and delete tenants using the pulsarctl CLI tool. For a full list of supported operations on tenants, see pulsarctl command reference.

Before using the pulsarctl CLI tool, you need to connect to a Pulsar cluster. For details, see connect to Pulsar cluster on StreamNative Cloud and connect to Pulsar cluster on StreamNative Platform.

Create a tenant

After creating a Pulsar cluster, you can create tenants for the Pulsar cluster. When creating a tenant, you need to use -cluster or -c option to specify the target cluster for the tenant.

This example shows how to create a tenant named example-tenant for the example-cluster cluster with the admin role. If you do not configure the admin role when creating the tenant, you cannot perform follow-up operations on the target tenant, such as updating or deleting tenants.

Input

pulsarctl tenants create example-tenant -r [email protected] -c example-cluster

Output

Create tenant example-tenant successfully

Manage a tenant

This section describes how to manage tenants through the pulsarctl CLI tool.

Update a tenant

When you want to add more admin roles for a tenant, you can use the pulsarctl tenants update command to update the target tenant.

This example shows how to update the admin role for example-tenant.

Input

pulsarctl tenants update --admin-roles (bot) --admin-roles (bot1) example-tenant -c example-cluster

Output

Update tenant example-tenant successfully

Delete a tenant

When you want to remove a tenant from a Pulsar cluster, you can delete it. If a tenant is associated with any resources, you cannot delete the tenant. In this case, you must delete its associated resources first.

Note

You cannot delete a tenant if there are resources associated with the tenant.

This example shows how to delete example-tenant.

Input

pulsarctl tenants delete example-tenant

Output

Delete tenant example-tenant successfully

Work with namespaces

You can create and manage namespaces using the pulsarctl CLI tool. For a full list of supported operations on namespaces, see the pulsarctl command reference.

Note

This section uses a tenant named example-tenant as an example. For details about how to create a tenant, see work with tenants.

Create a namespace

After creating and authorizing a tenant, you can create and manage namespaces and topics.

This example shows how to create a namespace named example-ns for example-tenant.

Input

pulsarctl namespaces create example-tenant/example-ns

Output

Created example-tenant/example-ns successfully

Manage a namespace

This section describes how to manage namespaces using the pulsarctl CLI tool.

Clear namespace backlog

Pulsar stores all unacknowledged messages in backlogs until they are processed and acknowledged. You can clear backlogs of messages for a specific namespace to release more backlog quota for the namespace.

This example shows how to clear the backlog for all topics of example-tenant/example-ns.

Input

pulsarctl namespaces clear-backlog example-tenant/example-ns

Output

Are you sure you want to clear the backlog? (Y or N)

y

Successfully clear backlog for all topics of the example-tenant/example-ns

Unload a namespace

This example shows how to unload example-tenant/example-ns from the current serving broker.

Input

pulsarctl namespaces unload example-tenant/example-ns

Output

Unload namespace example-tenant/example-ns successfully

Delete a namespace

Note

You cannot delete a namespace if there are resources associated with the namespace.

This example shows how to delete example-tenant/example-ns.

Input

pulsarctl namespaces delete example-tenant/example-ns

Output

Deleted example-tenant/example-ns successfully

Work with topics

This section describes how to create and manage topics using the pulsarctl CLI tool. For a full list of supported operations on topics, see pulsarctl command reference.

Before using the pulsarctl CLI tool to create and manage topics, you need to create a tenant and a namespace.

Create a topic

You can use the pulsarctl topics create TOPIC_NAME command to create a topic.

If you want to create a non-partitioned topic, you need to set the number of partitions to 0.
This example shows how to create a non-partitioned topic in the example-tenant/example-ns namespace.
Input
```
pulsarctl topics create example-tenant/example-ns/topic-test 0
```
Output
```
Create topic persistent://example-tenant/example-ns/topic-test with 0 partitions successfully
```
If you want to create a partitioned topic, you need to set the number of partitions to a specific number.
This example shows how to create a topic with 5 partitions in the example-tenant/example-ns namespace.
Input
```
pulsarctl topics create example-tenant/example-ns/test-topic 5
```
Output
```
Create topic persistent://example-tenant/example-ns/test-topic with 5 partitions successfully
```

Manage a topic

This section describes how to manage topics using the pulsarctl CLI tool.

Get topic status

You can use the pulsarctl topics get TOPIC_NAME command to get information about a specific topic.

This example shows how to list all topics available for the example-tenant/example-ns namespace.

Input

pulsarctl topics list example-tenant/example-ns/

Output

+--------------------------------------------------------------------------------+-----------------------+
|                 TOPIC NAME                                                          | PARTITIONED ? |
+--------------------------------------------------------------------------------+-----------------------+
| persistent://example-tenant/example-ns/topic-test                  | N                         |
| persistent://example-tenant/example-ns/test-topic                  | Y                         |
| persistent://example-tenant/example-ns/test-topic-partition-0 | N                         |
| persistent://example-tenant/example-ns/test-topic-partition-1 | N                         |
| persistent://example-tenant/example-ns/test-topic-partition-2 | N                         |
| persistent://example-tenant/example-ns/test-topic-partition-3 | N                         |
| persistent://example-tenant/example-ns/test-topic-partition-4 | N                         |
+--------------------------------------------------------------------------------+-----------------------+

This example shows how to get detailed information about the topic-test topic.
Input
```
pulsarctl topics get topic-test
```
Output
```
{
"partitions": 0
}
```

Delete a topic

You can use the pulsarctl topics delete TOPIC_NAME command to delete a partitioned topic. To delete a non-partitioned topic, you need to set the --non-partitioned parameter.

This example shows how to delete the test-topic partitioned topic.

Input

pulsarctl topics delete topic-test

Output

Delete topic persistent://example-tenant/example-ns/test-topic  successfully

This example shows how to delete the topic-test non-partitioned topic.

Input

pulsarctl topics delete --non-partitioned topic-test

Output

Delete topic persistent://example-tenant/example-ns/topic-test  successfully

Learn about all the available Pulsar CLI Tools on StreamNative Cloud.
Learn about all the available Pulsar CLI Tools on StreamNative Platform.

Work with tenants

Create a tenant

Manage a tenant

Update a tenant

Delete a tenant

Work with namespaces

Create a namespace

Manage a namespace

Clear namespace backlog

Unload a namespace

Delete a namespace

Work with topics

Create a topic

Manage a topic

Get topic status

Delete a topic

Related topics