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:
- 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.
- The K8s namespace is prefixed onto both the topic and the subscription/consumer-group on every publish and subscribe, on the broker side.
- 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.
- 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.
- 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:
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:
{namespace}appears anywhere in a pub/sub component's metadata, the runtime flags the whole component as namespace-scoped, not just the consumerID field.team-aand logical topicorders, the broker entity is physically namedteam-aorders(no separator) and the subscription isteam-a.<appID>.Suggested rewording for the bullet list under "With namespace consumer groups":
Additional context
Source code references confirming the documented vs. actual behavior: