Ansible

The ansible part of the library implements

Ansible Playbook execution by providing a configuration object
Checking out Ansible Galaxy requirements to track role changes
Getting Ansible Galaxy role info from the galaxy API

`checkoutRequirements(String requirementsYmlPath)`

This step checks out all ansible galaxy role requirements into subdirectories of the workspace to track SCM changes in the depending roles. For Ansible Galaxy roles the src Attribute is used, for scm roles the name attribute is used

This currently works for:

Ansible Galaxy roles (with and without version)
Git scm Roles

💡 The roles are checkout into sub folders using the name (src for Ansible Galaxy Roles) of the role.

Example of a `requirements.yml`

- src: williamyeh.oracle-java
- src: tecris.maven
  version: v3.5.2
- src: https://github.com/wcm-io-devops/ansible-aem-cms.git
  name: aem-cms
  scm: git
- src: https://github.com/wcm-io-devops/ansible-aem-service.git
  name: aem-service
  scm: git
  version: develop

This requirements.yml will result in a checkout of four repositories:

https://github.com/William-Yeh/ansible-oracle-java.git (master) into folder "williamyeh.oracle-java"
https://github.com/tecris/ansible-maven.git (tag v3.5.2) into folder "tecris.maven"
https://github.com/wcm-io-devops/ansible-aem-cms.git (master) into folder "aem-cms"
https://github.com/wcm-io-devops/ansible-aem-service.git (master) into folder "aem-service"

Process

Load the provided yaml file
Parse the roles into Role objects by using RoleRequirements
Get API info for each Ansible Galaxy Role by using getGalaxyRoleInfo
1. When API info is available set the github url and branch into the Role
Transform the roles into configurations for the checkoutScm step
Checkout the SCM using the checkoutScm step

`execPlaybook(Map config)`

This step can be used to execute a Ansible Playbook.

Features

`--extra-vars` as JSON

The step transforms all given extra vars into JSON before calling the Ansible Playbook. This ensures that the types like boolean and integer are retained.

💡 These extra vars are combined with build parameters when ANSIBLE_INJECT_PARAMS is enabled.

Example

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

Map config = [
    (ANSIBLE) : [
        (ANSIBLE_INSTALLATION) : '<ansible-installation-id>',
        (ANSIBLE_PLAYBOOK) : 'path/to/playbook.yml',
        (ANSIBLE_INVENTORY) : 'path/to/inventory',
        (ANSIBLE_EXTRA_VARS) : [
            "string": "value",
            "boolean" : true,
            "integer" : 1,
            "list" : [1,2,3,4]
        ]
    ]
]

ansible.execPlaybook(config)

This config will execute the ansible playbook with the following --extra-vars parameter

ansible-playbook --extra-vars '{"string":"value","boolean":true,"integer":1,"list":[1,2,3,4]}' [...]

Inject Build parameters into `--extra-vars`

When enabled the step will automatically add all build parameters as extra variables an pass it to the playbook. :bulb: These extra vars are combined with the variables defined via ANSIBLE_EXTRA_VARS.

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

properties([
	parameters([
		booleanParam(defaultValue: false, description: '...', name: 'boolparam'), 
		choice(choices: 'choice1\nchoice2', description: '..', name: 'choiceparam'), 
		string(defaultValue: 'stringvalue', description: '..', name: 'stringparam')]), 
	]
)

Map config = [
    (ANSIBLE) : [
        (ANSIBLE_INSTALLATION) : '<ansible-installation-id>',
        (ANSIBLE_PLAYBOOK) : 'path/to/playbook.yml',
        (ANSIBLE_INVENTORY) : 'path/to/inventory',
        (ANSIBLE_INJECT_PARAMS) : true
    ]
]

ansible.execPlaybook(config)

This config will execute the ansible playbook with the following --extra-vars parameter

ansible-playbook --extra-vars '{"boolparam":false,"choiceparam":"choice1","stringparam":"defaultValue"}' [...]

❗ Pleaes note that all parameters are injected. If you want to decide which parameters are added as extra params use the ANSIBLE_EXTRA_VARS configuration option.

Extra parameters

The step provides a convenient way to add extra parameters to the command line.

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

