diff options
authorZuul <>2019-02-05 17:14:35 +0000
committerGerrit Code Review <>2019-02-05 17:14:35 +0000
commitbc5372817b5802a65fe74aa3cdba51013732eb1c (patch)
parent4f71cfa8494ea68ac2d4b922a7faa0dc3213d288 (diff)
parent00bf7b806a09d4bf86a1c2901a676a983b71e692 (diff)
Merge "Propose some job writing guidelines"
1 files changed, 104 insertions, 2 deletions
diff --git a/doc/source/policy.rst b/doc/source/policy.rst
index ef92aac..1c28545 100644
--- a/doc/source/policy.rst
+++ b/doc/source/policy.rst
@@ -52,8 +52,11 @@ Library code should be written to be compatible with both. There are
52some tips on this in `Ansible and Python 3 52some tips on this in `Ansible and Python 3
53<>`__. 53<>`__.
54 54
55Coding guidelines
55Role Variable Naming Policy 58Role Variable Naming Policy
56--------------------------- 59***************************
57 60
58Variables referenced by roles from global scope (often intended to be 61Variables referenced by roles from global scope (often intended to be
59set via ``host_vars`` and ``group_vars``, but also set during role 62set via ``host_vars`` and ``group_vars``, but also set during role
@@ -70,6 +73,106 @@ as ``example_role_variable``; e.g.
70 vars: 73 vars:
71 example_role_variable: 'something' 74 example_role_variable: 'something'
72 75
76Support for Multiple Operating Systems
79Ideally, roles should be able to run regardless of the OS or the distribution
80flavor of the host. A role can target a specific OS or distribution; in that case
81it should be mentioned in the role's documentation and start with a `fail` task
82if the host does not match the intended environment:
84.. code-block:: YAML
86 tasks:
87 - name: Make sure the role is run on XXX version Y
88 fail:
89 msg: "This role supports XXX version Y only"
90 when:
91 - ansible_distribution != "XXX"
92 - ansible_distribution_major_version != "Y"
94Here are a few guidelines to help make roles OS-independent when possible:
96* Use the **package** module instead of **yum**, **apt** or other
97 distribution-specific commands.
98* If more than one specific task is needed for a specific OS, these tasks should
99 be stored in a separate YAML file in a `distros` subdirectory and named after
100 the specific flavor they target. The following boilerplate code can be used to
101 target specific flavors:
103.. code-block:: YAML
105 tasks:
106 - name: Execute distro-specific tasks
107 include_tasks: "{{ lookup('first_found', params) }}"
108 vars:
109 params:
110 files:
111 - "mytasks-{{ ansible_distribution }}.{{ ansible_distribution_major_version }}.{{ ansible_architecture }}.yaml"
112 - "mytasks-{{ ansible_distribution }}.{{ ansible_distribution_major_version }}.yaml"
113 - "mytasks-{{ ansible_distribution }}.yaml"
114 - "mytasks-{{ ansible_os_family }}.yaml"
115 - "mytasks-default.yaml"
116 paths:
117 - distros
119If run on Fedora 29 x86_64, this playbook will attempt to include the first
120playbook found among
122* `distros/mytasks-Fedora.29.x86_64.yaml`
123* `distros/mytasks-Fedora.29.yaml`
124* `distros/mytasks-Fedora.yaml`
125* `distros/mytasks-RedHat.yaml`
126* `distros/mytasks-default.yaml`
128The default playbook should return a failure explaining the host's environment is
129not supported, or a skip if the tasks were optional.
131Handling privileges on hosts
134Zuul offers great freedom in the types and configurations of hosts on which roles
135are run. Therefore roles should not assume the amount of privileges they will be
136granted on hosts. Some settings may not allow any form of privilege escalation,
137meaning that some tasks such as installing packages will fail.
139In order to make a role available to as many hosts as possible, it is good practice
140to avoid privilege escalations:
142* Do not use ``become: yes`` in tasks, unless necessary
143* If installing software is required, favor software deployments in user land,
144 like virtualenvs, if possible.
145* Check before executing a task requiring privilege escalation is actually
146 needed (e.g. is the package to install already present, or is the firewall
147 rule already set), and make the task skippable if its effects were already
148 applied to the host.
150If privilege escalation is unavoidable, this should be mentioned in the role's
151documentation so that operators can choose or set up their hosts accordingly.
152If relevant, the specific steps where the privilege escalation occurs should be
153documented so that they can be reproduced when configuring hosts. If possible,
154they should be grouped in a separate playbook that can be applied to hosts manually.
156Installing Dependencies in Roles
159Roles should be self-sufficient. This makes it sometimes necessary to pull dependencies
160within a role, in order to execute a task. Since this is usually an action
161requiring elevated privileges on the host, the guidelines in the previous
162paragraph apply. Again, ideally all the installation tasks should be grouped in
163a separate playbook.
165Here are the ways to install dependencies in order of preference:
167* Use the **package** module to install packages
168* Manage dependencies with `bindep <>`__
169 and the `bindep` role.
170* Use OS-specific tasks like **apt**, **yum** etc. to support as many OSes as
171 possible.
173In any case, the role's documentation should mention which dependencies are
174needed, allowing users to prepare their hosts accordingly.
73Testing 176Testing
74------- 177-------
75 178
@@ -108,4 +211,3 @@ which is how it should remain until the next proposed change.
108 211
109.. _zuul-announce: 212.. _zuul-announce:
110.. _zuul-discuss: 213.. _zuul-discuss: