Status

Current state: Draft

Discussion thread: TODO

JIRA: TODO

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

Motivation

Quota management via Admin Client has gone through a couple drafts of proposals (KIP-248, KIP-422). The common ulterior motive is to remove ZooKeeper from this interaction for a variety of reasons (KIP-500), notwithstanding validation, security, and future extensibility. The goal of this KIP is to provide minimal interface changes to achieve quota management via Admin Client by reusing existing config mechanisms, but also convey as much useful information as possible.

Public Interfaces + Proposed Changes

(1) Quota should be modifiable via Admin::incrementalAlterConfigs().

The Admin signature would not change:

AlterConfigsResult incrementalAlterConfigs(Map<ConfigResource>, Collection<AlterConfigOp>>)

However, the ConfigResource object would have to be adapted to handle user, client, and user+client configurations. Therefore, enum values must be added for USER and CLIENT. However, this isn't sufficient for specifying a user+client configuration, so an additional USER_CLIENT type with a formatted name must be added, which can be delimited in the same way the path is formed in ZooKeeper today: sanitized-user/clients/sanitized-client. Note the user and client names have to be sanitized (escaped) since they're opaque, and therefore a special constructor should be added to facilitate this. [See Rejected Alternatives[1]]

The ConfigResource would be updated:

public final class ConfigResource {
    public enum Type {
        USER_CLIENT((byte) 48), CLIENT((byte) 32), USER((byte) 16), BROKER_LOGGER((byte) 8), BROKER((byte) 4), TOPIC((byte) 2), UNKNOWN((byte) 0);
        ...
    }

    public static ConfigResource makeUserClient(String user, String client) {
      // `user` and `client` are "sanitized" and merged into a canonical format.
    }
}

On the server side, incrementAlterConfigs would be updated to accept these new resource types, and would perform the expected configuration update to ZooKeeper.

(2) Quotas should be describable via Admin::describeConfigs().

The Admin signature would not change:

DescribeConfigsResult describeConfigs(Collection<ConfigResource> resources, DescribeConfigsOptions options);

One thing to address, however, is that user and client quotas can be complex in terms of determining which quotas are being applied. This is, in large part, due to the fact that there's 9 levels of configuration for a particular user. In typical use, it's not anticipated for all these to be used, however it's worth conveying this information for administrative purposes.

To relay which config a particular quota value comes from, the ConfigSource will have to differentiate from each configuration level: 

public class ConfigEntry {
    public enum ConfigSource {
        DYNAMIC_TOPIC_CONFIG, // dynamic topic config that is configured for a specific topic
        DYNAMIC_BROKER_LOGGER_CONFIG, // dynamic broker logger config that is configured for a specific broker
        DYNAMIC_BROKER_CONFIG, // dynamic broker config that is configured for a specific broker
        DYNAMIC_DEFAULT_BROKER_CONFIG, // dynamic broker config that is configured as default for all brokers in the cluster
        STATIC_BROKER_CONFIG, // static broker config provided as broker properties at start up (e.g. server.properties file)
        DEFAULT_CONFIG, // built-in default configuration for configs that have a default value
        UNKNOWN, // source unknown e.g. in the ConfigEntry used for alter requests where source is not set

        // Dynamic user/client configurations, in order of descending precedence.
        DYNAMIC_USER_CLIENT_CONFIG,                 // /config/users/<user>/clients/<client-id>
        DYNAMIC_USER_DEFAULT_CLIENT_CONFIG,         // /config/users/<user>/clients/<default>
        DYNAMIC_USER_CONFIG,                        // /config/users/<user>
        DYNAMIC_DEFAULT_USER_CLIENT_CONFIG,         // /config/users/<default>/clients/<client-id>
        DYNAMIC_DEFAULT_USER_DEFAULT_CLIENT_CONFIG, // /config/users/<default>/clients/<default>
        DYNAMIC_DEFAULT_USER_CONFIG,                // /config/users/<default>
        DYNAMIC_CLIENT_CONFIG,                      // /config/clients/<client-id>
        DYNAMIC_DEFAULT_CLIENT_CONFIG               // /config/clients/<default>
    }
}

Compatibility, Deprecation, and Migration Plan

All changes would be forward-compatible, and no migration plan is necessary. It's outside the scope of this KIP to deprecate any functionality.

Rejected Alternatives

[1] An alternative to a USER_CLIENT resource type is to add a child ConfigResource field to the ConfigResource object, where the only valid resource relationship would be a parent type USER with a child type CLIENT. This has two pitfalls: (1) it's more complex, and a generic parent-child resource hierarchy isn't like to be useful in the long term, and (2) it requires modification to the wire protocol.

[2]