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