summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/docsite/rst/dev_guide/developing_modules_documenting.rst18
-rw-r--r--docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst106
-rw-r--r--docs/docsite/rst/dev_guide/shared_snippets/licensing.txt3
-rw-r--r--docs/docsite/rst/plugins/inventory.rst29
-rw-r--r--docs/docsite/rst/reference_appendices/python_3_support.rst4
-rw-r--r--docs/docsite/rst/reference_appendices/release_and_maintenance.rst2
-rw-r--r--lib/ansible/modules/apt_key.py12
-rw-r--r--lib/ansible/modules/apt_repository.py12
-rw-r--r--lib/ansible/modules/dpkg_selections.py5
-rw-r--r--lib/ansible/modules/stat.py4
-rw-r--r--lib/ansible/plugins/become/runas.py2
-rw-r--r--lib/ansible/plugins/become/su.py2
-rw-r--r--lib/ansible/plugins/become/sudo.py2
13 files changed, 73 insertions, 128 deletions
diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
index c8f37e4a8d..9bd9cbd461 100644
--- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
+++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
@@ -33,28 +33,24 @@ Begin your Ansible module with ``#!/usr/bin/python`` - this "shebang" allows ``a
Copyright and license
=====================
-After the shebang and UTF-8 coding, add a `copyright line <https://www.gnu.org/licenses/gpl-howto.en.html>`_ with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:
+After the shebang and UTF-8 coding, add a `copyright line <https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/>`_ with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:
.. code-block:: python
#!/usr/bin/python
# -*- coding: utf-8 -*-
- # Copyright: (c) 2018, Terry Jones <terry.jones@example.org>
+ # Copyright: Contributors to the Ansible project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-Major additions to the module (for instance, rewrites) may add additional copyright lines. Any legal review will include the source control history, so an exhaustive copyright header is not necessary.
-Please do not edit the existing copyright year. This simplifies project administration and is unlikely to cause any interesting legal issues.
-When adding a second copyright line for a significant feature or rewrite, add the newer line above the older one:
+Additions to the module (for instance, rewrites) are not permitted to add additional copyright lines other than the default copyright statement if missing:
.. code-block:: python
- #!/usr/bin/python
- # -*- coding: utf-8 -*-
-
- # Copyright: (c) 2017, [New Contributor(s)]
- # Copyright: (c) 2015, [Original Contributor(s)]
- # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+ # Copyright: Contributors to the Ansible project
+
+Any legal review will include the source control history, so an exhaustive copyright header is not necessary.
+Please do not include a copyright year. If the existing copyright statement includes a year, do not edit the existing copyright year. Any existing copyright header should not be modified without permission from the copyright author.
.. _ansible_metadata_block:
diff --git a/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst
index db35559a22..c176dfdbc3 100644
--- a/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst
+++ b/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst
@@ -4,108 +4,4 @@
Guidelines for VMware REST module development
*********************************************
-The Ansible VMware REST collection (on `Galaxy <https://galaxy.ansible.com/vmware/vmware_rest>`_, source code `repository <https://github.com/ansible-collections/vmware.vmware_rest>`_) is maintained by Red Hat and the community.
-
-.. contents::
- :local:
-
-Contribution process
-====================
-
-The modules of the vmware_rest collection are autogenerated by another tool called `vmware_rest_code_generator <https://github.com/ansible-collections/vmware_rest_code_generator>`.
-
-If you would like to contribute a change, we would appreciate if you:
-
-- submit a Github Pull Request (PR) against the vmware_rest_code_generator project
-- but also ensure the generated modules are compliant with our quality criteria.
-
-Requirements
-============
-
-You will need:
-
-- Python 3.6 or greater
-- the `tox <https://tox.readthedocs.io/en/latest/install.html>` command
-
-
-vmware_rest_code_generator
-==========================
-
-Your contribution should follow the coding style of `Black <https://github.com/psf/black>`.
-To run the code formatter, just run:
-
-.. code-block:: shell
-
- tox -e black
-
-To regenerate the vmware_rest collection, you can use the following commands:
-
-.. code-block:: shell
-
- tox -e refresh_modules -- --target-dir ~/.ansible/collections/ansible_collections/vmware/vmware_rest
-
-If you also want to update the EXAMPLE section of the modules, run:
-
-.. code-block:: shell
-
- tox -e refresh_examples -- --target-dir ~/.ansible/collections/ansible_collections/vmware/vmware_rest
-
-Testing with ansible-test
-=========================
-
-All the modules are covered by a functional test. The tests are located in the :file:`tests/integration/targets/`.
-
-To run the tests, you will need a vcenter instance and an ESXi.
-
-black code formatter
-^^^^^^^^^^^^^^^^^^^^
-
-We follow the coding style of `Black <https://github.com/psf/black>`.
-You can run the code formatter with the following command.
-
-
-.. code-block:: shell
-
- tox -e black
-
-sanity tests
-^^^^^^^^^^^^
-
-Here we use Python 3.8, the minimal version is 3.6.
-
-.. code-block:: shell
-
- tox -e black
- ansible-test sanity --debug --requirements --local --skip-test future-import-boilerplate --skip-test metaclass-boilerplate --python 3.8 -vvv
-
-
-integration tests
-^^^^^^^^^^^^^^^^^
-
-These tests should be run against your test environment.
-
-..warning:: The test suite will delete all the existing DC from your test environment.
-
-First, prepare a configuration file, we call it :file:`/tmp/inventory-vmware_rest` in
-this example:
-
-.. code-block:: ini
-
- [vmware_rest]
- localhost ansible_connection=local ansible_python_interpreter=python
-
- [vmware_rest:vars]
- vcenter_hostname=vcenter.test
- vcenter_username=administrator@vsphere.local
- vcenter_password=kLRy|FXwZSHXW0w?Q:sO
- esxi1_hostname=esxi1.test
- esxi1_username=zuul
- esxi1_password=f6QYNi65k05kv8m56
-
-
-To run the tests, use the following command. You may want to adjust the Python version.
-
-.. code-block:: shell
-
- ansible-test network-integration --diff --no-temp-workdir --python 3.8 --inventory /tmp/inventory-vmware_rest zuul/
-
+This guide has moved to :ref:`ansible_collections.vmware.vmware_rest.docsite.vmware_rest_devguide`.
diff --git a/docs/docsite/rst/dev_guide/shared_snippets/licensing.txt b/docs/docsite/rst/dev_guide/shared_snippets/licensing.txt
index 2802c4202e..d4b3051f98 100644
--- a/docs/docsite/rst/dev_guide/shared_snippets/licensing.txt
+++ b/docs/docsite/rst/dev_guide/shared_snippets/licensing.txt
@@ -7,3 +7,6 @@
* All other ``module_utils`` must be licensed under BSD, so GPL-licensed third-party and Galaxy modules can use them.
* If there's doubt about the appropriate license for a file in ``module_utils``, the Ansible Core Team will decide during an Ansible Core Community Meeting.
* All other files shipped with Ansible, including all modules, must be licensed under the GPL license (GPLv3 or later).
+ * Existing license requirements still apply to content in ansible/ansible (ansible-core).
+ * Content that was previously in ansible/ansible or a collection and has moved to a new collection must retain the license it had in its prior repository.
+ * Copyright entries by previous committers must also be kept in any moved files.
diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst
index 8e2ade376a..3328af62e4 100644
--- a/docs/docsite/rst/plugins/inventory.rst
+++ b/docs/docsite/rst/plugins/inventory.rst
@@ -23,13 +23,20 @@ In some circumstances, for example, if the inventory plugin does not use a YAML
[inventory]
enable_plugins = host_list, script, auto, yaml, ini, toml
-If the plugin is in a collection, use the fully qualified name:
+If the plugin is in a collection and is not being picked up by the `auto` statement, you can append the fully qualified name:
.. code-block:: ini
[inventory]
- enable_plugins = namespace.collection_name.inventory_plugin_name
+ enable_plugins = host_list, script, auto, yaml, ini, toml, namespace.collection_name.inventory_plugin_name
+Or, if it is a local plugin, perhaps stored in the path set by :ref:`DEFAULT_INVENTORY_PLUGIN_PATH`, you could reference it as follows:
+
+.. code-block:: ini
+
+ [inventory]
+ enable_plugins = host_list, script, auto, yaml, ini, toml, my_plugin
+
If you use a plugin that supports a YAML configuration source, make sure that the name matches the name provided in the ``plugin`` entry of the inventory source file.
.. _using_inventory:
@@ -80,12 +87,24 @@ You can create dynamic groups using host variables with the constructed ``keyed_
- key: tags.Name
prefix: tag_Name_
separator: ""
+ # If you have a tag called "Role" which has the value "Webserver", this will add the group
+ # role_Webserver and add any hosts that have that tag assigned to it.
+ - key: tags.Role
+ prefix: role
groups:
# add hosts to the group development if any of the dictionary's keys or values is the word 'devel'
development: "'devel' in (tags|list)"
+ # add hosts to the "private_only" group if the host doesn't have a public IP associated to it
+ private_only: "public_ip_address is not defined"
compose:
- # set the ansible_host variable to connect with the private IP address without changing the hostname
- ansible_host: private_ip_address
+ # use a private address where a public one isn't assigned
+ ansible_host: public_ip_address|default(private_ip_address)
+ # alternatively, set the ansible_host variable to connect with the private IP address without changing the hostname
+ # ansible_host: private_ip_address
+ # if you *must* set a string here (perhaps to identify the inventory source if you have multiple
+ # accounts you want to use as sources), you need to wrap this in two sets of quotes, either ' then "
+ # or " then '
+ some_inventory_wide_string: '"Yes, you need both types of quotes here"'
Now the output of ``ansible-inventory -i demo.aws_ec2.yml --graph``:
@@ -99,6 +118,8 @@ Now the output of ``ansible-inventory -i demo.aws_ec2.yml --graph``:
|--@development:
| |--ec2-12-345-678-901.compute-1.amazonaws.com
| |--ec2-98-765-432-10.compute-1.amazonaws.com
+ |--@role_Webserver
+ | |--ec2-12-345-678-901.compute-1.amazonaws.com
|--@tag_Name_ECS_Instance:
| |--ec2-98-765-432-10.compute-1.amazonaws.com
|--@tag_Name_Test_Server:
diff --git a/docs/docsite/rst/reference_appendices/python_3_support.rst b/docs/docsite/rst/reference_appendices/python_3_support.rst
index da06023c1a..4471c64714 100644
--- a/docs/docsite/rst/reference_appendices/python_3_support.rst
+++ b/docs/docsite/rst/reference_appendices/python_3_support.rst
@@ -52,11 +52,11 @@ Using Python 3 on the managed machines with commands and playbooks
localhost-py3 ansible_host=localhost ansible_connection=local ansible_python_interpreter=/usr/bin/python3
# Example of setting a group of hosts to use Python3
- [py3-hosts]
+ [py3_hosts]
ubuntu16
fedora27
- [py3-hosts:vars]
+ [py3_hosts:vars]
ansible_python_interpreter=/usr/bin/python3
.. seealso:: :ref:`intro_inventory` for more information.
diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
index 649f938b19..8fa16d21d3 100644
--- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
+++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
@@ -82,7 +82,7 @@ Ansible Community Package Release Status Core ver
================================== ============================ =========================
7.0.0 In development (unreleased) 2.14
`6.x Changelogs`_ Current 2.13
-`5.x Changelogs`_ Unmaintained/EOL after 5.10 2.12
+`5.x Changelogs`_ Unmaintained (end of life) 2.12
`4.x Changelogs`_ Unmaintained (end of life) 2.11
`3.x Changelogs`_ Unmaintained (end of life) 2.10
`2.10 Changelogs`_ Unmaintained (end of life) 2.10
diff --git a/lib/ansible/modules/apt_key.py b/lib/ansible/modules/apt_key.py
index 29de275de2..884b859542 100644
--- a/lib/ansible/modules/apt_key.py
+++ b/lib/ansible/modules/apt_key.py
@@ -81,6 +81,18 @@ options:
'''
EXAMPLES = '''
+- name: One way to avoid apt_key once it is removed from your distro
+ block:
+ - name: somerepo |no apt key
+ ansible.builtin.get_url:
+ url: https://download.example.com/linux/ubuntu/gpg
+ dest: /etc/apt/trusted.gpg.d/somerepo.asc
+
+ - name: somerepo | apt source
+ ansible.builtin.apt_repository:
+ repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/somerepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
+ state: present
+
- name: Add an apt key by id from a keyserver
ansible.builtin.apt_key:
keyserver: keyserver.ubuntu.com
diff --git a/lib/ansible/modules/apt_repository.py b/lib/ansible/modules/apt_repository.py
index a4b5023af7..ec5a52739f 100644
--- a/lib/ansible/modules/apt_repository.py
+++ b/lib/ansible/modules/apt_repository.py
@@ -131,6 +131,18 @@ EXAMPLES = '''
ansible.builtin.apt_repository:
repo: 'ppa:nginx/stable'
codename: trusty
+
+- name: One way to avoid apt_key once it is removed from your distro
+ block:
+ - name: somerepo |no apt key
+ ansible.builtin.get_url:
+ url: https://download.example.com/linux/ubuntu/gpg
+ dest: /etc/apt/trusted.gpg.d/somerepo.asc
+
+ - name: somerepo | apt source
+ ansible.builtin.apt_repository:
+ repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/somerepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
+ state: present
'''
RETURN = '''#'''
diff --git a/lib/ansible/modules/dpkg_selections.py b/lib/ansible/modules/dpkg_selections.py
index 6d0a1ec855..87cad529b5 100644
--- a/lib/ansible/modules/dpkg_selections.py
+++ b/lib/ansible/modules/dpkg_selections.py
@@ -46,6 +46,11 @@ EXAMPLES = '''
ansible.builtin.dpkg_selections:
name: python
selection: hold
+
+- name: Allow python to be upgraded
+ ansible.builtin.dpkg_selections:
+ name: python
+ selection: install
'''
from ansible.module_utils.basic import AnsibleModule
diff --git a/lib/ansible/modules/stat.py b/lib/ansible/modules/stat.py
index 8c8d5d31b7..ff0f6712a9 100644
--- a/lib/ansible/modules/stat.py
+++ b/lib/ansible/modules/stat.py
@@ -322,12 +322,12 @@ stat:
sample: 50ba294cdf28c0d5bcde25708df53346825a429f
pw_name:
description: User name of owner
- returned: success, path exists and user can read stats and installed python supports it
+ returned: success, path exists, user can read stats, owner name can be looked up and installed python supports it
type: str
sample: httpd
gr_name:
description: Group name of owner
- returned: success, path exists and user can read stats and installed python supports it
+ returned: success, path exists, user can read stats, owner group can be looked up and installed python supports it
type: str
sample: www-data
mimetype:
diff --git a/lib/ansible/plugins/become/runas.py b/lib/ansible/plugins/become/runas.py
index 1913824faa..0b7d466133 100644
--- a/lib/ansible/plugins/become/runas.py
+++ b/lib/ansible/plugins/become/runas.py
@@ -8,7 +8,7 @@ DOCUMENTATION = """
name: runas
short_description: Run As user
description:
- - This become plugins allows your remote/login user to execute commands as another user via the windows runas facility.
+ - This become plugin allows your remote/login user to execute commands as another user via the windows runas facility.
author: ansible (@core)
version_added: "2.8"
options:
diff --git a/lib/ansible/plugins/become/su.py b/lib/ansible/plugins/become/su.py
index 6e54bc336e..3a6fdea23b 100644
--- a/lib/ansible/plugins/become/su.py
+++ b/lib/ansible/plugins/become/su.py
@@ -8,7 +8,7 @@ DOCUMENTATION = """
name: su
short_description: Substitute User
description:
- - This become plugins allows your remote/login user to execute commands as another user via the su utility.
+ - This become plugin allows your remote/login user to execute commands as another user via the su utility.
author: ansible (@core)
version_added: "2.8"
options:
diff --git a/lib/ansible/plugins/become/sudo.py b/lib/ansible/plugins/become/sudo.py
index 778e7afeab..fb285f0027 100644
--- a/lib/ansible/plugins/become/sudo.py
+++ b/lib/ansible/plugins/become/sudo.py
@@ -8,7 +8,7 @@ DOCUMENTATION = """
name: sudo
short_description: Substitute User DO
description:
- - This become plugins allows your remote/login user to execute commands as another user via the sudo utility.
+ - This become plugin allows your remote/login user to execute commands as another user via the sudo utility.
author: ansible (@core)
version_added: "2.8"
options: