...

1. The Metadata request exposes topic metadata, but it does not expose topic configs. DescribeConfigs will make that information available to any client of the Kafka protocol and the 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.
3. One should be able to tell how a topic or broker is configured including defaults and overrides.

...

We will introduce 2 new ACL operations: ReadConfigs and WriteConfigs. The goal is for these These operations to apply to any resource resources that has have configs (i. In the initial version, they will only apply to the Cluster resource type.e. Broker and Topic). In addition, ReadConfigs/WriteConfigs on the Cluster resource allows one to read and write configs on any resource with configs. Finally, the ReadConfigs and WriteConfigs operations are included in the `All` operation.

Protocol APIsProtocol APIs

Wire Format types

KIP-140: Add administrative RPCs for adding, deleting, and listing ACLs introduced a wire format representation for ResourceType and AclOperation. We weill add new values to both types as follows:

...

• 0: Unknown

• 1: Any

• 2: Topic

• 3: Group

• 4: Cluster

• 5: Broker (new)

• 6: Client (new)

• 7: User (new)

Describe Configs

DescribeConfigs Request (Version: 0) => [resource [config_name]]   
  resource => resource_type resource_name
    resource_type => INT8
    resource_name => STRING
  config_name => STRING

...

1. Can be sent to any broker
2. If there are multiple instructions for the same resource in one request the extra request will be ignored
   • This is because the list of resources is modeled server side as a set
   • Multiple resources 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. If the config_name array is null, all configs are returned. Otherwise, configs with the provided names are returned.
