Skip to content

Clarify that {namespace} prefixes topics on the broker, not just consumer groups #5166

@MyMirelHub

Description

@MyMirelHub

Describe the issue

The "How to: Set up pub/sub namespace consumer groups" page lists "Keep the same topics" as one of the benefits of using consumerID: "{namespace}". This is misleading because, while the application's view of the topic name is preserved, Dapr actually prefixes the Kubernetes namespace onto the topic name on the broker side. Operators inspecting their broker directly (Azure Service Bus, Kafka, RabbitMQ, etc.) see physically prefixed topic names, which contradicts the docs and the Dapr sidecar logs (which also display the un-prefixed name).

The page also frames the feature purely around "consumer groups", which suggests only the subscription/consumer-group identifier is namespaced — not the topic itself.

URL of the docs

https://docs.dapr.io/developing-applications/building-blocks/pubsub/howto-namespace/

Expected content

The page should make clear that:

  1. When {namespace} appears anywhere in a pub/sub component's metadata, the runtime flags the whole component as namespace-scoped, not just the consumerID field.
  2. The K8s namespace is prefixed onto both the topic and the subscription/consumer-group on every publish and subscribe, on the broker side.
  3. From the application's perspective the topic name is preserved end-to-end — Dapr strips the prefix on the receive path before delivering to the app — which is what "Keep the same topics" is meant to convey, but this should be stated explicitly.
  4. This behavior applies to all pub/sub brokers (the prefix is applied in the broker-agnostic runtime layer), not only to brokers where consumer-groups are first-class (e.g., Kafka). The current Redis-centric example doesn't make this clear.
  5. A concrete example would help — e.g. with namespace team-a and logical topic orders, the broker entity is physically named team-aorders (no separator) and the subscription is team-a.<appID>.

Suggested rewording for the bullet list under "With namespace consumer groups":

Without you needing to change your code/app-id, the namespace consumer group allows you to:

  • Add more namespaces
  • Use the same topic names in your application code across namespaces (Dapr namespaces the underlying broker entities transparently)
  • Keep the same app-id across namespaces
  • Have your entire deployment pipeline remain intact

Note: on the broker, both the topic and the subscription/consumer-group are prefixed with the Kubernetes namespace for tenant isolation. For example, with namespace team-a and logical topic orders, you will see a topic named team-aorders on the broker. Your application code still publishes and subscribes to orders.

Additional context

Source code references confirming the documented vs. actual behavior:

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions