Table of Contents

Status

Current state: Under discussionAccepted - 2.6.0 contains describe and alter functionality, resolve is pending for a future release.

Discussion thread: TODO here

JIRA: KAFKA-7740

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

Motivation

Quota management via Admin Client has gone through a couple drafts of proposals (KIP -248, KIP-422). While improvements have been made to the Admin interface for configuration handling, fitting quotas into the API is awkward as they don't fit the natural key-value pairing, nor is the configuration output expressive enough to return all useful information. Therefore, it'd be beneficial to have a quota-native API for managing quotas, which would offer an intuitive and less error-prone interface, convey additional information beyond what the configuration APIs provide, and enable for future extensibility as quotas types are added or evolved.

Background

By default, quotas are defined in terms of a user and client ID, where the user acts as an opaque principal name, and the client ID as a generic group identifier. When setting quotas, an administrator has flexibility in how it specifies the user and client ID for which the quota applies, where the user and client ID may be specifically named, indicated as a default, or omitted entirely. Since quotas have flexible configurations, there is a method for resolving the quotas that apply to a request: a hierarchy structure is used, where the most specific defined quota will be matched to a request's user and client ID.

...

As such, reasoning around quotas can be complex, as it's not immediately obvious which quotas may apply to a given user and/or client ID. Providing descriptive information about how quotas are matched is the first goal of this KIP. Likewise, retrieving and modifying quota values can be done in a more expressive and robust way, which is the second goal of the KIP.

APIs

In order to clearly specify the APIs, let's first disambiguate some terminology: Every client request that is processed is associated with a quota entity, which is a map of entity types to their corresponding entity names for the request. Using the current entity types, an entity is of the form {user=test-user, client-id=test-client}, where user and client-id are the types, and test-user and test-client are the names. However, when specifying a quota configuration entry, only a subset of the entity types need to be provided, which is referred to as an entity match, for example, {user=<default>}.

...

The config-centric mode describes what is exactly specified for the configuration for the given entity match. However, it would also be useful to also be able to determine which matches have configuration values defined, so the presence of a filter is used for gathering information about the entity matches that the administrator is interested in. This is DescribeClientQuotas.
The entity-centric mode describes what quotas apply to an entity. Note that an entity may match to various configuration entries depending on how the quotas are specified, e.g. the producer byte rate may be specified for the user, but the consumer byte rate for the client ID. Since it may not be clear how quotas were matched for an entity from the configuration, additional information should be returned to provide more context. This is DescribeEffectiveClientQuotas ResolveClientQuotas.

Altering quotas only works on a config-centric manner, and therefore doesn't need distinguishing. For a given entity match, the administrator should be able to specify which quotas apply, or alternatively remove existing quotas so they no longer match. This is AlterClientQuotas.

Units

This KIP introduces the concept of a quota unit to be applied to a quota value. Currently, only a single unit is used for quotas: bytes-per-second, however this has limitations to effective quota management. For example, since it's a global throughput value, it doesn't scale well as brokers are added or removed, and so a broker-bytes-per-second unit could be added to better manage this behavior. As units are added, the possible quota configuration entries becomes the cross product of the quota types by the quota units, which means that it'd be possible to specify bytes-per-second both on a global and per-broker basis, and quota enforcement would occur at whichever limit was hit first. Additional considerations could be made for a fair-share system, where units of shares could be configured for quotas, and when bandwidth is contested, the share count of the active entities could be used to determine their restricted throughput.

It's beyond the scope of this KIP to add new units and implement their corresponding functionality in the broker, however it must be noted for future extensibility of the APIs.

Types Rationale

While there's two defined entity types in AK, a server-side plugin mechanism allows for further expansion. Likewise, as use cases evolve, finer-grained quota control may be necessary. Therefore, entity types should not be statically bound to publicly defined constants, and instead the API should support flexible entity types by interpreting them as a String identifier. Any entity types that the broker doesn't understand should throw an IllegalArgumentException back to the client.

The quota types (producer byte rate, consumer byte rate, etc.) and units should also be given the same consideration. The possible quota applications may expand in the future, and the API shouldn't lock in which quota types are accessible. Modification of quota types/units that are unknown should also fail with error.

Since a fixed set of entity types aren't defined, an entity should be represented by a Map<String, String>, which maps an entity type to the entity name.

Public Interfaces

Admin client calls will be added to correspond to DescribeClientQuotas, DescribeEffectiveClientQuotas, and AlterClientQuotas, with supporting types defined in the common.quotas package.

Common types in package org.apache.kafka.common.quota:

The quota values are of type Double, which presents a complication in that the RPC protocol doesn't support floating point values. To accommodate this, RPC protocol message type 'double' will be added, which will serialize doubles according to the IEEE 754 floating-point "double format" bit layout.

Types Rationale

While there's two defined entity types in AK, a server-side plugin mechanism allows for further expansion. Likewise, as use cases evolve, finer-grained quota control may be necessary. Therefore, entity types should not be statically bound to publicly defined constants, and instead the API should support flexible entity types by interpreting them as a String identifier. Any entity types that the broker doesn't understand should throw an IllegalArgumentException back to the client.

The quota types (producer byte rate, consumer byte rate, etc.) should also be given the same consideration. The possible quota applications may expand in the future, and the API shouldn't lock in which quota types are accessible. Modification of quota types that are unknown should also fail with error.

Since a fixed set of entity types aren't defined, an entity should be represented by a Map<String, String>, which maps an entity type to the entity name.

Public Interfaces

Admin client calls will be added to correspond to DescribeClientQuotas, ResolveClientQuotas, and AlterClientQuotas, with supporting types defined in the common.quotas package.

Common types in package org.apache.kafka.common.quota (2.6.0)

Code Block

language	java

/**
 * Describes a client quota entity, which is a mapping of entity types to their names.
 */
public class ClientQuotaEntity {

    /**
     * The type of an entity entry.
     */
    public static final String USER = "user";
    public static final String CLIENT_ID = "client-id";

