Merge pull request #3542 from pol/docs_task_format

Update to conventional task format

docsite/latest/rst/playbooks.rst

@@ -55,16 +55,16 @@ For starters, here's a playbook that contains just one play::
       user: root
       tasks:
       - name: ensure apache is at the latest version
-        action: yum pkg=httpd state=latest
+        yum: pkg=httpd state=latest
       - name: write the apache config file
-        action: template src=/srv/httpd.j2 dest=/etc/httpd.conf
+        template: src=/srv/httpd.j2 dest=/etc/httpd.conf
         notify:
         - restart apache
       - name: ensure apache is running
-        action: service name=httpd state=started
+        service: name=httpd state=started
       handlers:
         - name: restart apache
-          action: service name=httpd state=restarted
+          service: name=httpd state=restarted
 
 Below, we'll break down what the various features of the playbook language are.
 
@@ -165,7 +165,7 @@ porting over from those other configuration systems.
 How about an example.  If I wanted to write the hostname into the /etc/motd file, I could say::
 
    - name: write the motd
-     action: template src=/srv/templates/motd.j2 dest=/etc/motd
+     template: src=/srv/templates/motd.j2 dest=/etc/motd
 
 And in /srv/templates/motd.j2::
 
@@ -205,12 +205,17 @@ nice to have reasonably good descriptions of each task step.  If the name
 is not provided though, the string fed to 'action' will be used for
 output.
 
+Tasks can be declared using the legacy "action: module options" format, but 
+it is recommeded that you use the more conventional "module: options" format.
+This recommended format is used throughout the documentation, but you may
+encounter the older format in some playbooks.
+
 Here is what a basic task looks like, as with most modules,
 the service module takes key=value arguments::
 
    tasks:
      - name: make sure apache is running
-       action: service name=httpd state=running
+       service: name=httpd state=running
 
 The `command` and `shell` modules are the one modules that just takes a list
 of arguments, and don't use the key=value form.  This makes
@@ -218,20 +223,20 @@ them work just like you would expect. Simple::
 
    tasks:
      - name: disable selinux
-       action: command /sbin/setenforce 0
+       command: /sbin/setenforce 0
 
 The command and shell module care about return codes, so if you have a command
 who's successful exit code is not zero, you may wish to do this::
 
    tasks:
      - name: run this command and ignore the result
-       action: shell /usr/bin/somecommand || /bin/true
+       shell: /usr/bin/somecommand || /bin/true
 
 Or this::
 
    tasks:
      - name: run this command and ignore the result
-       action: shell /usr/bin/somecommand
+       shell: /usr/bin/somecommand
        ignore_errors: True
 
 
@@ -240,7 +245,7 @@ a space and indent any continuation lines::
 
     tasks:
       - name: Copy ansible inventory file to client
-        action: copy src=/etc/ansible/hosts dest=/etc/ansible/hosts
+        copy: src=/etc/ansible/hosts dest=/etc/ansible/hosts
                 owner=root group=root mode=0644
 
 Variables can be used in action lines.   Suppose you defined
@@ -248,7 +253,7 @@ a variable called 'vhost' in the 'vars' section, you could do this::
 
    tasks:
      - name: create a virtual host file for {{ vhost }}
-       action: template src=somefile.j2 dest=/etc/httpd/conf.d/{{ vhost }}
+       template: src=somefile.j2 dest=/etc/httpd/conf.d/{{ vhost }}
 
 Those same variables are usable in templates, which we'll get to later.
 
@@ -262,7 +267,7 @@ Action Shorthand
 
 Rather than listing out the explicit word, "action:", like so::
 
-    action: template src=templates/foo.j2 dest=/etc/foo.conf
+    template: src=templates/foo.j2 dest=/etc/foo.conf
 
 It is also possible to say:
 
@@ -290,7 +295,7 @@ Here's an example of restarting two services when the contents of a file
 change, but only if the file changes::
 
    - name: template configuration file
-     action: template src=template.j2 dest=/etc/foo.conf
+     template: src=template.j2 dest=/etc/foo.conf
      notify:
         - restart memcached
         - restart apache
@@ -308,9 +313,9 @@ Here's an example handlers section::
 
     handlers:
         - name: restart memcached
-          action: service name=memcached state=restarted
+          service:  name=memcached state=restarted
         - name: restart apache
-          action: service name=apache state=restarted
+          service: name=apache state=restarted
 
 Handlers are best used to restart services and trigger reboots.  You probably
 won't need them for much else.
@@ -345,9 +350,9 @@ A task include file simply contains a flat list of tasks, like so::
     ---
     # possibly saved as tasks/foo.yml
     - name: placeholder foo
-      action: command /bin/foo
+      command: /bin/foo
     - name: placeholder bar
-      action: command /bin/bar
+      command: /bin/bar
 
 Include directives look like this, and can be mixed in with regular tasks in a playbook::
 
@@ -398,7 +403,7 @@ of your playbooks.  You might make a handlers.yml that looks like::
    ---
    # this might be in a file like handlers/handlers.yml
    - name: restart apache
