Creating Roles
Ansible Galaxy
Ansible has a built in tool ansible-galaxy which allows us to quickly create a set of folders and files that are needed in the creation of an Ansible role.
Simply run ansible-galaxy init rolename --offline and a folder will be created within your current directory that contains the basic structure of an Ansible role. Within this directory, we can easily pick and choose which components we will need for our role.
Creating NGINX Roles
To begin, we will create a simple role for installing and configuring a simple nginx server. Navigate within your role, which we will assume is simply called nginx-role
Define Tasks
Within nginx-role/tasks/main.yml we include the following -
---
# tasks file for /etc/ansible/roles/nginx
- import_tasks: install.yml
- import_tasks: configure.yml
- import_tasks: service.yml
This task assumes that within the nginx-role/tasks/ directory we also have the files install.yml , configure.yml , and service.yml - See the below snippets for examples of how these files could look, depending on your scenario.
Within the nginx-role/tasks/ directory, create the following files -
Create a nginx-role/tasks/install.yml task for installing nginx and any other required packages if needed
---
- name: Install nginx Package
apt: name=nginx state=latest
Create a nginx-role/tasks/configure.yml task for templating various configuration files needed to configure an nginx webserver
---
- name: Copy nginx configuration file
template: src=files/nginx.conf dest=/etc/nginx/nginx.conf
- name: Copy index.html file
template: src=files/index.html dest=/var/www/html
notify:
- restart nginx
Create a task nginx-role/tasks/service.yml for starting the nginx service
---
- name: Start and enable nginx service
service: name=nginx state=restarted enabled=yes
Now we have defined all the tasks that Ansible needs to carryout in order to create a new nginx host. All thats left to do is ensure that the tasks we created above have all the resources we said would be available when the role is ran on a host.
Define Handlers
In the tasks above, notice the notify: -restart nginx within configure.yml. Here, we have declared that this task makes changes that require nginx to be restarted in order to be applied. So, we create the handler task below to carry out the restart nginx task that we have notified of our changes.
To set this up, create the following nginx-role/handlers/main.yml configuration
---
# handlers file for /etc/ansible/roles/nginx
- name: restart nginx
service: name=nginx state=restarted
Define Templates / Files
Ansible will need to refer to the templates / files we declared in the above tasks -
Add them within the nginx-role/files/ directory
Create the following nginx-role/files/nginx.conf
user www-data;
worker_processes auto;
pid /run/nginx.pid;
events { }
http {
include mime.types;
# Basic Server Configuration
server {
listen 80;
server_tokens off;
server_name {{ domain_name }};
location / {
root {{ nginx_root_dir }};
index {{ index_files }};
}
# Uncomment to pass for SSL
#return 301 https://$host$request_uri;
}
}
Then we can create a custom template at nginx-role/files/index.html for our landing page to verify things are working.
Welcome to nginx!
Klips!
If you see this page, the nginx web server is successfully installed and working. Further configuration is required.
For online documentation and support please refer to
nginx.org.
Commercial support is available at
nginx.com.
Thank you for using nginx.
Define Variables / Defaults
Last, we need to define the Ansible defaults we referenced in the above configurations {{ variable_name }} is a variable within Ansible, these can be used to create roles that can be used dynamically or easily reconfigured and reapplied to different scenarios.
Create the following main.yml file in nginx-role/defaults
---
# defaults file for /etc/ansible/roles/nginx
#
domain_name: "localhost"
nginx_root_dir: "/var/www/html/"
index_files: "index.html index.htm"
Ansible has a wide range of variables, or facts, that it collects on the hosts within its inventory. To see a complete list of all the facts available for a host, run the following
ansible hostname -m setup
This will print a ton of information, all of which is available for use within ansible templates by calling a variable corresponding to the fact name. For example, if we wanted the fact ansible_hostname and ansible_fqdn , we call them as {{ ansible_hostname }} or {{ ansible_fqdn }} . When these variables are ran within a playbook, ansible will insert the values of these variables depending on the host the task is running on.
Using Ansible Roles
That's it! Now all we need to do is create an inventory / hosts file and run a playbook using our new role -
Create your ansible host file at /etc/ansible/hosts with the relevant information for your environment
# This is the default ansible 'hosts' file.
#
# It should live in /etc/ansible/hosts
[group]
www.domain.com
sub.domain.com:22
0.0.0.0
127.0.0.1:22
[othergroup]
sub.domain.com:22
127.0.0.1:22
[nginx-server]
sub.domain.com:22
Create the playbook /etc/ansible/nginx.yml to kick off our role using the role information and groups entered above within the hosts file.
---
- hosts: nginx-server
become: yes
roles:
- nginx
Now from within /etc/ansible/ , simply run ansible-playbook nginx.yml and our tasks configured above will be carried out on the server defined in the hosts file above.
If you are testing using SSL, be sure to use the --dry-run argument until your configurations are tested and working correctly.
sudo certbot certonly -d domain.com -d www.domain.com --dry-run --standalone --agree-tos -m some-email@domain.com