    /**
     * Constructs a quota entity for the given types and names. If a name is null,
     * then it is mapped to the built-in default entity name.
     *
     * @param entries maps entity type to its name
     */
    public ClientQuotaEntity(Map<String, String> entries);

Code Block

language	java

/**
 * Describes a fully-qualified entity.
 */
public class QuotaEntity {
    /**
     * @return Typemap of entity type anto entityits entry.name
     */
    public enumMap<String, Type {
        USER,
        CLIENT_ID,String> entries();
}

/**
 * Describes a component for applying a client quota filter.
 */
public class ClientQuotaFilterComponent {

    /**
     * Constructs and UNKNOWN;
returns a filter component }

that exactly matches  /**the provided entity
     * Represents the default name for anthe entity, itype.e.
  the entity that's matched*
     * when@param anentityType exactthe matchentity isn't found.
     */type the filter component applies to
    public final static String QUOTA_ENTITY_NAME_DEFAULT = // implementation defined* @param entityName the entity name that's matched exactly
     */
    public static ClientQuotaFilterComponent ofEntity(String entityType, String entityName);

    /**
     * `entries`Constructs describesand thereturns fully-qualified entity. The key is a {@code Type} string, howevera filter component that matches the built-in default entity name
     * for therethe mayentity alsotype.
 exist keys that are not*
 enumerated by {@code Type} that still apply, e.g.  * @param entityType the entity type the filter component applies to
     */
 the server may internallypublic associatestatic another type. When querying entities, it's necessaryClientQuotaFilterComponent ofDefaultEntity(String entityType);

    /**
     * toConstructs returnand allreturns quotaa typesfilter becausecomponent quotathat valuesmatches forany thesespecified typesname may influencefor the effective
     * quotaentity valuetype.
 However, when altering a quota,*
 any types that aren't specified* must@param beentityType able
the     * to be inferred byentity type the server,filter otherwisecomponent an error is returned.applies to
     */
    public *static For example, {("CLIENT_ID" -> "test-client"),ClientQuotaFilterComponent ofEntityType(String entityType);

     /**
     * @return the component's entity type
     ("USER" -> "test-user"),*/
    public * String entityType();

    /**
     * @return the optional  ("GROUP" -> "internal-group")}.match string, where:
     */
    public QuotaEntity(Map<String, String> entries);
}

/**
 * Describesif apresent, quotathe key.
 */
public class QuotaKey {
name that's matched exactly
     /**
      * The quota types.
if empty, matches the default */name
    public enum* Type {
       if CONSUMER_BYTE_RATEnull,
 matches any specified name
     PRODUCER_BYTE_RATE,*/
    public    REQUEST_PERCENTAGE,
        UNKNOWN;
    }Optional<String> match();
}

/**
 * Describes a client quota entity filter.
 */
public class ClientQuotaFilter {

    /**
     * TheA unitsfilter forto abe quotaapplied value.to Notematching thereclient mayquotas.
 be multiple units for a*
 given quota type
  * @param components *the thatcomponents influencesto quotafilter behavior.on
     */
 @param strict whether publicthe enumfilter Unitsonly {
includes specified components
      RATE_BPS,*/
    private ClientQuotaFilter(Collection<ClientQuotaFilterComponent> components, boolean UNKNOWN;
    }strict);

    /**
     * Constructs @paramand typereturns thea quota type
filter that matches all provided *components. @paramMatching unitsentities
 the units for the quota* type
with entity types that are not */
specified by a component publicwill QuotaKey(Type type, Units units);
}

/**
 * Describes a quota entity filter.
 */
public class QuotaFilter {
    /**also be included in the result.
     *
     * @param components the components for the filter
     * A filter to be applied./
    public static ClientQuotaFilter contains(Collection<ClientQuotaFilterComponent> components);

     /**
     * @param entityType the entity type the filter applies toConstructs and returns a quota filter that matches all provided components. Matching entities
     * @paramwith matchentity thetypes non-nullthat stringare that'snot matchedspecified exactly
by a component will  *not*/
 be included in publicthe QuotaFilter(QuotaEntity.Type entityType, String match);
}

DescribeClientQuotas:

Code Block

language	java

public class DescribeClientQuotasOptions extends AbstractOptions<DescribeClientQuotasOptions> {result.
     *
    // Empty.
}

/**
 * The result of the {@link Admin#DescribeClientQuotas(Collection<QuotaFilter>, DescribeClientQuotasOptions)} call.
* @param components the components for the filter
     */
    public class DescribeClientQuotasResult {static ClientQuotaFilter containsOnly(Collection<ClientQuotaFilterComponent> components);

    /**
     * Maps an entity to its configured quota value(s). Note if no value is defined for a quota Constructs and returns a quota filter that matches all configured entities.
     */
    public static ClientQuotaFilter all();

    /**
     * type@return forthe that entityfilter's components
 config, then it is not*/
 included in the resultingpublic value map.Collection<ClientQuotaFilterComponent> components();

     /**
     * @param@return entitieswhether the collection of entities that matched the filterfilter is strict, i.e. only includes specified components
     */
    public boolean DescribeClientQuotasResult(KafkaFuture<Map<QuotaEntity, Map<QuotaKey, Long>>> entitiesstrict();
}
    
/**
 * Describes   * Returns a map from quota entity to a future which canconfiguration alteration to be usedmade to checka theclient status of the operationquota entity.
     */
public class ClientQuotaAlteration {

