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 devopstoolbox.apache
. To get info on a role: ansible-galaxy info devopstoolbox.users
.
Ansible Colors
- Green: OK task status. No changes made.
- Yellow: Changed task status.
- White: General information.
- Blue: Skipped.
- Purple: Deprecation / warning.
- Red: Failed.