Browse Source

Propose some job writing guidelines

In order to see more consistency and good practices in zuul-jobs,
suggest some guidelines regarding OS and containers support, and
dealing with roles dependencies.

Change-Id: Iad001766a56833094ac8703fca11559265b6f914
changes/07/631507/3
mhuin 6 months ago
parent
commit
00bf7b806a
1 changed files with 104 additions and 2 deletions
  1. 104
    2
      doc/source/policy.rst

+ 104
- 2
doc/source/policy.rst View File

@@ -52,8 +52,11 @@ Library code should be written to be compatible with both.  There are
52 52
 some tips on this in `Ansible and Python 3
53 53
 <https://docs.ansible.com/ansible/2.5/dev_guide/developing_python_3.html>`__.
54 54
 
55
+Coding guidelines
56
+-----------------
57
+
55 58
 Role Variable Naming Policy
56
----------------------------
59
+***************************
57 60
 
58 61
 Variables referenced by roles from global scope (often intended to be
59 62
 set via ``host_vars`` and ``group_vars``, but also set during role
@@ -70,6 +73,106 @@ as ``example_role_variable``; e.g.
70 73
       vars:
71 74
         example_role_variable: 'something'
72 75
 
76
+Support for Multiple Operating Systems
77
+**************************************
78
+
79
+Ideally, roles should be able to run regardless of the OS or the distribution
80
+flavor of the host. A role can target a specific OS or distribution; in that case
81
+it should be mentioned in the role's documentation and start with a `fail` task
82
+if 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
+
94
+Here 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
+
119
+If run on Fedora 29 x86_64, this playbook will attempt to include the first
120
+playbook 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
+
128
+The default playbook should return a failure explaining the host's environment is
129
+not supported, or a skip if the tasks were optional.
130
+
131
+Handling privileges on hosts
132
+****************************
133
+
134
+Zuul offers great freedom in the types and configurations of hosts on which roles
135
+are run. Therefore roles should not assume the amount of privileges they will be
136
+granted on hosts. Some settings may not allow any form of privilege escalation,
137
+meaning that some tasks such as installing packages will fail.
138
+
139
+In order to make a role available to as many hosts as possible, it is good practice
140
+to 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
+
150
+If privilege escalation is unavoidable, this should be mentioned in the role's
151
+documentation so that operators can choose or set up their hosts accordingly.
152
+If relevant, the specific steps where the privilege escalation occurs should be
153
+documented so that they can be reproduced when configuring hosts. If possible,
154
+they should be grouped in a separate playbook that can be applied to hosts manually.
155
+
156
+Installing Dependencies in Roles
157
+********************************
158
+
159
+Roles should be self-sufficient.  This makes it sometimes necessary to pull dependencies
160
+within a role, in order to execute a task. Since this is usually an action
161
+requiring elevated privileges on the host, the guidelines in the previous
162
+paragraph apply. Again, ideally all the installation tasks should be grouped in
163
+a separate playbook.
164
+
165
+Here 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
+
173
+In any case, the role's documentation should mention which dependencies are
174
+needed, allowing users to prepare their hosts accordingly.
175
+
73 176
 Testing
74 177
 -------
75 178
 
@@ -108,4 +211,3 @@ which is how it should remain until the next proposed change.
108 211
 
109 212
 .. _zuul-announce: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-announce
110 213
 .. _zuul-discuss: http://lists.zuul-ci.org/cgi-bin/mailman/listinfo/zuul-discuss
111
-

Loading…
Cancel
Save