Jenkins Declarative Pipelines can execute Ansible Playbooks, but they often fail due to a surprisingly simple misconfiguration of the Ansible installation within the Jenkins environment.
Here’s how to get it working:
First, ensure you have the Ansible plugin installed in Jenkins. You can find it under Manage Jenkins -> Manage Plugins -> Available and search for "Ansible". Install and restart Jenkins if prompted.
Next, configure Jenkins to know where your Ansible executable is. Go to Manage Jenkins -> Global Tool Configuration. Scroll down to the "Ansible" section. Click "Add Ansible". Give it a name, like ansible-2.10.7. In the Installation directory field, you need to provide the path to your Ansible installation on the Jenkins controller or agent where the build will run. This is often something like /usr/bin or /usr/local/bin if Ansible is installed system-wide, or a specific path if you’re using a virtual environment.
Once that’s done, you can use the ansible tool within your Jenkinsfile. Here’s a basic example of how to call an Ansible playbook:
pipeline {
agent any
stages {
stage('Run Ansible Playbook') {
steps {
ansiblePlaybook(
playbook: 'path/to/your/playbook.yml',
credentialsId: 'your-ssh-credentials-id', // If your playbook needs SSH access
inventory: 'path/to/your/inventory/file'
)
}
}
}
}
The ansiblePlaybook step is provided by the Ansible plugin. You specify the path to your playbook, and optionally credentials and inventory. The credentialsId should correspond to a Jenkins credential of type "SSH Username with private key" that your Ansible playbook will use to connect to target hosts.
When you define your SSH credentials in Jenkins, make sure the "ID" field matches exactly what you put in credentialsId. This is crucial for the plugin to find and use the correct key.
If your Ansible playbook requires specific Python modules or a particular version of Ansible that isn’t globally available on your Jenkins agent, you’ll need to ensure that environment is set up before the ansiblePlaybook step runs. This often involves using a script block to activate a virtual environment:
pipeline {
agent any
stages {
stage('Setup Ansible Environment') {
steps {
script {
// Assuming you have a virtual environment at /path/to/your/venv
sh 'source /path/to/your/venv/bin/activate'
sh 'ansible-playbook path/to/your/playbook.yml'
}
}
}
}
}
In this script block, sh commands are executed directly on the agent. Activating a virtual environment ensures that the ansible-playbook command uses the Ansible version and modules installed within that environment. The Jenkins Ansible plugin will then pick up this activated environment if it’s run within the same script block or if the ansiblePlaybook step is called after the environment has been activated.
The most common pitfall is not correctly pointing Jenkins to the Ansible executable or not having Ansible installed on the Jenkins agent at all. The ansiblePlaybook step relies on the ansible command being available in the PATH of the Jenkins agent’s execution environment. If it’s not, you’ll get errors like "Command not found."
Another frequent issue is related to Ansible’s configuration file, ansible.cfg. If your playbook relies on specific settings in ansible.cfg (like remote_user or private_key_file), ensure that this file is discoverable by Ansible when run from Jenkins. You might need to specify its location using the ANSIBLE_CONFIG environment variable, perhaps within a script block:
pipeline {
agent any
stages {
stage('Run Ansible with Custom Config') {
steps {
script {
sh 'export ANSIBLE_CONFIG=/path/to/your/ansible.cfg'
ansiblePlaybook(
playbook: 'path/to/your/playbook.yml',
inventory: 'path/to/your/inventory/file'
)
}
}
}
}
}
This explicitly tells Ansible where to find its configuration, overriding defaults or system-wide settings.
The ansiblePlaybook step has a directory parameter that allows you to specify the working directory from which the playbook should be executed. This is vital if your playbook uses relative paths for roles, inventory, or other files. If you don’t set this, Ansible will try to run from the Jenkins workspace root, which might not be where your playbook expects to find its dependencies.
If you’re using dynamic inventories, ensure that the inventory script or plugin is executable on the Jenkins agent and that any necessary Python dependencies for the dynamic inventory are also installed. The ansiblePlaybook step will execute the inventory script, so it needs the same environment considerations as Ansible itself.
Finally, if you encounter issues with SSH connection timeouts or authentication, double-check that the SSH private key configured in Jenkins is correctly loaded and that the corresponding public key is in the authorized_keys file on your target Ansible hosts. Also, ensure that the ansible_user in your inventory matches the user specified in your Jenkins SSH credentials.
The next error you’ll likely encounter after fixing these issues is a permission denied error when Ansible tries to write logs or temporary files on the target hosts, usually requiring adjustment of become settings or file permissions on the remote systems.