 public KafkaFuture<Map<QuotaEntity, Map<QuotaKey, Long>>> entities();
}

public interfacestatic Adminclass extendsOp AutoCloseable {

    ...

    /**
     *  Describes all entities* matching@param allkey providedthe filtersquota (logicaltype AND)to thatalter
 have at least one
     * quota@param value defined.
     *if set then the existing value is updated,
     * @param filters filters to* apply to matching entities
     * @param options the options tootherwise use
if null, the existing value *is @returncleared
 result containing all matching entities
     */
    DescribeClientQuotasResult DescribeClientQuotas(Collection<QuotaFilter> filters, DescribeClientQuotasOptions options    public Op(String key, Double value);
}

DescribeEffectiveClientQuotas:

Code Block

language	java

public class DescribeEffectiveClientQuotasOptions extends AbstractOptions<DescribeEffectiveClientQuotasOptions> {

    /**
     *   Whether to* exclude@return the listquota type ofto overriddenalter
 values for every quota type in the result. */
     */
    public DescribeEffectiveClientQuotasOptionsString setOmitOverriddenValueskey(boolean omitOverriddenValues);
}

/**
 * The result of the {@link Admin#DescribeEffectiveClientQuotas(Collection<QuotaEntity>, DescribeEffectiveClientQuotasOptions)} call.
 */
public class DescribeEffectiveClientQuotasResult {
 /**
         /**
 @return if set then the *existing Informationvalue aboutis aupdated,
 specific quota configuration entry.
     */
     public class Entry {
 otherwise if null, the existing value is /**cleared
         */
 @param source the entity source for the value
public Double value();
    }

   * @paramprivate valuefinal the non-null valueClientQuotaEntity entity;
    private final    */Collection<Op> ops;

    /**
    public Entry(QuotaEntity source, Long value);
    }

    /*** @param entity the entity whose config will be modified
     * Information@param aboutops the valuealteration for a quota type.to perform
     */
    public class Value { ClientQuotaAlteration(ClientQuotaEntity entity, Collection<Op> ops);

        /**
     * @return the entity *whose @paramconfig entrywill thebe quota entrymodified
     */
    *public @param overriddenEntries all values that are overridden due to being lower in
    ClientQuotaEntity entity();

    /**
     * @return the alteration to perform
     */
    public Collection<Op> ops();
}

DescribeClientQuotas (2.6.0)

Code Block

language	java

public class DescribeClientQuotasOptions extends AbstractOptions<DescribeClientQuotasOptions> {
    // Empty.
}

/**
 * The result of the     specificity, or null if not requested{@link Admin#describeClientQuotas(Collection, DescribeClientQuotasOptions)} call.
 */
public class DescribeClientQuotasResult {

    /**
     */
 Maps an entity to its configured  public Value(Entry entry, List<Entry> overriddenEntries);
    }

quota value(s). Note if no value is defined for a quota
     /**
 type for that entity's *config, Mapsthen ait collectionis ofnot entitiesincluded toin theirthe effectiveresulting quotavalue valuesmap.
     *
     * @param entities future configfor the quota configuration forcollection of entities that matched the requested entitiesfilter
     */
    public DescribeEffectiveClientQuotasResultDescribeClientQuotasResult(Map<QuotaEntityKafkaFuture<Map<ClientQuotaEntity, KafkaFuture<Map<QuotaKeyMap<String, Value>>>Double>>> configentities);

    /**
     * Returns a map from quota entity to a future which can be used to check the status of the operation.
     */
    public Map<QuotaEntityKafkaFuture<Map<ClientQuotaEntity, KafkaFuture<Map<QuotaKeyMap<String, Value>>>Double>>> configentities();

    /**
     * Returns a future which succeeds only if all quota descriptions succeed.
     */
    public KafkaFuture<Void> all();
}

public interface Admin extends AutoCloseable {
    ...

    /**
     * Describes theall effectiveentities quotas formatching the provided entities.
     * filter that have at least one client quota configuration
     * @paramvalue entitiesdefined.
 the entities to describe the effective quotas for* <p>
     * @paramThe optionsfollowing theexceptions optionscan tobe use
anticipated when calling {@code get()} *on @return the effectivefuture quotas forfrom the entities
     */
 returned {@link DescribeClientQuotasResult}:
  DescribeEffectiveClientQuotasResult DescribeEffectiveClientQuotas(Collection<QuotaEntity> entities, DescribeEffectiveClientQuotasOptions* options);
}

AlterClientQuotas

Code Block

language	java
title	AlterQuotas

public class AlterClientQuotasEntry {
<ul>
     public* class Op <li>{@link org.apache.kafka.common.errors.ClusterAuthorizationException}
     *   /**
    If the authenticated user didn't have describe access to the cluster.</li>
     * @param key the quota type and units to alter
         * @param value if set then the existing value is updated,
         *              otherwise if null, the existing value is cleared
         */
        public Op(QuotaKey key, Long value);
    }

    /**
     * @param entity the entity whose config will be modified
     * @param ops the alteration to perform - if value is set, then the existing value is updated,
     *            otherwise if null, the existing value is cleared
     */
    public AlterClientQuotasEntry(QuotaEntity entity, Collection<Op> ops);
}

public class AlterClientQuotasOptions extends AbstractOptions<AlterClientQuotasOptions> {
    /**
     * Sets whether the request should be validated without altering the configs.
     */
    public AlterClientQuotasOptions validateOnly(boolean validateOnly);
}

/**
 * The result of the {@link Admin#AlterClientQuotas(Collection<AlterClientQuotasEntry>, AlterClientQuotasOptions)} call.
 *
 * The API of this class is evolving, see {@link Admin} for details.
 */
public class AlterClientQuotasResult {
    public AlterClientQuotasResult(Map<QuotaEntity, KafkaFuture<Void>> futures);

    /**
     * Returns a map from quota entity to a future which can be used to check the status of the operation.
     */
    public Map<QuotaEntity, KafkaFuture<Void>> values();

    /**
     * Returns a future which succeeds only if all quota alterations succeed.
     */
    public KafkaFuture<Void> all();
}

public interface Admin extends AutoCloseable {
    ...

