Reference: KafkaUser CRD¶
The KafkaUser custom resource defines a Kafka client identity: how it
authenticates, which access control list (ACL) rules apply to it, and which
quotas limit it. The Strimzi User Operator creates the user in Kafka and, for
the scram-sha-512 and tls authentication types, writes the credentials to a
Kubernetes Secret with the same name as the KafkaUser. You grant
permissions in spec.authorization of the KafkaUser. Strimzi has no separate
ACL resource.
| Property | Value |
|---|---|
apiVersion |
kafka.strimzi.io/v1 |
kind |
KafkaUser |
| Scope | Namespaced |
| Short name | ku |
This page documents Strimzi 1.3.1.
Example¶
This user authenticates with SCRAM-SHA-512, can produce to and consume from the
my-app-orders topic, and consumes as part of the my-app-group consumer
group.
apiVersion: kafka.strimzi.io/v1
kind: KafkaUser
metadata:
name: my-app-user
namespace: your-application-namespace
labels:
# Required. The name of the Kafka cluster we provisioned for you.
strimzi.io/cluster: my-kafka-cluster
spec:
authentication:
type: scram-sha-512
authorization:
type: simple
acls:
# Producer access
- resource:
type: topic
name: my-app-orders
patternType: literal
operations:
- Describe
- Write
# Consumer access
- resource:
type: topic
name: my-app-orders
patternType: literal
operations:
- Describe
- Read
- resource:
type: group
name: my-app-group
patternType: literal
operations:
- Read
quotas:
producerByteRate: 1048576 # 1 MiB/s per broker
consumerByteRate: 2097152 # 2 MiB/s per broker
Required Metadata¶
| Field | Description |
|---|---|
metadata.labels."strimzi.io/cluster" |
Required. The name of the Kafka cluster resource the user belongs to. If the label is missing or does not match the cluster, the User Operator ignores the resource, the user is not created, and the status stays empty. |
metadata.name |
The Kafka username, and the name of the generated Secret. |
Specification (spec)¶
The spec block is required.
| Field | Type | Description |
|---|---|---|
authentication |
object |
Optional. How the user authenticates and which credentials Strimzi generates. See spec.authentication. If you omit it, Strimzi generates no credentials. |
authorization |
object |
Optional. The ACL rules for the user. See spec.authorization. If you omit it, the User Operator grants the user no access rights. |
quotas |
object |
Optional. Limits on network bandwidth and request rate. See spec.quotas. |
template |
object |
Optional. Labels and annotations for the generated Secret. See spec.template. |
spec.authentication¶
The type field selects the authentication mechanism. The type must match the
authentication that the Kafka listener you connect to uses.
| Field | Type | Description |
|---|---|---|
type |
string |
Required. One of scram-sha-512, tls, or tls-external. See the table below. |
password |
object |
Optional. Only for scram-sha-512. Reads the password from an existing Secret instead of generating one. See spec.authentication.password. |
validityDays |
integer |
Optional. Only for tls. Number of days the user certificate is valid. Minimum 1, and must be greater than renewalDays. Set it together with renewalDays. Defaults to the clients certificate authority (CA) setting of the cluster. |
renewalDays |
integer |
Optional. Only for tls. Number of days before expiry when the User Operator renews the certificate. Minimum 1, and must be less than validityDays. Set it together with validityDays. Defaults to the clients CA setting of the cluster. |
type |
What Strimzi generates | Principal used in ACLs and quotas |
|---|---|---|
scram-sha-512 |
A Secret with a SASL SCRAM-SHA-512 password. |
<username> |
tls |
A Secret with a client certificate and key for mutual TLS (mTLS), signed by the cluster's clients CA. |
CN=<username> |
tls-external |
Nothing. You bring a certificate issued outside Strimzi, with <username> as the common name. |
CN=<username> |
The API server rejects a KafkaUser that sets validityDays or renewalDays
with any type other than tls, sets only one of the two, or sets renewalDays
greater than or equal to validityDays.
spec.authentication.password¶
Use this to supply your own SCRAM-SHA-512 password, for example one you sync from a secrets store.
| Field | Type | Description |
|---|---|---|
valueFrom.secretKeyRef.name |
string |
Required. Name of a Secret in the same namespace as the KafkaUser. |
valueFrom.secretKeyRef.key |
string |
Required. Key in that Secret that holds the password. |
valueFrom.secretKeyRef.optional |
boolean |
Optional. Standard Kubernetes SecretKeySelector field. |
spec:
authentication:
type: scram-sha-512
password:
valueFrom:
secretKeyRef:
name: my-app-kafka-password
key: password
spec.authorization¶
| Field | Type | Description |
|---|---|---|
type |
string |
Required. Must be simple. Strimzi manages the ACL rules through the Kafka Admin API. |
acls |
[]object |
Required. The list of ACL rules for this user. See spec.authorization.acls[]. An empty list grants nothing. |
spec.authorization.acls[]¶
Each entry is one rule that allows or denies a list of operations on one resource.
| Field | Type | Description |
|---|---|---|
resource |
object |
Required. The Kafka resource the rule applies to. See spec.authorization.acls[].resource. |
operations |
[]string |
Required. The operations to allow or deny. Allowed values are Read, Write, Create, Delete, Alter, Describe, ClusterAction, AlterConfigs, DescribeConfigs, IdempotentWrite, and All. Only some operations apply to each resource type. See Kafka authorization and ACLs. |
type |
string |
Optional. allow or deny. Defaults to allow. A deny rule takes precedence over an allow rule that matches the same request. |
host |
string |
Optional. The client host the rule applies to. Defaults to *, which means any host. |
spec.authorization.acls[].resource¶
| Field | Type | Description |
|---|---|---|
type |
string |
Required. One of topic, group (consumer group), cluster, or transactionalId. |
name |
string |
The resource name. Use it with topic, group, and transactionalId. Leave it out for cluster, which has no name. With patternType: literal, * matches all resources of the type. |
patternType |
string |
Optional. literal or prefix. Defaults to literal. With literal, name must match the resource name exactly. With prefix, the rule applies to every resource whose name starts with name. Not used with cluster. |
The following rules cover the common client roles. They follow the upstream Strimzi examples.
| Client role | Resource | Operations |
|---|---|---|
| Producer | topic |
Describe, Write. Add Create if the client creates the topic itself. |
| Consumer | topic |
Describe, Read |
| Consumer | group (the client's group.id) |
Read |
This rule grants read access to every topic that starts with my-app-:
spec.quotas¶
Quotas limit how much of the broker resources the user's clients can consume. Kafka throttles clients that exceed a quota. All fields are optional.
| Field | Type | Description |
|---|---|---|
producerByteRate |
integer |
Maximum bytes per second that the user's clients can publish to each broker. Minimum 0. |
consumerByteRate |
integer |
Maximum bytes per second that the user's clients can fetch from each broker. Minimum 0. |
requestPercentage |
integer |
Maximum CPU utilization of the user's clients, as a percentage of the broker network and I/O threads. Minimum 0. |
controllerMutationRate |
number |
Maximum rate at which the cluster accepts create topic, create partition, and delete topic requests, counted in partitions created or deleted. Minimum 0. |
spec.template¶
| Field | Type | Description |
|---|---|---|
secret.metadata.labels |
map[string]string |
Optional. Labels to add to the generated Secret. |
secret.metadata.annotations |
map[string]string |
Optional. Annotations to add to the generated Secret. |
Generated Secret¶
For scram-sha-512 and tls, the User Operator creates a Secret with the
same name as the KafkaUser in the same namespace. All values are base64
encoded.
| Authentication | Key | Content |
|---|---|---|
scram-sha-512 |
password |
The generated password, or the password from spec.authentication.password. |
scram-sha-512 |
sasl.jaas.config |
A complete JAAS configuration string for SASL SCRAM-SHA-512. |
tls |
ca.crt |
Public key of the clients CA that signed the user certificate. |
tls |
user.crt |
The user certificate. |
tls |
user.key |
The user private key. |
tls |
user.p12 |
A PKCS #12 store with the user certificate and key. |
tls |
user.password |
The password that protects user.p12. |
Status (status)¶
Run kubectl get kafkauser <name> -o yaml to see the status.
| Field | Description |
|---|---|
conditions |
List of conditions. A Ready condition with status True means the user, its ACLs, and its quotas exist in Kafka. Otherwise reason and message explain the problem. |
observedGeneration |
The resource generation the User Operator last reconciled. If it is lower than metadata.generation, the operator has not yet processed your latest change. |
username |
The Kafka username. |
secret |
The name of the Secret that holds the credentials. |
kubectl get kafkausers also shows the cluster, authentication type,
authorization type, and readiness in its default output.
Platform Notes¶
- We provision and manage the
Kafkacluster resource for you, including high availability, upgrades, and the underlying infrastructure. You do not create or edit it. Reference it by name in thestrimzi.io/clusterlabel. We give you the cluster name when we provision the cluster. Contact us to have one provisioned. - A new user has no permissions. You must grant access to topics and consumer
groups explicitly in
spec.authorization. - Clients connect to the bootstrap address
<cluster-name>-kafka-bootstrap.<namespace>.svc.cluster.local:9093with SASL SCRAM-SHA-512 authentication and TLS encryption. Useauthentication.type: scram-sha-512for this listener.
Further Reading¶
- Strimzi: Using the User Operator to manage Kafka users
- Strimzi: Configuring user (client-side) security mechanisms
- Strimzi:
KafkaUserschema reference - Strimzi:
AclRuleschema reference - Apache Kafka: Authorization and ACLs
- Apache Kafka: Quotas
- Getting Started with Event Streaming
- Reference:
KafkaTopicCRD