Table of Contents |
---|
...
Status
Current state: Under DiscussionAccepted
Discussion thread: here
JIRA: https://issues.apache.org/jira/browse/ Jira server ASF JIRA serverId 5aa69414-a9e9-3523-82ec-879b028fb15b key KAFKA-9494
PR:
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).
...
- Bump up the valid versions range
- New fields -
IncludeSynoyms
and fieldIncludeDocumentation
- with default value of false
Code Block |
---|
{ "apiKey": 32, "type": "request", "name": "DescribeConfigsRequest", // Version 1 adds IncludeSynoyms. // Version 2 is the same as version 1. // Version 3 is the same as version 2. "validVersions": "0-3", <--- Updated Field "flexibleVersions": "none", "fields": [ { "name": "Resources", "type": "[]DescribeConfigsResource", "versions": "0+", "about": "The resources whose configurations we want to describe.", "fields": [ { "name": "ResourceType", "type": "int8", "versions": "0+", "about": "The resource type." }, { "name": "ResourceName", "type": "string", "versions": "0+", "about": "The resource name." }, { "name": "ConfigurationKeys", "type": "[]string", "versions": "0+", "nullableVersions": "0+", "about": "The configuration keys to list, or null to list all configuration keys." } ]}, { "name": "IncludeSynoyms", "type": "bool", "versions": "1+", "default": "false", "ignorable": false, "about": "True if we should include all synonyms." } { "name": "IncludeTypeIncludeDocumentation", "type": "bool", "versions": "1+", "default": "false", "ignorable": false, <--- New Field "about": "True if we should include configuration typedocumentation." } { "name": "IncludeDocumentation", "type": "bool", "versions": "1+", "default": "false", "ignorable": false, ] } |
Response
The changes to the Response schema include
- Bump valid versions range
- Add new Fields -
ConfigValueType and Documentation
Code Block |
---|
{ "apiKey": 32, "type": "response", "name": "DescribeConfigsResponse", "validVersions": "0-3", <--- NewUpdated Field "flexibleVersions": "none", "aboutfields": "True if we should include configuration documentation." } ] } |
Response
The changes to the Response schema include
...
Code Block |
---|
{ "apiKey": 32, "type": "response", "name": "DescribeConfigsResponse", "validVersions": "0-3", <--- Updated Field "flexibleVersions": "none", "fields": [[ { "name": "ThrottleTimeMs", "type": "int32", "versions": "0+", "about": "The duration in milliseconds for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." }, { "name": "ThrottleTimeMsResults", "type": "int32[]DescribeConfigsResult", "versions": "0+", "about": "The duration in millisecondsresults for which the request was throttled due to a quota violation, or zero if the request did not violate any quota." }, each resource.", "fields": [ { "name": "ResultsErrorCode", "type": "[]DescribeConfigsResult"int16", "versions": "0+", "about": "The results for each resource.", "fields": [ error code, or 0 if we were able to successfully describe the configurations." }, { "name": "ErrorCodeErrorMessage", "type": "int16string", "versions": "0+", "nullableVersions": "0+", "about": "The error codemessage, or 0null if we were able to successfully describe the configurations." }, { "name": "ErrorMessageResourceType", "type": "stringint8", "versions": "0+", "nullableVersions": "0+", "about": "The error message, or null if we were able to successfully describe the configurationsresource type." }, { "name": "ResourceTypeResourceName", "type": "int8string", "versions": "0+", "about": "The resource typename." }, { "name": "ResourceNameConfigs", "type": "string[]DescribeConfigsResourceResult", "versions": "0+", "about": "TheEach resourcelisted nameconfiguration." }, , "fields": [ { "name": "ConfigsName", "type": "[]DescribeConfigsResourceResultstring", "versions": "0+", "about": "EachThe listedconfiguration configurationname.", "fields": [ }, { "name": "NameValue", "type": "string", "versions": "0+", "nullableVersions": "0+", "about": "The configuration namevalue." }, { "name": "ValueReadOnly", "type": "stringbool", "versions": "0+", "nullableVersions": "0+", "about": "TheTrue if the configuration valueis read-only." }, { "name": "ReadOnlyIsDefault", "type": "bool", "versions": "0+", "about": "True if the configuration is read-onlynot set." }, { "name": "IsDefault", "type": "bool", "versions": "0",// Note: the v0 default for this field that should be exposed to callers is // "about": "Truecontext-dependent. For example, if the configurationresource is not set." }, a broker, this should default to 4. // Note:-1 theis v0just defaulta forplaceholder thisvalue. field that should be exposed to callers is // context-dependent. For example, if the resource is a broker, this should default to 4.{ "name": "ConfigSource", "type": "int8", "versions": "1+", "default": "-1", "ignorable": true, // -1 is just a placeholder value. "about": "The configuration source." }, { "name": "ConfigSourceIsSensitive", "type": "int8bool", "versions": "10+", "default": "-1", "ignorable": true, "about": "TheTrue if this configuration sourceis sensitive." }, { "name": "IsSensitiveSynonyms", "type": "bool[]DescribeConfigsSynonym", "versions": "01+", "ignorable": true, "about": "TrueThe synonyms iffor this configuration is sensitivekey." }, "fields": [ { "name": "SynonymsName", "type": "[]DescribeConfigsSynonymstring", "versions": "1+", "ignorable": true, "about": "The synonyms for this configuration keysynonym name.", "fields": [ }, { "name": "NameValue", "type": "string", "versions": "1+", "nullableVersions": "0+", "about": "The synonym namevalue." }, { "name": "ValueSource", "type": "stringint8", "versions": "1+", "nullableVersions": "0+", "about": "The synonym valuesource." }, ]}, { "name": "SourceConfigValueType", "type": "int8", "versions": "13+", default": "0", <--- New Field "about": "The configuration synonymdata sourcetype." }, ]}, <--- Start of new Fields { { "name": "ConfigValueTypeDocumentation", "type": "int8string", "versions": "3+", default"nullableVersions": "0+", <--- New Field "about": "The configuration data typedocumentation." }, ]} { "name": "Documentation", "type": "string", "versions": "3+", "nullableVersions": "0+", "about": "The configuration documentation." }, <---- End of new Fields ]} ]} ] } ]} ] } |
AdminClient Class
No new method will be added or updated to the AdminCient
class.
Proposed Changes
Under the proposed change, response for AdminClient.describeConfigs
would include following new properties. These new properties would be part of DescribeConfigsResponse.ConfigEntry
class.
AbstractConfig Class
As part of this KIP, a new method will be added to AbstractConfig to return the documentation of the given Config
Code Block |
---|
public String documentationOf(String key) {
ConfigDef.ConfigKey configKey = definition.configKeys().get(key);
if (configKey == null)
return null;
return configKey.documentation;
} |
Proposed Changes
Under the proposed change, response for AdminClient.describeConfigs
would include following new properties, which would be part of DescribeConfigsResponse.ConfigEntry
class.
Type: ConfigType -
This is an Enum of all the supported data type.Code Block Type: ConfigType -
This is an Enum of all the supported data type.Code Block /** * Data type of configuration entry. */ public enum ConfigType { UNKNOWN, BOOLEAN, STRING, INT, SHORT, LONG, DOUBLE, LIST, CLASS, PASSWORD }
ConfigType.Unknown
is for ensuring backward compatibility (explained is Compatibility section below)/
The values in above Enum are derived from existingType
Enum defined in ConfigDef.java belowCode Block /** * The config types Data type of configuration entry. */ public enum TypeConfigType { UNKNOWN, BOOLEAN, STRING, INT, SHORT, LONG, DOUBLE, LIST, CLASS, PASSWORD }
...
ConfigType.Unknown
is for ensuring backward compatibility (explained is Compatibility section below)
The values in above Enum is derived from existingType
Enum defined in ConfigDef.java belowCode Block /** * The config types */ public enum Type { BOOLEAN, STRING, INT, SHORT, LONG, DOUBLE, LIST, CLASS, PASSWORD }
2. Documentation: String
- field's documentation
DescribeConfigsResponse.ConfigEntry
with the above new fields
Code Block |
---|
public class ConfigEntry {
private final String name |
...
DescribeConfigsResponse.ConfigEntry
with the above new fields
Code Block |
---|
public class ConfigEntry { private final String name; private final String value; private final ConfigSource source; private final boolean isSensitive; private final boolean isReadOnly; private final List<ConfigSynonym>String synonyms; .....value; private final ConfigTypeConfigSource typesource; // This is private final boolean isSensitive; private final boolean isReadOnly; private final List<ConfigSynonym> synonyms; ..... private final ConfigType type; // This is the new property private final String documentation; // This is the new property ..... |
...
Code Block | ||
---|---|---|
| ||
{
"name": "offsets.topic.num.partitions",
"value": "50",
"source": "DEFAULT_CONFIG",
"type": "INT", // <---- New Field
"synonyms": [
{
"name": "offsets.topic.num.partitions",
"value": "50",
"source": "DEFAULT_CONFIG"
}
],
"documentation": "The number of partitions for the offset commit topic (should not change after deployment)", // <---- New Field
"isReadOnly": true,
"isSensitive": false,
} |
Default Behavior
...
}
],
"documentation": "The number of partitions for the offset commit topic (should not change after deployment)", // <---- New Field
"isReadOnly": true,
"isSensitive": false,
} |
Default Behavior
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
Code Block | ||
---|---|---|
| ||
KafkaAdminClient.describeConfigs(
resources,
new DescribeConfigsOptions()
.includeSynonyms(true)
.includeDocumentation(true)
) |
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 | |
---|---|---|---|
1 | X | X | Both Type and Documentation is visible to the client. |
2 | X | X-1 |
Not serialized as part of the response. |
3 | X-1 | X | IllegalArgumentException: Invalid version for API key... |
4 | X+1 | X | Both If version X+1 has new value in enum |
Rejected Alternatives
NA