    /**
     * Alters the quotas as specified for the entries.
     *
     * @param alterations the alterations to perform
     * @return the result of the alterations
     */
    AlterClientQuotasResult AlterClientQuotas(Collection<AlterClientQuotasEntry> entries, AlterClientQuotasOptions options);
}

kafka-client-quotas.sh/ClientQuotasCommand:

A ClientQuotasCommand would be constructed with an associated bin/kafka-client-quotas.sh script for managing quotas via command line, and would have three modes of operation, roughly correlating to each of the API calls:

List: Lists the quota entities for the given entity specification and their corresponding quota values, as explicitly specified in the configuration. The user may provide explicit entity types+names, or a pattern to apply to an entity type find matching entity names. If an entity type is omitted from the input, it is treated as a wildcard.
Describe: Describes the effective quotas for an entity, including contextual information about how those quotas were derived. This includes what configuration entries matched to the entity and, if requested, the overridden, less-specific matches for the entity.
Alter: Modifies a quota configuration entry in an incremental manner, i.e. specify which entries to add, update, and/or remove.

Flags

Various flags will be used to accomplish these operations.

Common flags:
--bootstrap-server: The standard bootstrap server.
--command-config: Property file for the Admin client.

Operations (mutually exclusive):
--list: Lists the entities that match the given specification, and prints out their configuration values.
--describe: Describes the effective quota values for an entity.
--alter: Alters the configuration for the given specification.

Entity specification flags (common to all):
--names: Comma-separated list of type=name pairs, e.g. "user=some-user,client-id=some-client-id"
--defaults: Comma-separated list of entity types with the default name, e.g. "defaults=user,client-id" (Note a separate flag is necessary since names are opaque.)

Exclusive to --list:
--prefix: Comma-separated prefix=name pairs, e.g. "user=test-".

Exclusive to --describe:
--show-overridden: Whether to include overridden config entries.

Exclusive to --alter:
--add: Comma-separated list of entries to add or update to the configuration, in format "name:unit=value".
--delete: Comma-separated list of entries to remove from the configuration, in format "name:unit".
--validate-only: If set, validates the alteration but doesn't perform it.

Input

When specifying configuration entries, the form: quota-name[:quota-unit][=quota-value] is used. For convenience, if no quota unit is specified, then the historical default RATE_BPS is used.

Output

In general, the output of the entities will be of the form: {entity-type=entity-name, ...}, where entity-name is sanitized for output since it is an opaque string. When displaying configuration values, the form: quota-name:quota-unit=quota-value.

When describing overridden entries in the DescribeEffectiveClientQuotas, the entry is prefixed by a * to denote it's not effective.

List:

Code Block

$./bin/kafka-client-quotas.sh --bootstrap-server localhost:9092 --list \
                              --names=client-id=my-client

{user=user-two, client-id=my-client}
consumer_byte_rate:shares=200
producer_byte_rate:bps=10000000

{user=user-one, client-id=my-client}
producer_byte_rate:broker_bps=2000000

{user=<default>, client-id=my-client}
consumer_byte_rate:shares=100
producer_byte_rate:broker_bps=500000

$./bin/kafka-client-quotas.sh --bootstrap-server localhost:9092 --list \
                              --prefix=user=user-

{user=user-two, client-id=my-client}
consumer_byte_rate:shares=200
producer_byte_rate:bps=10000000

{user=user-one, client-id=my-client}
producer_byte_rate:broker_bps=2000000

Describe:

Code Block

$./bin/kafka-client-quotas.sh --bootstrap-server localhost:9092 --describe \
                              --names=user=user-one,client-id=my-client

consumer_byte_rate:shares=200 {user=user-one, client-id=my-client}
producer_byte_rate:bps=10000000 {user=user-one, client-id=my-client}
producer_byte_rate:broker_bps=500000 {user=<default>, client-id=my-client}

$./bin/kafka-client-quotas.sh --bootstrap-server localhost:9092 --describe \
                              --names=user=user-two,client-id=my-client    \
                              --show-overridden

consumer_byte_rate:shares=100 {user=<default>, client-id=my-client}
producer_byte_rate:broker_bps=2000000 {user=user-two, client-id=my-client}
* producer_byte_rate:broker_bps=500000 {user=<default>, client-id=my-client}

Alter:

   <li>{@link org.apache.kafka.common.errors.InvalidRequestException}
     *   If the request details are invalid. e.g., an invalid entity type was specified.</li>
     *   <li>{@link org.apache.kafka.common.errors.TimeoutException}
     *   If the request timed out before the describe could finish.</li>
     * </ul>
     * <p>
     * This operation is supported by brokers with version 2.6.0 or higher.
     *
     * @param filter the filter to apply to match entities
     * @param options the options to use
     * @return the DescribeClientQuotasResult containing the result
     */
    DescribeClientQuotasResult describeClientQuotas(ClientQuotaFilter filter, DescribeClientQuotasOptions options);
}

ResolveClientQuotas (pending future release)

Code Block

language	java

public class ResolveClientQuotasOptions extends AbstractOptions<ResolveClientQuotasOptions> {
    // Empty.
}

/**
 * The result of the {@link Admin#resolveClientQuotas(Collection, ResolveClientQuotasOptions)} call.
 */
public class ResolveClientQuotasResult {
    /**
     * Information about a specific quota configuration entry.
     */
    public class Entry {
        /**
         * @param source the entity source for the value
         * @param value the non-null value
         */
        public Entry(QuotaEntity source, Double value);
    }

    /**
     * Information about the value for a quota type.
     *
     * NOTE: We maintain a `Value` class because additional information may be added, e.g.,
     *       a list of overridden entries.
     */
    public class Value {
        /**
         * @param entry the quota entry
         */
        public Value(Entry entry);
    }

    /**
     * Maps a collection of entities to their resolved quota values.
     *
     * @param config the quota configuration for the requested entities
     */
    public ResolveClientQuotasResult(Map<QuotaEntity, KafkaFuture<Map<String, Value>>> config);

    /**
     * Returns a map from quota entity to a future which can be used to check the status of the operation.
     */
    public Map<QuotaEntity, KafkaFuture<Map<String, Value>>> config();

