Status

Current state: Under discussion

Discussion thread: here (<- link to https://mail-archives.apache.org/mod_mbox/lucene-dev/)

JIRA:

Released: <Solr Version>

Please keep the discussion on the mailing list (or in Jira) rather than commenting on the wiki (wiki discussions get unwieldy fast). Confluence supports inline comments that can also be used.

Motivation

Current cluster-level configuration uses a hodgepodge of traditional Solr config sources (solr.xml, system properties) and the new somewhat arbitrary config files kept in ZK (/clusterprops.json, /security.json, /packages.json, /autoscaling.json etc...).

There's no uniform strongly-typed API to access and manage these configs - currently each config source has its own CRUD, often relying on direct access to Zookeeper. There's also no uniform method for monitoring changes to these config sources.

This caused the situation where different Solr component authors had to come up with their own solutions, in many cases directly accessing ZK + watches.

The scope of this SIP is to define a new uniform cluster-level configuration API, mostly for internal purposes, to be consumed by various Solr components.

Public Interfaces

Most of the design will be related to the internal APIs but there will be also a public CRUD API to manipulate the configs.

Proposed Changes

General design

This SIP proposes a uniform config API facade with the following characteristics:

1. Using a single hierarchical (or at least key-based) facade for accessing any global config.
2. Using strongly-typed sub-system configs instead of opaque Map-s: components would no longer deal with JSON parsing/writing, instead they would use properly annotated Java objects for config CRUD. Config objects would include versioning information (eg. lastModified timestamp).
3. Isolating access to the underlying config persistence layer: components would no longer directly interact with Zookeeper or files. Most likely the default implementation would continue using different ZK files per-subsystem in order to limit the complexity of file formats and to reduce the cost of notifications for unmodified parts of the configs.
4. Providing uniform way to register listeners for monitoring changes in specific configs: components would no longer need to interact with ZK watches, they would instead be notified about modified configs that they are interested in.

Hierarchical strongly-typed and versioned config

The API will offer a single facade interface (eg. ClusterConfig ) that will allow to retrieve and set strongly-typed instances of subsystem configurations.

Individual configurations need to be versioned (eg. timestamped). Since initially the primary backing store will be ZK we will get this information for free from zkVersion.

For example:

public interface VersionedConfig {
  // monotonically increasing version number
  long getVersion();
}

As an example, container-level plugins configuration could be defined in a PluginConfigs POJO and then it could be accessed like this:

ClusterConfig clusterConfig = ...
...
PluginConfigs containerPluginConfigs = clusterConfig.get("container/plugins", PluginConfigs.class);
... // modify the configuration
clusterConfig.set("container/plugins", containerPluginConfigs);

Change notifications

Components may register as listeners to the respective configuration path in order to receive notifications about updates:

public interface ClusterConfigListener<T extends VersionedConfig> {
  void onChange(T oldConfig, T newConfig);
}
...
clusterConfig.registerListener("container/plugins", listener);

Configuration sources

• solr.xml
• /clusterprops.json and other ZK files
• system properties
• environment variables

Initial configuration bootstrap

Configuration defaults

Distributed state of the config and effects of updates

Persistence

Compatibility, Deprecation, and Migration Plan

• What impact (if any) will there be on existing users?
• If we are changing behavior how will we phase out the older behavior?
• If we need special migration tools, describe them here.
• When will we remove the existing behavior?

Security considerations

Describe how this proposal affects security. Will this SIP expose Solr to new attack vectors? Will it be necessary to add new permissions to the security framework due to this SIP?

Test Plan

Describe in few sentences how the SIP will be tested. We are mostly interested in system tests (since unit-tests are specific to implementation details). How will we know that the implementation works as expected? How will we know nothing broke?

Rejected Alternatives

If there are alternative ways of accomplishing the same thing, what were they? The purpose of this section is to motivate why the design is the way it is and not some other way.