Skip to content

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-:

- resource:
    type: topic
    name: my-app-
    patternType: prefix
  operations:
    - Describe
    - Read

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 Kafka cluster resource for you, including high availability, upgrades, and the underlying infrastructure. You do not create or edit it. Reference it by name in the strimzi.io/cluster label. 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:9093 with SASL SCRAM-SHA-512 authentication and TLS encryption. Use authentication.type: scram-sha-512 for this listener.

Further Reading