Current state: Accepted
Discussion thread: here
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).
The admin client allows users to describe the configuration of brokers and topics in the cluster via
describeConfigs method. The returned configuration includes name, default values, source, configuration synonym including if the information is sensitive
isSensitive, or is read only
isReadOnly. The consumer of this API can choose to display this information in GUI e.g. web forms in Kafka lenses, Confluent Control Center. While displaying this information, fields such as
isReadOnly can be used by the client to hide sensitive information and to prevent the user from editing the field respectively. This provides better upfront experience to the user.
This KIP proposes to include 2 additional metadata information -
documentation for the individual config entries.
The motivation behind including
dataType is to enable the client to provide better validation to the user. In the absence of
dataType the only way to know if the user specified value is correct is to make an `alter` call and check if there is no error, which is a sub-optimal experience. Including the
dataType could open up potentially other use cases as well.
documentation would enable the client to provide latest information about the config and would also act as a single source of truth.
The changes to the Request schema include
- Bump up the valid versions range
- New field
IncludeDocumentation- with default value of false
The changes to the Response schema include
- Bump valid versions range
- Add new Fields -
ConfigValueType and Documentation
No new method will be added or updated to the
As part of this KIP, a new method will be added to AbstractConfig to return the documentation of the given Config
Under the proposed change, response for
AdminClient.describeConfigs would include following new properties, which would be part of
Type: ConfigType -This is an Enum of all the supported data type.
ConfigType.Unknownis for ensuring backward compatibility (explained is Compatibility section below)
The values in above Enum is derived from existing
TypeEnum defined in ConfigDef.java below
Documentation: String - field's documentation
DescribeConfigsResponse.ConfigEntry with the above new fields
Rest of the changes would be plumbing this new property in
AdminManager class to be eventually consumed by
Following example show how the response would look like in JSON format.
Note: Kafka uses binary protocol over TCP. ConfigType Enum is serialized as byte instead of string.
By default, the `documentation` field will not be included in the response to
describeConfigs. This is to avoid the response from boating up as the value for
documentation field can be quite large.
Below example shows how client can include the new fields in the response
Compatibility, Deprecation, and Migration Plan
For backward compatibility we rely on existing schema versioning technique. Under this, client sends its version information in the request header. This in turn is used on the server to select the schema for that version.
|Server version||Client version||Expected Behavior|
Not serialized as part of the response.
|3||X-1||X||IllegalArgumentException: Invalid version for API key...|
If version X+1 has new value in enum