The Marionette Collective 1.1.1 and newer supports a single executable - called mco - and have a plugin type called application that lets you create applications for this single executable.
In the past we tended to write small standalone scripts to interact with MCollective, this had a number of issues:
- Large number of executables in /usr/sbin
- Applications behave inconsistently with regard to error handling and reporting
- Discovering new applications is difficult since they are all over the filesystem
- Installation and packaging of plugins is complex
We’ve attempted to address these concerns by creating a single point of access for all applications - the mco script - with unified help, error reporting and option parsing.
Below you can see the single executable system in use:
These applications are equivalent to the old mc-rpc and similar applications but without the problem of lots of files in /usr/sbin.
Applications goes in libdir/mcollective/application/echo.rb, the one below is a simple application that speaks to a hypothetical echo action of a helloworld agent. This agent has been demonstrated in : writing agents.
Here’s the application we wrote in action:
Most of the techniques documented in SimpleRPC Clients can be reused here, we’ve just simplified a lot of the common used patterns like CLI arguments and incorporated it all in a single framework.
To add custom usage messages to your application we can add lines like this:
You can add several of these messages by just adding multiple such lines.
A standard options hash is available simply as options you can manipulate it and pass it into the RPC Client like normal. See the SimpleRPC Clients reference for more on this.
CLI Argument Parsing
There are several options available to assist in parsing CLI arguments. The most basic option is:
In this case if the user used either
-m message or
--message message on the CLI the desired message would be in
You can require that a certain parameter is always passed:
Argument data types
CLI arguments can be forced to a specific type, we also have some additional special types that the default ruby option parser cant handle on its own.
You can force data to be of type String, Integer etc:
You can force an argument to be boolean:
If you have an argument that can be called many times you can force that to build an array:
Here if you supplied multiple arguments
configuration[:args] will be an array with all the options supplied.
You can validate input passed on the CLI:
Should the supplied value be 10 or more a error message will be displayed.
Disabling standard sections of arguments
By default every Application get all the RPC options enabling filtering, discovery etc. In some cases this is undesirable so we let users disable those.
This application will only have –help, –verbose and –config as options, all the other options will be removed.
Post argument parsing hook
Right after all arguments are parsed you can have a hook in your program called, this hook could perhaps parse the remaining data on ARGV after option parsing is complete.
After the options are parsed and the post hook is called you can validate the contents of the configuration:
Exiting your application
You can use the normal exit Ruby method at any time to exit your application and you can supply any exit code as normal.
The supplied applications have a standard exit code convention, if you want your applications to exhibit the same behavior use the halt helper. The exit codes are below:
|0||Nodes were discovered and all passed|
|0||No discovery was done but responses were received|
|1||No nodes were discovered|
|2||Nodes were discovered but some responses failed|
|3||Nodes were discovered but no responses were received|
|4||No discovery were done and no responses were received|
As you can see you pass the halt helper an instance of the RPC Client statistics and it will then use that to do the right exit code.