From bd7448ccf07498be36475803ca8ced5377dd342d Mon Sep 17 00:00:00 2001 From: Pol Llovet Date: Mon, 15 Jul 2013 11:50:48 -0600 Subject: [PATCH] Update to conventional task format --- docsite/latest/rst/playbooks.rst | 43 +++++++++-------- docsite/latest/rst/playbooks2.rst | 76 +++++++++++++++---------------- 2 files changed, 62 insertions(+), 57 deletions(-) diff --git a/docsite/latest/rst/playbooks.rst b/docsite/latest/rst/playbooks.rst index adf03f18d76..6b832625b85 100644 --- a/docsite/latest/rst/playbooks.rst +++ b/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 diff --git a/docsite/latest/rst/playbooks2.rst b/docsite/latest/rst/playbooks2.rst index 92283d549ff..4e26c77a014 100644 --- a/docsite/latest/rst/playbooks2.rst +++ b/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' } @@ -465,16 +465,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 @@ -493,19 +493,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 @@ -660,7 +660,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 @@ -688,7 +688,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 @@ -705,7 +705,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 @@ -776,10 +776,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 @@ -815,14 +815,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 @@ -886,7 +886,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 @@ -900,8 +900,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 - - action: pip name={{ item }} state=present + - easy_install: name=pip + - pip: name={{ item }} state=present with_items: - pyzmq - pyasn1