Hello,
I have drafted a PIP around this proposal.
PIP link: https://github.com/apache/pulsar/issues/17155
I am preparing an official PR, I already have a working prototype.
Copy of the contents of the GH issue is attached for discussion here
on the Mailing list.
Motivation
There are many projects that are in the Pulsar ecosystem like Protocol
Handlers (Kafka, MQTT, RabbitMQ) and libraries (JMS…) that need
additional tools for operating Pulsar following specific conventions
adopted by each project and to handle custom domain objects (like JMS
queues, Kafka Consumer Groups...).
Some examples:
Kafka: tools for inspecting internal systems, SchemaRegistry,
Transaction Manager, Consumers Groups
JMS: tools to handling Subscriptions and Selectors
RabbitMQ: tools to handle Pulsar topics and subscription following the
convention
This is very important as it is hard to follow the conventions of each
project using pulsar-admin and the administrator may inadvertently
break the system.
This feature will enhance the UX of the Pulsar Admin CLI tools for the
benefit of the whole ecosystem and users.
Goal
As we do for many other components in Pulsar, we need a way to enhance
the CLI tools, pulsar-admin and pulsar-shell, with additional commands
that are specific to the additional features.
The proposal here is to add an extension mechanism to the pulsar-admin
(and so pulsar-shell) tool.
Following the usual conventions for extensions the extension will be
bundled in a .nar file that may contain additional third party
libraries.
The extension will be able to provide new top level commands
pulsar-admin my-command-group my-command arguments…
The extension will be able to access the PulsarAdmin API provided by
the environment.
The extension must not depend directly on the JCommander library but
we will provide an API to declare the parameters and the other
metadata necessary to document and execute the command.
This is very important because during the lifecycle of Pulsar the
project may decide to upgrade JCommander to an incompatible version or
to drop the dependency at all.
API Changes
We will introduce a new Maven module pulsar-tools-api that contains
the public API that can be used by implementations of the custom
commands.
The implementation will be bundled in a .nar file with a descriptor
with the following fields:
factoryClass: xxxxx.CommandFactory
name: extension-name
description: Description...
There are the new classes:
/**
Access to the environment
*/
public interface CommandExecutionContext {
PulsarAdmin getPulsarAdmin();
Properties getConfiguration();
}
/**
* Custom command implementation
*/
public interface CustomCommand {
String name();
String description();
List<ParameterDescriptor> parameters();
boolean execute(Map<String, Object> parameters,
CommandExecutionContext context) throws Exception;
}
/**
* A group of commands.
*/
public interface CustomCommandGroup {
String name();
String description();
List<CustomCommand> commands(CommandExecutionContext context);
}
/**
* Main entry point of the extension
*/
public interface CustomCommandFactory {
/**
* Generate the available command groups.
*/
List<CustomCommandGroup> commandGroups(CommandExecutionContext context);
}
@Builder
@Getter
public final class ParameterDescriptor {
@Builder.Default
private String name = "";
@Builder.Default
private String description = "";
private ParameterType type = ParameterType.STRING;
private boolean required = false;
}
