restructure the examples directory

examples/playbooks/handlers/handlers.yml

@@ -0,0 +1,10 @@
+---
+
+# this is an example to show that handlers can be included from yaml files,
+# to promote reuse between different plays or even playbooks.  They work
+# just like normal handlers.
+
+- name: restart apache
+  action: service name=httpd state=restarted
+- name: restart memcached
+  action: service name=memcached state=restarted

examples/playbooks/playbook.yml

@@ -0,0 +1,71 @@
+---
+# this is an annotated example of some features available in playbooks
+# it shows how to make sure packages are updated, how to make sure
+# services are running, and how to template files.  It also demos
+# change handlers that can restart things (or trigger other actions)
+# when resources change.  For more advanced examples, see example2.yml
+
+# on all hosts, run as the user root...
+
+- hosts: all
+  user: root
+
+  # make these variables available inside of templates
+  # for when we use the 'template' action/module later on...
+
+  vars:
+    http_port: 80
+    max_clients: 200
+
+  # define the tasks that are part of this play...
+
+  tasks:
+
+  # task #1 is to run an arbitrary command
+  # we'll simulate a long running task, wait for up to 45 seconds, poll every 5
+  # obviously this does nothing useful but you get the idea
+
+  - name: longrunner
+    action: command /bin/sleep 15
+    async: 45
+    poll: 5
+
+  # let's demo file operations.
+  #
+  # We can 'copy' files or 'template' them instead, using jinja2
+  # as the templating engine.  This is done using the variables 
+  # from the vars section above mixed in with variables bubbled up 
+  # automatically from tools like facter and ohai.  'copy' 
+  # works just like 'template' but does not do variable subsitution.
+  #
+  # If and only if the file changes, restart apache at the very
+  # end of the playbook run
+
+  - name: write some_random_foo configuration
+    action: template src=templates/foo.j2 dest=/etc/some_random_foo.conf
+    notify:
+    - restart apache
+
+  # make sure httpd is installed at the latest version
+
+  - name: install httpd
+    action: yum pkg=httpd state=latest
+
+  # make sure httpd is running
+
+  - name: httpd start
+    action: service name=httpd state=started
+
+  # handlers are only run when things change, at the very end of each
+  # play.  Let's define some.  The names are significant and must
+  # match the 'notify' sections above
+
+  handlers:
+
+    # this particular handler is run when some_random_foo.conf
+    # is changed, and only then
+
+    - name: restart apache
+      action: service name=httpd state=restarted
+
+

examples/playbooks/playbook2.yml

@@ -0,0 +1,89 @@
+---
+# see examples.yml first!
+# This file explains some more advanced features of playbooks.  
+# because of the comments it's less concise than it normally is.  But feel
+# free to comment your playbooks if you like.
+
+- hosts: dbservers
+
+  # we can define variables the normal way...
+
+  vars:
+    release: 2.0
+
+  # but they can also come from other files.  This can be a relative
+  # or absolute path.  This is a good way to store 'secret' variable
+  # files but still keep the playbook in public source control
+
+  vars_files:
+    - vars/external_vars.yml
+
+  # as with before, every play has a list of tasks in it
+
+  tasks:
+
+  # tasks can be written the normal way...
+
+  - name: arbitrary command
+    action: command /bin/true
+
+  # or we can promote reuse and simplicity by including tasks
+  # from other files, for instance, to reuse common tasks
+
+  - include: tasks/base.yml
+
+  # we could also have done something like:
+  # - include: wordpress.yml user=timmy
+  # and had access to the template variable {{ user }} in the 
+  # included file, if we wanted to.  Variables from vars
+  # and vars_files are also available inside include files
+
+  handlers:
+ 
+    # handlers can also be included from files, to promote reuse
+    # and simpler recipes, you may wish to only have one
+    # handler file for all your plays and playbooks
+
+    - include: handlers/handlers.yml
+
+    # you can mix things that are directly in the file with things
+    # that are included.  Order is executed as written, but only
+    # handlers that have been notified get executed
+
+    - name: restart foo
+      action: service name=foo state=restarted
+
+# ===============================================================
+
+# Here's a second play in the same playbook.  This will be run
+# after the first playbook completes on all hosts.  You may want
+# a different play for each class of systems, or may want a different
+# play for each stage in a complex multi-node deployment push
+# process.  How you use them are up to you.
+
+# any play in a playbook can be executed by a user other than root
+# if you want.  sudo support is coming too.
+
+- hosts: webservers
+  user: mdehaan
+
+  # vars must be specified again for the next play in the playbook
+  # but can be reused by including from vars_files if you want
+  # you can use vars, vars_files, or both.  vars_files overrides
+  # those set in vars. 
+
+  vars:
+     release: 2.0
+  vars_files:
+     - vars/external_vars.yml
+
+
+  # these all runs as the user 'mdehaan'.  If there were any handlers
+  # they would as well.
+
+  tasks:
+
+     - name: some random command
+       action: command /bin/true
+
+

examples/playbooks/playbook3.yml

@@ -0,0 +1,26 @@
+---
+# this is not so much an example playbook file as a playbook we sometimes use
+# for testing.  I have chosen to not comment this one so folks can get
+# an idea of what a concise playbook can look like...
+
+- hosts: all
+  user: root
+  vars:
+    http_port: 80
+    max_clients: 200
+  tasks:
+  - name: simulate long running op, wait for 45s, poll every 5
+    action: command /bin/sleep 15
+    async: 45
+    poll: 5
+  - include: tasks/base.yml favcolor=blue
+  - name: write the foo config file using vars set above
+    action: template src=foo.j2 dest=/etc/some_random_foo.conf
+    notify:
+    - restart apache
+  - name: ensure apache is running
+    action: service name=httpd state=started
+  - name: pointless test action
+    action: command /bin/echo {{ http_port }}
+  handlers:
+    - include: handlers/handlers.yml

examples/playbooks/tasks/base.yml

@@ -0,0 +1,22 @@
+---
+
+# this is the example of an included tasks file.  It contains a flat list of tasks
+# they can notify other tasks, and have full access to variables from 'vars'
+# or 'vars_files' directives.  Further, if ohai or facter were installed on 
+# the remote machines, variables from those tools can be accessed on the 'action'
+# line or in templates.  Just prefix with 'facter_' or 'ohai_' before the particular
+# variable.
+
+# possible uses for a included yaml file might be to represent a 'class' of a system
+# like defining what makes up a webserver, or you might have a common 'base.yml'
+# (like this) that might be applied to all your systems as well.
+
+- name: no selinux
+  action: command /usr/sbin/setenforce 0
+
+- name: no iptables
+  action: service name=iptables state=stopped
+
+- name: made up task just to show variables work here
+  action: command /bin/echo release is {{ release }}
+

examples/playbooks/templates/foo.j2

@@ -0,0 +1,4 @@
+# This is a very simple Jinja2 template representing an imaginary configuration file
+# for an imaginary app.
+
+http_port={{ http_port }}

examples/playbooks/vars/external_vars.yml

@@ -0,0 +1,3 @@
+---
+alpha: one
+beta: two