This plugin allows to execute Ansible tasks as a job build step.
Ansible needs to be on the PATH for the build job in order to be used. This can be done through either Jenkins Global Tool Configuration or including Ansible on the OS User PATH variable.
Configuring Ansible through the Global Tool Configuration in Jenkins (Jenkins → Manage Jenkins → Global Tool Configuration) allows for multiple Ansible installations to be present and used by different Jenkins jobs.
-
Click "Add Ansible"
-
Configure the name and path
Field name Description Name Symbolic name used to identify a specific Ansible installation when multiple installations are configured Path to ansible executables directory Directory containing the ansible, ansible-playbook, and ansible-vault binaries -
Repeat for any additional desired installations
Ansible can also be added to the PATH user used by the Jenkins executor instead of configured through Global Tool Configuration. This is done through normal OS tools outside of Jenkins and is not covered by this guide.
Adhoc commands allow for simple operations to be done without writing a full playbook. This allows for a convenient way of doing quick tasks with Ansible.
Due to JENKINS-43782 and JENKINS-49056, adhoc commands cannot be run with a pipeline job.
See also jenkins.io documentation.
| Freestyle Name | Description |
|---|---|
| Ansible installation | Ansible installation to use for the playbook invocation |
| Host pattern | The host pattern to manage. See Ansible Patterns for details. |
| Module | CLI arg: -m |
| Module arguments or command to execute | CLI arg: -a |
| Inventory file or host list | CLI arg: -i: See the Inventory section for additional details. |
| Inventory inline content | CLI arg: -i: See the Inventory section for additional details. |
| Credentials | The Jenkins credential to use for the SSH connection. See the Authentication section for additional details. |
| Vault Credentials | CLI arg: --vault-password-file: The Jenkins credential to use as the vault credential. See the Vault Credentials section for additional details. |
| sudo | CLI arg: -s |
| sudo user | CLI arg: -U |
| Number of parallel processes | CLI arg: -f |
| Check host SSH key | Toggle checking of the host key. Sets the environment variable ANSIBLE_HOST_KEY_CHECKING, similar to the recommendations for running with Vagrant. |
| Unbuffered stdout | Toggle buffering of standard out. Sets the environment variable PYTHONUNBUFFERED, similar to the recommendations for running with Vagrant. |
| Colorized stdout | Toggle color codes in console text. See Colorized Output section for example usage. Sets the environment variable ANSIBLE_FORCE_COLOR, similar to the recommendations for running with Vagrant. |
| Extra Variables | CLI arg: -e |
| Additional parameters | String passed to the Ansible Command Line invocation as-is. |
Ansible playbook operations can be run with the plugin. The plugin provides several conveniences such as easily using credentials from the Jenkins credential store, unbuffered color output in the log, etc.
Jenkinsfile
ansiblePlaybook credentialsId: 'private_key', inventory: 'inventories/a/hosts', playbook: 'my_playbook.yml'Jenkinsfile
ansiblePlaybook(credentialsId: 'private_key', inventory: 'inventories/a/hosts', playbook: 'my_playbook.yml')Additional scripted and declarative pipeline examples can be found on the plugin's GitHub readme.
Refer to jenkins.io for documentation extracted from the online help of the plugin.
| Freestyle Name | Pipeline Name | Description |
|---|---|---|
| Ansible installation | installation | Ansible installation to use for the playbook invocation |
| Playbook path | playbook | Mandatory. The name of the playbook to run |
| Inventory file or host list | inventory | CLI arg: -i: See the inventory section for details. |
| Inventory inline content | inventoryContent | CLI arg: -i: See the inventory section for details. |
| Credentials | credentialsId | The Jenkins credential to use for the SSH connection. See the Authentication section for additional details |
| Vault Credentials | vaultCredentialsId | The Jenkins credential to use as the vault credential. See the Vault Credentials section for more details |
| sudo | sudo | CLI arg: -s |
| sudo user | sudoUser | CLI arg: -U |
| Host subset | limit | CLI arg: -l |
| Tags to run | tags | CLI arg: -t |
| Tags to skip | skippedTags | CLI arg: --skip-tags |
| Task to start at | startAtTask | CLI arg: --start-at-task |
| Number of parallel processes | forks | CLI arg: -f |
| Check host SSH key | hostKeyChecking | Toggle checking of the host key. Sets the environment variable ANSIBLE_HOST_KEY_CHECKING, similar to the recommendations for running with Vagrant. |
| Colorized stdout | colorized | Toggle color codes in console text. See Colorized Output section for example usage. Sets the environment variable ANSIBLE_FORCE_COLOR, similar to the recommendations for running with Vagrant. |
| Additional parameters | extras | String passed to the Ansible Command Line invocation as-is |
| Extra Variables | extraVars | CLI arg: -e |
Refer to the ansible-playbook manual page for details on how each command line argument is interpreted.
SSH keys are the recommended authentication method for SSH connections. The plugin supports the credential type "SSH Username with private key" configured in the Jenkins credential store through the SSH crendentials plugin.
Even if using SSH keys is recommended authentication method, password authentication may sometimes be required. The plugin has supported password based authentication since 0.3.0. When using password based authentication, the sshpass binary is expected to be on the PATH. The plugin supports the credential type "Username with password" configured in the Jenkins credential store through the SSH crendentials plugin.
Vault credentials can be setup in the Jenkins credential store as either a "Secret text" or a "Secret file".
The AnsiColor plugin is needed for colorized console output. Once installed, colorized output can be enabled with the argument "colorized: true".
Jenkinsfile
ansiColor('xterm') {
ansiblePlaybook(
playbook: 'path/to/playbook.yml',
inventory: 'path/to/inventory.ini',
credentialsId: 'sample-ssh-key',
colorized: true)
}
Extra parameters is a string passed to the Ansible Command Line invocation as-is and can be useful for arguments occasionally added to an invocation at runtime, such as tags and host limits.
A string path to the inventory file to use with the playbook invocation.
The provided content is used as the content of the inventory file for the playbook invocation.
Jenkins environment variables can be accessed from within an Ansible playbook. The Jenkins variables are injected as environment variables making them available through the Ansible lookup plugin.
The following Ansible playbook accesses the Jenkins BUILD_TAG variable:
playbook.yml
---
- hosts: example
tasks:
- debug: msg="{{ lookup('env','BUILD_TAG') }}"Most Ansible Vault operations can be performed with the plugin. Interactive operations such as create, edit, and view are not supported through the plugin. One use case for this enabling developers to encrypt secret values while keeping the vault password a secret.
Encrypts a File
ansibleVault action: 'encrypt', input: 'vars/secrets.yml', vaultCredentialsId: 'ansible_vault_credentials'Encrypts a String
ansibleVault action: 'encrypt_string', content: 'secret_content', vaultCredentialsId: 'ansible_vault_credentials'Jenkinsfile
ansibleVault(action: 'encrypt', input: 'vars/secrets.yml', vaultCredentialsId: 'ansible_vault_credentials')Jenkinsfile
ansibleVault(action: 'encrypt_string', content: 'secret_content', vaultCredentialsId: 'ansible_vault_password')See also jenkins.io Pipeline step documentation.
| Freestyle Name | Pipeline Name | Description |
|---|---|---|
| Ansible installation | installation | Ansible installation to use for the playbook invocation |
| Action | action | Mandatory. The name of the action to use. Interactive operations such as create, edit, and view are not supported. |
| Vault Credentials | vaultCredentialsId | CLI arg: --vault-password-file. The Jenkins credential to use as the vault credential. See the Vault Credentials section for more details |
| New Vault Credentials | newVaultCredentialsId | CLI arg: --new-vault-password-file. The Jenkins credential to use as the vault credential. See the Vault Credentials section for more details |
| Content | content | The content to encrypt with the 'encrypt_string' action. |
| Input | input | The file to encrypt with the encrypt actions. |
| Output | output | CLI arg: --output |
Vault credentials can be setup in the Jenkins credential store as either a "Secret text" or a "Secret file".
- Fix security issue: Do not disable host key verification by default. This may break existing configurations as host key verification will be enabled everywhere by default.
- Add support for Ansible Vault JENKINS-48499
- Add hostKeyChecking option to pipeline JENKINS-42445
- Fix blocker bug when launched from a pipeline JENKINS-40780
- Use latest parent project definition in order to deploy plugin (thanks to alecharp for the help and the PR)
WARN: 0.6.x version will be the last one to support Jenkins 1.xxx and Ansible 1.x - The 0.7.x and next releases will require Jenkins 2.32.1 (or higher) and Ansible 2.2 (or higher)
- Add a "do not specify" option for inventory JENKINS-34627
- Support inventoryContent in pipeline (thanks to leewin12 for the PR)
- Add support of extra variables in jobdsl (thanks to pawbur for the PR)
- Support empty forks (number of parallel processes) parameter JENKINS-39438
- Escape '%' character in private key path (thanks to ewollesen for the PR)
- Omit ansible option when expanded environment variable is empty (thanks to vjestin for the PR)
- Add the --forks parameter configurable in pipeline step (thanks to anguswilliams for the PR)
- Fix usage of environment variable in ansiblePlaybook pipeline step (thanks to thomasKalmar and barthorre for the PR) JENKINS-38289
- Add support for ansible extra variables JENKINS-29863
- Improve Pipeline plugin integration JENKINS-32911
- Add the possibility to use the default inventory file (thanks to Johann Schmitz for the PR)
- Add colorized output in pipeline jobs (thanks to Kirill Merkushev for the PR)
- Make Jenkins build variables available as environment variables for ansible (thanks to Kevin Mooney for the PR) JENKINS-29284
- Support for password protected SSH keys JENKINS-30656
- Initial support for the workflow plugin JENKINS-30398
- Add support for Job DSL plugin (thanks to Kirill Merkushev for the PR) JENKINS-31790
- Fix execution on slave nodes JENKINS-29294
- Add support for password based SSH authentication (with sshpass)
- Environment variables can be used in Module and Module arguments text field in Ad-hoc command builder
- Environment variables can be used in inline inventory text box JENKINS-28547
- Fix NullPointerException when no credentials are selected
- Fix --skippedTags parameter configuration which was ignored
- Fix NullPointerException and print an error message in the build console when the inventory is not set in the job configuration
- Initial version
This plugin gives the possibility to run Ansible ad-hoc command or playbooks as a build step.
It is possible to access build and environment variables in ansible playbooks. These variables are injected as environment variables within the ansible process. For example, use this code in an ansible playbook to access Jenkins BUILD_TAG variable.
---
- hosts: example
tasks:
- debug: msg="{{ lookup('env','BUILD_TAG') }}"steps {
ansiblePlaybook(String playbook) {
inventoryPath(String path)
inventoryContent(String content, boolean dynamic = false)
ansibleName(String name)
limit(String limit)
tags(String tags)
skippedTags(String tags)
startAtTask(String task)
credentialsId(String id)
become(boolean become = true)
becomeUser(String user = 'root')
sudo(boolean sudo = true)
sudoUser(String user = 'root')
forks(int forks = 5)
unbufferedOutput(boolean unbufferedOutput = true)
colorizedOutput(boolean colorizedOutput = false)
hostKeyChecking(boolean hostKeyChecking = false)
additionalParameters(String params)
extraVars {
extraVar(String key, String value, boolean hidden)
}
}
ansibleAdHoc(String module, String command) {
ansibleName(String name)
inventoryPath(String path)
inventoryContent(String content, boolean dynamic = false)
credentialsId(String id)
hostPattern(String pattern)
become(boolean become = true)
becomeUser(String user = 'root')
sudo(boolean sudo = true)
sudoUser(String user = 'root')
forks(int forks = 5)
unbufferedOutput(boolean unbufferedOutput = true)
colorizedOutput(boolean colorizedOutput = false)
hostKeyChecking(boolean hostKeyChecking = false)
additionalParameters(String params)
extraVars {
extraVar(String key, String value, boolean hidden)
}
}
}steps {
ansiblePlaybook('path/playbook.yml') {
inventoryPath('hosts.ini')
ansibleName('1.9.4')
tags('one,two')
credentialsId('credsid')
become(true)
becomeUser("user")
extraVars {
extraVar("key1", "value1", false)
extraVar("key2", "value2", true)
}
}
}Ansible playbooks can be executed from workflow scripts. Only the playbook parameter is mandatory.
node {
ansiblePlaybook(
playbook: 'path/to/playbook.yml',
inventory: 'path/to/inventory.ini',
credentialsId: 'sample-ssh-key',
extras: '-e parameter="some value"')
}Extra variables can be passed to ansible by using a map in the pipeline script. Use the hidden parameter
to keep the variable secret in the build log.
node {
ansiblePlaybook(
inventory: 'local_inventory/hosts.cfg',
playbook: 'cloud_playbooks/create-aws.yml',
extraVars: [
login: 'mylogin',
secret_key: [value: 'g4dfKWENpeF6pY05', hidden: true]
])
}You need to install the AnsiColor plugin to output a colorized Ansible log.
node {
wrap([$class: 'AnsiColorBuildWrapper', colorMapName: "xterm"]) {
ansiblePlaybook(
playbook: 'path/to/playbook.yml',
inventory: 'path/to/inventory.ini',
credentialsId: 'sample-ssh-key',
colorized: true)
}
}