Map config = [
    (ANSIBLE) : [
        (ANSIBLE_INSTALLATION) : '<ansible-installation-id>',
        (ANSIBLE_PLAYBOOK) : 'path/to/playbook.yml',
        (ANSIBLE_INVENTORY) : 'path/to/inventory',
        (ANSIBLE_EXTRA_PARAMETERS) : ["-v"]
    ]
]

ansible.execPlaybook(config)

This config will execute the ansible playbook with the -v parameter

ansible-playbook -v [...]

Configuration Options

Complete list of all configuration options.

All configuration options must be inside the ansible (ConfigConstants.ANSIBLE) map element to be evaluated and used by the step.

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

ansible.execPlaybook(
        (ANSIBLE): [
            (ANSIBLE_COLORIZED)       : true,
            (ANSIBLE_EXTRA_PARAMETERS): ["-list","-of","-params"],
            (ANSIBLE_EXTRA_VARS)      : [ "<name1>" : "<value1>", "<name2>" : "<value2>" ],
            (ANSIBLE_FORKS)           : 5,
            (ANSIBLE_INSTALLATION)    : "<ansible-installation>",
            (ANSIBLE_INVENTORY)       : "<path/to/inventory>",
            (ANSIBLE_LIMIT)           : "<limit>",
            (ANSIBLE_PLAYBOOK)        : "<path/to/playbook>",
            (ANSIBLE_CREDENTIALS_ID)  : "<credentials/id>",
            (ANSIBLE_SKIPPED_TAGS)    : "<tags-to-skip>",
            (ANSIBLE_START_AT_TASK)   : "<task-to-start-at>",
            (ANSIBLE_SUDO)            : false,
            (ANSIBLE_SUDO_USER)       : "<ansible-sudo-user>",
            (ANSIBLE_TAGS)            : "<tags-to-execute>",
            (ANSIBLE_INJECT_PARAMS)   : false
        ]
    )

`colorized` (optional)


Constant	`ConfigConstants.ANSIBLE_COLORIZED`
Type	`Boolean`
Default	`true`

Controls the colorized output of ansible. Default is set to true.

`credentialsId` (optional)


Constant	`ConfigConstants.ANSIBLE_CREDENTIALS_ID`
Type	`String`
Default	`null`

Use this option to pass SSH credentials.

💡 It is recommended to use the sshAgentWrapper instead.

`extraParameters` (optional)


Constant	`ConfigConstants.ANSIBLE_EXTRA_PARAMETERS`
Type	`List` of `String`
Default	`[]`

Extra parameters that will be passed to ansible-playbook commandline

Example: This example will add -v to the command line.

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

Map config = {
    (ANSIBLE) : [
        (ANSIBLE_EXTRA_PARAMETERS) : ["-v"]
        // ...
    ]
]

`extraVars` (optional)


Constant	`ConfigConstants.ANSIBLE_EXTRA_VARS`
Type	`Map`
Default	`[:]`

Can be used to define --extra-vars which will be passed in JSON format to the command line.

💡 When injectParams is used they will be combined with the injected build parameters.

Example: This example will add --extra-vars '{"string":"value","boolean":true,"integer":1,"list":[1,2,3,4]}' to the command line.

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

Map config = [
    (ANSIBLE) : [
        (ANSIBLE_INSTALLATION) : '<ansible-installation-id>',
        (ANSIBLE_PLAYBOOK) : 'path/to/playbook.yml',
        (ANSIBLE_INVENTORY) : 'path/to/inventory',
        (ANSIBLE_EXTRA_VARS) : [
            "string": "value",
            "boolean" : true,
            "integer" : 1,
            "list" : [1,2,3,4]
        ]
    ]
]

`forks` (optional)


Constant	`ConfigConstants.ANSIBLE_FORKS`
Type	`Integer`
Default	`5`

Controls how many forks will be used during Ansible Playbook execution.

`injectParams` (optional)


Constant	`ConfigConstants.ANSIBLE_INJECT_PARAMS`
Type	`Boolean`
Default	`false`

When enabled all build parameters are injected into --extra-vars* :bulb: When extraVars are defined they will be combined with the injected params.

`installation`