    /**
     * Returns a future which succeeds only if all quota descriptions succeed.
     */
    public KafkaFuture<Void> all();
}

public interface Admin extends AutoCloseable {
    ...

    /**
     * Resolves the effective quota values for the provided entities.
     *
     * @param entities the entities to describe the resolved quotas for
     * @param options the options to use
     * @return the resolved quotas for the entities
     */
    ResolveClientQuotasResult resolveClientQuotas(Collection<QuotaEntity> entities, ResolveClientQuotasOptions options);
}

AlterClientQuotas (2.6.0)

Code Block

language	java
title	AlterQuotas

/**
 * Options for {@link Admin#alterClientQuotas(Collection, AlterClientQuotasOptions)}.
 *
 * The API of this class is evolving, see {@link Admin} for details.
 */
public class AlterClientQuotasOptions extends AbstractOptions<AlterClientQuotasOptions> {

    /**
     * Returns whether the request should be validated without altering the configs.
     */
    public boolean validateOnly();

    /**
     * Sets whether the request should be validated without altering the configs.
     */
    public AlterClientQuotasOptions validateOnly(boolean validateOnly);
}

/**
 * The result of the {@link Admin#alterClientQuotas(Collection, AlterClientQuotasOptions)} call.
 *
 * The API of this class is evolving, see {@link Admin} for details.
 */
@InterfaceStability.Evolving
public class AlterClientQuotasResult {

    /**
     * Maps an entity to its alteration result.
     *
     * @param futures maps entity to its alteration result
     */
    public AlterClientQuotasResult(Map<ClientQuotaEntity, KafkaFuture<Void>> futures);

    /**
     * Returns a map from quota entity to a future which can be used to check the status of the operation.
     */
    public Map<ClientQuotaEntity, KafkaFuture<Void>> values();

    /**
     * Returns a future which succeeds only if all quota alterations succeed.
     */
    public KafkaFuture<Void> all();
}

public interface Admin extends AutoCloseable {
    ...

