THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
As represented by the current ZK node structure, the order in which quotas are matched are as follows. Note , from highest priority to lowest (note <user> is a specified user principal, <client-id> is a specified client ID, and <default> is a special default user/client ID that matches to all users or clients IDs.):
/config/users/<user>/clients/<client-id> /config/users/<user>/clients/<default> /config/users/<user> /config/users/<default>/clients/<client-id> /config/users/<default>/clients/<default> /config/users/<default> /config/clients/<client-id> /config/clients/<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 DescribeQuotas 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 DescribeEffectiveQuotas DescribeEffectiveClientQuotas.
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 AlterQuotas 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.
...
Admin client calls will be added to correspond to describeQuotas DescribeClientQuotas, describeEffectiveQuotas DescribeEffectiveClientQuotas, and alterQuotas AlterClientQuotas, with supporting types defined in the common.quotas package.
...
| Code Block | ||
|---|---|---|
| ||
/**
* Describes a fully-qualified entity.
*/
public class QuotaEntity {
/**
* Type of an entity entry.
*/
public enum Type {
USER,
CLIENT_ID,
UNKNOWN;
}
/**
* Represents the default name for an entity, i.e. the entity that's matched
* when an exact match isn't found.
*/
public final static String QUOTA_ENTITY_NAME_DEFAULT = // implementation defined
/**
* `entries` describes the fully-qualified entity. The key is a {@code Type} string, however
* there may also exist keys that are not enumerated by {@code Type} that still apply, e.g.
* the server may internally associate another type. When querying entities, it's necessary
* to return all quota types because quota values for these types may influence the effective
* quota value. However, when altering a quota, any types that aren't specified must be able
* to be inferred by the server, otherwise an error is returned.
*
* For example, {("CLIENT_ID" -> "test-client"),
* ("USER" -> "test-user"),
* ("GROUP" -> "internal-group")}.
*/
public QuotaEntity(Map<String, String> entries);
}
/**
* Describes a quota key.
*/
public class QuotaKey {
/**
* The quota types.
*/
public enum Type {
CONSUMER_BYTE_RATE,
PRODUCER_BYTE_RATE,
REQUEST_PERCENTAGE,
UNKNOWN;
}
/**
* The units for a quota value. Note there may be multiple units for a given quota type
* that influences quota behavior.
*/
public enum Units {
RATE_BPS,
UNKNOWN;
}
/**
* @param type the quota type
* @param units the units for the quota type
*/
public QuotaKey(Type type, Units units);
}
/**
* Describes a quota entity filter.
*/
public class QuotaFilter {
public/**
enum Rule {
* A filter to be applied.
EXACT, //*
exact name match
* @param entityType the entity type PREFIX;the filter applies //to
matches all names with the given prefix
}
/**
* A filtering rule to be applied.
*
* @param entityType the entity type the rule applies to
* @param rule the rule to apply
* @param match the non-null string that's applied by the rulematched exactly
*/
public QuotaFilter(QuotaEntity.Type entityType, Rule rule, String match);
}
|
DescribeQuotasDescribeClientQuotas:
| Code Block | ||
|---|---|---|
| ||
public class DescribeQuotasOptionsDescribeClientQuotasOptions extends AbstractOptions<DescribeQuotasOptions>AbstractOptions<DescribeClientQuotasOptions> { // Empty. } /** * The result of the {@link Admin#describeQuotasAdmin#DescribeClientQuotas(Collection<QuotaFilter>, DescribeQuotasOptionsDescribeClientQuotasOptions)} call. */ public class DescribeQuotasResultDescribeClientQuotasResult { /** * Maps an entity to its configured quota value(s). Note if no value is defined for a quota * type for that entity's config, then it is not included in the resulting value map. * * @param entities the collection of entities that matched the filter */ public DescribeQuotasResultDescribeClientQuotasResult(KafkaFuture<Map<QuotaEntity, Map<QuotaKey, Long>>> entities); /** * Returns a map from quota entity to a future which can be used to check the status of the operation. */ public KafkaFuture<Map<QuotaEntity, Map<QuotaKey, Long>>> entities(); } public interface Admin extends AutoCloseable { ... /** * Describes all entities matching all provided filters (logical AND) that have at least one * quota value defined. * * @param filters filteringfilters rules to apply to matching entities * @param options the options to use * @return result containing all matching entities */ DescribeQuotasResultDescribeClientQuotasResult describeQuotasDescribeClientQuotas(Collection<QuotaFilter> filters, DescribeQuotasOptionsDescribeClientQuotasOptions options); } |
...
DescribeEffectiveClientQuotas:
| Code Block | ||
|---|---|---|
| ||
public class DescribeEffectiveQuotasOptionsDescribeEffectiveClientQuotasOptions extends AbstractOptions<DescribeEffectiveQuotasOptions>AbstractOptions<DescribeEffectiveClientQuotasOptions> { /** * Whether to exclude the list of overridden values for every quota type in the result. */ public DescribeEffectiveQuotasOptionsDescribeEffectiveClientQuotasOptions setOmitOverriddenValues(boolean omitOverriddenValues); } /** * The result of the {@link Admin#describeEffectiveQuotasAdmin#DescribeEffectiveClientQuotas(Collection<QuotaEntity>, DescribeEffectiveQuotasOptionsDescribeEffectiveClientQuotasOptions)} call. */ public class DescribeEffectiveQuotasResultDescribeEffectiveClientQuotasResult { /** * 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, Long value); } /** * Information about the value for a quota type. */ public class Value { /** * @param entry the quota entry * @param overriddenEntries all values that are overridden due to being lower in * specificity, or null if not requested */ public Value(Entry entry, List<Entry> overriddenEntries); } /** * Maps a collection of entities to their effective quota values. * * @param config the quota configuration for the requested entities */ public DescribeEffectiveQuotasResultDescribeEffectiveClientQuotasResult(Map<QuotaEntity, KafkaFuture<Map<QuotaKey, 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<QuotaKey, Value>>> config(); /** * Returns a future which succeeds only if all quota descriptions succeed. */ public KafkaFuture<Void> all(); } public interface Admin extends AutoCloseable { ... /** * Describes the effective quotas for the provided entities. * * @param entities the entities to describe the effective quotas for * @param options the options to use * @return the effective quotas for the entities */ DescribeEffectiveQuotasResultDescribeEffectiveClientQuotasResult describeEffectiveQuotasDescribeEffectiveClientQuotas(Collection<QuotaEntity> entities, DescribeEffectiveQuotasOptionsDescribeEffectiveClientQuotasOptions options); } |
...
AlterClientQuotas
| Code Block | ||||
|---|---|---|---|---|
| ||||
public class AlterQuotasEntryAlterClientQuotasEntry { public class Op { /** * @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 AlterQuotasEntryAlterClientQuotasEntry(QuotaEntity entity, Collection<Op> ops); } public class AlterQuotasOptionsAlterClientQuotasOptions extends AbstractOptions<AlterQuotasOptions>AbstractOptions<AlterClientQuotasOptions> { /** * Sets whether the request should be validated without altering the configs. */ public AlterQuotasOptionsAlterClientQuotasOptions validateOnly(boolean validateOnly); } /** * The result of the {@link Admin#alterQuotasAdmin#AlterClientQuotas(Collection<AlterQuotasEntry>Collection<AlterClientQuotasEntry>, AlterQuotasOptionsAlterClientQuotasOptions)} call. * * The API of this class is evolving, see {@link Admin} for details. */ public class AlterQuotasResultAlterClientQuotasResult { public AlterQuotasResultAlterClientQuotasResult(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 */ AlterQuotasResultAlterClientQuotasResult alterQuotasAlterClientQuotas(Collection<AlterQuotasEntry>Collection<AlterClientQuotasEntry> entries, AlterQuotasOptionsAlterClientQuotasOptions options); } |
kafka-client-quotas.sh/QuotasCommandClientQuotasCommand:
A QuotasCommand 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:
...
Exclusive to --describe:--includeshow-overridesoverridden: 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: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.
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 \ --includeshow-overridesoverridden 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:
| 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 \ --names=client-id=my-client --defaults=user {user=<default>, client-id=my-client} consumer_byte_rate:shares=100 producer_byte_rate:shares=100 |
...
In addition to the API changes above, the following write protocol would be implemented:
DescribeQuotasDescribeClientQuotas:
| Code Block |
|---|
{
"apiKey": 48,
"type": "request",
"name": "DescribeQuotasRequestDescribeClientQuotasRequest",
"validVersions": "0",
"flexibleVersions": "none",
"fields": [
{ "name": "Filter", "type": "[]QuotaFilterData", "versions": "0+",
"about": "Filters to apply to quota entities.", "fields": [
{ "name": "EntityType", "type": "string", "versions": "0+",
"about": "The entity type that the filter applies to." },
{ "name": "Rule", "type": "string", "versions": "0+",
"about": "The rule the filter performs." },
{ "name": "Match", "type": "string", "versions": "0+",
"about": "The string to applymatch the rule against." }
]}
]
}
{
"apiKey": 48,
"type": "response",
"name": "DescribeQuotasResponseDescribeClientQuotasResponse",
"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": "[]EntryData", "versions": "0+",
"about": "A result entry.", "fields": [
{ "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": "Entity", "type": "[]QuotaEntityData", "versions": "0+",
"about": "The quota entity description.", "fields": [
{ "name": "EntityType", "type": "string", "versions": "0+",
"about": "The entity type." },
{ "name": "EntityName", "type": "string", "versions": "0+",
"about": "The entity name." }
]},
{ "name": "Type", "type": "string", "versions": "0+",
"about": "The quota type." },
{ "name": "Units", "type": "string", "versions": "0+",
"about": "The units for the value." },
{ "name": "Value", "type": "int64", "versions": "0+",
"about": "The quota value." }
]}
]
}
|
DescribeEffectiveQuotasDescribeEffectiveClientQuotas:
| Code Block |
|---|
{
"apiKey": 49,
"type": "request",
"name": "DescribeEffectiveQuotasRequestDescribeEffectiveClientQuotasRequest",
"validVersions": "0",
"flexibleVersions": "none",
"fields": [
{ "name": "Entity", "type": "[]QuotaEntityData", "versions": "0+",
"about": "The quota entity description.", "fields": [
{ "name": "EntityType", "type": "string", "versions": "0+",
"about": "The entity type." },
{ "name": "EntityName", "type": "string", "versions": "0+",
"about": "The entity name." }
]},
{ "name": "OmitOverriddenValues", "type": "bool", "versions": "0+",
"about": "Whether to exclude the list of overridden values for every quota type." }
]
}
{
"apiKey": 49,
"type": "response",
"name": "DescribeEffectiveQuotasResponseDescribeEffectiveClientQuotasResponse",
"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": "[]QuotaEntryData", "versions": "0+",
"about": "Effective quota entries.", "fields": [
{ "name": "ErrorCode", "type": "int16", "versions": "0+",
"about": "The error code, or `0` if the effective quota description succeeded." },
{ "name": "ErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+",
"about": "The error message, or `null` if the effective quota description succeeded." },
{ "name": "QuotaEntity", "type": "[]QuotaEntity", "versions": "0+",
"about": "Effective quota entries.", "fields": [
{ "name": "EntityType", "type": "string", "versions": "0+",
"about": "The entity type." },
{ "name": "EntityName", "type": "string", "versions": "0+",
"about": "The entity name." }
]},
{ "name": "QuotaValues", "type": "[]QuotaValueData", "versions": "0+",
"about": "Quota configuration values.", "fields": [
{ "name": "Type", "type": "string", "versions": "0+",
"about": "The quota type." },
{ "name": "Units", "type": "string", "versions": "0+",
"about": "The units for the quota type." },
{ "name": "Entry", "type": "[]ValueEntryData", "versions": "0+",
"about": "Quota value entries.", "fields": [
{ "name": "QuotaEntity", "type": "[]ValueQuotaEntity", "versions": "0+",
"about": "Effective quota entries.", "fields": [
{ "name": "EntityType", "type": "string", "versions": "0+",
"about": "The entity type." },
{ "name": "EntityName", "type": "string", "versions": "0+",
"about": "The entity name." }
]},
{ "name": "Value", "type": "int64", "versions": "0+",
"about": "The quota configuration value." }
]}
]}
]}
]
}
|
AlterQuotasAlterClientQuotas:
| Code Block |
|---|
{
"apiKey": 50,
"type": "request",
"name": "AlterQuotasRequestAlterClientQuotasRequest",
"validVersions": "0",
"flexibleVersions": "none",
"fields": [
{ "name": "Entry", "type": "[]EntryData", "versions": "0+",
"about": "The quota configuration entries to alter.", "fields": [
{ "name": "QuotaEntity", "type": "[]QuotaEntity", "versions": "0+",
"about": "The quota entity to alter.", "fields": [
{ "name": "EntityType", "type": "string", "versions": "0+",
"about": "The entity type." },
{ "name": "EntityName", "type": "string", "versions": "0+",
"about": "The name of the entity." }
]},
{ "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." },
{ "name": "Units", "type": "string", "versions": "0+",
"about": "The units for the quota type." },
{ "name": "Value", "type": "int64", "versions": "0+",
"about": "The value to set, otherwise ignored if the value is to be removed." },
{ "name": "Remove", "type": "bool", "versions": "0+",
"about": "Whether the quota configuration value should be removed, otherwise set." }
]}
]},
{ "name": "ValidateOnly", "type": "bool", "versions": "0+",
"about": "Whether the alteration should be validated, but not performed." }
]
}
{
"apiKey": 50,
"type": "response",
"name": "AlterQuotasResponseAlterClientQuotasResponse",
"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": "[]EntryData", "versions": "0+",
"about": "The quota configuration entries to alter.", "fields": [
{ "name": "ErrorCode", "type": "int16", "versions": "0+",
"about": "The error code, or `0` if the quota alteration succeeded." },
{ "name": "ErrorMessage", "type": "string", "versions": "0+", "nullableVersions": "0+",
"about": "The error message, or `null` if the quota alteration succeeded." },
{ "name": "QuotaEntity", "type": "[]QuotaEntity", "versions": "0+",
"about": "The quota entity to alter.", "fields": [
{ "name": "EntityType", "type": "string", "versions": "0+",
"about": "The entity type." },
{ "name": "EntityName", "type": "string", "versions": "0+",
"about": "The name of the entity." }
]}
]}
]
} |
...