Page History

...

Cassandra makes use of the JMX to expose the management commands, such as taking a snapshot operation of specified keyspaces, with local JMX access enabled by default and remote access enabled by configuration when it's needed. JMX is used as the transport layer for command execution by all most of the management tools, such as the built-in command line tool, the `nodetool` that ships with the Cassandra itself, or the Cassandra Sidecar a standalone JVM process that runs alongside the Cassandra server daemon and is used for the configuration management and/or metrics exposure.

...

• Asynchronous execution, preferably with a UUID for each execution to track the execution result;
• A single command registry, to provide generic command metadata to the API consumers such as CLI tools, or other ecosystem products. This concept is borrowed from the Dropwizard metrics registry and shares the same idea;
• A dedicated admin port with the native protocol behind it, allowing only admin commands, to address the concerns when the native protocol is disabled in certain circumstances e.g. the disablebinary command is executed;
• Management via CQL must be developed alongside existing C* management API such as statically registered JMX MBeans, to ensure backward compatibility for ecosystem products that rely on it. However, this doesn't mean that new commands have to be implemented twice when they are required;
• Reduce the cost of implementing a new command, meaning that once a new command is registered in the command registry, it is automatically available through all of the public interfaces we support e.g. JMX, CQL. There is no need to implement a new command for the CLI tools, such as the nodetool, or the corresponding MBeans, a new command must be available there out of the box.

...

Cassandra Solutions

Currently, there are a few ways to perform management operations:

...

The starting point for management operations is the CommandRegistry (or OperationManager), which is a collection of all commands or subcommands for C* management commands.

Command Registry Adapters

public interface CommandRegistry<A, R> extends Command<A, R>
{
    public Command<?, ?> command(String name);
    public Iterator<Map.Entry<String, Command<?, ?>>> commands();
}

Command API

The nodetool CLI uses the Airline annotation-based framework [6] to parse input arguments and execute management commands from the command line; these annotations already contain all the necessary command metadata including input arguments, their descriptions, and general command details. A significant limitation, however, is that the metadata is embedded in the CLI tool itself, making it inaccessible on the C* server node. As a result, the metadata can't be shared with other API consumers involved in management operations. Direct migration of all CLI commands to the CommandRegistry is not feasible as well. This is not only due to the obsolescence of the Airline library, but also because it lacks the necessary abstractions to support a transparent and aligned reflection of available commands in the CLI, JMX, and REST API (represented as k8ssandra management API project) that we have, and thus such a reflection requires a more narrow approach to ensure consistency and compatibility across different management interfaces.

Therefore, the Command API might look like this:

public interface Command<A, R>
{
    public String description();

    public Class<? extends A> argClass();

    public R execute(A arg);

    /** Custom output required to preserve backwards compatibility with the nodetool output. */
    public default void printResult(A arg, R res, Consumer<String> printer) {}
}

public CompactCommand implements Command<CompactCommandArg, Response> 
{
    public String description()
    {
        return "Force a (major) compaction on one or more tables or user-defined compaction on given SSTables";
    }

    public Class<? extends A> argClass()
    {
        return CompactCommandArg.class;
    }

    // The rest part of the class.
}

@ArgumentGroup(value = {"userDefined", "startToken", "partitionKey"}, optional = true, oneOf = true)
public class CompactCommandArg implements Serializable 
{
  @Argument(aliases = {"s", "split-output"}, description = "Use -s to not create a single big file", optional = true)
  public final boolean splitOutput;

  @Argument(aliases = {"user-defined"}, description = "Use --user-defined to submit listed files for user-defined compaction")
  public final boolean userDefined;

  @Argument(aliases = {"st", "start-token"}, description = "Use --user-defined to submit listed files for user-defined compaction", optional = true)
  public final String startToken;

  @Argument(aliases = {"et", "end-token"}, description = "Use -et to specify a token at which compaction range ends (inclusive)", optional = true)
  public final String endToken;

  @Argument(aliases = {"partition", "partition_key"}, description = "String representation of the partition key", optional = true)
  private String partitionKey;

  @Argument(aliases = {"keyspace"}, description = "The keyspace followed by one or many tables or list of SSTable data files when using --user-defined")
  public final String keyspaceName;

  @Argument(description = "The table names to compact")
  public final List<String> tables;

  // The rest part of the class.
}

Command Registry Adapters

Once the CommandRegistry is available, some out-of-the-box adapters must be developed to achieve the goals of the proposal and make the commands available through JMX, CQL and indirectly REST APIOnce the CommandRegistry is available, some out-of-the-box adapters must be developed to achieve the goals of the proposal and make the commands available through JMX and CQL:

1. CQL Command Adapter - The CQL invoker validates the given arguments based on the command metadata from CommandRegistry and invokes the corresponding command;
2. Dynamic Command MBean Adapter - New dynamic JMX MBeans for management operations are generated and exposed to public API based on available command metadata for use by the nodetool. The JMX MBeans that are now statically registered are still supported. However, they are deprecated in favour of new ones;
3. Open API Adapter - an adapter that provides dynamically generated RESTful API endpoints based on the CommandRegistry metadata as well as `openapi.json` specification; 

...

CQL Command Syntax

The commands below become valid. While many commands in Apache Cassandra are typically run on keyspaces and tables, and adopting a CQL syntax like `EXECUTE COMMAND rebuild ON keyspace.table` seems logical, it's more practical for the initial implementation to concentrate on accepting command arguments as straightforward key-value pairs or as a JSON string. This approach simplifies the early stages of development. Subsequently, the more intuitive CQL syntax can be introduced as an alias for these commands, enhancing usability and aligning with familiar patterns.

...

• New dynamic JMX MBeans must be created to expose the available commands to the public API in a way that matches the corresponding CQL queries. The API that is provided by static MBeans and the CLI are too far apart.
• The nodetool uses a newly created dynamic MBean to achieve both API alignment and API backward compatibility goals;
• The nodetool parses the input arguments based on the command metadata it receives from the CommandRegistry;

Minimum Viable Product (MVP)

Although the scope has been described quite broadly, the minimum viable product includes the following changes:

...