1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
|
.. _contributing_maintained_collections:
***********************************************
Contributing to Ansible-maintained Collections
***********************************************
The Ansible team welcomes community contributions to the collections maintained by Red Hat Ansible Engineering. This section describes how you can open issues and create PRs with the required testing before your PR can be merged.
.. contents::
:local:
Ansible-maintained collections
=================================
The following table shows:
* **Ansible-maintained collection** - Click the link to the collection on Galaxy, then click the ``repo`` button in Galaxy to find the GitHub repository for this collection.
* **Related community collection** - Collection that holds community-created content (modules, roles, and so on) that may also be of interest to a user of the Ansible-maintained collection. You can, for example, add new modules to the community collection as a technical preview before the content is moved to the Ansible-maintained collection.
* **Sponsor** - Working group that manages the collections. You can join the meetings to discuss important proposed changes and enhancements to the collections.
* **Test requirements** - Testing required for any new or changed content for the Ansible-maintained collection.
* **Developer details** - Describes whether the Ansible-maintained collection accepts direct community issues and PRs for existing collection content, as well as more specific developer guidelines based on the collection type.
.. _ansible-collection-table:
.. raw:: html
<style>
/* Style for this single table. Add delimiters between header columns */
table#ansible-collection-table th {
border-width: 1px;
border-color: #dddddd /*rgb(225, 228, 229)*/;
border-style: solid;
text-align: center;
padding: 5px;
background-color: #eeeeee;
}
tr, td {
border-width: 1px;
border-color: rgb(225, 228, 229);
border-style: solid;
text-align: center;
padding: 5px;
}
</style>
<table id="ansible-collection-table">
<tr>
<th colspan="3">Collection details</th>
<th colspan="4">Test requirements: Ansible collections</th>
<th colspan="2">Developer details</th>
</tr>
<tr>
<th>Ansible collection</th>
<th>Related community collection</th>
<th>Sponsor</th>
<th>Sanity</th>
<th>Unit</th>
<th>Integration</th>
<th>CI Platform</th>
<th>Open to PRs*</th>
<th>Guidelines</th>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/amazon/aws">amazon.aws</a></td>
<td><a href="https://galaxy.ansible.com/community/aws">community.aws</a></td>
<td><a href="https://github.com/ansible/community/tree/main/group-aws">AWS</a></td>
<td>✓**</td>
<td>**</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/dev_guide/platforms/aws_guidelines.html">AWS guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/ansible/netcommon">ansible.netcommon***</a></td>
<td><a href="https://galaxy.ansible.com/community/network">community.network</a></td>
<td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/ansible/posix">ansible.posix</a></td>
<td><a href="https://galaxy.ansible.com/community/general">community.general</a></td>
<td>Linux</a></td>
<td>✓</td>
<td></td>
<td></td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/latest/dev_guide/index.html">Developer guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/ansible/windows">ansible.windows</a></td>
<td><a href="https://galaxy.ansible.com/community/windows">community.windows</a></td>
<td><a href="https://github.com/ansible/community/wiki/Windows">Windows</a></td>
<td>✓</td>
<td>✓****</td>
<td>✓</td>
<td>Azure Pipelines and Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_general_windows.html#developing-modules-general-windows">Windows guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/arista/eos">arista.eos</a></td>
<td><a href="https://galaxy.ansible.com/community/network">community.network</a></td>
<td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/cisco/asa">cisco.asa</a></td>
<td><a href="https://github.com/ansible-collections/community.asa">community.asa</a></td>
<td><a href="https://github.com/ansible/community/wiki/Security-Automation">Security</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/latest/dev_guide/index.html">Developer guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/cisco/ios">cisco.ios</a></td>
<td><a href="https://galaxy.ansible.com/community/network">community.network</a></td>
<td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/cisco/iosxr">cisco.iosxr</a></td>
<td><a href="https://galaxy.ansible.com/community/network">community.network</a></td>
<td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/cisco/nxos">cisco.nxos</a></td>
<td><a href="https://galaxy.ansible.com/community/network">community.network</a></td>
<td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/ibm/qradar">ibm.qradar</a></td>
<td><a href="https://github.com/ansible-collections/community.qradar">community.qradar</a></td>
<td><a href="https://github.com/ansible/community/wiki/Security-Automation">Security</a></td>
<td>✓</td>
<td></td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/latest/dev_guide/index.html">Developer guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/junipernetworks/junos">junipernetworks.junos</a></td>
<td><a href="https://galaxy.ansible.com/community/network">community.network</a></td>
<td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/kubernetes/core">kubernetes.core</a></td>
<td><a href="https://galaxy.ansible.com/kubernetes/core">kubernetes.core</a></td>
<td><a href="https://github.com/ansible/community/wiki/Kubernetes">Kubernetes</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>GitHub Actions</td>
<td>✓</td>
<td></td>
</tr>
<tr>
<td><a href="https://cloud.redhat.com/ansible/automation-hub/redhat/openshift">redhat.openshift</a></td>
<td><a href="https://galaxy.ansible.com/community/okd">community.okd</a></td>
<td><a href="https://github.com/ansible/community/wiki/Kubernetes">Kubernetes</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>GitHub Actions</td>
<td>✓</td>
<td></td>
<tr>
<td><a href="https://galaxy.ansible.com/openvswitch/openvswitch">openvswitch.openvswitch</a></td>
<td><a href="https://galaxy.ansible.com/community/network">community.network</a></td>
<td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td>
</tr>
<tr>
<td><a href="https://github.com/ansible-collections/splunk.es">splunk.es</a></td>
<td><a href="https://github.com/ansible-collections/community.es">community.es</a></td>
<td><a href="https://github.com/ansible/community/wiki/Security-Automation">Security</a></td>
<td>✓</td>
<td></td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/latest/dev_guide/index.html">Developer guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/vyos/vyos">vyos.vyos</a></td>
<td><a href="https://galaxy.ansible.com/community/network">community.network</a></td>
<td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td>
</tr>
<tr>
<td><a href="https://galaxy.ansible.com/vmware/vmware_rest">vmware.vmware_rest</a></td>
<td><a href="https://galaxy.ansible.com/vmware/vmware_rest">vmware.vmware_rest</a></td>
<td><a href="https://github.com/ansible/community/wiki/VMware">VMware</a></td>
<td>✓</td>
<td>✓</td>
<td>✓</td>
<td>Zuul</td>
<td>✓</td>
<td><a href="https://docs.ansible.com/ansible/devel/dev_guide/platforms/vmware_rest_guidelines.html">VMware REST guide</a></td>
</tr>
</table>
.. note::
\* A ✓ under **Open to PRs** means the collection welcomes GitHub issues and PRs for any changes to existing collection content (plugins, roles, and so on).
\*\* Integration tests are required and unit tests are welcomed but not required for the AWS collections. An exception to this is made in cases where integration tests are logistically not feasible due to external requirements. An example of this is AWS Direct Connect, as this service can not be functionally tested without the establishment of network peering connections. Unit tests are therefore required for modules that interact with AWS Direct Connect. Exceptions to ``amazon.aws`` must be approved by Red Hat, and exceptions to ``community.aws`` must be approved by the AWS community.
\*\*\* ``ansible.netcommon`` contains all foundational components for enabling many network and security :ref:`platform <platform_options>` collections. It contains all connection and filter plugins required, and installs as a dependency when you install the platform collection.
\*\*\*\* Unit tests for Windows PowerShell modules are an exception to testing, but unit tests are valid and required for the remainder of the collection, including Ansible-side plugins.
.. _which_collection:
Deciding where your contribution belongs
=========================================
We welcome contributions to Ansible-maintained collections. Because these collections are part of a downstream supported Red Hat product, the criteria for contribution, testing, and release may be higher than other community collections. The related community collections (such as ``community.general`` and ``community.network``) have less-stringent requirements and are a great place for new functionality that may become part of the Ansible-maintained collection in a future release.
The following scenarios use the ``arista.eos`` to help explain when to contribute to the Ansible-maintained collection, and when to propose your change or idea to the related community collection:
1. You want to fix a problem in the ``arista.eos`` Ansible-maintained collection. Create the PR directly in the `arista.eos collection GitHub repository <https://github.com/ansible-collections/arista.eos>`_. Apply all the :ref:`merge requirements <ansible_collection_merge_requirements>`.
2. You want to add a new Ansible module for Arista. Your options are one of the following:
* Propose a new module in the ``arista.eos`` collection (requires approval from Arista and Red Hat).
* Propose a new collection in the ``arista`` namespace (requires approval from Arista and Red Hat).
* Propose a new module in the ``community.network`` collection (requires network community approval).
* Place your new module in a collection in your own namespace (no approvals required).
Most new content should go into either a related community collection or your own collection first so that is well established in the community before you can propose adding it to the ``arista`` namespace, where inclusion and maintenance criteria are much higher.
.. _ansible_collection_merge_requirements:
Requirements to merge your PR
==============================
Your PR must meet the following requirements before it can merge into an Ansible-maintained collection:
#. The PR is in the intended scope of the collection. Communicate with the appropriate Ansible sponsor listed in the :ref:`Ansible-maintained collection table <ansible-collection-table>` for help.
#. For network and security domains, the PR follows the :ref:`resource module development principles <developing_resource_modules>`.
#. Passes :ref:`sanity tests and tox <tox_resource_modules>`.
#. Passes unit, and integration tests, as listed in the :ref:`Ansible-maintained collection table <ansible-collection-table>` and described in :ref:`testing_resource_modules`.
#. Follows Ansible guidelines. See :ref:`developing_modules` and :ref:`developing_collections`.
#. Addresses all review comments.
#. Includes an appropriate :ref:`changelog <community_changelogs>`.
|
