Skip to main content
Plugins / Ansible

Ansible

by Woodpecker Authors
Website
ansibleplaybookautomation

Plugin to execute Ansible playbooks


Overview

Woodpecker CI plugin to execute Ansible playbooks. This plugin is a fork of drone-plugins/drone-ansible with substantial modifications of the source code.

Features

  • Install required dependencies before the start of a playbook
  • Execute Ansible playbooks

Installing required python module dependencies

Many ansible modules require additional python dependencies to work. Because ansible is run inside an alpine-based container, these dependencies must be installed dynamically during playbook execution.

It is important to use delegate_to: localhost as otherwise the pip module will install the dependency on the remote host, which will not have an effect.

- name: Install required pip dependencies
  delegate_to: localhost
  ansible.builtin.pip:
    name: <name>
    state: present
    extra_args: --break-system-packages

Without --break-system-packages alpine will complain aiming for plain pip3 packages being installed system-wide. Alternatively, one can also use the apk/packages module if the required pip module is available as an python3-<name> package

Effient handling of Ansible dependencies

By default, each step using the plugin will install the required dependencies using ansible-galaxy install -r requirements.yml. Often, one wants to run multiple playbooks in different steps, ideally in parallel. In this case, a step which installs the requirements for all subsequent steps is useful.

steps:
  "Install galaxy requirements":
    image: pad92/ansible-alpine
    commands:
      - ansible-galaxy install -r requirements.yml

In addition, Ansible dependencies can be cached. This avoids having to re-download them for each build, saving bandwith and time. If root access to the Woodpecker instance is given, one can mount a volume to the container and store the dependencies there.

steps:
  "Install galaxy requirements":
    image: pad92/ansible-alpine
    volumes:
      - /root/woodpecker-cache/collections:/tmp/collections
    commands:
      - cp -r /tmp/collections $${CI_WORKSPACE}/
      - ansible-galaxy install -r requirements.yml
      - cp -r $${CI_WORKSPACE}/collections /tmp/

In the above example, the first command copies the cached dependencies to the workspace directory. After the installation, the dependencies are copied back to the cache directory. Note that this requires the creation of the cache directory on the host upfront (i.e. /root/woodpecker-cache). The location of the cache directory can be adjusted to the user's needs.

Mounting the cache directory directly to $${CI_WORKSPACE}/collections is not feasible due to the following reasons:

  • The volume mount conflicts with the volume mount providing the workspace directory to each container
  • The mount would need to be added to each step as otherwise the dependencies are missing in these

Settings

Settings Name Default Description
become-method none privilege escalation method to use
become-user none run operations as this user
become false run operations with become
check false run in "check mode"/dry-run, do not apply changes
connection none connection type to use
diff false show the differences (may print secrets!)
extra-vars none set additional variables via key=value list or map or load them from yaml/json files via @ prefix
flush-cache false clear the fact cache for every host in inventory
force-handlers none run handlers even if a task fails
forks 5 number of parallel processes to use
galaxy-force true force overwriting an existing role or collection
galaxy none path to galaxy requirements file
inventory none specify inventory host path
limit none limit selected hosts to an additional pattern
list-hosts false outputs a list of matching hosts
list-tags false list all available tags
list-tasks false list all tasks that would be executed
module-path none prepend paths to module library
playbook none list of playbooks to apply
private-key none SSH private key to connect to host
requirements none path to python requirements file
scp-extra-args none specify extra arguments to pass to scp only
sftp-extra-args none specify extra arguments to pass to sftp only
skip-tags none skip tasks and playbooks with a matching tag
ssh-common-args none specify common arguments to pass to sftp/scp/ssh
ssh-extra-args none specify extra arguments to pass to ssh only
start-at-task none start the playbook at the task matching this name
syntax-check false perform a syntax check on the playbook
tags none only run plays and tasks tagged with these values
timeout none override the connection timeout in seconds
user none connect as this user
vault-id none the vault identity to used
vault-password none vault password
verbose 0 level of verbosity, 0 up to 4

Examples

steps:
  '[CI Agent] ansible (apply)':
    image: woodpeckerci/plugin-ansible
    settings:
      playbook: playbooks/ci/agent.yml
      diff: true
      inventory: environments/prod/inventory.ini
      syntax_check: false
      limit: ci_agent_prod
      become: true
      user: root
      private_key:
        from_secret: id_ed25519_ci
      extra_vars:
        woodpecker_agent_secret:
          from_secret: woodpecker_agent_secret
        woodpecker_agent_secret_baarkerlounger:
          from_secret: woodpecker_agent_secret_baarkerlounger