EMQX Enterprise

日本語

简体中文
English

日本語

简体中文
English

Appearance

お問い合わせ

Namespace ​

Starting from EMQX 5.9.0, the Namespace feature allows users to logically group MQTT clients and apply traffic limits within a single EMQX cluster. This feature enables scalable deployments where multiple client groups (such as business units, applications, or customers) share the same infrastructure while remaining logically separated.

Note

This feature is referred to as Namespace in EMQX 5.9, even though it follows multi-tenancy design principles.

Beginning with EMQX 6.1, namespace-related capabilities have been enhanced without changing their original semantics. These enhancements simplify multi-tenant isolation configuration and unify the behavior of topic isolation.

What Is a Namespace ​

A Namespace in EMQX Enterprise is a mechanism used for logical isolation and resource management of MQTT clients. It allows users to divide clients from different businesses or tenants into separate namespaces within a shared EMQX cluster, achieving isolation in connections, messages, quotas, and more.

A namespace is identified by a special client attribute named tns (tenant namespace). This attribute is not created automatically; instead, it must be derived from client connection metadata, such as the username or Server Name Indication (SNI), through configuration.

Typical use cases include: multiple business units sharing a cluster within an enterprise, tenant-level resource isolation management, centralized access control, etc.

What Namespaces Can Achieve ​

  • Logical Isolation of Clients and Messages

    Namespaces enable you to logically separate clients across different tenants by isolating client IDs and topic spaces.

    Note

    Enabling namespaces does not automatically apply client ID overrides or topic prefixes. These features must be manually configured. See Isolation Mechanisms for details.

  • Tenant-Level Quotas and Connection Control

    You can define limits on the number of concurrent connections and message publish rates for each namespace, helping to ensure fair usage and system stability.

  • Enhanced Logging and Operational Visibility

    Logs automatically include the namespace identifier (tns), making it easier to trace client activity, detect issues, and perform tenant-level diagnostics.

  • Namespace-Based Resource Monitoring

    Namespaces provide a clean boundary for collecting metrics such as connection count and message throughput per tenant, essential for capacity planning and operational insight.

  • Admin User Isolation

    Starting from EMQX 6.0, namespaces are extended to Dashboard, CLI, and API users through namespaced roles.

    • Admin users can be created with roles restricted to a specific namespace, e.g., ns:team_a::administrator.
    • Namespaced users only see and operate on resources within their assigned namespace.
    • Cluster-level configurations not yet namespace-aware are visible but read-only for namespaced users, and only modifiable by global administrators.
    • This ensures secure, tenant-specific administrative access alongside data isolation.

  • Multi-Tenant Management

    System administrators can manage multiple namespaces within the same cluster, while each tenant operates in a self-contained environment with isolated resources and user permissions.

Isolation Mechanisms ​

EMQX is highly flexible and supports multiple isolation mechanisms even before namespaces were introduced.

Namespaces provide a unified tenant identifier (client_attrs.tns) that allows Client IDs, topic mountpoints, and related configurations to be organized around a consistent tenant context.

However, isolation policies still need to be explicitly configured based on business requirements. EMQX does not automatically enable Client ID or topic isolation when namespaces are enabled.

  • Client ID override

    To allow clients in different namespaces to use the same Client ID, you can configure a Client ID override rule. For example:

    hocon
    mqtt.clientid_override = "concat([client_attrs.tns, '-', clientid])"

    This rule prefixes the Client ID with the namespace to avoid conflicts.

  • Topic isolation using mountpoints

    If clients in different namespaces need to publish or subscribe to the same topic names without interfering with each other, a mountpoint can be used to automatically prefix topics with the namespace.

    In EMQX 6.0 and earlier, mountpoints were typically configured at the listener level, for example:

    hocon
    listener.{TYPE}.{NAME}.mountpoint = "${client_attrs.tns}/"

    In environments with multiple listeners, this required repetitive configuration.

    Starting from EMQX 6.1, namespaces can be used as a unified topic mountpoint. Once a namespace is successfully identified, EMQX internally applies {namespace}/ as the topic prefix, achieving the same isolation effect as listener mountpoints without requiring per-listener configuration.

    To maintain backward compatibility, authorization (ACL) checks do not include the mountpoint prefix by default.

    From EMQX 6.1 onward, you can enable this behavior by setting:

    hocon
    authorization.include_mountpoint = true

    This allows authorization backends to receive topics with the mountpoint prefix.

Enable Namespaces ​

To enable the namespace feature, you must first tell EMQX how to determine which namespace a client belongs to. This is done by configuring a namespace source rule that derives and sets the special client attribute tns (tenant namespace) from client connection information.

Enable Namespaces via Configuration File ​

You can extract the tns attribute from the connection metadata, such as the client's username, SNI, or other fields.

For example, to use the client's username as the namespace identifier, you can apply the following configuration:

mqtt.client_attrs_init = [{expression = username, set_as_attr = tns}]

Enable Namespaces via Dashboard ​

You can also enable namespaces using the EMQX Dashboard:

  1. Navigate to Management -> MQTT Settings -> General tab, and locate the Client Attributes section.
  2. Click Add, and fill in the following information:
    • Attribute: tns
    • Attribute Expression: For example, if you want to use the client's username as the namespace identifier, enter username. You may also use other variables. For more information on attribute expressions, refer to Set Client Attributes.
  3. Click Save Changes.

Multi-Tenancy Capability Support ​

Namespaces are the core building block of EMQX multi-tenancy. Introduced in EMQX 5.9 and enhanced in 6.1, namespaces now support tenant isolation across multiple subsystems. The current support status is as follows:

  • Unified management and MQTT namespaces (6.0)

    The management plane (Dashboard, CLI, APIs) and the MQTT data plane share the same namespace model.

  • Isolation for built-in database authentication (6.1)

    Authentication data stored in the built-in database can be isolated by namespace.

  • Isolation for built-in database authorization (6.1)

    Authorization rules can be scoped to specific namespaces.

  • Prometheus metrics isolation (6.1)

    Metrics can be exposed and aggregated by namespace, enabling better observability in multi-tenant environments.

  • Retained message quota isolation

    Resource usage related to retained messages can be limited per namespace.

In addition, starting from EMQX 6.0, namespace isolation has been fully implemented for rules, actions, sources, and connectors, and is no longer part of the future roadmap.

What's Next ​

Now that you understand what namespaces are and what they can achieve, here are the next steps to start using them in EMQX: