Status

Current state: Under Discussion

...

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

Motivation

The AlterConfigs RPC gives users a way to alter the configuration of a topic, broker, or other resource.  However, the new configuration replaces any existing configuration.  This makes AlterConfigs unusable in cases where the client does not know the full existing configuration before making the modification.  This makes AlterConfigs less efficient, since it means that the client needs to call DescribeConfigs to retrieve the existing configuration before making any modification.  It also introduces the possibility of "lost updates" when multiple clients enter a read-modify-write cycle around the same time.

...

In order to fix these issues, we should introduce a new RPC named modifyConfigs.  The new RPC should operate incrementally, modifying only the configuration values that are specified.  We should deprecate AlterConfigs.

Proposed Changes

The new ModifyConfigs API in AdminClient will take a map describing the configuration modifications, and a set describing configuration keys which should be removed.

...

@InterfaceStability.Evolving
public class ModifyConfigsOptions extends AbstractOptions<ModifyConfigsOptions> {
    private boolean validateOnly = false;

    /**
     * Set the request timeout in milliseconds for this operation or {@code null} if the default request timeout for the
     * AdminClient should be used.
     */
    public ModifyConfigsOptions timeoutMs(Integer timeoutMs) {
        this.timeoutMs = timeoutMs;
        return this;
    }

    /**
     * Return true if the request should be validated without altering the configs.
     */
    public boolean shouldValidateOnly() {
        return validateOnly;
    }

    /**
     * Set to true if the request should be validated without altering the configs.
     */
    public ModifyConfigsOptions validateOnly(boolean validateOnly) {
        this.validateOnly = validateOnly;
        return this;
    }
}

Protocol APIs

There will be a new ModifyConfigsRequest.  This request is very similar to AlterConfigsRequest.  However, unlike in AlterConfigsRequest, the config_value is nullable in ModifyConfigsRequest.  In the case where config_value is null, the existing configuration key will be erased.

...

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

Compatibility, Deprecation, and Migration Plan

This change is backwards compatible because the existing alterConfigs RPC is retained.  Clients will migrate to the new modifyConfigs RPC as needed.

Rejected Alternatives

We could have changed alterConfigs so that it had an incremental mode.  This would have avoided creating a new RPC.  However, in order to avoid breaking compatibility, the incremental mode could not have been made the default for AdminClient.  We would also not have been able to deprecate the non-incremental mode.  This would create a confusing and dangerous stumbling block for new users.  Because the problems with non-incremental mode are not immediately obvious, it is likely that many users would have made the wrong decision about what API to use.