...

• 0: Unknown

• 1: Any

• 2: Topic

• 3: Group

• 4: Broker

• 5: User (new)

• 6: Client (new)

...

Describe Quotas

To create a robust API for the admin client we should be able to list quotas for clients and users. This is needed to be able to create finer grained authorization if needed (for instance listing would be more restrictive than simply describing) and to provide a query functionality so that multiple quota configs could be described or altered in a batchimplement the use cases of kafka-configs.sh where a quota is modified, like user, client or (user,client) we have to create a protocol to handle quota listings. The justification for a new protocol is that a quota is quite different from a broker or topic config because a quota can sometimes be identified a simple user, client or even a (user,client) tuple while a topic or a broker config can be identified only by the topic's name or the broker's ID.

ListQuotasDescribeQuotas Request (Version: 1) => quota_config_[resource]
  resource => [quota_config_resource] [config_name]
    quota_config_resource => type name
      type => INT8
      name => NULLABLE_ STRING
    config_name => STRING

Request semantics:

1. Can be sent to any broker
2. The type of quota_config_resource can either be "Client" or "User".
3. If the name is <default> it means that listing the default quota is asked. Responses will be returned the same way for defaults.
4. If the config_name array is null, all configs are returned. Otherwise, configs with the provided names are returnedThe name of quota_config_resource is nullable. 
5. If name is not provided, we list the given type of resources. 
If name is provided, we list the children of the given user or client resource.
6. Authorization:  "ListQuotasDescribeQuotas" can only be interpreted on the "Cluster" resource and represented by the Describe DescribeConfigs ACL due to the similarity with other listing protocols like ListOffsets or ListGroupsin use cases. Unauthorized requests will receive an appropriate AuthorizationFailed error code.

...

ListQuotasDescribeQuotas Response (Version: 1) => throttle_time_ms error_code error_message[resource]
  throttle_time_ms => INT32
  resource => [quota_config_entity_nameresource] [config]
  throttle  quota_timeconfig_msresource => type INT32name
  error_code    type => INT16INT8
     error_message name => NULLABLE_STRING
  quota_config_entity_name => STRING

Response semantics:

1. Only the quota config names will be returned because the request explicitly specifies the config's type information ("User" and/or "Client") therefore there is no need to specify it here.
2. The error returned means that the requestor doesn't have access to the specified resource.

Describe Quotas

To be able to implement the use cases of kafka-configs.sh where a quota is modified, like user, client or (user,client) we have to create a protocol to handle quota listings. The justification for a new protocol is that a quota is quite different from a broker or topic config because a quota can sometimes be identified a simple user, client or even a (user,client) tuple while a topic or a broker config can be identified only by the topic's name or the broker's ID.

DescribeQuotas Request (Version: 1) => [resource]
  resource => [quota_config_resource] [config_name]
    quota_config_resource => type name
      type => INT8
      name => STRING
    config_name => STRING

Request semantics:

1. Can be sent to any broker
2. If the name is <default> it means that listing the default quota is asked. Responses will be returned the same way for defaults.
3. If the config_name array is null, all configs are returned. Otherwise, configs with the provided names are returned.
4. Authorization:  "DescribeQuotas" can only be interpreted on the "Cluster" resource and represented by the DescribeConfigs ACL due to the similarity in use cases. Unauthorized requests will receive an appropriate AuthorizationFailed error code.

DescribeQuotas Response (Version: 1) => throttle_time_ms [resource]
  throttle_time_ms => INT32
  resource => [quota_config_resource] [config]
    quota_config_resource => type name
      type => INT8
      name => STRING
    config => error_code error_message  config => error_code error_message [config_entry]
      error_code => INT16
      error_message => NULLABLE_STRING
      config_entry =>
        config_name => STRING
        config_value => STRING
        read_only => BOOLEAN
        is_default => BOOLEAN
        is_sensitive => BOOLEAN

...

To ease the migration for users who are stuck with this command, the USE_OLD_COMMAND will be introduced.

Special Migration Tools

There are no tools required.

Removal Of The Existing Behavior

The current --zookeeper option will be disabled with this change as it has minimal impact on the current users.

Test Plan

Most of the functionality can be covered with end-to-end tests. There will be unit tests also to verify the protocol and the broker side logic.

Rejected Alternatives

...

_COMMAND will be introduced.

Special Migration Tools

There are no tools required.

Removal Of The Existing Behavior

The current --zookeeper option will be disabled with this change as it has minimal impact on the current users.

Test Plan

Most of the functionality can be covered with end-to-end tests. There will be unit tests also to verify the protocol and the broker side logic.

Future Considerations

At this moment this ConfigCommand can describe all the topics and all the brokers with one command but can't describe all clients or users. The reason for this is that we can gain the required information for topics and brokers by a MetadataRequest but we have no such protocols for getting a list of users or clients.