Rundeck Salt-Step Plugin
Build / Deploy
- To build the project from source, issue:
./gradlew clean build
- The resulting jar files can be found under
- Copy the
rundeck-salt-plugin-<version>.jarfile to your
- Restart Rundeck
- You should now have an additional "salt remote" option when configuring jobs
- Rundeck node resource IDs MUST match salt minion IDs
The following job-level params must be configured to provide authentication input fields:
SALT_USER- standard input field, required.
SALT_PASSWORD- secure input field, required. NOTE the option should *not be set as a secure remote authentication option*
- Workflow configuration must be set to dispatch to nodes.
Remote execution over salt-api
NOTE: This plugin leverages salt-api, which requires its own additional setup. For more information on how to setup salt-api please refer to its documentation which can be found here.
This plugin requires three properties that need to be configured for each step:
SALT_API_END_POINT: the URL of the salt-api endpoint (e.g. https://localhost:8000)
Function: the function to be passed to the salt-api call (excluding the target) -- For example, if you enter
test.pingfor the function value, the resulting salt call will be
salt <yourHostName> test.ping. The target will always default to the hostname of the Rundeck server.
SALT_API_EAUTH: the authentication mechanism that should be used by salt-api -- This would be the equivalent to the
-aparameter being passed on the command line (e.g.
salt -a pam <target> test.ping)
SALT_API_VERSION(optional): The expected version of salt-api. Defaults to latest if left blank.
- Ensure that your salt-api setup is fully functional before attempting to execute jobs with this plugin
- Set the job output level to
debugto print the raw JSON data and returned output
- Ensure the API endpoint is correct -- http vs https
Setting up salt return response parsers
This plugin interacts with salt and salt-api. By default, it requests JSON payloads. YAML configuration files are used to determine how it should parse the output and behave with respect to exit codes, standard output, and standard error.
YAML Configuration File Format
handlerMappings: <salt module>[.<salt function>]: <java object implementing org.rundeck.plugin.salt.output.SaltReturnHandler>
Salt-step is configured in two locations:
_saltStep.returnHandlers_property accepts a comma separated list of additional configuration files
Thanks for contributing to the project!
- Same line braces.
- 4 spaces for tabs.
- Clarity over brevity.
- When in doubt, follow what's already there.
- At the very minimum, please ensure that class-level and method-level javadocs are present.
- While we don't expect 100% coverage, we do expect repeatable, automated tests.
- Include unit tests that confirm that your change performs as expected (e.g. new feature or bug fix).
Before submitting a pull request
- Merge the latest master branch before submitting a pull request.
- Perform a build (
./gradlew clean build) and confirm that all tests are passing.
- Ensure that all documentation (e.g.
README.mdor other supporting links) is updated.
- Rebase changes into as few commits as makes sense.
- Ensure that all commit messages accurately describe the changes.
Submitting a pull request
- Submit a pull request to the master branch of this project.
- Ensure that the pull request has a clear description of the included changes.