Permalink
Browse files

Adds step-12 about roles

Adds symlinks to last chapter and doc
Added doc about linking the last "real" chapter to the final chapter.
Improves suite test script
Added parameter support to test a single step
Added multiline summary support (roles)
Added role chapter
Added expectations for testing

Adds chapters 12 and 99

Adding a chapter just requires adding symlinks to hosts and site.yml to
the last chapter :
    cd step-99 && ln -sf
    ../step-<last>/{hosts,roles,site.yml,group_vars,host_vars} .
where last is the last chapter except final 99 (fixes #12).
Added step-12 about roles and a site.yml (fixes #21)

Adds more explanations on step-99
  • Loading branch information...
leucos committed Nov 12, 2013
1 parent ad6cb33 commit d770e7b96a13a83fd5fa9cb16fe537bb8f90ef3c
View
@@ -90,9 +90,18 @@ Just in case you want to skip to a specific step, here is a topic table of conte
- [09. Extending to several hosts](https://github.com/leucos/ansible-tuto/tree/master/step-09)
- [10. Templates](https://github.com/leucos/ansible-tuto/tree/master/step-10)
- [11. Variables again](https://github.com/leucos/ansible-tuto/tree/master/step-11)
- [12. Migrating to roles](https://github.com/leucos/ansible-tuto/tree/master/step-12)
- [99. The end](https://github.com/leucos/ansible-tuto/tree/master/step-99)
## Note to contributors
If you make changes, please fill the `test/expectations` file and run
the tests (`test/run.sh`).
See the `test/run.sh` file for (a bit) more information.
When adding a new chapter (e.g. `step-NN`), please issue :
cd step-99
ln -sf ../step-NN/{hosts,roles,site.yml,group_vars,host_vars} .
Thank you !
View
@@ -183,4 +183,4 @@ see the result. Your cluster is deployed !
you can even peek at HAProxy's statistics at
[http://192.168.33.10/haproxy?stats](http://192.168.33.10/haproxy?stats).
Now on to the last chapter about "Variables again", in [step-11](https://github.com/leucos/ansible-tuto/tree/master/step-11).
Now on to the next chapter about "Variables again", in [step-11](https://github.com/leucos/ansible-tuto/tree/master/step-11).
View
@@ -136,31 +136,6 @@ This is required because the haproxy playbook needs to pick facts from
hosts in this group. If we don't do this, ansible will complain saying
that `ansible_eth1` key doesn't exist.
At this point, you can try building up everything from scratch, to see
if you can properly provision your cluster with your playbook.
Now on to the next chapter about "Migrating to Roles !", in [step-12](https://github.com/leucos/ansible-tuto/tree/master/step-12).
Fire in the hole!
vagrant destroy -f
vagrant up
ansible-playbook -i step-00/hosts step-00/setup.yml --ask-pass --sudo
(you might need to wait a little for the network to come up before
running the last command).
All the preceeding commands are just here to set-up our test
environment. Deploying on the blank machines just requires one line :
ansible-playbook -i step-11/hosts step-11/apache.yml step-11/haproxy.yml
Just one command to rule them all: you have your cluster, can add nodes ad
nauseam, tune settings, ... all this can be extended at will with more variables,
other plays, etc...
# The end
Ok, seems we're done with our tutorial. Hope you enjoyed playing with Ansible, and
felt the power of this new tool.
Now go straight to [Ansible website](http://ansible.cc), dive in the docs, check references,
skim through playbooks, chat on freenode in #ansible, and foremost, have fun!
View
@@ -0,0 +1,175 @@
Ansible tutorial
================
Migrating to roles !
--------------------
Now that our playbook is done, let's refactor everything ! We'll replace
our plays with roles. Roles are just a new way of organizing files but
bring interesting features. I won't go into great lengths here, since
they're listed in
[Ansible's documentation](http://www.ansibleworks.com/docs/playbooks_roles.html#id5),
but my favorite is probably roles dependencies: role B can depend on
another role A. Thus, when applying role B, role A will automatically be
applied too. We'll see this in the [next
chapter](https://github.com/leucos/ansible-tuto/tree/master/step-13),
but for now, let's refactor out playbook to use roles.
# Roles structures
Roles add a bit of "magic" to Ansible : they assume a specific file
organization. While there is a suggested layout regarding roles, you can
organize things the way you want using includes. However, role's
conventions help building modular playbooks, and housekeeping will be
much simpler.
Rubyists would call this "convention over configuration".
The file layout for roles looks like this :
roles
|
|_some_role
|
|_files
| |
| |_file1
| |_...
|
|_template
| |
| |_template1.j2
| |_...
|
|_tasks
| |
| |_main.yml
| |_some_other_file.yml
| |_ ...
|
|_handlers
| |
| |_main.yml
| |_some_other_file.yml
| |_ ...
|
|_vars
| |
| |_main.yml
| |_some_other_file.yml
| |_ ...
|
|_meta
|
|_main.yml
|_some_other_file.yml
|_ ...
Quite simple.
The files names `main.yml` are not mandatory. However, when they exist,
roles will add them to the play automatically.
You can use this file to include other tasks, handlers, ... in the play.
We'll see that in a minute.
Note that there is also a `vars` and a `meta` directory. `vars` is used
when you want to put a bunch of variables regarding the roles. However,
I don't like setting vars in roles (or plays) directly. I think variables
belong to configuration, while plays are the structure. In other works,
I see plays and roles as a factory, and data as inputs to this factory.
So I really prefer to have "data" (e.g. variables) outside roles and
play. This way, I can share my roles more easily, without worring
exposing too much about my servers. But that's just a personal
preference. Ansible just lets you do it the way you want.
The `meta` directory is where you can add dependencies, and it's really
a neat feature. We'll see that later.
Note that roles lay in the `roles` directory, which is also cool since
it will reduce top level ansible playbook clutter.
# Creating the apache role
Ok, now that we know the required layout, we can create our apache role
from our apache playbook.
The steps required are really simple :
- create the roles directory and apache role layout
- extract the apache handler into `roles/apache/handlers/main.yml`
- move the apache configuration file `awesome-app` into
`roles/apache/files/`
## Creating the role layout
This is what has been done to convert step-11 apache files into a role :
mkdir -p step-12/roles/apache/{tasks,handlers,files}
cp step-11/files/awesome-app step-12/roles/apache/files/
Now we need to copy the tasks from `apache.yml` to `main.yml`, so this
file looks like this :
- name: Updates apt cache
action: apt update_cache=true
- name: Installs necessary packages
action: apt pkg={{ item }} state=latest
with_items:
- apache2
- libapache2-mod-php5
- git
...
- name: Deactivates the default ssl virtualhost
action: command a2dissite default-ssl
notify:
- restart apache
The file is not fully reproduced, but it is exactly the content of
`apache.yml` between `tasks:` and `handlers:`.
Note that we also have to remove references to `files/` and `templates/`
directories in tasks. Since we're using the roles structure, Ansible
will look for them in the right directories.
We can extract the handlers part and create
`step-12/roles/apache/handlers/main.yml` :
- name: restart apache
action: service name=apache2 state=restarted
At this point, the apache role is fully working, but we need a way to
invoke it.
Let's create a top level playbook that we'll use to map hosts and hosts
groups to roles. We'll call it `site.yml`, since our goal is to have our
site-wide configuration in it. While we're at it, we'll include
`haproxy` int it too :
- hosts: web
roles:
- { role: apache }
- hosts: haproxy
roles:
- { role: haproxy }
That wasn't too hard. We'll do the same for haproxy :
mkdir -p step-12/roles/haproxy/{tasks,handlers,templates}
cp step-11/templates/haproxy.cfg.j2 step-12/roles/haproxy/templates/
then extract the handler, and remove reference to `templates/`.
We can try out the new playbook with :
ansible-playbook -i step-12/hosts step-12/site.yml
should be fine.
We'll see how we can deploy firewall rules for our cluster in
[step-13](https://github.com/leucos/ansible-tuto/tree/master/step-13)
chapter about "Deploying firewall rules". In this chapter, we'll use
role dependencies to build our systems.
@@ -0,0 +1 @@
haproxy_check_interval: 3000
@@ -0,0 +1,3 @@
haproxy_backend_weight: 150
haproxy_stats_socket: /tmp/sock
@@ -0,0 +1 @@
haproxy_backend_weight: 100
@@ -0,0 +1 @@
haproxy_backend_weight: 150
View
@@ -0,0 +1,6 @@
[web]
host1.example.org ansible_ssh_host=192.168.33.11 ansible_ssh_user=root
host2.example.org ansible_ssh_host=192.168.33.12 ansible_ssh_user=root
[haproxy]
host0.example.org ansible_ssh_host=192.168.33.10 ansible_ssh_user=root
@@ -0,0 +1,9 @@
<VirtualHost *:80>
DocumentRoot /var/www/awesome-app
Options -Indexes
ErrorLog /var/log/apache2/error.log
TransferLog /var/log/apache2/access.log
</VirtualHost>
@@ -0,0 +1,3 @@
- name: restart apache
action: service name=apache2 state=restarted
@@ -0,0 +1,45 @@
- name: Updates apt cache
action: apt update_cache=true
- name: Installs necessary packages
action: apt pkg={{ item }} state=latest
with_items:
- apache2
- libapache2-mod-php5
- git
- name: Push future default virtual host configuration
action: copy src=awesome-app dest=/etc/apache2/sites-available/ mode=0640
- name: Activates our virtualhost
action: command a2ensite awesome-app
- name: Check that our config is valid
action: command apache2ctl configtest
register: result
ignore_errors: True
- name: Rolling back - Restoring old default virtualhost
action: command a2ensite default
when: result|failed
- name: Rolling back - Removing out virtualhost
action: command a2dissite awesome-app
when: result|failed
- name: Rolling back - Ending playbook
action: fail msg="Configuration file is not valid. Please check that before re-running the playbook."
when: result|failed
- name: Deploy our awesome application
action: git repo=https://github.com/leucos/ansible-tuto-demosite.git dest=/var/www/awesome-app
tags: deploy
- name: Deactivates the default virtualhost
action: command a2dissite default
- name: Deactivates the default ssl virtualhost
action: command a2dissite default-ssl
notify:
- restart apache
@@ -0,0 +1,3 @@
- name: restart haproxy
action: service name=haproxy state=restarted
@@ -0,0 +1,12 @@
- name: Installs haproxy load balancer
action: apt pkg=haproxy state=installed update_cache=yes
- name: Pushes configuration
action: template src=haproxy.cfg.j2 dest=/etc/haproxy/haproxy.cfg mode=0640 owner=root group=root
notify:
- restart haproxy
- name: Sets default starting flag to 1
action: lineinfile dest=/etc/default/haproxy regexp="^ENABLED" line="ENABLED=1"
notify:
- restart haproxy
@@ -0,0 +1,22 @@
global
daemon
maxconn 256
{% if haproxy_stats_socket %}
stats socket {{ haproxy_stats_socket }}
{% endif %}
defaults
mode http
timeout connect 5000ms
timeout client 50000ms
timeout server 50000ms
listen cluster
bind {{ ansible_eth1['ipv4']['address'] }}:80
mode http
stats enable
balance roundrobin
{% for backend in groups['web'] %}
server {{ hostvars[backend]['ansible_hostname'] }} {{ hostvars[backend]['ansible_eth1']['ipv4']['address'] }} check inter {{ haproxy_check_interval }} weight {{ hostvars[backend]['haproxy_backend_weight'] }} port 80
{% endfor %}
option httpchk HEAD /index.php HTTP/1.0
View
@@ -0,0 +1,8 @@
- hosts: web
roles:
- { role: apache }
- hosts: haproxy
roles:
- { role: haproxy }
View
@@ -0,0 +1,30 @@
# The end
At this point, you can try building up everything from scratch, to see
if you can properly provision your cluster with your playbook.
Fire in the hole!
vagrant destroy -f
vagrant up
ansible-playbook -i step-00/hosts step-00/setup.yml --ask-pass --sudo
(you might need to wait a little for the network to come up before
running the last command).
All the preceeding commands are just here to set-up our test
environment. Deploying on the blank machines just requires one line :
ansible-playbook -i step-99/hosts step-99/site.yml
Just one command to rule them all: you have your cluster, can add nodes ad
nauseam, tune settings, ... all this can be extended at will with more variables,
other plays, etc...
# The end
Ok, seems we're done with our tutorial. Hope you enjoyed playing with Ansible, and
felt the power of this new tool.
Now go straight to [Ansible website](http://ansible.cc), dive in the docs, check references,
skim through playbooks, chat on freenode in #ansible, and foremost, have fun!
View
View
View
Oops, something went wrong.

0 comments on commit d770e7b

Please sign in to comment.