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 bot@matrix.auth.streamnative -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.
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.
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

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