diff options
| -rw-r--r-- | docs/docsite/rst/dev_guide/developing_modules_documenting.rst | 18 | ||||
| -rw-r--r-- | docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst | 106 | ||||
| -rw-r--r-- | docs/docsite/rst/dev_guide/shared_snippets/licensing.txt | 3 | ||||
| -rw-r--r-- | docs/docsite/rst/plugins/inventory.rst | 29 | ||||
| -rw-r--r-- | docs/docsite/rst/reference_appendices/python_3_support.rst | 4 | ||||
| -rw-r--r-- | docs/docsite/rst/reference_appendices/release_and_maintenance.rst | 2 | ||||
| -rw-r--r-- | lib/ansible/modules/apt_key.py | 12 | ||||
| -rw-r--r-- | lib/ansible/modules/apt_repository.py | 12 | ||||
| -rw-r--r-- | lib/ansible/modules/dpkg_selections.py | 5 | ||||
| -rw-r--r-- | lib/ansible/modules/stat.py | 4 | ||||
| -rw-r--r-- | lib/ansible/plugins/become/runas.py | 2 | ||||
| -rw-r--r-- | lib/ansible/plugins/become/su.py | 2 | ||||
| -rw-r--r-- | lib/ansible/plugins/become/sudo.py | 2 |
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: |