Work with namespaces

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

Namespace Overview

A namespace represents an administrative unit within a tenant. The configuration policies set on a namespace apply to all the topics created in that namespace. You can create multiple namespaces for a tenant using the StreamNative Cloud Console, REST API or the pulsar-admin CLI tool.

Permissions

In Pulsar, permissions are managed at the namespace level (within tenants and clusters). You can grant permissions to specific users for lists of operations such as produce and consume. In addition, you can revoke permissions from specific users, which means that those users cannot access the specified namespace.

Backlog quotas

Backlogs are sets of unacknowledged messages for a topic that have been stored by bookies. Pulsar stores all unacknowledged messages in backlogs until they are processed and acknowledged. You can use the backlog quotas to control the allowable size of backlogs at the namespace level. You can set the following items for a backlog quota:

• an allowable size threshold for each topic in the namespace
• a retention policy that determines the action the broker takes if the threshold is exceeded.

The following table lists available retention policies.

Bundles

For assignment, a namespace is sharded into a list of bundles, with each bundle comprising a portion of the overall hash range of the namespace. A bundle is a virtual group of topics that belong to the same namespace. A namespace bundle is defined as a range between two 32-bit hashes, such as 0x00000000 and 0xffffffff. By default, four bundles are supported for each namespace.

Since the load for topics in a bundle might change over time, one bundle can be split into two bundles by brokers. Then, the new smaller bundle is reassigned to different brokers. By default, the newly split bundles are immediately offloaded to other brokers to facilitate the traffic distribution.

Dispatch rate

Dispatch rate refers to the number of messages dispatched per second by topics for a namespace. Dispatch rate can be restricted by the number of messages per second (msg-dispatch-rate) or by the number of bytes of messages per second (byte-dispatch-rate). Dispatch rate is in seconds and it can be configured with dispatch-rate-period. By default, msg-dispatch-rate and byte-dispatch-rate are both set to -1, which indicates that throttling is disabled.

Create a namespace

To create a namespace, follow these steps.

1. On the left navigation pane, under Tenants/Namespaces, select the name of the tenant you want to associate with the new namespace, and click New Namespace.

2. On the Namespace page, click New Namespace.

3. Enter a name for the namespace and then click Confirm. A namespace name can contain any combination of lowercase letters (a-z), numbers (0-9), and hyphens (-).

Manage a namespace

This section describes how to manage namespaces through the StreamNative Console.

1. On the left navigation pane, under Tenants/Namespaces, select the name of the Tenant/Namespace you want to manage.

2. Select the OVERVIEW tab to check statistics about the namespace, as well as unload and split bundles. The following table lists statistics about the namespace.

   Item	Description
   In Rate	The ingress rate of the namespace.
   Out Rate	The egress rate of the namespace.
   In Throughput	The ingress throughput of the namespace.
   Out Throughput	The egress throughput of the namespace.

3. Select the TOPICS tab to check the number of topics included in the namespace and statistics about topics. In addition, you can update specific topics. For details about how to update topics, see edit topics.

4. Select the POLICIES tab to configure related policies for the namespace. For details, see configure policies for a namespace.

Unload bundles for a namespace

For an assignment, a namespace is sharded into a list of bundles, with each bundle comprising a portion of the overall hash range of the namespace. By default, four bundles are supported for each namespace.

To unload bundles for a namespace, follow these steps.

1. On the left navigation pane, under Tenants/Namespaces, select the name of the Tenant/Namespace you need to edit, and click New Namespace.

2. Click Edit in the Actions column.

3. Select the OVERVIEW tab.

   

4. In the Bundle section, select the target cluster from the Cluster drop-down list, and then do one of the following:

   • Click Unload All to unload all bundles for the namespaces in the cluster.

   • Click Unload in the Operation column to unload a specific bundle for the namespace.

Split bundles for a namespace

Because the load for topics in a bundle might change over time, one bundle can be split in two bundles by brokers. Then, the new smaller bundles are reassigned to different brokers. By default, the newly split bundles are immediately offloaded to other brokers to facilitate the traffic distribution.

To split bundles for a namespace, follow these steps.

1. From the left navigation pane, click Namespaces.

2. Click Edit icon (it looks like a pencil.) in the Action column or click the link of the namespace name.

3. Select OVERVIEW tab.

   

4. Click Split.

Clear namespace backlog

To clear backlog for bundles of a namespace, follow these steps.

1. On the left navigation pane, under ADMIN, click Tenants/Namespaces.

2. Select the name of the tenant that is associated with the target namespace.

3. Click the name of the namespace that you want to clear backlog for.

4. In the Bundle section of the OVERVIEW tab, click Clean All Backlog to clear the backlog for all the topics of the namespace.

Configure policies for a namespace

To configure policies for a namespace, follow these steps.

1. From the left navigation pane, click Namespaces.

2. Click Edit in the Action column or click the link of the namespace name.

