Several ad hoc commands were shown in the previous post but no real detail was given as to what they can fully offer. These ad hoc commands are often cited as being a good starter point for learning what’s possible with Ansible; without having to dive straight into writing a playbook.
Most of them incorporate the use of a module into their structure, so this post introduces modules too. Both from the point of view of an ad hoc command, and within the context of a task. Towards the end, the “special” Ansible module types are shown.
1 – Ad Hoc Commands
Sometimes you may not need nor want to write a fully-fledged playbook for simple operations. Either way, the concepts here for these commands port directly over to the playbook language for when you do begin writing them later on. These due to their impromptu nature and use.
In their simplest form, these commands are shell commands performed in parallel to each host by Ansible.
coreservers is the group name that contains several hosts and the ad hoc command
-a we are running on them is
10 Ansible forks.
- $ ansible coreservers -a “/sbin/reboot” -f 10 -b -K
-f 10 in the above specifies the usage of 10 simultaneous processes to use (10 hosts at a time). You can also set this as an assumed default in the configuration file to avoid setting it here. The default is set to 5, which is lacking and conservative, so feel free to increase this value to a more optimal number.
Ansible defaults to running from your current user account (or from any hosts variables). To change this pass in the
-u option. Where
scarlz is the username you want to run the command as.
- $ ansible coreservers -a “/usr/bin/foo” -u scarlz
When not calling raw programs on the node through Ansible, modules are the main choice for carrying out operations.
In general, the
-m option denotes a named module. Here is an example of the
shell module that is used to issue precise commands on the Ansible node.
- $ ansible coreservers -u scarlz -m shell -a ‘echo $TERM’
There is a whole back-catalog of these inbuilt modules for you to make use of.
2 – Modules
Modules contain the actions or functionality we want to implement and run. Some commonly used modules are apt/yum, copy, ec2, file, service, template, and user. As shown in the previous section, modules can be used in ad-hoc commands as well as “tasks”.
This command transfers a “hosts” file directly to all servers in the “coreservers” group, using SCP and the
- $ ansible coreservers -m copy -a “src=/etc/hosts dest=/tmp/hosts” -b -K
file module provides the ability to change system ownership and permissions on remote files.
- $ ansible coreservers -m file -a “dest=/var/www/index.html mode=755 owner=scarlz group=www” -b -K
To create directories with
file, like when using the
mkdir -p command in Linux, add the “directory”
- $ ansible coreservers -m file -a “dest=/var/www/new-vhost-dir mode=755 owner=scarlz group=www state=directory” -b -K
Delete directories recursively, and delete files through
file with the
- $ ansible coreservers -m file -a “dest=/path/to/delete state=absent”
This module is referred to when you need to interact with the OS system services. Inclusive of BSD init, OpenRC, SysV, Solaris SMF, systemd, and upstart.
As an example of how this could work, this starts Nginx via systemd:
- $ ansible coreservers -m service -a “name=nginx.service state=started” -b -K
Changing the state option changes the result – this is to restart:
- $ ansible coreservers -m service -a “name=nginx.service state=restarted” -b -K
The value of “state” must be one of either: running, started, stopped, restarted, or reloaded.
Users and Groups
A module named the “user” module serves as an interface to creating, removing, and manipulating system user accounts.
Altering a user’s password only requires the username, in this next example this is
scarlz, then the new password for the user which is substituted into the
- $ ansible coreservers -m user -a “name=scarlz password=<user-password>”
Removing the user account completely once again needs the username (
scarlz in my case) as well as the value
absent for the
- $ ansible coreservers -m user -a “name=scarlz state=absent” -b -K
Practical Ad Hoc Module Example
The first command updates the Apt package index – similar to running the usual
apt-get update command.
- $ ansible coreservers -b -K -m apt -a update_cache=yes
Continuing on from before, upgrading the system packages (like with
apt-get upgrade) uses:
- $ ansible coreservers -b -K -m apt -a upgrade=yes
dist-upgrade uses the
full switch instead of just “yes”.
- $ ansible coreservers -b -K -m apt -a upgrade=full
Here’s a page from the official Ansible documentation that acts as a catalogue for all the registered inbuilt modules available. There are many many modules, to cater for all specific needs.
3 – Modules in Tasks
Here are some examples of using the modules in a task (like you’d find in an Ansible playbook).
The file module (most shown before) creates a new directory to be used for caching purposes.
- – name: add cache directory
- file: path=/opt/cache state=directory
In more detail this time, the
apt module handles packages for Ubuntu/Debian OS.
The state option here designates that the install of Nginx should be implemented via apt-get, but the state value could also be replaced with
latest (to update the package) or
absent (to remove the package) instead.
- – name: install nginx
- yum name=nginx state=present
This one’s pretty straight forward and is the “task” equivalent of the ad hoc command from earlier.
- – name: start nginx
- service: name=nginx enabled=yes state=started
One thing to notice here is with the
name: field. Tasks can be defined as anything you want here but should be descriptive. Tasks are simple and declarative, they aim to pass the correct arguments to the module calls, to achieve what is needed.
4 – Special Modules
There are several modules that fall into their own category, that exist to provide special core use cases. The code examples here are in the form of a task you’d find within a playbook.
commandmodule – Used for executing simple commands on remote nodes. (first example shown in step one).
- – name: Run the command if the specified file does not exist.
- command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
shellmodule – Similar to the command module but allows the use of redirection, variables, and further operators. The
shellmodule was also used in the first step.
- – name: Execute the command in remote shell; stdout goes to the specified file on the remote.
- shell: somescript.sh >> somelog.txt
script– Let’s you run a local script on a remote node – after transferring it.
- – script: /some/local/script.sh –some-arguments 1234
raw– Executes a low-down and dirty SSH command. Mainly used for installing Python versions onto hosts that do not already have it.
- – name: Bootstrap a legacy python 2.4 host
- raw: yum -y install python-simplejson
The examples uses Yum package manager, so is in the context of an enterprise Linux OS.
With a basic understanding of how modules work within both ad hoc commands and tasks. It’s easy to now see how the bulk of an Ansible playbooks actions are laid out.