summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZuul <zuul@review.openstack.org>2019-02-05 17:14:35 +0000
committerGerrit Code Review <review@openstack.org>2019-02-05 17:14:35 +0000
commitbc5372817b5802a65fe74aa3cdba51013732eb1c (patch)
treea0c0af1214e0e13f79090feb4e906b5c745a7522
parent4f71cfa8494ea68ac2d4b922a7faa0dc3213d288 (diff)
parent00bf7b806a09d4bf86a1c2901a676a983b71e692 (diff)
Merge "Propose some job writing guidelines"
-rw-r--r--doc/source/policy.rst106
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<https://docs.ansible.com/ansible/2.5/dev_guide/developing_python_3.html>`__. 53<https://docs.ansible.com/ansible/2.5/dev_guide/developing_python_3.html>`__.
54 54
55Coding guidelines
56-----------------
57
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
77**************************************
78
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:
83
84.. code-block:: YAML
85
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"
93
94Here are a few guidelines to help make roles OS-independent when possible:
95
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:
102
103.. code-block:: YAML
104
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
118
119If run on Fedora 29 x86_64, this playbook will attempt to include the first
120playbook found among
121
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`
127
128The default playbook should return a failure explaining the host's environment is
129not supported, or a skip if the tasks were optional.
130
131Handling privileges on hosts
132****************************
133
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.
138
139In order to make a role available to as many hosts as possible, it is good practice
140to avoid privilege escalations:
141
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.
149
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.
155
156Installing Dependencies in Roles
157********************************
158
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.
164
165Here are the ways to install dependencies in order of preference:
166
167* Use the **package** module to install packages
168* Manage dependencies with `bindep <https://docs.openstack.org/infra/bindep/readme.html>`__
169 and the `bindep` role.
170* Use OS-specific tasks like **apt**, **yum** etc. to support as many OSes as
171 possible.
172
173In any case, the role's documentation should mention which dependencies are
174needed, allowing users to prepare their hosts accordingly.
175
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: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-announce 212.. _zuul-announce: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-announce
110.. _zuul-discuss: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-discuss 213.. _zuul-discuss: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-discuss
111