Kafka Users, Topic Names and ACL Roles

This page explains what a Kafka ACL Component creates, how the names it
generates are built, and what each ACL role allows, so you can read an
authorisation error or ask for exactly the access an application needs.

What one Kafka ACL Component creates

Each Kafka ACL Component describes one Kafka user in one tenant on one
Kafka cluster. From it the platform creates:

the Kafka user, authenticated with SCRAM-SHA-512;
a secret holding that user's credentials, in the namespace the Component is
deployed to, ready to inject into your application — see
Kafka Access, ACLs and Topics;
the ACLs: the user's default rights on its own topics, plus any extra grants
you list.

The Component can be deployed on its own, or bundled into an application's
deployment so the application and its Kafka user are created together.

The values

belongsTo: shared
cluster: kafka-bootstrap.kafka.svc.cluster.local
tenant: vote
user: api
consumerGroups: []
idempotent: false
acls: []
rawAcls: []
global: {}
metadata: {}

Value	Meaning
`belongsTo`	The Kafka instance name, usually `shared`.
`cluster`	The bootstrap service. Leave it as it is.
`tenant`	Your tenant, usually the namespace your applications run in. It is added to every user, topic and consumer group name.
`user`	The short name of this application's user, such as `api`.
`consumerGroups`	Extra consumer groups this user may join, beyond its own.
`idempotent`	`true` grants the cluster-level rights (IdempotentWrite, TransactionalDescribe) that transactional producers need.
`acls`	Grants to other users on this tenant's topics.
`rawAcls`	Grants on topics whose names do not follow the naming convention.
`global`	Holds `acls` instead of the top level when the Component is bundled into an application deployment.
`metadata`	Set by the platform (stage, Environment, cloud). Do not edit.

The names it generates

Every name starts with the stage and tenant. With stage dev, tenant vote and
user api:

What	Pattern	Example
Kafka user	`<stage>-<tenant>-<user>-user`	`dev-vote-api-user`
Credentials secret	`sview-kafka-<stage>-<tenant>-<user>-user`	`sview-kafka-dev-vote-api-user`
The user's own topics	`<stage>.<tenant>.<user>.*`	`dev.vote.api.events`
The user's own consumer groups	`<stage>.<tenant>.<user>.*`	`dev.vote.api.worker`

A user has full rights on topics and consumer groups under its own prefix
without any extra configuration. Name your topics to match — dev.vote.api.events
rather than events — and the owning application needs no ACL entries at all.

Granting another application access

List the grant under acls in the Component of the user that owns the
topics. Write the topic without the <stage>.<tenant>. part and the user as
its short name; both are completed for you:

tenant: vote
user: api
acls:
  - topic: api.events        # becomes dev.vote.api.events
    role: reader
    user: ui                 # becomes dev-vote-ui-user
  - topic: api.commands.     # every topic starting with dev.vote.api.commands.
    role: multiwriter
    user: worker

Because both names are completed with the same tenant, acls grants access to
users in the same tenant. For a topic outside the naming convention, such as
a connector's internal topic, use rawAcls: its topic name is used exactly as
written.

ACL roles

Roles without multi apply to one exact topic name. Roles with multi apply to
every topic that starts with the given prefix, so end the prefix with a dot.

Role	Rights	Applies to
`reader`	Read	One topic
`multireader`	Read	Every topic with the prefix
`writer`	Write, which includes read	One topic
`multiwriter`	Write, which includes read	Every topic with the prefix
`admin`	All operations	One topic
`multiadmin`	All operations	Every topic with the prefix
`readcluster`	Read cluster metadata	The cluster (the `topic` value is ignored)

Consumer groups

A user can always join consumer groups under its own <stage>.<tenant>.<user>.
prefix. To let it join another group, add the group's name without the stage
and tenant:

user: api
consumerGroups:
  - name: reporting.        # lets dev-vote-api-user join dev.vote.reporting.*

Reading an authorisation error

Error	What is missing
`TOPIC_AUTHORIZATION_FAILED` / `TopicAuthorizationException`	An ACL for this user on that topic, with a role that allows the operation.
`GROUP_AUTHORIZATION_FAILED` / `GroupAuthorizationException`	The consumer group under the user's prefix or in `consumerGroups`.
`CLUSTER_AUTHORIZATION_FAILED` on a producer	`idempotent: true` for a transactional producer.
`UNKNOWN_TOPIC_OR_PARTITION`	The topic does not exist. Topics are never created automatically — declare it first, see Kafka Access, ACLs and Topics.
Authentication fails right after a change	The new user or password has not reached the cluster yet. Wait a minute or two and restart the client.