3. Select the Policies tab.

   

4. Configure policies for the namespace, as listed in the following table.

   Item	Description
   Clusters	Select a replication cluster. Messages of the topics in this namespace are asynchronically replicated between the configured replication clusters. Currently, this item is set to the cluster you created because there is only one cluster available for an instance.
   Authorization	Grant/Revoke permissions to other client roles in this namespace. - consume: grant/revoke the consuming action. - produce: grant/revoke the producing action. - functions: grant/revoke the Pulsar functions action.
   Subscription Authentication	Configure the subscription authentication mode to limit the naming convention for subscriptions when authentication is enabled. - None: clients can use any allowed subscription name to connect to the cluster. - Prefix: clients can only use subscription names that are prefixed with their role names to subscribe messages. By default, it is set to None.
   Storage	Configure the storage policy for the namespace. Replication Factor: configure the storage replication settings. - Ensemble size: configure the number of bookies to be used when creating a ledger. - Write Quorum Size: configure the number of replicas to be stored for each message. - Ack Quorum Size: configure the number of responses to wait before claiming a message is guaranteed to be stored. Mark-Delete Rate: configure the number of mark-deletion calls that are allowed for each second. When the value is set to 0, the rate limiter is disabled. By default, the value is set to 0. Encryption Required: enable/disable message encryption for the namespace. - Enabled: enable message encryption for the namespace. - Disabled: disable message encryption for the namespace. Deduplication: enable/disable deduplication for the namespace. - Enabled: enable deduplication for the namespace. - Disabled: disable deduplication for the namespace.
   Backlog	Configure the backlog policy for the namespace. Backlog Quota Size: configure the maximum backlog quota (in bytes) allowed for the namespace. The backlog quota size must be smaller than 1000000000 bytes. By default, it is set to -1073741824 bytes. Backlog Retention Policy: configure the backlog retention policy. - consumer_backlog_eviction: the broker starts discarding backlog messages. - producer_exception: the broker disconnects with the client by giving an exception. - producer_request_hold: the broker holds but does not persist producer request payload.
   Schema	Configure the schema policy for the namespace. - AutoUpdate Strategy: configure the automatic update strategy for the namespace. - Schema Validation Enforced: enable/disable schema validation for producers without schema. If it is disabled, producers without schema are disallowed to produce messages to topics with schema.
   Cleanup Policy	Configure the cleanup policy for the namespace. - Message TTL (seconds): configure the message TTL in seconds. If messages are not consumed by any consumer of a subscription, they are marked as consumed after the configured TTL period expires. - Retention Size (bytes): configure the retention size. This field is only applied to the messages that are acknowledged by all subscriptions. The retention size must be smaller than 1000 MB. By default, it is set to 0. - Retention Period (minutes): configure the retention period. This field is only applied to the messages that are acknowledged by all subscriptions. By default, it is set to 0. - Compaction Threshold (bytes): configure the threshold to compact topics. The compaction is automatically triggered when the threshold is reached. By default, it is set to 0. - Offload Threshold (bytes): configure the threshold to offload messages. Messages are automatically offloaded to the tiered storage when the threshold is reached. By default, it is set to -1. - Offload Deletion Lag (milliseconds): configure the time (in milliseconds) to wait before deleting a ledger offloaded from the BookKeeper. When the value is set to a negative value, offloading deletion is disabled.
   Throttling	Configure the throttling policy for the namespace. - Max Producers Per Topic: configure the maximum number of producers allowed for each topic. - Max Consumers Per Topic: configure the maximum number of consumers allowed for each topic. - Max Consumers Per Subscription: configure the maximum number of consumers allowed for each subscription.
   Dispatch Rate	Configure the dispatch rate policy for the namespace. Dispatch Rate Per Topic: configure the dispatch rate based on the topic. - Throughput (bytes/second): configure the dispatch rate of bytes in a topic. - Rate (messages/second): configure the dispatch rate of messages in a topic. - Time Period (seconds): configure the dispatch rate period. Dispatch Rate Per Subscription: configure the dispatch rate based on the subscription mode. - Throughput (bytes/second): configure the dispatch rate of bytes for a subscription. - Rate (messages/second): configure the dispatch rate of messages for a subscription. - Time Period (seconds): configure the dispatch rate period. Subscribe Rate Per Consumer: configure the rate at which a consumer subscribes to a topic. - Throughput (bytes/second): configure the throughput for a topic that a consumer subscribes to. - Rate (messages/second): configure the rate for a topic that a consumer subscribes to.

Delete a namespace

To delete a namespace, follow these steps.

1. On the left navigation pane, in the Admin section, click Namespaces.

2. In the Warning section at the bottom of the Namespace Policy page, click Delete Namespace. A dialog box displays asking, Are you sure you want to delete this?

3. Enter the namespace name and then click Confirm.

Next step

• Work with topics