    /**
     * Alters client quota configurations with the specified alterations.
     * <p>
     * Alterations for a single entity are atomic, but across entities is not guaranteed. The resulting
     * per-entity error code should be evaluated to resolve the success or failure of all updates.
     * <p>
     * The following exceptions can be anticipated when calling {@code get()} on the futures obtained from
     * the returned {@link AlterClientQuotasResult}:
     * <ul>
     *   <li>{@link org.apache.kafka.common.errors.ClusterAuthorizationException}
     *   If the authenticated user didn't have alter access to the cluster.</li>
     *   <li>{@link org.apache.kafka.common.errors.InvalidRequestException}
     *   If the request details are invalid. e.g., a configuration key was specified more than once for an entity.</li>
     *   <li>{@link org.apache.kafka.common.errors.TimeoutException}
     *   If the request timed out before the alterations could finish. It cannot be guaranteed whether the update
     *   succeed or not.</li>
     * </ul>
     * <p>
     * This operation is supported by brokers with version 2.6.0 or higher.
     *
     * @param entries the alterations to perform
     * @return the AlterClientQuotasResult containing the result
     */
    AlterClientQuotasResult alterClientQuotas(Collection<ClientQuotaAlteration> entries, AlterClientQuotasOptions options);
}

kafka-configs.sh/ConfigCommand (2.6.0)

As a result of introducing the APIs, the ConfigCommand will be updated to support the users and clients entity types when using the --bootstrap-server option. The modification to ConfigCommand was adopted in KIP-543, and usage will remain unchanged from the original --zookeeper functionality.

kafka-client-quotas.sh/ClientQuotasCommand (pending future release)

A ClientQuotasCommand would be constructed with an associated bin/kafka-client-quotas.sh script for managing quotas via command line, and would have three modes of operation, roughly correlating to each of the API calls:

Describe: Describes the quota entities for the given entity specification and their corresponding quota values, as explicitly specified in the configuration. The user may provide explicit entity types+names, or a pattern to apply to an entity type find matching entity names. If an entity type is omitted from the input, it is treated as a wildcard.
Resolve: Resolves the effective quotas for an entity, including contextual information about how those quotas were derived. This includes what configuration entries matched to the entity.
Alter: Modifies a quota configuration entry in an incremental manner, i.e. specify which entries to add, update, and/or remove.

Flags

Various flags will be used to accomplish these operations.

Common flags:
--bootstrap-server: The standard bootstrap server.
--command-config: Property file for the Admin client.

Operations (mutually exclusive):
--describe: Describes the entities that match the given specification, and prints out their configuration values.
--resolve: Resolves the effective quota values for an entity.
--alter: Alters the configuration for the given specification.

Entity specification flags (common to all):
--names: Comma-separated list of type=name pairs, e.g. "user=some-user,client-id=some-client-id"
--defaults: Comma-separated list of entity types with the default name, e.g. "defaults=user,client-id" (Note a separate flag is necessary since names are opaque.)

Exclusive to --describe: None.

Exclusive to --resolve: None.

Exclusive to --alter:
--add: Comma-separated list of entries to add or update to the configuration, in format "name=value".
--delete: Comma-separated list of entries to remove from the configuration, in format "name".
--validate-only: If set, validates the alteration but doesn't perform it.

Input

When specifying configuration entries, the form: quota-name[=quota-value] is used.

Output

In general, the output of the entities will be of the form: {entity-type=entity-name, ...}, where entity-name is sanitized for output since it is an opaque string. When displaying configuration values, the form: quota-name=quota-value.

Describe:

Code Block

$./bin/kafka-client-quotas.sh --bootstrap-server localhost:9092 --describe \
                              --names=client-id=my-client

{user=user-one, client-id=my-client}
consumer_byte_rate=4000000
producer_byte_rate=1000000

{user=user-two, client-id=my-client}
producer_byte_rate=2000000

{user=<default>, client-id=my-client}
consumer_byte_rate=1000000
producer_byte_rate=500000

Resolve:

Code Block

$./bin/kafka-client-quotas.sh --bootstrap-server localhost:9092 --resolve \
                              --names=user=user-two,client-id=my-client

consumer_byte_rate=2000000 {user=user-two, client-id=my-client}
producer_byte_rate=500000 {user=<default>, client-id=my-client}

Alter:

Code Block

$./bin/kafka-client-quotas.sh --bootstrap-server localhost:9092 --alter   \
                              --names=client-id=my-client --defaults=user \
                              --add=consumer_byte_rate=2000000            \
                              --delete=producer_byte_rate

<no output on success>

$./bin/kafka-client-quotas.sh --bootstrap-server localhost:9092 --describe \
                              --names=client-id=my-client --defaults=user

{user=<default>, client-id=my-client}
consumer_byte_rate=2000000

Proposed Changes

In addition to the API changes above, the following write protocol would be implemented:

DescribeClientQuotas (2.6.0)

Code Block

{
  "apiKey": 48,
  "type": "request",
  "name": "DescribeClientQuotasRequest",
  "validVersions": "0",
  "flexibleVersions": "none",
  "fields": [
    { "name": "Components", "type": "[]ComponentData", "versions": "0+",
      "about": "Filter components to apply to quota entities.", "fields": [
      { "name": "EntityType", "type": "string", "versions": "0+",
        "about": "The entity type that the filter component applies to." },
      { "name": "MatchType", "type": "int8", "versions": "0+",
        "about": "How to match the entity {0 = exact name, 1 = default name, 2 = any specified name}." },
      { "name": "Match", "type": "string", "versions": "0+", "nullableVersions": "0+",
        "about": "The string to match against, or null if unused for the match type." }
    ]},
    { "name": "Strict", "type": "bool", "versions": "0+",
      "about": "Whether the match is strict, i.e. should exclude entities with unspecified entity types." }
  ]
}

{
  "apiKey": 48,
  "type": "response",
  "name": "DescribeClientQuotasResponse",
  "validVersions": "0",
  "flexibleVersions": "none",
  "fields": [
    { "name": "ThrottleTimeMs", "type": "int32", "versions": "0+",
      "about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
    { "name": "ErrorCode", "type": "int16", "versions": "0+",
      "about": "The error code, or `0` if the quota description succeeded." },
    { "name": "ErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+",
      "about": "The error message, or `null` if the quota description succeeded." },
    { "name": "Entries", "type": "[]EntryData", "versions": "0+", "nullableVersions": "0+",
      "about": "A result entry.", "fields": [
      { "name": "Entity", "type": "[]EntityData", "versions": "0+",
        "about": "The quota entity description.", "fields": [
        { "name": "EntityType", "type": "string", "versions": "0+",
          "about": "The entity type." },
        { "name": "EntityName", "type": "string", "versions": "0+", "nullableVersions": "0+",
          "about": "The entity name, or null if the default." }
      ]},
      { "name": "Values", "type": "[]ValueData", "versions": "0+",
	"about": "The quota values for the entity.", "fields": [
        { "name": "Key", "type": "string", "versions": "0+",
          "about": "The quota configuration key." },
        { "name": "Value", "type": "float64", "versions": "0+",

Code Block

$./bin/kafka-client-quotas.sh --bootstrap-server localhost:9092 --describe \
                              --names=client-id=my-client --defaults=user  \
                              --add=producer_byte_rate:shares=100          \
                              --delete=producer_byte_rate:broker_bps

<no output on success>

$./bin/kafka-client-quotas.sh --bootstrap-server localhost:9092 --list     \
          "about": "The quota       configuration value." }
      ]}
     --names=client-id=my-client --defaults=user

{user=<default>, client-id=my-client}
consumer_byte_rate:shares=100
producer_byte_rate:shares=100

...

]}
  ]
}

ResolveClientQuotas (pending future release)

In addition to the API changes above, the following write protocol would be implemented:

...

Code Block

{
  "apiKey": 4850,
  "type": "request",
  "name": "DescribeClientQuotasRequestResolveClientQuotasRequest",
  "validVersions": "0",
  "flexibleVersions": "none",
  "fields": [
    { "name": "FilterEntity", "type": "[]QuotaFilterDataQuotaEntityData", "versions": "0+",
      "about": "FiltersThe toquota apply to quota entitiesentity description.", "fields": [
      { "name": "EntityType", "type": "string", "versions": "0+",
        "about": "The entity type that the filter applies to." },
      { "name": "MatchEntityName", "type": "string", "versions": "0+",
        "about": "The string to match againstentity name." }
    ]}
  ]
}

{
  "apiKey": 4850,
  "type": "response",
  "name": "DescribeClientQuotasResponseResolveClientQuotasResponse",
  "validVersions": "0",
  "flexibleVersions": "none",
  "fields": [
    { "name": "ThrottleTimeMs", "type": "int32", "versions": "0+",
      "about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
    { "name": "Entry", "type": "[]EntryDataQuotaEntryData", "versions": "0+",
      "about": "AResolved resultquota entryentries.", "fields": [
      { "name": "ErrorCode", "type": "int16", "versions": "0+",
        "about": "The error code, or `0` if the resolved quota description succeeded." },
      { "name": "ErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+",
        "about": "The error message, or `null` if the resolved quota description succeeded." },
      { "name": "EntityQuotaEntity", "type": "[]QuotaEntityDataQuotaEntity", "versions": "0+",
        "about": "TheResolved quota entity descriptionentries.", "fields": [
        { "name": "EntityType", "type": "string", "versions": "0+",
          "about": "The entity type." },
        { "name": "EntityName", "type": "string", "versions": "0+",
          "about": "The entity name." }
      ]},
      { "name": "TypeQuotaValues", "type": "string[]QuotaValueData", "versions": "0+",
        "about": "TheQuota quotaconfiguration type." },
      { "name": "Units", "type": "string", "versions": "0+",
        "about": "The units for the value." },
values.", "fields": [
        { "name": "ValueType", "type": "int64string", "versions": "0+",
          "about": "The quota valuetype." },
      ]}
  ]
}

DescribeEffectiveClientQuotas:

Code Block

{
  "apiKeyname": 49"Entry",
  "type": "request[]ValueEntryData",
  "nameversions": "DescribeEffectiveClientQuotasRequest0+",
  "validVersions": "0",
        "flexibleVersionsabout": "noneQuota value entries.",
  "fields": [
          { "name": "EntityQuotaEntity", "type": "[]QuotaEntityDataValueQuotaEntity", "versions": "0+",
            "about": "TheResolved quota entity descriptionentries.", "fields": [
            { "name": "EntityType", "type": "string", "versions": "0+",
              "about": "The entity type." },
            { "name": "EntityName", "type": "string", "versions": "0+",
              "about": "The entity name." }
          ]},
          { "name": "OmitOverriddenValuesValue", "type": "booldouble", "versions": "0+",
            "about": "WhetherThe toquota excludeconfiguration the list of overridden values for every quota type." value." }
        ]}
      ]}
    ]}
  ]
}

