Ansible is a powerful open-source automation tool that simplifies tasks such as configuration management, application deployment, and task automation. Creating a complete Ansible playbook involves structuring your project, writing the playbook code, and testing it to ensure everything works smoothly before deployment. This guide will walk you through every step of creating and testing a complete Ansible playbook.
1. Understanding Ansible Playbooks
Ansible playbooks are YAML files that define a series of automation tasks. These tasks can configure systems, install software, or perform other automated operations. Each playbook consists of one or more “plays” that define the desired state of the managed hosts.
A typical playbook structure involves:
- Hosts: The machines on which the tasks will be executed.
- Tasks: The individual operations performed on the hosts.
- Handlers: Conditional tasks that run only when notified (e.g., restarting a service).
- Variables: Dynamic values that can be reused throughout the playbook.
2. Setting Up Your Ansible Environment
Before you begin, ensure that you have Ansible installed on your system. You can install Ansible via pip (Python’s package manager) or your operating system’s package manager.
For example, on a Debian-based system:
sudo apt update
sudo apt install ansibleb
Verify the installation by checking the version:
ansible - version
3. Creating a Directory Structure (Arborescence)
A well-organized project directory helps manage complex playbooks and roles. Here’s a typical directory structure for an Ansible project:
ansible_project/
├── ansible.cfg
├── inventory/
│ └── hosts
├── group_vars/
│ └── all.yml
├── roles/
│ └── common/
│ ├── tasks/
│ │ └── main.yml
│ ├── handlers/
│ │ └── main.yml
│ ├── templates/
│ │ └── sample_template.j2
│ ├── vars/
│ │ └── main.yml
│ └── files/
├── playbooks/
│ └── site.yml
└── README.md
Explanation of the structure:
- **ansible.cfg**\: Configuration file that sets Ansible-wide defaults.
- **inventory/hosts**\: Inventory file that lists the hosts and groups.
- **group\_vars/**\: Directory that stores variables for specific groups or hosts.
- **roles/**\: A directory for reusable roles, with separate subdirectories for tasks, handlers, templates, variables, and files.
- **playbooks/**\: Directory that stores your main playbooks.
- **README.md**\: Documentation for your project.
This structure is flexible and can be extended as your project grows.
4. Writing Your First Playbook
Now that your structure is in place, let’s create a simple playbook.
File: playbooks/site.yml\
- name: Ensure web server is installed and running
hosts: webservers
become: true
vars:
http_port: 80
tasks:
- name: Install Apache
apt:
name: apache2
state: present
notify:
- Restart Apache
- name: Ensure Apache is running
service:
name: apache2
state: started
enabled: true
handlers:
- name: Restart Apache
service:
name: apache2
state: restarted
Explanation:
- hosts: webservers\: This play targets hosts in the webservers\ group defined in your inventory.
- become: true\: This enables privilege escalation (e.g., sudo).
- vars:\: Here, we define the HTTP port variable.
- tasks:\: We install Apache and ensure it’s running.
- handlers:\: A handler is defined to restart Apache if needed.
5. Adding Variables, Handlers, and Templates
Variables, handlers, and templates allow for more flexibility and reusability in your playbooks. You can define variables in the **group\_vars/**\ directory, create handlers in the **roles/common/handlers/main.yml**\ file, and use templates to manage configuration files.
Example: group\_vars/all.yml\
http_port: 8080
Example: roles/common/handlers/main.yml\
- name: Reload Apache
service:
name: apache2
state: reloaded
Example: roles/common/templates/sample\_template.j2\
<VirtualHost *:{{ http_port }}>
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html
</VirtualHost>
6. Using Roles for Better Organization
Roles allow you to break down playbooks into reusable components. The directory structure we created earlier already includes a **roles/**\ directory, where each role contains its own tasks, handlers, templates, variables, and files.
Here’s an example of a role structure for managing a web server:
File: roles/common/tasks/main.yml\
- name: Install Apache
apt:
name: apache2
state: present
notify: Reload Apache
By organizing tasks into roles, you can reuse the **common**\ role across multiple playbooks.
7. Testing Your Playbook
Before running your playbook in a production environment, it’s essential to test it. You can do this by using tools such as:
- Vagrant: To spin up virtual machines.
- Docker: To create containers for testing.
- Molecule: A dedicated testing framework for Ansible.
Example: Testing with Vagrant
1. Create a Vagrantfile\ to set up a virtual machine.
2. Write a test playbook to execute on the VM.
3. Use vagrant up\ to bring up the VM and run your tests.
Example: Testing with Molecule
1. Install Molecule: pip install molecule\[docker\]\
2. Create a Molecule scenario: molecule init role -r my\_role\
3. Write your tests in the molecule/default/tests/\ directory.
4. Run the tests: molecule test\
8. Executing the Playbook
Once you’ve tested your playbook, you can execute it on your target hosts.
ansible-playbook -i inventory/hosts playbooks/site.ymlb
This command will run your **site.yml**\ playbook on the hosts defined in your inventory.
9. Conclusion
Creating a complete Ansible playbook involves setting up a clear directory structure, writing playbooks with tasks, handlers, and templates, and organizing them into roles. Testing your playbook using tools like Vagrant, Docker, or Molecule ensures that your automation tasks run smoothly before deployment. With this guide, you now have the foundation to create, structure, and test complex Ansible playbooks.
Top comments (0)