Note that this KIP proposal is derived from a proposal by Grant Henke that was part of KIP-4 - Command line and centralized administrative operations.
Current state: Under Discussion
Discussion thread: TBD
JIRA:
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).
KIP-4 - Command line and centralized administrative operations outlines the motivation for exposing admin operations via the protocol:
A couple of specific use cases are worth pointing out:
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.
Entity types will be encoded to INT8 in the following way:
ListConfigs Request (Version: 0) => [entities]
entities => entity_type entity_name
entity_type => INT8
entity_name => STRING |
Request semantics:
ListConfigs Response (Version: 0) => error_code [entities]
error_code => INT16
entities => entity_type entity_name [configs]
entity_type => INT8
entity_name => STRING
configs =>
config_name => STRING
config_value => STRING
read_only => BOOLEAN
is_default => BOOLEAN
is_sensitive => BOOLEAN |
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 |
Request Semantics
Alter operation is attempted on a read-only config, an UnsupportedOperation error will be returned for the relevant entity.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;
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(ConfigEntity entity, 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 entities 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.
They follow a similar pattern as existing AdminClient APIs:
public class AdminClient {
public ListConfigsResult listConfigs(Collection<ConfigEntity> entities, ListConfigsOptions options);
public AlterConfigsResult alterConfigs(Map<ConfigEntity, List<Config>> configs, AlterConfigsOptions options);
}
public class ListConfigsOptions {
public ListConfigsOptions timeoutMs(Integer timeout);
}
public class ListConfigsResult {
public KafkaFuture<Map<ConfigEntity, Collection<Config>>> all();
}
public class AlterConfigsOptions {
public AlterConfigsOptions timeoutMs(Integer timeout);
public AlterConfigsOptions validateOnly(boolean validateOnly);
}
public class AlterConfigsResult {
public KafkaFuture<Void> all();
public Map<ConfigEntity, KafkaFuture<Void>> results();
}
public class ConfigEntity {
enum Type {
CLIENT, BROKER, TOPIC, UNKNOWN;
}
public ConfigEntity(Type type, String name) { ... }
public Type type() { ... }
public String name() { ... }
}
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 "Public Interfaces" section covers all the proposed changes.
We are adding a new ACL resource type, so third-party Authorizer implementations will potentially have to be updated in order to support it. 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.
With regards to forwards compatibility, ConfigEntity.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.