Motivation

The IEP is intended to simplify, standardise, unifies development of Ignite management commands by providing declarative API for arguments and unified command invokers via various protocols - CLI, JMX, REST.

Overview

All of Ignite Cluster management operations are presented as running compute tasks over the cluster. Depending on the management operation required to be executed some of the tasks are running on a single Ignite node only or performing full compute operation overall cluster nodes with reducing the computation result on the originating node.

For instance, single-node operations may look the following:

• running a built-in internal distributed operations e.g. IndexForceRebuiltTask;
• cancelling internal operations that are currently being run e.g.  VisorScanQueryCancelTask;

Distributed management compute tasks may look the following:

• collecting info about internal structures e.g. MetadataInfoTask;
• custom check operations over the cluster e.g. CheckIndexInlineSizesTask;

Limitations

Command API Exposure

Each time a new management task is added or is required to be added the developer should take into account the following things:

• a task must be exposed to the Ignite REST API (a new implementation of GridRestCommandHandler must be developed);
• a task must be exposed to the Ignite JMX API (a new MXBean interfaces and implementations must be added);
• a task must be exposed to the Ignite CLI (a new extension of AbstractCommand must be implemented);

Without handlers and abstractions mentioned above, a new management task won't be available for a user even if it persists in the node classpath (it's still possible to run it using the ignite thin client). Most of such handlers and abstractions look like a boilerplate code and must be covered by some internal command exposer.

There are no any sufficient abstractions in any protocol and each protocol has (or has no if you lucky) slightly different logic.

Moreover, format of arguments, help messages and other things are not standardized and have different logic from command to command. 

Command Plugin Extension

Ignite plugins have no control over the cluster management operations. The built-in management tasks can't be extended by Ignite running with custom plugins and even more, they can't be available through the standard Ignite's REST, JMX, CLI APIs.

Description

This IEP is primary focused on providing good abstraction for command invocation which includes:

• Internal framework to declarative command definition.
• Migration of existing commands to new framework without any changes in public behavior(if possible).
• Creation of commands registry which provide unified access to all commands known by Ignite. 
• Creation of invokers for all popular protocols. Each invoker must be able to invoke any of the command based on definition:
  • CLI - control.sh.
  • JMX.
  • REST - Open API bindings and REST endpoint.
• Automatic documentation creation:
  • Ascii doc during release preparation.
  • man/tldr pages.

Keeping in mind that command will be described in declarative way all newly created commands will be automatically available and used by all of the features above. 

Design Model

Command Execution

The ComputeTask is a common way for building various cluster management commands with the ability to execute them via Ignite Binary Protocol. Taking into account the current limitations mentioned above the following must be a part of design solution to create a common internal management API:

1. A ProxyManagementTask - an entry point for each management request through the thin client API.
2. Input arguments to find the required command by given path.
3. Input argements to execute the corresponding command with. This is a map of parameters with String  as a key, and String  or String[]  as a value.
4. The output execution result – BinaryObject. It may be formatted to different string results depending on what type of client is used (e.g. REST, CLI, JMX). 

Command Execution Model

Command Interface

Management commands are always wrapped with the ProxyManagementTask. The management command may be executed on a single cluster node only or broadcast to all nodes with reducing the execution results.

/** */
public interface IgniteCommand<T> extends IgniteCallable<T>, IgniteReducer<T, T> {
    /** {@inheritDoc} */
    @Override public default boolean collect(@Nullable T t) {
        return true;
    }

    /** {@inheritDoc} */
    @Override public default T reduce() {
        return null;
    }
}

/** */
@Command(name = "add",
    commandDescription = "Add nodes to baseline topology.")
public class BaselineAddCommand implements IgniteCallable<String> {
    /** Auto-injected Ignite instance. */
    @IgniteInstanceResource
    private IgniteEx ignite;

    /** Parameter will be injected on command instantiation. Default comma separation. */
    @Parameter(names = {"--nodes", "-n"}, description = "List of baseline nodes to add.")
    private List<String> consistentIds;

    /** {@inheritDoc} */
    @Override public String call() throws Exception {
        Collection<BaselineNode> baseline = ignite.cluster().currentBaselineTopology();
        Collection<ClusterNode> srvs = ignite.cluster().forServers().nodes();

        for (String consistentId : consistentIds) {
            ClusterNode node = F.find(srvs, null, new IgnitePredicate<ClusterNode>() {
                @Override public boolean apply(ClusterNode node) {
                    return node.consistentId().toString().equals(consistentId);
                }
            });

            if (node == null)
                throw new IllegalArgumentException("Node not found for consistent ID: " + consistentId);

            baseline.add(node);
        }

        ignite.cluster().setBaselineTopology(baseline);

        return consistentIds.toString();
    }
}

Roadmap

Phase-1

The following changes must be introduced to allow new command creation and migration processes:

• annotations to mark up command classes and annotation-based scanner to fill-up the command registry;
• command registry (available for clients and for server nodes);
• input string parsers for CLI, REST, JMX interfaces to allow command migration to a new CommandRegistry;
• proxy compute task for commands management through the GridTaskExecutor;

Phase-2

To be done.

Risks and Assumptions

Although most of the commands are available through the REST, CLI, JMX APIs some of the commands may have various input arguments and/or input argument types in different sub-systems. This may require some breaking changes through all APIs being migrated to the new cluster management API.

Discussion Links

// Links to discussions on the devlist, if applicable.

Reference Links

[1] https://www.mail-archive.com/dev@ignite.apache.org/msg49612.html

[2] https://jcommander.org/

[3] https://picocli.info/

Tickets