how to create an ansible task

• Privacy Policy
• Terms of Service
• Knowledgebase

How to Create and Use Ansible Playbooks

One of the core components of Ansible is a playbook file. Ansible uses playbook files to define complex tasks that are executed against managed nodes with limited user involvement.

In this guide, you will learn how to create and use Ansible playbook files to execute tasks on managed nodes.

# What is Ansible Playbook?

A playbook is essentially a YAML file that comprises one or multiple plays. A play is a set of ordered tasks to be executed against managed hosts that are specified in the /etc/ansible/hosts file. Each play in a playbook represents a unique task with environment-specific parameters for the target hosts.

Playbooks are quite flexible and can be reused indefinitely with multiple servers to perform the same tasks. Ansible playbooks are often used for server configuration, network device management and application deployment tasks.

# Prerequisites

To follow this guide, you should have:

• A control node with Ubuntu 20.04 operating system and Ansible installed. If you haven’t installed Ansible before, follow our guide on How to Install and Configure Ansible on Ubuntu 20.04 .
• A single managed node configured in the control node’s hosts file that will be used to run the playbook tasks.

# Create Ansible Playbook

Let’s start by making and running our first Ansible playbook. On the control node create a simple YAML file in the /etc/ansible/ directory as follows:

Now populate the playbook file with the following code:

The --- marks the start of the YAML file.

The first instance of the name directive specifies the name of the play. The second instance specifies the name of the task.

The hosts directive specifies the target hosts on which the playbook will be executed. In this example, the playbook will run on all the hosts specified in the inventory file . To target a specific host, provide the host’s IP address or domain name.

The tasks directive is a list of tasks to be executed on the target host. In this playbook, we have one task which prints a statement to stdout.

The debug keyword is a built-in module that comes with Ansible and prints statements during Playbook runtime. In addition, it comes in handy when debugging statements and variables without halting a playbook. The debug module comes with some options such as msg and var . The msg option specifies the string to the printed to stdout.

# Execute Ansible Playbook

To run the playbook, use the ansible-playbook command as shown below:

In our example, you should run the following command:

During playbook execution, you should see the following output:

Notice that two tasks were carried out, even though we defined only one in the Playbook file.

The first task gathers facts about the managed node. Ansible facts refer to host-specific system data that is presented in JSON format such as BIOS information, system date and time, OS type and version and IP address. It also includes hardware data such as the block devices, CPU, RAM, and swap space to name a few.

The second task prints a simple message to stdout as specified in the playbook file. The ok=2 indicates that two tasks were successfully executed.

If you are curious to get a list of all the Ansible facts, execute the following command:

# Ansible Playbook Modules

Ansible modules are standalone reusable Python scripts that are referenced in Playbooks to help execute specific tasks on managed nodes. Ansible modules can automate a wide selection of tasks on managed nodes including package management, service management, file management and so much more.

In this section, we will demonstrate how you can accomplish various system administration tasks by incorporating modules in Playbooks.

# Package Management Modules

Managing software packages is an essential system administration task. It specifically deals with installing and removing software packages in Linux servers. Ansible provides built-in package management modules for major Linux distributions as shown.

The following playbook file installs the Apache webserver on the remote target defined under the webserver sub-group in the inventory file. The apt module provides two options: the name option which specifies the name of the package ( apache2 ) and the state option which instructs Ansible to install the latest version of Apache.

Upon running the playbook file, you should get similar output to what we have:

On RHEL 8 and CentOS 8, the same task can be accomplished using the dnf module. Here, the Apache package for RedHat derivatives is defined by httpd .

# Service Module

You can also use modules to start, stop and restart running services on managed nodes. For example, to restart the Apache webserver, we will use the service module in the playbook shown.

Here is the output of the Playbook execution:

Here’s a playbook showing how you can stop the webserver. Note the change of the state parameter from restarted to stop .

From the output of the playbook execution, you can see that the task was successful:

To start the webserver, set the state parameter to started .

Once again, here is the output of the playbook execution:

# Copy Module

Another useful module is the copy module. As the name suggests, the module is used for copying files from one location to another. You can copy files from the Ansible controller to the remote node or copy files from one location to another within the remote node.