AlterClientQuotas (2.6.0)

Code Block

{
  "apiKey": 49,
  "type": "responserequest",
  "name": "DescribeEffectiveClientQuotasResponseAlterClientQuotasRequest",
  "validVersions": "0",
  "flexibleVersions": "none",
  "fields": [
    { "name": "ThrottleTimeMsEntries", "type": "int32[]EntryData", "versions": "0+",
      "about": "The durationquota in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
    configuration entries to alter.", "fields": [
      { "name": "EntryEntity", "type": "[]QuotaEntryDataEntityData", "versions": "0+",
        "about": "EffectiveThe quota entity entriesto alter.", "fields": [
        { "name": "ErrorCodeEntityType", "type": "int16string", "versions": "0+",
          "about": "The error code, or `0` if the effective quota description succeededentity type." },
        { "name": "ErrorMessageEntityName", "type": "string", "versions": "0+", "nullableVersions": "0+",
          "about": "The error messageThe name of the entity, or `null`null if the effective quota description succeeded."  default." }
      ]},
      { "name": "QuotaEntityOps", "type": "[]QuotaEntityOpData", "versions": "0+",
        "about": "EffectiveAn individual quota entries configuration entry to alter.", "fields": [
        { "name": "EntityTypeKey", "type": "string", "versions": "0+",
          "about": "The entityquota configuration typekey." },
        { "name": "EntityNameValue", "type": "stringfloat64", "versions": "0+",
          "about": "The entity name." }
      ]},
 value to set, otherwise ignored if the value is to be removed." },
        { "name": "QuotaValuesRemove", "type": "[]QuotaValueDatabool", "versions": "0+",
          "about": "Whether the quota configuration value should be removed, otherwise set." }
 "about": "Quota configuration values.", "fields": [ ]}
    ]},
    { "name": "TypeValidateOnly", "type": "stringbool", "versions": "0+",
          "about": "TheWhether quotathe type." },
        { "name": "Units", alteration should be validated, but not performed." }
  ]
}

{
  "apiKey": 49,
  "type": "stringresponse",
  "versionsname": "0+AlterClientQuotasResponse",
          "aboutvalidVersions": "The0",
 units for the quota type." } "flexibleVersions": "none",
    "fields": [
    { "name": "EntryThrottleTimeMs", "type": "[]ValueEntryDataint32", "versions": "0+",
          "about": "Quota value entries.", "fields": [
      The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
    { "name": "QuotaEntityEntries", "type": "[]ValueQuotaEntityEntryData", "versions": "0+",
            "about": "EffectiveThe quota configuration entries to alter.", "fields": [
            { "name": "EntityTypeErrorCode", "type": "stringint16", "versions": "0+",
              "about": "The entity type." },
       error code, or `0` if the quota alteration succeeded." },
      { "name": "EntityNameErrorMessage", "type": "string", "versions": "0+",
 "nullableVersions": "0+",
            "about": "The entity name." }
          ]error message, or `null` if the quota alteration succeeded." },
          { "name": "ValueEntity", "type": "int64[]EntityData", "versions": "0+",
            "about": "The quota entity configurationto valuealter." }
        ]}
      ]}
, "fields": [
      ]}
  ]
}

AlterClientQuotas:

Code Block

{
  "apiKeyname": 50"EntityType",
  "type": "requeststring",
  "nameversions": "AlterClientQuotasRequest0+",
   "validVersions       "about": "0",
The entity type."flexibleVersions": "none" },
   "fields": [
    { "name": "EntryEntityName", "type": "[]EntryDatastring", "versions": "0+", "nullableVersions": "0+",
          "about": "The quota configuration entries to alter.", "fields": [ name of the entity, or null if the default." }
      { "name": "QuotaEntity", "type": "[]QuotaEntity", "versions": "0+",
        "about": "The quota entity to alter.", "fields": [
        { "name": "EntityType", "type": "string", "versions": "0+",]}
    ]}
  ]
}

Kafka RPC 'double' support (2.6.0)

Note that, while the ByteBuffer natively supports serializing a Double, the format in which the value is serialized is not strongly specified, so the preference is to explicitly ensure a standard representation of double-precision 64-bit IEEE 754 format. This is achieved in Java using Double.doubleToRawLongBits() and Double.longBitsToDouble() and should be easily portable to other languages.

Code Block

