# in Ansible 1.2 and later, roles allow easy best-practices organization of content 
# and maximize shareability of ansible building blocks.
#
# suppose a playbook applied to a group of hosts includes two roles, foo and bar.
#
# what do roles do in this case?
#
# listing the roles as foo and bar will auto include the following:
#
#    tasks    from ./roles/foo/tasks/main.yml,    then ./roles/bar/tasks/main.yml
#    handlers from ./roles/foo/handlers/main.yml, then ./roles/bar/handlers/main.yml
#    vars     from ./roles/foo/vars/main.yml,     then ./roles/bar/vars/main.yml
#
# should any of these files not exist, that is ok, and they will simply not be loaded.
#
# should the task file in foo/tasks/main.yml want to include subtasks in other files, that
# is also permitted.
#
# templates and copy operations also get smarter about where to look for content when using
# roles.
# 
# as an example, a task in foo/tasks/main.yml could copy or template a file by
# referencing a "src=foo.j2" rather than having to explicitly path src=roles/foo/templates/foo.j2.

---

  - hosts: all

    pre_tasks:

        # these tasks are executed prior to roles.
        # this might be a good time to signal an outage window or take a host out of a load balanced pool

        - local_action: shell echo "hi this is a pre_task step about {{ inventory_hostname }}"

    roles:

    # a role can be listed flat like this: 
    #
    #   - common
    #   - webservers

    # but you can also pass variables to them, so they can be parameterized.  You can call
    # a role more than once with different parameters too.  It might look like the section
    # below.  Note I can also declare tags at this time.

      - { role: foo, param1: 1000, param2: 2000, tags: [ 'foo', 'bar' ] }
      - { role: foo, param1: 8000, param2: 9000, tags: [ 'baz' ]  }

    # add as many roles as you like, roles takes a list of roles names
    # these paths can be qualified, but if bare, it will look from them in
    # roles/{{rolename}} relative to the playbook

    # explicit tasks and handlers can be used, but are not required.
    # they will run after the roles if present.

    tasks:

        # you can still have loose tasks/handlers and they will execute after roles are applied

        - shell: echo 'this is a loose task'

    post_tasks:

        # just to provide a syntactic mirroring to 'pre_tasks', these run absolute last in the play.
        # this might be a good time to put a host back in a load balanced pool or end an outage window

        - local_action: shell echo 'this is a post_task about {{ inventory_hostname }}'