Ansible Help

Document Control

TODO:

  • Overall structure.
  • Initial draft complete
  • Testing
  • Ready

What version am I running?

which ansible

Find out where ansible is in your PATH and how it was installed.

which ansible
whence -p ansible
whereis ansible
type ansible
whatis ansible
rpm -qa | grep ansible
~/.local/bin/ansible
/home/cmihai/.local/bin/ansible
ansible: /usr/bin/ansible /etc/ansible /usr/share/ansible /home/cmihai/.local/bin/ansible /usr/share/man/man1/ansible.1.gz
ansible is /home/cmihai/.local/bin/ansible
ansible (1) - Define and run a single task 'playbook' against a set of hosts
ansible-2.8.5-2.el8.noarch

We can see ansible was installed in ~/.local/bin (likely using pip), but also, that it was installed using rpm.

ansible –version

To find out what version you are running, where the config file resides and the configured module search path:

ansible --version
/usr/bin/ansible --verion
ansible 2.9.2
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/cmihai/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /home/cmihai/.local/lib/python3.6/site-packages/ansible
  executable location = /home/cmihai/.local/bin/ansible
  python version = 3.6.8 (default, Oct  7 2019, 17:58:22) [GCC 8.2.1 20180905 (Red Hat 8.2.1-3)]
ansible 2.8.5
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/cmihai/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.6/site-packages/ansible
  executable location = /usr/bin/ansible
  python version = 3.6.8 (default, Oct  7 2019, 17:58:22) [GCC 8.2.1 20180905 (Red Hat 8.2.1-3)]

We're going to use the ansible commands from $PATH, in this case, ~/.local/bin.

Getting Help

The online help is available at https://docs.ansible.com/

Offline, you can use the ansible-doc command to get help, corresponding to your installed ansible version.

Ansible ships with over 3600 modules
ansible-doc -l | wc
3681
Look for a specific module
ansible-doc -l | grep archive
archive   Creates a compressed archive of one or more files or trees
unarchive Unpacks an archive after (optionally) copying it from the local machine
win_unzip Unzips compressed files and archives on the Windows node
Get a summary with -s
ansible-doc -s apt_repo
- name: Manage APT repositories via apt-repo
  apt_repo:
      remove_others:         # Remove other then added repositories Used if `state=present'
      repo:                  # (required) Name of the repository to add or remove.
      state:                 # Indicates the desired repository state.
      update:                # Update the package database after changing repositories.
Usage and examples
ansible-doc package
> YUM    (/home/cmihai/.local/lib/python3.6/site-packages/ansible/modules/packaging/os/yum.py)

        Installs, upgrade, downgrades, removes, and lists packages and groups with the `yum' package manager. This module only works on Python 2. If you
        require Python 3 support see the [dnf] module.

  * This module is maintained by The Ansible Core Team
  * note: This module has a corresponding action plugin.
- name: install the latest version of Apache
  yum:
    name: httpd
    state: latest

- name: ensure a list of packages installed
  yum:
    name: ""
  vars:
    packages:
    - httpd
    - httpd-tools

- name: remove the Apache package
  yum:
    name: httpd
    state: absent

- name: install the latest version of Apache from the testing repo
  yum:
    name: httpd
    enablerepo: testing
    state: present

- name: install one specific version of Apache
  yum:
    name: httpd-2.2.29-1.4.amzn1
    state: present

- name: upgrade all packages
  yum:
    name: '*'
    state: latest

- name: upgrade all packages, excluding kernel & foo related packages
  yum:
    name: '*'
    state: latest
    exclude: kernel*,foo*

- name: install the nginx rpm from a remote repo
  yum:
    name: http://nginx.org/packages/centos/6/noarch/RPMS/nginx-release-centos-6-0.el6.ngx.noarch.rpm
    state: present

- name: install nginx rpm from a local file
  yum:
    name: /usr/local/src/nginx-release-centos-6-0.el6.ngx.noarch.rpm
    state: present

- name: install the 'Development tools' package group
  yum:
    name: "@Development tools"
    state: present

- name: install the 'Gnome desktop' environment group
  yum:
    name: "@^gnome-desktop-environment"
    state: present

- name: List ansible packages and register result to print with debug later.
  yum:
    list: ansible
  register: result

- name: Install package with multiple repos enabled
  yum:
    name: sos
    enablerepo: "epel,ol7_latest"

- name: Install package with multiple repos disabled
  yum:
    name: sos
    disablerepo: "epel,ol7_latest"

- name: Install a list of packages
  yum:
    name:
      - nginx
      - postgresql
      - postgresql-server
    state: present

- name: Download the nginx package but do not install it
  yum:
    name:
      - nginx
    state: latest
    download_only: true

Observe the source code in the corresponding yum.py module and "maintained by the Core Team

Scroll down to the EXAMPLES section for detailed usage examples.

Callback Plugins and other types

list callback plugins

ansible-doc --help shows a number of types: become,cache,callback,cliconf,connection,httpapi,inventory,lookup,shell,module,strategy,vars.

ansible-doc --type=callback -l
ansible-doc --type=callback timer
~/.local/bin/ansible
ansible-doc --type=callback timer
> TIMER    (/home/cmihai/.local/lib/python3.6/site-packages/ansible/plugins/callback/timer.py)

        This callback just adds total play duration to the play stats.

  * This module is maintained by The Ansible Community
REQUIREMENTS:  whitelist in configuration

CALLBACK_TYPE: aggregate
        METADATA:
          status:
          - preview
          supported_by: community

Setting a callback plugin

Callback plugins are configured using a whitelist in the configuration. Example ansible.cfg

[defaults]
callback_whitelist = timer

Inventory Management

ansible-inventory

What hosts is ansible managing?

[mymachine]
localhost
ansible-inventory -i inventory.ini --graph
ansible-inventory -i inventory.ini --list --yaml
@all:
  |--@mymachine:
  |  |--localhost
  |--@ungrouped:
all:
  children:
    mymachine:
      hosts:
        localhost: {}
    ungrouped: {}

Example Configuration

When installing Ansible from a package, a sample configuration is placed in /etc/ansible/.

Normally, this is overriden by ansible.cfg placed in the playbook directory. This is the recommended approach, as local directory files can be checked under version control (ex: git).

This file can also be found online, in the github ansible - examples directory.

Example Roles and Playbooks on Galaxy

https://galaxy.ansible.com/ has more than 23,000 roles contributed by the ansible community.

To find high quality roles, check the role's:

  • build passing TravisCI badge (usually means the role has been tested with molecule)
  • Quality Score - showing adherence to ansible-lint, yamllint and best practices
  • Community Score - showing scores for Quality of Docs, Ease of Use, Does what it promises, Works without change and Read for Production as evaluated by the ansible community and the number of user surveys.
  • Number of downloads
  • The Issue Tracker (usually links to Github issues)
  • The Readme: What license is the role under? Does it show any TODOs or bugs?
  • The Repo: how recently was this updated? Is it being maintained?
  • The OS Platforms and Versions: what OS and Versions does this role claim to support? Can you find the same systems in TravisCI (build passing)?

As with all contributed content, a code reading is highly advised before use.

Ansible Galaxy

To use roles in ansible galaxy, see the ansible-galaxy command. Ex: ansible-galaxy install crivetimihai.apache. To get info on a role: ansible-galaxy info crivetimihai.users.

Ansible Colors

  • Green: OK task status. No changes made.
  • Yellow: Changed task status.
  • White: General information.
  • Blue: Skipped.
  • Purple: Deprecation / warning.
  • Red: Failed.

Last update: 2020-01-25