Module org.elasticsearch.server
Package org.elasticsearch.plugins

Interface SystemIndexPlugin

All Superinterfaces:
ActionPlugin
public interface SystemIndexPlugin extends ActionPlugin
A Plugin that can store state in protected Elasticsearch indices or data streams.

A Plugin that implements this interface can define SystemIndexDescriptors and SystemDataStreamDescriptors using index patterns. Any index or data stream matching these patterns will be separated from user space.

The indices and data streams will be restricted to users whose relevant index permissions have the “allow_restricted_indices” parameter set to true. Accessing these indices without using specific headers may result in a deprecation warning, or, in some cases, will result in denial of the request. In the future, all requests without correct headers will be rejected or ignored.

SystemIndexPlugin extends ActionPlugin because, ideally, the plugin will provide its own APIs for manipulating its resources, rather than providing direct access to the indices or data streams. However, if direct index access is required, system index descriptors can be defined as “external” (see SystemIndexDescriptor.Type).

A SystemIndexPlugin may also specify “associated indices,” which hold plugin state in user space. These indices are not managed or protected, but they are included in snapshots of the feature.

An implementation of SystemIndexPlugin may override cleanUpFeature(ClusterService, Client, ActionListener) in order to provide a “factory reset” of the plugin state. This can be useful for testing. The default method will simply retrieve a list of system and associated indices and delete them.

An implementation may also override prepareForIndicesMigration(ClusterService, Client, ActionListener) and indicesMigrationComplete(Map, ClusterService, Client, ActionListener) in order to take special action before and after a feature migration, which will temporarily block access to system indices. For example, a plugin might want to enter a safe mode and reject certain requests while the migration is in progress. See SystemIndexMigrationExecutor for more details.

After plugins are loaded, the SystemIndices class will provide the rest of the system with access to the feature's descriptors.

  • Method Details

    • getSystemIndexDescriptors

      default Collection<SystemIndexDescriptor> getSystemIndexDescriptors(Settings settings)
      Returns a Collection of SystemIndexDescriptors that describe this plugin's system indices, including name, mapping, and settings.
      Parameters:
      settings - The node's settings. Note that although this parameter is not heavily used in our codebase, it could be an excellent way to make the definition of a system index responsive to settings on the node.
      Returns:
      Descriptions of the system indices managed by this plugin.

    • getSystemDataStreamDescriptors

      default Collection<SystemDataStreamDescriptor> getSystemDataStreamDescriptors()

    • getFeatureName

      String getFeatureName()
      Returns:
      The name of the feature, as used for specifying feature states in snapshot creation and restoration.

    • getFeatureDescription

      String getFeatureDescription()
      Returns:
      A description of the feature, as used for the Get Snapshottable Features API.

    • getAssociatedIndexDescriptors

      default Collection<AssociatedIndexDescriptor> getAssociatedIndexDescriptors()
      Returns a list of descriptors for "associated indices": indices which depend on this plugin's system indices, but are not themselves system indices.
      Returns:
      A list of descriptors of indices which depend on the contents of this plugin's system indices, but are not themselves system indices

    • cleanUpFeature

      default void cleanUpFeature(ClusterService clusterService, Client client, ActionListener<ResetFeatureStateResponse.ResetFeatureStateStatus> listener)
      Cleans up the state of the feature by deleting system indices and associated indices. Override to do more for cleanup (e.g. cancelling tasks).
      Parameters:
      clusterService - Cluster service to provide cluster state
      client - A client, for executing actions
      listener - Listener for post-cleanup result

    • prepareForIndicesMigration

      default void prepareForIndicesMigration(ClusterService clusterService, Client client, ActionListener<Map<String,Object>> listener)
      A method used to signal that the system indices owned by this plugin are about to be upgraded. This method will typically be called once, before any changes are made to the system indices owned by this plugin. However, if there is a master failover at exactly the wrong time during the upgrade process, this may be called more than once, though this should be very rare. This method can also store metadata to be passed to indicesMigrationComplete(Map, ClusterService, Client, ActionListener) when it is called; see the listener parameter for details.
      Parameters:
      clusterService - The cluster service.
      client - A ParentTaskAssigningClient with the parent task set to the upgrade task. Does not set the origin header, so implementors of this method will likely want to wrap it in an OriginSettingClient.
      listener - A listener that should have ActionListener.onResponse(Object) called once all necessary preparations for the upgrade of indices owned by this plugin have been completed. The Map passed to the listener will be stored and passed to indicesMigrationComplete(Map, ClusterService, Client, ActionListener). Note the contents of the map *must* be writeable using StreamOutput.writeGenericValue(Object).

    • indicesMigrationComplete

      default void indicesMigrationComplete(Map<String,Object> preUpgradeMetadata, ClusterService clusterService, Client client, ActionListener<Boolean> listener)
      A method used to signal that the system indices owned by this plugin have been upgraded and all restrictions (i.e. write blocks) necessary for the upgrade have been lifted from the indices owned by this plugin. This method will be called once, after all system indices owned by this plugin have been upgraded. Note that the upgrade may not have completed successfully, but if not, all write blocks/etc. will have been removed from the indices in question anyway as the upgrade process tries not to leave anything in an unusable state. Note: This method may need additional parameters when we support breaking mapping changes, as in that case we can't assume that any indices which were not upgraded can still be used (whereas we can assume that while the upgrade process is limited to reindexing, with no data format changes allowed).
      Parameters:
      preUpgradeMetadata - The metadata that was given to the listener by prepareForIndicesMigration(ClusterService, Client, ActionListener).
      clusterService - The cluster service.
      client - A ParentTaskAssigningClient with the parent task set to the upgrade task. Does not set the origin header, so implementors of this method will likely want to wrap it in an OriginSettingClient.
      listener - A listener that should have ActionListener.onResponse(true) called once all actions following the upgrade of this plugin's system indices have been completed.