-     action: service name=apache state=restarted
+     service: name=apache state=restarted
 
 And in your main playbook file, just include it like so, at the bottom
 of a play::
@@ -419,7 +424,7 @@ For example::
       tasks:
       - name: say hi
         tags: foo
-        action: shell echo "hi..."
+        shell: echo "hi..."
 
     - include: load_balancers.yml
     - include: webservers.yml

docsite/latest/rst/playbooks2.rst

@@ -23,14 +23,14 @@ Example::
 
     tasks:
 
-        - action: yum name={{ item }} state=installed
+        - yum: name={{ item }} state=installed
           with_items:
              - httpd
              - memcached
           tags:
              - packages
 
-        - action: template src=templates/src.j2 dest=/etc/foo.conf
+        - template: src=templates/src.j2 dest=/etc/foo.conf
           tags:
              - configuration
 
@@ -66,7 +66,7 @@ has a failure.  Sometimes, though, you want to continue on.  To do so,
 write a task that looks like this::
 
     - name: this will not be counted as a failure
-      action: command /bin/false
+      command: /bin/false
       ignore_errors: yes
 
 Accessing Complex Variable Data
@@ -149,7 +149,7 @@ You can do this by using an external variables file, or files, just like this::
         - /vars/external_vars.yml
       tasks:
       - name: this is just a placeholder
-        action: command /bin/echo foo
+        command: /bin/echo foo
 
 This removes the risk of sharing sensitive data with others when
 sharing your playbook source with them.
@@ -285,7 +285,7 @@ Don't panic -- it's actually pretty simple::
 
     tasks:
       - name: "shutdown Debian flavored systems"
-        action: command /sbin/shutdown -t now
+        command: /sbin/shutdown -t now
         when: ansible_os_family == "Debian"
 
 A number of Jinja2 "filters" can also be used in when statements, some of which are unique
@@ -293,14 +293,14 @@ and provided by Ansible.  Suppose we want to ignore the error of one statement a
 decide to do something conditionally based on success or failure::
 
     tasks:
-      - action: command /bin/false
+      - command: /bin/false
         register: result
         ignore_errors: True
-      - action: command /bin/something
+      - command: /bin/something
         when: result|failed
-      - action: command /bin/something_else
+      - command: /bin/something_else
         when: result|success
-      - action: command /bin/still/something_else
+      - command: /bin/still/something_else
         when: result|skipped
 
 
@@ -336,14 +336,14 @@ there will be accessible to future tasks::
     tasks:
         - name: gather site specific fact data
           action: site_facts
-        - action: command echo {{ my_custom_fact_can_be_used_now }}
+        - command: echo {{ my_custom_fact_can_be_used_now }}
 
 One useful trick with *when* is to key off the changed result of a last command.  As an example::
 
     tasks:
-        - action: template src=/templates/foo.j2 dest=/etc/foo.conf
+        - template: src=/templates/foo.j2 dest=/etc/foo.conf
           register: last_result
-        - action: command echo 'the file has changed'
+        - command: echo 'the file has changed'
           when: last_result.changed
 
 {{ last_result }} is a variable set by the register directive. This assumes Ansible 0.8 and later.
@@ -352,7 +352,7 @@ When combining `when` with `with_items`, be aware that the `when` statement is p
 This is by design::
 
     tasks:
-        - action: command echo {{ item }}
+        - command: echo {{ item }}
           with_items: [ 0, 2, 4, 6, 8, 10 ]
           when: item > 5
 
@@ -380,7 +380,7 @@ but it is easily handled with a minimum of syntax in an Ansible Playbook::
         - [ "vars/{{ ansible_os_family }}.yml", "vars/os_defaults.yml" ]
       tasks:
       - name: make sure apache is running
-        action: service name={{ apache }} state=running
+        service: name={{ apache }} state=running
 
 .. note::
    The variable 'ansible_os_family' is being interpolated into
@@ -420,7 +420,7 @@ Loops
 To save some typing, repeated tasks can be written in short-hand like so::
 
     - name: add several users
-      action: user name={{ item }} state=present groups=wheel
+      user: name={{ item }} state=present groups=wheel
       with_items:
          - testuser1
          - testuser2
@@ -432,9 +432,9 @@ If you have defined a YAML list in a variables file, or the 'vars' section, you
 The above would be the equivalent of::
 
     - name: add user testuser1
-      action: user name=testuser1 state=present groups=wheel
+      user: name=testuser1 state=present groups=wheel
     - name: add user testuser2
-      action: user name=testuser2 state=present groups=wheel
+      user: name=testuser2 state=present groups=wheel
 
 The yum and apt modules use with_items to execute fewer package manager transactions.
 
@@ -442,7 +442,7 @@ Note that the types of items you iterate over with 'with_items' do not have to b
 If you have a list of hashes, you can reference subkeys using things like::
 
     - name: add several users
-      action: user name={{ item.name }} state=present groups={{ item.groups }}
+      user: name={{ item.name }} state=present groups={{ item.groups }}
       with_items:
         - { name: 'testuser1', groups: 'wheel' }
         - { name: 'testuser2', groups: 'root' }
