Skip to content
This repository has been archived by the owner on Sep 7, 2022. It is now read-only.

Modules

Jump to bottom
jlin21 edited this page Feb 29, 2016 · 23 revisions

What is a Module?

Modules are "plugins" which get executed in each task. Modules are generally scripts which perform various commands such as running a shell command, manage packages, cURL requests, etc.

Creating a Module

Creating modules are easy! Inputs to modules will be in the format of a JSON object as a string. The module only needs to read system input and apply it through a JSON parser to receive the module parameters. After the module executes, it only needs to return a stringified JSON object with the fields:

  • Msg
  • Output
  • State
    ('ok' , 'changed', 'skipped', 'failure', 'error', 'unreachable')

Modules should be placed in the modules folder located in the same level as main.go, and can be accessed by tasks by which the module is named. In addition, modules can be created in two ways. The first being a standalone script using only standard libraries. For example, the shell module is a standalone script. The second method is to create a directory of what the module is to be called. In this directory there should be a script named exec and any packages/libraries/modules the exec script depends on. The curl module is an example of this method.

This is a skeleton of a module written in python. Refer to the shell or curl module for a detailed example.

#!/usr/bin/env python

import sys
import json
import os

# if this module is using method two
sys.path.append(os.path.dirname(os.path.realpath(__file__)) + "/package_name")
import package_name

# convert the input string to a json format
params = json.loads(sys.stdin.read())

# NOTE: How a call for this module would look like in a task
# - name: "task dummy"
#   skeleton: foo="bar" bar="foo"
#
# Params for this module
# foo:  does bar
# bar:  does foo
result = {}
try:
    foo = params.get("foo", "/bin/sh")
    bar = params.get("bar")

    if not foo:
        raise Exception("Required parameter 'foo' not found")
    
    result["status"] = "ok"
    result["output"] = "Generally the output of the functions"
    result["msg"] = "Successfully exec'ed command"
except Exception as e:
    result["status"] = "error"
    result["msg"] = "Exec'ed command failed"
    result["output"] = str(e)

# convert the result to a string to be consumed by henchman
print json.dumps(result)

List of Modules Available

copy

Copy the specified file or folder to the destination. Params:

  • src (required) - location of file to be copied
  • dest (required)- location of file to be stored (Absolute paths give the best results). This will be the file/folder name NOT the folder it's in.
  • owner - defaults to the user. Can be overridden
  • group - defaults to the user. Can be overridden
  • mode - defaults to 0644 for files and 0775 for directories.
  • override - Defaults to true.
    • If false and the dest is a file, nothing will happen, else it will be overwritten.
    • If the dest is a folder and the src is a folder, the two folders will be merged. If the override is true existing files with the same name will be overwritten, otherwise existing files with the same name will be preserved.

curl

Executes curl commands. Currently only supports GET, PUT, POST, DELETE, OPTIONS.
Params:

  • url - Url to be curl'd (required)
  • http - Set the http method. Defaults to GET.
  • headers - Sets header values. To set headers, use "key:value,key:value" format.
  • data - Sets any data to be sent (E.G for Post calls). Use "key:value,key:value" format.

Returns:

  • State - ok or error
  • Msg - If the http call succeeds or not. Will also notify of non supported Content-Types as the payload.
  • Output - the payload with key value pairs of...
    • status - status code
    • headers - map of headers (NOTE: all key and values are strings)
    • body - map of the payload (NOTE: currently only converts json and xml payloads. To add more supported Content-Types submit an issue)

rpm

Install a package using rpm.
Params:

  • url - url that provides the rpm that should be installed

shell

Runs a shell command.
Params:

  • chdir - cd into the given directory to execute the shell command
  • shell - The shell to use, by default it's /bin/sh
  • cmd - The command to run. Wrapped by quotes if there are spaces. (required)
  • env - Environment variables to be run with the cmd. E.G "key=value key=value key=value"

template

Renders and copies over a file/folder.
Params:

  • src - location of file/folder to be copied
  • dest - location of file/folder to be stored
  • override - Defaults to true. If false the src file/folder retains its name and will be placed in the folder specified in dest.
  • ext - Any file/folder containing these file extensions won't be rendered. Default exts are "zip,sh,tar"
  • override - Defaults to true.
    • If false and the dest is a file, nothing will happen, else it will be overwritten.
    • If the dest is a folder and the src is a folder, the two folders will be merged. If the override is true existing files with the same name will be overwritten, otherwise existing files with the same name will be preserved.

yum

Install a package using yum.
Params:

  • name - the name of the package to be installed
  • version - the version of the package to be installed. Use latest or omit this field to use the latest version
  • state - specify present or absent to specify if yum should install or uninstall the package. If present then the package will check if package exists and install it if it does not exist. Absent does the opposite.
  • repo - specify the repo to use.
Clone this wiki locally