4. Valid resource types are "Topic", "Client", "User" and "Broker".
5. If resource_type is "Broker" and , the resource_name matches must be the broker that has received the request, read-only configs (i.e. configs that can only be defined statically, typically via server.properties) for this broker are also returned. Note that brokers are the only resource type with read-only configs at this point.id of the broker processing the request as the brokers don't have any dynamic configs currently (apart from replication quotas configs, which are excluded). All broker configs are read-only. Conversely, there are no read-only topic configs at the moment.
6. Replication, User and Client Quota configs are not supported. See "Future work" for more details.
7. Authorization is as follows:
   1. Topic configs: "DescribeConfigs" on the "Topic" or "Cluster" resource ("DescribeConfigs
   The principal must be authorized to "ReadConfigs" on the "Cluster" resource ("ReadConfigs
   1. " is also included in the "All" operation). Unauthorized requests will receive
   a ClusterAuthorizationFailed
   1. an appropriate AuthorizationFailed error code.
   2. Broker configs: "DescribeConfigs" on the "Broker" or "Cluster" resource ("DescribeConfigs" is also included in the "All" operation). Unauthorized requests will receive an appropriate AuthorizationFailed error code.
8. Errors are reported independently per resource.

...

1. Can be sent to any broker
2. If there are multiple instructions for the same resource 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 resources is modeled server side as a map with the resource as the key
3. Valid resource types are "Topic", "Client", " User" and "Broker".
4. The principal must be authorized to "WriteConfigs" on the "Cluster" resource ("WriteConfigs" is also included in the "All" operation). Unauthorized requests will receive a ClusterAuthorizationFailed error code.
5. However, since all broker configs are currently read_only, only the former makes sense until that changes.
6. If an Alter operation If an Alter operation is attempted on a read-only config, an an UnsupportedOperation error  error will be returned for the relevant resource.
7. The request is not transactional. 
   1. If an error occurs for an resource, others could still be updated.
   2. Errors are reported independently per resource.
8. 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.
9. Authorization is as follows:
   1. Topic configs: "WriteConfigs" on the "Topic" or "Cluster" resource ("WriteConfigs" is also included in the "All" operation). Unauthorized requests will receive an appropriate AuthorizationFailed error code.
   2. Broker configs: "WriteConfigs" on the "Broker" or "Cluster" resource ("WriteConfigs" is also included in the "All" operation). Unauthorized requests will receive an appropriate AuthorizationFailed error code.
10. Replication, User and Client Quota configs are not supported. See "Future work" for more details.
11. The request is not transactional. 
    1. If an error occurs for an resource, others could still be updated.
    2. Errors are reported independently per resource.
12. 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 => resource_type resource_name error_code error_message

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

...

public class AdminClient {
    public DescribeConfigsResult describeConfigs(Collection<ConfigResource> resources, DescribeConfigsOptions options);
    public AlterConfigsResult alterConfigs(Map<ConfigResource, Config> configs, AlterConfigsOptions options);
}

public class DescribeConfigsOptions { 
    public DescribeConfigsOptions timeoutMs(Integer timeout);
}

public class DescribeConfigsResult {
    public Map<ConfigResource, KafkaFuture<Config>> results()
    public KafkaFuture<Map<ConfigResource, Config>> all();
}
 
public class AlterConfigsOptions { 
    public AlterConfigsOptions timeoutMs(Integer timeout);
	public AlterConfigsOptions validateOnly(boolean validateOnly);
}

public class AlterConfigsResult {
    public KafkaFuture<Void> all();
    public Map<ConfigResource, KafkaFuture<Void>> results();
}
 
public class ConfigResource {
    enum Type {
		CLIENT, BROKER, TOPIC, USER, UNKNOWN;
    }
 
    public ConfigResource(Type type, String name) { ... }
    
    public Type type() { ... }
    public String name() { ... }
}

 
public class Config {
    public Config(Collection<ConfigEntry> configs) { ... }
    public Collection<ConfigEntry> entries() { ... }
}
public class ConfigEntry {
    public ConfigEntry(String name, String value) {
        this(name, value, false, false, false);
    }
    public ConfigEntry(String name, String value, boolean isDefault, boolean isSensitive, boolean isReadOnly) { ... }
    public String name() { ... }
    public String value() { ... }
    public boolean isDefault { ... }
    public boolean isSensitive { ... }
    public boolean isReadOnly { ... }
}

Proposed Changes

The In addition to what is mentioned in the "Public Interfaces" section covers all the proposed changes.

Compatibility, Deprecation, and Migration Plan

We are adding new ACL operations, so third-party Authorizer implementations will potentially have to be updated in order to support them. Since this only affects newly introduced protocol and AdminClient APIs, it's not a compatibility issue. It simply means that the new functionality won't be available for users of such Authorizer implementations until they are updated.

With regards to forwards compatibility, ConfigResource.Type has an UNKNOWN element in case it receives data from a newer broker that cannot be mapped to one of the existing enum types.

Rejected Alternatives

1. Allowing sensitive data to be returned: it's good security practice to never expose sensitive data. If necessary, the user can reset the relevant sensitive data (e.g. a password).
2. Introducing a new Configs resource instead of ReadConfigs and WriteConfigs operations: there is always a one to one mapping between a resource and its configs, so there isn't much value in creating a separate resource for Configs. By adding new operations to existing resources, it's easier to see all the ACLs that affect a given resource.

Future work

, it's worth mentioning that the describeConfigs implementation will perform requests to min(1, N) brokers where N is the number of ConfigResources that have a Broker resource type.

Compatibility, Deprecation, and Migration Plan

We are adding new ACL Operations and a new ACL Resource Type, so third-party Authorizer implementations will potentially have to be updated in order to support them. Since this only affects newly introduced protocol and AdminClient APIs, it's not a compatibility issue. It simply means that the new functionality won't be available for users of such Authorizer implementations until they are updated.

With regards to forwards compatibility, ConfigResource.Type has an UNKNOWN element in case it receives data from a newer broker that cannot be mapped to one of the existing enum types.

Rejected Alternatives

1. Allowing sensitive data to be returned: it's good security practice to never expose sensitive data. If necessary, the user can reset the relevant sensitive data (e.g. a password).
2. Introducing a new Configs resource instead of ReadConfigs and WriteConfigs operations: there is always a one to one mapping between a resource and its configs, so there isn't much value in creating a separate resource for Configs. By adding new operations to existing resources, it's easier to see all the ACLs that affect a given resource.

Future work

1. Forward requests to the relevant brokers in order to return `read-only` broker configs.
2. More fine-grained ACLs so that a user authorized to ReadConfigs/WriteConfigs on a given resource type (topic, broker, etc.) can read/write the relevant configs.
3. Support for reading and updating client, user and replication quotas. We initially included that in the KIP, but it subsequently became apparent that a separate protocol and AdminClient API would be more appropriate. The reason is that client/user quotas can be applied on a client id, user or (client id, user) tuple. In the future, the hierarchy may get even more complicated. So, it makes sense to keeping the API simple for the simple cases while introducing a more sophisticated API for the more complex case
4. Forward requests to the relevant brokers in order to return `read-only` broker configs.
5. More fine-grained ACLs so that a user authorized to ReadConfigs/WriteConfigs on a given resource type (topic, broker, etc.) can read/write the relevant configs.