@@ -484,16 +484,16 @@ be used like this::
       tasks:
 
         # first ensure our target directory exists
-        - action: file dest=/etc/fooapp state=directory
+        - file: dest=/etc/fooapp state=directory
 
         # copy each file over that matches the given pattern
-        - action: copy src={{ item }} dest=/etc/fooapp/ owner=root mode=600
+        - copy: src={{ item }} dest=/etc/fooapp/ owner=root mode=600
           with_fileglob:
             - /playbooks/files/fooapp/*
 
 ``with_file`` loads data in from a file directly::
 
-        - action: authorized_key user=foo key={{ item }}
+        - authorized_key: user=foo key={{ item }}
           with_file:
              - /home/foo/.ssh/id_rsa.pub
 
@@ -512,19 +512,19 @@ Many new lookup abilities were added in 0.9.  Remember, lookup plugins are run o
 
       tasks:
 
-         - action: debug msg="{{ lookup('env','HOME') }} is an environment variable"
+         - debug: msg="{{ lookup('env','HOME') }} is an environment variable"
 
-         - action: debug msg="{{ item }} is a line from the result of this command"
+         - debug: msg="{{ item }} is a line from the result of this command"
            with_lines:
              - cat /etc/motd
 
-         - action: debug msg="{{ lookup('pipe','date') }} is the raw result of running this command"
+         - debug: msg="{{ lookup('pipe','date') }} is the raw result of running this command"
 
-         - action: debug msg="{{ lookup('redis_kv', 'redis://localhost:6379,somekey') }} is value in Redis for somekey"
+         - debug: msg="{{ lookup('redis_kv', 'redis://localhost:6379,somekey') }} is value in Redis for somekey"
 
-         - action: debug msg="{{ lookup('dnstxt', 'example.com') }} is a DNS TXT record for example.com"
+         - debug: msg="{{ lookup('dnstxt', 'example.com') }} is a DNS TXT record for example.com"
 
-         - action: debug msg="{{ lookup('template', './some_template.j2') }} is a value from evaluation of this template"
+         - debug: msg="{{ lookup('template', './some_template.j2') }} is a value from evaluation of this template"
 
 As an alternative you can also assign lookup plugins to variables or use them
 elsewhere.  This macros are evaluated each time they are used in a task (or
@@ -679,7 +679,7 @@ The following construct selects the first available file appropriate for the var
 The following example shows how to template out a configuration file that was very different between, say, CentOS and Debian::
 
     - name: template a file
-      action: template src={{ item }} dest=/etc/myapp/foo.conf
+      template: src={{ item }} dest=/etc/myapp/foo.conf
       first_available_file:
         - /srv/templates/myapp/{{ ansible_distribution }}.conf
         - /srv/templates/myapp/default.conf
@@ -707,7 +707,7 @@ poll value is 10 seconds if you do not specify a value for `poll`::
       user: root
       tasks:
       - name: simulate long running op (15 sec), wait for up to 45, poll every 5
-        action: command /bin/sleep 15
+        command: /bin/sleep 15
         async: 45
         poll: 5
 
@@ -724,7 +724,7 @@ Alternatively, if you do not need to wait on the task to complete, you may
       user: root
       tasks:
       - name: simulate long running op, allow to run for 45, fire and forget
-        action: command /bin/sleep 15
+        command: /bin/sleep 15
         async: 45
         poll: 0
 
@@ -795,10 +795,10 @@ The 'register' keyword decides what variable to save a result in.  The resulting
 
       tasks:
 
-          - action: shell cat /etc/motd
+          - shell: cat /etc/motd
             register: motd_contents
 
-          - action: shell echo "motd contains the word hi"
+          - shell: echo "motd contains the word hi"
             when: motd_contents.stdout.find('hi') != -1
 
 
@@ -834,14 +834,14 @@ a good idea::
 
       tasks:
       - name: take out of load balancer pool
-        action: command /usr/bin/take_out_of_pool {{ inventory_hostname }}
+        command: /usr/bin/take_out_of_pool {{ inventory_hostname }}
         delegate_to: 127.0.0.1
 
       - name: actual steps would go here
-        action: yum name=acme-web-stack state=latest
+        yum: name=acme-web-stack state=latest
 
       - name: add back to load balancer pool
-        action: command /usr/bin/add_back_to_pool {{ inventory_hostname }}
+        command: /usr/bin/add_back_to_pool {{ inventory_hostname }}
         delegate_to: 127.0.0.1
 
 
@@ -905,7 +905,7 @@ if you have a large number of hosts::
     - hosts: all
       connection: fireball
       tasks:
-          - action: shell echo "Hello {{ item }}"
+          - shell: echo "Hello {{ item }}"
             with_items:
                 - one
                 - two
@@ -919,8 +919,8 @@ any platform.  You will also need gcc and zeromq-devel installed from your packa
       gather_facts: no
       connection: ssh
       tasks:
-          - action: easy_install name=pip
+          - easy_install: name=pip
-          - action: pip name={{ item }} state=present
+          - pip: name={{ item }} state=present
             with_items:
               - pyzmq
               - pyasn1