In the Playbook file below, we are copying the sales_report.txt file from the Ansible control node to the remote server in the /tmp/reports/ directory. In addition, we have assigned the owner and group ownership to the cherry user using the owner and group options. The mode option assigns the octal file permissions 0644 to the file.

The outcome of the Playbook execution is printed as shown:

To copy files within the remote node, use the remote_src option and set it to yes . In the example below we are making a backup copy of apache2.conf configuration file on the remote node. Simply put, we are making a copy of the file and renaming it to apache2.conf.back .

The playbook runs successfully as shown:

# Lineinfile Module

The lineinfile module is a module that is used for performing a wide selection of tasks on a line such as modifying, replacing, or adding a single line to a file. It can be used in conjunction with regex expressions to match specific lines and make changes.

To demonstrate its functionality, let us take a few examples. The playbook modifies the SSH service configuration on the remote target by changing two parameters. The first task sets the ClientAliveInterval directive to 15 while the second task sets the ClientAliveCountMax directive to 4 . The regexp option matches the lines that contain the parameters we are trying to modify.

The playbook executes both tasks in order of appearance - from the first to the last:

💡 Pro Tip: In the example above, we are trying to match a line that starts with ClientAliveInterval string. Some lines in Linux configuration files may be commented out (i.e. # ClientActiveInterval ). In such case, the regex won’t match, so the lineinfile module will create a new line with the specified string for you.

To add a line to a file, specify the full path of the file, the line to be added to the file, and set the create option to yes .

The playbook shown adds a new line 173.82.120.115 cherry.localdomain to the /etc/hosts file on the remote node.

Here is the Playbook execution:

# Command Module

The Command module takes a command name followed by a list of arguments. The command is executed on target nodes, but the output is not displayed to stdout.

The playbook shown runs the "uptime" and "date" commands on the target modes.

The playbook runs successfully, however, no output from the commands is printed out.

To print the result to stdout, use the shell module. The output of both commands is captured by the register option using our defined uptime_var and date_var variables. These variables are eventually referenced by the msg option, and the values printed to stdout.

In the playbook execution output, you can see the output of both commands printed:

So far, we have demonstrated just a handful of modules. There are hundreds upon hundreds of Ansible modules for performing different tasks. For a more comprehensive list of Ansible modules, visit the Ansible Modules documentation page .

# Ansible Playbook Variables

If you are a developer or a programmer, chances are that you have used variables countless times in your code. Like in many programming languages, variables are used in Playbooks to store values. You can assign a value to a variable and reference it anywhere within the playbook.

Variables can also come from external sources, such as variable files, and then be referenced in a Playbook. Special precedence rules apply when working with variables from multiple sources that bear the same name.

To demonstrate how variables are used in practice, let’s create a playbook file that will print out the value of two variables: greetings and topic .

The vars section defines the list of variables that will be referenced by the debug module in the scope of the play. These variables are accessible to all the tasks and files specified within the playbook file.

In the output, the values assigned to the variables have been printed to stdout in the place of the variable names.

Alternatively, you can have a list of variable items. In the playbook below, let’s define a variable called oceans with a list of five values that represent the five oceans.

The playbook iterates through the list of values under the vars section and prints them to stdout using the msg option.

In addition, you can access each of the values in the variable using the index [ x ] attribute in the msg directive where x is the value of the item in the list. The first item is denoted by index[0] . For example, to access the third item on the list, we will modify the referencing as

# Ansible Playbook Conditionals

Conditional statements are used when you need to execute a set of tasks based on certain criteria. In Ansible Playbooks when is a widely used conditional statement that is used with OR and AND operators.

To better elaborate how conditional statements work, we will have a simple setup with two managed nodes of different OS families:

Server IP: 173.82.120.115 Ubuntu 20.04

Server IP: 173.82.255.207 CentOS 8.3

# Using ‘when’ Statement

Consider the Playbook below. The when statement instructs the Playbook to install Nginx webserver on all the servers that belong to the Debian OS family. We are using the ansible_os_family variable here that belongs to the Ansible facts object, so you don’t need to define it in your playbook.

From the output of the playbook execution, we can see that the CentOS host has been excluded since it does not satisfy our condition.

# Using ‘AND’ Operator with ‘when’ Statement

When using the and operator, both conditions MUST be satisfied. In this example, the playbook will run the task successfully if the managed nodes belong to the Debian Linux family and whose release number is 20.04.

Since the Ubuntu node matches the criteria, the playbook will successfully run and install Nginx on it but skip the CentOS 8 server.

# Using ‘OR’ Operator with ‘when’ Statement

With or operator a task will be executed if either condition is met. In the following Playbook, a new directory called data is created in the home directories of managed nodes that belong to either Debian or RedHat Linux families.

Predictably, the directory is created on both managed nodes since both belong to either of the two OS families.

And just to confirm this, we will list the contents of the home directories on both nodes.

# Ansible Playbook Loops

Occasionally, you will find yourself performing repetitive tasks that require you to write multiple tasks performing the same operation. Take, for example, a playbook that creates new users on a target system as shown.

Evidently, there is a lot of duplication here. It can be daunting and time consuming when dealing with multiple tasks of a similar nature. This is where loops come in handy.

Loops provide a simplified way of executing repetitive tasks with fewer lines of code. They iterate through a list of values specified using the loop or with_* directives.

The loop directive lists the values which are referenced by a variable called item enclosed in double curly braces. During runtime, the playbook iterates through the list of users defined by the loop directive. Each of the users is then passed to the item variable and all the users are created in a simple, yet efficient manner. It’s apparent that the playbook looks neater with fewer lines of code achieving the same goal.

Here is the output of the Playbook execution to confirm the creation of the users:

# Conclusion

In this guide, you have learned how to create and run Ansible playbooks. You have delved into various Playbook elements such as modules, variables, conditional statements, and loops.

Still, we have barely scratched the surface and there’s a lot you can achieve with Playbooks. For more information about Ansible Playbooks, check out the official Ansible Documentation portal.

Winnie Ondara

Winnie is an ardent Linux fan and a lover of FOSS technologies. With over five years of Linux experience, she takes pleasure in penning down high-quality "How-to" guides.

Cloud VPS - Cheaper Each Month

Related articles.

How to Create Ansible Templates [With Examples]

In this guide, we'll learn how to create and use Ansible templates in Ansible playbooks to help you get started with this powerful IT automation tool.

How to Install Ansible on Ubuntu 20.04 | 7 Steps [+ Configuration]

This step-by-step tutorial will show how to install Ansible on Ubuntu 20.04, including how to configure and start using it.

Ansible Roles Tutorial: How to Create and Use Roles in Ansible?

This step-by-step Ansible roles tutorial will teach you how to create and use roles in Ansible to abstract your infrastructure environment.

Creating Ansible tasks

Before you begin.

In your Ansible® instance, create a user token. You use the token to authenticate your UrbanCode Velocity user to Ansible®.

About this task

Create an Ansible® task to manage Ansible® jobs.

To create an Ansible® task, complete the following steps:

• On the Deployment plan detail page, click Create Task . If you want to insert a task at a specific position in the plan, select a task before using the Create Task . The new task is inserted above the selected task.
• On the Create Task dialog box, in the Type list, select Ansible .
• In the Name field, enter a name for the task.
• In the Description field, enter a name for the task.
• In the Instance URL field, enter the location of your Ansible® installation..
• In the Access Token field, paste the token that you generated in your Ansible® instance.
• In the Job ID field, enter the Ansible® job identification number..
• Optional: In the Extra Variables box, enter any parameters that you want to pass to the Ansible® job. The parameter format is JSON. For example: { "environment": "DEV" } example,
• Click Save . The task is inserted into the deployment plan.

What to do next

• Articles Automation Career Cloud Containers Kubernetes Linux Programming Security

8 steps to developing an Ansible role in Linux

%t min read | by Ricardo Gerardi (Editorial Team, Sudoer alumni, Red Hat)

In the article How to use Ansible to configure Vim , I developed an Ansible playbook to configure an initial Vim environment using a few Vim plugins. In this current article, I continue building on the previous example by converting the playbook into an Ansible role .

Ansible roles allow you to develop reusable automation components by grouping and encapsulating related automation artifacts, like configuration files, templates, tasks, and handlers. Because roles isolate these components, it's easier to reuse them and share them with other people. You can also make your roles configurable by exposing variables that users can set when calling the role, allowing them to configure their system according to specific requirements.

[ You might also like:  The four things you must be able to do in Vim ]

In this article, I convert the original playbook vim-config.yaml into a reusable role. At this time, I won't add any new functionality, but I'll further expand this example in the next article. You can find the original playbook and vimrc configuration file here .

1. Starting a new role

To create an Ansible role, it's enough to make a directory following the standard directory structure documented in the official documentation .

To make it easier and follow the standard, use the  ansible-galaxy role init role_name  command to create this directory for you. This command creates the required structure, including a few templates for documentation that you can update. Use it to initialize the  vim  role under the roles directory. First, create the roles directory and switch to it:

Then, use the command ansible-galaxy to initialize the role:

Now, verify the role directory structure:

While not required for the role to work, it's highly recommended to document your role by updating the files README.md and meta/main.yml . If your role depends on other roles to execute, it's important to document these dependencies in meta/main.yml , allowing Ansible to download them automatically if required.

Switch into the newly created directory:

Your Vim role does not require any dependencies. Here's an example of a working meta configuration file. Update it with your name, company name, and a suitable license, if necessary:

The original file has additional comments, which I removed for brevity.

Next, define the tasks to execute.

2. Defining tasks

Generally speaking, your role will execute one or more tasks to configure the target system according to the role's requirements. In this case, you'll want to install and configure Vim. By default, when you execute a role, it looks for a file named main.yml in the tasks subdirectory and execute all the tasks listed within it. You can break the tasks into multiple files for more complex roles and call them from main.yml using the include_tasks or import_tasks modules.

For this role, include all required tasks in the tasks/main.yml file:

Notice that, unlike the original playbook, you don't include the list of packages or plugins to install directly with the task definition. Instead, you're using the variables install_packages and plugins .

By defining variables instead of hard coding the values, you make your roles more reusable and easier to maintain. Now, define values for these variables in two different ways. Start with the plugins variable, covered next.

3. Defining default variables

When you're developing an Ansible role, you might want to allow role users to provide values to customize how the role performs its tasks. These variables make your role more reusable, allowing users to modify the outcome based on their specific requirements.

For this example, the plugins variable allows the users to specify which plugins they want to install with Vim, making the role flexible for their needs. It's recommended to define a default value for it in the defaults/main.yml file to ensure that the roles execute successfully even if the user does not provide a value to this variable.

This file defines variables with a very low precedence which means Ansible will only use them in case the value wasn't defined anywhere else.

Now, define the default value for the plugins variable like this:

In this case, you're defining the default value using the same values from the original playbook, which means that if you call the role without providing a value for this variable, it will behave exactly like the original playbook, installing these six plugins.

Define the internal variables.

4. Defining role variables

Another class of variables is role variables or internal variables. By defining these variables in a separate file from the tasks, you make your role easier to maintain. You can reuse these variables in many places, and it's easier to update them in a central place. However, you don't want to make it too easy for users to override them by setting them in general locations such as the playbook or the inventory.

The variables install_packages , which defines a list of required packages to install, and vimrc , which specifies the location of Vim's configuration file, are good examples of internal variables. Define them in vars/main.yml . This file defines variables with higher precedence that are not easily overridden. Users can still provide values if necessary by explicitly setting them when calling the role, but in this case, you can assume they know what they're doing.

For more details on how Ansible variables precedence works, consult Understanding variable precedence in the documentation.

5. Copying files

The last step to create this role is to copy the file vimrc to the files directory. By default, when using the copy module as a role task, it will look for files to copy in the files subdirectory. Define the vimrc file like this:

Save and close the file to complete your role. Now, it's time to define the playbook to use the role.

6. Calling the role from a playbook

Now that your role is complete, you can call it from your playbooks. By default, Ansible looks for roles in the roles subdirectory relative to the playbook file or the system directory /etc/ansible/roles . You can also use the Ansible configuration roles_path to define alternative role locations.

For this example, create a playbook in the same directory where you created the roles directory. Switch to it:

Create the playbook vim-config.yaml , similar to the original playbook but this time, instead of defining the tasks, use the module import_role to import your new vim role into the playbook:

You can also include the role in the playbook using the module include_role . I'll discuss the differences between these two modules in a separate article. If you can't wait, check the documentation .

Finally, execute the playbook.

8. Execute the playbook

Execute the playbook using the ansible-playbook command with the -K parameter and type your sudo password to allow Ansible to install system packages.

Note : Backup any existing .vimrc configuration file before running this playbook.

This playbook runs and executes all tasks in the localhost. If you want to configure a remote system, create an inventory file with the desired systems and update the playbook hosts list.

[ Looking for more on system automation? Get started with The Automated Enterprise, a free book from Red Hat . ] 

Now you have a role that installs and configures Vim that you can reuse and share. In the next article in this series, I'll improve this role by adding a template file to make the configuration even more flexible.

You can also use Molecule to test your roles using containers or virtual machines. If you want to know more about that tool, read my article Developing and Testing Ansible Roles with Molecule and Podman - Part 1 in the official Ansible blog.

For more information about Ansible, consult the  official documentation .

Ricardo Gerardi

Ricardo Gerardi is Technical Community Advocate for Enable Sysadmin and Enable Architect. He was previously a senior consultant at Red Hat Canada, where he specialized in IT automation with Ansible and OpenShift.  More about me

Try Red Hat Enterprise Linux

Download it at no charge from the red hat developer program., related content.

Creating Ansible tasks

Create an Ansible® task.

Before you begin

In your Ansible® instance, create a user token. You use the token to authenticate your HCL ™ Accelerate user to Ansible®.

About this task

Create an Ansible® task to manage Ansible® jobs.

To create an Ansible® task, complete the following steps:

• On the Deployment plan detail page, click Create Task . If you want to insert a task at a specific position in the plan, select a task before using the Create Task . The new task is inserted above the selected task.
• On the Create Task dialog box, in the Type list, select Ansible .
• In the Name field, enter a name for the task.
• In the Description field, enter a name for the task.
• In the Instance URL field, enter the location of your Ansible® installation..
• In the Access Token field, paste the token that you generated in your Ansible® instance.
• In the Job ID field, enter the Ansible® job identification number..
• Optional: In the Extra Variables box, enter any parameters that you want to pass to the Ansible® job. The parameter format is JSON. For example: { "environment": "DEV" } example,
• Click Save . The task is inserted into the deployment plan.

What to do next

• AnsibleFest
• Webinars & Training

• Developer Guide
• Developing modules
• Edit on GitHub

Developing modules 

A module is a reusable, standalone script that Ansible runs on your behalf, either locally or remotely. Modules interact with your local machine, an API, or a remote system to perform specific tasks like changing a database password or spinning up a cloud instance. Each module can be used by the Ansible API, or by the ansible or ansible-playbook programs. A module provides a defined interface, accepts arguments, and returns information to Ansible by printing a JSON string to stdout before exiting.

If you need functionality that is not available in any of the thousands of Ansible modules found in collections, you can easily write your own custom module. When you write a module for local use, you can choose any programming language and follow your own rules. Use this topic to learn how to create an Ansible module in Python. After you create a module, you must add it locally to the appropriate directory so that Ansible can find and execute it. For details about adding a module locally, see Adding modules and plugins locally .

If you are developing a module in a collection , see those documents instead.

Preparing an environment for developing Ansible modules 

You just need ansible-core installed to test the module. Modules can be written in any language, but most of the following guide is assuming you are using Python. Modules for inclusion in Ansible itself must be Python or Powershell.

One advantage of using Python or Powershell for your custom modules is being able to use the module_utils common code that does a lot of the heavy lifting for argument processing, logging and response writing, among other things.

Creating a module 

It is highly recommended that you use a venv or virtualenv for Python development.

To create a module:

Create a library directory in your workspace, your test play should live in the same directory.

Create your new module file: $ touch library/my_test.py . Or just open/create it with your editor of choice.

Paste the content below into your new module file. It includes the required Ansible format and documentation , a simple argument spec for declaring the module options , and some example code.

Modify and extend the code to do what you want your new module to do. See the programming tips and Python 3 compatibility pages for pointers on writing clean and concise module code.

Creating an info or a facts module 

Ansible gathers information about the target machines using facts modules, and gathers information on other objects or files using info modules. If you find yourself trying to add state: info or state: list to an existing module, that is often a sign that a new dedicated _facts or _info module is needed.

In Ansible 2.8 and onwards, we have two type of information modules, they are *_info and *_facts .

If a module is named <something>_facts , it should be because its main purpose is returning ansible_facts . Do not name modules that do not do this with _facts . Only use ansible_facts for information that is specific to the host machine, for example network interfaces and their configuration, which operating system and which programs are installed.

Modules that query/return general information (and not ansible_facts ) should be named _info . General information is non-host specific information, for example information on online/cloud services (you can access different accounts for the same online service from the same host), or information on VMs and containers accessible from the machine, or information on individual files or programs.

Info and facts modules, are just like any other Ansible Module, with a few minor requirements:

They MUST be named <something>_info or <something>_facts , where <something> is singular.

Info *_info modules MUST return in the form of the result dictionary so other modules can access them.

Fact *_facts modules MUST return in the ansible_facts field of the result dictionary so other modules can access them.

They MUST support check_mode .

They MUST NOT make any changes to the system.

They MUST document the return fields and examples .

The rest is just like creating a normal module.

Verifying your module code 

After you modify the sample code above to do what you want, you can try out your module. Our debugging tips will help if you run into bugs as you verify your module code.

Verifying your module code locally 

The simplest way is to use ansible adhoc command:

If your module does not need to target a remote host, you can quickly and easily exercise your code locally like this:

If for any reason (pdb, using print(), faster iteration, etc) you want to avoid going through Ansible, another way is to create an arguments file, a basic JSON config file that passes parameters to your module so that you can run it. Name the arguments file /tmp/args.json and add the following content:

Then the module can be tested locally and directly. This skips the packing steps and uses module_utils files directly:

It should return output like this:

Verifying your module code in a playbook 

You can easily run a full test by including it in a playbook, as long as the library directory is in the same directory as the play:

Create a playbook in any directory: $ touch testmod.yml

Add the following to the new playbook file:

Run the playbook and analyze the output: $ ansible-playbook ./testmod.yml

Testing your newly-created module 

The following two examples will get you started with testing your module code. Please review our testing section for more detailed information, including instructions for testing module documentation , adding integration tests , and more.

If contributing to Ansible, every new module and plugin should have integration tests, even if the tests cannot be run on Ansible CI infrastructure. In this case, the tests should be marked with the unsupported alias in aliases file .

Performing sanity tests 

You can run through Ansible’s sanity checks in a container:

$ ansible-test sanity -v --docker --python 3.10 MODULE_NAME

Note that this example requires Docker to be installed and running. If you’d rather not use a container for this, you can choose to use --venv instead of --docker .

Contributing back to Ansible 

If you would like to contribute to ansible-core by adding a new feature or fixing a bug, create a fork of the ansible/ansible repository and develop against a new feature branch using the devel branch as a starting point. When you have a good working code change, you can submit a pull request to the Ansible repository by selecting your feature branch as a source and the Ansible devel branch as a target.

If you want to contribute a module to an Ansible collection , review our submission checklist , programming tips , and strategy for maintaining Python 2 and Python 3 compatibility , as well as information about testing before you open a pull request.

The Community Guide covers how to open a pull request and what happens next.

Communication and development support 

Join the #ansible-devel chat channel (using Matrix at ansible.im or using IRC at irc.libera.chat ) for discussions surrounding Ansible development.

For questions and discussions pertaining to using the Ansible product, join the #ansible channel.

To find other topic-specific chat channels, look at Community Guide, Communicating .

Thank you to Thomas Stringer ( @trstringer ) for contributing source material for this topic.