Constant	`ConfigConstants.ANSIBLE_INSTALLATION`
Type	`String`
Default	`null`

Controls which ansible installation will be used for playbook execution.

`inventory`


Constant	`ConfigConstants.ANSIBLE_INVENTORY`
Type	`String`
Default	`null`

Specifies the path to the Ansible Playbook inventory.

`limit` (optional)


Constant	`ConfigConstants.ANSIBLE_LIMIT`
Type	`String`
Default	`null`

When set the configured value will be passed as --limit <value> to the Ansible Playbook.

`playbook`


Constant	`ConfigConstants.ANSIBLE_PLAYBOOK`
Type	`String`
Default	`null`

Specifies the path to the Ansible Playbook.

`skippedTags` (optional)


Constant	`ConfigConstants.ANSIBLE_SKIPPED_TAGS`
Type	`String`
Default	`null`

When set the configured value will be passed as --skip-tags <value> to the Ansible Playbook.

`startAtTask` (optional)


Constant	`ConfigConstants.ANSIBLE_START_AT_TASK`
Type	`String`
Default	`null`

When set the configured value will be passed as --start-at-task <value> to the Ansible Playbook.

`tags` (optional)


Constant	`ConfigConstants.ANSIBLE_TAGS`
Type	`String`
Default	`null`

When set the configured value will be passed as --tags <value> to the Ansible Playbook.

`sudo` (optional)


Constant	`ConfigConstants.ANSIBLE_SUDO`
Type	`Boolean`
Default	`false`

When enabled sudo (become) will be used. Combined with sudoUser setting.

`sudoUser` (optional)


Constant	`ConfigConstants.ANSIBLE_SUDO_USER`
Type	`String`
Default	`null`

Specifies the sudo user to use (become_user)

`getGalaxyRoleInfo(Role role)`

Utility function to the the Ansible Galaxy role info from the API. :bulb: Works only for Ansible Galaxy Roles

💡 This method will return null when no info was found.

Example

This example will return the API role info for the role "tecris.maven"

import io.wcm.devops.jenkins.pipeline.tools.ansible.Role
Role role = new Role("tecris.maven")

Object apiInfo = ansible.getGalaxyRoleInfo(role)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ansible.md

ansible.md

Ansible

Table of contents

`checkoutRequirements(String requirementsYmlPath)`

Example of a `requirements.yml`

Process

`execPlaybook(Map config)`

Features

`--extra-vars` as JSON

Inject Build parameters into `--extra-vars`

Extra parameters

Configuration Options

`colorized` (optional)

`credentialsId` (optional)

`extraParameters` (optional)

`extraVars` (optional)

`forks` (optional)

`injectParams` (optional)

`installation`

`inventory`

`limit` (optional)

`playbook`

`skippedTags` (optional)

`startAtTask` (optional)

`tags` (optional)

`sudo` (optional)

`sudoUser` (optional)

`getGalaxyRoleInfo(Role role)`

Example

Files

ansible.md

Latest commit

History

ansible.md

File metadata and controls

Ansible

Table of contents

checkoutRequirements(String requirementsYmlPath)

Example of a requirements.yml

Process

execPlaybook(Map config)

Features

--extra-vars as JSON

Inject Build parameters into --extra-vars

Extra parameters

Configuration Options

colorized (optional)

credentialsId (optional)

extraParameters (optional)

extraVars (optional)

forks (optional)

injectParams (optional)

installation

inventory

limit (optional)

playbook

skippedTags (optional)

startAtTask (optional)

tags (optional)

sudo (optional)

sudoUser (optional)

getGalaxyRoleInfo(Role role)

Example

`checkoutRequirements(String requirementsYmlPath)`

Example of a `requirements.yml`

`execPlaybook(Map config)`

`--extra-vars` as JSON

Inject Build parameters into `--extra-vars`

`colorized` (optional)

`credentialsId` (optional)

`extraParameters` (optional)

`extraVars` (optional)

`forks` (optional)

`injectParams` (optional)

`installation`

`inventory`

`limit` (optional)

`playbook`

`skippedTags` (optional)

`startAtTask` (optional)

`tags` (optional)

`sudo` (optional)

`sudoUser` (optional)

`getGalaxyRoleInfo(Role role)`