Topic aliases let you expose a backend Kafka topic under a different, client-facing name.
Clients connecting to the virtual cluster see the alias, while Event Gateway transparently routes requests to the original backend topic.
This is useful when you want to:
- Expose internally-named topics (like
team-alpha-orders-v2) under client-friendly names (like orders)
- Migrate clients to renamed backend topics without updating client configuration
- Provide multiple client-facing names for the same backend topic
Unlike namespaces, which apply a prefix to every topic and consumer group, topic aliases are explicit one-to-one mappings between an alias and a backend topic.
Both the alias and the original backend topic name remain accessible through the virtual cluster.
Define topic aliases on the virtual cluster using the topic_aliases field:
curl -X POST "https://us.api.konghq.com/v1/event-gateways/$EVENT_GATEWAY_ID/virtual-clusters" \
--no-progress-meter --fail-with-body \
-H "Authorization: Bearer $KONNECT_TOKEN" \
--json '{
"name": "example-virtual-cluster",
"destination": {
"name": "example-backend-cluster"
},
"authentication": [
{
"type": "anonymous"
}
],
"dns_label": "virtual-cluster-1",
"acl_mode": "passthrough",
"topic_aliases": [
{
"alias": "orders",
"topic": "team-alpha-orders-v2"
},
{
"alias": "clicks",
"topic": "analytics-raw-clicks"
}
]
}'
In this example, clients can produce and consume to orders and clicks. Event Gateway resolves these to the backend topics team-alpha-orders-v2 and analytics-raw-clicks.
Aliases are a read-only abstraction over physical topics. Read and write operations are forwarded to the backend topic, but topic-modifying operations are rejected.
|
Operation
|
Behavior
|
|
Produce, fetch, list offsets, consumer group operations
|
Allowed. Requests reference the alias name and are transparently resolved to the backend topic.
|
Metadata (ListTopics)
|
Allowed. Both the alias and the original backend topic name appear in the response.
|
CreateTopics, DeleteTopics, CreatePartitions, DeleteRecords, AlterPartitionReassignments, ElectLeaders
|
Rejected with InvalidTopicException when the request references an alias. This avoids a client unintentionally modifying a physical topic that other aliases or clients depend on.
|
ACLs are evaluated on the name the client uses, before alias resolution. An ACL on the backend topic does not automatically grant access to its aliases, and vice versa. Operators must configure ACLs for each alias name explicitly. With acl_mode: enforce_on_gateway (deny-by-default), a new alias with no matching ACL is blocked.
The topic field in topic_aliases references namespace-visible names, not raw backend topic names. In the request path, aliases resolve after policies but before the namespace transformer:
client → policies → alias resolution → namespace → backend
If the virtual cluster has a namespace, the alias must target a name that the namespace already exposes. For example, with namespace.mode: hide_prefix and prefix: analytics_, topic: foo resolves to the backend topic analytics_foo.
A backend topic that the namespace doesn’t expose (not matching the prefix and not listed in additional_topics) can’t be aliased directly. Expose it through the namespace first:
namespace:
mode: hide_prefix
prefix: analytics_
additional_topics:
- type: exact_list
list:
- team-alpha-orders-v2
topic_aliases:
- alias: orders
topic: team-alpha-orders-v2 # valid because additional_topics exposes it
Policies attached to a virtual cluster see the alias name, not the backend topic name. In a CEL match expression, topic.name evaluates to the alias name. Policies that match on a backend topic name don’t automatically apply to its aliases. Match the alias name explicitly:
condition: topic.name == "orders"
Avoid consuming from both an alias and its backend topic with the same consumer group.
Event Gateway treats the alias and the backend topic as distinct topic names that share the same underlying partitions. Mixing them in one consumer group leaves offset commits and partition assignment undefined.
Pick one name per consumer group and stick with it.
For a full walkthrough, see Configure topic aliases.