title	clients/src/main/java/org/apache/kafka/common/utils/ByteUtils.java

    /**
     * Read a double-precision  "about": "The entity type." },64-bit format IEEE 754 value.
     *
   { "name": "EntityName", "type": "string", "versions": "0+",
    * @param buffer The buffer to read from
     * @return "about": "The namelong ofvalue theread
 entity." }
   */
   ]},
 public static double readDouble(ByteBuffer  { "name": "Op", "type": "[]OpData", "versions": "0+",
        "about": "An individual quota configuration entry to alter.", "fields": [
        { "name": "Type", "type": "string", "versions": "0+",
          "about": "The quota type." },buffer) {
        return Double.longBitsToDouble(buffer.getLong());
    }

    /**
     * Write the given double following the double-precision 64-bit format IEEE 754 value into the buffer.
     *
     * @param value The value to write
     * @param buffer The buffer to { "name": "Units", "type": "string", "versions": "0+",write to
     */
    public static void writeDouble(double value, ByteBuffer buffer) {
  "about": "The units for the quota type." },buffer.putLong(Double.doubleToRawLongBits(value));
    }

The protocol type definition:

Code Block

title	clients/src/main/java/org/apache/kafka/common/protocol/types/Type.java

    { "name": "Value", "type": "int64", "versions": "0+",
  public static final DocumentedType DOUBLE = new DocumentedType() {
        "about": "The value to set, otherwise ignored if the value is to be removed." },
@Override
        public void write(ByteBuffer buffer, Object o) {
         { "name": "Remove", "type": "bool", "versions": "0+", ByteUtils.writeDouble((Double) o, buffer);
        }

   "about": "Whether the quota configuration value@Override
 should be removed, otherwise set." }
  public Object read(ByteBuffer buffer) ]}{
    ]},
    { "name": "ValidateOnly", "type": "bool", "versions": "0+",
 return ByteUtils.readDouble(buffer);
    "about": "Whether the alteration should}

 be validated, but not performed." }
  ]
}

{@Override
  "apiKey": 50,
  "type": "response",
  "name": "AlterClientQuotasResponse",
  "validVersions": "0",
  "flexibleVersions": "none",
  "fields": [
public int sizeOf(Object o) {
          { "name": "ThrottleTimeMs", "type": "int32", "versions": "0+",
 return 8;
         "about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." },
    { "name": "Entry", "type": "[]EntryData", "versions": "0+",}

        @Override
        public String typeName() {
            return "DOUBLE";
        }

      "about": "The quota@Override
 configuration entries to alter.", "fields": [
  public Double validate(Object item) {
 "name": "ErrorCode", "type": "int16", "versions": "0+",
      if  "about": "The error code, or `0` if the quota alteration succeeded." },
(item instanceof Double)
                { "name": "ErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+",
return (Double) item;
            else
 "about": "The error message, or `null` if the quota alteration succeeded." },
    throw new { "name": "QuotaEntity", "type": "[]QuotaEntity", "versions": "0+",SchemaException(item + " is not a Double.");
        "about": "The quota entity to alter.", "fields": [}

        @Override
        public String documentation() {
 "name": "EntityType", "type": "string", "versions": "0+",
           return "Represents a double-precision  "about": "The entity type." },64-bit format IEEE 754 value. " +
        { "name": "EntityName", "type": "string", "versions": "0+",
            "The values are encoded using eight "about": "The name of the entity." }
bytes in network byte order (big-endian).";
        ]}
    ]}
  ]
}};

In generator/src/main/java/org/apache/kafka/message/MessageGenerator.java, the following operations will be used (code omitted for brevity):

Code Block

title	generator/src/main/java/org/apache/kafka/message/MessageGenerator.java

Hash code: Double.hashCode(value)

Empty value: (double) 0

Parsing a default value string: Double.parseDouble(defaultValue)

Compatibility, Deprecation, and Migration Plan

All changes would be are forward-compatible, and no migration plan is necessary. It's outside the scope of this KIP to deprecate any functionality.

Rejected Alternatives

Use existing describeConfigs/incrementalAlterConfigs for quota functionality. This falls short for a couple reasons. First, quotas entity names are more dynamic than brokers and tasks which makes them awkward to fit into generic tools which expect a single unique, distinct key, e.g. ConfigCommand. Second, there's no tool that expresses a way to get the effective quota resolved quota for an entity without some heavy engineering on the client side, which lacks extensibility and is more expensive to perform, especially over large collection of entities. Therefore, it makes sense to approach quotas as a standalone set of APIs that provide more targeted information and can properly support future extensibility.

...

Space shortcuts

Child pages

Versions Compared

Old Version 44

New Version Current

Key

Status

Motivation

Background

APIs

Units

Types Rationale

Public Interfaces

Types Rationale

Public Interfaces

Common types in package org.apache.kafka.common.quota (2.6.0)

DescribeEffectiveClientQuotas:

DescribeClientQuotas (2.6.0)

AlterClientQuotas

Flags

Input

Output

ResolveClientQuotas (pending future release)

AlterClientQuotas (2.6.0)

kafka-configs.sh/ConfigCommand (2.6.0)

kafka-client-quotas.sh/ClientQuotasCommand (pending future release)

Flags

Input

Output

Proposed Changes

DescribeClientQuotas (2.6.0)

ResolveClientQuotas (pending future release)

AlterClientQuotas (2.6.0)

Kafka RPC 'double' support (2.6.0)

Compatibility, Deprecation, and Migration Plan

Rejected Alternatives

Space shortcuts

Child pages

Page History

Versions Compared

Old Version 44

New Version Current

Key

Status

Motivation

Background

APIs

Units

Types Rationale

Public Interfaces

Types Rationale

Public Interfaces

Common types in package org.apache.kafka.common.quota (2.6.0)

DescribeEffectiveClientQuotas:

DescribeClientQuotas (2.6.0)

AlterClientQuotas

Flags

Input

Output

ResolveClientQuotas (pending future release)

AlterClientQuotas (2.6.0)

kafka-configs.sh/ConfigCommand (2.6.0)

kafka-client-quotas.sh/ClientQuotasCommand (pending future release)

Flags

Input

Output

Proposed Changes

DescribeClientQuotas (2.6.0)

ResolveClientQuotas (pending future release)

AlterClientQuotas (2.6.0)

Kafka RPC 'double' support (2.6.0)

Compatibility, Deprecation, and Migration Plan

Rejected Alternatives