From 6c1a63dd14bb906bc51f603dc2ac29951a75d2d0 Mon Sep 17 00:00:00 2001 From: Joshua Smith Date: Sat, 3 Feb 2018 06:28:22 -0500 Subject: [PATCH] Update example syntax (#35670) * Update examples in guide_rolling_upgrade.rst. * Update examples playbooks_best_practices.rst. * Update examples in playbooks_checkmode.rst. --- docs/docsite/rst/guide_rolling_upgrade.rst | 23 +++++++++--- docs/docsite/rst/playbooks_best_practices.rst | 37 ++++++++++++------- docs/docsite/rst/playbooks_checkmode.rst | 37 +++++++++++-------- 3 files changed, 62 insertions(+), 35 deletions(-) diff --git a/docs/docsite/rst/guide_rolling_upgrade.rst b/docs/docsite/rst/guide_rolling_upgrade.rst index 48e7ad049ac..2a10cfd3f80 100644 --- a/docs/docsite/rst/guide_rolling_upgrade.rst +++ b/docs/docsite/rst/guide_rolling_upgrade.rst @@ -134,11 +134,17 @@ If you look in the example, there are group variables for the ``webservers`` gro These variables are used in a variety of places. You can use them in playbooks, like this, in ``roles/db/tasks/main.yml``:: - name: Create Application Database - mysql_db: name={{ dbname }} state=present + mysql_db: + name: "{{ dbname }}" + state: present - name: Create Application DB User - mysql_user: name={{ dbuser }} password={{ upassword }} - priv=*.*:ALL host='%' state=present + mysql_user: + name: "{{ dbuser }}" + password: "{{ upassword }}" + priv: "*.*:ALL" + host: '%' + state: present You can also use these variables in templates, like this, in ``roles/common/templates/ntp.conf.j2``:: @@ -211,7 +217,10 @@ Here is the next part of the update play:: pre_tasks: - name: disable nagios alerts for this host webserver service - nagios: action=disable_alerts host={{ inventory_hostname }} services=webserver + nagios: + action: disable_alerts + host: "{{ inventory_hostname }}" + services: webserver delegate_to: "{{ item }}" loop: "{{ groups.monitoring }}" @@ -220,7 +229,6 @@ Here is the next part of the update play:: delegate_to: "{{ item }}" loop: "{{ groups.lbservers }}" - .. note:: - The ``serial`` keyword forces the play to be executed in 'batches'. Each batch counts as a full play with a subselection of hosts. This has some consequences on play behavior. For example, if all hosts in a batch fails, the play fails, which in turn fails the entire run. You should consider this when combining with ``max_fail_percentage``. @@ -247,7 +255,10 @@ Finally, in the ``post_tasks`` section, we reverse the changes to the Nagios con loop: "{{ groups.lbservers }}" - name: re-enable nagios alerts - nagios: action=enable_alerts host={{ inventory_hostname }} services=webserver + nagios: + action: enable_alerts + host: "{{ inventory_hostname }}" + services: webserver delegate_to: "{{ item }}" loop: "{{ groups.monitoring }}" diff --git a/docs/docsite/rst/playbooks_best_practices.rst b/docs/docsite/rst/playbooks_best_practices.rst index ff4e9240048..c7984cfbd9e 100644 --- a/docs/docsite/rst/playbooks_best_practices.rst +++ b/docs/docsite/rst/playbooks_best_practices.rst @@ -250,17 +250,24 @@ Below is an example tasks file that explains how a role works. Our common role # file: roles/common/tasks/main.yml - name: be sure ntp is installed - yum: name=ntp state=installed + yum: + name: ntp + state: installed tags: ntp - name: be sure ntp is configured - template: src=ntp.conf.j2 dest=/etc/ntp.conf + template: + src: ntp.conf.j2 + dest: /etc/ntp.conf notify: - restart ntpd tags: ntp - name: be sure ntpd is running and enabled - service: name=ntpd state=started enabled=yes + service: + name: ntpd + state: started + enabled: yes tags: ntp Here is an example handlers file. As a review, handlers are only fired when certain tasks report changes, and are run at the end @@ -269,7 +276,9 @@ of each play:: --- # file: roles/common/handlers/main.yml - name: restart ntpd - service: name=ntpd state=restarted + service: + name: ntpd + state: restarted See :doc:`playbooks_reuse_roles` for more information. @@ -383,16 +392,17 @@ This makes a dynamic group of hosts matching certain criteria, even if that grou --- - # talk to all hosts just so we can learn about them - - hosts: all - tasks: - - group_by: key=os_{{ ansible_distribution }} + # talk to all hosts just so we can learn about them + - hosts: all + tasks: + - group_by: + key: os_{{ ansible_distribution }} - # now just on the CentOS hosts... + # now just on the CentOS hosts... - - hosts: os_CentOS - gather_facts: False - tasks: + - hosts: os_CentOS + gather_facts: False + tasks: - # tasks that only happen on CentOS go here This will throw all systems into a dynamic group based on the operating system name. @@ -415,7 +425,8 @@ Alternatively, if only variables are needed:: - hosts: all tasks: - include_vars: "os_{{ ansible_distribution }}.yml" - - debug: var=asdf + - debug: + var: asdf This will pull in variables based on the OS name. diff --git a/docs/docsite/rst/playbooks_checkmode.rst b/docs/docsite/rst/playbooks_checkmode.rst index 3b37769a60c..6123e0c6fad 100644 --- a/docs/docsite/rst/playbooks_checkmode.rst +++ b/docs/docsite/rst/playbooks_checkmode.rst @@ -39,15 +39,17 @@ Instead of ``yes``/``no`` you can use a Jinja2 expression, just like the ``when` Example:: - tasks: + tasks: + - name: this task will make changes to the system even in check mode + command: /something/to/run --even-in-check-mode + check_mode: no - - name: this task will make changes to the system even in check mode - command: /something/to/run --even-in-check-mode - check_mode: no - - - name: this task will always run under checkmode and not change the system - lineinfile: line="important config" dest=/path/to/myconfig.conf state=present - check_mode: yes + - name: this task will always run under checkmode and not change the system + lineinfile: + line: "important config" + dest: /path/to/myconfig.conf + state: present + check_mode: yes Running single tasks with ``check_mode: yes`` can be useful to write tests for @@ -67,17 +69,20 @@ which will be set to ``True`` during check mode. Example:: - tasks: - - - name: this task will be skipped in check mode - git: repo=ssh://git@github.com/mylogin/hello.git dest=/home/mylogin/hello - when: not ansible_check_mode - - name: this task will ignore errors in check mode - git: repo=ssh://git@github.com/mylogin/hello.git dest=/home/mylogin/hello - ignore_errors: "{{ ansible_check_mode }}" + tasks: + - name: this task will be skipped in check mode + git: + repo: ssh://git@github.com/mylogin/hello.git + dest: /home/mylogin/hello + when: not ansible_check_mode + - name: this task will ignore errors in check mode + git: + repo: ssh://git@github.com/mylogin/hello.git + dest: /home/mylogin/hello + ignore_errors: "{{ ansible_check_mode }}" .. _diff_mode: