...

1. The Metadata request exposes topic metadata, but it does not expose topic configs. ListConfigs will make that information available to any client of the Kafka protocol (including and the upcoming Java AdminClient)AdminClient will expose it to normal users.
2. AlterConfigs would make it possible to update topic configs, but also client and replication quotas via the protocol and the AdminClient.

Public Interfaces

ACLs

A new ACL resource type `Configs` will be introduced with Describe, Alter and All operations. Initially, this resource type will work at a global level like the Cluster resource type. That is, the only valid resource name will be "kafka-cluster". This leaves the door open for evolving this to be more fine-grained in the future.

Protocol APIs

Wire Format types

Entity types will be encoded to INT8 in the following way:

• -2: Unknown
• -1: Any (for filtering, but currently unused)
• 0: Broker
• 1: Topic
• 2: Client

List Configs

ListConfigs Request (Version: 0) => [entities]   
  entities => entity_type entity_name
    entity_type => INT8
    entity_name => STRING

...

1. Can be sent to any broker
2. If there are multiple instructions for the same entity in one request the extra request will be ignored
   • This is because the list of entities is modeled server side as a set
   • Multiple entities results in the same end goal, so handling this error for the user should be okay
   • This is similar to how delete topics handles requests
3. Entity types are "Topic", "Client", and "Broker".
4. If entity_type is "Broker" and entity_name matches the broker that has received the request, read-only configs for this broker are also returned.
5. Below are the authorization requirements for each type:Broker: Must The principal must be authorized to the "Describe" Operation on the "ClusterConfigs" resource Topic: Must be authorized to the type or "Describe" Operation on the "Topic" resource
6. Client: Must be authorized to the "Describe" Operation on the "Client" resource
   • This is a new resource needed
   • TODO: best way to handle this...
Arbitrary configurations are allowed
7. This provides flexibility for custom clients, and allows all "plugin" or extra configs to be shown
The user can validate the configs after the describe command in their client to check for errors, but the wire protocol should relay all informationCluster" resource type. Unauthorized requests will receive a ConfigsAuthorization error code.

ListConfigs Response (Version: 0) => error_code [entities]
  error_code => INT16
  entities => entity_type entity_name error_code [configs]
    entity_type => INT8
    entity_name => STRING
    error_code => INT16
    configs =>
      config_name => STRING
      config_value => STRING
      read_only => BOOLEAN
      is_default => BOOLEAN
      is_sensitive => BOOLEAN

For each config, If is_sensitive is true, config_value will always be null to ensure that we don't leak sensitive information like passwords.

Alter Configs

AlterConfigs Request (Version: 0) => [entities] validate_only
  validate_only => BOOLEAN
  entities => entity_type entity_name [configs]
    entity_type => INT8
    entity_name => STRING
    configs =>
      config_name => STRING
      config_value => STRING

...

1. Can be sent to any broker
2. If there are multiple instructions for the same entity in one request, an InvalidRequestException will be logged on the broker and a single error code for that topic will be returned to the client
   • This is because the list of entities is modeled server side as a map with entity as the key
3. Entity types are "Topic", "Client", and "Broker".Below are the authorization requirements for each type:
4. The principal must be authorized to "Alter" the "Create" Operation on Configs" resource type or "Alter" the "Cluster" resource to create topicstype.   Unauthorized requests will receive a ClusterAuthorizationExceptionConfigsAuthorization for all entities.
5. If an Alter operation is attempted on a read-only config, an UnsupportedOperation error will be returned for the relevant entity.
6. The request is not transactional. 
   1. If an error occurs for an entity, others could still be updated.
   2. Errors are reported independently per entity.
7. For tools that allow users to alter configs, a validation/dry-run mode where validation errors are reported but no creation is attempted is available via the validate_only parameter.

AlterConfigs Response (Version: 0) => [responses]   
  responses => entity_type entity_name error_code error_message
    entity_type => INT8
    entity_name => STRING
    error_code => INT16
    error_message => STRING

Policy

In a similar fashion to KIP-108: Create Topic Policy, we allow users to define a policy class to validate alter configs requests. The config name will be alter.configs.policy.class.name and the interface follows:

package org.apache.kafka.server.policy;
 
enum ConfigEntityType {
    CLIENT, BROKER, TOPIC, UNKNOWN;
}

public interface AlterConfigsPolicy extends Configurable, AutoCloseable {

    /**
     * Class containing the create request parameters.
     */
    class RequestMetadata {
        /**
         * Create an instance of this class with the provided parameters.
         *
         * This constructor is public to make testing of <code>AlterConfigPolicy</code> implementations easier.
         */
        public RequestMetadata(ConfigEntityType entityType, String entityName, Map<String, String> configs) { ... }

        /**
         * Return configs in the request.
         */
        public Map<String, String> configs() { ... }
    }

    /**
     * Validate the request parameters and throw a <code>PolicyViolationException</code> with a suitable error
     * message if the alter configs request parameters for the provided entity do not satisfy this policy.
     *
     * Clients will receive the POLICY_VIOLATION error code along with the exception's message. Note that validation
     * failure only affects the relevant entity, other entity in the request will still be processed.
     *
     * @param requestMetadata the alter configs request parameters for the provided entity.
     * @throws PolicyViolationException if the request parameters do not satisfy this policy.
     */
    void validate(RequestMetadata requestMetadata) throws PolicyViolationException;
}

Users will have to ensure that the policy implementation code is in the broker's classpath. Implementations should throw the existing PolicyViolationException with an appropriate error message if the request does not fulfill the policy requirements. We chose a generic name for the only parameter of the validate method in case we decide to add parameters that are not strictly related to the topic (e.g. session information) in the future. The constructor of RequestMetadata is public to make testing convenient for users. Under normal circumstances, it should only be instantiated by Kafka. We chose to create separate API classes instead of reusing request classes to make it easier to evolve the latter.

AdminClient APIs

Proposed Changes

TBD

Compatibility, Deprecation, and Migration Plan

TBDAuthorization...

Rejected Alternatives

• TBD

Future work

• Forward requests to the relevant brokers in order to return `read-only` broker configs.

...