From 6d64021d7bee839e98339c8a299ec17a3b49de75 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 29 Mar 2023 17:53:19 -0400 Subject: [PATCH] Backportapalooza 03 29 (#80350) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update special_variables.rst (#80210) The usage of a glossary on this page will allow linking to a specific special variable, like on the glossary page, e.g.: https://docs.ansible.com/ansible/latest/reference_appendices/glossary.html#term-Idempotency (cherry picked from commit 1491ec8019b064374145dace41b1320e04fb494b) * uri: improve force_basic_auth documentation (#80211) Add more details about what "true" and "false" mean for the force_basic_auth setting. Give example scenarios when clients may want to use this setting. (cherry picked from commit fc8203168e964b26478a0f28b0e34d9b34331fde) * Improve dirname and basename filter doc (#80054) (cherry picked from commit 93beef053eabdb6ff2a9823bc8d0d1037671b1e3) * Move Collection requirements to ansible/ansible (#80234) (cherry picked from commit cba395243454b0a959edea20425618fe7b9be775) * Add Ansible community 7.4.0 porting guide (#80338) (cherry picked from commit 29e0a68af251981b97b6c594e52051652ef472d3) * Add antsibull-changelog and antsibull-docs to other tools and programs page. (#80340) (cherry picked from commit cf44c84396ee2afdd0258aed1d09d5eecde94d17) --------- Co-authored-by: Benoît Geeraerts <10222438+b-enoit-be@users.noreply.github.com> Co-authored-by: Ken Dreyer Co-authored-by: Daniel Ziegenberg Co-authored-by: Anwesha Das Co-authored-by: Felix Fontein --- .../collection_requirements.rst | 499 ++++++++++++++++++ .../collection_reviewing.rst | 4 +- .../collection_unit_tests.rst | 2 +- .../community/contributions_collections.rst | 1 + .../rst/community/maintainers_guidelines.rst | 2 +- .../rst/community/maintainers_workflow.rst | 2 +- .../community/other_tools_and_programs.rst | 2 + .../steering/community_steering_committee.rst | 4 +- .../rst/porting_guides/porting_guide_7.rst | 70 +++ .../special_variables.rst | 206 ++++---- docs/docsite/sphinx_conf/core_conf.py | 1 + docs/docsite/sphinx_conf/core_lang_conf.py | 1 + lib/ansible/modules/uri.py | 13 +- lib/ansible/plugins/filter/basename.yml | 4 +- lib/ansible/plugins/filter/dirname.yml | 4 +- 15 files changed, 703 insertions(+), 112 deletions(-) create mode 100644 docs/docsite/rst/community/collection_contributors/collection_requirements.rst diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst new file mode 100644 index 00000000000..bae0f21d37f --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -0,0 +1,499 @@ +.. _collections_requirements: + +************************************************** +Ansible community package collections requirements +************************************************** + +This section describes the requirements for maintainers of Ansible community collections in the `ansible-collections `_ repository or included in the Ansible community package. + +.. contents:: + :local: + + +Overview +======== + +This section provides help, advice, and guidance on making sure your collections are correct and ready for inclusion in the Ansible community package. + +.. note:: + + `Inclusion of a new collection `_ in the Ansible package is ultimately at the discretion of the :ref:`community_steering_committee`. Every rejected candidate will get feedback. Differences of opinion should be taken to a dedicated `Community Topic `_ for discussion and a final vote. + +Feedback and communications +============================== + +As with any project it is very important that we get feedback from users, contributors, and maintainers. You can get feedback and help as follows: + +* Discussing in the `#community:ansible.com Matrix room `_, which is bridged with the ``#ansible-community`` channel on Libera.Chat IRC. See the :ref:`Ansible Communication Guide ` for details. +* Discussing in the `Community Working Group meeting `_. +* Creating `GitHub Issues `_ in the ``ansible-collections`` repository. + +Keeping informed +================ + +You should subscribe to: + +* The `news-for-maintainers repository `_ to track changes that collection maintainers should be aware of. Subscribe only to issues if you want less traffic. +* The `Bullhorn `_ Ansible contributor newsletter. + +.. _coll_infrastructure_reqs: + +Collection infrastructure +========================= + + +The following guidelines describe the required structure for your collection: + +* MUST have a publicly available issue tracker that does not require a paid level of service to create an account or view issues. +* MUST have a Code of Conduct (CoC). + + * The collection's CoC MUST be compatible with the :ref:`code_of_conduct`. + * The collections SHOULD consider using the Ansible CoC if they do not have a CoC that they consider better. + * The :ref:`Diversity and Inclusion working group ` may evaluate all CoCs and object to a collection's inclusion based on the CoCs contents. + * The CoC MUST be linked from the ``README.md`` file, or MUST be present or linked from the ``CODE_OF_CONDUCT.md`` file in the collection root. + +* MUST be published to `Ansible Galaxy `_. +* SHOULD NOT contain any large objects (binaries) comparatively to the current Galaxy tarball size limit of 20 MB, For example, do not include package installers for testing purposes. +* SHOULD NOT contain any unnecessary files such as temporary files. +* MUST only contain objects that follow the :ref:`Licensing rules `. + + +.. _coll_python_compatibility: + +Python Compatibility +==================== + +A collection MUST be developed and tested using the below Python requirements as Ansible supports a wide variety of machines. + +The collection should adhere to the tips at :ref:`ansible-and-python-3`. + +.. _coll_python_reqs: + +Python Requirements +------------------- + +Python requirements for a collection vary between **controller environment** and **other environment**. On the controller-environment, the Python versions required may be higher than what is required on the other-environment. While developing a collection, you need to understand the definitions of both the controller-environment and other-environment to help you choose Python versions accordingly: + +* controller environment: The plugins/modules always run in the same environment (Python interpreter, venv, host, and so on) as ansible-core itself. +* other environment: It is possible, even if uncommon in practice, for the plugins/modules to run in a different environment than ansible-core itself. + +One example scenario where the "even if" clause comes into play is when using cloud modules. These modules mostly run on the controller node but in some environments, the controller might run on one machine inside a demilitarized zone which cannot directly access the cloud machines. The user has to have the cloud modules run on a bastion host/jump server which has access to the cloud machines. + +.. _coll_controller_req: + +Controller environment +~~~~~~~~~~~~~~~~~~~~~~ + +In the controller environment, collections MUST support Python 2 (version 2.7) and Python 3 (Version 3.6 and higher), unless required libraries do not support these versions. Collections SHOULD also support Python v3.5 if all required libraries support this version. + +Other environment +~~~~~~~~~~~~~~~~~ + +In the other environment, collections MUST support Python 2 (version 2.7) and Python 3 (Version 3.6 and higher), unless required libraries do not support these versions. Collections SHOULD also support Python v2.6 and v3.5 if all required libraries support this version. + +.. note:: + + If the collection does not support Python 2.6 and/or Python 3.5 explicitly then take the below points into consideration: + + - Dropping support for Python 2.6 in the other environment means that you are dropping support for RHEL6. RHEL6 ended full support in November, 2020, but some users are still using RHEL6 under extended support contracts (ELS) until 2024. ELS is not full support; not all CVEs of the python-2.6 interpreter are fixed, for instance. + + - Dropping support for Python 3.5 means that Python 2.7 has to be installed on Ubuntu Xenial (16.04) and that you have to support Python 2.7. + + Also, note that dropping support for a Python version for an existing module/plugin is a breaking change, and thus requires a major release. A collection MUST announce dropping support for Python versions in their changelog, if possible in advance (for example, in previous versions before support is dropped). + +.. _coll_python_docs_req: + +Python documentation requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* If everything in your collection supports the same Python versions as the collection-supported versions of ansible-core, you do not need to document Python versions. +* If your collection does not support those Python versions, you MUST document which versions it supports in the README. +* If most of your collection supports the same Python versions as ansible-core, but some modules and plugins do not, you MUST include the supported Python versions in the documentation for those modules and plugins. + +For example, if your collection supports Ansible 2.9 to ansible-core 2.13, the Python versions supported for modules are 2.6, 2.7, and 3.5 and newer (until at least 3.10), while the Python versions supported for plugins are 2.7 and 3.5 and newer (until at least 3.10). So if the modules in your collection do not support Python 2.6, you have to document this in the README, for example ``The content in this collection supports Python 2.7, Python 3.5 and newer.``. + +.. _coll_plugin_standards: + +Standards for developing module and plugin utilities +==================================================== + +* ``module_utils`` and ``plugin_utils`` can be marked for only internal use in the collection, but they MUST document this and MUST use a leading underscore for filenames. +* It is a breaking change when you make an existing ``module_utils`` private and in that case the collection requires a major version bump. +* Below are some recommendations for ``module_utils`` documentation: + + * No docstring: everything we recommend for ``other-environment`` is supported. + * The docstring ``'Python versions supported: same as for controller-environment'``: everything we recommend for ``controller-environment`` is supported. + * The docstring with specific versions otherwise: ``'Python versions supported: '``. + +.. _coll_repo_structure: + +Repository structure requirements +================================== + +galaxy.yml +---------- + +* The ``tags`` field MUST be set. +* Collection dependencies must meet a set of rules. See the section on `Collection Dependencies ` for details. +* The ``ansible`` package MUST NOT depend on collections not shipped in the package. +* If you plan to split up your collection, the new collection MUST be approved for inclusion before the smaller collections replace the larger in Ansible. +* If you plan to add other collections as dependencies, they MUST run through the formal application process. + +.. _coll_readme_req: + +README.md +--------- + +Your collection repository MUST have a ``README.md`` in the root of the collection, see `collection_template/README.md `_ for an example. + +meta/runtime.yml +---------------- +Example: `meta/runtime.yml `_ + +* The ``meta/runtime.yml`` MUST define the minimum version of Ansible which this collection works with. + + * If the collection works with Ansible 2.9, then this should be set to `>=2.9.10` + * It is usually better to avoid adding `<2.11` as a restriction, since this for example makes it impossible to use the collection with the current ansible-base devel branch (which has version 2.11.0.dev0) + +.. _coll_module-reqs: + +Modules & Plugins +------------------ + +* Collections MUST only use the directories specified below in the ``plugins/`` directory and + only for the purposes listed: + + :Those recognized by ansible-core: ``doc_fragments``, ``modules``, ``module_utils``, ``terminal``, and those listed in :ref:`working_with_plugins`. This list can be verified by looking at the last element of the package argument of each ``*_loader`` in https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/loader.py#L1126 + :plugin_utils: For shared code which is only used controller-side, not in modules. + :sub_plugins: For other plugins which are managed by plugins inside of collections instead of ansible-core. We use a subfolder so there aren't conflicts when ansible-core adds new plugin types. + + The core team (which maintains ansible-core) has committed not to use these directories for + anything which would conflict with the uses specified here. + +Other directories +----------------- + +Collections MUST not use files outside ``meta/``, ``plugins/``, ``roles/`` and ``playbooks/`` in any plugin, role, or playbook that can be called by FQCN, used from other collections, or used from user playbooks and roles. A collection must work if every file or directory is deleted from the installed collection except those four directories and their contents. + +Internal plugins, roles and playbooks (artifacts used only in testing, or only to release the collection, or only for some other internal purpose and not used externally) are exempt from this rule and may rely on files in other directories. + +.. _coll_docs_structure_reqs: + +Documentation requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All modules and plugins MUST: + +* Include a :ref:`DOCUMENTATION ` block. +* Include an :ref:`EXAMPLES ` block (except where not relevant for the plugin type). +* Use FQCNs when referring to modules, plugins and documentation fragments inside and outside the collection (including ``ansible.builtin`` for the listed entities from ansible-core. + +When using ``version_added`` in the documentation: + +* Declare the version of the collection in which the options were added -- NOT the version of Ansible. +* If you for some reason really have to specify version numbers of Ansible or of another collection, you also have to provide ``version_added_collection: collection_name``. We strongly recommend to NOT do this. +* Include ``version_added`` when you add new content (modules, plugins, options) to an existing collection. The values are shown in the documentation, and can be useful, but you do not need to add ``version_added`` to every option, module, and plugin when creating a new collection. + +Other items: + +* The ``CONTRIBUTING.md`` (or ``README.md``) file MUST state what types of contributions (pull requests, feature requests, and so on) are accepted and any relevant contributor guidance. Issues (bugs and feature request) reports must always be accepted. +* Collections are encouraged to use z:ref:`links and formatting macros ` +* Including a :ref:`RETURN ` block for modules is strongly encouraged but not required. + +.. _coll_workflow: + +Contributor Workflow +==================== + +.. _coll_changlogs_req: + +Changelogs +---------- + +Collections are required to include a changelog. To give a consistent feel for changelogs across collections and ensure changelogs exist for collections included in the ``ansible`` package we suggest you use `antsibull-changelog `_ to maintain and generate this but other options exist. Preferred (in descending order): + +#. Use antsibull-changelog (preferred). +#. Provide ``changelogs/changelog.yaml`` in the `correct format `_. (You can use ``antsibull-lint changelog-yaml /path/to/changelog.yaml`` to validate the format.) +#. Provide a link to the changelog file (self-hosted) (not recommended). + +Note that the porting guide is compiled from ``changelogs/changelog.yaml`` (sections ``breaking_changes``, ``major_changes``, ``deprecated_features``, ``removed_features``). So if you use option 3, you will not be able to add something to the porting guide. + +.. _coll_versioning_req: + +Versioning and deprecation +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Collections MUST adhere to `semantic versioning `_. +* To preserve backward compatibility for users, every Ansible minor version series (x.Y.z) will keep the major version of a collection constant. If ansible 3.0.0 includes ``community.general`` 2.2.0, then each 3.Y.z (3.1.z, 3.2.z, and so on) release will include the latest ``community.general`` 2.y.z release available at build time. Ansible 3.y.z will **never** include a ``community.general`` 3.y.z release, even if it is available. Major collection version changes will be included in the next Ansible major release (4.0.0 in this example). +* Therefore, ensure that the current major release of your collection included in 3.0.0 receives at least bugfixes as long as new 3.Y.Z releases are produced. +* Since new minor releases are included, you can include new features, modules and plugins. You must make sure that you do not break backwards compatibility! (See `semantic versioning `_.) This means in particular: + + * You can fix bugs in patch releases, but not add new features or deprecate things. + * You can add new features and deprecate things in minor releases, but not remove things or change behavior of existing features. + * You can only remove things or make breaking changes in major releases. +* We recommend that you ensure that if a deprecation is added in a collection version that is included in Ansible 3.y.z, the removal itself will only happen in a collection version included in Ansible 5.0.0 or later, but not in a collection version included in Ansible 4.0.0. +* Content moved from ansible/ansible that was scheduled for removal in 2.11 or later MUST NOT be removed in the current major release available when ansible 2.10.0 is released. Otherwise it would already be removed in 2.10, unexpectedly for users! Deprecation cycles can be shortened (since they are now uncoupled from ansible or ansible-base versions), but existing ones must not be unexpectedly terminated. +* We recommend you announce your policy of releasing, versioning and deprecation to contributors and users in some way. For an example of how to do this, see `the announcement in community.general `_. You could also do this in the README. + +.. _ coll_naming_req: + +Naming +====== + +Collection naming +----------------- + +For collections under ansible-collections the repository SHOULD be named ``NAMESPACE.COLLECTION``. + +To create a new collection and corresponding repository, first, a new namespace in Galaxy has to be created by submitting `Request a namespace `_. + +`Namespace limitations `_ lists requirements for namespaces in Galaxy. + +For collections created for working with a particular entity, they should contain the entity name, for example ``community.mysql``. + +For corporate maintained collections, the repository can be named ``COMPANY_NAME.PRODUCT_NAME``, for example ``ibm.db2``. + +We should avoid FQCN / repository names: + +* which are unnecessary long: try to make it compact but clear. +* contain the same words / collocations in ``NAMESPACE`` and ``COLLECTION`` parts, for example ``my_system.my_system``. + +If your collection is planned to be certified on **Red Hat Automation Hub**, please consult with Red Hat Partner Engineering through ``ansiblepartners@redhat.com`` to ensure collection naming compatibility between the community collection on **Galaxy**. + +.. _coll_module_name_req: + +Module naming +------------- + +Modules that only gather information MUST be named ``_info``. Modules that return ``ansible_facts`` are named ``_facts`` and do not return non-facts. +For more information, refer to the :ref:`Developing modules guidelines `. + +.. _coll_licensing_req: + +Collection licensing requirements +=================================== + +.. note:: + + The guidelines below are more restrictive than strictly necessary. We will try to add a larger list of acceptable licenses once we have approval from Red Hat Legal. + +There are four types of content in collections which licensing has to address in different +ways: + +:modules: must be licensed with a free software license that is compatible with the + `GPL-3.0-or-later `_ +:module_utils: must be licensed with a free software license that is compatible with the + `GPL-3.0-or-later `_. Ansible + itself typically uses the `BSD-2-clause + `_ license to make it possible for + third-party modules which are licensed incompatibly with the GPLv3 to use them. + Please consider this use case when licensing your own ``module_utils``. +:All other code in ``plugins/``: All other code in ``plugins/`` must be under the `GPL-3.0-or-later + `_. These plugins + are run inside of the Ansible controller process which is licensed under + the ``GPL-3.0-or-later`` and often must import code from the controller. + For these reasons, ``GPL-3.0-or-later`` must be used. +:All other code: Code outside ``plugins/`` may be licensed under another free software license that is compatible + with the `GPL-3.0-or-later `_, + provided that such code does not import any other code that is licensed under + the ``GPL-3.0-or-later``. If the file does import other ``GPL-3.0-or-later`` code, + then it must similarly be licensed under ``GPL-3.0-or-later``. Note that this applies in + particular to unit tests; these often import code from ansible-core, plugins, module utils, + or modules, and such code is often licensed under ``GPL-3.0-or-later``. +:Non code content: At the moment, these must also be under the `GPL-3.0-or-later + `_. + +Use `this table of licenses from the Fedora Project +`_ to find which licenses are +compatible with the GPLv3+. The license must be considered open source on both the Fedora License +table and the `Debian Free Software Guidelines `_ to be +allowed. + +These guidelines are the policy for inclusion in the Ansible package and are in addition to any +licensing and legal concerns that may otherwise affect your code. + +.. _coll_repo_management: + +Repository management +===================== + +Every collection MUST have a public git repository. Releases of the collection MUST be tagged in said repository. This means that releases MUST be ``git tag``\ ed and that the tag name MUST exactly match the Galaxy version number. Tag names MAY have a ``v`` prefix, but a collection's tag names MUST have a consistent format from release to release. + +Additionally, collection artifacts released to Galaxy MUST be built from the sources that are tagged in the collection's git repository as that release. Any changes made during the build process MUST be clearly documented so the collection artifact can be reproduced. + +We are open to allowing other SCM software once our tooling supports them. + +.. _coll_branch_config: + +Branch name and configuration +----------------------------- + +This subsection is **only** for repositories under `ansible-collections `_! Other collection repositories can also follow these guidelines, but do not have to. + +All new repositories MUST have ``main`` as the default branch. + +Existing repositories SHOULD be converted to use ``main``. + +Repository Protections: + +* Allow merge commits: disallowed + +Branch protections MUST be enforced: + +* Require linear history +* Include administrators + +.. _coll_ci_tests: + +CI Testing +=========== + +.. note:: + + You can copy the free-to-use `GitHub action workflow file `_ from the `Collection Template repository `_ to the `.github/workflows` directory in your collection to set up testing through GitHub actions. The workflow covers all the requirements below. + +* You MUST run the ``ansible-test sanity`` command from the `latest stable ansible-base/ansible-core branch `_. + + * Collections MUST run an equivalent of the ``ansible-test sanity --docker`` command. + * If they do not use ``--docker``, they must make sure that all tests run, in particular the compile and import tests (which should run for all :ref:`supported Python versions `). + * Collections can choose to skip certain Python versions that they explicitly do not support; this needs to be documented in ``README.md`` and in every module and plugin (hint: use a docs fragment). However we strongly recommend you follow the :ref:`Ansible Python Compatibility ` section for more details. + +* You SHOULD suggest to *additionally* run ``ansible-test sanity`` from the ansible/ansible ``devel`` branch so that you find out about new linting requirements earlier. +* The sanity tests MUST pass. + + * Adding some entries to the ``test/sanity/ignore*.txt`` file is an allowed method of getting them to pass, except cases listed below. + * You SHOULD not have ignored test entries. A reviewer can manually evaluate and approve your collection if they deem an ignored entry to be valid. + + * You MUST not ignore the following validations. They must be fixed before approval: + * ``validate-modules:doc-choices-do-not-match-spec`` + * ``validate-modules:doc-default-does-not-match-spec`` + * ``validate-modules:doc-missing-type`` + * ``validate-modules:doc-required-mismatch`` + * ``validate-modules:mutually_exclusive-unknown`` + * ``validate-modules:no-log-needed`` (use ``no_log=False`` in the argument spec to flag false positives!) + * ``validate-modules:nonexistent-parameter-documented`` + * ``validate-modules:parameter-list-no-elements`` + * ``validate-modules:parameter-type-not-in-doc`` + * ``validate-modules:undocumented-parameter`` + + * All entries in ignores.txt MUST have a justification in a comment in the ignore.txt file for each entry. For example ``plugins/modules/docker_container.py use-argspec-type-path # uses colon-separated paths, can't use type=path``. + * Reviewers can block acceptance of a new collection if they don't agree with the ignores.txt entries. + +* You MUST run CI against each of the "major versions" (2.10, 2.11, 2.12, etc) of ``ansible-base``/``ansible-core`` that the collection supports. (Usually the ``HEAD`` of the stable-xxx branches.) +* All CI tests MUST run against every pull request and SHOULD pass before merge. +* At least sanity tests MUST run against a commit that releases the collection; if they do not pass, the collection will NOT be released. + + - If the collection has integration/unit tests, they SHOULD run too; if they do not pass, the errors SHOULD be analyzed to decide whether they should block the release or not. +* All CI tests MUST run regularly (nightly, or at least once per week) to ensure that repositories without regular commits are tested against the latest version of ansible-test from each ansible-base/ansible-core version tested. The results from the regular CI runs MUST be checked regularly. + +All of the above can be achieved by using the `GitHub Action template `_. + +To learn how to add tests to your collection, see: + +* :ref:`collection_integration_tests` +* :ref:`collection_unit_tests` + + +.. _coll_wg_reqs: + +Collections and Working Groups +============================== + +The collections have: + +* Working group page(s) on a corresponding wiki if needed. Makes sense if there is a group of modules for working with one common entity, for example postgresql, zabbix, grafana, and so on. +* Issue for agenda (or pinboard if there are not regular meetings) as a pinned issue in the repository. + +.. _coll_migrating_reqs: + +When moving modules between collections +======================================= + +All related entities must be moved/copied including: + +* Related plugins and module_utils files (when moving, be sure it is not used by other modules, otherwise copy). +* CI and unit tests. +* Corresponding documentation fragments from ``plugins/doc_fragments``. + +Also: + +* Change ``M()``, examples, ``seealso``, ``extended_documentation_fragments`` to use actual FQCNs in moved content and in other collections that have references to the content. +* Move all related issues, pull requests, and wiki pages. +* Look through ``docs/docsite`` directory of `ansible-base GitHub repository `_ (for example, using the ``grep`` command-line utility) to check if there are examples using the moved modules and plugins to update their FQCNs. + +See :ref:`Migrating content to a different collection ` for complete details. + +.. _coll_development_conventions: + +Development conventions +======================= + +Besides all the requirements listed in the :ref:`module_dev_conventions`, be sure: + +* Your modules satisfy the concept of :ref:`idempotency `: if a module repeatedly runs with the same set of inputs, it will not make any changes on the system. +* Your modules do not query information using special ``state`` option values like ``get``, ``list``, ``query``, or ``info`` - + create new ``_info`` or ``_facts`` modules instead (for more information, refer to the :ref:`Developing modules guidelines `). +* ``check_mode`` is supported in all ``*_info`` and ``*_facts`` modules (for more information, refer to the :ref:`Development conventions <#following-ansible-conventions>`). + +.. _coll_dependencies: + +Collection Dependencies +======================= + +**Notation:** if foo.bar has a dependency on baz.bam, we say that baz.bam is the collection *depended on*, and foo.bar is the *dependent collection*. + +* Collection dependencies must have a lower bound on the version which is at least 1.0.0. + + * This means that all collection dependencies have to specify lower bounds on the versions, and these lower bounds should be stable releases, and not versions of the form 0.x.y. + * When creating new collections where collection dependencies are also under development, you need to watch out since Galaxy checks whether dependencies exist in the required versions: + + #. Assume that ``foo.bar`` depends on ``foo.baz``. + #. First release ``foo.baz`` as 1.0.0. + #. Then modify ``foo.bar``'s ``galaxy.yml`` to specify ``'>=1.0.0'`` for ``foo.baz``. + #. Finally release ``foo.bar`` as 1.0.0. + +* The dependencies between collections included in Ansible must be valid. If a dependency is violated, the involved collections must be pinned so that all dependencies are valid again. This means that the version numbers from the previous release are kept or only partially incremented so that the resulting set of versions has no invalid dependencies. + +* If a collection has a too strict dependency for a longer time, and forces another collection depended on to be held back, that collection will be removed from the next major Ansible release. What "longer time" means depends on when the next Ansible major release happens. If a dependent collection prevents a new major version of a collection it depends on to be included in the next major Ansible release, the dependent collection will be removed from that major release to avoid blocking the collection being depended on. + +* We strongly suggest that collections also test against the ``main`` branches of their dependencies to ensure that incompatibilities with future releases of these are detected as early as possible and can be resolved in time to avoid such problems. Collections depending on other collections must understand that they bear the risk of being removed when they do not ensure compatibility with the latest releases of their dependencies. + +* Collections included in Ansible must not depend on other collections except if they satisfy one of the following cases: + + #. They have a loose dependency on one (or more) major versions of other collections included in Ansible. For example, ``ansible.netcommon: >=1.0.0``, or ``ansible.netcommon: >=2.0.0, <3.0.0``. In case the collection depended on releases a new major version outside of this version range that will be included in the next major Ansible release, the dependent collection will be removed from the next major Ansible release. The cut-off date for this is feature freeze. + #. They are explicitly being allowed to do so by the Steering Committee. + +Examples +-------- + +#. ``community.foo 1.2.0`` has a dependency on ``community.bar >= 1.0.0, < 1.3.0``. + + * Now ``community.bar`` creates a new release ``1.3.0``. When ``community.foo`` does not create a new release with a relaxed dependency, we have to include ``community.bar 1.2.x`` in the next Ansible release despite ``1.3.0`` being available. + * If ``community.foo`` does not relax its dependency on ``community.bar`` for some time, ``community.foo`` will be removed from the next Ansible major release. + * Unfortunately ``community.bar`` has to stay at ``1.2.x`` until either ``community.foo`` is removed (in the next major release), or loosens its requirements so that newer ``community.bar 1.3.z`` releases can be included. + +#. ``community.foonetwork`` depends on ``ansible.netcommon >= 2.0.0, <3.0.0``. + + * ``ansible.netcommon 4.0.0`` is released during this major Ansible release cycle. + * ``community.foonetwork`` either releases a new version before feature freeze of the next major Ansible release that allows depending on all ``ansible.netcommon 4.x.y`` releases, or it will be removed from the next major Ansible release. + +.. _coll_inclusion_reqs: + +Requirements for collections to be included in the Ansible Package +================================================================== + +To be included in the `ansible` package, collections must meet the following criteria: + +* :ref:`Development conventions `. +* `Collection requirements `_ (this document). + + * The `Collection Inclusion Criteria Checklist `_ covers most of the criteria from this document. +* :ref:`Ansible documentation format ` and the :ref:`style guide `. +* To pass the Ansible :ref:`sanity tests `. +* To have :ref:`unit `_and / or :ref:`integration tests ` according to the corresponding sections of this document. + + +Other requirements +=================== + +* After content is moved out of another currently included collection such as ``community.general`` or ``community.network`` OR a new collection satisfies all the requirements, add the collection to the ``ansible.in`` file in a corresponding directory of the `ansible-build-data repository `_. \ No newline at end of file diff --git a/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst b/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst index 0eb203b58a0..4a379dcda62 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst @@ -39,10 +39,10 @@ Other standards to check for in a PR include: * For jinja2 filter and test plugins, check out the `special syntax for changelog fragments `_. * The changelog content contains useful information for end users of the collection. -* If new files are added with the pull request, they follow the `licensing rules `_. +* If new files are added with the pull request, they follow the :ref:`coll_licensing_req`. * The changes follow the :ref:`Ansible documentation standards ` and the :ref:`style_guide`. * The changes follow the :ref:`Development conventions `. -* If a new plugin is added, it is one of the `allowed plugin types `_. +* If a new plugin is added, it is one of the :ref:`allowed plugin types `. * Documentation, examples, and return sections use FQCNs for the ``M(..)`` :ref:`format macros ` when referring to modules. * Modules and plugins from ansible-core use ``ansible.builtin.`` as an FQCN prefix when mentioned. * When a new option, module, plugin, or return value is added, the corresponding documentation or return sections use ``version_added:`` containing the *collection* version in which they will be first released. diff --git a/docs/docsite/rst/community/collection_contributors/collection_unit_tests.rst b/docs/docsite/rst/community/collection_contributors/collection_unit_tests.rst index e3573584b47..7a758c50155 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_unit_tests.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_unit_tests.rst @@ -26,7 +26,7 @@ Ansible uses `pytest `_ as a testing framewo See :ref:`testing_units_modules` for complete details. -Inclusion in the Ansible package `requires integration and/or unit tests `_ You should have tests for your collection as well as for individual modules and plugins to make your code more reliable To learn how to get started with integration tests, see :ref:`collection_integration_tests`. +Inclusion in the Ansible package :ref:`requires integration and/or unit tests ` You should have tests for your collection as well as for individual modules and plugins to make your code more reliable To learn how to get started with integration tests, see :ref:`collection_integration_tests`. See :ref:`collection_prepare_local` to prepare your environment. diff --git a/docs/docsite/rst/community/contributions_collections.rst b/docs/docsite/rst/community/contributions_collections.rst index f702d590f3b..7b1aad4c6c0 100644 --- a/docs/docsite/rst/community/contributions_collections.rst +++ b/docs/docsite/rst/community/contributions_collections.rst @@ -12,6 +12,7 @@ Ansible Collections Contributor Guide create_pr_quick_start collection_contributors/test_index collection_contributors/collection_reviewing + collection_contributors/collection_requirements maintainers contributing_maintained_collections steering/steering_index diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst index 43a0e69619c..cfdd0e9595b 100644 --- a/docs/docsite/rst/community/maintainers_guidelines.rst +++ b/docs/docsite/rst/community/maintainers_guidelines.rst @@ -21,7 +21,7 @@ In general, collection maintainers: - :ref:`Backport ` changes to stable branches. - Address or assign issues to appropriate contributors. - :ref:`Release collections `. -- Ensure that collections adhere to the `Collection Requirements `_, +- Ensure that collections adhere to the :ref:`collections_requirements`. - Track changes announced in `News for collection contributors and maintainers `_ and update a collection in accordance with these changes. - Subscribe and submit news to the `Bullhorn newsletter `_. - :ref:`Build a healthy community ` to increase the number of active contributors and maintainers around collections. diff --git a/docs/docsite/rst/community/maintainers_workflow.rst b/docs/docsite/rst/community/maintainers_workflow.rst index 6754d125ffa..e14ce5c025d 100644 --- a/docs/docsite/rst/community/maintainers_workflow.rst +++ b/docs/docsite/rst/community/maintainers_workflow.rst @@ -76,7 +76,7 @@ For convenience, backporting can be implemented automatically using GitHub bots Including a collection in Ansible ----------------------------------- -If a collection is not included in Ansible (not shipped with Ansible package), maintainers can submit the collection for inclusion by creating a discussion under the `ansible-collections/ansible-inclusion repository `_. For more information, see the `repository's README `_, and the `Ansible community package collections requirements `. +If a collection is not included in Ansible (not shipped with Ansible package), maintainers can submit the collection for inclusion by creating a discussion under the `ansible-collections/ansible-inclusion repository `_. For more information, see the `repository's README `_, and the :ref:`Ansible community package collections requirements `. Stepping down as a collection maintainer =========================================== diff --git a/docs/docsite/rst/community/other_tools_and_programs.rst b/docs/docsite/rst/community/other_tools_and_programs.rst index 40627912f9e..fbf21514f5e 100644 --- a/docs/docsite/rst/community/other_tools_and_programs.rst +++ b/docs/docsite/rst/community/other_tools_and_programs.rst @@ -114,6 +114,8 @@ Other tools - `Ansible Shell `_ - an interactive shell for Ansible with built-in tab completion for all the modules. - `Ansible Silo `_ - a self-contained Ansible environment by Docker. - `Ansigenome `_ - a command line tool designed to help you manage your Ansible roles. +- `antsibull-changelog `_ - a changelog generator for Ansible collections. +- `antsibull-docs `_ - generates docsites for collections and can validate collection documentation. - `ARA `_ - ARA Records Ansible playbooks and makes them easier to understand and troubleshoot with a reporting API, UI and CLI. - `Awesome Ansible `_ - a collaboratively curated list of awesome Ansible resources. - `AWX `_ - provides a web-based user interface, REST API, and task engine built on top of Ansible. Red Hat Ansible Automation Platform includes code from AWX. diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index 282d0ca0f34..5a5f2672bf2 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -92,7 +92,7 @@ To submit new collections for inclusion into the Ansible package: Depending on a topic you want to discuss with the Community and the Committee, as you prepare your proposal, please consider the requirements established by: * :ref:`code_of_conduct`. -* `Ansible Collection Requirements `_. +* :ref:`collections_requirements`. * `Ansible Collection Inclusion Checklist `_. Community topics workflow @@ -131,7 +131,7 @@ A person starting the triage: Collection inclusion requests workflow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When reviewing community collection `inclusion requests `_, the Committee members check if a collection adheres to the `Community collection requirements `_. +When reviewing community collection `inclusion requests `_, the Committee members check if a collection adheres to the :ref:`collections_requirements`. #. A Committee member who conducts the inclusion review copies the `Ansible community collection checklist `_ into a corresponding `discussion `_. diff --git a/docs/docsite/rst/porting_guides/porting_guide_7.rst b/docs/docsite/rst/porting_guides/porting_guide_7.rst index 5ac2f0f46cc..d5a94f260eb 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_7.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_7.rst @@ -92,6 +92,76 @@ Networking No notable changes +Porting Guide for v7.4.0 +======================== + +Breaking Changes +---------------- + +Ansible-core +~~~~~~~~~~~~ + +- ansible-test - Integration tests which depend on specific file permissions when running in an ansible-test managed host environment may require changes. Tests that require permissions other than ``755`` or ``644`` may need to be updated to set the necessary permissions as part of the test run. + +Major Changes +------------- + +community.hrobot +~~~~~~~~~~~~~~~~ + +- firewall - Hetzner added output rules support to the firewall. This change unfortunately means that using old versions of the firewall module will always set the output rule list to empty, thus disallowing the server to send out packets (https://github.com/ansible-collections/community.hrobot/issues/75, https://github.com/ansible-collections/community.hrobot/pull/76). + +community.vmware +~~~~~~~~~~~~~~~~ + +- Use true/false (lowercase) for boolean values in documentation and examples (https://github.com/ansible-collections/community.vmware/issues/1660). + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Add annotations of member operation for every module. +- Update ``fortios.py`` for higher performance; +- supports temporary session key and pre/post login banner; +- update the examples on how to use member operation in Q&A. + +purestorage.fusion +~~~~~~~~~~~~~~~~~~ + +- Patching of resource properties was brought to parity with underlying Python SDK, meaning the collection can create/update/delete all resource properties the SDK can +- fusion_volume - fixed and reorganized, arguments changed + +Deprecated Features +------------------- + +amazon.aws +~~~~~~~~~~ + +- support for passing both profile and security tokens through a mix of environment variables and parameters has been deprecated and support will be removed in release 6.0.0. After release 6.0.0 it will only be possible to pass either a profile or security tokens, regardless of mechanism used to pass them. To explicitly block a parameter coming from an environment variable pass an empty string as the parameter value. Support for passing profile and security tokens together was originally deprecated in release 1.2.0, however only partially implemented in release 5.0.0 (https://github.com/ansible-collections/amazon.aws/pull/1355). + +community.aws +~~~~~~~~~~~~~ + +- ecs_service - In a release after 2024-06-01, tha default value of ``purge_placement_constraints`` will be change from ``false`` to ``true`` (https://github.com/ansible-collections/community.aws/pull/1716). +- ecs_service - In a release after 2024-06-01, tha default value of ``purge_placement_strategy`` will be change from ``false`` to ``true`` (https://github.com/ansible-collections/community.aws/pull/1716). +- iam_role - All top level return values other than ``iam_role`` and ``changed`` have been deprecated and will be removed in a release after 2023-12-01 (https://github.com/ansible-collections/community.aws/issues/551). +- iam_role - In a release after 2023-12-01 the contents of ``assume_role_policy_document`` will no longer be converted from CamelCase to snake_case. The ``assume_role_policy_document_raw`` return value already returns the policy document in this future format (https://github.com/ansible-collections/community.aws/issues/551). +- iam_role_info - In a release after 2023-12-01 the contents of ``assume_role_policy_document`` will no longer be converted from CamelCase to snake_case. The ``assume_role_policy_document_raw`` return value already returns the policy document in this future format (https://github.com/ansible-collections/community.aws/issues/551). + +community.hashi_vault +~~~~~~~~~~~~~~~~~~~~~ + +- hashi_vault lookup - in ``v5.0.0`` duplicate term string options will raise an exception instead of showing a warning (https://github.com/ansible-collections/community.hashi_vault/issues/356). + +purestorage.fusion +~~~~~~~~~~~~~~~~~~ + +- fusion_hw - hardware module is being removed as changing hardware type has never been supported by Pure Storage Fusion +- fusion_info - nigs subset is deprecated in favor of network_interface_groups and will be removed in the version 1.7.0 (https://github.com/Pure-Storage-Ansible/Fusion-Collection/pull/46). +- fusion_info - placements subset is deprecated in favor of placement_groups and will be removed in the version 1.7.0 (https://github.com/Pure-Storage-Ansible/Fusion-Collection/pull/62). +- fusion_pg - placement_engine option is deprecated because Fusion API does not longer support this parameter It will be removed in the version 2.0.0 (https://github.com/Pure-Storage-Ansible/Fusion-Collection/pull/53). +- fusion_se - parameters "addresses", "gateway" and "network_interface_groups" are deprecated in favor of "iscsi" and will be removed in version 2.0.0 +- fusion_tn - tenant networks are being replaced by storage endpoints ```fusion_se``` and Network Interface Groups ```fusion_nig``` + Porting Guide for v7.3.0 ======================== diff --git a/docs/docsite/rst/reference_appendices/special_variables.rst b/docs/docsite/rst/reference_appendices/special_variables.rst index e159f476f24..73bd07c0866 100644 --- a/docs/docsite/rst/reference_appendices/special_variables.rst +++ b/docs/docsite/rst/reference_appendices/special_variables.rst @@ -7,141 +7,145 @@ Magic variables --------------- These variables cannot be set directly by the user; Ansible will always override them to reflect internal state. -ansible_check_mode - Boolean that indicates if we are in check mode or not +.. glossary:: -ansible_config_file - The full path of used Ansible configuration file + ansible_check_mode + Boolean that indicates if we are in check mode or not -ansible_dependent_role_names - The names of the roles currently imported into the current play as dependencies of other plays + ansible_config_file + The full path of used Ansible configuration file -ansible_diff_mode - Boolean that indicates if we are in diff mode or not + ansible_dependent_role_names + The names of the roles currently imported into the current play as dependencies of other plays -ansible_forks - Integer reflecting the number of maximum forks available to this run + ansible_diff_mode + Boolean that indicates if we are in diff mode or not -ansible_inventory_sources - List of sources used as inventory + ansible_forks + Integer reflecting the number of maximum forks available to this run -ansible_limit - Contents of the ``--limit`` CLI option for the current execution of Ansible + ansible_inventory_sources + List of sources used as inventory -ansible_loop - A dictionary/map containing extended loop information when enabled through ``loop_control.extended`` + ansible_limit + Contents of the ``--limit`` CLI option for the current execution of Ansible -ansible_loop_var - The name of the value provided to ``loop_control.loop_var``. Added in ``2.8`` + ansible_loop + A dictionary/map containing extended loop information when enabled through ``loop_control.extended`` -ansible_index_var - The name of the value provided to ``loop_control.index_var``. Added in ``2.9`` + ansible_loop_var + The name of the value provided to ``loop_control.loop_var``. Added in ``2.8`` -ansible_parent_role_names - When the current role is being executed by means of an :ref:`include_role ` or :ref:`import_role ` action, this variable contains a list of all parent roles, with the most recent role (in other words, the role that included/imported this role) being the first item in the list. - When multiple inclusions occur, this list lists the *last* role (in other words, the role that included this role) as the *first* item in the list. It is also possible that a specific role exists more than once in this list. + ansible_index_var + The name of the value provided to ``loop_control.index_var``. Added in ``2.9`` - For example: When role **A** includes role **B**, inside role B, ``ansible_parent_role_names`` will equal to ``['A']``. If role **B** then includes role **C**, the list becomes ``['B', 'A']``. + ansible_parent_role_names + When the current role is being executed by means of an :ref:`include_role ` or :ref:`import_role ` action, this variable contains a list of all parent roles, with the most recent role (in other words, the role that included/imported this role) being the first item in the list. + When multiple inclusions occur, this list lists the *last* role (in other words, the role that included this role) as the *first* item in the list. It is also possible that a specific role exists more than once in this list. -ansible_parent_role_paths - When the current role is being executed by means of an :ref:`include_role ` or :ref:`import_role ` action, this variable contains a list of all parent roles paths, with the most recent role (in other words, the role that included/imported this role) being the first item in the list. - Please refer to ``ansible_parent_role_names`` for the order of items in this list. + For example: When role **A** includes role **B**, inside role B, ``ansible_parent_role_names`` will equal to ``['A']``. If role **B** then includes role **C**, the list becomes ``['B', 'A']``. -ansible_play_batch - List of active hosts in the current play run limited by the serial, aka 'batch'. Failed/Unreachable hosts are not considered 'active'. + ansible_parent_role_paths + When the current role is being executed by means of an :ref:`include_role ` or :ref:`import_role ` action, this variable contains a list of all parent roles paths, with the most recent role (in other words, the role that included/imported this role) being the first item in the list. + Please refer to ``ansible_parent_role_names`` for the order of items in this list. -ansible_play_hosts - List of hosts in the current play run, not limited by the serial. Failed/Unreachable hosts are excluded from this list. + ansible_play_batch + List of active hosts in the current play run limited by the serial, aka 'batch'. Failed/Unreachable hosts are not considered 'active'. -ansible_play_hosts_all - List of all the hosts that were targeted by the play + ansible_play_hosts + List of hosts in the current play run, not limited by the serial. Failed/Unreachable hosts are excluded from this list. -ansible_play_role_names - The names of the roles currently imported into the current play. This list does **not** contain the role names that are - implicitly included through dependencies. + ansible_play_hosts_all + List of all the hosts that were targeted by the play -ansible_playbook_python - The path to the python interpreter being used by Ansible on the controller + ansible_play_role_names + The names of the roles currently imported into the current play. This list does **not** contain the role names that are + implicitly included through dependencies. -ansible_role_names - The names of the roles currently imported into the current play, or roles referenced as dependencies of the roles - imported into the current play. + ansible_playbook_python + The path to the python interpreter being used by Ansible on the controller -ansible_role_name - The fully qualified collection role name, in the format of ``namespace.collection.role_name`` + ansible_role_names + The names of the roles currently imported into the current play, or roles referenced as dependencies of the roles + imported into the current play. -ansible_collection_name - The name of the collection the task that is executing is a part of. In the format of ``namespace.collection`` + ansible_role_name + The fully qualified collection role name, in the format of ``namespace.collection.role_name`` -ansible_run_tags - Contents of the ``--tags`` CLI option, which specifies which tags will be included for the current run. Note that if ``--tags`` is not passed, this variable will default to ``["all"]``. + ansible_collection_name + The name of the collection the task that is executing is a part of. In the format of ``namespace.collection`` -ansible_search_path - Current search path for action plugins and lookups, in other words, where we search for relative paths when you do ``template: src=myfile`` + ansible_run_tags + Contents of the ``--tags`` CLI option, which specifies which tags will be included for the current run. Note that if ``--tags`` is not passed, this variable will default to ``["all"]``. -ansible_skip_tags - Contents of the ``--skip-tags`` CLI option, which specifies which tags will be skipped for the current run. + ansible_search_path + Current search path for action plugins and lookups, in other words, where we search for relative paths when you do ``template: src=myfile`` -ansible_verbosity - Current verbosity setting for Ansible + ansible_skip_tags + Contents of the ``--skip-tags`` CLI option, which specifies which tags will be skipped for the current run. -ansible_version - Dictionary/map that contains information about the current running version of ansible, it has the following keys: full, major, minor, revision and string. + ansible_verbosity + Current verbosity setting for Ansible -group_names - List of groups the current host is part of + ansible_version + Dictionary/map that contains information about the current running version of ansible, it has the following keys: full, major, minor, revision and string. -groups - A dictionary/map with all the groups in inventory and each group has the list of hosts that belong to it + group_names + List of groups the current host is part of -hostvars - A dictionary/map with all the hosts in inventory and variables assigned to them + groups + A dictionary/map with all the groups in inventory and each group has the list of hosts that belong to it -inventory_hostname - The inventory name for the 'current' host being iterated over in the play + hostvars + A dictionary/map with all the hosts in inventory and variables assigned to them -inventory_hostname_short - The short version of `inventory_hostname` + inventory_hostname + The inventory name for the 'current' host being iterated over in the play -inventory_dir - The directory of the inventory source in which the `inventory_hostname` was first defined + inventory_hostname_short + The short version of `inventory_hostname` -inventory_file - The file name of the inventory source in which the `inventory_hostname` was first defined + inventory_dir + The directory of the inventory source in which the `inventory_hostname` was first defined -omit - Special variable that allows you to 'omit' an option in a task, for example ``- user: name=bob home={{ bobs_home|default(omit) }}`` + inventory_file + The file name of the inventory source in which the `inventory_hostname` was first defined -play_hosts - Deprecated, the same as ansible_play_batch + omit + Special variable that allows you to 'omit' an option in a task, for example ``- user: name=bob home={{ bobs_home|default(omit) }}`` -ansible_play_name - The name of the currently executed play. Added in ``2.8``. (`name` attribute of the play, not file name of the playbook.) + play_hosts + Deprecated, the same as ansible_play_batch -playbook_dir - The path to the directory of the current playbook being executed. NOTE: This might be different than directory of the playbook passed to the ``ansible-playbook`` command line when a playbook contains a ``import_playbook`` statement. + ansible_play_name + The name of the currently executed play. Added in ``2.8``. (`name` attribute of the play, not file name of the playbook.) -role_name - The name of the role currently being executed. + playbook_dir + The path to the directory of the current playbook being executed. NOTE: This might be different than directory of the playbook passed to the ``ansible-playbook`` command line when a playbook contains a ``import_playbook`` statement. -role_names - Deprecated, the same as ansible_play_role_names + role_name + The name of the role currently being executed. -role_path - The path to the dir of the currently running role + role_names + Deprecated, the same as ansible_play_role_names + + role_path + The path to the dir of the currently running role Facts ----- These are variables that contain information pertinent to the current host (`inventory_hostname`). They are only available if gathered first. See :ref:`vars_and_facts` for more information. -ansible_facts - Contains any facts gathered or cached for the `inventory_hostname` - Facts are normally gathered by the :ref:`setup ` module automatically in a play, but any module can return facts. +.. glossary:: + + ansible_facts + Contains any facts gathered or cached for the `inventory_hostname` + Facts are normally gathered by the :ref:`setup ` module automatically in a play, but any module can return facts. -ansible_local - Contains any 'local facts' gathered or cached for the `inventory_hostname`. - The keys available depend on the custom facts created. - See the :ref:`setup ` module and :ref:`local_facts` for more details. + ansible_local + Contains any 'local facts' gathered or cached for the `inventory_hostname`. + The keys available depend on the custom facts created. + See the :ref:`setup ` module and :ref:`local_facts` for more details. .. _connection_variables: @@ -151,17 +155,19 @@ Connection variables are normally used to set the specifics on how to execute ac Only the common ones are described as each connection/become/shell/etc plugin can define its own overrides and specific variables. See :ref:`general_precedence_rules` for how connection variables interact with :ref:`configuration settings`, :ref:`command-line options`, and :ref:`playbook keywords`. -ansible_become_user - The user Ansible 'becomes' after using privilege escalation. This must be available to the 'login user'. +.. glossary:: + + ansible_become_user + The user Ansible 'becomes' after using privilege escalation. This must be available to the 'login user'. -ansible_connection - The connection plugin actually used for the task on the target host. + ansible_connection + The connection plugin actually used for the task on the target host. -ansible_host - The ip/name of the target host to use instead of `inventory_hostname`. + ansible_host + The ip/name of the target host to use instead of `inventory_hostname`. -ansible_python_interpreter - The path to the Python executable Ansible should use on the target host. + ansible_python_interpreter + The path to the Python executable Ansible should use on the target host. -ansible_user - The user Ansible 'logs in' as. + ansible_user + The user Ansible 'logs in' as. diff --git a/docs/docsite/sphinx_conf/core_conf.py b/docs/docsite/sphinx_conf/core_conf.py index 7f1663b37b8..a279c02fed9 100644 --- a/docs/docsite/sphinx_conf/core_conf.py +++ b/docs/docsite/sphinx_conf/core_conf.py @@ -104,6 +104,7 @@ exclude_patterns = [ 'community/collection_contributors/collection_integration_tests.rst', 'community/collection_contributors/collection_integration_running.rst', 'community/collection_contributors/collection_reviewing.rst', + 'community/collection_contributors/collection_requirements.rst', 'community/collection_contributors/collection_unit_tests.rst', 'community/maintainers.rst', 'community/contributions_collections.rst', diff --git a/docs/docsite/sphinx_conf/core_lang_conf.py b/docs/docsite/sphinx_conf/core_lang_conf.py index 49efc6ee710..2d4ecc14e0c 100644 --- a/docs/docsite/sphinx_conf/core_lang_conf.py +++ b/docs/docsite/sphinx_conf/core_lang_conf.py @@ -104,6 +104,7 @@ exclude_patterns = [ 'community/collection_contributors/collection_integration_tests.rst', 'community/collection_contributors/collection_integration_running.rst', 'community/collection_contributors/collection_reviewing.rst', + 'community/collection_contributors/collection_requirements.rst', 'community/collection_contributors/collection_unit_tests.rst', 'community/maintainers.rst', 'community/contributions_collections.rst', diff --git a/lib/ansible/modules/uri.py b/lib/ansible/modules/uri.py index f68b86a530c..7919b9b2f5a 100644 --- a/lib/ansible/modules/uri.py +++ b/lib/ansible/modules/uri.py @@ -94,9 +94,16 @@ options: force_basic_auth: description: - Force the sending of the Basic authentication header upon initial request. - - The library used by the uri module only sends authentication information when a webservice - responds to an initial request with a 401 status. Since some basic auth services do not properly - send a 401, logins will fail. + - When this setting is C(false), this module will first try an unauthenticated request, and when the server replies + with an C(HTTP 401) error, it will submit the Basic authentication header. + - When this setting is C(true), this module will immediately send a Basic authentication header on the first + request. + - "Use this setting in any of the following scenarios:" + - You know the webservice endpoint always requires HTTP Basic authentication, and you want to speed up your + requests by eliminating the first roundtrip. + - The web service does not properly send an HTTP 401 error to your client, so Ansible's HTTP library will not + properly respond with HTTP credentials, and logins will fail. + - The webservice bans or rate-limits clients that cause any HTTP 401 errors. type: bool default: no follow_redirects: diff --git a/lib/ansible/plugins/filter/basename.yml b/lib/ansible/plugins/filter/basename.yml index 4e868df8047..b6e31d232d3 100644 --- a/lib/ansible/plugins/filter/basename.yml +++ b/lib/ansible/plugins/filter/basename.yml @@ -5,6 +5,8 @@ DOCUMENTATION: short_description: get a path's base name description: - Returns the last name component of a path, what is left in the string that is not 'dirname'. + notes: + - The result of this filter is different from the Unix basename program; where basename for C(/foo/bar/) returns C(bar), the basename filter returns an empty string (C('')). options: _input: description: A path. @@ -15,7 +17,7 @@ DOCUMENTATION: plugin: ansible.builtin.dirname EXAMPLES: | - # To get the last name of a file path, like 'foo.txt' out of '/etc/asdf/foo.txt' + # To get the last name of a file path, like 'foo.txt' out of '/etc/asdf/foo.txt'. {{ mypath | basename }} RETURN: diff --git a/lib/ansible/plugins/filter/dirname.yml b/lib/ansible/plugins/filter/dirname.yml index 52f7d5d42e3..4b8b0f7b29d 100644 --- a/lib/ansible/plugins/filter/dirname.yml +++ b/lib/ansible/plugins/filter/dirname.yml @@ -5,6 +5,8 @@ DOCUMENTATION: short_description: get a path's directory name description: - Returns the 'head' component of a path, basically everything that is not the 'basename'. + notes: + - The result of this filter is different from the Unix dirname program; where dirname for C(/foo/bar/) returns C(/foo), the dirname filter returns the full path (C(/foo/bar/)). options: _input: description: A path. @@ -15,7 +17,7 @@ DOCUMENTATION: plugin_type: filter EXAMPLES: | - # To get the dir name of a file path, like '/etc/asdf' out of '/etc/asdf/foo.txt' + # To get the dir name of a file path, like '/etc/asdf' out of '/etc/asdf/foo.txt'. {{ mypath | dirname }} RETURN: