Monedula
monedula-gitops docs menu

Set user, client-id and IP quotas

Limit producer and consumer byte rates, request percentage and connection creation rate with KafkaQuota, per user, client id or IP.

How-to guides 7 of 18

3 min read

Updated 5 October 2026

Markdown

On this page

Each KafkaQuota owns exactly one client quota entity and the limits set on it.

Before you start

  • Apache Kafka or Confluent Platform. KafkaQuota does not work on Confluent Cloud (Supported platforms).
  • A connecting principal with DescribeConfigs and AlterConfigs on the Cluster resource, or a super-user.

Steps

1. Limit a user

This quota caps User:svc-quota-user at 1 MiB per second for produce traffic and 2 MiB per second for consume traffic. Save it as manifests/quota.yaml:

apiVersion: gitops.monedula.dev/v1alpha1
kind: KafkaQuota
metadata:
  name: svc-quota
spec:
  clusterRef:
    name: shared
  entity:
    user: "User:svc-quota-user"
  limits:
    producerByteRate: 1048576
    consumerByteRate: 2097152

entity.user takes the principal form User:<name>. monedula-gitops strips the User: prefix for Kafka’s quota API, so the broker stores the quota for svc-quota-user.

2. Pick the entity and the limits

The entity says whom the quota applies to. It needs at least one component, and it cannot change after creation:

  • user and clientId target a specific user or client id. Set both to target that user and client id together.
  • userDefault: true and clientIdDefault: true target the default entity of that kind. user excludes userDefault, and clientId excludes clientIdDefault, but a default combines with a specific value of the other kind.
  • ip targets one IPv4 or IPv6 address, not a CIDR range or a host name, and ipDefault: true targets the IP default. An IP entity is a separate dimension and never combines with a user or client id.

limits takes at least one value, and every value must be 0 or more:

  • producerByteRate and consumerByteRate cap produce and fetch throughput in bytes per second.
  • requestPercentage caps the share of broker request-handler time. It is a percentage that may exceed 100 on brokers with several cores.
  • controllerMutationRate caps topic and partition creations and deletions, in mutations per second.
  • connectionCreationRate caps new connections per second. It is valid only on an IP entity, and it is the only limit an IP entity takes.

3. Limit connections from an IP address

This quota allows at most 100 new connections per second from 10.0.0.7. Save it next to the first one, as manifests/ip-quota.yaml:

apiVersion: gitops.monedula.dev/v1alpha1
kind: KafkaQuota
metadata:
  name: ip-quota
spec:
  clusterRef:
    name: shared
  entity:
    ip: "10.0.0.7"
  limits:
    connectionCreationRate: 100

4. Apply the quotas

monedula-gitops apply -f ./manifests --cluster-config-file ./cluster.yaml
kubectl apply -f manifests/

Setting a quota and changing a limit value need no approval: both are fully reversible.

5. Remove a limit

limits is authoritative for its entity: a limit that is live on the entity but missing from limits is removed. Removing a limit unthrottles clients, so it is gated: without approval, apply reports the removal as Blocked, exits 3 and leaves the limit in place.

With the CLI, approve the removal with --allow-destructive:

monedula-gitops apply -f ./manifests --cluster-config-file ./cluster.yaml --allow-destructive

With the operator, add the annotation gitops.monedula.dev/allow-destructive: "true" to the KafkaQuota.

The CLI only manages the quota entities that your manifests name. If you remove a KafkaQuota from your manifests, its quota stays in Kafka.

Check it worked

monedula-gitops verify -f ./manifests --cluster-config-file ./cluster.yaml
kubectl get kafkaquota svc-quota -o jsonpath='{.status.conditions}'
kubectl get kafkaquota ip-quota -o jsonpath='{.status.conditions}'

verify exits 0 when the live quotas match the manifests. With the operator, each KafkaQuota reports the conditions Ready and QuotaSynced with the status True. The broker now has a quota for the user svc-quota-user with producer_byte_rate=1048576 and consumer_byte_rate=2097152, and one for the IP 10.0.0.7 with connection_creation_rate=100.