Salt Step
Rundeck, Inc.

Allows Rundeck to delegate tasks to a Salt master by executing the request over salt-api.

Rundeck Salt-Step Plugin

Description

A Rundeck NodeStepPlugin that allows Rundeck to delegate tasks to a Salt master by executing the request over salt-api.

Build / Deploy

  • To build the project from source, issue: ./gradlew clean build
  • The resulting jar files can be found under build/libs.
  • Copy the rundeck-salt-plugin-<version>.jar file to your $RDECK_BASE/libext folder
  • Restart Rundeck
  • You should now have an additional "salt remote" option when configuring jobs

Configuration

  • Rundeck node resource IDs MUST match salt minion IDs

Usage

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

Additionally:

  • 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.ping for 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 authenticati​on mechanism that should be used by salt-api -- This would be the equivalent to the -a parameter 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.

Troubleshooting

  • Ensure that your salt-api setup is fully functional before attempting to execute jobs with this plugin
  • Set the job output level to debug to 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 configuratio​n 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:

  • src/main/resources/defaultReturners.yaml
  • ​rundeck-​config.​properties: The _saltStep.​return​Handlers_ property accepts a comma separated list of additional configuratio​n files

Developer Guidelines

Thanks for contributing to the project!

Code style

  • Same line braces.
  • 4 spaces for tabs.
  • Clarity over brevity.
  • When in doubt, follow what's already there.

Javadocs

  • At the very minimum, please ensure that class-level and method-level javadocs are present.

Unit tests

  • 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.md or 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.