From 9339f71d3f6c3706aad31a810c4013bcefbd7dd6 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 13 Oct 2023 11:06:05 -0400 Subject: [PATCH 001/536] corrected cli for help (#599) this prevents an error, but it does not really matter as -h will return generic help for ansible-test and not specific to a test. --- docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst b/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst index 27779190833..d368d1015c1 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/validate-modules.rst @@ -20,7 +20,7 @@ Usage Help ----- -Type ``ansible-test sanity validate-modules -h`` to display help for using this sanity test. +Type ``ansible-test sanity --test validate-modules -h`` to display help for using this sanity test. From baedfb3b2fed62d896839319cfd0140fa9837189 Mon Sep 17 00:00:00 2001 From: simeononsecurity <4913771+simeononsecurity@users.noreply.github.com> Date: Fri, 13 Oct 2023 15:31:02 +0000 Subject: [PATCH 002/536] Update PowerShell Codeblock (#489) Improve error handling, implement powershell best practices, allow for assemblies to be passed into it as an argument. Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com> --- .../rst/os_guide/windows_performance.rst | 61 ++++++++++++++----- 1 file changed, 45 insertions(+), 16 deletions(-) diff --git a/docs/docsite/rst/os_guide/windows_performance.rst b/docs/docsite/rst/os_guide/windows_performance.rst index c922b4d9edd..7adf5d81999 100644 --- a/docs/docsite/rst/os_guide/windows_performance.rst +++ b/docs/docsite/rst/os_guide/windows_performance.rst @@ -20,24 +20,52 @@ seconds. .. code-block:: powershell - function Optimize-PowershellAssemblies { - # NGEN powershell assembly, improves startup time of powershell by 10x - $old_path = $env:path - try { - $env:path = [Runtime.InteropServices.RuntimeEnvironment]::GetRuntimeDirectory() - [AppDomain]::CurrentDomain.GetAssemblies() | % { - if (! $_.location) {continue} - $Name = Split-Path $_.location -leaf - if ($Name.startswith("Microsoft.PowerShell.")) { - Write-Progress -Activity "Native Image Installation" -Status "$name" - ngen install $_.location | % {"`t$_"} - } + function Optimize-Assemblies { + param ( + [string]$assemblyFilter = "Microsoft.PowerShell.", + [string]$activity = "Native Image Installation" + ) + + try { + # Get the path to the ngen executable dynamically + $ngenPath = [System.IO.Path]::Combine([Runtime.InteropServices.RuntimeEnvironment]::GetRuntimeDirectory(), "ngen.exe") + + # Check if ngen.exe exists + if (-Not (Test-Path $ngenPath)) { + Write-Host "Ngen.exe not found at $ngenPath. Make sure .NET Framework is installed." + return + } + + # Get a list of loaded assemblies + $assemblies = [AppDomain]::CurrentDomain.GetAssemblies() + + # Filter assemblies based on the provided filter + $filteredAssemblies = $assemblies | Where-Object { $_.FullName -ilike "$assemblyFilter*" } + + if ($filteredAssemblies.Count -eq 0) { + Write-Host "No matching assemblies found for optimization." + return + } + + foreach ($assembly in $filteredAssemblies) { + # Get the name of the assembly + $name = [System.IO.Path]::GetFileName($assembly.Location) + + # Display progress + Write-Progress -Activity $activity -Status "Optimizing $name" + + # Use Ngen to install the assembly + Start-Process -FilePath $ngenPath -ArgumentList "install `"$($assembly.Location)`"" -Wait -WindowStyle Hidden + } + + Write-Host "Optimization complete." + } catch { + Write-Host "An error occurred: $_" } - } finally { - $env:path = $old_path - } } - Optimize-PowershellAssemblies + + # Optimize PowerShell assemblies: + Optimize-Assemblies -assemblyFilter "Microsoft.PowerShell." PowerShell is used by every Windows Ansible module. This optimization reduces the time PowerShell takes to start up, removing that overhead from every invocation. @@ -59,3 +87,4 @@ Place the following near the end of your playbook, bearing in mind the factors t - name: generate native .NET images for CPU win_dotnet_ngen: + From 10b151f39c8061f6a85eae8f0f537b8a487a9e1d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 14 Oct 2023 19:33:06 -0500 Subject: [PATCH 003/536] ci: refresh dev dependencies (#608) Co-authored-by: Github Actions <41898282+github-actions[bot]@users.noreply.github.com> --- tests/typing.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/typing.txt b/tests/typing.txt index 799da429fb4..f4586466ced 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -34,7 +34,7 @@ jinja2==3.1.2 # via -r tests/../hacking/pr_labeler/requirements.txt markupsafe==2.1.3 # via jinja2 -mypy==1.5.1 +mypy==1.6.0 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy From b9323fbe54986d4a8ea941653bae1bb92597b4c8 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 15 Oct 2023 21:34:02 +0200 Subject: [PATCH 004/536] Document how to bump dependencies (#446) * Document how to bump dependencies. * Drop `-i`, keep `-t`. * Expand option names. * Place command in code block. * Adjust command. Co-authored-by: Maxwell G --------- Co-authored-by: Maxwell G --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 2a707e72f11..172c5abce40 100644 --- a/README.md +++ b/README.md @@ -7,3 +7,10 @@ This repository holds the ReStructuredText (RST) source, and other files, for us ## Building Ansible community documentation Follow the documentation to [set up your environment](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally) and then [build Ansible community documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally) + +## Updating the dependencies + +To update dependencies, you can use `nox -e pip-compile`. Since this requires Python 3.10, this might not work in your environment if you do not have Python 3.10 installed. In that case, you can use root-less podman with a Python 3.10 image: +```bash +podman run --rm --tty --volume "$(pwd):/mnt:z" --workdir /mnt python:3.10 bash -c 'pip install nox ; nox -e pip-compile' +``` From 2f8810b25589a94c10bcd35dc56212c81fd24b20 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 16 Oct 2023 19:18:28 +0100 Subject: [PATCH 005/536] Add RST spellcheck (#524) * Add docs spelling check * Add codespell config to noxfile and ci * Update README with details on spelling checks Co-authored-by: Maxwell G <9920591+gotmax23@users.noreply.github.com> --- .codespellignorelines | 15 ++++++++ .codespellignorewords | 4 ++ .codespellrc | 8 ++++ .github/workflows/pip-compile-dev.yml | 1 + .github/workflows/reusable-nox.yml | 2 + README.md | 21 ++++++++++ .../collection_reviewing.rst | 2 +- .../rst/community/committer_guidelines.rst | 6 +-- .../developing_collections_distributing.rst | 2 +- .../developing_modules_general_windows.rst | 2 +- .../developing_modules_in_groups.rst | 2 +- .../rst/dev_guide/developing_plugins.rst | 2 +- .../docsite/rst/dev_guide/migrating_roles.rst | 2 +- docs/docsite/rst/playbook_guide/index.rst | 2 +- .../playbooks_advanced_syntax.rst | 2 +- .../playbook_guide/playbooks_conditionals.rst | 6 +-- .../playbook_guide/playbooks_environment.rst | 4 +- .../rst/playbook_guide/playbooks_filters.rst | 2 +- .../rst/playbook_guide/playbooks_intro.rst | 2 +- .../rst/playbook_guide/playbooks_reuse.rst | 38 +++++++++---------- .../rst/playbook_guide/playbooks_tags.rst | 10 ++--- .../playbook_guide/playbooks_variables.rst | 2 +- .../docsite/rst/scenario_guides/guide_aci.rst | 4 +- .../rst/scenario_guides/guide_scaleway.rst | 2 +- .../vault_using_encrypted_content.rst | 2 +- noxfile.py | 14 +++++++ tests/spelling.in | 1 + tests/spelling.txt | 8 ++++ 28 files changed, 121 insertions(+), 47 deletions(-) create mode 100644 .codespellignorelines create mode 100644 .codespellignorewords create mode 100644 .codespellrc create mode 100644 tests/spelling.in create mode 100644 tests/spelling.txt diff --git a/.codespellignorelines b/.codespellignorelines new file mode 100644 index 00000000000..59936541356 --- /dev/null +++ b/.codespellignorelines @@ -0,0 +1,15 @@ +# This file contains exact lines ignored by the spelling check. + $ ssh-add ~/.ssh/keypair.pem + shell: echo "disable server myapplb/{{ inventory_hostname }}" | socat stdio /var/lib/haproxy/stats + shell: echo "enable server myapplb/{{ inventory_hostname }}" | socat stdio /var/lib/haproxy/stats + "ro": true, + "options": "ro,relatime,mode=0700", + RootSDDL = O:NSG:BAD:P(A;;GA;;;BA)(A;;GR;;;IU)S:P(AU;FA;GA;;;WD)(AU;SA;GXGW;;;WD) +IAM policies for AWS + for managing IAM roles, users and groups. +see the `Active Directory Certificate Services documentation `_. + `Act as part of the operating system `_. +`Accounts: Limit local account use of blank passwords to console logon only `_ + role_type: ANS + # => "$6$43927$lQxPKz2M2X.NWO.gK.t7phLwOKQMcSq72XxDZQ0XzYV6DlL1OD72h417aj16OnHTGxNzhftXJQBcjbunLEepM0" + table#network-platform-table thead tr th.head { diff --git a/.codespellignorewords b/.codespellignorewords new file mode 100644 index 00000000000..e59b06502e1 --- /dev/null +++ b/.codespellignorewords @@ -0,0 +1,4 @@ +# This file contains words ignored by the spelling check. +aci +falsy +doas diff --git a/.codespellrc b/.codespellrc new file mode 100644 index 00000000000..ee4f01c1e09 --- /dev/null +++ b/.codespellrc @@ -0,0 +1,8 @@ +[codespell] +skip = _build,collections,*.po,_static,porting_guide*,style_guide +count = +check-filenames = true +quiet-level = 3 +ignore-words = .codespellignorewords +exclude-file = .codespellignorelines +builtin = clear,code,en-GB_to_en-US,informal,names,rare diff --git a/.github/workflows/pip-compile-dev.yml b/.github/workflows/pip-compile-dev.yml index befde055072..5931b4f4481 100644 --- a/.github/workflows/pip-compile-dev.yml +++ b/.github/workflows/pip-compile-dev.yml @@ -39,4 +39,5 @@ jobs: -e 'pip-compile-3.10(formatters)' 'pip-compile-3.10(typing)' 'pip-compile-3.10(static)' + 'pip-compile-3.10(spelling)' reset-branch: "${{ inputs.reset-branch || false }}" diff --git a/.github/workflows/reusable-nox.yml b/.github/workflows/reusable-nox.yml index a43f6c634d3..ba56fb1a097 100644 --- a/.github/workflows/reusable-nox.yml +++ b/.github/workflows/reusable-nox.yml @@ -17,6 +17,8 @@ jobs: python-versions: "3.11" - session: typing python-versions: "3.11" + - session: spelling + python-versions: "3.11" name: "Run nox ${{ matrix.session }} session" steps: - name: Check out repo diff --git a/README.md b/README.md index 172c5abce40..1f18d861c93 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,27 @@ This repository holds the ReStructuredText (RST) source, and other files, for us Follow the documentation to [set up your environment](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally) and then [build Ansible community documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally) +## Using nox + +This project includes a `nox` configuration to automate checks and other functions. +You should use `nox` to run checks locally before you submit a pull request. + +Install `nox` using `python3 -m pip install nox` or your distribution's package manager. + +Run `nox --list` from the repository root to view available sessions. + +Run `nox` with no arguments to execute the default sessions. + +## Running the spelling check + +This repository uses [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source. + +Run `nox -s spelling` to check spelling. + +Run `nox -s spelling -- -w` to correct spelling errors. + +When `codespell` suggests more than one word as a correction, run `nox -s spelling -- -w -i 3` to select an option. + ## Updating the dependencies To update dependencies, you can use `nox -e pip-compile`. Since this requires Python 3.10, this might not work in your environment if you do not have Python 3.10 installed. In that case, you can use root-less podman with a Python 3.10 image: diff --git a/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst b/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst index 4a379dcda62..25f4f52a4f0 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst @@ -14,7 +14,7 @@ When users report bugs, verify the behavior reported. Remember always to be kind * Did the user assume an unexpected behavior? Ensure that the related documentation is clear. If not, the issue is useful to help us improve documentation. * Is there a minimal reproducer? If not, ask the reporter to reduce the complexity to help pinpoint the issue. * Is the issue a consequence of a misconfigured environment? -* If it seems to be a real bug, does the behaviour still exist in the most recent release or the development branch? +* If it seems to be a real bug, does the behavior still exist in the most recent release or the development branch? * Reproduce the bug, or if you do not have a suitable infrastructure, ask other contributors to reproduce the bug. diff --git a/docs/docsite/rst/community/committer_guidelines.rst b/docs/docsite/rst/community/committer_guidelines.rst index 7067a5a266c..5cd0e20a832 100644 --- a/docs/docsite/rst/community/committer_guidelines.rst +++ b/docs/docsite/rst/community/committer_guidelines.rst @@ -41,11 +41,11 @@ As a committer, you may already know this, but our workflow forms a lot of our t Addendum to workflow for committers: ------------------------------------ -The Core Team is aware that this can be a difficult process at times. Sometimes, the team breaks the rules by making direct commits or merging their own pull requests. This section is a set of guidelines. If you are changing a comma in documentation, or making a very minor change, you can use your best judgement. This is another trust thing. The process is critical for any major change, but for little things or getting something done quickly, use your best judgement and make sure people on the team are aware of your work. +The Core Team is aware that this can be a difficult process at times. Sometimes, the team breaks the rules by making direct commits or merging their own pull requests. This section is a set of guidelines. If you are changing a comma in documentation, or making a very minor change, you can use your best judgment. This is another trust thing. The process is critical for any major change, but for little things or getting something done quickly, use your best judgment and make sure people on the team are aware of your work. Roles on Core ============= -* Core committers: Fine to do pull requests for most things, but we should have a timebox. Hanging pull requests may merge on the judgement of these developers. +* Core committers: Fine to do pull requests for most things, but we should have a timebox. Hanging pull requests may merge on the judgment of these developers. * :ref:`Module maintainers `: Module maintainers own specific modules and have indirect commit access through the current module pull request mechanisms. * :ref:`Collection maintainers `: Collection maintainers own specific collections and have commit access to them. Each collection can set its own rules for contributions. @@ -53,7 +53,7 @@ Roles on Core General rules ============= -Individuals with direct commit access are entrusted with powers that allow them to do a broad variety of things--probably more than we can write down. Rather than rules, treat these as general *guidelines*, individuals with this power are expected to use their best judgement. +Individuals with direct commit access are entrusted with powers that allow them to do a broad variety of things--probably more than we can write down. Rather than rules, treat these as general *guidelines*, individuals with this power are expected to use their best judgment. * Do NOT diff --git a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst index 124d112439c..31a07ceacc5 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst @@ -388,7 +388,7 @@ Publishing a collection from the website To publish your collection directly on the Galaxy website: #. Go to the `My Content `_ page, and click the **Add Content** button on one of your namespaces. -#. From the **Add Content** dialogue, click **Upload New Collection**, and select the collection archive file from your local filesystem. +#. From the **Add Content** dialog, click **Upload New Collection**, and select the collection archive file from your local filesystem. When you upload a collection, Ansible always uploads the tarball to the namespace specified in the collection metadata in the ``galaxy.yml`` file, no matter which namespace you select on the website. If you are not an owner of the namespace specified in your collection metadata, the upload request fails. diff --git a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst index 7a20affc257..e51e4a9cc00 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst @@ -206,7 +206,7 @@ options set: - ``default``: The default value for the module option if not set - ``deprecated_aliases``: A list of hashtables that define aliases that are deprecated and the versions they will be removed in. Each entry must contain the keys ``name`` and ``collection_name`` with either ``version`` or ``date`` - ``elements``: When ``type=list``, this sets the type of each list value, the values are the same as ``type`` -- ``no_log``: Will sanitise the input value before being returned in the ``module_invocation`` return value +- ``no_log``: Will sanitize the input value before being returned in the ``module_invocation`` return value - ``removed_in_version``: States when a deprecated module option is to be removed, a warning is displayed to the end user if set - ``removed_at_date``: States the date (YYYY-MM-DD) when a deprecated module option will be removed, a warning is displayed to the end user if set - ``removed_from_collection``: States from which collection the deprecated module option will be removed; must be specified if one of ``removed_in_version`` and ``removed_at_date`` is specified diff --git a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst index 5f21662894d..fc0fecceaf7 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst @@ -55,7 +55,7 @@ Ansible has a thriving and knowledgeable community of module developers that is In the :ref:`ansible_community_guide` you can find how to: * Subscribe to the Mailing Lists - We suggest "Ansible Development List" and "Ansible Announce list" -* ``#ansible-devel`` - We have found that communicating on the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) works best for developers so we can have an interactive dialogue. +* ``#ansible-devel`` - We have found that communicating on the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) works best for developers so we can have an interactive dialog. * Working group and other chat channel meetings - Join the various weekly meetings `meeting schedule and agenda page `_ Required files diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 86161433696..dce4ed934f4 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -383,7 +383,7 @@ Here's a simple lookup plugin implementation --- this lookup returns the content required: True option1: description: - - Sample option that could modify plugin behaviour. + - Sample option that could modify plugin behavior. - This one can be set directly ``option1='x'`` or in ansible.cfg, but can also use vars or environment. type: string ini: diff --git a/docs/docsite/rst/dev_guide/migrating_roles.rst b/docs/docsite/rst/dev_guide/migrating_roles.rst index ddf79c954ba..02dbb68a68a 100644 --- a/docs/docsite/rst/dev_guide/migrating_roles.rst +++ b/docs/docsite/rst/dev_guide/migrating_roles.rst @@ -5,7 +5,7 @@ Migrating Roles to Roles in Collections on Galaxy ************************************************* -You can migrate any existing standalone role into a collection and host the collection on Galaxy. With Ansible collections, you can distribute many roles in a single cohesive unit of re-usable automation. Inside a collection, you can share custom plugins across all roles in the collection instead of duplicating them in each role's :file:`library/`` directory. +You can migrate any existing standalone role into a collection and host the collection on Galaxy. With Ansible collections, you can distribute many roles in a single cohesive unit of reusable automation. Inside a collection, you can share custom plugins across all roles in the collection instead of duplicating them in each role's :file:`library/`` directory. You must migrate roles to collections if you want to distribute them as certified Ansible content. diff --git a/docs/docsite/rst/playbook_guide/index.rst b/docs/docsite/rst/playbook_guide/index.rst index 3bd50fdc256..56849b379d4 100644 --- a/docs/docsite/rst/playbook_guide/index.rst +++ b/docs/docsite/rst/playbook_guide/index.rst @@ -20,7 +20,7 @@ This guide introduces you to playbooks and then covers different use cases for t * Running conditional tasks and evaluating conditions with playbook tests. * Using blocks to group sets of tasks. -You can also learn how to use Ansible playbooks more effectively by using collections, creating re-usable files and roles, including and importing playbooks, and running selected parts of a playbook with tags. +You can also learn how to use Ansible playbooks more effectively by using collections, creating reusable files and roles, including and importing playbooks, and running selected parts of a playbook with tags. .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst index ee6ff67fe98..e4c53d59e58 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst @@ -90,7 +90,7 @@ This is inefficient and, at scale, means more maintenance. To incorporate the ve - "ToDo_App" - *my_version -Now, you can re-use the value of ``app_version`` within the value of ``custom_name`` and use the output in a template: +Now, you can reuse the value of ``app_version`` within the value of ``custom_name`` and use the output in a template: .. code-block:: yaml diff --git a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst index ab2e7a73b2a..31ad1136239 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst @@ -287,10 +287,10 @@ You can provide your own facts, as described in :ref:`developing_modules`. To r .. _when_with_reuse: -Conditionals with re-use +Conditionals with reuse ------------------------ -You can use conditionals with re-usable tasks files, playbooks, or roles. Ansible executes these conditional statements differently for dynamic re-use (includes) and for static re-use (imports). See :ref:`playbooks_reuse` for more information on re-use in Ansible. +You can use conditionals with reusable tasks files, playbooks, or roles. Ansible executes these conditional statements differently for dynamic reuse (includes) and for static reuse (imports). See :ref:`playbooks_reuse` for more information on reuse in Ansible. .. _conditional_imports: @@ -359,7 +359,7 @@ When you use a conditional on an ``include_*`` statement, the condition is appli .. code-block:: yaml - # Includes let you re-use a file to define a variable when it is not already defined + # Includes let you reuse a file to define a variable when it is not already defined # main.yml - include_tasks: other_tasks.yml diff --git a/docs/docsite/rst/playbook_guide/playbooks_environment.rst b/docs/docsite/rst/playbook_guide/playbooks_environment.rst index d347812b9c2..c4ec680dbe9 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_environment.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_environment.rst @@ -31,7 +31,7 @@ You can set the environment directly at the task level. environment: http_proxy: http://proxy.example.com:8080 -You can re-use environment settings by defining them as variables in your play and accessing them in a task as you would access any stored Ansible variable. +You can reuse environment settings by defining them as variables in your play and accessing them in a task as you would access any stored Ansible variable. .. code-block:: yaml @@ -51,7 +51,7 @@ You can re-use environment settings by defining them as variables in your play a state: present environment: "{{ proxy_env }}" -You can store environment settings for re-use in multiple playbooks by defining them in a group_vars file. +You can store environment settings for reuse in multiple playbooks by defining them in a group_vars file. .. code-block:: yaml diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index 5aa5f11ce9a..e99ab1dd5a2 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -517,7 +517,7 @@ recursive list_merge Is a string, its possible values are ``replace`` (default), ``keep``, ``append``, ``prepend``, ``append_rp`` or ``prepend_rp``. - It modifies the behaviour of :ansplugin:`ansible.builtin.combine#filter` when the hashes to merge contain arrays/lists. + It modifies the behavior of :ansplugin:`ansible.builtin.combine#filter` when the hashes to merge contain arrays/lists. .. code-block:: yaml diff --git a/docs/docsite/rst/playbook_guide/playbooks_intro.rst b/docs/docsite/rst/playbook_guide/playbooks_intro.rst index 6aa5a8117d7..280097a359e 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_intro.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_intro.rst @@ -5,7 +5,7 @@ Ansible playbooks ***************** -Ansible Playbooks offer a repeatable, re-usable, simple configuration management and multi-machine deployment system, one that is well suited to deploying complex applications. If you need to execute a task with Ansible more than once, write a playbook and put it under source control. Then you can use the playbook to push out new configuration or confirm the configuration of remote systems. The playbooks in the `ansible-examples repository `_ illustrate many useful techniques. You may want to look at these in another tab as you read the documentation. +Ansible Playbooks offer a repeatable, reusable, simple configuration management and multi-machine deployment system, one that is well suited to deploying complex applications. If you need to execute a task with Ansible more than once, write a playbook and put it under source control. Then you can use the playbook to push out new configuration or confirm the configuration of remote systems. The playbooks in the `ansible-examples repository `_ illustrate many useful techniques. You may want to look at these in another tab as you read the documentation. Playbooks can: diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse.rst index d4e42d8ac20..70a3b57f2be 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse.rst @@ -4,19 +4,19 @@ Re-using Ansible artifacts ************************** -You can write a simple playbook in one very large file, and most users learn the one-file approach first. However, breaking your automation work up into smaller files is an excellent way to organize complex sets of tasks and reuse them. Smaller, more distributed artifacts let you re-use the same variables, tasks, and plays in multiple playbooks to address different use cases. You can use distributed artifacts across multiple parent playbooks or even multiple times within one playbook. For example, you might want to update your customer database as part of several different playbooks. If you put all the tasks related to updating your database in a tasks file or a role, you can re-use them in many playbooks while only maintaining them in one place. +You can write a simple playbook in one very large file, and most users learn the one-file approach first. However, breaking your automation work up into smaller files is an excellent way to organize complex sets of tasks and reuse them. Smaller, more distributed artifacts let you reuse the same variables, tasks, and plays in multiple playbooks to address different use cases. You can use distributed artifacts across multiple parent playbooks or even multiple times within one playbook. For example, you might want to update your customer database as part of several different playbooks. If you put all the tasks related to updating your database in a tasks file or a role, you can reuse them in many playbooks while only maintaining them in one place. .. contents:: :local: -Creating re-usable files and roles +Creating reusable files and roles ================================== -Ansible offers four distributed, re-usable artifacts: variables files, task files, playbooks, and roles. +Ansible offers four distributed, reusable artifacts: variables files, task files, playbooks, and roles. - A variables file contains only variables. - A task file contains only tasks. - - A playbook contains at least one play, and may contain variables, tasks, and other content. You can re-use tightly focused playbooks, but you can only re-use them statically, not dynamically. + - A playbook contains at least one play, and may contain variables, tasks, and other content. You can reuse tightly focused playbooks, but you can only reuse them statically, not dynamically. - A role contains a set of related tasks, variables, defaults, handlers, and even modules or other plugins in a defined file-tree. Unlike variables files, task files, or playbooks, roles can be easily uploaded and shared through Ansible Galaxy. See :ref:`playbooks_reuse_roles` for details about creating and using roles. .. versionadded:: 2.4 @@ -24,7 +24,7 @@ Ansible offers four distributed, re-usable artifacts: variables files, task file Re-using playbooks ================== -You can incorporate multiple playbooks into a main playbook. However, you can only use imports to re-use playbooks. For example: +You can incorporate multiple playbooks into a main playbook. However, you can only use imports to reuse playbooks. For example: .. code-block:: yaml @@ -52,15 +52,15 @@ For some use cases, simple playbooks work well. However, starting at a certain l Re-using files and roles ======================== -Ansible offers two ways to re-use files and roles in a playbook: dynamic and static. +Ansible offers two ways to reuse files and roles in a playbook: dynamic and static. - - For dynamic re-use, add an ``include_*`` task in the tasks section of a play: + - For dynamic reuse, add an ``include_*`` task in the tasks section of a play: - :ref:`include_role ` - :ref:`include_tasks ` - :ref:`include_vars ` - - For static re-use, add an ``import_*`` task in the tasks section of a play: + - For static reuse, add an ``import_*`` task in the tasks section of a play: - :ref:`import_role ` - :ref:`import_tasks ` @@ -69,8 +69,8 @@ Task include and import statements can be used at arbitrary depth. You can still use the bare :ref:`roles ` keyword at the play level to incorporate a role in a playbook statically. However, the bare :ref:`include ` keyword, once used for both task files and playbook-level includes, is now deprecated. -Includes: dynamic re-use ------------------------- +Includes: dynamic reuse +----------------------- Including roles, tasks, or variables adds them to a playbook dynamically. Ansible processes included files and roles as they come up in a playbook, so included tasks can be affected by the results of earlier tasks within the top-level playbook. Included roles and tasks are similar to handlers - they may or may not run, depending on the results of other tasks in the top-level playbook. @@ -80,8 +80,8 @@ The file names for included roles, tasks, and vars are templated before inclusio You can pass variables into includes. See :ref:`ansible_variable_precedence` for more details on variable inheritance and precedence. -Imports: static re-use ----------------------- +Imports: static reuse +--------------------- Importing roles, tasks, or playbooks adds them to a playbook statically. Ansible pre-processes imported files and roles before it runs any tasks in a playbook, so imported content is never affected by other tasks within the top-level playbook. @@ -108,10 +108,10 @@ See :ref:`ansible_variable_precedence` for more details on variable inheritance .. _dynamic_vs_static: -Comparing includes and imports: dynamic and static re-use ------------------------------------------------------------- +Comparing includes and imports: dynamic and static reuse +-------------------------------------------------------- -Each approach to re-using distributed Ansible artifacts has advantages and limitations. You may choose dynamic re-use for some playbooks and static re-use for others. Although you can use both dynamic and static re-use in a single playbook, it is best to select one approach per playbook. Mixing static and dynamic re-use can introduce difficult-to-diagnose bugs into your playbooks. This table summarizes the main differences so you can choose the best approach for each playbook you create. +Each approach to re-using distributed Ansible artifacts has advantages and limitations. You may choose dynamic reuse for some playbooks and static reuse for others. Although you can use both dynamic and static reuse in a single playbook, it is best to select one approach per playbook. Mixing static and dynamic reuse can introduce difficult-to-diagnose bugs into your playbooks. This table summarizes the main differences so you can choose the best approach for each playbook you create. .. table:: :class: documentation-table @@ -119,7 +119,7 @@ Each approach to re-using distributed Ansible artifacts has advantages and limit ========================= ======================================== ======================================== .. Include_* Import_* ========================= ======================================== ======================================== - Type of re-use Dynamic Static + Type of reuse Dynamic Static When processed At runtime, when encountered Pre-processed during playbook parsing @@ -168,12 +168,12 @@ You can also use includes and imports in the :ref:`handlers` section of a playbo name: mysql state: restarted -You can trigger handlers from either an import or an include, but the procedure is different for each method of re-use. If you include the file, you must notify the include itself, which triggers all the tasks in ``restarts.yml``. If you import the file, you must notify the individual task(s) within ``restarts.yml``. You can mix direct tasks and handlers with included or imported tasks and handlers. +You can trigger handlers from either an import or an include, but the procedure is different for each method of reuse. If you include the file, you must notify the include itself, which triggers all the tasks in ``restarts.yml``. If you import the file, you must notify the individual task(s) within ``restarts.yml``. You can mix direct tasks and handlers with included or imported tasks and handlers. Triggering included (dynamic) handlers -------------------------------------- -Includes are executed at run-time, so the name of the include exists during play execution, but the included tasks do not exist until the include itself is triggered. To use the ``Restart apache`` task with dynamic re-use, refer to the name of the include itself. This approach triggers all tasks in the included file as handlers. For example, with the task file shown above: +Includes are executed at run-time, so the name of the include exists during play execution, but the included tasks do not exist until the include itself is triggered. To use the ``Restart apache`` task with dynamic reuse, refer to the name of the include itself. This approach triggers all tasks in the included file as handlers. For example, with the task file shown above: .. code-block:: yaml @@ -189,7 +189,7 @@ Includes are executed at run-time, so the name of the include exists during play Triggering imported (static) handlers ------------------------------------- -Imports are processed before the play begins, so the name of the import no longer exists during play execution, but the names of the individual imported tasks do exist. To use the ``Restart apache`` task with static re-use, refer to the name of each task or tasks within the imported file. For example, with the task file shown above: +Imports are processed before the play begins, so the name of the import no longer exists during play execution, but the names of the individual imported tasks do exist. To use the ``Restart apache`` task with static reuse, refer to the name of each task or tasks within the imported file. For example, with the task file shown above: .. code-block:: yaml diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst index 1b6509f9336..7d29a7d79eb 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst @@ -94,7 +94,7 @@ You add tags to includes the same way you add tags to any other task: --- # file: roles/common/tasks/main.yml - - name: Dynamic re-use of database tasks + - name: Dynamic reuse of database tasks include_tasks: db.yml tags: db @@ -111,7 +111,7 @@ You can add a tag only to the dynamic include of a role. In this example, the `` tags: - foo -With plays, blocks, the ``role`` keyword, and static imports, Ansible applies tag inheritance, adding the tags you define to every task inside the play, block, role, or imported file. However, tag inheritance does *not* apply to dynamic re-use with ``include_role`` and ``include_tasks``. With dynamic re-use (includes), the tags you define apply only to the include itself. If you need tag inheritance, use a static import. If you cannot use an import because the rest of your playbook uses includes, see :ref:`apply_keyword` for ways to work around this behavior. +With plays, blocks, the ``role`` keyword, and static imports, Ansible applies tag inheritance, adding the tags you define to every task inside the play, block, role, or imported file. However, tag inheritance does *not* apply to dynamic reuse with ``include_role`` and ``include_tasks``. With dynamic reuse (includes), the tags you define apply only to the include itself. If you need tag inheritance, use a static import. If you cannot use an import because the rest of your playbook uses includes, see :ref:`apply_keyword` for ways to work around this behavior. .. _tag_inheritance: @@ -251,9 +251,9 @@ You can also apply a tag or tags to all the tasks imported by the static ``impor Tag inheritance for includes: blocks and the ``apply`` keyword ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -By default, Ansible does not apply :ref:`tag inheritance ` to dynamic re-use with ``include_role`` and ``include_tasks``. If you add tags to an include, they apply only to the include itself, not to any tasks in the included file or role. This allows you to execute selected tasks within a role or task file - see :ref:`selective_reuse` when you run your playbook. +By default, Ansible does not apply :ref:`tag inheritance ` to dynamic reuse with ``include_role`` and ``include_tasks``. If you add tags to an include, they apply only to the include itself, not to any tasks in the included file or role. This allows you to execute selected tasks within a role or task file - see :ref:`selective_reuse` when you run your playbook. -If you want tag inheritance, you probably want to use imports. However, using both includes and imports in a single playbook can lead to difficult-to-diagnose bugs. For this reason, if your playbook uses ``include_*`` to re-use roles or tasks, and you need tag inheritance on one include, Ansible offers two workarounds. You can use the ``apply`` keyword: +If you want tag inheritance, you probably want to use imports. However, using both includes and imports in a single playbook can lead to difficult-to-diagnose bugs. For this reason, if your playbook uses ``include_*`` to reuse roles or tasks, and you need tag inheritance on one include, Ansible offers two workarounds. You can use the ``apply`` keyword: .. code-block:: yaml @@ -381,7 +381,7 @@ These command-line flags have one limitation: they cannot show tags or tasks wit .. _selective_reuse: -Selectively running tagged tasks in re-usable files +Selectively running tagged tasks in reusable files --------------------------------------------------- If you have a role or a tasks file with tags defined at the task or block level, you can selectively run or skip those tagged tasks in a playbook if you use a dynamic include instead of a static import. You must use the same tag on the included tasks and on the include statement itself. For example you might create a file with some tagged and some untagged tasks: diff --git a/docs/docsite/rst/playbook_guide/playbooks_variables.rst b/docs/docsite/rst/playbook_guide/playbooks_variables.rst index 7c1812a4e1f..52674d77642 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_variables.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_variables.rst @@ -4,7 +4,7 @@ Using Variables *************** -Ansible uses variables to manage differences between systems. With Ansible, you can execute tasks and playbooks on multiple different systems with a single command. To represent the variations among those different systems, you can create variables with standard YAML syntax, including lists and dictionaries. You can define these variables in your playbooks, in your :ref:`inventory `, in re-usable :ref:`files ` or :ref:`roles `, or at the command line. You can also create variables during a playbook run by registering the return value or values of a task as a new variable. +Ansible uses variables to manage differences between systems. With Ansible, you can execute tasks and playbooks on multiple different systems with a single command. To represent the variations among those different systems, you can create variables with standard YAML syntax, including lists and dictionaries. You can define these variables in your playbooks, in your :ref:`inventory `, in reusable :ref:`files ` or :ref:`roles `, or at the command line. You can also create variables during a playbook run by registering the return value or values of a task as a new variable. After you create variables, either by defining them in a file, passing them at the command line, or registering the return value or values of a task as a new variable, you can use those variables in module arguments, in :ref:`conditional "when" statements `, in :ref:`templates `, and in :ref:`loops `. The `ansible-examples github repository `_ contains many examples of using variables in Ansible. diff --git a/docs/docsite/rst/scenario_guides/guide_aci.rst b/docs/docsite/rst/scenario_guides/guide_aci.rst index be5aa770929..499863e3d46 100644 --- a/docs/docsite/rst/scenario_guides/guide_aci.rst +++ b/docs/docsite/rst/scenario_guides/guide_aci.rst @@ -231,7 +231,7 @@ Every Ansible ACI module accepts the following parameters that influence the mod Proxy support ............. -By default, if an environment variable ``_proxy`` is set on the target host, requests will be sent through that proxy. This behaviour can be overridden by setting a variable for this task (see :ref:`playbooks_environment`), or by using the ``use_proxy`` module parameter. +By default, if an environment variable ``_proxy`` is set on the target host, requests will be sent through that proxy. This behavior can be overridden by setting a variable for this task (see :ref:`playbooks_environment`), or by using the ``use_proxy`` module parameter. HTTP redirects can redirect from HTTP to HTTPS so ensure that the proxy environment for both protocols is correctly configured. @@ -623,7 +623,7 @@ All below issues either have been reported to the vendor, and most can simply be Specific requests are known to not be idempotent (`#35050 `_) - The behaviour of the APIC is inconsistent to the use of ``status="created"`` and ``status="deleted"``. The result is that when you use ``status="created"`` in your payload the resulting tasks are not idempotent and creation will fail when the object was already created. However this is not the case with ``status="deleted"`` where such call to an non-existing object does not cause any failure whatsoever. + The behavior of the APIC is inconsistent to the use of ``status="created"`` and ``status="deleted"``. The result is that when you use ``status="created"`` in your payload the resulting tasks are not idempotent and creation will fail when the object was already created. However this is not the case with ``status="deleted"`` where such call to an non-existing object does not cause any failure whatsoever. **NOTE:** A workaround is to avoid using ``status="created"`` and instead use ``status="modified"`` when idempotency is essential to your workflow.. diff --git a/docs/docsite/rst/scenario_guides/guide_scaleway.rst b/docs/docsite/rst/scenario_guides/guide_scaleway.rst index 0baf58a5e26..354daddcf1e 100644 --- a/docs/docsite/rst/scenario_guides/guide_scaleway.rst +++ b/docs/docsite/rst/scenario_guides/guide_scaleway.rst @@ -50,7 +50,7 @@ How to add an SSH key? ====================== Connection to Scaleway Compute nodes use Secure Shell. -SSH keys are stored at the account level, which means that you can re-use the same SSH key in multiple nodes. +SSH keys are stored at the account level, which means that you can reuse the same SSH key in multiple nodes. The first step to configure Scaleway compute resources is to have at least one SSH key configured. :ref:`scaleway_sshkey_module` is a module that manages SSH keys on your Scaleway account. diff --git a/docs/docsite/rst/vault_guide/vault_using_encrypted_content.rst b/docs/docsite/rst/vault_guide/vault_using_encrypted_content.rst index 3d883f56442..e4b12bfc953 100644 --- a/docs/docsite/rst/vault_guide/vault_using_encrypted_content.rst +++ b/docs/docsite/rst/vault_guide/vault_using_encrypted_content.rst @@ -154,7 +154,7 @@ The vaulttext is a concatenation of the ciphertext and a SHA256 digest with the hexlify()'ed result of: - hexlify()'ed string of the salt, followed by a newline (``0x0a``) -- hexlify()'ed string of the crypted HMAC, followed by a newline. The HMAC is: +- hexlify()'ed string of the encrypted HMAC, followed by a newline. The HMAC is: - a `RFC2104 `_ style HMAC diff --git a/noxfile.py b/noxfile.py index cc7e39bc507..880fbf4bc93 100644 --- a/noxfile.py +++ b/noxfile.py @@ -56,11 +56,25 @@ def typing(session: nox.Session): session.run("mypy", *session.posargs, *LINT_FILES) +@nox.session +def spelling(session: nox.Session): + """ + Spell check RST documentation + """ + install(session, req="spelling") + session.run( + "codespell", + "docs/docsite", + *session.posargs, + ) + + @nox.session def lint(session: nox.Session): session.notify("typing") session.notify("static") session.notify("formatters") + session.notify("spelling") requirements_files = list( diff --git a/tests/spelling.in b/tests/spelling.in new file mode 100644 index 00000000000..e3da9e4b090 --- /dev/null +++ b/tests/spelling.in @@ -0,0 +1 @@ +codespell diff --git a/tests/spelling.txt b/tests/spelling.txt new file mode 100644 index 00000000000..1b5e6127689 --- /dev/null +++ b/tests/spelling.txt @@ -0,0 +1,8 @@ +# +# This file is autogenerated by pip-compile with Python 3.10 +# by the following command: +# +# pip-compile --allow-unsafe --output-file=tests/spelling.txt --strip-extras tests/spelling.in +# +codespell==2.2.6 + # via -r tests/spelling.in From 627576e1d58fcb30ff5321330d4d2e6ffbbb7e03 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 17 Oct 2023 07:01:07 -0500 Subject: [PATCH 006/536] .codespellrc: ignore intersphinx inventories (*.inv) (#624) We don't want to spell check these. We have removed the in-repo intersphinx inventories from devel, but they exist on older branches. There's no harm in also including the ignores on devel, and it makes sense to keep the configuration consistent. --- .codespellrc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.codespellrc b/.codespellrc index ee4f01c1e09..f5fa9cc7451 100644 --- a/.codespellrc +++ b/.codespellrc @@ -1,5 +1,5 @@ [codespell] -skip = _build,collections,*.po,_static,porting_guide*,style_guide +skip = _build,collections,*.po,_static,porting_guide*,style_guide,*.inv count = check-filenames = true quiet-level = 3 From 96d5929c8dd03a20d9c5f397a27a4cd43a494b1e Mon Sep 17 00:00:00 2001 From: Anwesha Das Date: Tue, 17 Oct 2023 16:57:34 +0200 Subject: [PATCH 007/536] Add Ansible community 9.0.0a3 porting guide (#625) --- .../rst/porting_guides/porting_guide_9.rst | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index e595b9faa08..708ce6ea88c 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -64,6 +64,28 @@ Networking ========== +Porting Guide for v9.0.0a3 +========================== + +Deprecated Features +------------------- + +Ansible-core +~~~~~~~~~~~~ + +- Old style vars plugins which use the entrypoints `get_host_vars` or `get_group_vars` are deprecated. The plugin should be updated to inherit from `BaseVarsPlugin` and define a `get_vars` method as the entrypoint. + +cisco.ios +~~~~~~~~~ + +- ospfv2 - removed passive_interface to passive_interfaces that supports a list of interfaces + +community.general +~~~~~~~~~~~~~~~~~ + +- The next major release, community.general 8.0.0, will drop support for ansible-core 2.11 and 2.12, which have been End of Life for some time now. This means that this collection no longer supports Python 2.6 on the target. Individual content might still work with unsupported ansible-core versions, but that can change at any time. Also please note that from now on, for every new major community.general release, we will drop support for all ansible-core versions that have been End of Life for more than a few weeks on the date of the major release (https://github.com/ansible-community/community-topics/discussions/271, https://github.com/ansible-collections/community.general/pull/7259). +- redfish_info, redfish_config, redfish_command - the default value ``10`` for the ``timeout`` option is deprecated and will change to ``60`` in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/7295). + Porting Guide for v9.0.0a1 ========================== @@ -80,7 +102,6 @@ Ansible-core - ansible-galaxy - dies in the middle of installing a role when that role contains Java inner classes (files with $ in the file name). This is by design, to exclude temporary or backup files. (https://github.com/ansible/ansible/pull/81553). - ansible-test - The ``pep8`` sanity test is unable to detect f-string spacing issues (E201, E202) on Python 3.10 and 3.11. They are correctly detected under Python 3.12. See (https://github.com/PyCQA/pycodestyle/issues/1190). -- ansible-test - The ``pylint`` sanity test is not supported on Python 3.12. Use Python 3.10 or 3.11 instead. community.crypto ~~~~~~~~~~~~~~~~ @@ -197,6 +218,12 @@ community.vmware - vmware_vasa - added a new module to register/unregister a VASA provider - vmware_vasa_info - added a new module to gather the information about existing VASA provider(s) +fortinet.fortimanager +~~~~~~~~~~~~~~~~~~~~~ + +- Support all FortiManager versions in 6.2, 6.4, 7.0, 7.2 and 7.4. 139 new modules. +- Support token based authentication. + fortinet.fortios ~~~~~~~~~~~~~~~~ From 1efa06b8a68880f63fac0910d5171bfa8e7eeb2f Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 17 Oct 2023 14:35:41 -0500 Subject: [PATCH 008/536] ci: use Github App token to authenticate (#621) This uses the new Ansible Documentation Bot Github app to authenticate with the Github API instead of the limited token built in to Github Actions. The app token allows creating automatic dependency update PRs that trigger CI properly. A github-bot environment to store the BOT_APP_ID and BOT_APP_KEY secrets. Fixes: https://github.com/ansible/ansible-documentation/issues/382 --- .github/workflows/labeler.yml | 9 ++++++++- .github/workflows/pip-compile-dev.yml | 6 ++---- .github/workflows/pip-compile-docs.yml | 6 ++---- .github/workflows/reusable-pip-compile.yml | 17 ++++++++++------- hacking/get_bot_user.sh | 14 ++++++++++++++ 5 files changed, 36 insertions(+), 16 deletions(-) create mode 100755 hacking/get_bot_user.sh diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml index 2c09379cf3b..a8abec2a423 100644 --- a/.github/workflows/labeler.yml +++ b/.github/workflows/labeler.yml @@ -28,6 +28,7 @@ permissions: jobs: label_prs: runs-on: ubuntu-latest + environment: github-bot name: "Label Issue/PR" steps: - name: Print event information @@ -35,6 +36,12 @@ jobs: event_json: "${{ toJSON(github.event) }}" run: | echo "${event_json}" + - name: Generate temp GITHUB_TOKEN + id: create_token + uses: tibdex/github-app-token@v2 + with: + app_id: ${{ secrets.BOT_APP_ID }} + private_key: ${{ secrets.BOT_APP_KEY }} - name: Checkout parent repository uses: actions/checkout@v4 - name: Install Python 3.11 @@ -56,6 +63,6 @@ jobs: if: "github.event.pull_request || inputs.type == 'pr'" env: event_json: "${{ toJSON(github.event) }}" - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_TOKEN: ${{ steps.create_token.outputs.token }} run: ./venv/bin/python hacking/pr_labeler/label.py pr ${{ github.event.number || inputs.number }} diff --git a/.github/workflows/pip-compile-dev.yml b/.github/workflows/pip-compile-dev.yml index 5931b4f4481..5f5fd19329e 100644 --- a/.github/workflows/pip-compile-dev.yml +++ b/.github/workflows/pip-compile-dev.yml @@ -23,10 +23,6 @@ name: "Refresh dev dependencies" - ".github/workflows/pip-compile-dev.yml" - "tests/*.in" -permissions: - pull-requests: write - contents: write - jobs: refresh: name: "Refresh dev dependencies" @@ -41,3 +37,5 @@ jobs: 'pip-compile-3.10(static)' 'pip-compile-3.10(spelling)' reset-branch: "${{ inputs.reset-branch || false }}" + secrets: inherit + environment: github-bot diff --git a/.github/workflows/pip-compile-docs.yml b/.github/workflows/pip-compile-docs.yml index 00585e79422..456dc723f93 100644 --- a/.github/workflows/pip-compile-docs.yml +++ b/.github/workflows/pip-compile-docs.yml @@ -23,10 +23,6 @@ name: "Refresh docs build dependencies" - ".github/workflows/pip-compile-docs.yml" - "tests/*.in" -permissions: - pull-requests: write - contents: write - jobs: refresh: name: "Refresh docs build dependencies" @@ -37,3 +33,5 @@ jobs: pr-branch: "${{ inputs.pr-branch || 'pip-compile/devel/docs' }}" nox-args: "-e 'pip-compile-3.10(requirements)' 'pip-compile-3.10(requirements-relaxed)'" reset-branch: "${{ inputs.reset-branch || false }}" + secrets: inherit + environment: github-bot diff --git a/.github/workflows/reusable-pip-compile.yml b/.github/workflows/reusable-pip-compile.yml index 88e9dd8fd07..1d08d2f725f 100644 --- a/.github/workflows/reusable-pip-compile.yml +++ b/.github/workflows/reusable-pip-compile.yml @@ -54,19 +54,23 @@ name: "Refresh pinned dependencies" type: boolean default: false -permissions: - pull-requests: write - contents: write - jobs: refresh: runs-on: ubuntu-latest + environment: github-bot steps: + - name: Generate temp GITHUB_TOKEN + id: create_token + uses: tibdex/github-app-token@v2 + with: + app_id: ${{ secrets.BOT_APP_ID }} + private_key: ${{ secrets.BOT_APP_KEY }} - name: Check out repo uses: actions/checkout@v4 with: fetch-depth: 0 ref: "${{ inputs.base-branch }}" + token: "${{ steps.create_token.outputs.token }}" - name: Fetch required contents of ansible-core run: | python docs/bin/clone-core.py @@ -76,8 +80,7 @@ jobs: python-versions: "3.9" - name: Set up git committer run: | - git config user.name "Github Actions" - git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + hacking/get_bot_user.sh "ansible-documentation-bot" "Ansible Documentation Bot" - name: "Use a branch named ${{ inputs.pr-branch }}" id: branch run: | @@ -99,7 +102,7 @@ jobs: nox ${{ inputs.nox-args }} - name: Push new dependency versions and create a PR env: - GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" + GITHUB_TOKEN: ${{ steps.create_token.outputs.token }} run: | set -x git diff || : diff --git a/hacking/get_bot_user.sh b/hacking/get_bot_user.sh new file mode 100755 index 00000000000..3052958deb6 --- /dev/null +++ b/hacking/get_bot_user.sh @@ -0,0 +1,14 @@ +#!/usr/bin/bash -x + +# Set Github committer to a bot user + +set -euo pipefail + +bot="${1}" +name="${2-${1}}" +path="https://api.github.com/users/${bot}%5Bbot%5D" +user_id="$(curl -sS "${path}" | jq -r .id)" +GIT="${GIT:-git}" + +${GIT} config user.name "${name}" +${GIT} config user.email "${user_id}+${bot}@users.noreply.github.com" From 8a8b3b42858cc4bcf4195eaf0db69def6e901b53 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 17 Oct 2023 14:46:10 -0500 Subject: [PATCH 009/536] ci pip-compile: remove duplicate environment key (#633) We apparently need `secrets: inherit` in the caller but not `environment:`. --- .github/workflows/pip-compile-dev.yml | 1 - .github/workflows/pip-compile-docs.yml | 1 - 2 files changed, 2 deletions(-) diff --git a/.github/workflows/pip-compile-dev.yml b/.github/workflows/pip-compile-dev.yml index 5f5fd19329e..93792aa7a3f 100644 --- a/.github/workflows/pip-compile-dev.yml +++ b/.github/workflows/pip-compile-dev.yml @@ -38,4 +38,3 @@ jobs: 'pip-compile-3.10(spelling)' reset-branch: "${{ inputs.reset-branch || false }}" secrets: inherit - environment: github-bot diff --git a/.github/workflows/pip-compile-docs.yml b/.github/workflows/pip-compile-docs.yml index 456dc723f93..c679f8cd79b 100644 --- a/.github/workflows/pip-compile-docs.yml +++ b/.github/workflows/pip-compile-docs.yml @@ -34,4 +34,3 @@ jobs: nox-args: "-e 'pip-compile-3.10(requirements)' 'pip-compile-3.10(requirements-relaxed)'" reset-branch: "${{ inputs.reset-branch || false }}" secrets: inherit - environment: github-bot From 47e2248f8692fd2900c59ea02039eeb6cb9c4a9f Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 17 Oct 2023 14:58:11 -0500 Subject: [PATCH 010/536] ci pr_labeler: also use the app token for issues (#636) `label.py pr` used the app token, but `label.py issue` still used the old builtin GHA token. Oops! --- .github/workflows/labeler.yml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml index a8abec2a423..3affdf14ec5 100644 --- a/.github/workflows/labeler.yml +++ b/.github/workflows/labeler.yml @@ -21,10 +21,6 @@ name: "Triage Issues and PRs" -permissions: - issues: write - pull-requests: write - jobs: label_prs: runs-on: ubuntu-latest @@ -56,7 +52,7 @@ jobs: if: "github.event.issue || inputs.type == 'issue'" env: event_json: "${{ toJSON(github.event) }}" - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_TOKEN: ${{ steps.create_token.outputs.token }} run: ./venv/bin/python hacking/pr_labeler/label.py issue ${{ github.event.issue.number || inputs.number }} - name: "Run the PR labeler" From 90ee733d44f1e414b63153bc45a1e16ab12ee455 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Tue, 17 Oct 2023 15:11:08 -0500 Subject: [PATCH 011/536] ci: refresh dev dependencies (#638) --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 6 ++++-- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 7d5ecae2b9a..6aa9a7aeed4 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==23.9.1 +black==23.10.0 # via -r tests/formatters.in click==8.1.7 # via black diff --git a/tests/static.txt b/tests/static.txt index bfa81aff1ee..cde7dc0519a 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.0.292 +ruff==0.1.0 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index f4586466ced..88e52c7fc35 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -49,7 +49,9 @@ pycparser==2.21 pygithub==2.1.1 # via -r tests/../hacking/pr_labeler/requirements.txt pyjwt==2.8.0 - # via pygithub + # via + # pygithub + # pyjwt pynacl==1.5.0 # via pygithub python-dateutil==2.8.2 @@ -68,7 +70,7 @@ typing-extensions==4.8.0 # mypy # pygithub # typer -urllib3==2.0.6 +urllib3==2.0.7 # via # pygithub # requests From e43d253f6c8ae9a3e40b1c804036112c1bbb654d Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 18 Oct 2023 12:12:25 -0500 Subject: [PATCH 012/536] pr_labeler: stop adding new_triage labels to new PRs (#643) Fixes: https://github.com/ansible/ansible-documentation/issues/628 --- hacking/pr_labeler/label.py | 1 - 1 file changed, 1 deletion(-) diff --git a/hacking/pr_labeler/label.py b/hacking/pr_labeler/label.py index 6a4b4ba10ce..118b281a67f 100644 --- a/hacking/pr_labeler/label.py +++ b/hacking/pr_labeler/label.py @@ -268,7 +268,6 @@ def process_pr( return handle_codeowner_labels(ctx) - add_label_if_new(ctx, "needs_triage") new_contributor_welcome(ctx) no_body_nag(ctx) From 5730ba9a015ca053591e6e277ccc097cb4f02fee Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 4 Oct 2023 18:28:05 +0000 Subject: [PATCH 013/536] pr_labeler: improve create_boilerplate_comment logging --- hacking/pr_labeler/label.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/hacking/pr_labeler/label.py b/hacking/pr_labeler/label.py index 118b281a67f..3ed919cf1fe 100644 --- a/hacking/pr_labeler/label.py +++ b/hacking/pr_labeler/label.py @@ -166,7 +166,10 @@ def create_boilerplate_comment(ctx: IssueOrPrCtx, name: str, **kwargs) -> None: if comment.body.splitlines()[-1] == last: log(ctx, name, "boilerplate was already commented") return - log(ctx, "Templating", name, "boilerplate") + msg = f"Templating {name} boilerplate" + if kwargs: + msg += f" with {kwargs}" + log(ctx, msg) create_comment(ctx, tmpl) From 44ffe0f2105f6154234aa40c2a99c51597c6fd7d Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 4 Oct 2023 18:28:33 +0000 Subject: [PATCH 014/536] pr_labeler: add --force-process-closed flag --- hacking/pr_labeler/label.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/hacking/pr_labeler/label.py b/hacking/pr_labeler/label.py index 3ed919cf1fe..265d4b5e420 100644 --- a/hacking/pr_labeler/label.py +++ b/hacking/pr_labeler/label.py @@ -246,6 +246,7 @@ def process_pr( pr_number: int, dry_run: bool = False, authed_dry_run: bool = False, + force_process_closed: bool = False, ) -> None: global_args = click_ctx.ensure_object(GlobalArgs) @@ -266,7 +267,7 @@ def process_pr( event_info=get_event_info(), issue=pr.as_issue(), ) - if pr.state != "open": + if not force_process_closed and pr.state != "open": log(ctx, "Refusing to process closed ticket") return @@ -282,6 +283,7 @@ def process_issue( issue_number: int, dry_run: bool = False, authed_dry_run: bool = False, + force_process_closed: bool = False, ) -> None: global_args = click_ctx.ensure_object(GlobalArgs) @@ -300,7 +302,7 @@ def process_issue( dry_run=dry_run, event_info=get_event_info(), ) - if issue.state != "open": + if not force_process_closed and issue.state != "open": log(ctx, "Refusing to process closed ticket") return From d2e6625e8bb64bf831eb8b31582c654f5333901a Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 4 Oct 2023 18:29:12 +0000 Subject: [PATCH 015/536] pr_labeler: add warning for porting_guides changes This adds a warning message when PRs are created that edit porting_guides by someone outside of the Release Management WG. These files are automatically generated during the ansible release process and should not be modified. Fixes: https://github.com/ansible/ansible-documentation/issues/503 --- .../pr_labeler/data/porting_guide_changes.md | 8 +++++ hacking/pr_labeler/label.py | 29 +++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 hacking/pr_labeler/data/porting_guide_changes.md diff --git a/hacking/pr_labeler/data/porting_guide_changes.md b/hacking/pr_labeler/data/porting_guide_changes.md new file mode 100644 index 00000000000..0e0cc12e3fe --- /dev/null +++ b/hacking/pr_labeler/data/porting_guide_changes.md @@ -0,0 +1,8 @@ +The following files are automatically generated and should not be modified outside of the ansible release process: + +{% for file in changed_files %} +- {{ file }} +{% endfor %} + +Please double check your changes. + diff --git a/hacking/pr_labeler/label.py b/hacking/pr_labeler/label.py index 265d4b5e420..e13f13c47eb 100644 --- a/hacking/pr_labeler/label.py +++ b/hacking/pr_labeler/label.py @@ -6,6 +6,7 @@ import dataclasses import json import os +import re from collections.abc import Collection from contextlib import suppress from functools import cached_property @@ -26,6 +27,14 @@ LABELS_BY_CODEOWNER: dict[OwnerTuple, list[str]] = { ("TEAM", "@ansible/steering-committee"): ["sc_approval"], } +RELEASE_MANAGEMENT_MEMBERS = { + "anweshadas", + "felixfontein", + "gotmax23", + "mariolenz", + "rooftopcellist", + "webknjaz", +} HERE = Path(__file__).resolve().parent ROOT = HERE.parent.parent CODEOWNERS = (ROOT / ".github/CODEOWNERS").read_text("utf-8") @@ -228,6 +237,25 @@ def no_body_nag(ctx: IssueOrPrCtx) -> None: create_boilerplate_comment(ctx, "no_body_nag.md") +def warn_porting_guide_change(ctx: PRLabelerCtx) -> None: + """ + Complain if a user outside of the Release Management WG changes porting_guide + """ + if ctx.pr.user.login in RELEASE_MANAGEMENT_MEMBERS: + return + matches: list[str] = [] + for file in ctx.pr.get_files(): + if re.fullmatch( + # Match community porting guides but not core porting guides + r"docs/docsite/rst/porting_guides/porting_guide_\d.*.rst", + file.filename, + ): + matches.append(file.filename) + if not matches: + return + create_boilerplate_comment(ctx, "porting_guide_changes.md", changed_files=matches) + + APP = typer.Typer() @@ -274,6 +302,7 @@ def process_pr( handle_codeowner_labels(ctx) new_contributor_welcome(ctx) no_body_nag(ctx) + warn_porting_guide_change(ctx) @APP.command(name="issue") From dddfd7eb55fae94241a8da054ce8245293c8576f Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 17 Oct 2023 21:54:17 +0000 Subject: [PATCH 016/536] pr_labeler: use @release-management-wg team for porting_guide check Instead of hardcoding the list of release managers, we can use the Github API to retrieve the members of the `@ansible/release-management-wg` team. --- hacking/pr_labeler/label.py | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/hacking/pr_labeler/label.py b/hacking/pr_labeler/label.py index e13f13c47eb..6fa0ed97e92 100644 --- a/hacking/pr_labeler/label.py +++ b/hacking/pr_labeler/label.py @@ -27,14 +27,6 @@ LABELS_BY_CODEOWNER: dict[OwnerTuple, list[str]] = { ("TEAM", "@ansible/steering-committee"): ["sc_approval"], } -RELEASE_MANAGEMENT_MEMBERS = { - "anweshadas", - "felixfontein", - "gotmax23", - "mariolenz", - "rooftopcellist", - "webknjaz", -} HERE = Path(__file__).resolve().parent ROOT = HERE.parent.parent CODEOWNERS = (ROOT / ".github/CODEOWNERS").read_text("utf-8") @@ -182,6 +174,18 @@ def create_boilerplate_comment(ctx: IssueOrPrCtx, name: str, **kwargs) -> None: create_comment(ctx, tmpl) +def get_team_members(ctx: IssueOrPrCtx, team: str) -> list[str]: + """ + Get the members of a Github team + """ + return [ + user.login + for user in ctx.client.get_organization(ctx.repo.organization.login) + .get_team_by_slug(team) + .get_members() + ] + + def handle_codeowner_labels(ctx: PRLabelerCtx) -> None: labels = LABELS_BY_CODEOWNER.copy() owners = CodeOwners(CODEOWNERS) @@ -241,8 +245,16 @@ def warn_porting_guide_change(ctx: PRLabelerCtx) -> None: """ Complain if a user outside of the Release Management WG changes porting_guide """ - if ctx.pr.user.login in RELEASE_MANAGEMENT_MEMBERS: + # If the API token does not have permisisons to view teams in the ansible + # org, fall back to an empty list. + members = [] + try: + members = get_team_members(ctx, "release-management-wg") + except github.UnknownObjectException: + log(ctx, "Failed to get members of @ansible/release-management-wg") + if ctx.pr.user.login in members: return + matches: list[str] = [] for file in ctx.pr.get_files(): if re.fullmatch( From 746662c25577a1ba0bbfcac69b2b0ced28d75343 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 18 Oct 2023 02:37:17 +0000 Subject: [PATCH 017/536] pr_labeler: exempt bots from porting_guide check For example, patchback is not a release manager, but we still want it to backport Porting Guide PRs. --- hacking/pr_labeler/label.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/hacking/pr_labeler/label.py b/hacking/pr_labeler/label.py index 6fa0ed97e92..29c4a468071 100644 --- a/hacking/pr_labeler/label.py +++ b/hacking/pr_labeler/label.py @@ -243,8 +243,13 @@ def no_body_nag(ctx: IssueOrPrCtx) -> None: def warn_porting_guide_change(ctx: PRLabelerCtx) -> None: """ - Complain if a user outside of the Release Management WG changes porting_guide + Complain if a non-bot user outside of the Release Management WG changes + porting_guide """ + user = ctx.pr.user.login + if user.endswith("[bot]"): + return + # If the API token does not have permisisons to view teams in the ansible # org, fall back to an empty list. members = [] @@ -252,7 +257,7 @@ def warn_porting_guide_change(ctx: PRLabelerCtx) -> None: members = get_team_members(ctx, "release-management-wg") except github.UnknownObjectException: log(ctx, "Failed to get members of @ansible/release-management-wg") - if ctx.pr.user.login in members: + if user in members: return matches: list[str] = [] From 95ece7e9d6dc8e411dd729fc7c7ef48500c04d15 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 18 Oct 2023 02:45:08 +0000 Subject: [PATCH 018/536] pr_labeler: improve porting_guide_changes template wording Co-authored-by: Sandra McCann --- hacking/pr_labeler/data/porting_guide_changes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hacking/pr_labeler/data/porting_guide_changes.md b/hacking/pr_labeler/data/porting_guide_changes.md index 0e0cc12e3fe..1bab844220d 100644 --- a/hacking/pr_labeler/data/porting_guide_changes.md +++ b/hacking/pr_labeler/data/porting_guide_changes.md @@ -1,8 +1,8 @@ -The following files are automatically generated and should not be modified outside of the ansible release process: +The following files are automatically generated and should not be modified outside of the Ansible release process: {% for file in changed_files %} - {{ file }} {% endfor %} -Please double check your changes. +Please double-check your changes. From 95f1d2d016a0bd76f83d02834ae1f6e736fb5531 Mon Sep 17 00:00:00 2001 From: Harish Rao Date: Thu, 19 Oct 2023 00:15:16 +0530 Subject: [PATCH 019/536] Changed it's to it is in all .rst files (#491) --- docs/docsite/rst/community/contributor_path.rst | 2 +- .../rst/community/documentation_contributions.rst | 4 ++-- .../dev_guide/developing_collections_structure.rst | 2 +- .../rst/dev_guide/developing_modules_checklist.rst | 2 +- .../rst/dev_guide/developing_modules_documenting.rst | 2 +- .../dev_guide/developing_modules_general_windows.rst | 2 +- .../dev_guide/developing_program_flow_modules.rst | 6 +++--- docs/docsite/rst/dev_guide/developing_python_3.rst | 6 +++--- docs/docsite/rst/dev_guide/overview_architecture.rst | 2 +- .../dev_guide/style_guide/grammar_punctuation.rst | 8 ++++---- .../dev_guide/style_guide/spelling_word_choice.rst | 2 +- .../rst/dev_guide/style_guide/voice_style.rst | 2 +- docs/docsite/rst/dev_guide/testing.rst | 2 +- docs/docsite/rst/inventory_guide/intro_inventory.rst | 2 +- .../rst/network/getting_started/first_inventory.rst | 2 +- .../user_guide/network_debug_troubleshooting.rst | 2 +- .../rst/playbook_guide/guide_rolling_upgrade.rst | 8 ++++---- docs/docsite/rst/playbook_guide/playbooks_blocks.rst | 2 +- docs/docsite/rst/playbook_guide/playbooks_loops.rst | 2 +- .../rst/playbook_guide/playbooks_reuse_roles.rst | 2 +- docs/docsite/rst/porting_guides/porting_guide_7.rst | 2 +- docs/docsite/rst/reference_appendices/YAMLSyntax.rst | 6 +++--- docs/docsite/rst/reference_appendices/faq.rst | 6 +++--- docs/docsite/rst/reference_appendices/glossary.rst | 12 ++++++------ .../rst/reference_appendices/test_strategies.rst | 4 ++-- docs/docsite/rst/roadmap/COLLECTIONS_8.rst | 2 +- docs/docsite/rst/roadmap/COLLECTIONS_9.rst | 2 +- docs/docsite/rst/roadmap/ROADMAP_2_5.rst | 2 +- docs/docsite/rst/scenario_guides/guide_azure.rst | 6 +++--- docs/docsite/rst/scenario_guides/guide_gce.rst | 2 +- docs/docsite/rst/scenario_guides/guide_packet.rst | 6 +++--- .../vmware_rest_scenarios/authentication.rst | 2 +- .../vmware_rest_scenarios/create_vm.rst | 2 +- 33 files changed, 58 insertions(+), 58 deletions(-) diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst index 205772c6145..fde8f01230f 100644 --- a/docs/docsite/rst/community/contributor_path.rst +++ b/docs/docsite/rst/community/contributor_path.rst @@ -4,7 +4,7 @@ Contributor path This section describes the contributor's journey from the beginning to becoming a leader who helps shape the future of Ansible. You can use this path as a roadmap for your long-term participation. -Any contribution to the project, even a small one, is very welcome and valuable. Any contribution counts, whether it's feedback on an issue, a pull request, a topic or documentation change, or a coding contribution. When you contribute regularly, your proficiency and judgment in the related area increase and, along with this, the importance of your presence in the project. +Any contribution to the project, even a small one, is very welcome and valuable. Any contribution counts, whether it is feedback on an issue, a pull request, a topic or documentation change, or a coding contribution. When you contribute regularly, your proficiency and judgment in the related area increase and, along with this, the importance of your presence in the project. .. contents:: :local: diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index e3a22ad65e4..18541d36178 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -30,7 +30,7 @@ To submit a documentation PR from docs.ansible.com with ``Edit on GitHub``: #. Enter a commit message in the first rectangle under the heading ``Propose file change`` at the bottom of the GitHub page. The more specific, the better. For example, "fixes typo in my_module description". You can put more detail in the second rectangle if you like. Leave the ``+label: docsite_pr`` there. #. Submit the suggested change by clicking on the green "Propose file change" button. GitHub will handle branching and committing for you, and open a page with the heading "Comparing Changes". #. Click on ``Create pull request`` to open the PR template. -#. Fill out the PR template, including as much detail as appropriate for your change. You can change the title of your PR if you like (by default it's the same as your commit message). In the ``Issue Type`` section, delete all lines except the ``Docs Pull Request`` line. +#. Fill out the PR template, including as much detail as appropriate for your change. You can change the title of your PR if you like (by default it is the same as your commit message). In the ``Issue Type`` section, delete all lines except the ``Docs Pull Request`` line. #. Submit your change by clicking on ``Create pull request`` button. #. Be patient while Ansibot, our automated script, adds labels, pings the docs maintainers, and kicks off a CI testing run. #. Keep an eye on your PR - the docs team may ask you for changes. @@ -66,7 +66,7 @@ If the problem you have noticed is too complex to fix with the ``Edit on GitHub` A great documentation GitHub issue or PR includes: - a specific title -- a detailed description of the problem (even for a PR - it's hard to evaluate a suggested change unless we know what problem it's meant to solve) +- a detailed description of the problem (even for a PR - it is hard to evaluate a suggested change unless we know what problem it is meant to solve) - links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on) diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index 08702f3f038..3c852521db7 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -204,7 +204,7 @@ Ansible Collections are tested much like Ansible itself, by using the `ansible-t See :ref:`testing_collections` for specific information on how to test collections with ``ansible-test``. -When reading the :ref:`developing_testing` documentation, there will be content that applies to running Ansible from source code through a git clone, which is typical of an Ansible developer. However, it's not always typical for an Ansible Collection author to be running Ansible from source but instead from a stable release, and to create Collections it is not necessary to run Ansible from source. Therefore, when references of dealing with `ansible-test` binary paths, command completion, or environment variables are presented throughout the :ref:`developing_testing` documentation; keep in mind that it is not needed for Ansible Collection Testing because the act of installing the stable release of Ansible containing `ansible-test` is expected to setup those things for you. +When reading the :ref:`developing_testing` documentation, there will be content that applies to running Ansible from source code through a git clone, which is typical of an Ansible developer. However, it is not always typical for an Ansible Collection author to be running Ansible from source but instead from a stable release, and to create Collections it is not necessary to run Ansible from source. Therefore, when references of dealing with `ansible-test` binary paths, command completion, or environment variables are presented throughout the :ref:`developing_testing` documentation; keep in mind that it is not needed for Ansible Collection Testing because the act of installing the stable release of Ansible containing `ansible-test` is expected to setup those things for you. .. _meta_runtime_yml: diff --git a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst index 292bb9061f3..c11689f05c3 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst @@ -36,7 +36,7 @@ Please make sure your module meets these requirements before you submit your PR/ Contributing to Ansible: subjective requirements ================================================ -If your module meets these objective requirements, collection maintainers will review your code to see if they think it's clear, concise, secure, and maintainable. They will consider whether your module provides a good user experience, helpful error messages, reasonable defaults, and more. This process is subjective, with no exact standards for acceptance. For the best chance of getting your module accepted, follow our :ref:`tips for module development `. +If your module meets these objective requirements, collection maintainers will review your code to see if they think it is clear, concise, secure, and maintainable. They will consider whether your module provides a good user experience, helpful error messages, reasonable defaults, and more. This process is subjective, with no exact standards for acceptance. For the best chance of getting your module accepted, follow our :ref:`tips for module development `. Other checklists ================ diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index c330e78936f..fc45afbb1cf 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -135,7 +135,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require :options: * Options are often called `parameters` or `arguments`. Because the documentation field is called `options`, we will use that term. - * If the module has no options (for example, it's a ``_facts`` module), all you need is one line: ``options: {}``. + * If the module has no options (for example, it is a ``_facts`` module), all you need is one line: ``options: {}``. * If your module has options (in other words, accepts arguments), each option should be documented thoroughly. For each module option, include: :option-name: diff --git a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst index e51e4a9cc00..1ad3365e1ab 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst @@ -153,7 +153,7 @@ protocols can be access over ``127.0.0.1`` using these forwarded ports: Replace ``xx`` with the entry number in the inventory file where the domain controller started with ``00`` and is incremented from there. For example, in the default ``inventory.yml`` file, WinRM over HTTPS for ``SERVER2012R2`` is -forwarded over port ``29804`` as it's the fourth entry in ``domain_children``. +forwarded over port ``29804`` as it is the fourth entry in ``domain_children``. Windows new module development ============================== diff --git a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst index dd6709242c9..37af41d4b85 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -174,8 +174,8 @@ Executor/task_executor The TaskExecutor receives the module name and parameters that were parsed from the :term:`playbook ` (or from the command-line in the case of -:command:`/usr/bin/ansible`). It uses the name to decide whether it's looking -at a module or an :ref:`Action Plugin `. If it's +:command:`/usr/bin/ansible`). It uses the name to decide whether it is looking +at a module or an :ref:`Action Plugin `. If it is a module, it loads the :ref:`Normal Action Plugin ` and passes the name, variables, and other information about the task and play to that Action Plugin for further processing. @@ -914,7 +914,7 @@ The helper functions ``module.load_file_common_arguments()`` and ``module.set_fs module = AnsibleModule(argument_spec, add_file_common_args=True) changed = False - # TODO do something with module.params['path'], like update it's contents + # TODO do something with module.params['path'], like update its contents # Ensure that module.params['path'] satisfies the file options supplied by the user file_args = module.load_file_common_arguments(module.params) diff --git a/docs/docsite/rst/dev_guide/developing_python_3.rst b/docs/docsite/rst/dev_guide/developing_python_3.rst index 5feea668f2e..f3bece8db54 100644 --- a/docs/docsite/rst/dev_guide/developing_python_3.rst +++ b/docs/docsite/rst/dev_guide/developing_python_3.rst @@ -60,7 +60,7 @@ and text (:class:`str `) more strict. Python 3 will throw an excep trying to combine and compare the two types. The programmer has to explicitly convert from one type to the other to mix values from each. -In Python 3 it's immediately apparent to the programmer when code is +In Python 3 it is immediately apparent to the programmer when code is mixing the byte and text types inappropriately, whereas in Python 2, code that mixes those types may work until a user causes an exception by entering non-ASCII input. Python 3 forces programmers to proactively define a strategy for @@ -95,7 +95,7 @@ Unicode Sandwich common borders: places to convert bytes to text in control node ------------------------------------------------------------------------------------- This is a partial list of places where we have to convert to and from bytes -when using the Unicode Sandwich string strategy. It's not exhaustive but +when using the Unicode Sandwich string strategy. It is not exhaustive but it gives you an idea of where to watch for problems. Reading and writing to files @@ -144,7 +144,7 @@ systems file names are bytes. On Python 2, if we pass a text string to these functions, the text string will be converted to a byte string inside of the function and a traceback will occur if non-ASCII characters are present. In Python 3, a traceback will only occur if the text string can't be decoded in -the current locale, but it's still good to be explicit and have code which +the current locale, but it is still good to be explicit and have code which works on both versions: .. code-block:: python diff --git a/docs/docsite/rst/dev_guide/overview_architecture.rst b/docs/docsite/rst/dev_guide/overview_architecture.rst index 89677e96d9a..fb78da60512 100644 --- a/docs/docsite/rst/dev_guide/overview_architecture.rst +++ b/docs/docsite/rst/dev_guide/overview_architecture.rst @@ -6,7 +6,7 @@ Ansible is a radically simple IT automation engine that automates cloud provisio Being designed for multi-tier deployments since day one, Ansible models your IT infrastructure by describing how all of your systems inter-relate, rather than just managing one system at a time. -It uses no agents and no additional custom security infrastructure, so it's easy to deploy - and most importantly, it uses a very simple language (YAML, in the form of Ansible Playbooks) that allow you to describe your automation jobs in a way that approaches plain English. +It uses no agents and no additional custom security infrastructure, so it is easy to deploy - and most importantly, it uses a very simple language (YAML, in the form of Ansible Playbooks) that allows you to describe your automation jobs in a way that approaches plain English. In this section, we'll give you a really quick overview of how Ansible works so you can see how the pieces fit together. diff --git a/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst b/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst index da06070918d..016de47e9d6 100644 --- a/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst +++ b/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst @@ -16,7 +16,7 @@ Ansible Capitalization ^^^^^^^^^^^^^^ -If it's not a real product, service, or department at Ansible, don't capitalize it. Not even if it seems important. Capitalize only the first letter of the first word in headlines. +If it is not a real product, service, or department at Ansible, don't capitalize it. Not even if it seems important. Capitalize only the first letter of the first word in headlines. Colon ^^^^^ @@ -48,7 +48,7 @@ Use serial commas, the comma before the "and" in a series of three or more items - "Item 1, item 2, and item 3." -It's easier to read that way and helps avoid confusion. The primary exception to this you will see is in PR, where it is traditional not to use serial commas because it is often the style of journalists. +It is easier to read that way and helps avoid confusion. The primary exception to this you will see is in PR, where it is traditional not to use serial commas because it is often the style of journalists. Commas are always important, considering the vast difference in meanings of the following two statements. @@ -145,7 +145,7 @@ Capitalize the first word of each bullet. Unless it is obvious that it is just a * keyboard * mouse -When the bulleted list appears within the context of other copy, (unless it's a straight list like the previous example) add periods, even if the bullets are sentence fragments. Part of the reason behind this is that each bullet is said to complete the original sentence. +When the bulleted list appears within the context of other copy, (unless it is a straight list like the previous example) add periods, even if the bullets are sentence fragments. Part of the reason behind this is that each bullet is said to complete the original sentence. In some cases where the bullets are appearing independently, such as in a poster or a homepage promotion, they do not need periods. @@ -162,7 +162,7 @@ States: Ala., Ariz., Ark., Calif., Colo., Conn., Del., Fla., Ga., Ill., Ind., Ka Numbers ^^^^^^^ -Numbers between one and nine are written out. 10 and above are numerals. The exception to this is writing "4 million" or "4 GB." It's also acceptable to use numerals in tables and charts. +Numbers between one and nine are written out. 10 and above are numerals. The exception to this is writing "4 million" or "4 GB." It is also acceptable to use numerals in tables and charts. Phone Numbers ^^^^^^^^^^^^^ diff --git a/docs/docsite/rst/dev_guide/style_guide/spelling_word_choice.rst b/docs/docsite/rst/dev_guide/style_guide/spelling_word_choice.rst index 8de21e091c6..efddb929e7b 100644 --- a/docs/docsite/rst/dev_guide/style_guide/spelling_word_choice.rst +++ b/docs/docsite/rst/dev_guide/style_guide/spelling_word_choice.rst @@ -57,7 +57,7 @@ Use "using" instead. Can/May ^^^^^^^ -Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If either "can," "could," or "may" apply, use "can" because it's less tentative. +Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If either "can," "could," or "may" apply, use "can" because it is less tentative. CD or cd ^^^^^^^^ diff --git a/docs/docsite/rst/dev_guide/style_guide/voice_style.rst b/docs/docsite/rst/dev_guide/style_guide/voice_style.rst index b15029df2fa..dd241384154 100644 --- a/docs/docsite/rst/dev_guide/style_guide/voice_style.rst +++ b/docs/docsite/rst/dev_guide/style_guide/voice_style.rst @@ -11,7 +11,7 @@ The essence of the Ansible writing style is short sentences that flow naturally - Short sentences show confidence. - Grammar rules are meant to be bent, but only if the reader knows you are doing this. - Choose words with fewer syllables for faster reading and better understanding. -- Think of copy as one-on-one conversations rather than as a speech. It's more difficult to ignore someone who is speaking to you directly. +- Think of copy as one-on-one conversations rather than as a speech. It is more difficult to ignore someone who is speaking to you directly. - When possible, start task-oriented sentences (those that direct a user to do something) with action words. For example: Find software... Contact support... Install the media.... and so forth. Active Voice diff --git a/docs/docsite/rst/dev_guide/testing.rst b/docs/docsite/rst/dev_guide/testing.rst index ca2fca158b8..86ec4c2ccf0 100644 --- a/docs/docsite/rst/dev_guide/testing.rst +++ b/docs/docsite/rst/dev_guide/testing.rst @@ -201,7 +201,7 @@ Run integration tests More information: :ref:`testing_integration` -Any potential issues should be added as comments on the pull request (and it's acceptable to comment if the feature works as well), remembering to include the output of ``ansible --version`` +Any potential issues should be added as comments on the pull request (and it is acceptable to comment if the feature works as well), remembering to include the output of ``ansible --version`` Example: diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index f3fa459220a..f1b359e51d9 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -735,7 +735,7 @@ See also :ref:`sample_setup`, which shows inventory along with playbooks and oth Example: One inventory per environment -------------------------------------- -If you need to manage multiple environments it's sometimes prudent to +If you need to manage multiple environments it is sometimes prudent to have only hosts of a single environment defined per inventory. This way, it is harder to, for example, accidentally change the state of nodes inside the "test" environment when you actually wanted to update diff --git a/docs/docsite/rst/network/getting_started/first_inventory.rst b/docs/docsite/rst/network/getting_started/first_inventory.rst index 384a23d7ef7..5df08538aa2 100644 --- a/docs/docsite/rst/network/getting_started/first_inventory.rst +++ b/docs/docsite/rst/network/getting_started/first_inventory.rst @@ -428,4 +428,4 @@ To see the original value, you can use the debug module. Please note if your YAM For more details on building inventory files, see :ref:`the introduction to inventory`; for more details on ansible-vault, see :ref:`the full Ansible Vault documentation`. -Now that you understand the basics of commands, playbooks, and inventory, it's time to explore some more complex Ansible Network examples. +Now that you understand the basics of commands, playbooks, and inventory, it is time to explore some more complex Ansible Network examples. diff --git a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst index 19d4632a738..77c5dd66324 100644 --- a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst +++ b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst @@ -159,7 +159,7 @@ Isolating an error **Platforms:** Any -As with any effort to troubleshoot it's important to simplify the test case as much as possible. +As with any effort to troubleshoot it is important to simplify the test case as much as possible. For Ansible this can be done by ensuring you are only running against one remote device: diff --git a/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst b/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst index 6dfbd3ac5f1..36fbd736d3e 100644 --- a/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst +++ b/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst @@ -219,7 +219,7 @@ Looking at the playbook, you can see it is made up of two plays. The first play - hosts: monitoring tasks: [] -What's going on here, and why are there no tasks? You might know that Ansible gathers "facts" from the servers before operating upon them. These facts are useful for all sorts of things: networking information, OS/distribution versions, and so on. In our case, we need to know something about all of the monitoring servers in our environment before we perform the update, so this simple play forces a fact-gathering step on our monitoring servers. You will see this pattern sometimes, and it's a useful trick to know. +What's going on here, and why are there no tasks? You might know that Ansible gathers "facts" from the servers before operating upon them. These facts are useful for all sorts of things: networking information, OS/distribution versions, and so on. In our case, we need to know something about all of the monitoring servers in our environment before we perform the update, so this simple play forces a fact-gathering step on our monitoring servers. You will see this pattern sometimes, and it is a useful trick to know. The next part is the update play. The first part looks like this: @@ -229,7 +229,7 @@ The next part is the update play. The first part looks like this: user: root serial: 1 -This is just a normal play definition, operating on the ``webservers`` group. The ``serial`` keyword tells Ansible how many servers to operate on at once. If it's not specified, Ansible will parallelize these operations up to the default "forks" limit specified in the configuration file. But for a zero-downtime rolling upgrade, you may not want to operate on that many hosts at once. If you had just a handful of webservers, you may want to set ``serial`` to 1, for one host at a time. If you have 100, maybe you could set ``serial`` to 10, for ten at a time. +This is just a normal play definition, operating on the ``webservers`` group. The ``serial`` keyword tells Ansible how many servers to operate on at once. If it is not specified, Ansible will parallelize these operations up to the default "forks" limit specified in the configuration file. But for a zero-downtime rolling upgrade, you may not want to operate on that many hosts at once. If you had just a handful of webservers, you may want to set ``serial`` to 1, for one host at a time. If you have 100, maybe you could set ``serial`` to 10, for ten at a time. Here is the next part of the update play: @@ -257,7 +257,7 @@ The ``pre_tasks`` keyword just lets you list tasks to run before the roles are c The ``delegate_to`` and ``loop`` arguments, used together, cause Ansible to loop over each monitoring server and load balancer, and perform that operation (delegate that operation) on the monitoring or load balancing server, "on behalf" of the webserver. In programming terms, the outer loop is the list of web servers, and the inner loop is the list of monitoring servers. -Note that the HAProxy step looks a little complicated. We're using HAProxy in this example because it's freely available, though if you have (for example) an F5 or Netscaler in your infrastructure (or maybe you have an AWS Elastic IP setup?), you can use Ansible modules to communicate with them instead. You might also wish to use other monitoring modules instead of nagios, but this just shows the main goal of the 'pre tasks' section -- take the server out of monitoring, and take it out of rotation. +Note that the HAProxy step looks a little complicated. We're using HAProxy in this example because it is freely available, though if you have (for example) an F5 or Netscaler in your infrastructure (or maybe you have an AWS Elastic IP setup?), you can use Ansible modules to communicate with them instead. You might also wish to use other monitoring modules instead of nagios, but this just shows the main goal of the 'pre tasks' section -- take the server out of monitoring, and take it out of rotation. The next step simply re-applies the proper roles to the web servers. This will cause any configuration management declarations in ``web`` and ``base-apache`` roles to be applied to the web servers, including an update of the web application code itself. We don't have to do it this way--we could instead just purely update the web application, but this is a good example of how roles can be used to reuse tasks: @@ -293,7 +293,7 @@ Again, if you were using a Netscaler or F5 or Elastic Load Balancer, you would j Managing other load balancers ============================= -In this example, we use the simple HAProxy load balancer to front-end the web servers. It's easy to configure and easy to manage. As we have mentioned, Ansible has support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. See the :ref:`working_with_modules` documentation for more information. +In this example, we use the simple HAProxy load balancer to front-end the web servers. It is easy to configure and easy to manage. As we have mentioned, Ansible has support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. See the :ref:`working_with_modules` documentation for more information. For other load balancers, you may need to send shell commands to them (like we do for HAProxy above), or call an API, if your load balancer exposes one. For the load balancers for which Ansible has modules, you may want to run them as a ``local_action`` if they contact an API. You can read more about local actions in the :ref:`playbooks_delegation` section. Should you develop anything interesting for some hardware where there is not a module, it might make for a good contribution! diff --git a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst index b64e084abbc..e9a6fcb0820 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst @@ -206,7 +206,7 @@ These can be inspected in the ``rescue`` section: - name: All is good if the first task failed when: "'/bin/false' in ansible_failed.result.cmd|d([])" fail: - msg: It's still false!!! + msg: It is still false!!! .. note:: diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index b4d30d2fb00..e22c1ccdbfd 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -43,7 +43,7 @@ you would need loop: "{{ lookup('fileglob', '*.txt', wantlist=True) }}" -it's cleaner to keep +it is cleaner to keep .. code-block:: yaml diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index be5698e77a2..d5fe4944fdd 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -283,7 +283,7 @@ role ``meta/argument_specs.yml`` file. All fields are lowercase. :short_description: - * A short, one-line description of the entry point. Ideally, it's a phrase and not a sentence. + * A short, one-line description of the entry point. Ideally, it is a phrase and not a sentence. * The ``short_description`` is displayed by ``ansible-doc -t role -l``. * It also becomes part of the title for the role page in the documentation. * The short description should always be a string and never a list, and should not end in a period. diff --git a/docs/docsite/rst/porting_guides/porting_guide_7.rst b/docs/docsite/rst/porting_guides/porting_guide_7.rst index 9cc35c8fdd2..1daf769befc 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_7.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_7.rst @@ -1181,7 +1181,7 @@ Ansible-core ~~~~~~~~~~~~ - Deprecate ability of lookup plugins to return arbitrary data. Lookup plugins must return lists, failing to do so will be an error in 2.18. (https://github.com/ansible/ansible/issues/77788) -- Encryption - Deprecate use of the Python crypt module due to it's impending removal from Python 3.13 +- Encryption - Deprecate use of the Python crypt module due to its impending removal from Python 3.13 - PlayContext.verbosity is deprecated and will be removed in 2.18. Use ansible.utils.display.Display().verbosity as the single source of truth. - ``DEFAULT_FACT_PATH``, ``DEFAULT_GATHER_SUBSET`` and ``DEFAULT_GATHER_TIMEOUT`` are deprecated and will be removed in 2.18. Use ``module_defaults`` keyword instead. - ``PlayIterator`` - deprecate ``cache_block_tasks`` and ``get_original_task`` which are noop and unused. diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index 13f08ef4c2c..2ef4994932f 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -93,7 +93,7 @@ Ansible doesn't really use these too much, but you can also specify a :ref:`bool Use lowercase 'true' or 'false' for boolean values in dictionaries if you want to be compatible with default yamllint options. Values can span multiple lines using ``|`` or ``>``. Spanning multiple lines using a "Literal Block Scalar" ``|`` will include the newlines and any trailing spaces. -Using a "Folded Block Scalar" ``>`` will fold newlines to spaces; it's used to make what would otherwise be a very long line easier to read and edit. +Using a "Folded Block Scalar" ``>`` will fold newlines to spaces; it is used to make what would otherwise be a very long line easier to read and edit. In either case the indentation will be ignored. Examples are: @@ -223,7 +223,7 @@ If your value starts with a quote the entire value must be quoted, not just part foo: "{{ variable }}/additional/string/literal" foo2: "{{ variable }}\\backslashes\\are\\also\\special\\characters" - foo3: "even if it's just a string literal it must all be quoted" + foo3: "even if it is just a string literal it must all be quoted" Not valid: @@ -235,7 +235,7 @@ In addition to ``'`` and ``"`` there are a number of characters that are special as the first character of an unquoted scalar: ``[] {} > | * & ! % # ` @ ,``. You should also be aware of ``? : -``. In YAML, they are allowed at the beginning of a string if a non-space -character follows, but YAML processor implementations differ, so it's better to use quotes. +character follows, but YAML processor implementations differ, so it is better to use quotes. In Flow Collections, the rules are a bit more strict: diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 13467e8540e..e663e7ba856 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -126,7 +126,7 @@ in addition to any ``ssh_args`` from ``ansible.cfg``, so you do not need to repeat global ``ControlPersist`` settings in ``ansible_ssh_common_args``.) Note that ``ssh -W`` is available only with OpenSSH 5.4 or later. With -older versions, it's necessary to execute ``nc %h:%p`` or some equivalent +older versions, it is necessary to execute ``nc %h:%p`` or some equivalent command on the bastion host. With earlier versions of Ansible, it was necessary to configure a @@ -490,7 +490,7 @@ through a role parameter or other input. Variable names can be built by adding s {{ hostvars[inventory_hostname]['ansible_' ~ which_interface]['ipv4']['address'] }} -The trick about going through hostvars is necessary because it's a dictionary of the entire namespace of variables. ``inventory_hostname`` +The trick about going through hostvars is necessary because it is a dictionary of the entire namespace of variables. ``inventory_hostname`` is a magic variable that indicates the current host you are looping over in the host loop. In the example above, if your interface names have dashes, you must replace them with underscores: @@ -730,7 +730,7 @@ The ``no_log`` attribute can also apply to an entire play: - hosts: all no_log: True -Though this will make the play somewhat difficult to debug. It's recommended that this +Though this will make the play somewhat difficult to debug. It is recommended that this be applied to single tasks only, once a playbook is completed. Note that the use of the ``no_log`` attribute does not prevent data from being shown when debugging Ansible itself through the :envvar:`ANSIBLE_DEBUG` environment variable. diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst index dea37f48c84..b22af1db8f4 100644 --- a/docs/docsite/rst/reference_appendices/glossary.rst +++ b/docs/docsite/rst/reference_appendices/glossary.rst @@ -4,7 +4,7 @@ Glossary The following is a list (and re-explanation) of term definitions used elsewhere in the Ansible documentation. Consult the documentation home page for the full documentation and to see the terms in context, but this should be a good resource -to check your knowledge of Ansible's components and understand how they fit together. It's something you might wish to read for review or +to check your knowledge of Ansible's components and understand how they fit together. It is something you might wish to read for review or when a term comes up on the mailing list. .. glossary:: @@ -115,7 +115,7 @@ when a term comes up on the mailing list. A core software component of Ansible that is the power behind :command:`/usr/bin/ansible` directly -- and corresponds to the invocation of each task in a :term:`playbook `. The - Executor is something Ansible developers may talk about, but it's not + Executor is something Ansible developers may talk about, but it is not really user land vocabulary. Facts @@ -364,7 +364,7 @@ when a term comes up on the mailing list. Playbooks Playbooks are the language by which Ansible orchestrates, configures, administers, or deploys systems. They are called playbooks partially - because it's a sports analogy, and it's supposed to be fun using them. + because it is a sports analogy, and it is supposed to be fun using them. They aren't workbooks :) Plays @@ -394,8 +394,8 @@ when a term comes up on the mailing list. Push Mode - Push mode is the default mode of Ansible. In fact, it's not really - a mode at all -- it's just how Ansible works when you aren't thinking + Push mode is the default mode of Ansible. In fact, it is not really + a mode at all -- it is just how Ansible works when you aren't thinking about it. Push mode allows Ansible to be fine-grained and conduct nodes through complex orchestration processes without waiting for them to check in. @@ -448,7 +448,7 @@ when a term comes up on the mailing list. :term:`Rolling Update` Sudo - Ansible does not require root logins, and since it's daemonless, + Ansible does not require root logins, and since it is daemonless, definitely does not require root level daemons (which can be a security concern in sensitive environments). Ansible can log in and perform many operations wrapped in a sudo command, and can work with diff --git a/docs/docsite/rst/reference_appendices/test_strategies.rst b/docs/docsite/rst/reference_appendices/test_strategies.rst index fa28f76b7f0..8a3c43ed471 100644 --- a/docs/docsite/rst/reference_appendices/test_strategies.rst +++ b/docs/docsite/rst/reference_appendices/test_strategies.rst @@ -15,7 +15,7 @@ we'll go into some patterns for integrating tests of infrastructure and discuss .. note:: This is a chapter about testing the application you are deploying, not the chapter on how to test Ansible modules during development. For that content, please hop over to the Development section. By incorporating a degree of testing into your deployment workflow, there will be fewer surprises when code hits production and, in many cases, -tests can be used in production to prevent failed updates from migrating across an entire installation. Since it's push-based, it's +tests can be used in production to prevent failed updates from migrating across an entire installation. Since it is push-based, it is also very easy to run the steps on the localhost or testing servers. Ansible lets you insert as many checks and balances into your upgrade workflow as you would like to have. The Right Level of Testing @@ -86,7 +86,7 @@ Here's an example of using the URI module to make sure a web service returns: msg: 'service is not happy' when: "'AWESOME' not in webpage.content" -It's easy to push an arbitrary script (in any language) on a remote host and the script will automatically fail if it has a non-zero return code: +It is easy to push an arbitrary script (in any language) on a remote host and the script will automatically fail if it has a non-zero return code: .. code:: yaml diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_8.rst b/docs/docsite/rst/roadmap/COLLECTIONS_8.rst index d8da0d6459c..792dc6ca47c 100644 --- a/docs/docsite/rst/roadmap/COLLECTIONS_8.rst +++ b/docs/docsite/rst/roadmap/COLLECTIONS_8.rst @@ -48,7 +48,7 @@ Release schedule .. note:: - In general, it's in the discretion of the release manager to delay a release by 1-2 days for reasons such as personal (schedule) problems, technical problems (CI/infrastructure breakdown), and so on. + In general, it is in the discretion of the release manager to delay a release by 1-2 days for reasons such as personal (schedule) problems, technical problems (CI/infrastructure breakdown), and so on. However, in case two releases are planned for the same day, a release of the latest stable version takes precedence. This means that if a stable Ansible 8 release collides with a pre-release of Ansible 9, the latter will be delayed. If a Ansible 8 release collides with a stable Ansible 9 release, including 9.0.0, the Ansible 8 release will be delayed. diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_9.rst b/docs/docsite/rst/roadmap/COLLECTIONS_9.rst index db644263eb8..242e6549bed 100644 --- a/docs/docsite/rst/roadmap/COLLECTIONS_9.rst +++ b/docs/docsite/rst/roadmap/COLLECTIONS_9.rst @@ -48,7 +48,7 @@ Release schedule .. note:: - In general, it's in the discretion of the release manager to delay a release by 1-2 days for reasons such as personal (schedule) problems, technical problems (CI/infrastructure breakdown), and so on. + In general, it is in the discretion of the release manager to delay a release by 1-2 days for reasons such as personal (schedule) problems, technical problems (CI/infrastructure breakdown), and so on. However, in case two releases are planned for the same day, a release of the latest stable version takes precedence. This means that if a stable Ansible 9 release collides with a pre-release of Ansible 10, the latter will be delayed. If a Ansible 9 release collides with a stable Ansible 10 release, including 10.0.0, the Ansible 9 release will be delayed. diff --git a/docs/docsite/rst/roadmap/ROADMAP_2_5.rst b/docs/docsite/rst/roadmap/ROADMAP_2_5.rst index 75f4fdee6d3..0b5b8a45cb8 100644 --- a/docs/docsite/rst/roadmap/ROADMAP_2_5.rst +++ b/docs/docsite/rst/roadmap/ROADMAP_2_5.rst @@ -74,7 +74,7 @@ Windows - logontype - elevation behavior - Convert win_updates to action plugin for auto reboot and extra features **(done)** -- Spike out changing the connection over to PSRP instead of WSMV **(done- it's possible)** +- Spike out changing the connection over to PSRP instead of WSMV **(done- it is possible)** - Module updates - win_updates **(done)** diff --git a/docs/docsite/rst/scenario_guides/guide_azure.rst b/docs/docsite/rst/scenario_guides/guide_azure.rst index 41bdab3c24f..5e7dc578a1e 100644 --- a/docs/docsite/rst/scenario_guides/guide_azure.rst +++ b/docs/docsite/rst/scenario_guides/guide_azure.rst @@ -49,7 +49,7 @@ After stepping through the tutorial you will have: * Your Client ID, which is found in the "client id" box in the "Configure" page of your application in the Azure portal * Your Secret key, generated when you created the application. You cannot show the key after creation. If you lost the key, you must create a new one in the "Configure" page of your application. -* And finally, a tenant ID. It's a UUID (for example, ABCDEFGH-1234-ABCD-1234-ABCDEFGHIJKL) pointing to the AD containing your +* And finally, a tenant ID. It is a UUID (for example, ABCDEFGH-1234-ABCD-1234-ABCDEFGHIJKL) pointing to the AD containing your application. You will find it in the URL from within the Azure portal, or in the "view endpoints" of any given URL. @@ -98,7 +98,7 @@ To pass Active Directory username/password in ADFS through the environment, defi * AZURE_TENANT * AZURE_ADFS_AUTHORITY_URL -"AZURE_ADFS_AUTHORITY_URL" is optional. It's necessary only when you have own ADFS authority like https://yourdomain.com/adfs. +"AZURE_ADFS_AUTHORITY_URL" is optional. It is necessary only when you have own ADFS authority like https://yourdomain.com/adfs. Storing in a File ````````````````` @@ -144,7 +144,7 @@ Or, pass the following parameters for ADFS username/password: * tenant * adfs_authority_url -"adfs_authority_url" is optional. It's necessary only when you have own ADFS authority like https://yourdomain.com/adfs. +"adfs_authority_url" is optional. It is necessary only when you have own ADFS authority like https://yourdomain.com/adfs. Other Cloud Environments diff --git a/docs/docsite/rst/scenario_guides/guide_gce.rst b/docs/docsite/rst/scenario_guides/guide_gce.rst index 737537d7cfc..7e98d026d51 100644 --- a/docs/docsite/rst/scenario_guides/guide_gce.rst +++ b/docs/docsite/rst/scenario_guides/guide_gce.rst @@ -59,7 +59,7 @@ Similarly, for Ubuntu (>= 22.04) (and Debian), install the ``python3-google-auth Credentials ----------- -It's easy to create a GCP account with credentials for Ansible. You have multiple options to +It is easy to create a GCP account with credentials for Ansible. You have multiple options to get your credentials - here are two of the most common options: * Service Accounts (Recommended): Use JSON service accounts with specific permissions. diff --git a/docs/docsite/rst/scenario_guides/guide_packet.rst b/docs/docsite/rst/scenario_guides/guide_packet.rst index 512620c2454..839515a5fda 100644 --- a/docs/docsite/rst/scenario_guides/guide_packet.rst +++ b/docs/docsite/rst/scenario_guides/guide_packet.rst @@ -21,7 +21,7 @@ The Packet modules and inventory script connect to the Packet API using the pack $ pip install packet-python -In order to check the state of devices created by Ansible on Packet, it's a good idea to install one of the `Packet CLI clients `_. Otherwise you can check them through the `Packet portal `_. +In order to check the state of devices created by Ansible on Packet, it is a good idea to install one of the `Packet CLI clients `_. Otherwise you can check them through the `Packet portal `_. To use the modules and inventory script you'll need a Packet API token. You can generate an API token through the Packet portal `here `__. The simplest way to authenticate yourself is to set the Packet API token in an environment variable: @@ -31,7 +31,7 @@ To use the modules and inventory script you'll need a Packet API token. You can If you're not comfortable exporting your API token, you can pass it as a parameter to the modules. -On Packet, devices and reserved IP addresses belong to `projects `_. In order to use the packet_device module, you need to specify the UUID of the project in which you want to create or manage devices. You can find a project's UUID in the Packet portal `here `_ (it's just under the project table) or through one of the available `CLIs `_. +On Packet, devices and reserved IP addresses belong to `projects `_. In order to use the packet_device module, you need to specify the UUID of the project in which you want to create or manage devices. You can find a project's UUID in the Packet portal `here `_ (it is just under the project table) or through one of the available `CLIs `_. If you want to use a new SSH key pair in this tutorial, you can generate it to ``./id_rsa`` and ``./id_rsa.pub`` as: @@ -185,7 +185,7 @@ As with most Ansible modules, the default states of the Packet modules are idemp The second module call provisions 3 Packet Type 0 (specified using the 'plan' parameter) servers in the project identified by the 'project_id' parameter. The servers are all provisioned with CoreOS beta (the 'operating_system' parameter) and are customized with cloud-config user data passed to the 'user_data' parameter. -The ``packet_device`` module has a ``wait_for_public_IPv`` that is used to specify the version of the IP address to wait for (valid values are ``4`` or ``6`` for IPv4 or IPv6). If specified, Ansible will wait until the GET API call for a device contains an Internet-routeable IP address of the specified version. When referring to an IP address of a created device in subsequent module calls, it's wise to use the ``wait_for_public_IPv`` parameter, or ``state: active`` in the packet_device module call. +The ``packet_device`` module has a ``wait_for_public_IPv`` that is used to specify the version of the IP address to wait for (valid values are ``4`` or ``6`` for IPv4 or IPv6). If specified, Ansible will wait until the GET API call for a device contains an Internet-routeable IP address of the specified version. When referring to an IP address of a created device in subsequent module calls, it is wise to use the ``wait_for_public_IPv`` parameter, or ``state: active`` in the packet_device module call. Run the playbook: diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/authentication.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/authentication.rst index 4f09cbe1012..5c778e429c4 100644 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/authentication.rst +++ b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/authentication.rst @@ -41,7 +41,7 @@ All the vcenter_rest modules accept the following arguments: Ignore SSL certificate error ============================ -It's common to run a test environment without a proper SSL certificate configuration. +It is common to run a test environment without a proper SSL certificate configuration. To ignore the SSL error, you can use the ``vcenter_validate_certs: no`` argument or ``export VMWARE_VALIDATE_CERTS=no`` to set the environment variable. diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/create_vm.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/create_vm.rst index 0e64bd0310e..6d19f61f559 100644 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/create_vm.rst +++ b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/create_vm.rst @@ -36,4 +36,4 @@ ______ .. literalinclude:: task_outputs/Create_a_VM.result.json .. note:: - ``vcenter_vm`` accepts more parameters, however you may prefer to start with a simple VM and use the ``vcenter_vm_hardware`` modules to tune it up afterwards. It's easier this way to identify a potential problematical step. + ``vcenter_vm`` accepts more parameters, however you may prefer to start with a simple VM and use the ``vcenter_vm_hardware`` modules to tune it up afterwards. It is easier this way to identify a potential problematical step. From 441ae85e24206599ab83b8f32327f9aa4a9c02b5 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Wed, 18 Oct 2023 20:06:22 +0100 Subject: [PATCH 020/536] ci: refresh docs build dependencies (#632) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot@users.noreply.github.com> --- tests/requirements-relaxed.txt | 2 +- tests/requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 4049a85991b..790b7315d61 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -163,7 +163,7 @@ typing-extensions==4.8.0 # via # pydantic # rstcheck -urllib3==2.0.6 +urllib3==2.0.7 # via requests yarl==1.9.2 # via aiohttp diff --git a/tests/requirements.txt b/tests/requirements.txt index bf04414abcd..6e4a36ae6c8 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -166,7 +166,7 @@ typing-extensions==4.8.0 # via # pydantic # rstcheck -urllib3==2.0.6 +urllib3==2.0.7 # via requests yarl==1.9.2 # via aiohttp From 4e28a0f57e00a7562e0dff50e738ca196636f7ed Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 18 Oct 2023 14:50:59 -0500 Subject: [PATCH 021/536] porting_guides: add porting_guide_9 to the index (#653) Fixes: https://github.com/ansible/ansible-documentation/issues/630 --- docs/docsite/rst/porting_guides/porting_guides.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docsite/rst/porting_guides/porting_guides.rst b/docs/docsite/rst/porting_guides/porting_guides.rst index b97303d0673..a3241c147dd 100644 --- a/docs/docsite/rst/porting_guides/porting_guides.rst +++ b/docs/docsite/rst/porting_guides/porting_guides.rst @@ -10,6 +10,7 @@ This section lists porting guides that can help you in updating playbooks, plugi :maxdepth: 1 :glob: + porting_guide_9 porting_guide_8 porting_guide_7 porting_guide_6 From 2949a0f180d1e70958ce245a676b4737d6e5eda4 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 18 Oct 2023 16:02:05 -0400 Subject: [PATCH 022/536] Added delegation info to special vars (#629) also reordered alpha --- .../special_variables.rst | 41 ++++++++++--------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/special_variables.rst b/docs/docsite/rst/reference_appendices/special_variables.rst index 35e0164e76b..55f24949fad 100644 --- a/docs/docsite/rst/reference_appendices/special_variables.rst +++ b/docs/docsite/rst/reference_appendices/special_variables.rst @@ -12,6 +12,9 @@ These variables cannot be set directly by the user; Ansible will always override ansible_check_mode Boolean that indicates if we are in check mode or not + ansible_collection_name + The name of the collection the task that is executing is a part of. In the format of ``namespace.collection`` + ansible_config_file The full path of used Ansible configuration file @@ -24,6 +27,9 @@ These variables cannot be set directly by the user; Ansible will always override ansible_forks Integer reflecting the number of maximum forks available to this run + ansible_index_var + The name of the value provided to ``loop_control.index_var``. Added in ``2.9`` + ansible_inventory_sources List of sources used as inventory @@ -36,9 +42,6 @@ These variables cannot be set directly by the user; Ansible will always override ansible_loop_var The name of the value provided to ``loop_control.loop_var``. Added in ``2.8`` - ansible_index_var - The name of the value provided to ``loop_control.index_var``. Added in ``2.9`` - 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. @@ -58,6 +61,9 @@ These variables cannot be set directly by the user; Ansible will always override ansible_play_hosts_all List of all the hosts that were targeted by the play + 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.) + 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. @@ -65,15 +71,12 @@ These variables cannot be set directly by the user; Ansible will always override ansible_playbook_python The path to the python interpreter being used by Ansible on the control node - 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_role_name The fully qualified collection role name, in the format of ``namespace.collection.role_name`` - 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_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_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"]``. @@ -91,7 +94,7 @@ These variables cannot be set directly by the user; Ansible will always override Dictionary/map that contains information about the current running version of ansible, it has the following keys: full, major, minor, revision and string. group_names - List of groups the current host is part of + List of groups the current host is part of, it always reflects the ``inventory_hostname`` and ignores delegation. groups A dictionary/map with all the groups in inventory and each group has the list of hosts that belong to it @@ -99,18 +102,19 @@ These variables cannot be set directly by the user; Ansible will always override hostvars A dictionary/map with all the hosts in inventory and variables assigned to them + inventory_dir + The directory of the inventory source in which the `inventory_hostname` was first defined. This always reflects the ``inventory_hostname`` and ignores delegation. + inventory_hostname - The inventory name for the 'current' host being iterated over in the play + The inventory name for the 'current' host being iterated over in the play. This is not affected by delegation, it always reflects the original host for the task inventory_hostname_short The short version of `inventory_hostname`, is the first section after splitting it via ``.``. - As an example, for the ``inventory_hostname`` of ``www.example.com``, ``www`` would be the ``inventory_hostname_short``. - - inventory_dir - The directory of the inventory source in which the `inventory_hostname` was first defined + As an example, for the ``inventory_hostname`` of ``www.example.com``, ``www`` would be the ``inventory_hostname_short`` + This is affected by delegation, so it will reflect the 'short name' of the delegated host inventory_file - The file name of the inventory source in which the `inventory_hostname` was first defined + The file name of the inventory source in which the `inventory_hostname` was first defined. Ignores delegation and always reflects the information for the ``inventory_hostname``. omit Special variable that allows you to 'omit' an option in a task, for example ``- user: name=bob home={{ bobs_home|default(omit) }}`` @@ -118,11 +122,8 @@ These variables cannot be set directly by the user; Ansible will always override play_hosts Deprecated, the same as ansible_play_batch - 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.) - 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. + 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_name The name of the role currently being executed. From 7e8d5ad89d46f5acbe5f176eee118aee2b825f13 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 18 Oct 2023 22:08:19 +0200 Subject: [PATCH 023/536] Add forum info to collection maintainer guidelines (#549) Co-authored-by: Don Naro --- .../rst/community/maintainers_guidelines.rst | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst index cfdd0e9595b..4c3250c8a39 100644 --- a/docs/docsite/rst/community/maintainers_guidelines.rst +++ b/docs/docsite/rst/community/maintainers_guidelines.rst @@ -39,15 +39,14 @@ To nominate a candidate, create a GitHub issue in the relevant collection reposi Communicating as a collection maintainer ----------------------------------------- - Maintainers MUST subscribe to the `"Changes impacting collection contributors and maintainers" GitHub repo `_ and the `Bullhorn newsletter `_. If you have something important to announce through the newsletter (for example, recent releases), see the `Bullhorn's wiki page `_ to learn how. + Maintainers are highly encouraged to subscribe to the `"Changes impacting collection contributors and maintainers" GitHub repo `_ and the `Bullhorn newsletter `_. If you have something important to announce through the newsletter (for example, recent releases), see the `Bullhorn's wiki page `_ to learn how. -Collection contributors and maintainers should also communicate through: +Collection contributors and maintainers can also communicate through: -* :ref:`communication_irc` appropriate to their collection, or if none exists, the general community and developer chat channels -* Mailing lists such as `ansible-announce `_ and `ansible-devel `_ -* Collection project boards, issues, and GitHub discussions in corresponding repositories -* Quarterly Contributor Summits. +* Real-time chats and forum topics appropriate to their collection, or if none exists, the general community and developer chat channels. +* Collection project boards, issues, and GitHub discussions in corresponding repositories. +* Contributor Summits and Ansible community days. * Ansiblefest and local meetups. See :ref:`communication` for more details on these communication channels. @@ -55,16 +54,16 @@ See :ref:`communication` for more details on these communication channels. .. _wg_and_real_time_chat: Establishing working group communication ----------------------------------------------------------------- +---------------------------------------- -Working groups depend on efficient, real-time communication. +Working groups depend on efficient communication. Project maintainers can use the following techniques to establish communication for working groups: -* Find an existing :ref:`working_group_list` that is similar to your project and join the conversation. +* Find an existing `forum group `_ or :ref:`working group` that is similar to your project and join the conversation. * `Request `_ a new working group for your project. * `Create `_ a public chat for your working group or `ask `_ the community team. * Provide working group details and links to chat rooms in the contributor section of your project ``README.md``. -* Encourage contributors to join the chats and add themselves to the working group. +* Encourage contributors to join the forum group and chat. See the :ref:`Communication guide ` to learn more about real-time chat. @@ -97,7 +96,7 @@ Expanding the collection community Here are some ways you can expand the community around your collection: * Give :ref:`newcomers a positive first experience `. - * Invite contributors to join :ref:`real-time chats ` related to your project. + * Invite contributors to join forum groups and :ref:`real-time chats ` related to your project. * Have :ref:`good documentation ` with guidelines for new contributors. * Make people feel welcome personally and individually. * Use labels to show easy fixes and leave non-critical easy fixes to newcomers and offer to mentor them. From c008f3d0740f1e9187bf7e13cbbd4e1a17b3e7ec Mon Sep 17 00:00:00 2001 From: flowerysong Date: Wed, 18 Oct 2023 16:26:31 -0400 Subject: [PATCH 024/536] Use a working exponential backoff example (#607) It's not possible to do exponential backoff with retries in a generic task, but we can demonstrate the same use of `map` using an action that takes a delay. --- .../complex_data_manipulation.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst b/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst index e7d23b336fc..d828bd42204 100644 --- a/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst +++ b/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst @@ -27,15 +27,20 @@ Most programming languages have loops (``for``, ``while``, and so on) and list c .. _exponential_backoff: -Use a loop to create exponential backoff for retries/until. +Use a loop to create exponential backoff. .. code-block:: yaml - - name: retry ping 10 times with exponential backoff delay - ping: - retries: 10 - delay: '{{item|int}}' - loop: '{{ range(1, 10)|map("pow", 2) }}' + - name: try wait_for_connection up to 10 times with exponential delay + ansible.builtin.wait_for_connection: + delay: '{{ item | int }}' + timeout: 1 + loop: '{{ range(1, 11) | map("pow", 2) }}' + loop_control: + extended: true + ignore_errors: "{{ not ansible_loop.last }}" + register: result + when: result is not defined or result is failed .. _keys_from_dict_matching_list: From a986664e99687d02c44af938921eee70643caf7f Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 18 Oct 2023 15:33:14 -0500 Subject: [PATCH 025/536] Rename tests/sanity.py to tests/checkers.py (#563) This change renames tests/sanity.py -> tests/checkers.py. The term sanity is not very clear and potentially offensive, and it's already used by `ansible-test sanity` to mean something different. Fixes: https://github.com/ansible/ansible-documentation/issues/530 --- .github/workflows/ci.yaml | 8 ++++---- tests/{sanity.py => checkers.py} | 0 2 files changed, 4 insertions(+), 4 deletions(-) rename tests/{sanity.py => checkers.py} (100%) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 74ac09904ab..656321080b4 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -29,9 +29,9 @@ jobs: run: | python docs/bin/clone-core.py - - name: Run docs-build Sanity + - name: Run docs-build Checkers run: | - python tests/sanity.py docs-build + python tests/checkers.py docs-build docs_sanity_rstcheck: name: rstcheck @@ -53,9 +53,9 @@ jobs: run: | python docs/bin/clone-core.py - - name: Run rstcheck Sanity + - name: Run rstcheck Checkers run: | - python tests/sanity.py rstcheck + python tests/checkers.py rstcheck nox: uses: ./.github/workflows/reusable-nox.yml diff --git a/tests/sanity.py b/tests/checkers.py similarity index 100% rename from tests/sanity.py rename to tests/checkers.py From b02dc78b040b78b9b5f023de1f99fef9c05c68d2 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Thu, 19 Oct 2023 12:36:33 -0500 Subject: [PATCH 026/536] get_bot_user: use correct username in committer email (#664) There is a small error in the Ansible Documentation Bot's committer email used by the pip-compile jobs. There needs to be a `[bot]` suffix in the username of a bot. --- hacking/get_bot_user.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hacking/get_bot_user.sh b/hacking/get_bot_user.sh index 3052958deb6..0a09d3b370a 100755 --- a/hacking/get_bot_user.sh +++ b/hacking/get_bot_user.sh @@ -11,4 +11,4 @@ user_id="$(curl -sS "${path}" | jq -r .id)" GIT="${GIT:-git}" ${GIT} config user.name "${name}" -${GIT} config user.email "${user_id}+${bot}@users.noreply.github.com" +${GIT} config user.email "${user_id}+${bot}[bot]@users.noreply.github.com" From 3297187cd155f364aed1c9da944e68b85be9d283 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Thu, 19 Oct 2023 12:42:02 -0500 Subject: [PATCH 027/536] ci: refresh dev dependencies (#672) --- tests/typing.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/typing.txt b/tests/typing.txt index 88e52c7fc35..184a8503e83 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -34,7 +34,7 @@ jinja2==3.1.2 # via -r tests/../hacking/pr_labeler/requirements.txt markupsafe==2.1.3 # via jinja2 -mypy==1.6.0 +mypy==1.6.1 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy From 6d9f4817eeee6761144344022680ec3e8116e245 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Gr=C3=BCtzmacher?= Date: Sat, 21 Oct 2023 01:07:54 +0200 Subject: [PATCH 028/536] Update example using special variables in resuce section of blocks (#671) * Update example using special variables in resuce section of blocks * Reverted to previous example with linting fixes and corrected variables --- docs/docsite/rst/playbook_guide/playbooks_blocks.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst index e9a6fcb0820..ecf45cc531b 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst @@ -199,14 +199,14 @@ These can be inspected in the ``rescue`` section: ansible.builtin.command: /bin/false rescue: - name: All is good if the first task failed - when: ansible_failed.task.name == 'Do Something' - debug: - msg: All is good, ignore error as grep could not find 'me' in hosts + when: ansible_failed_task.name == 'Do Something' + ansible.builtin.debug: + msg: All is good, ignore error as grep could not find 'me' in hosts - name: All is good if the first task failed - when: "'/bin/false' in ansible_failed.result.cmd|d([])" - fail: - msg: It is still false!!! + when: "'/bin/false' in ansible_failed_result.cmd | d([])" + ansible.builtin.fail: + msg: It is still false!!! .. note:: From a220e0c2b08e56fe2e64eb53430172f49605bd13 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sat, 21 Oct 2023 20:27:05 -0500 Subject: [PATCH 029/536] ci: refresh dev dependencies (#682) --- tests/static.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/static.txt b/tests/static.txt index cde7dc0519a..101b61d2fad 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.0 +ruff==0.1.1 # via -r tests/static.in From de9e1e522e8d9f0d48c9bd8afc4999149b2acf7e Mon Sep 17 00:00:00 2001 From: Matt Clay Date: Mon, 23 Oct 2023 02:46:58 -0700 Subject: [PATCH 030/536] Update shebang sanity test docs to match test (#677) The `#!/bin/bash` shebang was removed in https://github.com/ansible/ansible/pull/50954, but the documentation was never updated to reflect the change. --- docs/docsite/rst/dev_guide/testing/sanity/shebang.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/dev_guide/testing/sanity/shebang.rst b/docs/docsite/rst/dev_guide/testing/sanity/shebang.rst index cff2aa0914b..b4e0b037259 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/shebang.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/shebang.rst @@ -4,13 +4,12 @@ shebang Most executable files should only use one of the following shebangs: - ``#!/bin/sh`` -- ``#!/bin/bash`` +- ``#!/bin/bash -eu`` +- ``#!/bin/bash -eux`` - ``#!/usr/bin/make`` - ``#!/usr/bin/env python`` - ``#!/usr/bin/env bash`` -NOTE: For ``#!/bin/bash``, any of the options ``eux`` may also be used, such as ``#!/bin/bash -eux``. - This does not apply to Ansible modules, which should not be executable and must always use ``#!/usr/bin/python``. Some exceptions are permitted. Ask if you have questions. From c6fb5c108c806172ac11d53c754d8a564e013e80 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Mon, 23 Oct 2023 12:56:18 +0200 Subject: [PATCH 031/536] communication.rst: add a note about Matrix (#670) * communication.rst: add a note about Matrix * Restructure. Reflect the fact that bridging doesn't work Co-authored-by: Don Naro --- docs/docsite/rst/community/communication.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 90a30b2eb4a..2e015a3592b 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -27,7 +27,15 @@ In most cases, joining a forum group automatically subscribes you to related pos Real-time chat ============== -For real-time interactions, conversations in the Ansible community happen over two chat protocols: Matrix and IRC. We maintain a bridge between Matrix and IRC, so you can choose whichever protocol you prefer. All channels exist in both places. Join a channel any time to ask questions, participate in a Working Group meeting, or just say hello. +For real-time interactions, conversations in the Ansible community happen over two chat protocols: Matrix (recommended) and IRC. +The main Matrix and IRC channels exchange messages. +This means you can choose whichever protocol you prefer for the main channels. + +.. note:: + + Although you can choose either Matrix or IRC, please take into account that many Ansible communities use only Matrix. + +Join a channel any time to ask questions, participate in a Working Group meeting, or just say hello. Ansible community on Matrix --------------------------- From c614075767a84d2f7317af18281cdca2e5747f94 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Sun, 8 Oct 2023 09:04:42 -0700 Subject: [PATCH 032/536] Update slicing in inventory pattern Fixes: #512 Signed-off-by: Abhijeet Kasurde --- .../rst/inventory_guide/intro_patterns.rst | 46 +++++++++++++++---- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/docs/docsite/rst/inventory_guide/intro_patterns.rst b/docs/docsite/rst/inventory_guide/intro_patterns.rst index a11a4546cab..e3bb607c8eb 100644 --- a/docs/docsite/rst/inventory_guide/intro_patterns.rst +++ b/docs/docsite/rst/inventory_guide/intro_patterns.rst @@ -27,7 +27,7 @@ For example: ansible webservers -m service -a "name=httpd state=restarted" -In a playbook the pattern is the content of the ``hosts:`` line for each play: +In a playbook, the pattern is the content of the ``hosts:`` line for each play: .. code-block:: yaml @@ -80,7 +80,7 @@ Once you know the basic patterns, you can combine them. This example: webservers:dbservers:&staging:!phoenix targets all machines in the groups 'webservers' and 'dbservers' that are also in -the group 'staging', except any machines in the group 'phoenix'. +the group 'staging', except for any machines in the group 'phoenix'. You can use wildcard patterns with FQDNs or IP addresses, as long as the hosts are named in your inventory by FQDN or IP address: @@ -168,17 +168,45 @@ You can define a host or subset of hosts by its position in a group. For example webbing weber -you can use subscripts to select individual hosts or ranges within the webservers group: +you can use subscripts to select individual hosts or ranges within the webservers group. + +Slicing at specific items +""""""""""""""""""""""""" + +* **Operation:** ``s[i]`` +* **Result:** ``i-th`` item of ``s`` where the indexing origin is ``0`` + +If *i* is negative, the index is relative to the end of sequence *s*: ``len(s) + i`` is substituted. However ``-0`` is ``0``. .. code-block:: yaml webservers[0] # == cobweb webservers[-1] # == weber - webservers[0:2] # == webservers[0],webservers[1] - # == cobweb,webbing + + +Slicing with start and end points +""""""""""""""""""""""""""""""""" + +* **Operation:** ``s[i:j]`` +* **Result:** slice of ``s`` from ``i`` to ``j`` + +The slice of *s* from *i* to *j* is defined as the sequence of items with index *k* such that ``i <= k <= j``. +If *i* is omitted, use ``0``. If *j* is omitted, use ``len(s)``. +The slice omitting both *i* and *j*, results in an invalid host pattern. +If *i* is greater than *j*, the slice is empty. +If *i* is equal to *j*, the *s[i]* is substituted. + + +.. code-block:: yaml + + webservers[0:2] # == webservers[0],webservers[1],webservers[2] + # == cobweb,webbing,weber + webservers[1:2] # == webservers[1],webservers[2] + # == webbing,weber webservers[1:] # == webbing,weber webservers[:3] # == cobweb,webbing,weber + Using regexes in patterns ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -198,25 +226,25 @@ You can also limit the hosts you target on a particular run with the ``--limit`` .. code-block:: bash - $ ansible all -m [module] -a "[module options]" --limit "host1" + $ ansible all -m -a "" --limit "host1" * Limit to multiple hosts .. code-block:: bash - $ ansible all -m [module] -a "[module options]" --limit "host1,host2" + $ ansible all -m -a "" --limit "host1,host2" * Negated limit. Note that single quotes MUST be used to prevent bash interpolation. .. code-block:: bash - $ ansible all -m [module] -a "[module options]" --limit 'all:!host1' + $ ansible all -m -a "" --limit 'all:!host1' * Limit to host group .. code-block:: bash - $ ansible all -m [module] -a "[module options]" --limit 'group1' + $ ansible all -m -a "" --limit 'group1' Patterns and ansible-playbook flags ----------------------------------- From aa42fb6050a1bd4a5e0135a933da7da7c9976618 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Tue, 24 Oct 2023 01:17:38 -0700 Subject: [PATCH 033/536] Update intro_inventory page (#691) * Update intro_inventory page * Spelling fixes * Rewording of sentences * Remove non-SSH-based connection plugins section * Update documentation about sudo_flags and ssh_executable Signed-off-by: Abhijeet Kasurde Co-authored-by: Don Naro --- .../rst/inventory_guide/intro_inventory.rst | 80 +++++-------------- 1 file changed, 18 insertions(+), 62 deletions(-) diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index f1b359e51d9..94118538eb5 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -76,7 +76,7 @@ Every host will always belong to at least 2 groups (``all`` and ``ungrouped`` or Hosts in multiple groups ------------------------ -You can (and probably will) put each host in more than one group. For example a production webserver in a datacenter in Atlanta might be included in groups called ``[prod]`` and ``[atlanta]`` and ``[webservers]``. You can create groups that track: +You can put each host in more than one group. For example, a production web server in a data center in Atlanta might be included in groups called ``[prod]`` and ``[atlanta]`` and ``[webservers]``. You can create groups that track: * What - An application, stack or microservice (for example, database servers, web servers, and so on). * Where - A datacenter or region, to talk to local DNS, storage, and so on (for example, east, west). @@ -165,9 +165,9 @@ Here is the same inventory as shown above, simplified with parent groups for the Child groups have a couple of properties to note: -* Any host that is member of a child group is automatically a member of the parent group. +* Any host that is a member of a child group is automatically a member of the parent group. * Groups can have multiple parents and children, but not circular relationships. -* Hosts can also be in multiple groups, but there will only be **one** instance of a host at runtime. Ansible merges the data from the multiple groups. +* Hosts can also be in multiple groups, but there will only be **one** instance of a host at runtime. Ansible merges the data from multiple groups. Adding ranges of hosts ---------------------- @@ -291,7 +291,7 @@ We document adding variables in the main inventory file for simplicity. However, Assigning a variable to one machine: host variables =================================================== -You can easily assign a variable to a single host, then use it later in playbooks. You can do this directly in your inventory file. +You can easily assign a variable to a single host and then use it later in playbooks. You can do this directly in your inventory file. In INI: @@ -465,7 +465,7 @@ In YAML: northwest: southwest: -A child group's variables will have higher precedence (override) a parent group's variables. +A child group's variables will have higher precedence (override) than a parent group's variables. .. _splitting_out_vars: @@ -514,14 +514,14 @@ is an excellent way to track changes to your inventory and host variables. How variables are merged ======================== -By default variables are merged/flattened to the specific host before a play is run. This keeps Ansible focused on the Host and Task, so groups don't really survive outside of inventory and host matching. By default, Ansible overwrites variables including the ones defined for a group and/or host (see :ref:`DEFAULT_HASH_BEHAVIOUR`). The order/precedence is (from lowest to highest): +By default, variables are merged/flattened to the specific host before a play is run. This keeps Ansible focused on the Host and Task, so groups do not survive outside of inventory and host matching. By default, Ansible overwrites variables including the ones defined for a group and/or host (see :ref:`DEFAULT_HASH_BEHAVIOUR`). The order/precedence is (from lowest to highest): - all group (because it is the 'parent' of all other groups) - parent group - child group - host -By default Ansible merges groups at the same parent/child level in ASCII order, and variables from the last group loaded overwrite variables from the previous groups. For example, an a_group will be merged with b_group and b_group vars that match will overwrite the ones in a_group. +By default, Ansible merges groups at the same parent/child level in ASCII order, and variables from the last group loaded overwrite variables from the previous groups. For example, an a_group will be merged with b_group and b_group vars that match will overwrite the ones in a_group. You can change this behavior by setting the group variable ``ansible_group_priority`` to change the merge order for groups of the same level (after the parent/child order is resolved). The larger the number, the later it will be merged, giving it higher priority. This variable defaults to ``1`` if not set. For example: @@ -578,7 +578,7 @@ Host connection: .. include:: shared_snippets/SSH_password_prompt.txt ansible_connection - Connection type to the host. This can be the name of any of ansible's connection plugins. SSH protocol types are ``smart``, ``ssh`` or ``paramiko``. The default is smart. Non-SSH based types are described in the next section. + Connection type to the host. This can be the name of any of Ansible's connection plugins. SSH protocol types are ``smart``, ``ssh`` or ``paramiko``. The default is smart. Non-SSH based types are described in the next section. General for all connections: @@ -595,7 +595,7 @@ ansible_password Specific to the SSH connection: ansible_ssh_private_key_file - Private key file used by ssh. Useful if using multiple keys and you don't want to use SSH agent. + Private key file used by SSH. Useful if using multiple keys and you do not want to use SSH agent. ansible_ssh_common_args This setting is always appended to the default command line for :command:`sftp`, :command:`scp`, and :command:`ssh`. Useful to configure a ``ProxyCommand`` for a certain host (or @@ -609,7 +609,7 @@ ansible_ssh_extra_args ansible_ssh_pipelining Determines whether or not to use SSH pipelining. This can override the ``pipelining`` setting in :file:`ansible.cfg`. ansible_ssh_executable (added in version 2.2) - This setting overrides the default behavior to use the system :command:`ssh`. This can override the ``ssh_executable`` setting in :file:`ansible.cfg`. + This setting overrides the default behavior to use the system :command:`ssh`. This can override the ``ssh_executable`` setting in :file:`ansible.cfg` under ``ssh_connection``. Privilege escalation (see :ref:`Ansible Privilege Escalation` for further details): @@ -619,13 +619,13 @@ ansible_become ansible_become_method Allows to set privilege escalation method ansible_become_user - Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows to set the user you become through privilege escalation + Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows you to set the user you become through privilege escalation ansible_become_password Equivalent to ``ansible_sudo_password`` or ``ansible_su_password``, allows you to set the privilege escalation password (never store this variable in plain text; always use a vault. See :ref:`tip_for_variables_and_vaults`) ansible_become_exe Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``, allows you to set the executable for the escalation method selected ansible_become_flags - Equivalent to ``ansible_sudo_flags`` or ``ansible_su_flags``, allows you to set the flags passed to the selected escalation method. This can be also set globally in :file:`ansible.cfg` in the ``sudo_flags`` option + Equivalent to ``ansible_sudo_flags`` or ``ansible_su_flags``, allows you to set the flags passed to the selected escalation method. This can be also set globally in :file:`ansible.cfg` in the ``become_flags`` option under ``privilege_escalation``. Remote host environment parameters: @@ -633,7 +633,7 @@ Remote host environment parameters: ansible_shell_type The shell type of the target system. You should not use this setting unless you have set the - :ref:`ansible_shell_executable` to a non-Bourne (sh) compatible shell. By default commands are + :ref:`ansible_shell_executable` to a non-Bourne (sh) compatible shell. By default, commands are formatted using ``sh``-style syntax. Setting this to ``csh`` or ``fish`` will cause commands executed on target systems to follow those shell's syntax instead. @@ -648,7 +648,7 @@ ansible_python_interpreter ansible_*_interpreter Works for anything such as ruby or perl and works just like :ref:`ansible_python_interpreter`. - This replaces shebang of modules which will run on that host. + This replaces shebang of modules that will run on that host. .. versionadded:: 2.1 @@ -657,7 +657,7 @@ ansible_*_interpreter ansible_shell_executable This sets the shell the ansible control node will use on the target machine, overrides ``executable`` in :file:`ansible.cfg` which defaults to - :command:`/bin/sh`. You should really only change it if is not possible + :command:`/bin/sh`. You should only change this value if it is not possible to use :command:`/bin/sh` (in other words, if :command:`/bin/sh` is not installed on the target machine or cannot be run from sudo.). @@ -674,54 +674,10 @@ Non-SSH connection types ------------------------ As stated in the previous section, Ansible executes playbooks over SSH but it is not limited to this connection type. -With the host specific parameter ``ansible_connection=``, the connection type can be changed. -The following non-SSH based connectors are available: - -**local** - -This connector can be used to deploy the playbook to the control machine itself. - -**docker** - -This connector deploys the playbook directly into Docker containers using the local Docker client. The following parameters are processed by this connector: - -ansible_host - The name of the Docker container to connect to. -ansible_user - The username to operate within the container. The user must exist inside the container. -ansible_become - If set to ``true`` the ``become_user`` will be used to operate within the container. -ansible_docker_extra_args - Could be a string with any additional arguments understood by Docker, which are not command specific. This parameter is mainly used to configure a remote Docker daemon to use. - -Here is an example of how to instantly deploy to created containers: - -.. code-block:: yaml - - - name: Create a jenkins container - community.general.docker_container: - docker_host: myserver.net:4243 - name: my_jenkins - image: jenkins - - - name: Add the container to inventory - ansible.builtin.add_host: - name: my_jenkins - ansible_connection: docker - ansible_docker_extra_args: "--tlsverify --tlscacert=/path/to/ca.pem --tlscert=/path/to/client-cert.pem --tlskey=/path/to/client-key.pem -H=tcp://myserver.net:4243" - ansible_user: jenkins - changed_when: false - - - name: Create a directory for ssh keys - delegate_to: my_jenkins - ansible.builtin.file: - path: "/var/jenkins_home/.ssh/jupiter" - state: directory +With the host-specific parameter ``ansible_connection=``, the connection type can be changed. For a full list with available plugins and examples, see :ref:`connection_plugin_list`. -.. note:: If you're reading the docs from the beginning, this may be the first example you've seen of an Ansible playbook. This is not an inventory file. - Playbooks will be covered in great detail later in the docs. .. _inventory_setup_examples: @@ -738,7 +694,7 @@ Example: One inventory per environment If you need to manage multiple environments it is sometimes prudent to have only hosts of a single environment defined per inventory. This way, it is harder to, for example, accidentally change the state of -nodes inside the "test" environment when you actually wanted to update +nodes inside the "test" environment when you wanted to update some "staging" servers. For the example mentioned above you could have an @@ -783,7 +739,7 @@ following command: Example: Group by function -------------------------- -In the previous section you already saw an example for using groups in +In the previous section, you already saw an example of using groups in order to cluster hosts that have the same function. This allows you, for example, to define firewall rules inside a playbook or role affecting only database servers: From 532a95f8b572fca4fe668fe592c95ec26de1dc36 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 24 Oct 2023 10:34:54 +0200 Subject: [PATCH 034/536] communication.rst: other forum-related tweaks (#669) * communication.rst: other forum-related tweaks * Fix rst --- docs/docsite/rst/community/communication.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 2e015a3592b..b38e9d7491b 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -22,6 +22,9 @@ The `Ansible Community Forum `_ is a single starting Take a look at the `forum groups `_ and join ones that match your interests. In most cases, joining a forum group automatically subscribes you to related posts. +Want to create a group? +Request it in the `forum topic `_. + .. _communication_irc: Real-time chat @@ -107,7 +110,7 @@ The clickable links will take you directly to the relevant Matrix room in your b Working groups -------------- -Our community working groups are represented in forms of `Forum groups `_ (new style) or `wiki pages `_. +Our community working groups are represented in forms of `Forum groups `_ (new style) or `wiki pages `_ (deprecated). Many of them meet in chat. If you want to get involved in a working group, join the Matrix room or IRC channel where it meets or comment on the agenda. @@ -187,7 +190,9 @@ Read past issues on the official Bullhorn's `wiki page Date: Tue, 24 Oct 2023 12:02:08 -0700 Subject: [PATCH 035/536] Update JSON queries examples (#690) Fixes: #547 Signed-off-by: Abhijeet Kasurde --- .../rst/playbook_guide/playbooks_filters.rst | 96 +++++++++---------- 1 file changed, 47 insertions(+), 49 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index e99ab1dd5a2..90a70a02733 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -843,49 +843,47 @@ Consider this data structure: .. code-block:: json { - "domain_definition": { - "domain": { - "cluster": [ - { - "name": "cluster1" - }, - { - "name": "cluster2" - } - ], - "server": [ - { - "name": "server11", - "cluster": "cluster1", - "port": "8080" - }, - { - "name": "server12", - "cluster": "cluster1", - "port": "8090" - }, - { - "name": "server21", - "cluster": "cluster2", - "port": "9080" - }, - { - "name": "server22", - "cluster": "cluster2", - "port": "9090" - } - ], - "library": [ - { - "name": "lib1", - "target": "cluster1" - }, - { - "name": "lib2", - "target": "cluster2" - } - ] - } + "domain": { + "cluster": [ + { + "name": "cluster1" + }, + { + "name": "cluster2" + } + ], + "server": [ + { + "name": "server11", + "cluster": "cluster1", + "port": "8080" + }, + { + "name": "server12", + "cluster": "cluster1", + "port": "8090" + }, + { + "name": "server21", + "cluster": "cluster2", + "port": "9080" + }, + { + "name": "server22", + "cluster": "cluster2", + "port": "9090" + } + ], + "library": [ + { + "name": "lib1", + "target": "cluster1" + }, + { + "name": "lib2", + "target": "cluster2" + } + ] } } @@ -920,7 +918,7 @@ To extract ports from cluster1: .. note:: You can use a variable to make the query more readable. -To print out the ports from cluster1 in a comma separated string: +To print out the ports from cluster1 in a comma-separated string: .. code-block:: yaml+jinja @@ -950,23 +948,23 @@ To get a hash map with all ports and names of a cluster: var: item loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}" vars: - server_name_cluster1_query: "domain.server[?cluster=='cluster2'].{name: name, port: port}" + server_name_cluster1_query: "domain.server[?cluster=='cluster1'].{name: name, port: port}" -To extract ports from all clusters with name starting with 'server1': +To extract ports from all clusters with the name starting with 'server1': .. code-block:: yaml+jinja - - name: Display all ports from cluster1 + - name: Display ports from all clusters with the name starting with 'server1' ansible.builtin.debug: msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}" vars: server_name_query: "domain.server[?starts_with(name,'server1')].port" -To extract ports from all clusters with name containing 'server1': +To extract ports from all clusters with the name containing 'server1': .. code-block:: yaml+jinja - - name: Display all ports from cluster1 + - name: Display ports from all clusters with the name containing 'server1' ansible.builtin.debug: msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}" vars: From 919fbe55f86daf9f0bf28a381515945f88676971 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Wed, 25 Oct 2023 01:04:04 -0700 Subject: [PATCH 036/536] Drop reference of obsolete inventory script (#686) Openstack Ansible collection removed obsolete inventory script in 2.0.0 release. Remove the reference to this inventory script. Fixes: #679 Signed-off-by: Abhijeet Kasurde --- .../intro_dynamic_inventory.rst | 90 ------------------- 1 file changed, 90 deletions(-) diff --git a/docs/docsite/rst/inventory_guide/intro_dynamic_inventory.rst b/docs/docsite/rst/inventory_guide/intro_dynamic_inventory.rst index 7997aa47115..a9583dfffab 100644 --- a/docs/docsite/rst/inventory_guide/intro_dynamic_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_dynamic_inventory.rst @@ -113,96 +113,6 @@ And technically, though there is no major good reason to do it, this also works: So, in other words, you can use those variables in arguments/actions as well. -.. _openstack_example: - -Inventory script example: OpenStack -=================================== - -If you use an OpenStack-based cloud, instead of manually maintaining your own inventory file, you can use the ``openstack_inventory.py`` dynamic inventory to pull information about your compute instances directly from OpenStack. - -You can download the latest version of the OpenStack inventory script `here `_. - -You can use the inventory script explicitly (by passing the `-i openstack_inventory.py` argument to Ansible) or implicitly (by placing the script at `/etc/ansible/hosts`). - -Explicit use of OpenStack inventory script ------------------------------------------- - -Download the latest version of the OpenStack dynamic inventory script and make it executable. - -.. code-block:: bash - - wget https://raw.githubusercontent.com/openstack/ansible-collections-openstack/master/scripts/inventory/openstack_inventory.py - chmod +x openstack_inventory.py - -.. note:: - Do not name it `openstack.py`. This name will conflict with imports from openstacksdk. - -Source an OpenStack RC file: - -.. code-block:: bash - - source openstack.rc - -.. note:: - - An OpenStack RC file contains the environment variables required by the client tools to establish a connection with the cloud provider, such as the authentication URL, username, password and region name. For more information on how to download, create or source an OpenStack RC file, please refer to `Set environment variables using the OpenStack RC file `_. - -You can confirm the file has been successfully sourced by running a simple command, such as `nova list` and ensuring it returns no errors. - -.. note:: - - The OpenStack command line clients are required to run the `nova list` command. For more information on how to install them, please refer to `Install the OpenStack command-line clients `_. - -You can test the OpenStack dynamic inventory script manually to confirm it is working as expected: - -.. code-block:: bash - - ./openstack_inventory.py --list - -After a few moments you should see some JSON output with information about your compute instances. - -Once you confirm the dynamic inventory script is working as expected, you can tell Ansible to use the `openstack_inventory.py` script as an inventory file, as illustrated below: - -.. code-block:: bash - - ansible -i openstack_inventory.py all -m ansible.builtin.ping - -Implicit use of OpenStack inventory script ------------------------------------------- - -Download the latest version of the OpenStack dynamic inventory script, make it executable and copy it to `/etc/ansible/hosts`: - -.. code-block:: bash - - wget https://raw.githubusercontent.com/openstack/ansible-collections-openstack/master/scripts/inventory/openstack_inventory.py - chmod +x openstack_inventory.py - sudo cp openstack_inventory.py /etc/ansible/hosts - -Download the sample configuration file, modify it to suit your needs and copy it to `/etc/ansible/openstack.yml`: - -.. code-block:: bash - - wget https://raw.githubusercontent.com/openstack/ansible-collections-openstack/master/scripts/inventory/openstack.yml - vi openstack.yml - sudo cp openstack.yml /etc/ansible/ - -You can test the OpenStack dynamic inventory script manually to confirm it is working as expected: - -.. code-block:: bash - - /etc/ansible/hosts --list - -After a few moments you should see some JSON output with information about your compute instances. - -Refreshing the cache --------------------- - -Note that the OpenStack dynamic inventory script will cache results to avoid repeated API calls. To explicitly clear the cache, you can run the openstack_inventory.py (or hosts) script with the ``--refresh`` parameter: - -.. code-block:: bash - - ./openstack_inventory.py --refresh --list - .. _other_inventory_scripts: Other inventory scripts From 8453b7c9d04d9eafd7dfff828c9531f478d0c5ba Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Wed, 25 Oct 2023 16:04:34 +0530 Subject: [PATCH 037/536] Add a copy button to code snippet Fixes: #75 Signed-off-by: Abhijeet Kasurde --- docs/docsite/rst/conf.py | 1 + tests/requirements-relaxed.in | 1 + tests/requirements.txt | 3 +++ 3 files changed, 5 insertions(+) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 4de0c881c76..2dc33cc06ff 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -62,6 +62,7 @@ 'sphinx.ext.intersphinx', 'notfound.extension', 'sphinx_antsibull_ext', # provides CSS for the plugin/module docs generated by antsibull + 'sphinx_copybutton', ] # Later on, add 'sphinx.ext.viewcode' to the list if you want to have diff --git a/tests/requirements-relaxed.in b/tests/requirements-relaxed.in index cd442cfa9b3..ffc37e73cc2 100644 --- a/tests/requirements-relaxed.in +++ b/tests/requirements-relaxed.in @@ -13,3 +13,4 @@ sphinx-notfound-page sphinx-ansible-theme rstcheck antsibull-docs ~= 2.0 +sphinx-copybutton diff --git a/tests/requirements.txt b/tests/requirements.txt index 6e4a36ae6c8..a2ad9711f75 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -121,6 +121,7 @@ sphinx==7.2.5 # -r tests/requirements-relaxed.in # antsibull-docs # sphinx-ansible-theme + # sphinx-copybutton # sphinx-intl # sphinx-notfound-page # sphinx-rtd-theme @@ -132,6 +133,8 @@ sphinx==7.2.5 # sphinxcontrib-serializinghtml sphinx-ansible-theme==0.10.2 # via -r tests/requirements-relaxed.in +sphinx-copybutton==0.5.2 + # via -r tests/requirements-relaxed.in sphinx-intl==2.1.0 # via -r tests/requirements-relaxed.in sphinx-notfound-page==1.0.0 From 2007f29a56dba9fc69a611bc2d7f0a0bfd8cad65 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 25 Oct 2023 08:48:44 -0500 Subject: [PATCH 038/536] documentation_contributions: use tests/checkers.py (#706) changed the documentation_contributions doc to match the tests/sanity.py rename to tests/checker.py in https://github.com/ansible/ansible-documentation/pull/563 --- docs/docsite/rst/community/documentation_contributions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 18541d36178..5946337f44b 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -237,8 +237,8 @@ When you submit a documentation pull request, automated tests are run. Those sam .. code-block:: bash make clean -C docs/docsite - python tests/sanity.py docs-build - python tests/sanity.py rstcheck + python tests/checkers.py docs-build + python tests/checkers.py rstcheck It is recommended to run tests on a clean copy of the repository, which is the purpose of the ``make clean`` command. From bd2ce70a0f3c74a6ee06a9e41e168fc0a03d2ff8 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 25 Oct 2023 15:40:07 +0100 Subject: [PATCH 039/536] improve Ansible getting started diagram (#711) Co-authored-by: Tina Yip <98424339+tiyiprh@users.noreply.github.com> --- docs/docsite/rst/getting_started/index.rst | 17 +- docs/docsite/rst/images/ansible_basic.svg | 333 ---------- docs/docsite/rst/images/ansible_inv_start.svg | 598 ++++++++++++++++++ 3 files changed, 606 insertions(+), 342 deletions(-) delete mode 100644 docs/docsite/rst/images/ansible_basic.svg create mode 100644 docs/docsite/rst/images/ansible_inv_start.svg diff --git a/docs/docsite/rst/getting_started/index.rst b/docs/docsite/rst/getting_started/index.rst index e27f5eaaf3a..99d38b80c61 100644 --- a/docs/docsite/rst/getting_started/index.rst +++ b/docs/docsite/rst/getting_started/index.rst @@ -5,25 +5,24 @@ Getting started with Ansible ############################ Ansible automates the management of remote systems and controls their desired state. -A basic Ansible environment has three main components: +.. image:: ../images/ansible_inv_start.svg + :width: 800px + :height: 400px + :alt: Basic components of an Ansible environment include a control node, an inventory of managed nodes, and a module copied to each managed node. + +As shown in the preceding figure, most Ansible environments have three main components: Control node A system on which Ansible is installed. You run Ansible commands such as ``ansible`` or ``ansible-inventory`` on a control node. -Managed node - A remote system, or host, that Ansible controls. - Inventory A list of managed nodes that are logically organized. You create an inventory on the control node to describe host deployments to Ansible. -.. image:: ../images/ansible_basic.svg - :width: 400px - :align: center - :height: 200px - :alt: Basic components of an Ansible environment include a control node, an inventory of managed nodes, and a module copied to each managed node. +Managed node + A remote system, or host, that Ansible controls. .. toctree:: :maxdepth: 1 diff --git a/docs/docsite/rst/images/ansible_basic.svg b/docs/docsite/rst/images/ansible_basic.svg deleted file mode 100644 index 6217c89ff39..00000000000 --- a/docs/docsite/rst/images/ansible_basic.svg +++ /dev/null @@ -1,333 +0,0 @@ - - - - diff --git a/docs/docsite/rst/images/ansible_inv_start.svg b/docs/docsite/rst/images/ansible_inv_start.svg new file mode 100644 index 00000000000..1a9fb34fa20 --- /dev/null +++ b/docs/docsite/rst/images/ansible_inv_start.svg @@ -0,0 +1,598 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From ae79ff73f492c3bd4d7cef4bfa3b952b89d49193 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 25 Oct 2023 11:07:12 -0400 Subject: [PATCH 040/536] add changeloge link to core support matrix (#692) --- .../rst/reference_appendices/release_and_maintenance.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 7de14d02d12..4c004376ee9 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -159,7 +159,7 @@ Dates listed indicate the start date of the maintenance cycle. - | Python 3.10 - 3.12 - | Python 3.7 - 3.12 | PowerShell TBD - * - `2.16` + * - `2.16`_ - | GA: 06 Nov 2023 | Critical: 20 May 2024 | Security: Nov 2024 @@ -311,6 +311,8 @@ Dates listed indicate the start date of the maintenance cycle. .. _2.13: https://github.com/ansible/ansible/blob/stable-2.13/changelogs/CHANGELOG-v2.13.rst .. _2.14: https://github.com/ansible/ansible/blob/stable-2.14/changelogs/CHANGELOG-v2.14.rst .. _2.15: https://github.com/ansible/ansible/blob/stable-2.15/changelogs/CHANGELOG-v2.15.rst +.. _2.16: https://github.com/ansible/ansible/blob/stable-2.16/changelogs/CHANGELOG-v2.16.rst + Preparing for a new release From ebe3578d7d2057196755b2985885b802dd5fc353 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 25 Oct 2023 16:11:43 +0100 Subject: [PATCH 041/536] Point EE getting started to ecosystem (#617) * ee getting started points to ecosystem * fix rst error with new line * add more specific links to ecosystem pages * remove orphan tag from index * rm orphaned pages to rely on redirects --- .../build_execution_environment.rst | 76 ------------- docs/docsite/rst/getting_started_ee/index.rst | 40 ++++--- .../rst/getting_started_ee/introduction.rst | 63 ----------- .../run_community_ee_image.rst | 52 --------- .../run_execution_environment.rst | 104 ------------------ .../getting_started_ee/setup_environment.rst | 45 -------- 6 files changed, 19 insertions(+), 361 deletions(-) delete mode 100644 docs/docsite/rst/getting_started_ee/build_execution_environment.rst delete mode 100644 docs/docsite/rst/getting_started_ee/introduction.rst delete mode 100644 docs/docsite/rst/getting_started_ee/run_community_ee_image.rst delete mode 100644 docs/docsite/rst/getting_started_ee/run_execution_environment.rst delete mode 100644 docs/docsite/rst/getting_started_ee/setup_environment.rst diff --git a/docs/docsite/rst/getting_started_ee/build_execution_environment.rst b/docs/docsite/rst/getting_started_ee/build_execution_environment.rst deleted file mode 100644 index 0200fbf13c9..00000000000 --- a/docs/docsite/rst/getting_started_ee/build_execution_environment.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. _building_execution_environments: - -Building your first EE -====================== - -We are going to build an EE that represents an Ansible control node containing standard packages such as ``ansible-core`` and Python in addition to -an Ansible collection (``community.postgresql``) and its dependency (the ``psycopg2-binary`` Python connector). - -To build your first EE: - -1. Create a project folder on your filesystem. - -.. code-block:: bash - - mkdir my_first_ee && cd my_first_ee - -2. Create a ``execution-environment.yml`` file that specifies dependencies to include in the image. - -.. code-block:: yaml - - cat > execution-environment.yml<`_ for details. - -3. Build a EE container image called ``postgresql_ee``. If you use docker, add the ``--container-runtime docker`` argument. - -.. code-block:: bash - - ansible-builder build --tag postgresql_ee - -4. List container images to verify that you built it successfully. - -.. code-block:: bash - - podman image list - - localhost/postgresql_ee latest 2e866777269b 6 minutes ago 1.11 GB - -You can verify the image you created by inspecting the ``Containerfile`` or ``Dockerfile`` in the ``context`` directory to view its configuration. - -.. code-block:: bash - - less context/Containerfile - -You can also use Ansible Navigator to view detailed information about the image. - -Run the ``ansible-navigator`` command, type ``:images`` in the TUI, and then choose ``postgresql_ee``. - -Proceed to :ref:`Running your EE` and test the EE you just built. - -.. seealso:: - - `Running a local container registry for EE `_ - Learn how to set up a simple local registry to host your Execution Environment images diff --git a/docs/docsite/rst/getting_started_ee/index.rst b/docs/docsite/rst/getting_started_ee/index.rst index 69a6858d97a..3e3d38edcb8 100644 --- a/docs/docsite/rst/getting_started_ee/index.rst +++ b/docs/docsite/rst/getting_started_ee/index.rst @@ -1,34 +1,32 @@ -:orphan: - .. _getting_started_ee_index: ******************************************* Getting started with Execution Environments ******************************************* -You can run Ansible automation in containers, like any other modern software application. -Ansible uses container images known as Execution Environments (EE) that act as control nodes. +Execution Environments (EEs) are Ansible control nodes packaged as container images. +EEs remove complexity to scale out automation projects and make things like deployment operations much more straightforward. + +EEs provide you with: -An Execution Environment image contains the following packages as standard: +* Software dependency isolation +* Portability across teams and environments +* Separation from other automation content and tooling -* ``ansible-core`` -* ``ansible-runner`` -* Python -* Ansible content dependencies +You can use Ansible community EEs to get up and running. +Or you can easily build and deploy custom EEs with whatever packages and Ansible community collections you need for your project. -In addition to the standard packages, an EE can also contain: +Visit `Getting started with Execution Environments `_ in the Ansible ecosystem documentation. -* one or more Ansible collections and their dependencies -* other custom components +Ansible ecosystem +----------------- -This getting started guide shows you how to build and test a simple Execution Environment. -The resulting container image represents an Ansible control node that contains the standard EE packages plus the ``community.postgresql`` collection and the ``psycopg2-binary`` Python package. +Using EEs with projects in the Ansible ecosystem lets you expand automation to lots of use cases: -.. toctree:: - :maxdepth: 1 +* `Ansible Builder `_ +* `Ansible Navigator `_ +* `Ansible AWX `_ +* `Ansible Runner `_ +* VS Code `Ansible `_ and `Dev Containers `_ extensions - introduction - setup_environment - build_execution_environment - run_execution_environment - run_community_ee_image +Visit the `Ansible ecosystem documentation `_ to find How Tos and tutorials for using EEs with Ansible projects. diff --git a/docs/docsite/rst/getting_started_ee/introduction.rst b/docs/docsite/rst/getting_started_ee/introduction.rst deleted file mode 100644 index 6eb86042f94..00000000000 --- a/docs/docsite/rst/getting_started_ee/introduction.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. _introduction_execution_environments: - -Introduction to Execution Environments -====================================== - -Ansible Execution Environments aim to resolve complexity issues and provide all the benefits you can get from containerization. - -Reducing complexity -------------------- - -There are three main areas where EEs can reduce complexity: software dependencies, portability, and content separation. - -Dependencies -^^^^^^^^^^^^ - -Software applications typically have dependencies, and Ansible is no exception. -These dependencies can include software libraries, configuration files or other services, to name a few. - -Traditionally, administrators install application dependencies on top of an operating system using packaging management tools such as RPM or Python-pip. - -The major drawback of such an approach is that an application might require versions of dependencies different from those provided by default. - -For Ansible, a typical installation consists of ``ansible-core`` and a set of Ansible collections. -Many of them have dependencies for the plugins, modules, roles and playbooks they provide. - -The Ansible collections can depend on the following pieces of software and their versions: - -* ``ansible-core`` -* Python -* Python packages -* System packages -* Other Ansible collections - -The dependencies have to be installed and sometimes can conflict with each other. - -One way to **partially** resolve the dependency issue is to use Python virtual environments on Ansible control nodes. -However, applied to Ansible, virtual environments have drawbacks and natural limitations. - -Portability -^^^^^^^^^^^ - -An Ansible user writes content for Ansible locally and wants to leverage the container technology to make their automation runtimes portable, shareable and easily deployable to testing and production environments. - -Content separation -^^^^^^^^^^^^^^^^^^ - -In situations when there is an Ansible control node or a tool such as Ansible AWX/Controller used by several users, they might want separate their content to avoid configuration and dependency conflicts. - -.. _ansible_tooling_for_ee: - -Ansible tooling for EEs ------------------------ - -Projects in the Ansible ecosystem also provide several tools that you can use with EEs, such as: - -* `Ansible Builder `_ -* `Ansible Navigator `_ -* `Ansible AWX `_ -* `Ansible Runner `_ -* VS Code `Ansible `_ and `Dev Containers `_ extensions - -Ready to get started with EEs? -Proceed to :ref:`Setting up your environment`. diff --git a/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst b/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst deleted file mode 100644 index d4686d32610..00000000000 --- a/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. _run_community_ee_image: - -Running Ansible with the community EE image -=========================================== - -You can run ansible without the need to build a custom EE using community images. -Use the ``community-ee-minimal`` image that includes only ``ansible-core`` or -the ``community-ee-base`` image that also includes several base collections. - -Run the following command to see the collections included in the ``community-ee-base`` image: - -.. code-block:: bash - - ansible-navigator collections --execution-environment-image ghcr.io/ansible-community/community-ee-base:latest - -Run the following Ansible ad-hoc command against localhost inside the ``community-ee-minimal`` container: - -.. code-block:: bash - - ansible-navigator exec "ansible localhost -m setup" --execution-environment-image ghcr.io/ansible-community/community-ee-minimal:latest --mode stdout - -Now, create a simple test playbook and run it against localhost inside the container: - -.. code-block:: yaml - - cat > test_localhost.yml<` for an example of how to run your playbook against a remote target. - -Ready to learn how to build an Execution Environment in a few easy steps? -Proceed to the :ref:`Building your first EE`. - -.. seealso:: - - `Ansible Navigator documentation `_ - Learn more about the ansible-navigator utility. - :ref:`The list of tools for EE` - See the list of tools you can use Execution Environments with. diff --git a/docs/docsite/rst/getting_started_ee/run_execution_environment.rst b/docs/docsite/rst/getting_started_ee/run_execution_environment.rst deleted file mode 100644 index 60f53474833..00000000000 --- a/docs/docsite/rst/getting_started_ee/run_execution_environment.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. _running_execution_environments: - -Running your EE -=============== - -You can run your EE on the command line against ``localhost`` or a remote target -using ``ansible-navigator``. - -.. note:: - - There are other tools besides ``ansible-navigator`` you can run EEs with. - -Run against localhost ---------------------- - -1. Create a ``test_localhost.yml`` playbook. - -.. code-block:: yaml - - cat > test_localhost.yml< inventory/hosts.yml< test_remote.yml<`_ - More about Execution Environment definition file and available options. - `Ansible Builder CLI usage `_ - Find out more about Ansible Builder's command-line arguments. - `Ansible Navigator documentation `_ - Learn more about the ansible-navigator utility. - :ref:`The list of tools for EE` - See the list of tools you can use Execution Environments with. - :ref:`Running community EE guide` - Learn more about running the community-provided Execution Environment. - `Running a local container registry for EE `_ - Learn how to quickly set up a local container registry for your Execution Environments. diff --git a/docs/docsite/rst/getting_started_ee/setup_environment.rst b/docs/docsite/rst/getting_started_ee/setup_environment.rst deleted file mode 100644 index 0720be10a7e..00000000000 --- a/docs/docsite/rst/getting_started_ee/setup_environment.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _setting_up_environment: - -Setting up your environment -=========================== - -Complete the following steps to set up a local environment for your first Execution Environment: - -1. Ensure the following packages are installed on your system: - -* ``podman`` or ``docker`` -* ``python3`` - -If you use the DNF package manager, install these prerequisites as follows: - -.. code-block:: bash - - sudo dnf install -y podman python3 - -2. Install ``ansible-navigator``: - -.. code-block:: bash - - pip3 install ansible-navigator - -Installing ``ansible-navigator`` lets you run EEs on the command line. -It includes the ``ansible-builder`` package to build EEs. - -If you want to build EEs without testing, install only ``ansible-builder``: - -.. code-block:: bash - - pip3 install ansible-builder - -3. Verify your environment with the following commands: - -.. code-block:: bash - - ansible-navigator --version - ansible-builder --version - -Ready to build an EE in a few easy steps? -Proceed to the :ref:`Building your first EE`. - -Want to try an EE without having to build one? -Proceed to the :ref:`Running the community EE`. From a86f2ea4572bfc4812e4b0aae535be2e3b0e1411 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 25 Oct 2023 16:12:24 +0100 Subject: [PATCH 042/536] update urls for getting started with ees (#716) --- docs/docsite/rst/collections_guide/collections_installing.rst | 2 +- docs/docsite/rst/command_guide/index.rst | 2 +- docs/docsite/rst/shared_snippets/basic_concepts.txt | 2 +- docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/collections_guide/collections_installing.rst b/docs/docsite/rst/collections_guide/collections_installing.rst index 47e782b7985..48da5a69013 100644 --- a/docs/docsite/rst/collections_guide/collections_installing.rst +++ b/docs/docsite/rst/collections_guide/collections_installing.rst @@ -11,7 +11,7 @@ Installing collections in containers ------------------------------------ You can install collections with their dependencies in containers known as Execution Environments. -See `Getting started with Execution Environments `_ for details. +See `Getting started with Execution Environments `_ for details. Installing collections with ``ansible-galaxy`` ---------------------------------------------- diff --git a/docs/docsite/rst/command_guide/index.rst b/docs/docsite/rst/command_guide/index.rst index 774745eaff6..4027e3493d7 100644 --- a/docs/docsite/rst/command_guide/index.rst +++ b/docs/docsite/rst/command_guide/index.rst @@ -25,5 +25,5 @@ Ansible provides ad hoc commands and several utilities for performing various op `Ansible Navigator `_ A command-line tool and a TUI that provides a convenient user interface for most of the native Ansible command-line utilities and allows to run Ansible automation content - inside containers (`Execution Environments `_) + inside containers (`Execution Environments `_) diff --git a/docs/docsite/rst/shared_snippets/basic_concepts.txt b/docs/docsite/rst/shared_snippets/basic_concepts.txt index 2920e0a23cb..a4f7ce06130 100644 --- a/docs/docsite/rst/shared_snippets/basic_concepts.txt +++ b/docs/docsite/rst/shared_snippets/basic_concepts.txt @@ -2,7 +2,7 @@ Control node ============ The machine from which you run the Ansible CLI tools (``ansible-playbook`` , ``ansible``, ``ansible-vault`` and others). You can use any computer that meets the software requirements as a control node - laptops, shared desktops, and servers can all run Ansible. -You can also run Ansible in containers known as `Execution Environments `_. +You can also run Ansible in containers known as `Execution Environments `_. Multiple control nodes are possible, but Ansible itself does not coordinate across them, see ``AAP`` for such features. diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index a082de02ee9..f3c1bb8ab73 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -127,7 +127,7 @@ These tips apply to using Ansible, rather than to Ansible artifacts. Use Execution Environments -------------------------- -Reduce complexity with portable container images known as `Execution Environments `_. +Reduce complexity with portable container images known as `Execution Environments `_. Try it in staging first ----------------------- From d002e08d07fbb640599233f637662eceda4a9383 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 25 Oct 2023 15:26:35 +0000 Subject: [PATCH 043/536] ci: add sphinx-copybutton to requirements-relaxed.txt Both requirements-relaxed.txt and requirements.txt need to be refreshed when adding new dependencies. --- tests/requirements-relaxed.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 790b7315d61..fa5e678f891 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -118,6 +118,7 @@ sphinx==7.2.6 # -r tests/requirements-relaxed.in # antsibull-docs # sphinx-ansible-theme + # sphinx-copybutton # sphinx-intl # sphinx-notfound-page # sphinx-rtd-theme @@ -129,6 +130,8 @@ sphinx==7.2.6 # sphinxcontrib-serializinghtml sphinx-ansible-theme==0.10.2 # via -r tests/requirements-relaxed.in +sphinx-copybutton==0.5.2 + # via -r tests/requirements-relaxed.in sphinx-intl==2.1.0 # via -r tests/requirements-relaxed.in sphinx-notfound-page==1.0.0 From c9c2ae44abeb3ce8e76411f6402f4f9804787564 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Wed, 25 Oct 2023 11:17:28 -0500 Subject: [PATCH 044/536] ci: refresh dev dependencies (#721) --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 6aa9a7aeed4..ebcf05b9c50 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==23.10.0 +black==23.10.1 # via -r tests/formatters.in click==8.1.7 # via black diff --git a/tests/static.txt b/tests/static.txt index 101b61d2fad..2cb0574a25c 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.1 +ruff==0.1.2 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 184a8503e83..c8a2ea11f6f 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -12,7 +12,7 @@ cffi==1.16.0 # via # cryptography # pynacl -charset-normalizer==3.3.0 +charset-normalizer==3.3.1 # via requests click==8.1.7 # via typer @@ -20,7 +20,7 @@ codeowners==0.6.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.7.0 # via nox -cryptography==41.0.4 +cryptography==41.0.5 # via pyjwt deprecated==1.2.14 # via pygithub @@ -74,7 +74,7 @@ urllib3==2.0.7 # via # pygithub # requests -virtualenv==20.24.5 +virtualenv==20.24.6 # via nox wrapt==1.15.0 # via deprecated From e7390b443a779c63c2c4427125856d352e35ceca Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Wed, 25 Oct 2023 11:57:43 -0700 Subject: [PATCH 045/536] Proof reading (#616) * Proof reading * Fixing misc typos * Correct usage of words * Highlight keywords --------- Signed-off-by: Abhijeet Kasurde Co-authored-by: Don Naro --- .../docsite/rst/command_guide/intro_adhoc.rst | 4 +- .../dev_guide/style_guide/search_hints.rst | 6 +-- .../intro_configuration.rst | 6 +-- .../inventory_guide/connection_details.rst | 6 +-- docs/docsite/rst/inventory_guide/index.rst | 2 +- .../rst/inventory_guide/intro_inventory.rst | 14 +++-- .../developing_resource_modules_network.rst | 2 +- docs/docsite/rst/os_guide/windows_dsc.rst | 2 +- docs/docsite/rst/os_guide/windows_faq.rst | 2 +- docs/docsite/rst/os_guide/windows_setup.rst | 2 +- docs/docsite/rst/os_guide/windows_usage.rst | 2 +- docs/docsite/rst/os_guide/windows_winrm.rst | 2 +- .../playbook_guide/guide_rolling_upgrade.rst | 2 +- docs/docsite/rst/playbook_guide/playbooks.rst | 4 +- .../playbooks_advanced_syntax.rst | 2 +- .../rst/playbook_guide/playbooks_async.rst | 2 +- .../rst/playbook_guide/playbooks_blocks.rst | 4 +- .../playbook_guide/playbooks_conditionals.rst | 26 +++++----- .../rst/playbook_guide/playbooks_debugger.rst | 2 +- .../playbook_guide/playbooks_delegation.rst | 18 +++---- .../playbook_guide/playbooks_environment.rst | 4 +- .../playbooks_error_handling.rst | 14 ++--- .../rst/playbook_guide/playbooks_filters.rst | 52 +++++++++---------- .../rst/playbook_guide/playbooks_handlers.rst | 10 ++-- .../rst/playbook_guide/playbooks_lookups.rst | 2 +- .../rst/playbook_guide/playbooks_loops.rst | 12 ++--- .../playbooks_privilege_escalation.rst | 47 ++++++++--------- .../rst/playbook_guide/playbooks_prompts.rst | 4 +- .../playbooks_python_version.rst | 2 +- .../rst/playbook_guide/playbooks_reuse.rst | 2 +- .../playbook_guide/playbooks_reuse_roles.rst | 18 +++---- .../playbook_guide/playbooks_strategies.rst | 2 +- .../rst/playbook_guide/playbooks_tags.rst | 2 +- .../playbook_guide/playbooks_templating.rst | 2 +- .../rst/playbook_guide/playbooks_tests.rst | 10 ++-- .../playbook_guide/playbooks_variables.rst | 10 ++-- .../playbook_guide/playbooks_vars_facts.rst | 10 ++-- docs/docsite/rst/plugins/action.rst | 2 +- docs/docsite/rst/plugins/become.rst | 2 +- docs/docsite/rst/plugins/cache.rst | 2 +- docs/docsite/rst/plugins/callback.rst | 2 +- docs/docsite/rst/plugins/cliconf.rst | 2 +- docs/docsite/rst/plugins/connection.rst | 2 +- docs/docsite/rst/plugins/docs_fragment.rst | 2 +- docs/docsite/rst/plugins/filter.rst | 2 +- docs/docsite/rst/plugins/httpapi.rst | 2 +- docs/docsite/rst/plugins/inventory.rst | 2 +- docs/docsite/rst/plugins/lookup.rst | 2 +- docs/docsite/rst/plugins/module.rst | 2 +- docs/docsite/rst/plugins/module_util.rst | 2 +- docs/docsite/rst/plugins/netconf.rst | 2 +- docs/docsite/rst/plugins/plugins.rst | 2 +- docs/docsite/rst/plugins/shell.rst | 2 +- docs/docsite/rst/plugins/strategy.rst | 2 +- docs/docsite/rst/plugins/terminal.rst | 2 +- docs/docsite/rst/plugins/test.rst | 2 +- docs/docsite/rst/plugins/vars.rst | 2 +- .../rst/reference_appendices/YAMLSyntax.rst | 2 +- docs/docsite/rst/reference_appendices/faq.rst | 2 +- .../rst/reference_appendices/glossary.rst | 2 +- .../reference_appendices/test_strategies.rst | 2 +- .../docsite/rst/scenario_guides/guide_aci.rst | 2 +- .../installing_collections_git_repo.txt | 2 +- .../rst/tips_tricks/ansible_tips_tricks.rst | 2 +- docs/docsite/rst/tips_tricks/sample_setup.rst | 2 +- 65 files changed, 183 insertions(+), 186 deletions(-) diff --git a/docs/docsite/rst/command_guide/intro_adhoc.rst b/docs/docsite/rst/command_guide/intro_adhoc.rst index 8e29c9cf5b2..1f9406df092 100644 --- a/docs/docsite/rst/command_guide/intro_adhoc.rst +++ b/docs/docsite/rst/command_guide/intro_adhoc.rst @@ -42,7 +42,7 @@ The default module for the ``ansible`` command-line utility is the :ref:`ansible $ ansible atlanta -a "/sbin/reboot" -By default Ansible uses only 5 simultaneous processes. If you have more hosts than the value set for the fork count, Ansible will talk to them, but it will take a little longer. To reboot the [atlanta] servers with 10 parallel forks: +By default, Ansible uses only five simultaneous processes. If you have more hosts than the value set for the fork count, it can increase the time it takes for Ansible to communicate with the hosts. To reboot the [atlanta] servers with 10 parallel forks: .. code-block:: bash @@ -63,7 +63,7 @@ Rebooting probably requires privilege escalation. You can connect to the server If you add ``--ask-become-pass`` or ``-K``, Ansible prompts you for the password to use for privilege escalation (sudo/su/pfexec/doas/etc). .. note:: - The :ref:`command module ` does not support extended shell syntax like piping and + The :ref:`command module ` does not support extended shell syntaxes like piping and redirects (although shell variables will always work). If your command requires shell-specific syntax, use the `shell` module instead. Read more about the differences on the :ref:`working_with_modules` page. diff --git a/docs/docsite/rst/dev_guide/style_guide/search_hints.rst b/docs/docsite/rst/dev_guide/style_guide/search_hints.rst index d9bf3f665a7..82a559d95c4 100644 --- a/docs/docsite/rst/dev_guide/style_guide/search_hints.rst +++ b/docs/docsite/rst/dev_guide/style_guide/search_hints.rst @@ -10,7 +10,7 @@ To ensure Ansible documentation is findable, you should: #. Use headings that clearly reflect what you are documenting. #. Use numbered lists for procedures or high-level steps where possible. -#. Avoid linking to github blobs where possible. +#. Avoid linking to GitHub blobs where possible. Using clear headings in documentation @@ -33,10 +33,10 @@ Google can optimize the search results by adding a `feature snippet `. +Paths where the configuration file is searched are listed in :ref:`reference documentation`. .. _getting_the_latest_configuration: @@ -28,7 +28,7 @@ Getting the latest configuration If installing Ansible from a package manager, the latest ``ansible.cfg`` file should be present in ``/etc/ansible``, possibly as a ``.rpmnew`` file (or other) as appropriate in the case of updates. -If you installed Ansible from ``pip`` or from source, you may want to create this file in order to override +If you installed Ansible from ``pip`` or from the source, you may want to create this file to override default settings in Ansible. You can generate an Ansible configuration file, ``ansible.cfg``, that lists all default settings as follows: @@ -54,7 +54,7 @@ For in-depth details, see :ref:`ansible_configuration_settings`. Environmental configuration =========================== -Ansible also allows configuration of settings using environment variables. +Ansible also allows configuring settings using environment variables. If these environment variables are set, they will override any associated settings loaded from the configuration file. You can get a full listing of available environment variables from: diff --git a/docs/docsite/rst/inventory_guide/connection_details.rst b/docs/docsite/rst/inventory_guide/connection_details.rst index f6911fff80d..2c462e32b4d 100644 --- a/docs/docsite/rst/inventory_guide/connection_details.rst +++ b/docs/docsite/rst/inventory_guide/connection_details.rst @@ -9,7 +9,7 @@ This section shows you how to expand and refine the connection methods Ansible u ControlPersist and paramiko --------------------------- -By default, Ansible uses native OpenSSH, because it supports ControlPersist (a performance feature), Kerberos, and options in ``~/.ssh/config`` such as Jump Host setup. If your control machine uses an older version of OpenSSH that does not support ControlPersist, Ansible will fallback to a Python implementation of OpenSSH called 'paramiko'. +By default, Ansible uses native OpenSSH, because it supports ControlPersist (a performance feature), Kerberos, and options in ``~/.ssh/config`` such as Jump Host setup. If your control machine uses an older version of OpenSSH that does not support ControlPersist, Ansible will fall back to a Python implementation of OpenSSH called 'paramiko'. .. _connection_set_user: @@ -108,13 +108,13 @@ If you understand the implications and wish to disable this behavior, you can do [defaults] host_key_checking = False -Alternatively this can be set by the :envvar:`ANSIBLE_HOST_KEY_CHECKING` environment variable: +Alternatively, this can be set by the :envvar:`ANSIBLE_HOST_KEY_CHECKING` environment variable: .. code-block:: bash $ export ANSIBLE_HOST_KEY_CHECKING=False -Also note that host key checking in paramiko mode is reasonably slow, therefore switching to 'ssh' is also recommended when using this feature. +Also note that host key checking in ``paramiko`` mode is reasonably slow, therefore switching to 'ssh' is also recommended when using this feature. Other connection methods ------------------------ diff --git a/docs/docsite/rst/inventory_guide/index.rst b/docs/docsite/rst/inventory_guide/index.rst index 7b984eb1d74..709c85088ba 100644 --- a/docs/docsite/rst/inventory_guide/index.rst +++ b/docs/docsite/rst/inventory_guide/index.rst @@ -14,7 +14,7 @@ Welcome to the guide to building Ansible inventories. An inventory is a list of managed nodes, or hosts, that Ansible deploys and configures. This guide introduces you to inventories and covers the following topics: -* Creating inventories to track list of servers and devices that you want to automate. +* Creating inventories to track a list of servers and devices that you want to automate. * Using dynamic inventories to track cloud services with servers and devices that are constantly starting and stopping. * Using patterns to automate specific sub-sets of an inventory. * Expanding and refining the connection methods Ansible uses for your inventory. diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index 94118538eb5..93c36dd1126 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -11,7 +11,7 @@ Once your inventory is defined, you use :ref:`patterns ` to sele The simplest inventory is a single file with a list of hosts and groups. The default location for this file is ``/etc/ansible/hosts``. You can specify a different inventory file at the command line using the ``-i `` option or in configuration using ``inventory``. -Ansible :ref:`inventory_plugins` support a range of formats and sources to make your inventory flexible and customizable. As your inventory expands, you may need more than a single file to organize your hosts and groups. Here are three options beyond the ``/etc/ansible/hosts`` file: +Ansible :ref:`inventory_plugins` supports a range of formats and sources to make your inventory flexible and customizable. As your inventory expands, you may need more than a single file to organize your hosts and groups. Here are three options beyond the ``/etc/ansible/hosts`` file: - You can create a directory with multiple inventory files. See :ref:`inventory_directory`. These can use different formats (YAML, ini, and so on). - You can pull inventory dynamically. For example, you can use a dynamic inventory plugin to list resources in one or more cloud providers. See :ref:`intro_dynamic_inventory`. @@ -521,7 +521,7 @@ By default, variables are merged/flattened to the specific host before a play is - child group - host -By default, Ansible merges groups at the same parent/child level in ASCII order, and variables from the last group loaded overwrite variables from the previous groups. For example, an a_group will be merged with b_group and b_group vars that match will overwrite the ones in a_group. +By default, Ansible merges groups at the same parent/child level in ASCII order, and variables from the last group loaded overwrite variables from the previous groups. For example, an ``a_group`` will be merged with ``b_group`` and ``b_group`` vars that match will overwrite the ones in ``a_group``. You can change this behavior by setting the group variable ``ansible_group_priority`` to change the merge order for groups of the same level (after the parent/child order is resolved). The larger the number, the later it will be merged, giving it higher priority. This variable defaults to ``1`` if not set. For example: @@ -571,14 +571,14 @@ For more details on inventory plugins and dynamic inventory scripts see :ref:`in Connecting to hosts: behavioral inventory parameters ==================================================== -As described above, setting the following variables control how Ansible interacts with remote hosts. +As described above, setting the following variables controls how Ansible interacts with remote hosts. Host connection: .. include:: shared_snippets/SSH_password_prompt.txt ansible_connection - Connection type to the host. This can be the name of any of Ansible's connection plugins. SSH protocol types are ``smart``, ``ssh`` or ``paramiko``. The default is smart. Non-SSH based types are described in the next section. + Connection type to the host. This can be the name of any Ansible connection plugin. SSH protocol types are ``smart``, ``ssh`` or ``paramiko``. The default is smart. Non-SSH based types are described in the next section. General for all connections: @@ -595,7 +595,7 @@ ansible_password Specific to the SSH connection: ansible_ssh_private_key_file - Private key file used by SSH. Useful if using multiple keys and you do not want to use SSH agent. + Private key file used by SSH. Useful if using multiple keys and you do not want to use SSH agent. ansible_ssh_common_args This setting is always appended to the default command line for :command:`sftp`, :command:`scp`, and :command:`ssh`. Useful to configure a ``ProxyCommand`` for a certain host (or @@ -640,7 +640,7 @@ ansible_shell_type .. _ansible_python_interpreter: ansible_python_interpreter - The target host python path. This is useful for systems with more + The target host Python path. This is useful for systems with more than one Python or not located at :command:`/usr/bin/python` such as \*BSD, or where :command:`/usr/bin/python` is not a 2.X series Python. We do not use the :command:`/usr/bin/env` mechanism as that requires the remote user's path to be set right and also assumes the :program:`python` executable is named python, where the executable might @@ -675,10 +675,8 @@ Non-SSH connection types As stated in the previous section, Ansible executes playbooks over SSH but it is not limited to this connection type. With the host-specific parameter ``ansible_connection=``, the connection type can be changed. - For a full list with available plugins and examples, see :ref:`connection_plugin_list`. - .. _inventory_setup_examples: Inventory setup examples diff --git a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst index eefedb67f15..7ed80ce1d51 100644 --- a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst +++ b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst @@ -98,7 +98,7 @@ Accessing the resource module builder To access the resource module builder: -1. clone the github repository: +1. clone the GitHub repository: .. code-block:: bash diff --git a/docs/docsite/rst/os_guide/windows_dsc.rst b/docs/docsite/rst/os_guide/windows_dsc.rst index 1588a2329fc..651548bcc4e 100644 --- a/docs/docsite/rst/os_guide/windows_dsc.rst +++ b/docs/docsite/rst/os_guide/windows_dsc.rst @@ -503,6 +503,6 @@ Setup IIS Website :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/os_guide/windows_faq.rst b/docs/docsite/rst/os_guide/windows_faq.rst index 5e70c45e0a5..f4a8a1c8b68 100644 --- a/docs/docsite/rst/os_guide/windows_faq.rst +++ b/docs/docsite/rst/os_guide/windows_faq.rst @@ -244,6 +244,6 @@ host. :ref:`playbooks_best_practices` Tips and tricks for playbooks `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/os_guide/windows_setup.rst b/docs/docsite/rst/os_guide/windows_setup.rst index 6e57590c3a8..36660c440b1 100644 --- a/docs/docsite/rst/os_guide/windows_setup.rst +++ b/docs/docsite/rst/os_guide/windows_setup.rst @@ -494,6 +494,6 @@ Using SSH with Windows is experimental. Currently existing issues are: :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/os_guide/windows_usage.rst b/docs/docsite/rst/os_guide/windows_usage.rst index fd5566e8d22..c37fcb218d9 100644 --- a/docs/docsite/rst/os_guide/windows_usage.rst +++ b/docs/docsite/rst/os_guide/windows_usage.rst @@ -514,6 +514,6 @@ guides for Windows modules differ substantially from those for standard standard :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/os_guide/windows_winrm.rst b/docs/docsite/rst/os_guide/windows_winrm.rst index 9c5b19a58cf..d87cac8956b 100644 --- a/docs/docsite/rst/os_guide/windows_winrm.rst +++ b/docs/docsite/rst/os_guide/windows_winrm.rst @@ -1028,6 +1028,6 @@ Some of these limitations can be mitigated by doing one of the following: :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst b/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst index 36fbd736d3e..d4f306a30c8 100644 --- a/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst +++ b/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst @@ -30,7 +30,7 @@ rolling upgrades of the web application stack. The playbooks deploy Apache, PHP, MySQL, Nagios, and HAProxy to a CentOS-based set of servers. -We're not going to cover how to run these playbooks here. Read the included README in the github project along with the +We're not going to cover how to run these playbooks here. Read the included README in the GitHub project along with the example for that information. Instead, we're going to take a close look at every part of the playbook and describe what it does. .. _lamp_deployment: diff --git a/docs/docsite/rst/playbook_guide/playbooks.rst b/docs/docsite/rst/playbook_guide/playbooks.rst index 48ea92fb57e..924e4e357d8 100644 --- a/docs/docsite/rst/playbook_guide/playbooks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks.rst @@ -6,10 +6,10 @@ Working with playbooks Playbooks record and execute Ansible's configuration, deployment, and orchestration functions. They can describe a policy you want your remote systems to enforce, or a set of steps in a general IT process. -If Ansible modules are the tools in your workshop, playbooks are your instruction manuals, and your inventory of hosts are your raw material. +If Ansible modules are the tools in your workshop, playbooks are your instruction manuals, and your inventory of hosts is your raw material. At a basic level, playbooks can be used to manage configurations of and deployments to remote machines. -At a more advanced level, they can sequence multi-tier rollouts involving rolling updates, and can delegate actions to other hosts, interacting with monitoring servers and load balancers along the way. +At a more advanced level, they can sequence multi-tier rollouts involving rolling updates and can delegate actions to other hosts, interacting with monitoring servers and load balancers along the way. Playbooks are designed to be human-readable and are developed in a basic text language. There are multiple ways to organize playbooks and the files they include, and we'll offer up some suggestions on that and making the most out of Ansible. diff --git a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst index e4c53d59e58..1a84cb41e29 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst @@ -117,6 +117,6 @@ You've anchored the value of ``version`` with the ``&my_version`` anchor, and re :ref:`complex_data_manipulation` Doing complex data manipulation in Ansible `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_async.rst b/docs/docsite/rst/playbook_guide/playbooks_async.rst index 2f56dbf78cb..87842db72b9 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_async.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_async.rst @@ -184,6 +184,6 @@ To run multiple asynchronous tasks while limiting the number of tasks running co :ref:`playbooks_intro` An introduction to playbooks `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst index ecf45cc531b..795c6d9525c 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst @@ -145,7 +145,7 @@ Together, these elements offer complex error handling. The tasks in the ``block`` execute normally. If any tasks in the block return ``failed``, the ``rescue`` section executes tasks to recover from the error. The ``always`` section runs regardless of the results of the ``block`` and ``rescue`` sections. -If an error occurs in the block and the rescue task succeeds, Ansible reverts the failed status of the original task for the run and continues to run the play as if the original task had succeeded. The rescued task is considered successful, and does not trigger ``max_fail_percentage`` or ``any_errors_fatal`` configurations. However, Ansible still reports a failure in the playbook statistics. +If an error occurs in the block and the rescue task succeeds, Ansible reverts the failed status of the original task for the run and continues to run the play as if the original task had succeeded. The rescued task is considered successful and does not trigger ``max_fail_percentage`` or ``any_errors_fatal`` configurations. However, Ansible still reports a failure in the playbook statistics. You can use blocks with ``flush_handlers`` in a rescue task to ensure that all handlers run even if an error occurs: @@ -219,6 +219,6 @@ These can be inspected in the ``rescue`` section: :ref:`playbooks_reuse_roles` Playbook organization by roles `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst index 31ad1136239..19a36be16f8 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst @@ -4,9 +4,9 @@ Conditionals ************ -In a playbook, you may want to execute different tasks, or have different goals, depending on the value of a fact (data about the remote system), a variable, or the result of a previous task. You may want the value of some variables to depend on the value of other variables. Or you may want to create additional groups of hosts based on whether the hosts match other criteria. You can do all of these things with conditionals. +In a playbook, you may want to execute different tasks or have different goals, depending on the value of a fact (data about the remote system), a variable, or the result of a previous task. You may want the value of some variables to depend on the value of other variables. Or you may want to create additional groups of hosts based on whether the hosts match other criteria. You can do all of these things with conditionals. -Ansible uses Jinja2 :ref:`tests ` and :ref:`filters ` in conditionals. Ansible supports all the standard tests and filters, and adds some unique ones as well. +Ansible uses Jinja2 :ref:`tests ` and :ref:`filters ` in conditionals. Ansible supports all the standard tests and filters and adds some unique ones as well. .. note:: @@ -42,7 +42,7 @@ Often you want to execute or skip a task based on facts. Facts are attributes of - You can skip configuring a firewall on hosts with internal IP addresses. - You can perform cleanup tasks only when a filesystem is getting full. -See :ref:`commonly_used_facts` for a list of facts that frequently appear in conditional statements. Not all facts exist for all hosts. For example, the 'lsb_major_release' fact used in an example below only exists when the lsb_release package is installed on the target host. To see what facts are available on your systems, add a debug task to your playbook: +See :ref:`commonly_used_facts` for a list of facts that frequently appear in conditional statements. Not all facts exist for all hosts. For example, the 'lsb_major_release' fact used in the example below only exists when the ``lsb_release package`` is installed on the target host. To see what facts are available on your systems, add a debug task to your playbook: .. code-block:: yaml @@ -106,12 +106,12 @@ You can store Ansible facts as variables to use for conditional logic, as in the Conditions based on registered variables ---------------------------------------- -Often in a playbook you want to execute or skip a task based on the outcome of an earlier task. For example, you might want to configure a service after it is upgraded by an earlier task. To create a conditional based on a registered variable: +Often in a playbook, you want to execute or skip a task based on the outcome of an earlier task. For example, you might want to configure a service after it is upgraded by an earlier task. To create a conditional based on a registered variable: #. Register the outcome of the earlier task as a variable. #. Create a conditional test based on the registered variable. -You create the name of the registered variable using the ``register`` keyword. A registered variable always contains the status of the task that created it as well as any output that task generated. You can use registered variables in templates and action lines as well as in conditional ``when`` statements. You can access the string contents of the registered variable using ``variable.stdout``. For example: +You create the name of the registered variable using the ``register`` keyword. A registered variable always contains the status of the task that created it as well as any output that the task generated. You can use registered variables in templates and action lines as well as in conditional ``when`` statements. You can access the string contents of the registered variable using ``variable.stdout``. For example: .. code-block:: yaml @@ -198,7 +198,7 @@ Ansible always registers something in a registered variable for every host, even Conditionals based on variables ------------------------------- -You can also create conditionals based on variables defined in the playbooks or inventory. Because conditionals require boolean input (a test must evaluate as True to trigger the condition), you must apply the ``| bool`` filter to non boolean variables, such as string variables with content like 'yes', 'on', '1', or 'true'. You can define variables like this: +You can also create conditionals based on variables defined in the playbooks or inventory. Because conditionals require boolean input (a test must evaluate as True to trigger the condition), you must apply the ``| bool`` filter to non-boolean variables, such as string variables with content like 'yes', 'on', '1', or 'true'. You can define variables like this: .. code-block:: yaml @@ -232,7 +232,7 @@ If a required variable has not been set, you can skip or fail using Jinja2's `de ansible.builtin.fail: msg="Bailing out. This play requires 'bar'" when: bar is undefined -This is especially useful in combination with the conditional import of vars files (see below). +This is especially useful in combination with the conditional import of ``vars`` files (see below). As the examples show, you do not need to use `{{ }}` to use variables inside conditionals, as these are already implied. .. _loops_and_conditionals: @@ -273,7 +273,7 @@ You can do the same thing when looping over a dict: Loading custom facts -------------------- -You can provide your own facts, as described in :ref:`developing_modules`. To run them, just make a call to your own custom fact gathering module at the top of your list of tasks, and variables returned there will be accessible to future tasks: +You can provide your own facts, as described in :ref:`developing_modules`. To run them, just make a call to your own custom fact gathering module at the top of your list of tasks, and the variables returned there will be accessible for future tasks: .. code-block:: yaml @@ -288,16 +288,16 @@ You can provide your own facts, as described in :ref:`developing_modules`. To r .. _when_with_reuse: Conditionals with reuse ------------------------- +----------------------- -You can use conditionals with reusable tasks files, playbooks, or roles. Ansible executes these conditional statements differently for dynamic reuse (includes) and for static reuse (imports). See :ref:`playbooks_reuse` for more information on reuse in Ansible. +You can use conditionals with reusable tasks files, playbooks, or roles. Ansible executes these conditional statements differently for dynamic reuse (includes) and static reuse (imports). See :ref:`playbooks_reuse` for more information on reuse in Ansible. .. _conditional_imports: Conditionals with imports ^^^^^^^^^^^^^^^^^^^^^^^^^ -When you add a conditional to an import statement, Ansible applies the condition to all tasks within the imported file. This behavior is the equivalent of :ref:`tag_inheritance`. Ansible applies the condition to every task, and evaluates each task separately. For example, if you want to define and then display a variable that was not previously defined, you might have a playbook called ``main.yml`` and a tasks file called ``other_tasks.yml``: +When you add a conditional to an import statement, Ansible applies the condition to all tasks within the imported file. This behavior is the equivalent of :ref:`tag_inheritance`. Ansible applies the condition to every task and evaluates each task separately. For example, if you want to define and then display a variable that was not previously defined, you might have a playbook called ``main.yml`` and a tasks file called ``other_tasks.yml``: .. code-block:: yaml @@ -419,7 +419,7 @@ When you incorporate a role in your playbook statically with the ``roles`` keywo Selecting variables, files, or templates based on facts ------------------------------------------------------- -Sometimes the facts about a host determine the values you want to use for certain variables or even the file or template you want to select for that host. For example, the names of packages are different on CentOS and on Debian. The configuration files for common services are also different on different OS flavors and versions. To load different variables file, templates, or other files based on a fact about the hosts: +Sometimes the facts about a host determine the values you want to use for certain variables or even the file or template you want to select for that host. For example, the names of packages are different on CentOS and Debian. The configuration files for common services are also different on different OS flavors and versions. To load different variables files, templates, or other files based on a fact about the hosts: 1) name your vars files, templates, or files to match the Ansible fact that differentiates them @@ -601,6 +601,6 @@ Possible values (sample, not complete list): :ref:`playbooks_variables` All about variables `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst index 79d7c31ee09..97e6463d3dc 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst @@ -337,6 +337,6 @@ With the default ``linear`` strategy enabled, Ansible halts execution while the :ref:`playbooks_intro` An introduction to playbooks `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_delegation.rst b/docs/docsite/rst/playbook_guide/playbooks_delegation.rst index 8efdc90ed36..ae708bf3ec1 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_delegation.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_delegation.rst @@ -3,7 +3,7 @@ Controlling where tasks run: delegation and local actions ========================================================= -By default Ansible gathers facts and executes all tasks on the machines that match the ``hosts`` line of your playbook. This page shows you how to delegate tasks to a different machine or group, delegate facts to specific machines or groups, or run an entire playbook locally. Using these approaches, you can manage inter-related environments precisely and efficiently. For example, when updating your webservers, you might need to remove them from a load-balanced pool temporarily. You cannot perform this task on the webservers themselves. By delegating the task to localhost, you keep all the tasks within the same play. +By default, Ansible gathers facts and executes all tasks on the machines that match the ``hosts`` line of your playbook. This page shows you how to delegate tasks to a different machine or group, delegate facts to specific machines or groups, or run an entire playbook locally. Using these approaches, you can manage inter-related environments precisely and efficiently. For example, when updating your webservers, you might need to remove them from a load-balanced pool temporarily. You cannot perform this task on the webservers themselves. By delegating the task to localhost, you keep all the tasks within the same play. .. contents:: :local: @@ -11,7 +11,7 @@ By default Ansible gathers facts and executes all tasks on the machines that mat Tasks that cannot be delegated ------------------------------ -Some tasks always execute on the control node. These tasks, including ``include``, ``add_host``, and ``debug``, cannot be delegated. +Some tasks always executed on the control node. These tasks, including ``include``, ``add_host``, and ``debug``, cannot be delegated. You can determine if an action can be delegated from the ``connection`` attribute documentation. If the ``connection`` attribute indicates ``support`` is ``False`` or ``None``, then the action does not use a connection and cannot be delegated. @@ -20,7 +20,7 @@ If the ``connection`` attribute indicates ``support`` is ``False`` or ``None``, Delegating tasks ---------------- -If you want to perform a task on one host with reference to other hosts, use the ``delegate_to`` keyword on a task. This is ideal for managing nodes in a load balanced pool or for controlling outage windows. You can use delegation with the :ref:`serial ` keyword to control the number of hosts executing at one time: +If you want to perform a task on one host with the reference to other hosts, use the ``delegate_to`` keyword on a task. This is ideal for managing nodes in a load-balanced pool or for controlling outage windows. You can use delegation with the :ref:`serial ` keyword to control the number of hosts executing at one time: .. code-block:: yaml @@ -92,7 +92,7 @@ To specify more arguments, use the following syntax: .. warning:: - Although you can ``delegate_to`` a host that does not exist in inventory (by adding IP address, DNS name or whatever requirement the connection plugin has), doing so does not add the host to your inventory and might cause issues. Hosts delegated to in this way do not inherit variables from the "all" group', so variables like connection user and key are missing. If you must ``delegate_to`` a non-inventory host, use the :ref:`add host module `. + Although you can ``delegate_to`` a host that does not exist in inventory (by adding an IP address, DNS name or whatever requirement the connection plugin has), doing so does not add the host to your inventory and might cause issues. Hosts delegated to in this way do not inherit variables from the "all" group', so variables like connection user and key are missing. If you must ``delegate_to`` a non-inventory host, use the :ref:`add host module `. .. _delegate_templating: @@ -107,7 +107,7 @@ Be advised that under delegation, the execution interpreter (normally Python), ` Delegation and parallel execution --------------------------------- -By default Ansible tasks are executed in parallel. Delegating a task does not change this and does not handle concurrency issues (multiple forks writing to the same file). +By default, Ansible tasks are executed in parallel. Delegating a task does not change this and does not handle concurrency issues (multiple forks writing to the same file). Most commonly, users are affected by this when updating a single file on a single delegated to host for all hosts (using the ``copy``, ``template``, or ``lineinfile`` modules, for example). They will still operate in parallel forks (default 5) and overwrite each other. This can be handled in several ways: @@ -119,14 +119,14 @@ This can be handled in several ways: run_once: true loop: '{{ ansible_play_hosts_all }}' -By using an intermediate play with `serial: 1` or using `throttle: 1` at task level, for more detail see :ref:`playbooks_strategies` +By using an intermediate play with `serial: 1` or using `throttle: 1` at the task level, for more detail see :ref:`playbooks_strategies` .. _delegate_facts: Delegating facts ---------------- -Delegating Ansible tasks is like delegating tasks in the real world - your groceries belong to you, even if someone else delivers them to your home. Similarly, any facts gathered by a delegated task are assigned by default to the `inventory_hostname` (the current host), not to the host which produced the facts (the delegated to host). To assign gathered facts to the delegated host instead of the current host, set ``delegate_facts`` to ``true``: +Delegating Ansible tasks is like delegating tasks in the real world - your groceries belong to you, even if someone else delivers them to your home. Similarly, any facts gathered by a delegated task are assigned by default to the `inventory_hostname` (the current host), not to the host that produced the facts (the delegated to host). To assign gathered facts to the delegated host instead of the current host, set ``delegate_facts`` to ``true``: .. code-block:: yaml @@ -140,7 +140,7 @@ Delegating Ansible tasks is like delegating tasks in the real world - your groce delegate_facts: true loop: "{{ groups['dbservers'] }}" -This task gathers facts for the machines in the dbservers group and assigns the facts to those machines, even though the play targets the app_servers group. This way you can lookup `hostvars['dbhost1']['ansible_default_ipv4']['address']` even though dbservers were not part of the play, or left out by using `--limit`. +This task gathers facts for the machines in the dbservers group and assigns the facts to those machines, even though the play targets the app_servers group. This way you can lookup `hostvars['dbhost1']['ansible_default_ipv4']['address']` even though dbservers were not part of the play, or left out by using ``--limit``. .. _local_playbooks: @@ -179,6 +179,6 @@ use the default remote connection type: `Ansible Examples on GitHub `_ Many examples of full-stack deployments `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_environment.rst b/docs/docsite/rst/playbook_guide/playbooks_environment.rst index c4ec680dbe9..d4fe6094f51 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_environment.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_environment.rst @@ -82,7 +82,7 @@ These examples show proxy settings, but you can provide any number of settings t Working with language-specific version managers =============================================== -Some language-specific version managers (such as rbenv and nvm) require you to set environment variables while these tools are in use. When using these tools manually, you usually source some environment variables from a script or from lines added to your shell configuration file. In Ansible, you can do this with the environment keyword at the play level. +Some language-specific version managers (such as ``rbenv`` and ``nvm``) require you to set environment variables while these tools are in use. When using these tools manually, you usually source some environment variables from a script or lines added to your shell configuration file. In Ansible, you can do this with the environment keyword at the play level. .. code-block:: yaml+jinja @@ -148,6 +148,6 @@ You can also specify the environment at the task level. :ref:`playbooks_intro` An introduction to playbooks `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst index d94fc1ef46c..d0a134bf8d9 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst @@ -4,7 +4,7 @@ Error handling in playbooks *************************** -When Ansible receives a non-zero return code from a command or a failure from a module, by default it stops executing on that host and continues on other hosts. However, in some circumstances you may want different behavior. Sometimes a non-zero return code indicates success. Sometimes you want a failure on one host to stop execution on all hosts. Ansible provides tools and settings to handle these situations and help you get the behavior, output, and reporting you want. +When Ansible receives a non-zero return code from a command or a failure from a module, by default it stops executing on that host and continues on other hosts. However, in some circumstances, you may want different behavior. Sometimes a non-zero return code indicates success. Sometimes you want a failure on one host to stop execution on all hosts. Ansible provides tools and settings to handle these situations and help you get the behavior, output, and reporting you want. .. contents:: :local: @@ -14,7 +14,7 @@ When Ansible receives a non-zero return code from a command or a failure from a Ignoring failed commands ======================== -By default Ansible stops executing tasks on a host when a task fails on that host. You can use ``ignore_errors`` to continue on in spite of the failure. +By default, Ansible stops executing tasks on a host when a task fails on that host. You can use ``ignore_errors`` to continue despite of the failure. .. code-block:: yaml @@ -22,7 +22,7 @@ By default Ansible stops executing tasks on a host when a task fails on that hos ansible.builtin.command: /bin/false ignore_errors: true -The ``ignore_errors`` directive only works when the task is able to run and returns a value of 'failed'. It does not make Ansible ignore undefined variable errors, connection failures, execution issues (for example, missing packages), or syntax errors. +The ``ignore_errors`` directive only works when the task can run and returns a value of 'failed'. It does not make Ansible ignore undefined variable errors, connection failures, execution issues (for example, missing packages), or syntax errors. .. _ignore_unreachable: @@ -31,7 +31,7 @@ Ignoring unreachable host errors .. versionadded:: 2.7 -You can ignore a task failure due to the host instance being 'UNREACHABLE' with the ``ignore_unreachable`` keyword. Ansible ignores the task errors, but continues to execute future tasks against the unreachable host. For example, at the task level: +You can ignore a task failure due to the host instance being 'UNREACHABLE' with the ``ignore_unreachable`` keyword. Ansible ignores the task errors but continues to execute future tasks against the unreachable host. For example, at the task level: .. code-block:: yaml @@ -194,7 +194,7 @@ Sometimes you want a failure on a single host, or failures on a certain percenta Aborting on the first error: any_errors_fatal --------------------------------------------- -If you set ``any_errors_fatal`` and a task returns an error, Ansible finishes the fatal task on all hosts in the current batch, then stops executing the play on all hosts. Subsequent tasks and plays are not executed. You can recover from fatal errors by adding a :ref:`rescue section ` to the block. You can set ``any_errors_fatal`` at the play or block level. +If you set ``any_errors_fatal`` and a task returns an error, Ansible finishes the fatal task on all hosts in the current batch and then stops executing the play on all hosts. Subsequent tasks and plays are not executed. You can recover from fatal errors by adding a :ref:`rescue section ` to the block. You can set ``any_errors_fatal`` at the play or block level. .. code-block:: yaml @@ -236,7 +236,7 @@ You can use this feature when all tasks must be 100% successful to continue play - name: Start datacenter 'A' ansible.builtin.command: /usr/bin/enable-dc -In this example Ansible starts the software upgrade on the front ends only if all of the load balancers are successfully disabled. +In this example, Ansible starts the software upgrade on the front ends only if all of the load balancers are successfully disabled. .. _maximum_failure_percentage: @@ -274,6 +274,6 @@ You can also use blocks to define responses to task errors. This approach is sim :ref:`playbooks_variables` All about variables `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index 90a70a02733..21c48725096 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -43,7 +43,7 @@ If you want to use the default value when variables evaluate to false or an empt Making variables optional ------------------------- -By default Ansible requires values for all variables in a templated expression. However, you can make specific module variables optional. For example, you might want to use a system default for some items and control the value for others. To make a module variable optional, set the default value to the special variable ``omit``: +By default, Ansible requires values for all variables in a templated expression. However, you can make specific module variables optional. For example, you might want to use a system default for some items and control the value for others. To make a module variable optional, set the default value to the special variable ``omit``: .. code-block:: yaml+jinja @@ -92,7 +92,7 @@ You can create a test, then define one value to use when the test returns true a {{ (status == 'needs_restart') | ternary('restart', 'continue') }} -In addition, you can define a one value to use on true, one value on false and a third value on null (new in version 2.8): +In addition, you can define one value to use on true, one value on false and a third value on null (new in version 2.8): .. code-block:: yaml+jinja @@ -276,7 +276,7 @@ You can change the indentation of either format: {{ some_variable | to_nice_json(indent=2) }} {{ some_variable | to_nice_yaml(indent=8) }} -The :ansplugin:`ansible.builtin.to_yaml#filter` and :ansplugin:`ansible.builtin.to_nice_yaml#filter` filters use the `PyYAML library`_ which has a default 80 symbol string length limit. That causes unexpected line break after 80th symbol (if there is a space after 80th symbol) +The :ansplugin:`ansible.builtin.to_yaml#filter` and :ansplugin:`ansible.builtin.to_nice_yaml#filter` filters use the `PyYAML library`_ which has a default 80 symbol string length limit. That causes an unexpected line break after 80th symbol (if there is a space after 80th symbol) To avoid such behavior and generate long lines, use the :ansopt:`width` option. You must use a hardcoded number to define the width, instead of a construction like ``float("inf")``, because the filter does not support proxying Python functions. For example: .. code-block:: yaml+jinja @@ -371,7 +371,7 @@ To get a list combining the elements of other lists use :ansplugin:`ansible.buil # => [[1, "a"], [2, "b"], [3, "c"], [4, "d"], [5, "e"], [6, "f"]] - - name: Give me shortest combo of two lists + - name: Give me the shortest combo of two lists ansible.builtin.debug: msg: "{{ [1,2,3] | zip(['a','b','c','d','e','f']) | list }}" @@ -381,7 +381,7 @@ To always exhaust all lists use :ansplugin:`ansible.builtin.zip_longest#filter`: .. code-block:: yaml+jinja - - name: Give me longest combo of three lists , fill with X + - name: Give me the longest combo of three lists, fill with X ansible.builtin.debug: msg: "{{ [1,2,3] | zip_longest(['a','b','c','d','e','f'], [21, 22, 23], fillvalue='X') | list }}" @@ -549,7 +549,7 @@ This would result in: b: patch c: default -If :ansopt:`ansible.builtin.combine#filter:recursive=True`, recurse into nested hash and merge their keys: +If :ansopt:`ansible.builtin.combine#filter:recursive=True`, recurse into a nested hash and merge their keys: .. code-block:: yaml+jinja @@ -786,7 +786,7 @@ To get permutations of a list: .. code-block:: yaml+jinja - - name: Give me largest permutations (order matters) + - name: Give me the largest permutations (order matters) ansible.builtin.debug: msg: "{{ [1,2,3,4,5] | ansible.builtin.permutations | list }}" @@ -1056,7 +1056,7 @@ You can initialize the random number generator from a seed to create random-but- Shuffling a list ---------------- -The :ansplugin:`ansible.builtin.shuffle#filter` filter randomizes an existing list, giving a different order every invocation. +The :ansplugin:`ansible.builtin.shuffle#filter` filter randomizes an existing list, giving a different order for every invocation. To get a random list from an existing list: @@ -1084,7 +1084,7 @@ Managing list variables You can search for the minimum or maximum value in a list, or flatten a multi-level list. -To get the minimum value from list of numbers: +To get the minimum value from the list of numbers: .. code-block:: yaml+jinja @@ -1450,14 +1450,14 @@ value using the same ``show vlan | display xml`` command. The value of ``top`` is the XPath relative to the XML root node. -In the example XML output given below, the value of ``top`` is ``configuration/vlans/vlan``, +In the example, XML output given below, the value of ``top`` is ``configuration/vlans/vlan``, which is an XPath expression relative to the root node (). -``configuration`` in the value of ``top`` is the outer most container node, and ``vlan`` -is the inner-most container node. +``configuration`` in the value of ``top`` is the outermost container node, and ``vlan`` +is the innermost container node. ``items`` is a dictionary of key-value pairs that map user-defined names to XPath expressions that select elements. The Xpath expression is relative to the value of the XPath value contained in ``top``. -For example, the ``vlan_id`` in the spec file is a user defined name and its value ``vlan-id`` is the +For example, the ``vlan_id`` in the spec file is a user-defined name and its value ``vlan-id`` is the relative to the value of XPath in ``top`` Attributes of XML tags can be extracted using XPath expressions. The value of ``state`` in the spec @@ -1516,7 +1516,7 @@ Another example Jinja template: switchport trunk allowed vlan add {{ parsed_vlans[i] }} {% endfor %} -This allows for dynamic generation of VLAN lists on a Cisco IOS tagged interface. You can store an exhaustive raw list of the exact VLANs required for an interface and then compare that to the parsed IOS output that would actually be generated for the configuration. +This allows for the dynamic generation of VLAN lists on a Cisco IOS tagged interface. You can store an exhaustive raw list of the exact VLANs required for an interface and then compare that to the parsed IOS output that would actually be generated for the configuration. .. _hash_filters: @@ -1649,7 +1649,7 @@ Several filters work with text, including URLs, file names, and path names. Adding comments to files ------------------------ -The :ansplugin:`ansible.builtin.comment#filter` filter lets you create comments in a file from text in a template, with a variety of comment styles. By default Ansible uses ``#`` to start a comment line and adds a blank comment line above and below your comment text. For example the following: +The :ansplugin:`ansible.builtin.comment#filter` filter lets you create comments in a file from text in a template, with a variety of comment styles. By default, Ansible uses ``#`` to start a comment line and adds a blank comment line above and below your comment text. For example the following: .. code-block:: yaml+jinja @@ -1705,7 +1705,7 @@ That creates the following output: ### # -The filter can also be applied to any Ansible variable. For example to +The filter can also be applied to any Ansible variable. For example, to make the output of the ``ansible_managed`` variable more readable, we can change the definition in the ``ansible.cfg`` file to this: @@ -1945,19 +1945,19 @@ To get the last name of a file path, like 'foo.txt' out of '/etc/asdf/foo.txt': {{ path | basename }} -To get the last name of a windows style file path (new in version 2.0): +To get the last name of a Windows style file path (new in version 2.0): .. code-block:: yaml+jinja {{ path | win_basename }} -To separate the windows drive letter from the rest of a file path (new in version 2.0): +To separate the Windows drive letter from the rest of a file path (new in version 2.0): .. code-block:: yaml+jinja {{ path | win_splitdrive }} -To get only the windows drive letter: +To get only the Windows drive letter: .. code-block:: yaml+jinja @@ -1975,7 +1975,7 @@ To get the directory from a path: {{ path | dirname }} -To get the directory from a windows path (new version 2.0): +To get the directory from a Windows path (new version 2.0): .. code-block:: yaml+jinja @@ -2078,9 +2078,9 @@ As of version 2.6, you can define the type of encoding to use, the default is `` (Documentation: :ansplugin:`ansible.builtin.b64decode#filter`) -.. note:: The ``string`` filter is only required for Python 2 and ensures that text to encode is a unicode string. Without that filter before b64encode the wrong value will be encoded. +.. note:: The ``string`` filter is only required for Python 2 and ensures that the text to encode is a unicode string. Without that filter before b64encode the wrong value will be encoded. -.. note:: The return value of b64decode is a string. If you decrypt a binary blob using b64decode and then try to use it (for example by using :ref:`copy ` to write it to a file) you will mostly likely find that your binary has been corrupted. If you need to take a base64 encoded binary and write it to disk, it is best to use the system ``base64`` command with the :ref:`shell module `, piping in the encoded data using the ``stdin`` parameter. For example: ``shell: cmd="base64 --decode > myfile.bin" stdin="{{ encoded }}"`` +.. note:: The return value of b64decode is a string. If you decrypt a binary blob using b64decode and then try to use it (for example by using :ref:`copy ` to write it to a file) you will most likely find that your binary has been corrupted. If you need to take a base64 encoded binary and write it to disk, it is best to use the system ``base64`` command with the :ref:`shell module `, piping in the encoded data using the ``stdin`` parameter. For example: ``shell: cmd="base64 --decode > myfile.bin" stdin="{{ encoded }}"`` .. versionadded:: 2.6 @@ -2117,17 +2117,17 @@ To get a date object from a string use the `to_datetime` filter: .. code-block:: yaml+jinja - # Get total amount of seconds between two dates. Default date format is %Y-%m-%d %H:%M:%S but you can pass your own format + # Get the total amount of seconds between two dates. Default date format is %Y-%m-%d %H:%M:%S but you can pass your own format {{ (("2016-08-14 20:00:12" | to_datetime) - ("2015-12-25" | to_datetime('%Y-%m-%d'))).total_seconds() }} # Get remaining seconds after delta has been calculated. NOTE: This does NOT convert years, days, hours, and so on to seconds. For that, use total_seconds() {{ (("2016-08-14 20:00:12" | to_datetime) - ("2016-08-14 18:00:00" | to_datetime)).seconds }} # This expression evaluates to "12" and not "132". Delta is 2 hours, 12 seconds - # get amount of days between two dates. This returns only number of days and discards remaining hours, minutes, and seconds + # get amount of days between two dates. This returns only the number of days and discards remaining hours, minutes, and seconds {{ (("2016-08-14 20:00:12" | to_datetime) - ("2015-12-25" | to_datetime('%Y-%m-%d'))).days }} -.. note:: For a full list of format codes for working with python date format strings, see the `python datetime documentation `_. +.. note:: For a full list of format codes for working with Python date format strings, see the `python datetime documentation `_. .. versionadded:: 2.4 @@ -2217,7 +2217,7 @@ This can then be used to reference hashes in Pod specifications: :ref:`tips_and_tricks` Tips and tricks for playbooks `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels `Python 3 Regular expression operations `_ diff --git a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst index 1f54ce2968f..44a78a36f10 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst @@ -46,7 +46,7 @@ This playbook, ``verify-apache.yml``, contains a single play with a handler. name: httpd state: restarted -In this example playbook, the Apache server is restarted by the handler after all tasks complete in the play. +In this example playbook, the Apache server is restarted by the handler after all tasks are completed in the play. Notifying handlers @@ -76,7 +76,7 @@ Tasks can instruct one or more handlers to execute using the ``notify`` keyword. name: apache state: restarted -In the above example the handlers are executed on task change in the following order: ``Restart memcached``, ``Restart apache``. Handlers are executed in the order they are defined in the ``handlers`` section, not in the order listed in the ``notify`` statement. Notifying the same handler multiple times will result in executing the handler only once regardless of how many tasks notify it. For example, if multiple tasks update a configuration file and notify a handler to restart Apache, Ansible only bounces Apache once to avoid unnecessary restarts. +In the above example, the handlers are executed on task change in the following order: ``Restart memcached``, ``Restart apache``. Handlers are executed in the order they are defined in the ``handlers`` section, not in the order listed in the ``notify`` statement. Notifying the same handler multiple times will result in executing the handler only once regardless of how many tasks notify it. For example, if multiple tasks update a configuration file and notify a handler to restart Apache, Ansible only bounces Apache once to avoid unnecessary restarts. Naming handlers @@ -84,7 +84,7 @@ Naming handlers Handlers must be named in order for tasks to be able to notify them using the ``notify`` keyword. -Alternately, handlers can utilize the ``listen`` keyword. Using this handler keyword, handlers can listen on topics that can group multiple handlers as follows: +Alternatively, handlers can utilize the ``listen`` keyword. Using this handler keyword, handlers can listen on topics that can group multiple handlers as follows: .. code-block:: yaml @@ -172,9 +172,9 @@ While handler names can contain a template, ``listen`` topics cannot. Handlers in roles ----------------- -Handlers from roles are not just contained in their roles but rather inserted into global scope with all other handlers from a play. As such they can be used outside of the role they are defined in. It also means that their name can conflict with handlers from outside the role. To ensure that a handler from a role is notified as opposed to one from outside the role with the same name, notify the handler by using its name in the following form: ``role_name : handler_name``. +Handlers from roles are not just contained in their roles but rather inserted into the global scope with all other handlers from a play. As such they can be used outside of the role they are defined in. It also means that their name can conflict with handlers from outside the role. To ensure that a handler from a role is notified as opposed to one from outside the role with the same name, notify the handler by using its name in the following form: ``role_name : handler_name``. -Handlers notified within the ``roles`` section are automatically flushed at the end of the ``tasks`` section, but before any ``tasks`` handlers. +Handlers notified within the ``roles`` section are automatically flushed at the end of the ``tasks`` section but before any ``tasks`` handlers. Includes and imports in handlers diff --git a/docs/docsite/rst/playbook_guide/playbooks_lookups.rst b/docs/docsite/rst/playbook_guide/playbooks_lookups.rst index 785f150be69..ee49513ac7f 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_lookups.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_lookups.rst @@ -34,6 +34,6 @@ For more details and a list of lookup plugins in ansible-core, see :ref:`plugins :ref:`playbooks_loops` Looping in playbooks `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index e22c1ccdbfd..97d44d0f805 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -266,7 +266,7 @@ This task runs up to 5 times with a delay of 10 seconds between each attempt. If To see the results of individual retries, run the play with ``-vv``. -When you run a task with ``until`` and register the result as a variable, the registered variable will include a key called "attempts", which records the number of the retries for the task. +When you run a task with ``until`` and register the result as a variable, the registered variable will include a key called "attempts", which records the number of retries for the task. If ``until`` is not specified, the task will retry until the task succeeds but at most ``retries`` times. @@ -399,7 +399,7 @@ Defining inner and outer variable names with ``loop_var`` --------------------------------------------------------- .. versionadded:: 2.1 -You can nest two looping tasks using ``include_tasks``. However, by default Ansible sets the loop variable ``item`` for each loop. This means the inner, nested loop will overwrite the value of ``item`` from the outer loop. +You can nest two looping tasks using ``include_tasks``. However, by default, Ansible sets the loop variable ``item`` for each loop. This means the inner, nested loop will overwrite the value of ``item`` from the outer loop. You can specify the name of the variable for each loop using ``loop_var`` with ``loop_control``. .. code-block:: yaml+jinja @@ -422,13 +422,13 @@ You can specify the name of the variable for each loop using ``loop_var`` with ` - b - c -.. note:: If Ansible detects that the current loop is using a variable which has already been defined, it will raise an error to fail the task. +.. note:: If Ansible detects that the current loop is using a variable that has already been defined, it will raise an error to fail the task. Extended loop variables ----------------------- .. versionadded:: 2.8 -As of Ansible 2.8 you can get extended loop information using the ``extended`` option to loop control. This option will expose the following information. +As of Ansible 2.8, you can get extended loop information using the ``extended`` option to loop control. This option will expose the following information. ========================== =========== Variable Description @@ -466,7 +466,7 @@ Accessing the name of your loop_var ----------------------------------- .. versionadded:: 2.8 -As of Ansible 2.8 you can get the name of the value provided to ``loop_control.loop_var`` using the ``ansible_loop_var`` variable +As of Ansible 2.8, you can get the name of the value provided to ``loop_control.loop_var`` using the ``ansible_loop_var`` variable For role authors, writing roles that allow loops, instead of dictating the required ``loop_var`` value, you can gather the value through the following @@ -494,6 +494,6 @@ Migrating from with_X to loop :ref:`playbooks_variables` All about variables `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst b/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst index 743b7eb7f45..cb1e8afac99 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst @@ -26,7 +26,7 @@ become set to ``true`` to activate privilege escalation. become_user - set to user with desired privileges — the user you `become`, NOT the user you login as. Does NOT imply ``become: true``, to allow it to be set at host level. Default value is ``root``. + set to user with desired privileges — the user you `become`, NOT the user you login as. Does NOT imply ``become: true``, to allow it to be set at host level. The default value is ``root``. become_method (at play or task level) overrides the default method set in ansible.cfg, set to use any of the :ref:`become_plugins`. @@ -112,7 +112,7 @@ Become command-line options valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu | runas | machinectl ] --become-user=BECOME_USER - run operations as this user (default=root), does not imply --become/-b + run operations as this user (default=root), does not imply ``--become``/``-b`` Risks and limitations of become =============================== @@ -129,14 +129,14 @@ and finally executing it there. Everything is fine if the module file is executed without using ``become``, when the ``become_user`` is root, or when the connection to the remote machine -is made as root. In these cases Ansible creates the module file with +is made as root. In these cases, Ansible creates the module file with permissions that only allow reading by the user and root, or only allow reading by the unprivileged user being switched to. However, when both the connection user and the ``become_user`` are unprivileged, the module file is written as the user that Ansible connects as (the ``remote_user``), but the file needs to be readable by the user Ansible is set -to ``become``. The details of how Ansible solves this can vary based on platform. +to ``become``. The details of how Ansible solves this can vary based on the platform. However, on POSIX systems, Ansible solves this problem in the following way: First, if :command:`setfacl` is installed and available in the remote ``PATH``, @@ -146,7 +146,7 @@ with the second unprivileged user. Next, if POSIX ACLs are **not** available or :command:`setfacl` could not be run, Ansible will attempt to change ownership of the module file using -:command:`chown` for systems which support doing so as an unprivileged user. +:command:`chown` for systems that support doing so as an unprivileged user. New in Ansible 2.11, at this point, Ansible will try :command:`chmod +a` which is a macOS-specific way of setting ACLs on files. @@ -184,10 +184,10 @@ Once the module is done executing, Ansible deletes the temporary file. Several ways exist to avoid the above logic flow entirely: * Use `pipelining`. When pipelining is enabled, Ansible does not save the - module to a temporary file on the client. Instead it pipes the module to - the remote python interpreter's stdin. Pipelining does not work for - python modules involving file transfer (for example: :ref:`copy `, - :ref:`fetch `, :ref:`template `), or for non-python modules. + module to a temporary file on the client. Instead, it pipes the module to + the remote Python interpreter's stdin. Pipelining does not work for + Python modules involving file transfer (for example: :ref:`copy `, + :ref:`fetch `, :ref:`template `), or for non-Python modules. * Avoid becoming an unprivileged user. Temporary files are protected by UNIX file permissions when you @@ -226,7 +226,7 @@ on when this fallback happens. world-readable fallback will ever trigger, and yet Ansible might still be unable to access the module file. This is because after the group ownership change is successful, Ansible does not fall back any further, and also does - not do any check to ensure that the ``become_user`` is actually a member of + not do any checks to ensure that the ``become_user`` is actually a member of the "common group". This is a design decision made by the fact that doing such a check would require another round-trip connection to the remote machine, which is a time-expensive operation. Ansible does, however, emit a @@ -244,7 +244,7 @@ Only one method may be enabled per host Methods cannot be chained. You cannot use ``sudo /bin/su -`` to become a user, you need to have privileges to run the command as that user in sudo or be able -to su directly to it (the same for pbrun, pfexec or other supported methods). +to `su` directly to it (the same for `pbrun`, `pfexec` or other supported methods). Privilege escalation must be general ------------------------------------ @@ -253,10 +253,10 @@ You cannot limit privilege escalation permissions to certain commands. Ansible does not always use a specific command to do something but runs modules (code) from a temporary file name which changes every time. If you have '/sbin/service' -or '/bin/chmod' as the allowed commands this will fail with ansible as those +or '/bin/chmod' as the allowed commands this will fail with Ansible as those paths won't match with the temporary file that Ansible creates to run the -module. If you have security rules that constrain your sudo/pbrun/doas environment -to running specific command paths only, use Ansible from a special account that +module. If you have security rules that constrain your `sudo`/`pbrun`/`doas` environment +to run specific command paths only, use Ansible from a special account that does not have this constraint, or use AWX or the :ref:`ansible_platform` to manage indirect access to SSH credentials. May not access environment variables populated by pamd_systemd @@ -264,13 +264,13 @@ May not access environment variables populated by pamd_systemd For most Linux distributions using ``systemd`` as their init, the default methods used by ``become`` do not open a new "session", in the sense of -systemd. Because the ``pam_systemd`` module will not fully initialize a new +``systemd``. Because the ``pam_systemd`` module will not fully initialize a new session, you might have surprises compared to a normal session opened through ssh: some environment variables set by ``pam_systemd``, most notably ``XDG_RUNTIME_DIR``, are not populated for the new user and instead inherited or just emptied. -This might cause trouble when trying to invoke systemd commands that depend on +This might cause trouble when trying to invoke ``systemd`` commands that depend on ``XDG_RUNTIME_DIR`` to access the bus: .. code-block:: console @@ -280,7 +280,7 @@ This might cause trouble when trying to invoke systemd commands that depend on $ systemctl --user status Failed to connect to bus: Permission denied -To force ``become`` to open a new systemd session that goes through +To force ``become`` to open a new ``systemd`` session that goes through ``pam_systemd``, you can use ``become_method: machinectl``. For more information, see `this systemd issue @@ -336,7 +336,7 @@ To set enable mode for all tasks in a single play, add ``become`` at the play le Setting enable mode for all tasks --------------------------------- -Often you wish for all tasks in all plays to run using privilege mode, that is best achieved by using ``group_vars``: +Often you wish for all tasks in all plays to run using privilege mode, which is best achieved by using ``group_vars``: **group_vars/eos.yml** @@ -378,7 +378,7 @@ Ansible still supports ``enable`` mode with ``connection: local`` for legacy net authorize: true auth_pass: " {{ secret_auth_pass }}" -We recommend updating your playbooks to use ``become`` for network-device ``enable`` mode consistently. The use of ``authorize`` and of ``provider`` dictionaries will be deprecated in future. Check the :ref:`platform_options` documentation for details. +We recommend updating your playbooks to use ``become`` for network-device ``enable`` mode consistently. The use of ``authorize`` and ``provider`` dictionaries will be deprecated in the future. Check the :ref:`platform_options` documentation for details. .. _become_windows: @@ -388,8 +388,7 @@ Become and Windows Since Ansible 2.3, ``become`` can be used on Windows hosts through the ``runas`` method. Become on Windows uses the same inventory setup and invocation arguments as ``become`` on a non-Windows host, so the setup and -variable names are the same as what is defined in this document with the exception -of ``become_user``. As there is no sensible default for ``become_user`` on Windows +variable names are the same as what is defined in this document except ``become_user``. As there is no sensible default for ``become_user`` on Windows it is required when using ``become``. See :ansplugin:`ansible.builtin.runas become plugin ` for details. While ``become`` can be used to assume the identity of another user, there are other uses for @@ -400,7 +399,7 @@ delegation or accessing forbidden system calls like the WUA API. You can use and run commands that are not normally accessible in a WinRM session. .. Note:: - On Windows you cannot connect with an underprivileged account and use become + On Windows, you cannot connect with an underprivileged account and use become to elevate your rights. Become can only be used if your connection account is already an Administrator of the target host. @@ -627,7 +626,7 @@ account that has no password make sure to keep ``ansible_become_password`` as undefined or set ``ansible_become_password:``. .. Note:: Because there are no guarantees an existing token will exist for a - user when Ansible runs, there's a high change the become process will only + user when Ansible runs, there's a high chance the become process will only have access to local resources. Use become with a password if the task needs to access network resources @@ -691,7 +690,7 @@ can be set to one of the following: * ``network``: Runs the process under a network context without any cached credentials. This results in the same type of logon session as running a - normal WinRM process without credential delegation, and operates under the same + normal WinRM process without credential delegation and operates under the same restrictions. * ``network_cleartext``: Like the ``network`` logon type, but instead caches diff --git a/docs/docsite/rst/playbook_guide/playbooks_prompts.rst b/docs/docsite/rst/playbook_guide/playbooks_prompts.rst index c80dfa9c92d..d962352cb2c 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_prompts.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_prompts.rst @@ -82,7 +82,7 @@ If you have `Passlib `_ installed, yo - *bsd_nthash* - FreeBSD's MCF-compatible nthash encoding The only parameters accepted are 'salt' or 'salt_size'. You can use your own salt by defining -'salt', or have one generated automatically using 'salt_size'. By default Ansible generates a salt +'salt', or have one generated automatically using 'salt_size'. By default, Ansible generates a salt of size 8. .. versionadded:: 2.7 @@ -119,6 +119,6 @@ Some special characters, such as ``{`` and ``%`` can create templating errors. I :ref:`playbooks_variables` All about variables `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_python_version.rst b/docs/docsite/rst/playbook_guide/playbooks_python_version.rst index ee18b60713e..38e9e67a883 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_python_version.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_python_version.rst @@ -6,7 +6,7 @@ Python3 in templates Ansible uses Jinja2 to take advantage of Python data types and standard functions in templates and variables. You can use these data types and standard functions to perform a rich set of operations on your data. However, -if you use templates, you must be aware of differences between Python versions. +if you use templates, you must be aware of the differences between Python versions. These topics help you design templates that work on both Python2 and Python3. They might also help if you are upgrading from Python2 to Python3. Upgrading within Python2 or Python3 does not usually introduce changes that affect Jinja2 templates. diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse.rst index 70a3b57f2be..4e42fc8d28a 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse.rst @@ -74,7 +74,7 @@ Includes: dynamic reuse Including roles, tasks, or variables adds them to a playbook dynamically. Ansible processes included files and roles as they come up in a playbook, so included tasks can be affected by the results of earlier tasks within the top-level playbook. Included roles and tasks are similar to handlers - they may or may not run, depending on the results of other tasks in the top-level playbook. -The primary advantage of using ``include_*`` statements is looping. When a loop is used with an include, the included tasks or role will be executed once for each item in the loop. +The primary advantage of using ``include_*`` statements is looping. When a loop is used with an include, the included tasks or roles will be executed once for each item in the loop. The file names for included roles, tasks, and vars are templated before inclusion. diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index d5fe4944fdd..950db9d570b 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -4,7 +4,7 @@ Roles ***** -Roles let you automatically load related vars, files, tasks, handlers, and other Ansible artifacts based on a known file structure. After you group your content in roles, you can easily reuse them and share them with other users. +Roles let you automatically load related vars, files, tasks, handlers, and other Ansible artifacts based on a known file structure. After you group your content into roles, you can easily reuse them and share them with other users. .. contents:: :local: @@ -23,12 +23,12 @@ An Ansible role has a defined directory structure with eight main standard direc .. include:: shared_snippets/role_directory.txt -By default Ansible will look in each directory within a role for a ``main.yml`` file for relevant content (also ``main.yaml`` and ``main``): +By default, Ansible will look in each directory within a role for a ``main.yml`` file for relevant content (also ``main.yaml`` and ``main``): - ``tasks/main.yml`` - the main list of tasks that the role executes. - ``handlers/main.yml`` - handlers, which may be used within or outside this role. - ``library/my_module.py`` - modules, which may be used within this role (see :ref:`embedding_modules_and_plugins_in_roles` for more information). -- ``defaults/main.yml`` - default variables for the role (see :ref:`playbooks_variables` for more information). These variables have the lowest priority of any variables available, and can be easily overridden by any other variable, including inventory variables. +- ``defaults/main.yml`` - default variables for the role (see :ref:`playbooks_variables` for more information). These variables have the lowest priority of any variables available and can be easily overridden by any other variable, including inventory variables. - ``vars/main.yml`` - other variables for the role (see :ref:`playbooks_variables` for more information). - ``files/main.yml`` - files that the role deploys. - ``templates/main.yml`` - templates that the role deploys. @@ -73,7 +73,7 @@ By default, Ansible looks for roles in the following locations: - in the configured :ref:`roles_path `. The default search path is ``~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles``. - in the directory where the playbook file is located -If you store your roles in a different location, set the :ref:`roles_path ` configuration option so Ansible can find your roles. Checking shared roles into a single location makes them easier to use in multiple playbooks. See :ref:`intro_configuration` for details about managing settings in ansible.cfg. +If you store your roles in a different location, set the :ref:`roles_path ` configuration option so Ansible can find your roles. Checking shared roles into a single location makes them easier to use in multiple playbooks. See :ref:`intro_configuration` for details about managing settings in ``ansible.cfg``. Alternatively, you can call a role with a fully qualified path: @@ -229,7 +229,7 @@ You can reuse roles statically anywhere in the ``tasks`` section of a play using ansible.builtin.debug: msg: "after we ran our role" -You can pass other keywords, including variables and tags, when importing roles: +You can pass other keywords, including variables and tags when importing roles: .. code-block:: yaml @@ -475,7 +475,7 @@ Sample specification Running a role multiple times in one play ========================================= -Ansible only executes each role once in a play, even if you define it multiple times, unless the parameters defined on the role are different for each definition. For example, Ansible only runs the role ``foo`` once in a play like this: +Ansible only executes each role once in a play, even if you define it multiple times unless the parameters defined on the role are different for each definition. For example, Ansible only runs the role ``foo`` once in a play like this: .. code-block:: yaml @@ -573,7 +573,7 @@ Ansible treats duplicate role dependencies like duplicate roles listed under ``r .. note:: - Role deduplication does not consult the invocation signature of parent roles. Additionally, when using ``vars:`` instead of role params, there is a side effect of changing variable scoping. Using ``vars:`` results in those variables being scoped at the play level. In the below example, using ``vars:`` would cause ``n`` to be defined as ``4`` through the entire play, including roles called before it. + Role deduplication does not consult the invocation signature of parent roles. Additionally, when using ``vars:`` instead of role params, there is a side effect of changing variable scoping. Using ``vars:`` results in those variables being scoped at the play level. In the below example, using ``vars:`` would cause ``n`` to be defined as ``4`` throughout the entire play, including roles called before it. In addition to the above, users should be aware that role de-duplication occurs before variable evaluation. This means that :term:`Lazy Evaluation` may make seemingly different role invocations equivalently the same, preventing the role from running more than once. @@ -626,7 +626,7 @@ To use ``allow_duplicates: true`` with role dependencies, you must specify it fo .. note:: See :ref:`playbooks_variables` for details on how Ansible chooses among variable values defined in different places (variable inheritance and scope). - Also deduplication happens ONLY at the play level, so multiple plays in the same playbook may rerun the roles. + Also, deduplication happens ONLY at the play level, so multiple plays in the same playbook may rerun the roles. .. _embedding_modules_and_plugins_in_roles: @@ -636,7 +636,7 @@ Embedding modules and plugins in roles .. note:: This applies only to standalone roles. Roles in collections do not support plugin embedding; they must use the collection's ``plugins`` structure to distribute plugins. -If you write a custom module (see :ref:`developing_modules`) or a plugin (see :ref:`developing_plugins`), you might wish to distribute it as part of a role. For example, if you write a module that helps configure your company's internal software, and you want other people in your organization to use this module, but you do not want to tell everyone how to configure their Ansible library path, you can include the module in your internal_config role. +If you write a custom module (see :ref:`developing_modules`) or a plugin (see :ref:`developing_plugins`), you might wish to distribute it as part of a role. For example, if you write a module that helps configure your company's internal software, and you want other people in your organization to use this module, but do not want to tell everyone how to configure their Ansible library path, you can include the module in your internal_config role. To add a module or a plugin to a role: Alongside the 'tasks' and 'handlers' structure of a role, add a directory named 'library' and then include the module directly inside the 'library' directory. diff --git a/docs/docsite/rst/playbook_guide/playbooks_strategies.rst b/docs/docsite/rst/playbook_guide/playbooks_strategies.rst index 43d1605c332..4bcb6db58e8 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_strategies.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_strategies.rst @@ -249,6 +249,6 @@ As always with :ref:`delegation `, the action will be exec :ref:`playbooks_reuse_roles` Playbook organization by roles `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst index 7d29a7d79eb..e839b2173ea 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst @@ -433,6 +433,6 @@ If you run or skip certain tags by default, you can use the :ref:`TAGS_RUN` and :ref:`playbooks_reuse_roles` Playbook organization by roles `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_templating.rst b/docs/docsite/rst/playbook_guide/playbooks_templating.rst index b42fc0bbbde..9cc971ea28c 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_templating.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_templating.rst @@ -62,6 +62,6 @@ Our test.j2: `Jinja2 Docs `_ Jinja2 documentation, includes the syntax and semantics of the templates `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_tests.rst b/docs/docsite/rst/playbook_guide/playbooks_tests.rst index 95bfc76b305..4a298ef8099 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tests.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tests.rst @@ -172,7 +172,7 @@ As of Ansible 2.11 the ``version`` test accepts a ``version_type`` parameter whi loose, strict, semver, semantic, pep440 ``loose`` - This type corresponds to the Python ``distutils.version.LooseVersion`` class. All version formats are valid for this type. The rules for comparison are simple and predictable, but may not always give expected results. + This type corresponds to the Python ``distutils.version.LooseVersion`` class. All version formats are valid for this type. The rules for comparison are simple and predictable, but may not always give the expected results. ``strict`` This type corresponds to the Python ``distutils.version.StrictVersion`` class. A version number consists of two or three dot-separated numeric components, with an optional "pre-release" tag on the end. The pre-release tag consists of a single letter 'a' or 'b' followed by a number. If the numeric components of two version numbers are equal, then one with a pre-release tag will always be deemed earlier (lesser) than one without. @@ -356,7 +356,7 @@ you provide Byte format to computers and human-readable format to people. Human readable -------------- -Asserts whether the given string is human readable or not. +Asserts whether the given string is human-readable or not. For example @@ -516,8 +516,8 @@ When looking to determine types, it may be tempting to use the ``type_debug`` fi - FALSE assert: that: - # Note that while other values may be cast to boolean values, these are the only ones which are natively considered boolean - # Note also that `yes` is the only case sensitive variant of these values. + # Note that while other values may be cast to boolean values, these are the only ones that are natively considered boolean + # Note also that `yes` is the only case-sensitive variant of these values. - item is boolean .. _builtin tests: https://jinja.palletsprojects.com/en/latest/templates/#builtin-tests @@ -537,6 +537,6 @@ When looking to determine types, it may be tempting to use the ``type_debug`` fi :ref:`tips_and_tricks` Tips and tricks for playbooks `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_variables.rst b/docs/docsite/rst/playbook_guide/playbooks_variables.rst index 52674d77642..3a4e5fcace5 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_variables.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_variables.rst @@ -6,7 +6,7 @@ Using Variables Ansible uses variables to manage differences between systems. With Ansible, you can execute tasks and playbooks on multiple different systems with a single command. To represent the variations among those different systems, you can create variables with standard YAML syntax, including lists and dictionaries. You can define these variables in your playbooks, in your :ref:`inventory `, in reusable :ref:`files ` or :ref:`roles `, or at the command line. You can also create variables during a playbook run by registering the return value or values of a task as a new variable. -After you create variables, either by defining them in a file, passing them at the command line, or registering the return value or values of a task as a new variable, you can use those variables in module arguments, in :ref:`conditional "when" statements `, in :ref:`templates `, and in :ref:`loops `. The `ansible-examples github repository `_ contains many examples of using variables in Ansible. +After you create variables, either by defining them in a file, passing them at the command line, or registering the return value or values of a task as a new variable, you can use those variables in module arguments, in :ref:`conditional "when" statements `, in :ref:`templates `, and in :ref:`loops `. The `ansible-examples GitHub repository `_ contains many examples of using variables in Ansible. Once you understand the concepts and examples on this page, read about :ref:`Ansible facts `, which are variables you retrieve from remote systems. @@ -244,7 +244,7 @@ You can define variables in a variety of places, such as in inventory, in playbo Defining variables in inventory ------------------------------- -You can define different variables for each individual host, or set shared variables for a group of hosts in your inventory. For example, if all machines in the ``[Boston]`` group use 'boston.ntp.example.com' as an NTP server, you can set a group variable. The :ref:`intro_inventory` page has details on setting :ref:`host variables ` and :ref:`group variables ` in inventory. +You can define different variables for each host individually, or set shared variables for a group of hosts in your inventory. For example, if all machines in the ``[Boston]`` group use 'boston.ntp.example.com' as an NTP server, you can set a group variable. The :ref:`intro_inventory` page has details on setting :ref:`host variables ` and :ref:`group variables ` in inventory. .. _playbook_variables: @@ -323,7 +323,7 @@ JSON string format ansible-playbook release.yml --extra-vars '{"version":"1.23.45","other_variable":"foo"}' ansible-playbook arcade.yml --extra-vars '{"pacman":"mrs","ghosts":["inky","pinky","clyde","sue"]}' -When passing variables with ``--extra-vars``, you must escape quotes and other special characters appropriately for both your markup (for example, JSON), and for your shell: +When passing variables with ``--extra-vars``, you must escape quotes and other special characters appropriately for both your markup (for example, JSON) and for your shell: .. code-block:: shell @@ -348,7 +348,7 @@ If you have a lot of special characters, use a JSON or YAML file containing the Variable precedence: Where should I put a variable? =================================================== -You can set multiple variables with the same name in many different places. When you do this, Ansible loads every possible variable it finds, then chooses the variable to apply based on variable precedence. In other words, the different variables will override each other in a certain order. +You can set multiple variables with the same name in many different places. When you do this, Ansible loads every possible variable it finds, and then chooses the variable to apply based on variable precedence. In other words, the different variables will override each other in a certain order. Teams and projects that agree on guidelines for defining variables (where to define certain types of variables) usually avoid variable precedence concerns. We suggest that you define each variable in one place: figure out where to define a variable, and keep it simple. For examples, see :ref:`variable_examples`. @@ -529,6 +529,6 @@ For information about advanced YAML syntax used to declare variables and have mo :ref:`special_variables` List of special variables `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst b/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst index fb83e52e2a1..f27870a715a 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst @@ -4,7 +4,7 @@ Discovering variables: facts and magic variables ************************************************ -With Ansible you can retrieve or discover certain variables containing information about your remote systems or about Ansible itself. Variables related to remote systems are called facts. With facts, you can use the behavior or state of one system as configuration on other systems. For example, you can use the IP address of one system as a configuration value on another system. Variables related to Ansible are called magic variables. +With Ansible you can retrieve or discover certain variables containing information about your remote systems or about Ansible itself. Variables related to remote systems are called facts. With facts, you can use the behavior or state of one system as a configuration on other systems. For example, you can use the IP address of one system as a configuration value on another system. Variables related to Ansible are called magic variables. .. contents:: :local: @@ -525,7 +525,7 @@ Like registered variables, facts are stored in memory by default. However, unlik Caching is controlled by the cache plugins. By default, Ansible uses the memory cache plugin, which stores facts in memory for the duration of the current playbook run. To retain Ansible facts for repeated use, select a different cache plugin. See :ref:`cache_plugins` for details. -Fact caching can improve performance. If you manage thousands of hosts, you can configure fact caching to run nightly, then manage configuration on a smaller set of servers periodically throughout the day. With cached facts, you have access to variables and information about all hosts even when you are only managing a small number of servers. +Fact caching can improve performance. If you manage thousands of hosts, you can configure fact caching to run nightly, and then manage configuration on a smaller set of servers periodically throughout the day. With cached facts, you have access to variables and information about all hosts even when you are only managing a small number of servers. .. _disabling_facts: @@ -592,7 +592,7 @@ The ansible_local namespace separates custom facts created by facts.d from syste {{ ansible_local['preferences']['general']['asdf'] }} -.. note:: The key part in the key=value pairs will be converted into lowercase inside the ansible_local variable. Using the example above, if the ini file contained ``XYZ=3`` in the ``[general]`` section, then you should expect to access it as: ``{{ ansible_local['preferences']['general']['xyz'] }}`` and not ``{{ ansible_local['preferences']['general']['XYZ'] }}``. This is because Ansible uses Python's `ConfigParser`_ which passes all option names through the `optionxform`_ method and this method's default implementation converts option names to lower case. +.. note:: The key part in the key=value pairs will be converted into lowercase inside the ansible_local variable. Using the example above, if the ini file contained ``XYZ=3`` in the ``[general]`` section, then you should expect to access it as: ``{{ ansible_local['preferences']['general']['xyz'] }}`` and not ``{{ ansible_local['preferences']['general']['XYZ'] }}``. This is because Ansible uses Python's `ConfigParser`_ which passes all option names through the `optionxform`_ method and this method's default implementation converts option names to lowercase. .. _ConfigParser: https://docs.python.org/3/library/configparser.html .. _optionxform: https://docs.python.org/3/library/configparser.html#ConfigParser.RawConfigParser.optionxform @@ -634,7 +634,7 @@ If you use this pattern frequently, a custom facts module would be more efficien Information about Ansible: magic variables ========================================== -You can access information about Ansible operations, including the python version being used, the hosts and groups in inventory, and the directories for playbooks and roles, using "magic" variables. Like connection variables, magic variables are :ref:`special_variables`. Magic variable names are reserved - do not set variables with these names. The variable ``environment`` is also reserved. +You can access information about Ansible operations, including the Python version being used, the hosts and groups in inventory, and the directories for playbooks and roles, using "magic" variables. Like connection variables, magic variables are :ref:`special_variables`. Magic variable names are reserved - do not set variables with these names. The variable ``environment`` is also reserved. The most commonly used magic variables are ``hostvars``, ``groups``, ``group_names``, and ``inventory_hostname``. With ``hostvars``, you can access variables defined for any host in the play, at any point in a playbook. You can access Ansible facts using the ``hostvars`` variable too, but only after you have gathered (or cached) facts. Note that variables defined at play objects are not defined for specific hosts and therefore are not mapped to hostvars. @@ -680,7 +680,7 @@ Other useful magic variables refer to the current play or playbook. These vars m The batch size is defined by ``serial``, when not set it is equivalent to the whole play (making it the same as ``ansible_play_hosts``). -``ansible_playbook_python`` is the path to the python executable used to invoke the Ansible command line tool. +``ansible_playbook_python`` is the path to the Python executable used to invoke the Ansible command line tool. ``inventory_dir`` is the pathname of the directory holding Ansible's inventory host file. diff --git a/docs/docsite/rst/plugins/action.rst b/docs/docsite/rst/plugins/action.rst index fe7c547f4bc..1ead01562f0 100644 --- a/docs/docsite/rst/plugins/action.rst +++ b/docs/docsite/rst/plugins/action.rst @@ -50,6 +50,6 @@ Use ``ansible-doc `` to see specific documentation and examples, this shou :ref:`vars_plugins` Vars plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/become.rst b/docs/docsite/rst/plugins/become.rst index e740c144dd7..c76308373b3 100644 --- a/docs/docsite/rst/plugins/become.rst +++ b/docs/docsite/rst/plugins/become.rst @@ -62,6 +62,6 @@ Use ``ansible-doc -t become `` to see specific documentation and ex :ref:`lookup_plugins` Lookup plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst index 4aa88f9246b..5860df43d87 100644 --- a/docs/docsite/rst/plugins/cache.rst +++ b/docs/docsite/rst/plugins/cache.rst @@ -134,6 +134,6 @@ Use ``ansible-doc -t cache `` to see specific documentation and exa :ref:`vars_plugins` Vars plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst index 98e4beb754c..3134fb0fde7 100644 --- a/docs/docsite/rst/plugins/callback.rst +++ b/docs/docsite/rst/plugins/callback.rst @@ -111,6 +111,6 @@ Use ``ansible-doc -t callback `` to see specific documents and exam :ref:`vars_plugins` Vars plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/cliconf.rst b/docs/docsite/rst/plugins/cliconf.rst index f5af78c2124..8f47bdc1fc2 100644 --- a/docs/docsite/rst/plugins/cliconf.rst +++ b/docs/docsite/rst/plugins/cliconf.rst @@ -42,6 +42,6 @@ These plugins have migrated to collections on `Ansible Galaxy ` An overview of using Ansible to automate networking devices. `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! `irc.libera.chat `_ #ansible-network IRC chat channel diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index 59d3984c063..6681c106e38 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -73,6 +73,6 @@ Use ``ansible-doc -t connection `` to see detailed documentation an :ref:`vars_plugins` Vars plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/docs_fragment.rst b/docs/docsite/rst/plugins/docs_fragment.rst index 546229bee79..5f4350bffe1 100644 --- a/docs/docsite/rst/plugins/docs_fragment.rst +++ b/docs/docsite/rst/plugins/docs_fragment.rst @@ -30,6 +30,6 @@ Only collection developers and maintainers use docs fragments. For more informat :ref:`developing_collections` An guide to creating Ansible collections `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/filter.rst b/docs/docsite/rst/plugins/filter.rst index b768cfe5944..2985b1e42e2 100644 --- a/docs/docsite/rst/plugins/filter.rst +++ b/docs/docsite/rst/plugins/filter.rst @@ -58,6 +58,6 @@ You can use ``ansible-doc -t filter -l`` to see the list of available plugins. U :ref:`lookup_plugins` Lookup plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/httpapi.rst b/docs/docsite/rst/plugins/httpapi.rst index 7ce0573b918..7900ff6cf6c 100644 --- a/docs/docsite/rst/plugins/httpapi.rst +++ b/docs/docsite/rst/plugins/httpapi.rst @@ -67,6 +67,6 @@ These plugins have migrated to collections on `Ansible Galaxy ` How to develop network modules. `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! `irc.libera.chat `_ #ansible-network IRC chat channel diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst index 6ef7f603d13..8d9b12d9090 100644 --- a/docs/docsite/rst/plugins/inventory.rst +++ b/docs/docsite/rst/plugins/inventory.rst @@ -178,6 +178,6 @@ Use ``ansible-doc -t inventory `` to see plugin-specific documentat :ref:`vars_plugins` Vars plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/lookup.rst b/docs/docsite/rst/plugins/lookup.rst index d0336e91a52..570a333f38f 100644 --- a/docs/docsite/rst/plugins/lookup.rst +++ b/docs/docsite/rst/plugins/lookup.rst @@ -162,6 +162,6 @@ You can use ``ansible-doc -t lookup -l`` to see the list of available plugins. U :ref:`test_plugins` Jinja2 test plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/module.rst b/docs/docsite/rst/plugins/module.rst index 4d44f46979c..a07f3bbd3a5 100644 --- a/docs/docsite/rst/plugins/module.rst +++ b/docs/docsite/rst/plugins/module.rst @@ -38,6 +38,6 @@ For information on using modules in ad hoc tasks, see :ref:`intro_adhoc`. For in :ref:`developing_collections` An guide to creating Ansible collections `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! `irc.libera.chat `_ #ansible-devel IRC chat channel diff --git a/docs/docsite/rst/plugins/module_util.rst b/docs/docsite/rst/plugins/module_util.rst index c694380c6d4..8381fca2fd5 100644 --- a/docs/docsite/rst/plugins/module_util.rst +++ b/docs/docsite/rst/plugins/module_util.rst @@ -30,6 +30,6 @@ For information on using module utilities, see :ref:`developing_module_utilities :ref:`developing_collections` An guide to creating Ansible collections `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! `irc.libera.chat `_ #ansible-devel IRC chat channel diff --git a/docs/docsite/rst/plugins/netconf.rst b/docs/docsite/rst/plugins/netconf.rst index 4f79809d12e..217fd7e159c 100644 --- a/docs/docsite/rst/plugins/netconf.rst +++ b/docs/docsite/rst/plugins/netconf.rst @@ -42,6 +42,6 @@ These plugins have migrated to collections on `Ansible Galaxy ` An overview of using Ansible to automate networking devices. `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! `irc.libera.chat `_ #ansible-network IRC chat channel diff --git a/docs/docsite/rst/plugins/plugins.rst b/docs/docsite/rst/plugins/plugins.rst index 46ed28ee542..1c1355e081b 100644 --- a/docs/docsite/rst/plugins/plugins.rst +++ b/docs/docsite/rst/plugins/plugins.rst @@ -43,6 +43,6 @@ This section covers the various types of plugins that are included with Ansible: :ref:`command_line_tools` Ansible tools, description and options `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst index 30bf8c55a79..f17ecbb28ce 100644 --- a/docs/docsite/rst/plugins/shell.rst +++ b/docs/docsite/rst/plugins/shell.rst @@ -48,6 +48,6 @@ detailed in the plugin themselves (linked below). :ref:`lookup_plugins` Lookup plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/strategy.rst b/docs/docsite/rst/plugins/strategy.rst index 906d3b84ec1..a65a92b8d24 100644 --- a/docs/docsite/rst/plugins/strategy.rst +++ b/docs/docsite/rst/plugins/strategy.rst @@ -75,6 +75,6 @@ Use ``ansible-doc -t strategy `` to see plugin-specific specific do :ref:`lookup_plugins` Lookup plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/terminal.rst b/docs/docsite/rst/plugins/terminal.rst index 4c5f502ef67..ea0457d352d 100644 --- a/docs/docsite/rst/plugins/terminal.rst +++ b/docs/docsite/rst/plugins/terminal.rst @@ -37,6 +37,6 @@ Plugins are self-documenting. Each plugin should document its configuration opti :ref:`connection_plugins` Connection plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! `irc.libera.chat `_ #ansible-network IRC chat channel diff --git a/docs/docsite/rst/plugins/test.rst b/docs/docsite/rst/plugins/test.rst index 8f898af5d27..4d7e81bf863 100644 --- a/docs/docsite/rst/plugins/test.rst +++ b/docs/docsite/rst/plugins/test.rst @@ -96,6 +96,6 @@ You can use ``ansible-doc -t test -l`` to see the list of available plugins. Use :ref:`lookup_plugins` Lookup plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst index 054db623cfb..e9bd42c3064 100644 --- a/docs/docsite/rst/plugins/vars.rst +++ b/docs/docsite/rst/plugins/vars.rst @@ -62,6 +62,6 @@ You can use ``ansible-doc -t vars -l`` to see the list of available vars plugins :ref:`lookup_plugins` Lookup plugins `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index 2ef4994932f..d74f6dc8fdf 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -271,7 +271,7 @@ value: `YAMLLint `_ YAML Lint (online) helps you debug YAML syntax if you are having problems `GitHub examples directory `_ - Complete playbook files from the github project source + Complete playbook files from the GitHub project source `Wikipedia YAML syntax reference `_ A good guide to YAML syntax `Mailing List `_ diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index e663e7ba856..b0aaec7f243 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -946,4 +946,4 @@ If you have not found an answer to your questions, you can ask on one of our mai :ref:`playbooks_best_practices` Tips and tricks for playbooks `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst index b22af1db8f4..ce35c16e477 100644 --- a/docs/docsite/rst/reference_appendices/glossary.rst +++ b/docs/docsite/rst/reference_appendices/glossary.rst @@ -538,6 +538,6 @@ when a term comes up on the mailing list. :ref:`playbooks_best_practices` Tips and tricks for playbooks `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/reference_appendices/test_strategies.rst b/docs/docsite/rst/reference_appendices/test_strategies.rst index 8a3c43ed471..2cef3139f34 100644 --- a/docs/docsite/rst/reference_appendices/test_strategies.rst +++ b/docs/docsite/rst/reference_appendices/test_strategies.rst @@ -298,6 +298,6 @@ system. :ref:`playbooks_delegation` Delegation, useful for working with load balancers, clouds, and locally executed steps. `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! :ref:`communication_irc` How to join Ansible chat channels diff --git a/docs/docsite/rst/scenario_guides/guide_aci.rst b/docs/docsite/rst/scenario_guides/guide_aci.rst index 499863e3d46..95e76b54b5c 100644 --- a/docs/docsite/rst/scenario_guides/guide_aci.rst +++ b/docs/docsite/rst/scenario_guides/guide_aci.rst @@ -656,4 +656,4 @@ You will find our roadmap, an overview of open ACI issues and pull-requests, and `Network Working Group `_ The Ansible Network community page, includes contact information and meeting information. `User Mailing List `_ - Have a question? Stop by the google group! + Have a question? Stop by the Google group! diff --git a/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt b/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt index ba11d25d3e2..045887389a0 100644 --- a/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt +++ b/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt @@ -14,7 +14,7 @@ For example: # Install a collection in a repository using the latest commit on the branch 'devel' ansible-galaxy collection install git+https://github.com/organization/repo_name.git,devel - # Install a collection from a private github repository + # Install a collection from a private GitHub repository ansible-galaxy collection install git@github.com:organization/repo_name.git # Install a collection from a local git repository diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index f3c1bb8ab73..0a1163ebb88 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -202,6 +202,6 @@ This pulls in variables from the `group_vars/os_CentOS.yml` file. :ref:`intro_patterns` Learn about how to select hosts `GitHub examples directory `_ - Complete playbook files from the github project source + Complete playbook files from the GitHub project source `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/tips_tricks/sample_setup.rst b/docs/docsite/rst/tips_tricks/sample_setup.rst index 9c75df52c2f..9385aa69e29 100644 --- a/docs/docsite/rst/tips_tricks/sample_setup.rst +++ b/docs/docsite/rst/tips_tricks/sample_setup.rst @@ -290,6 +290,6 @@ If a playbook has a :file:`./library` directory relative to its YAML file, you c :ref:`intro_patterns` Learn about how to select hosts `GitHub examples directory `_ - Complete playbook files from the github project source + Complete playbook files from the GitHub project source `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups From b2cdfb08d256ea2b97fe474226a0a0bae7e294a8 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Wed, 25 Oct 2023 16:05:28 -0500 Subject: [PATCH 046/536] ci: refresh docs build dependencies (#720) --- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index fa5e678f891..bbed1a66400 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -30,7 +30,7 @@ asyncio-pool==0.6.0 # via antsibull-docs attrs==23.1.0 # via aiohttp -babel==2.13.0 +babel==2.13.1 # via # sphinx # sphinx-intl @@ -38,7 +38,7 @@ build==1.0.3 # via antsibull-core certifi==2023.7.22 # via requests -charset-normalizer==3.3.0 +charset-normalizer==3.3.1 # via # aiohttp # requests diff --git a/tests/requirements.txt b/tests/requirements.txt index a2ad9711f75..2429f0f2b4c 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -32,7 +32,7 @@ asyncio-pool==0.6.0 # via antsibull-docs attrs==23.1.0 # via aiohttp -babel==2.13.0 +babel==2.13.1 # via # sphinx # sphinx-intl @@ -40,7 +40,7 @@ build==1.0.3 # via antsibull-core certifi==2023.7.22 # via requests -charset-normalizer==3.3.0 +charset-normalizer==3.3.1 # via # aiohttp # requests From cb83448bcb940517f1b3e17e8524adbbce036015 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Fri, 6 Oct 2023 03:41:03 +0000 Subject: [PATCH 047/536] Run docs checkers in the noxfile This adds a checkers session to the noxfile to run docs checkers in tests/checkers.py. `nox -e checkers` runs all the docs checkers. `nox -e 'checkers(rstcheck)'` and `nox -e 'checkers(docs-build)'` can also be used to call individual checkers. Simply executing `nox` will clone ansible-core, run the Python linters, and the docs checkers (docs build test, rstcheck). This makes it a lot easier for contributors, as they can just run one command to make sure there changes will pass CI before submitting a PR and don't need to muck around with virtual environments and dependencies. --- noxfile.py | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/noxfile.py b/noxfile.py index 880fbf4bc93..ce660aee35f 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1,6 +1,7 @@ from __future__ import annotations import os +from argparse import ArgumentParser, BooleanOptionalAction from glob import iglob from pathlib import Path @@ -12,7 +13,7 @@ *iglob("docs/bin/*.py"), ) PINNED = os.environ.get("PINNED", "true").lower() in {"1", "true"} -nox.options.sessions = ("clone-core", "lint") +nox.options.sessions = ("clone-core", "lint", "checkers") def install(session: nox.Session, *args, req: str, **kwargs): @@ -113,3 +114,28 @@ def clone_core(session: nox.Session): source tree to facilitate building docs. """ session.run_always("python", "docs/bin/clone-core.py") + + +checker_tests = [ + path.with_suffix("").name for path in Path("tests/checkers/").glob("*.py") +] + + +@nox.session +@nox.parametrize(["test"], checker_tests, checker_tests) +def checkers(session: nox.Session, test: str): + """ + Run docs build checkers + """ + parser = ArgumentParser(prog=f"nox -e {session.name} --") + parser.add_argument( + "--relaxed", + default=False, + action=BooleanOptionalAction, + help="Whether to use requirements-relaxed file. (Default: %(default)s)", + ) + args = parser.parse_args(session.posargs) + + install(session, req="requirements-relaxed" if args.relaxed else "requirements") + session.run("make", "-C", "docs/docsite", "clean", external=True) + session.run("python", "tests/checkers.py", test) From b449dedcae03499402512354b40287d9b7dc56e6 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 18 Oct 2023 20:59:45 +0000 Subject: [PATCH 048/536] Use nox `checkers` session in CI Now that the docs checkers are integrated into the noxfile, we can use the nox session in CI instead of having to maintain separate CI configurations for these jobs. --- .github/workflows/ci.yaml | 48 ------------------------------ .github/workflows/reusable-nox.yml | 7 +++++ 2 files changed, 7 insertions(+), 48 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 656321080b4..3d92f5c4ede 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -9,53 +9,5 @@ on: workflow_dispatch: jobs: - docs_sanity_docs_build: - name: docs-build - runs-on: ubuntu-22.04 - steps: - - name: Checkout Docsite - uses: actions/checkout@v4 - - - name: Install Python 3.11 - uses: actions/setup-python@v4 - with: - python-version: '3.11' - - - name: Install Test Requirements - run: | - python -m pip install -r tests/requirements.in -c tests/requirements.txt - - - name: Graft ansible-core - run: | - python docs/bin/clone-core.py - - - name: Run docs-build Checkers - run: | - python tests/checkers.py docs-build - - docs_sanity_rstcheck: - name: rstcheck - runs-on: ubuntu-22.04 - steps: - - name: Checkout Docsite - uses: actions/checkout@v4 - - - name: Install Python 3.11 - uses: actions/setup-python@v4 - with: - python-version: '3.11' - - - name: Install Test Requirements - run: | - python -m pip install -r tests/requirements.in -c tests/requirements.txt - - - name: Graft ansible-core - run: | - python docs/bin/clone-core.py - - - name: Run rstcheck Checkers - run: | - python tests/checkers.py rstcheck - nox: uses: ./.github/workflows/reusable-nox.yml diff --git a/.github/workflows/reusable-nox.yml b/.github/workflows/reusable-nox.yml index ba56fb1a097..a7611e30f32 100644 --- a/.github/workflows/reusable-nox.yml +++ b/.github/workflows/reusable-nox.yml @@ -19,6 +19,10 @@ jobs: python-versions: "3.11" - session: spelling python-versions: "3.11" + - session: "checkers(rstcheck)" + python-versions: "3.11" + - session: "checkers(docs-build)" + python-versions: "3.11" name: "Run nox ${{ matrix.session }} session" steps: - name: Check out repo @@ -27,6 +31,9 @@ jobs: uses: wntrblm/nox@2023.04.22 with: python-versions: "${{ matrix.python-versions }}" + - name: Graft ansible-core + run: | + nox -e clone-core - name: "Run nox -e ${{ matrix.session }}" run: | nox -e "${{ matrix.session }}" From 5a74e2f0eb5840db1df01c9a0982983cbe10c08c Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 24 Oct 2023 18:31:38 +0100 Subject: [PATCH 049/536] README: document new nox sessions Co-authored-by: Maxwell G --- README.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 79 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 1f18d861c93..433c166c3f2 100644 --- a/README.md +++ b/README.md @@ -8,30 +8,95 @@ This repository holds the ReStructuredText (RST) source, and other files, for us Follow the documentation to [set up your environment](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally) and then [build Ansible community documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally) -## Using nox +## Verifying your pull request -This project includes a `nox` configuration to automate checks and other functions. -You should use `nox` to run checks locally before you submit a pull request. +We welcome all contributions to Ansible community documentation. +If you plan to submit a pull request with changes, you should [verify your PR](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#verifying-your-documentation-pr) to ensure it conforms with style guidelines and can build successfully. -Install `nox` using `python3 -m pip install nox` or your distribution's package manager. +### Running automated tests -Run `nox --list` from the repository root to view available sessions. +This project includes a `nox` configuration to automate tests, checks, and other functions. +You can use these automated tests to help you verify changes before you submit a PR. -Run `nox` with no arguments to execute the default sessions. +1. Install `nox` using `python3 -m pip install nox` or your distribution's package manager. +2. Run `nox --list` from the repository root to view available sessions. -## Running the spelling check +Each `nox` session creates a temporary environment that installs all requirements and runs the test or check. +This means you only need to run one command to perform the test accurately and consistently. +The following are some of the `nox` sessions you can run: -This repository uses [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source. +* Run all available sessions. -Run `nox -s spelling` to check spelling. + ``` + nox + ``` -Run `nox -s spelling -- -w` to correct spelling errors. +* Clone required parts of the `ansible/ansible` repository. -When `codespell` suggests more than one word as a correction, run `nox -s spelling -- -w -i 3` to select an option. + ``` + nox -s clone-core + ``` -## Updating the dependencies + See [Periodically cloning Ansible core](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#periodically-cloning-ansible-core) for more information. + +* Ensure there are no syntax errors in the reStructuredText source files. + + ``` + nox -s "checkers(rstcheck)" + ``` + + See [Running the final tests](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#running-the-final-tests) for more information. + +* Verify the docs build. + + ``` + nox -s "checkers(docs-build)" + ``` + + This session cleans the generated docs after it runs. + If you want to view the generated HTML in your browser, you should build the documentation locally. + See [Building the documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally) for more information. + +* Lint, type check, and format Python scripts in this repository. + + ``` + nox -s lint + ``` + +## Checking spelling + +Use [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source. + +* Check spelling. + + ``` + nox -s spelling + ``` + +* Correct any detected spelling errors. + + ``` + nox -s spelling -- -w + ``` + +* Select an option when `codespell` suggests more than one word as a correction. + + ``` + nox -s spelling -- -w -i 3 + ``` + +## Updating dependencies + +Use the following `nox` session to update project dependency versions. + + ``` + nox -e pip-compile + ``` + +> This session requires Python 3.10. + +If you do not have Python 3.10 installed, you can use root-less podman with a Python 3.10 image as follows: -To update dependencies, you can use `nox -e pip-compile`. Since this requires Python 3.10, this might not work in your environment if you do not have Python 3.10 installed. In that case, you can use root-less podman with a Python 3.10 image: ```bash -podman run --rm --tty --volume "$(pwd):/mnt:z" --workdir /mnt python:3.10 bash -c 'pip install nox ; nox -e pip-compile' +podman run --rm --tty --volume "$(pwd):/mnt:z" --workdir /mnt docker.io/library/python:3.10 bash -c 'pip install nox ; nox -e pip-compile' ``` From 54b7657e0aeab302fbaf00d0be9c90051a25ddad Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Thu, 26 Oct 2023 02:51:53 +0000 Subject: [PATCH 050/536] noxfile install(): log PIP_CONSTRAINT value When pinned dependencies are enabled (the default), this will log the value of the PIP_CONSTRAINT env var. --- noxfile.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/noxfile.py b/noxfile.py index ce660aee35f..2f6df57159d 100644 --- a/noxfile.py +++ b/noxfile.py @@ -18,7 +18,9 @@ def install(session: nox.Session, *args, req: str, **kwargs): if PINNED: - kwargs.setdefault("env", {})["PIP_CONSTRAINT"] = f"tests/{req}.txt" + pip_constraint = f"tests/{req}.txt" + kwargs.setdefault("env", {})["PIP_CONSTRAINT"] = pip_constraint + session.log(f"export PIP_CONSTRAINT={pip_constraint!r}") session.install("-r", f"tests/{req}.in", *args, **kwargs) From 30f0a7c080c7c6efd2c6908602d7c4cb5b6d1386 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Thu, 26 Oct 2023 03:09:01 +0000 Subject: [PATCH 051/536] README: document Dependency files and PINNED envvar This documents the way dependency files are organized and handled by nox. Co-authored-by: Don Naro --- README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 433c166c3f2..b88530961f9 100644 --- a/README.md +++ b/README.md @@ -85,9 +85,23 @@ Use [`codespell`](https://github.com/codespell-project/codespell) to check for c nox -s spelling -- -w -i 3 ``` +## Dependency files + +`nox` sessions use dependencies from requirements files in the `tests/` directory. +Each session has a `tests/{name}.in` file with direct dependencies and a lock file in `tests/{name}.txt` that pins *exact versions* for both direct and transitive dependencies. +The lock files contain tested dependencies that are automatically updated on a weekly basis. + +If you'd like to use untested dependencies, set `PINNED=false` as in the following example: + +``` +PINNED=false nox -s "checkers(docs-build)" +``` + +For more details about using unpinned and tested dependencies for doc builds, see [Setting up your environment to build documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally). + ## Updating dependencies -Use the following `nox` session to update project dependency versions. +Use the following `nox` session to update the dependency lock files in `tests/`. ``` nox -e pip-compile From 0713293b9d4639f766f011869a5a4d9a6f54a824 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sat, 28 Oct 2023 20:26:40 -0500 Subject: [PATCH 052/536] ci: refresh dev dependencies (#741) --- tests/static.txt | 2 +- tests/typing.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index 2cb0574a25c..534b98020c2 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.2 +ruff==0.1.3 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index c8a2ea11f6f..6b115249057 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -26,7 +26,7 @@ deprecated==1.2.14 # via pygithub distlib==0.3.7 # via virtualenv -filelock==3.12.4 +filelock==3.13.0 # via virtualenv idna==3.4 # via requests From 40d3af4771d9770069a68a0cb662f19ead2dce29 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 31 Oct 2023 16:57:55 +0100 Subject: [PATCH 053/536] communication.rst: Make WG a top-level section (#750) --- docs/docsite/rst/community/communication.rst | 33 +++++++++++--------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index b38e9d7491b..ed0bfcad80e 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -105,10 +105,28 @@ The clickable links will take you directly to the relevant Matrix room in your b - `For public community meetings `_ - ``Matrix: #meeting:ansible.im | IRC: #ansible-meeting`` - We will generally announce these on one or more of the above mailing lists. See the `meeting schedule and agenda page `_ +Working group-specific channels +------------------------------- + +Many of the working groups have dedicated chat channels. See the :ref:`working_group_list` for more information. + +Regional and Language-specific channels +--------------------------------------- + +- Comunidad Ansible en español - Matrix: `#espanol:ansible.im `_ | IRC: ``#ansible-es`` +- Communauté française d'Ansible - Matrix: `#francais:ansible.im `_ | IRC: ``#ansible-fr`` +- Communauté suisse d'Ansible - Matrix: `#suisse:ansible.im `_ | IRC: ``#ansible-zh`` +- European Ansible Community - Matrix: `#europe:ansible.im `_ | IRC: ``#ansible-eu`` + +Meetings on chat +---------------- + +The Ansible community holds regular meetings on various topics on Matrix/IRC, and anyone who is interested is invited to participate. For more information about Ansible meetings, consult the `meeting schedule and agenda page `_. + .. _working_group_list: Working groups --------------- +============== Our community working groups are represented in forms of `Forum groups `_ (new style) or `wiki pages `_ (deprecated). @@ -143,19 +161,6 @@ Many of them meet in chat. If you want to get involved in a working group, join Want to `form a new Working Group `_? -Regional and Language-specific channels ---------------------------------------- - -- Comunidad Ansible en español - Matrix: `#espanol:ansible.im `_ | IRC: ``#ansible-es`` -- Communauté française d'Ansible - Matrix: `#francais:ansible.im `_ | IRC: ``#ansible-fr`` -- Communauté suisse d'Ansible - Matrix: `#suisse:ansible.im `_ | IRC: ``#ansible-zh`` -- European Ansible Community - Matrix: `#europe:ansible.im `_ | IRC: ``#ansible-eu`` - -Meetings on chat ----------------- - -The Ansible community holds regular meetings on various topics on Matrix/IRC, and anyone who is interested is invited to participate. For more information about Ansible meetings, consult the `meeting schedule and agenda page `_. - Ansible Community Topics ======================== From 40342fa3be6b98e47bf134dacd97e08a381518ac Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 31 Oct 2023 12:28:28 -0400 Subject: [PATCH 054/536] Remove contributor summit banner (#749) * Remove contributor summit banner * Update docs/docsite/.templates/banner.html Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- docs/docsite/.templates/banner.html | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/docsite/.templates/banner.html b/docs/docsite/.templates/banner.html index 0afb629fdde..f013940f258 100644 --- a/docs/docsite/.templates/banner.html +++ b/docs/docsite/.templates/banner.html @@ -20,8 +20,6 @@ '
' + '

' + 'Discuss Ansible in the new Ansible Forum!' + - '
' + - 'Come join us for Ansible Contributor Summit in Durham, NC, USA. Propose topics by Oct 6!' + '

' + '
'; // Create a banner if we're not on the official docs site From 152e4b6cb2bb3066163e02efcf499fa86a0b7549 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Wed, 1 Nov 2023 07:10:15 -0700 Subject: [PATCH 055/536] Fixed equalto test filter (#758) Fixes: #748 Signed-off-by: Abhijeet Kasurde --- docs/docsite/rst/plugins/test.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/plugins/test.rst b/docs/docsite/rst/plugins/test.rst index 4d7e81bf863..19581d8461c 100644 --- a/docs/docsite/rst/plugins/test.rst +++ b/docs/docsite/rst/plugins/test.rst @@ -23,7 +23,7 @@ You can add a custom test plugin by dropping it into a ``test_plugins`` director Using test plugins ------------------- -You can use tests anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the :ref:`template ` module. For more information on using test plugins, see :ref:`playbooks_tests`. +You can use tests anywhere you can use templating in Ansible: in a play, in a variables file, or in a Jinja2 template for the :ref:`template ` module. For more information on using test plugins, see :ref:`playbooks_tests`. Tests always return ``True`` or ``False``, they are always a boolean, if you need a different return type, you should be looking at filters. @@ -44,7 +44,7 @@ Tests will always have an ``_input`` and this is normally what is on the left si .. code-block:: YAML+Jinja tasks: - - name: pass positional parameter to match test + - name: pass a positional parameter to match test action: dostuff when: myurl is match("https://example.com/users/.*/resources") @@ -68,10 +68,10 @@ As mentioned above, one way to use tests is with the ``select`` family of filter good_vars: "{{ all_vars|select('defined') }}" # this uses the 'equalto' test to filter out non 'fixed' type of addresses from a list - only_fixed_addresses: "{{ all_addresses|selectattr('type', 'equalsto', 'fixed') }}" + only_fixed_addresses: "{{ all_addresses|selectattr('type', 'equalto', 'fixed') }}" # this does the opposite of the previous one - only_fixed_addresses: "{{ all_addresses|rejectattr('type', 'equalsto', 'fixed') }}" + only_fixed_addresses: "{{ all_addresses|rejectattr('type', 'equalto', 'fixed') }}" Plugin list From 91c2704b30aa690d2c422ffeeb51f2d8d380e2c2 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Wed, 1 Nov 2023 13:19:35 -0700 Subject: [PATCH 056/536] Remove dangling reference (#732) * Removed dangling reference for working_with_modules * Updated references to modules Fixes: #513 Signed-off-by: Abhijeet Kasurde --- docs/docsite/rst/command_guide/intro_adhoc.rst | 5 ++--- docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst | 2 +- docs/docsite/rst/plugins/action.rst | 2 +- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/command_guide/intro_adhoc.rst b/docs/docsite/rst/command_guide/intro_adhoc.rst index 1f9406df092..6e1810fa197 100644 --- a/docs/docsite/rst/command_guide/intro_adhoc.rst +++ b/docs/docsite/rst/command_guide/intro_adhoc.rst @@ -24,7 +24,7 @@ ad hoc commands are great for tasks you repeat rarely. For example, if you want $ ansible [pattern] -m [module] -a "[module options]" The ``-a`` option accepts options either through the ``key=value`` syntax or a JSON string starting with ``{`` and ending with ``}`` for more complex option structure. -You can learn more about :ref:`patterns` and :ref:`modules` on other pages. +You can learn more about :ref:`patterns` and :ref:`modules` on other pages. Use cases for ad hoc tasks ========================== @@ -65,8 +65,7 @@ If you add ``--ask-become-pass`` or ``-K``, Ansible prompts you for the password .. note:: The :ref:`command module ` does not support extended shell syntaxes like piping and redirects (although shell variables will always work). If your command requires shell-specific - syntax, use the `shell` module instead. Read more about the differences on the - :ref:`working_with_modules` page. + syntax, use the `shell` module instead. So far all our examples have used the default 'command' module. To use a different module, pass ``-m`` for module name. For example, to use the :ref:`ansible.builtin.shell module `: diff --git a/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst b/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst index d4f306a30c8..9ab80ec679d 100644 --- a/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst +++ b/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst @@ -293,7 +293,7 @@ Again, if you were using a Netscaler or F5 or Elastic Load Balancer, you would j Managing other load balancers ============================= -In this example, we use the simple HAProxy load balancer to front-end the web servers. It is easy to configure and easy to manage. As we have mentioned, Ansible has support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. See the :ref:`working_with_modules` documentation for more information. +In this example, we use the simple HAProxy load balancer to front-end the web servers. It is easy to configure and easy to manage. As we have mentioned, Ansible has support for a variety of other load balancers like Citrix NetScaler, F5 BigIP, Amazon Elastic Load Balancers, and more. For other load balancers, you may need to send shell commands to them (like we do for HAProxy above), or call an API, if your load balancer exposes one. For the load balancers for which Ansible has modules, you may want to run them as a ``local_action`` if they contact an API. You can read more about local actions in the :ref:`playbooks_delegation` section. Should you develop anything interesting for some hardware where there is not a module, it might make for a good contribution! diff --git a/docs/docsite/rst/plugins/action.rst b/docs/docsite/rst/plugins/action.rst index 1ead01562f0..d4a75958419 100644 --- a/docs/docsite/rst/plugins/action.rst +++ b/docs/docsite/rst/plugins/action.rst @@ -7,7 +7,7 @@ Action plugins :local: :depth: 2 -Action plugins act in conjunction with :ref:`modules ` to execute the actions required by playbook tasks. They usually execute automatically in the background doing prerequisite work before modules execute. +Action plugins act in conjunction with :ref:`modules ` to execute the actions required by playbook tasks. They usually execute automatically in the background doing prerequisite work before modules execute. The 'normal' action plugin is used for modules that do not already have an action plugin. If necessary, you can :ref:`create custom action plugins `. From e3e7e7ef8b300a19960d8ad1820805e4276c6241 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 1 Nov 2023 16:21:48 -0400 Subject: [PATCH 057/536] moar complitz tags docs (#620) Co-authored-by: Don Naro Co-authored-by: Abhijeet Kasurde --- .../rst/playbook_guide/playbooks_tags.rst | 153 ++++++++++++------ 1 file changed, 100 insertions(+), 53 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst index e839b2173ea..c5aec6d55d1 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst @@ -80,45 +80,8 @@ You can apply the same tag to more than one individual task. This example tags s If you ran these four tasks in a playbook with ``--tags ntp``, Ansible would run the three tasks tagged ``ntp`` and skip the one task that does not have that tag. -.. _tags_on_includes: - -Adding tags to includes ------------------------ - -You can apply tags to dynamic includes in a playbook. As with tags on an individual task, tags on an ``include_*`` task apply only to the include itself, not to any tasks within the included file or role. If you add ``mytag`` to a dynamic include, then run that playbook with ``--tags mytag``, Ansible runs the include itself, runs any tasks within the included file or role tagged with ``mytag``, and skips any tasks within the included file or role without that tag. See :ref:`selective_reuse` for more details. - -You add tags to includes the same way you add tags to any other task: - -.. code-block:: yaml - - --- - # file: roles/common/tasks/main.yml - - - name: Dynamic reuse of database tasks - include_tasks: db.yml - tags: db -You can add a tag only to the dynamic include of a role. In this example, the ``foo`` tag will `not` apply to tasks inside the ``bar`` role: - -.. code-block:: yaml - - --- - - hosts: webservers - tasks: - - name: Include the bar role - include_role: - name: bar - tags: - - foo - -With plays, blocks, the ``role`` keyword, and static imports, Ansible applies tag inheritance, adding the tags you define to every task inside the play, block, role, or imported file. However, tag inheritance does *not* apply to dynamic reuse with ``include_role`` and ``include_tasks``. With dynamic reuse (includes), the tags you define apply only to the include itself. If you need tag inheritance, use a static import. If you cannot use an import because the rest of your playbook uses includes, see :ref:`apply_keyword` for ways to work around this behavior. - -.. _tag_inheritance: - -Tag inheritance: adding tags to multiple tasks ----------------------------------------------- - -If you want to apply the same tag or tags to multiple tasks without adding a ``tags`` line to every task, you can define the tags at the level of your play or block, or when you add a role or import a file. Ansible applies the tags down the dependency chain to all child tasks. With roles and imports, Ansible appends the tags set by the ``roles`` section or import to any tags set on individual tasks or blocks within the role or imported file. This is called tag inheritance. Tag inheritance is convenient, because you do not have to tag every task. However, the tags still apply to the tasks individually. +.. _tags_on_blocks: Adding tags to blocks ^^^^^^^^^^^^^^^^^^^^^ @@ -157,6 +120,9 @@ If you want to apply a tag to many, but not all, of the tasks in your play, use state: present tags: filesharing + +.. _tags_on_plays: + Adding tags to plays ^^^^^^^^^^^^^^^^^^^^ @@ -190,6 +156,9 @@ If all the tasks in a play should get the same tag, you can add the tag at the l tasks: ... + +.. _tags_on_roles: + Adding tags to roles ^^^^^^^^^^^^^^^^^^^^ @@ -223,6 +192,38 @@ or: # using YAML shorthand, this is equivalent to: # - { role: foo, tags: ["bar", "baz"] } +.. _tags_on_includes: + +Adding tags to includes +^^^^^^^^^^^^^^^^^^^^^^^ + +You can apply tags to dynamic includes in a playbook. As with tags on an individual task, tags on an ``include_*`` task apply only to the include itself, not to any tasks within the included file or role. If you add ``mytag`` to a dynamic include, then run that playbook with ``--tags mytag``, Ansible runs the include itself, runs any tasks within the included file or role tagged with ``mytag``, and skips any tasks within the included file or role without that tag. See :ref:`selective_reuse` for more details. + +You add tags to includes the same way you add tags to any other task: + +.. code-block:: yaml + + --- + # file: roles/common/tasks/main.yml + + - name: Dynamic reuse of database tasks + include_tasks: db.yml + tags: db + +You can add a tag only to the dynamic include of a role. In this example, the ``foo`` tag will `not` apply to tasks inside the ``bar`` role: + +.. code-block:: yaml + + --- + - hosts: webservers + tasks: + - name: Include the bar role + include_role: + name: bar + tags: + - foo + + .. _tags_on_imports: Adding tags to imports @@ -277,10 +278,16 @@ Or you can use a block: .. _special_tags: -Special tags: always and never -============================== +Special tags +============ -Ansible reserves two tag names for special behavior: always and never. If you assign the ``always`` tag to a task or play, Ansible will always run that task or play, unless you specifically skip it (``--skip-tags always``). +Ansible reserves several tag names for special behavior: ``always``, ``never``, ``tagged``, ``untagged`` and ``all``. +Both ``always`` and ``never`` are mostly for use in tagging the tasks themselves, the other three are used when selecting which tags to run or skip. + + +Always and Never +---------------- +Ansible reserves several tag names for special behavior, two of which are ``always`` and ``never``. If you assign the ``always`` tag to a task or play, Ansible will always run that task or play, unless you specifically skip it (``--skip-tags always``) or another tag defined on that task. For example: @@ -295,14 +302,21 @@ For example: - name: Print a message ansible.builtin.debug: - msg: "runs when you use tag1" + msg: "runs when you use specify tag1, all(default) or tagged" tags: - tag1 + - name: Print a message + ansible.builtin.debug: + msg: "always runs unless you explicitly skip, like if you use ``--skip-tags tag2``" + tags: + - always + - tag2 + .. warning:: - * Fact gathering is tagged with 'always' by default. It is only skipped if - you apply a tag to the play and then use a different tag in ``--tags`` or the same - tag in ``--skip-tags``. + * The internal fact gathering task is tagged with 'always' by default. But it can be skipped if + you apply a tag to the play and you skip it directly (``--skip-tags``) or indirectly when you use + ``--tags`` and omit it. .. warning:: * The role argument specification validation task is tagged with 'always' by default. This validation @@ -310,14 +324,14 @@ For example: .. versionadded:: 2.5 -If you assign the ``never`` tag to a task or play, Ansible will skip that task or play unless you specifically request it (``--tags never``). +If you assign the ``never`` tag to a task or play, Ansible skips that task or play unless you specifically request it (``--tags never``) or another tag defined for that task. For example: .. code-block:: yaml tasks: - - name: Run the rarely-used debug task + - name: Run the rarely-used debug task, either with ``--tags debug`` or ``--tags never`` ansible.builtin.debug: msg: '{{ showmevar }}' tags: [ never, debug ] @@ -331,13 +345,15 @@ Selecting or skipping tags when you run a playbook Once you have added tags to your tasks, includes, blocks, plays, roles, and imports, you can selectively execute or skip tasks based on their tags when you run :ref:`ansible-playbook`. Ansible runs or skips all tasks with tags that match the tags you pass at the command line. If you have added a tag at the block or play level, with ``roles``, or with an import, that tag applies to every task within the block, play, role, or imported role or file. If you have a role with several tags and you want to call subsets of the role at different times, either :ref:`use it with dynamic includes `, or split the role into multiple roles. + :ref:`ansible-playbook` offers five tag-related command-line options: -* ``--tags all`` - run all tasks, ignore tags (default behavior) -* ``--tags tag1,tag2`` - run only tasks with either the tag ``tag1`` or the tag ``tag2`` -* ``--skip-tags tag3,tag4`` - run all tasks except those with either the tag ``tag3`` or the tag ``tag4`` -* ``--tags tagged`` - run only tasks with at least one tag -* ``--tags untagged`` - run only tasks with no tags +* ``--tags all`` - run all tasks, tagged and untagged except if ``never`` (default behavior). +* ``--tags tag1,tag2`` - run only tasks with either the tag ``tag1`` or the tag ``tag2`` (also those tagged ``always``). +* ``--skip-tags tag3,tag4`` - run all tasks except those with either the tag ``tag3`` or the tag ``tag4`` or ``never``. +* ``--tags tagged`` - run only tasks with at least one tag (``never`` overrides). +* ``--tags untagged`` - run only tasks with no tags (``always`` overrides). + For example, to run only tasks and blocks tagged either ``configuration`` or ``packages`` in a very long playbook: @@ -357,6 +373,21 @@ To run all tasks, even those excluded because are tagged ``never``: ansible-playbook example.yml --tags "all,never" +Run tasks with tag1 or tag3 but skip tasks that also have tag4: + +.. code-block:: bash + + ansible-playbook example.yml --tags "tag1,tag3" --skip-tags "tag4" + + +.. _tag_precedence: + +Tag precedence +-------------- +Skipping always takes precedence over explicit tags, for example, if you specify both ``--tags`` and ``--skip-tags`` the latter has precedence. For example ``--tags tag1,tag3,tag4 --skip-tags tag3`` will only run tasks tagged with tag1 or tag4, but not with tag3, even if the task has one of the other tags. + + + Previewing the results of using tags ------------------------------------ @@ -379,6 +410,7 @@ If you do not know which tasks have the tags ``configuration`` and ``packages``, These command-line flags have one limitation: they cannot show tags or tasks within dynamically included files or roles. See :ref:`dynamic_vs_static` for more information on differences between static imports and dynamic includes. + .. _selective_reuse: Selectively running tagged tasks in reusable files @@ -419,7 +451,22 @@ And you might include the tasks file above in a playbook: name: mixed.yml tags: mytag -When you run the playbook with ``ansible-playbook -i hosts myplaybook.yml --tags "mytag"``, Ansible skips the task with no tags, runs the tagged individual task, and runs the two tasks in the block. +When you run the playbook with ``ansible-playbook -i hosts myplaybook.yml --tags "mytag"``, Ansible skips the task with no tags, runs the tagged individual task, and runs the two tasks in the block. Also it could run fact gathering (implicit task) as it is tagged with ``always``. + + +.. _tag_inheritance: + +Tag inheritance: adding tags to multiple tasks +---------------------------------------------- + +If you want to apply the same tag or tags to multiple tasks without adding a ``tags`` line to every task, you can define the tags at the level of your play or block, or when you add a role or import a file. Ansible applies the tags down the dependency chain to all child tasks. With roles and imports, Ansible appends the tags set by the ``roles`` section or import to any tags set on individual tasks or blocks within the role or imported file. This is called tag inheritance. Tag inheritance is convenient because you do not have to tag every task. However, the tags still apply to the tasks individually. + +With plays, blocks, the ``role`` keyword, and static imports, Ansible applies tag inheritance, adding the tags you define to every task inside the play, block, role, or imported file. However, tag inheritance does *not* apply to dynamic reuse with ``include_role`` and ``include_tasks``. With dynamic reuse (includes), the tags you define apply only to the include itself. If you need tag inheritance, use a static import. If you cannot use an import because the rest of your playbook uses includes, see :ref:`apply_keyword` for ways to work around this behavior. + +You can apply tags to dynamic includes in a playbook. As with tags on an individual task, tags on an ``include_*`` task apply only to the include itself, not to any tasks within the included file or role. If you add ``mytag`` to a dynamic include, then run that playbook with ``--tags mytag``, Ansible runs the include itself, runs any tasks within the included file or role tagged with ``mytag``, and skips any tasks within the included file or role without that tag. See :ref:`selective_reuse` for more details. + + +.. _tag_global_config: Configuring tags globally ------------------------- From f8e8191e8330bc80003d85bc97cf8256549803ce Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Thu, 2 Nov 2023 15:10:33 -0500 Subject: [PATCH 058/536] intro_installation: pass --include-injected in pipx upgrade example (#745) `--include-injected` ensures that the ansible-core package and other packages that users may have injected into the ansible pipx venv are updated alongside the ansible package. --- docs/docsite/rst/installation_guide/intro_installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index ff4b91a9fa5..73a3c7cc5b0 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -98,7 +98,7 @@ To upgrade an existing Ansible installation to the latest released version: .. code-block:: console - $ pipx upgrade ansible + $ pipx upgrade --include-injected ansible .. _pipx_inject: From a435c757e89e0aebc19103cc43c3b011c2560a7d Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sat, 4 Nov 2023 23:27:20 -0500 Subject: [PATCH 059/536] ci: refresh dev dependencies (#770) --- tests/static.txt | 2 +- tests/typing.txt | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index 534b98020c2..be223e23022 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.3 +ruff==0.1.4 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 6b115249057..078485655ff 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/typing.txt --strip-extras tests/typing.in # -argcomplete==3.1.2 +argcomplete==3.1.4 # via nox certifi==2023.7.22 # via requests @@ -12,7 +12,7 @@ cffi==1.16.0 # via # cryptography # pynacl -charset-normalizer==3.3.1 +charset-normalizer==3.3.2 # via requests click==8.1.7 # via typer @@ -26,7 +26,7 @@ deprecated==1.2.14 # via pygithub distlib==0.3.7 # via virtualenv -filelock==3.13.0 +filelock==3.13.1 # via virtualenv idna==3.4 # via requests From d9b59f1141bd3a1c591a9e2276937f1fcf5431d5 Mon Sep 17 00:00:00 2001 From: TVo Date: Mon, 6 Nov 2023 08:21:02 -0700 Subject: [PATCH 060/536] Replaced the AWX mailing list with the AWX Forum page. (#769) --- docs/docsite/rst/community/communication.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index ed0bfcad80e..ad353c4f97a 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -202,7 +202,7 @@ Asking questions over email Your first post to the mailing list will be moderated (to reduce spam), so please allow up to a day or so for your first post to appear. * `Ansible Announce list `_ is a read-only list that shares information about new releases of Ansible, and also rare infrequent event information, such as announcements about an upcoming AnsibleFest, which is our official conference series. Worth subscribing to! -* `Ansible AWX List `_ is for `Ansible AWX `_ +* `Ansible AWX List `_ is for `Ansible AWX `_ * `Ansible Development List `_ is for questions about developing Ansible modules (mostly in Python), fixing bugs in the Ansible Core code, asking about prospective feature design, or discussions about extending Ansible or features in progress. * `Ansible Outreach List `_ help with promoting Ansible and `Ansible Meetups `_ * `Ansible Project List `_ is for sharing Ansible tips, answering questions about playbooks and roles, and general user discussion. From caf45586db580c175fe7003a3721784d1520090f Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 6 Nov 2023 15:27:24 +0000 Subject: [PATCH 061/536] ci: refresh docs build dependencies (#771) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 2 +- tests/requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index bbed1a66400..a458d3c7f2f 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -38,7 +38,7 @@ build==1.0.3 # via antsibull-core certifi==2023.7.22 # via requests -charset-normalizer==3.3.1 +charset-normalizer==3.3.2 # via # aiohttp # requests diff --git a/tests/requirements.txt b/tests/requirements.txt index 2429f0f2b4c..f72f73c7b3f 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -40,7 +40,7 @@ build==1.0.3 # via antsibull-core certifi==2023.7.22 # via requests -charset-normalizer==3.3.1 +charset-normalizer==3.3.2 # via # aiohttp # requests From a8d65125fd435431893b961d8356fb504088e74c Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Mon, 6 Nov 2023 13:23:31 -0500 Subject: [PATCH 062/536] update versioning for 2.16 (#755) --- docs/docsite/rst/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 2dc33cc06ff..c4683441864 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -238,7 +238,7 @@ 'current_version': version, 'latest_version': ( 'devel' if tags.has('all') else - '2.15' if tags.has('core_lang') or tags.has('core') else + '2.16' if tags.has('core_lang') or tags.has('core') else '2.10' if tags.has('2.10') else '8' if tags.has('ansible') else '' @@ -247,7 +247,7 @@ 'available_versions': ( ('devel',) if tags.has('all') else ('2.15_ja', '2.14_ja', '2.13_ja',) if tags.has('core_lang') else - ('2.15', '2.14', '2.13', 'devel',) if tags.has('core') else + ('2.16', '2.15', '2.14', 'devel',) if tags.has('core') else ('latest', '2.9', '2.9_ja', '2.8', 'devel') if tags.has('2.10') else ('latest', '2.9', 'devel') if tags.has('ansible') else '' From fa6d0dfc491fdefec56fdd24edc803cccd578855 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Mon, 6 Nov 2023 13:24:03 -0500 Subject: [PATCH 063/536] update headings and title instructions (#778) --- .../rst/dev_guide/style_guide/index.rst | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst index 094fae5a4c8..cb0a1f10c9f 100644 --- a/docs/docsite/rst/dev_guide/style_guide/index.rst +++ b/docs/docsite/rst/dev_guide/style_guide/index.rst @@ -42,11 +42,11 @@ This cheat-sheet illustrates a few rules that help achieve the "Ansible tone": | Use American English | The color of the output | The colour of the output | +-------------------------------+------------------------------+----------------------------------------+ -Header case ------------ +Title and heading case +---------------------- -Headers should be written in sentence case. For example, this section's title is -``Header case``, not ``Header Case`` or ``HEADER CASE``. +Titles and headings should be written in sentence case. For example, this section's title is +``Title and heading case``, not ``Title and Heading Case`` or ``TITLE AND HEADING CASE``. Avoid using Latin phrases @@ -79,15 +79,15 @@ reStructuredText guidelines The Ansible documentation is written in reStructuredText and processed by Sphinx. We follow these technical or mechanical guidelines on all rST pages: -.. _headers_style: +.. _headings_style: -Header notation ---------------- +Heading notation +---------------- -`Section headers in reStructuredText `_ +`Section headings in reStructuredText `_ can use a variety of notations. -Sphinx will 'learn on the fly' when creating a hierarchy of headers. -To make our documents easy to read and to edit, we follow a standard set of header notations. +Sphinx will 'learn on the fly' when creating a hierarchy of headings. +To make our documents easy to read and to edit, we follow a standard set of heading notations. We use: * ``###`` with overline, for parts: @@ -179,11 +179,11 @@ work together to help users find related content. Local tables of contents also help users navigate quickly to the information they need. All internal links should use the ``:ref:`` syntax. Every page should have at least one anchor to support internal ``:ref:`` links. -Long pages, or pages with multiple levels of headers, can also include a local TOC. +Long pages, or pages with multiple levels of headings, can also include a local TOC. .. note:: - Avoid raw URLs. RST and sphinx allow ::code:`https://my.example.com`, but this is unhelpful for those using screen readers. ``:ref:`` links automatically pick up the header from the anchor, but for external links, always use the ::code:`link title `_` format. + Avoid raw URLs. RST and sphinx allow ::code:`https://my.example.com`, but this is unhelpful for those using screen readers. ``:ref:`` links automatically pick up the heading from the anchor, but for external links, always use the ::code:`link title `_` format. .. _adding_anchors_rst: @@ -191,7 +191,7 @@ Adding anchors ^^^^^^^^^^^^^^ * Include at least one anchor on every page -* Place the main anchor above the main header +* Place the main anchor above the main heading * If the file has a unique title, use that for the main page anchor: .. code-block:: text @@ -289,7 +289,7 @@ The page you're reading includes a `local TOC `_ +`Section headings in markdown `_ can use a variety of notations. -To make our documents easy to read and to edit, we follow a standard set of header notations. +To make our documents easy to read and to edit, we follow a standard set of heading notations. We use: * ``#`` for page titles: @@ -321,7 +321,7 @@ We use: # Installation -* ``##`` for section headers: +* ``##`` for section headings: .. code-block:: md @@ -344,7 +344,7 @@ Using Mkdocs, you can format `internal links Date: Tue, 7 Nov 2023 03:37:45 +0900 Subject: [PATCH 064/536] Update the Note for certificate authentication with a TLS 1.3 connection in windows_winrm.rst (#757) * Update windows_winrm.rst Since certificate authentication with a TLS 1.3 connection works using Ansible Automation Platform 2.4, updating the Note. * Delete requests python package from Note for certificate authentication with a TLS 1.3 connection in windows_winrm.rst Delete the requests python package from the mandatory packages since the fix is only included in urllib3 package. --- docs/docsite/rst/os_guide/windows_winrm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/os_guide/windows_winrm.rst b/docs/docsite/rst/os_guide/windows_winrm.rst index d87cac8956b..fbebe93a71d 100644 --- a/docs/docsite/rst/os_guide/windows_winrm.rst +++ b/docs/docsite/rst/os_guide/windows_winrm.rst @@ -127,7 +127,7 @@ be enabled by running the following in PowerShell: .. Note:: Encrypted private keys cannot be used as the urllib3 library that is used by Ansible for WinRM does not support this functionality. -.. Note:: Certificate authentication does not work with a TLS 1.3 connection. +.. Note:: For enabling certificate authentication with a TLS 1.3 connection, Python 3.8+, 3.7.1, or 3.6.7 and Python packages urllib3==2.0.7 or newer are required. .._winrm_certificate_generate: From 6c103851c35fe4d943defb2b12c0cd875d968ed5 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 7 Nov 2023 17:42:27 +0100 Subject: [PATCH 065/536] Porting guide for 9.0.0b1. (#787) --- .../rst/porting_guides/porting_guide_9.rst | 255 +++++++++++++++--- 1 file changed, 212 insertions(+), 43 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 708ce6ea88c..ea75e6b4535 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -64,6 +64,218 @@ Networking ========== +Porting Guide for v9.0.0b1 +========================== + +Added Collections +----------------- + +- ibm.storage_virtualize (version 2.1.0) + +Known Issues +------------ + +community.general +~~~~~~~~~~~~~~~~~ + +- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/general/ (https://github.com/ansible-collections/community.general/pull/6539). + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- ca_path missing - Issue(275740) - The roles idrac_attributes, redfish_storage_volume, and idrac_server_powerstate have a missing parameter ca_path. +- idrac_firmware - Issue(279282) - idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_network_attributes - Issue(279049) - If unsupported values are provided for the parameter ``ome_network_attributes``, then this module does not provide a correct error message. +- ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the following parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. +- ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` +- ome_device_quick_deploy - Issue(275231) - This module does not deploy a new configuration to a slot that has disabled IPv6. +- ome_smart_fabric_uplink - Issue(186024) - Despite the module supported by OpenManage Enterprise Modular, it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. + +Breaking Changes +---------------- + +amazon.aws +~~~~~~~~~~ + +- The amazon.aws collection has dropped support for ``botocore<1.29.0`` and ``boto3<1.26.0``. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/amazon.aws/pull/1763). +- amazon.aws collection - due to the AWS SDKs announcing the end of support for Python less than 3.7 (https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/) support for Python less than 3.7 by this collection wss been deprecated in release 6.0.0 and removed in release 7.0.0. (https://github.com/ansible-collections/amazon.aws/pull/1763). +- module_utils - ``module_utils.urls`` was previously deprecated and has been removed (https://github.com/ansible-collections/amazon.aws/pull/1540). +- module_utils._version - vendored copy of distutils.version has been dropped (https://github.com/ansible-collections/amazon.aws/pull/1587). + +community.aws +~~~~~~~~~~~~~ + +- The community.aws collection has dropped support for ``botocore<1.29.0`` and ``boto3<1.26.0``. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/amazon.aws/pull/1763). +- aws_region_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.aws_region_info``. +- aws_s3_bucket_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.aws_s3_bucket_info``. +- community.aws collection - due to the AWS SDKs announcing the end of support for Python less than 3.7 (https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/) support for Python less than 3.7 by this collection wss been deprecated in release 6.0.0 and removed in release 7.0.0. (https://github.com/ansible-collections/amazon.aws/pull/1763). +- iam_access_key - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_access_key``. +- iam_access_key_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_access_key_info``. +- iam_group - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_group`` (https://github.com/ansible-collections/community.aws/pull/1945). +- iam_managed_policy - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_managed_policy`` (https://github.com/ansible-collections/community.aws/pull/1954). +- iam_mfa_device_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_mfa_device_info`` (https://github.com/ansible-collections/community.aws/pull/1953). +- iam_password_policy - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_password_policy``. +- iam_role - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_role`` (https://github.com/ansible-collections/community.aws/pull/1948). +- iam_role_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_role_info`` (https://github.com/ansible-collections/community.aws/pull/1948). +- s3_bucket_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.s3_bucket_info``. +- sts_assume_role - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.sts_assume_role``. + +community.general +~~~~~~~~~~~~~~~~~ + +- collection_version lookup plugin - remove compatibility code for ansible-base 2.10 and ansible-core 2.11 (https://github.com/ansible-collections/community.general/pull/7269). +- gitlab_project - add ``default_branch`` support for project update. If you used the module so far with ``default_branch`` to update a project, the value of ``default_branch`` was ignored. Make sure that you either do not pass a value if you are not sure whether it is the one you want to have to avoid unexpected breaking changes (https://github.com/ansible-collections/community.general/pull/7158). +- selective callback plugin - remove compatibility code for Ansible 2.9 and ansible-core 2.10 (https://github.com/ansible-collections/community.general/pull/7269). +- vardict module utils - ``VarDict`` will no longer accept variables named ``_var``, ``get_meta``, and ``as_dict`` (https://github.com/ansible-collections/community.general/pull/6647). +- version module util - remove fallback for ansible-core 2.11. All modules and plugins that do version collections no longer work with ansible-core 2.11 (https://github.com/ansible-collections/community.general/pull/7269). + +community.hashi_vault +~~~~~~~~~~~~~~~~~~~~~ + +- The minimum required version of ``hvac`` is now ``1.2.1`` (https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/docsite/user_guide.html#hvac-version-specifics). + +community.vmware +~~~~~~~~~~~~~~~~ + +- Removed support for ansible-core version < 2.15.0. +- vmware_dvs_host - removed defaults for `vmnics` and `lag_uplinks` (https://github.com/ansible-collections/community.vmware/issues/1516). +- vmware_host_acceptance - removed `acceptance_level` and used its options in `state`. This also means there will be no state `list` anymore. In order to get information about the current acceptance level, use the new module `vmware_host_acceptance_info` (https://github.com/ansible-collections/community.vmware/issues/1872). +- vmware_vm_info - added prefix length to IP addresses in vm_network, so they now show up as for example 10.76.33.228/24 instead of just 10.76.33.228 (https://github.com/ansible-collections/community.vmware/issues/1761). + +purestorage.flasharray +~~~~~~~~~~~~~~~~~~~~~~ + +- purefa_pgsched - Change `snap_at` and `replicate_at` to be AM or PM hourly number rather than 24-hour time. +- purefa_pgsnap - `now` and `remote` are now mutually exclusive. + +Major Changes +------------- + +amazon.aws +~~~~~~~~~~ + +- aws_region_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.aws_region_info``. +- aws_s3_bucket_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.aws_s3_bucket_info``. +- iam_access_key - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_access_key``. +- iam_access_key_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_access_key_info``. +- iam_group - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_group`` (https://github.com/ansible-collections/amazon.aws/pull/1755). +- iam_managed_policy - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_managed_policy`` (https://github.com/ansible-collections/amazon.aws/pull/1762). +- iam_mfa_device_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_mfa_device_info`` (https://github.com/ansible-collections/amazon.aws/pull/1761). +- iam_password_policy - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_password_policy``. +- iam_role - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_role`` (https://github.com/ansible-collections/amazon.aws/pull/1760). +- iam_role_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_role_info`` (https://github.com/ansible-collections/amazon.aws/pull/1760). +- s3_bucket_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.s3_bucket_info``. +- sts_assume_role - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.sts_assume_role``. + +community.mysql +~~~~~~~~~~~~~~~ + +- The community.mysql collection no longer supports ``ansible-core 2.12`` and ``ansible-core 2.13``. While we take no active measures to prevent usage and there are no plans to introduce incompatible code to the modules, we will stop testing those versions. Both are or will soon be End of Life and if you are still using them, you should consider upgrading to the ``latest Ansible / ansible-core 2.15 or later`` as soon as possible (https://github.com/ansible-collections/community.mysql/pull/574). +- mysql_role - the ``column_case_sensitive`` argument's default value will be changed to ``true`` in community.mysql 4.0.0. If your playbook expected the column to be automatically uppercased for your roles privileges, you should set this to false explicitly (https://github.com/ansible-collections/community.mysql/issues/578). +- mysql_user - the ``column_case_sensitive`` argument's default value will be changed to ``true`` in community.mysql 4.0.0. If your playbook expected the column to be automatically uppercased for your users privileges, you should set this to false explicitly (https://github.com/ansible-collections/community.mysql/issues/577). + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Add new fortios version 7.4.1. +- Format the contents in the changelog.yml file. +- Update Ansible version from 2.9 to 2.14. +- Update Q&A with a resolution for Ansible Always Sending GET/PUT Requests as POST Requests. +- Update the requirement.txt file to specify the sphinx_rtd_theme==1.3.0 +- update the required Ansible version to 2.14.0 in the runtime.yml file. + +Removed Features +---------------- + +community.general +~~~~~~~~~~~~~~~~~ + +- The collection no longer supports ansible-core 2.11 and ansible-core 2.12. Parts of the collection might still work on these ansible-core versions, but others might not (https://github.com/ansible-collections/community.general/pull/7269). +- ansible_galaxy_install - support for Ansible 2.9 and ansible-base 2.10 has been removed (https://github.com/ansible-collections/community.general/pull/7358). +- consul - when ``state=absent``, the options ``script``, ``ttl``, ``tcp``, ``http``, and ``interval`` can no longer be specified (https://github.com/ansible-collections/community.general/pull/7358). +- gconftool2 - ``state=get`` has been removed. Use the module ``community.general.gconftool2_info`` instead (https://github.com/ansible-collections/community.general/pull/7358). +- gitlab_runner - remove the default value for the ``access_level`` option. To restore the previous behavior, explicitly set it to ``ref_protected`` (https://github.com/ansible-collections/community.general/pull/7358). +- htpasswd - removed code for passlib <1.6 (https://github.com/ansible-collections/community.general/pull/6901). +- manageiq_polices - ``state=list`` has been removed. Use the module ``community.general.manageiq_policies_info`` instead (https://github.com/ansible-collections/community.general/pull/7358). +- manageiq_tags - ``state=list`` has been removed. Use the module ``community.general.manageiq_tags_info`` instead (https://github.com/ansible-collections/community.general/pull/7358). +- mh.mixins.cmd module utils - the ``ArgFormat`` class has been removed (https://github.com/ansible-collections/community.general/pull/7358). +- mh.mixins.cmd module utils - the ``CmdMixin`` mixin has been removed. Use ``community.general.plugins.module_utils.cmd_runner.CmdRunner`` instead (https://github.com/ansible-collections/community.general/pull/7358). +- mh.mixins.cmd module utils - the mh.mixins.cmd module utils has been removed after all its contents were removed (https://github.com/ansible-collections/community.general/pull/7358). +- mh.module_helper module utils - the ``CmdModuleHelper`` and ``CmdStateModuleHelper`` classes have been removed. Use ``community.general.plugins.module_utils.cmd_runner.CmdRunner`` instead (https://github.com/ansible-collections/community.general/pull/7358). +- proxmox module utils - removed unused imports (https://github.com/ansible-collections/community.general/pull/6873). +- xfconf - the deprecated ``disable_facts`` option was removed (https://github.com/ansible-collections/community.general/pull/7358). + +community.hashi_vault +~~~~~~~~~~~~~~~~~~~~~ + +- The minimum supported version of ``ansible-core`` is now ``2.14``, support for ``2.13`` has been dropped (https://github.com/ansible-collections/community.hashi_vault/pull/403). + +community.vmware +~~~~~~~~~~~~~~~~ + +- Removed module util `version` (https://github.com/ansible-collections/community.vmware/issues/1639). +- vmware_guest - removed specifying CDROM configuration as a dict, instead use a list (https://github.com/ansible-collections/community.vmware/issues/1472). +- vmware_host_lockdown - removed deprecated states `absent` and `present` (https://github.com/ansible-collections/community.vmware/issues/1517). +- vmware_rest_client - removed deprecated method `get_tag_by_category()` (https://github.com/ansible-collections/community.vmware/issues/1898). + +Deprecated Features +------------------- + +- The collection ``ibm.spectrum_virtualize`` has been renamed to ``ibm.storage_virtualize``. For now, both collections are included in Ansible. The content in ``ibm.spectrum_virtualize`` will be replaced with deprecated redirects to the new collection in Ansible 10.0.0, and these redirects will eventually be removed from Ansible. Please update your FQCNs for ``ibm.spectrum_virtualize``. + +amazon.aws +~~~~~~~~~~ + +- ec2_instance - deprecation of ``tenancy`` and ``placement_group`` in favor of ``placement`` attribute (https://github.com/ansible-collections/amazon.aws/pull/1825). + +cisco.ios +~~~~~~~~~ + +- ios_snmp_server - deprecate traps.envmon.fan with traps.envmon.fan_enable +- ios_snmp_server - deprecate traps.mpls_vpn with traps.mpls + +community.general +~~~~~~~~~~~~~~~~~ + +- CmdRunner module utils - deprecate ``cmd_runner_fmt.as_default_type()`` formatter (https://github.com/ansible-collections/community.general/pull/6601). +- MH VarsMixin module utils - deprecates ``VarsMixin`` and supporting classes in favor of plain ``vardict`` module util (https://github.com/ansible-collections/community.general/pull/6649). +- ansible_galaxy_install - the ``ack_ansible29`` and ``ack_min_ansiblecore211`` options have been deprecated and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/7358). +- consul - the ``ack_params_state_absent`` option has been deprecated and will be removed in community.general 10.0.0 (https://github.com/ansible-collections/community.general/pull/7358). +- cpanm - value ``compatibility`` is deprecated as default for parameter ``mode`` (https://github.com/ansible-collections/community.general/pull/6512). +- ejabberd_user - deprecate the parameter ``logging`` in favour of producing more detailed information in the module output (https://github.com/ansible-collections/community.general/pull/7043). +- flowdock - module relies entirely on no longer responsive API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6930). +- proxmox - old feature flag ``proxmox_default_behavior`` will be removed in community.general 10.0.0 (https://github.com/ansible-collections/community.general/pull/6836). +- proxmox_kvm - deprecate the option ``proxmox_default_behavior`` (https://github.com/ansible-collections/community.general/pull/7377). +- redfish_info, redfish_config, redfish_command - the default value ``10`` for the ``timeout`` option is deprecated and will change to ``60`` in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/7295). +- redhat module utils - the ``module_utils.redhat`` module is deprecated, as + effectively unused: the ``Rhsm``, ``RhsmPool``, and ``RhsmPools`` classes + will be removed in community.general 9.0.0; the ``RegistrationBase`` class + will be removed in community.general 10.0.0 together with the + ``rhn_register`` module, as it is the only user of this class; this means + that the whole ``module_utils.redhat`` module will be dropped in + community.general 10.0.0, so importing it without even using anything of it + will fail + (https://github.com/ansible-collections/community.general/pull/6663). +- redhat_subscription - the ``autosubscribe`` alias for the ``auto_attach`` option has been + deprecated for many years, although only in the documentation. Officially mark this alias + as deprecated, and it will be removed in community.general 9.0.0 + (https://github.com/ansible-collections/community.general/pull/6646). +- redhat_subscription - the ``pool`` option is deprecated in favour of the + more precise and flexible ``pool_ids`` option + (https://github.com/ansible-collections/community.general/pull/6650). +- rhsm_repository - ``state=present`` has not been working as expected for many years, + and it seems it was not noticed so far; also, "presence" is not really a valid concept + for subscription repositories, which can only be enabled or disabled. Hence, mark the + ``present`` and ``absent`` values of the ``state`` option as deprecated, slating them + for removal in community.general 10.0.0 + (https://github.com/ansible-collections/community.general/pull/6673). +- stackdriver - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6887). +- webfaction_app - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). +- webfaction_db - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). +- webfaction_domain - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). +- webfaction_mailbox - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). +- webfaction_site - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). + Porting Guide for v9.0.0a3 ========================== @@ -118,11 +330,6 @@ community.docker - Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/docker/. -community.general -~~~~~~~~~~~~~~~~~ - -- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/general/ (https://github.com/ansible-collections/community.general/pull/6539). - community.hrobot ~~~~~~~~~~~~~~~~ @@ -399,44 +606,6 @@ community.crypto - get_certificate - the default ``false`` of the ``asn1_base64`` option is deprecated and will change to ``true`` in community.crypto 3.0.0 (https://github.com/ansible-collections/community.crypto/pull/600). -community.general -~~~~~~~~~~~~~~~~~ - -- CmdRunner module utils - deprecate ``cmd_runner_fmt.as_default_type()`` formatter (https://github.com/ansible-collections/community.general/pull/6601). -- MH VarsMixin module utils - deprecates ``VarsMixin`` and supporting classes in favor of plain ``vardict`` module util (https://github.com/ansible-collections/community.general/pull/6649). -- cpanm - value ``compatibility`` is deprecated as default for parameter ``mode`` (https://github.com/ansible-collections/community.general/pull/6512). -- ejabberd_user - deprecate the parameter ``logging`` in favour of producing more detailed information in the module output (https://github.com/ansible-collections/community.general/pull/7043). -- flowdock - module relies entirely on no longer responsive API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6930). -- proxmox - old feature flag ``proxmox_default_behavior`` will be removed in community.general 10.0.0 (https://github.com/ansible-collections/community.general/pull/6836). -- redhat module utils - the ``module_utils.redhat`` module is deprecated, as - effectively unused: the ``Rhsm``, ``RhsmPool``, and ``RhsmPools`` classes - will be removed in community.general 9.0.0; the ``RegistrationBase`` class - will be removed in community.general 10.0.0 together with the - ``rhn_register`` module, as it is the only user of this class; this means - that the whole ``module_utils.redhat`` module will be dropped in - community.general 10.0.0, so importing it without even using anything of it - will fail - (https://github.com/ansible-collections/community.general/pull/6663). -- redhat_subscription - the ``autosubscribe`` alias for the ``auto_attach`` option has been - deprecated for many years, although only in the documentation. Officially mark this alias - as deprecated, and it will be removed in community.general 9.0.0 - (https://github.com/ansible-collections/community.general/pull/6646). -- redhat_subscription - the ``pool`` option is deprecated in favour of the - more precise and flexible ``pool_ids`` option - (https://github.com/ansible-collections/community.general/pull/6650). -- rhsm_repository - ``state=present`` has not been working as expected for many years, - and it seems it was not noticed so far; also, "presence" is not really a valid concept - for subscription repositories, which can only be enabled or disabled. Hence, mark the - ``present`` and ``absent`` values of the ``state`` option as deprecated, slating them - for removal in community.general 10.0.0 - (https://github.com/ansible-collections/community.general/pull/6673). -- stackdriver - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6887). -- webfaction_app - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). -- webfaction_db - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). -- webfaction_domain - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). -- webfaction_mailbox - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). -- webfaction_site - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). - community.postgresql ~~~~~~~~~~~~~~~~~~~~ From 2a485247619a9f6efaa71da2f259a48907f70d6c Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 7 Nov 2023 10:54:19 -0600 Subject: [PATCH 066/536] Add Ansible community 8.6.0 porting guide (#788) --- .../rst/porting_guides/porting_guide_8.rst | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_8.rst b/docs/docsite/rst/porting_guides/porting_guide_8.rst index 20a5b16b463..3facf8db378 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_8.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_8.rst @@ -94,6 +94,48 @@ Networking No notable changes +Porting Guide for v8.6.0 +======================== + +Added Collections +----------------- + +- ibm.storage_virtualize (version 2.1.0) + +Breaking Changes +---------------- + +purestorage.flasharray +~~~~~~~~~~~~~~~~~~~~~~ + +- purefa_pgsched - Change `snap_at` and `replicate_at` to be AM or PM hourly number rather than 24-hour time. +- purefa_pgsnap - `now` and `remote` are now mutually exclusive. + +Major Changes +------------- + +community.mysql +~~~~~~~~~~~~~~~ + +- The community.mysql collection no longer supports ``ansible-core 2.12`` and ``ansible-core 2.13``. While we take no active measures to prevent usage and there are no plans to introduce incompatible code to the modules, we will stop testing those versions. Both are or will soon be End of Life and if you are still using them, you should consider upgrading to the ``latest Ansible / ansible-core 2.15 or later`` as soon as possible (https://github.com/ansible-collections/community.mysql/pull/574). +- mysql_role - the ``column_case_sensitive`` argument's default value will be changed to ``true`` in community.mysql 4.0.0. If your playbook expected the column to be automatically uppercased for your roles privileges, you should set this to false explicitly (https://github.com/ansible-collections/community.mysql/issues/578). +- mysql_user - the ``column_case_sensitive`` argument's default value will be changed to ``true`` in community.mysql 4.0.0. If your playbook expected the column to be automatically uppercased for your users privileges, you should set this to false explicitly (https://github.com/ansible-collections/community.mysql/issues/577). + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Add new fortios version 7.4.1. +- Format the contents in the changelog.yml file. +- Update Ansible version from 2.9 to 2.14. +- Update Q&A with a resolution for Ansible Always Sending GET/PUT Requests as POST Requests. +- Update the requirement.txt file to specify the sphinx_rtd_theme==1.3.0 +- update the required Ansible version to 2.14.0 in the runtime.yml file. + +Deprecated Features +------------------- + +- The collection ``ibm.spectrum_virtualize`` has been renamed to ``ibm.storage_virtualize``. For now, both collections are included in Ansible. The content in ``ibm.spectrum_virtualize`` will be replaced with deprecated redirects to the new collection in Ansible 10.0.0, and these redirects will eventually be removed from Ansible. Please update your FQCNs for ``ibm.spectrum_virtualize``. + Porting Guide for v8.5.0 ======================== From 14b8cb7c60af2a7563299fc411ad63438f2bd1e4 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 7 Nov 2023 11:08:37 -0600 Subject: [PATCH 067/536] Rebuild Ansible 8.6.0 with purestorage.flasharray 1.21.0 (#789) --- docs/docsite/rst/porting_guides/porting_guide_8.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_8.rst b/docs/docsite/rst/porting_guides/porting_guide_8.rst index 3facf8db378..7be215c91a8 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_8.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_8.rst @@ -102,15 +102,6 @@ Added Collections - ibm.storage_virtualize (version 2.1.0) -Breaking Changes ----------------- - -purestorage.flasharray -~~~~~~~~~~~~~~~~~~~~~~ - -- purefa_pgsched - Change `snap_at` and `replicate_at` to be AM or PM hourly number rather than 24-hour time. -- purefa_pgsnap - `now` and `remote` are now mutually exclusive. - Major Changes ------------- From 8473c295cd89a904b2c27c83d78c4d6503ceae9c Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 9 Nov 2023 20:16:31 +0100 Subject: [PATCH 068/536] communication.rst: update Docs WG reference (#785) --- docs/docsite/rst/community/communication.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index ad353c4f97a..120f6481e56 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -142,7 +142,7 @@ Many of them meet in chat. If you want to get involved in a working group, join - `DigitalOcean Working Group `_ - Matrix: `#digitalocean:ansible.im `_ | IRC: ``#ansible-digitalocean`` - `Diversity Working Group `_ - Matrix: `#diversity:ansible.com `_ | IRC: ``#ansible-diversity`` - `Docker Working Group `_ - Matrix: `#devel:ansible.com `_ | IRC: ``#ansible-devel`` -- `Documentation Working Group `_ - Matrix: `#docs:ansible.com `_ | IRC: ``#ansible-docs`` +- `Documentation Working Group `_ - Matrix: `#docs:ansible.com `_ | IRC: ``#ansible-docs`` - `Galaxy Working Group `_ - Matrix: `#galaxy:ansible.com `_ | IRC: ``#ansible-galaxy`` - `JBoss Working Group `_ - Matrix: `#jboss:ansible.com `_ | IRC: ``#ansible-jboss`` - `Kubernetes Working Group `_ - Matrix: `#kubernetes:ansible.com `_ | IRC: ``#ansible-kubernetes`` From 9968f25462ae5cb1115946a4983903e5966f8001 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 9 Nov 2023 20:19:11 +0100 Subject: [PATCH 069/536] communication.rst: update MySQL WG to point to the forum group page (#795) --- docs/docsite/rst/community/communication.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 120f6481e56..e45502f6cba 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -148,7 +148,7 @@ Many of them meet in chat. If you want to get involved in a working group, join - `Kubernetes Working Group `_ - Matrix: `#kubernetes:ansible.com `_ | IRC: ``#ansible-kubernetes`` - `Linode Working Group `_ - Matrix: `#linode:ansible.com `_ | IRC: ``#ansible-linode`` - `Molecule Working Group `_ (`testing platform for Ansible playbooks and roles `_) - Matrix: `#molecule:ansible.im `_ | IRC: ``#ansible-molecule`` -- `MySQL Working Group `_ - Matrix: `#mysql:ansible.com `_ +- `MySQL Working Group `_ - Matrix: `#mysql:ansible.com `_ - `Network Working Group `_ - Matrix: `#network:ansible.com `_ | IRC: ``#ansible-network`` - `PostgreSQL Working Group `_ - Matrix: `#postgresql:ansible.com `_ - `Release Management Working Group `_ - Matrix: `#release-management:ansible.com `_ From a6132e60fc000ea86a8a8919e20daf89299040b0 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Fri, 10 Nov 2023 13:01:11 +0100 Subject: [PATCH 070/536] communication.rst: add EE group to the list of WGs (#784) --- docs/docsite/rst/community/communication.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index e45502f6cba..a654dc22f52 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -143,6 +143,7 @@ Many of them meet in chat. If you want to get involved in a working group, join - `Diversity Working Group `_ - Matrix: `#diversity:ansible.com `_ | IRC: ``#ansible-diversity`` - `Docker Working Group `_ - Matrix: `#devel:ansible.com `_ | IRC: ``#ansible-devel`` - `Documentation Working Group `_ - Matrix: `#docs:ansible.com `_ | IRC: ``#ansible-docs`` +- `Execution Environments Group `_ - `Galaxy Working Group `_ - Matrix: `#galaxy:ansible.com `_ | IRC: ``#ansible-galaxy`` - `JBoss Working Group `_ - Matrix: `#jboss:ansible.com `_ | IRC: ``#ansible-jboss`` - `Kubernetes Working Group `_ - Matrix: `#kubernetes:ansible.com `_ | IRC: ``#ansible-kubernetes`` From d85357f343e5c4de900b1623f60218db291782e5 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Fri, 10 Nov 2023 10:09:48 -0500 Subject: [PATCH 071/536] EOL 2.13 in release table (#798) --- .../rst/reference_appendices/release_and_maintenance.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 4c004376ee9..2f8dc7e4de9 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -190,7 +190,8 @@ Dates listed indicate the start date of the maintenance cycle. - | GA: 23 May 2022 | Critical: 07 Nov 2022 | Security: 22 May 2023 - - 06 Nov 2023 + - | **EOL** + | 06 Nov 2023 - | Python 3.8 - 3.10 - | Python 2.7 | Python 3.5 - 3.10 From 79c06a502930da66f85999a0c599053e43263dd8 Mon Sep 17 00:00:00 2001 From: Peter Shen Date: Fri, 10 Nov 2023 15:23:00 -0500 Subject: [PATCH 072/536] Update windows_setup.rst to fix link (#766) --- docs/docsite/rst/os_guide/windows_setup.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/os_guide/windows_setup.rst b/docs/docsite/rst/os_guide/windows_setup.rst index 36660c440b1..5e5cc95d925 100644 --- a/docs/docsite/rst/os_guide/windows_setup.rst +++ b/docs/docsite/rst/os_guide/windows_setup.rst @@ -16,7 +16,7 @@ Windows host must meet these base requirements for connectivity: * You need to install PowerShell 5.1 or newer and at least .NET 4.0 on the Windows host. -* You need to create and activate a WinRM listener. More details, see `WinRM Setup `_. +* You need to create and activate a WinRM listener. More details, see :ref:`winrm_listener`. .. Note:: Some Ansible modules have additional requirements, such as a newer OS or PowerShell version. Consult the module documentation page to determine whether a host meets those requirements. @@ -92,6 +92,8 @@ WinRM Setup ``````````` You need to configure the WinRM service so that Ansible can connect to it. There are two main components of the WinRM service that governs how Ansible can interface with the Windows host: the ``listener`` and the ``service`` configuration settings. +.. _winrm_listener: + WinRM Listener -------------- The WinRM services listen for requests on one or more ports. Each of these ports must have a listener created and configured. From 4e331d79583095a3d34e48f9739a9df4345ce776 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 12 Nov 2023 23:51:56 -0600 Subject: [PATCH 073/536] ci: refresh dev dependencies (#813) --- tests/formatters.txt | 4 ++-- tests/static.txt | 2 +- tests/typing.txt | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index ebcf05b9c50..18f8c1b047d 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==23.10.1 +black==23.11.0 # via -r tests/formatters.in click==8.1.7 # via black @@ -16,7 +16,7 @@ packaging==23.2 # via black pathspec==0.11.2 # via black -platformdirs==3.11.0 +platformdirs==4.0.0 # via black tomli==2.0.1 # via black diff --git a/tests/static.txt b/tests/static.txt index be223e23022..9b732abb9df 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.4 +ruff==0.1.5 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 078485655ff..05eb31d3593 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -34,7 +34,7 @@ jinja2==3.1.2 # via -r tests/../hacking/pr_labeler/requirements.txt markupsafe==2.1.3 # via jinja2 -mypy==1.6.1 +mypy==1.7.0 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy @@ -76,5 +76,5 @@ urllib3==2.0.7 # requests virtualenv==20.24.6 # via nox -wrapt==1.15.0 +wrapt==1.16.0 # via deprecated From 6893bb3c099f334e30ba9d96940676fd185b97a8 Mon Sep 17 00:00:00 2001 From: ildjarnisdead Date: Mon, 13 Nov 2023 16:58:27 +0100 Subject: [PATCH 074/536] Update developing_program_flow_modules.rst (#819) Typo depecated -> deprecated --- docs/docsite/rst/dev_guide/developing_program_flow_modules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst index 37af41d4b85..35c01ed8498 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -731,7 +731,7 @@ This section will discuss the behavioral attributes for arguments: option = { 'type': 'str', 'aliases': ['foo', 'bar'], - 'depecated_aliases': [ + 'deprecated_aliases': [ { 'name': 'foo', 'version': '2.0.0', From 2c5010c04e722b75751a67152bdc223451c2b138 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 14 Nov 2023 09:36:00 -0500 Subject: [PATCH 075/536] update galaxy urls for networking docs' (#822) --- .../rst/network/user_guide/platform_ce.rst | 2 +- .../rst/network/user_guide/platform_cnos.rst | 2 +- .../network/user_guide/platform_dellos10.rst | 2 +- .../rst/network/user_guide/platform_enos.rst | 2 +- .../rst/network/user_guide/platform_eos.rst | 2 +- .../user_guide/platform_eric_eccli.rst | 2 +- .../rst/network/user_guide/platform_exos.rst | 2 +- .../rst/network/user_guide/platform_frr.rst | 2 +- .../rst/network/user_guide/platform_icx.rst | 2 +- .../rst/network/user_guide/platform_index.rst | 52 +++++++++---------- .../rst/network/user_guide/platform_ios.rst | 2 +- .../rst/network/user_guide/platform_iosxr.rst | 2 +- .../network/user_guide/platform_ironware.rst | 2 +- .../rst/network/user_guide/platform_junos.rst | 2 +- .../network/user_guide/platform_meraki.rst | 2 +- .../network/user_guide/platform_netvisor.rst | 2 +- .../rst/network/user_guide/platform_nos.rst | 2 +- .../rst/network/user_guide/platform_nxos.rst | 2 +- .../network/user_guide/platform_routeros.rst | 2 +- .../rst/network/user_guide/platform_slxos.rst | 2 +- .../rst/network/user_guide/platform_voss.rst | 2 +- .../rst/network/user_guide/platform_vyos.rst | 2 +- .../rst/network/user_guide/platform_weos4.rst | 2 +- .../rst/network/user_guide/validate.rst | 4 +- 24 files changed, 50 insertions(+), 50 deletions(-) diff --git a/docs/docsite/rst/network/user_guide/platform_ce.rst b/docs/docsite/rst/network/user_guide/platform_ce.rst index 81637379b12..7d9b45766d7 100644 --- a/docs/docsite/rst/network/user_guide/platform_ce.rst +++ b/docs/docsite/rst/network/user_guide/platform_ce.rst @@ -4,7 +4,7 @@ CloudEngine OS Platform Options *************************************** -CloudEngine CE OS is part of the `community.network `_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. +CloudEngine CE OS is part of the `community.network `_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_cnos.rst b/docs/docsite/rst/network/user_guide/platform_cnos.rst index cb79c7dac26..85cdeb1d22b 100644 --- a/docs/docsite/rst/network/user_guide/platform_cnos.rst +++ b/docs/docsite/rst/network/user_guide/platform_cnos.rst @@ -4,7 +4,7 @@ CNOS Platform Options *************************************** -CNOS is part of the `community.network `_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible. +CNOS is part of the `community.network `_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_dellos10.rst b/docs/docsite/rst/network/user_guide/platform_dellos10.rst index 35686b9b7c8..68e7010fc8e 100644 --- a/docs/docsite/rst/network/user_guide/platform_dellos10.rst +++ b/docs/docsite/rst/network/user_guide/platform_dellos10.rst @@ -4,7 +4,7 @@ Dell OS10 Platform Options *************************************** -The `dellemc.os10 `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS10 in Ansible. +The `dellemc.os10 `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on OS10 in Ansible. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_enos.rst b/docs/docsite/rst/network/user_guide/platform_enos.rst index 4ba9a761961..e85b4b348c0 100644 --- a/docs/docsite/rst/network/user_guide/platform_enos.rst +++ b/docs/docsite/rst/network/user_guide/platform_enos.rst @@ -4,7 +4,7 @@ ENOS Platform Options *************************************** -ENOS is part of the `community.network `_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ENOS in Ansible. +ENOS is part of the `community.network `_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ENOS in Ansible. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_eos.rst b/docs/docsite/rst/network/user_guide/platform_eos.rst index 296e0d4b876..3efc3dc4cef 100644 --- a/docs/docsite/rst/network/user_guide/platform_eos.rst +++ b/docs/docsite/rst/network/user_guide/platform_eos.rst @@ -4,7 +4,7 @@ EOS Platform Options *************************************** -The `Arista EOS `_ collection supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. +The `Arista EOS `_ collection supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst b/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst index 8e8bef0178c..05aa0386acb 100644 --- a/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst +++ b/docs/docsite/rst/network/user_guide/platform_eric_eccli.rst @@ -4,7 +4,7 @@ ERIC_ECCLI Platform Options *************************************** -Extreme ERIC_ECCLI is part of the `community.network `_ collection and only supports CLI connections today. This page offers details on how to use ``ansible.netcommon.network_cli`` on ERIC_ECCLI in Ansible. +Extreme ERIC_ECCLI is part of the `community.network `_ collection and only supports CLI connections today. This page offers details on how to use ``ansible.netcommon.network_cli`` on ERIC_ECCLI in Ansible. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_exos.rst b/docs/docsite/rst/network/user_guide/platform_exos.rst index 2e74be53f33..168906e2432 100644 --- a/docs/docsite/rst/network/user_guide/platform_exos.rst +++ b/docs/docsite/rst/network/user_guide/platform_exos.rst @@ -4,7 +4,7 @@ EXOS Platform Options *************************************** -Extreme EXOS is part of the `community.network `_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. +Extreme EXOS is part of the `community.network `_ collection and supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_frr.rst b/docs/docsite/rst/network/user_guide/platform_frr.rst index 026125098c5..d53a151a3f4 100644 --- a/docs/docsite/rst/network/user_guide/platform_frr.rst +++ b/docs/docsite/rst/network/user_guide/platform_frr.rst @@ -4,7 +4,7 @@ FRR Platform Options *************************************** -The `FRR `_ collection supports the ``ansible.netcommon.network_cli`` connection. This section provides details on how to use this connection for Free Range Routing (FRR). +The `FRR `_ collection supports the ``ansible.netcommon.network_cli`` connection. This section provides details on how to use this connection for Free Range Routing (FRR). .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_icx.rst b/docs/docsite/rst/network/user_guide/platform_icx.rst index 204312c5bce..e29bf41e78f 100644 --- a/docs/docsite/rst/network/user_guide/platform_icx.rst +++ b/docs/docsite/rst/network/user_guide/platform_icx.rst @@ -4,7 +4,7 @@ ICX Platform Options *************************************** -ICX is part of the `community.network `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ICX in Ansible. +ICX is part of the `community.network `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ICX in Ansible. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_index.rst b/docs/docsite/rst/network/user_guide/platform_index.rst index f9a8bc5f3c7..562aaf06f71 100644 --- a/docs/docsite/rst/network/user_guide/platform_index.rst +++ b/docs/docsite/rst/network/user_guide/platform_index.rst @@ -91,34 +91,34 @@ Settings by Platform OS that supports Netconf `[†]`_ ```` ✓ ✓ =============================== ================================ =========== ======= ======= =========== -.. _Arista EOS: https://galaxy.ansible.com/arista/eos -.. _Ciena SAOS6: https://galaxy.ansible.com/ciena/saos6 -.. _Cisco ASA: https://galaxy.ansible.com/cisco/asa -.. _Cisco IOS: https://galaxy.ansible.com/cisco/ios -.. _Cisco IOS XR: https://galaxy.ansible.com/cisco/iosxr -.. _Cisco NX-OS: https://galaxy.ansible.com/cisco/nxos -.. _Cloudengine OS: https://galaxy.ansible.com/community/network +.. _Arista EOS: https://galaxy.ansible.com/ui/repo/published/arista/eos +.. _Ciena SAOS6: https://galaxy.ansible.com/ui/repo/published/ciena/saos6 +.. _Cisco ASA: https://galaxy.ansible.com/ui/repo/published/cisco/asa +.. _Cisco IOS: https://galaxy.ansible.com/ui/repo/published/cisco/ios +.. _Cisco IOS XR: https://galaxy.ansible.com/ui/repo/published/cisco/iosxr +.. _Cisco NX-OS: https://galaxy.ansible.com/ui/repo/published/cisco/nxos +.. _Cloudengine OS: https://galaxy.ansible.com/ui/repo/published/community/network .. _Dell OS6: https://github.com/ansible-collections/dellemc.os6 .. _Dell OS9: https://github.com/ansible-collections/dellemc.os9 -.. _Dell OS10: https://galaxy.ansible.com/dellemc/os10 -.. _Ericsson ECCLI: https://galaxy.ansible.com/community/network -.. _Extreme EXOS: https://galaxy.ansible.com/community/network -.. _Extreme IronWare: https://galaxy.ansible.com/community/network -.. _Extreme NOS: https://galaxy.ansible.com/community/network -.. _Extreme SLX-OS: https://galaxy.ansible.com/community/network -.. _Extreme VOSS: https://galaxy.ansible.com/community/network -.. _F5 BIG-IP: https://galaxy.ansible.com/f5networks/f5_modules -.. _F5 BIG-IQ: https://galaxy.ansible.com/f5networks/f5_modules -.. _Junos OS: https://galaxy.ansible.com/junipernetworks/junos -.. _Lenovo CNOS: https://galaxy.ansible.com/community/network -.. _Lenovo ENOS: https://galaxy.ansible.com/community/network -.. _Meraki: https://galaxy.ansible.com/cisco/meraki -.. _MikroTik RouterOS: https://galaxy.ansible.com/community/network -.. _Nokia SR OS: https://galaxy.ansible.com/community/network -.. _Pluribus Netvisor: https://galaxy.ansible.com/community/network -.. _Ruckus ICX: https://galaxy.ansible.com/community/network -.. _VyOS: https://galaxy.ansible.com/vyos/vyos -.. _Westermo WeOS 4: https://galaxy.ansible.com/community/network +.. _Dell OS10: https://galaxy.ansible.com/ui/repo/published/dellemc/os10 +.. _Ericsson ECCLI: https://galaxy.ansible.com/ui/repo/published/community/network +.. _Extreme EXOS: https://galaxy.ansible.com/ui/repo/published/community/network +.. _Extreme IronWare: https://galaxy.ansible.com/ui/repo/published/community/network +.. _Extreme NOS: https://galaxy.ansible.com/ui/repo/published/community/network +.. _Extreme SLX-OS: https://galaxy.ansible.com/ui/repo/published/community/network +.. _Extreme VOSS: https://galaxy.ansible.com/ui/repo/published/community/network +.. _F5 BIG-IP: https://galaxy.ansible.com/ui/repo/published/f5networks/f5_modules +.. _F5 BIG-IQ: https://galaxy.ansible.com/ui/repo/published/f5networks/f5_modules +.. _Junos OS: https://galaxy.ansible.com/ui/repo/published/junipernetworks/junos +.. _Lenovo CNOS: https://galaxy.ansible.com/ui/repo/published/community/network +.. _Lenovo ENOS: https://galaxy.ansible.com/ui/repo/published/community/network +.. _Meraki: https://galaxy.ansible.com/ui/repo/published/cisco/meraki +.. _MikroTik RouterOS: https://galaxy.ansible.com/ui/repo/published/community/network +.. _Nokia SR OS: https://galaxy.ansible.com/ui/repo/published/community/network +.. _Pluribus Netvisor: https://galaxy.ansible.com/ui/repo/published/community/network +.. _Ruckus ICX: https://galaxy.ansible.com/ui/repo/published/community/network +.. _VyOS: https://galaxy.ansible.com/ui/repo/published/vyos/vyos +.. _Westermo WeOS 4: https://galaxy.ansible.com/ui/repo/published/community/network .. _`[†]`: **[†]** Maintained by Ansible Network Team diff --git a/docs/docsite/rst/network/user_guide/platform_ios.rst b/docs/docsite/rst/network/user_guide/platform_ios.rst index 70cf8c84ad1..2b4030fbbf3 100644 --- a/docs/docsite/rst/network/user_guide/platform_ios.rst +++ b/docs/docsite/rst/network/user_guide/platform_ios.rst @@ -4,7 +4,7 @@ IOS Platform Options *************************************** -The `Cisco IOS `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IOS in Ansible. +The `Cisco IOS `_ collection supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IOS in Ansible. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_iosxr.rst b/docs/docsite/rst/network/user_guide/platform_iosxr.rst index 1758f30fc9b..aa6a7900f48 100644 --- a/docs/docsite/rst/network/user_guide/platform_iosxr.rst +++ b/docs/docsite/rst/network/user_guide/platform_iosxr.rst @@ -4,7 +4,7 @@ IOS-XR Platform Options *************************************** -The `Cisco IOS-XR collection `_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. +The `Cisco IOS-XR collection `_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_ironware.rst b/docs/docsite/rst/network/user_guide/platform_ironware.rst index da1530bac16..2b2a53190d5 100644 --- a/docs/docsite/rst/network/user_guide/platform_ironware.rst +++ b/docs/docsite/rst/network/user_guide/platform_ironware.rst @@ -4,7 +4,7 @@ IronWare Platform Options *************************************** -IronWare is part of the `community.network `_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IronWare in Ansible. +IronWare is part of the `community.network `_ collection and supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on IronWare in Ansible. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_junos.rst b/docs/docsite/rst/network/user_guide/platform_junos.rst index 08cf8fc0d11..fc18846b49b 100644 --- a/docs/docsite/rst/network/user_guide/platform_junos.rst +++ b/docs/docsite/rst/network/user_guide/platform_junos.rst @@ -4,7 +4,7 @@ Junos OS Platform Options *************************************** -The `Juniper Junos OS `_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. +The `Juniper Junos OS `_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_meraki.rst b/docs/docsite/rst/network/user_guide/platform_meraki.rst index e51ca5b9120..9c1b25c84b8 100644 --- a/docs/docsite/rst/network/user_guide/platform_meraki.rst +++ b/docs/docsite/rst/network/user_guide/platform_meraki.rst @@ -4,7 +4,7 @@ Meraki Platform Options *************************************** -The `cisco.meraki `_ collection only supports the ``local`` connection type at this time. +The `cisco.meraki `_ collection only supports the ``local`` connection type at this time. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_netvisor.rst b/docs/docsite/rst/network/user_guide/platform_netvisor.rst index 648e9c1cad6..8e8841fb5fe 100644 --- a/docs/docsite/rst/network/user_guide/platform_netvisor.rst +++ b/docs/docsite/rst/network/user_guide/platform_netvisor.rst @@ -4,7 +4,7 @@ Pluribus NETVISOR Platform Options ********************************** -Pluribus NETVISOR Ansible is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +Pluribus NETVISOR Ansible is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. This page offers details on how to use ``ansible.netcommon.network_cli`` on NETVISOR in Ansible. .. contents:: diff --git a/docs/docsite/rst/network/user_guide/platform_nos.rst b/docs/docsite/rst/network/user_guide/platform_nos.rst index 6bc244c8d9b..26e14e3da40 100644 --- a/docs/docsite/rst/network/user_guide/platform_nos.rst +++ b/docs/docsite/rst/network/user_guide/platform_nos.rst @@ -4,7 +4,7 @@ NOS Platform Options *************************************** -Extreme NOS is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +Extreme NOS is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. This page offers details on how to use ``ansible.netcommon.network_cli`` on NOS in Ansible. .. contents:: diff --git a/docs/docsite/rst/network/user_guide/platform_nxos.rst b/docs/docsite/rst/network/user_guide/platform_nxos.rst index 73912389488..de461aea300 100644 --- a/docs/docsite/rst/network/user_guide/platform_nxos.rst +++ b/docs/docsite/rst/network/user_guide/platform_nxos.rst @@ -4,7 +4,7 @@ NXOS Platform Options *************************************** -The `Cisco NXOS `_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. +The `Cisco NXOS `_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_routeros.rst b/docs/docsite/rst/network/user_guide/platform_routeros.rst index 842ad4c424e..2db6c5ad1b8 100644 --- a/docs/docsite/rst/network/user_guide/platform_routeros.rst +++ b/docs/docsite/rst/network/user_guide/platform_routeros.rst @@ -4,7 +4,7 @@ RouterOS Platform Options *************************************** -RouterOS is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +RouterOS is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. This page offers details on how to use ``ansible.netcommon.network_cli`` on RouterOS in Ansible. .. contents:: diff --git a/docs/docsite/rst/network/user_guide/platform_slxos.rst b/docs/docsite/rst/network/user_guide/platform_slxos.rst index 4c4145130ca..2e36853b9db 100644 --- a/docs/docsite/rst/network/user_guide/platform_slxos.rst +++ b/docs/docsite/rst/network/user_guide/platform_slxos.rst @@ -4,7 +4,7 @@ SLX-OS Platform Options *************************************** -Extreme SLX-OS is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +Extreme SLX-OS is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. This page offers details on how to use ``ansible.netcommon.network_cli`` on SLX-OS in Ansible. .. contents:: diff --git a/docs/docsite/rst/network/user_guide/platform_voss.rst b/docs/docsite/rst/network/user_guide/platform_voss.rst index a66e42e65bb..b0a93b9cc89 100644 --- a/docs/docsite/rst/network/user_guide/platform_voss.rst +++ b/docs/docsite/rst/network/user_guide/platform_voss.rst @@ -4,7 +4,7 @@ VOSS Platform Options *************************************** -Extreme VOSS is part of the `community.network `_ collection and only supports CLI connections today. This page offers details on how to +Extreme VOSS is part of the `community.network `_ collection and only supports CLI connections today. This page offers details on how to use ``ansible.netcommon.network_cli`` on VOSS in Ansible. .. contents:: diff --git a/docs/docsite/rst/network/user_guide/platform_vyos.rst b/docs/docsite/rst/network/user_guide/platform_vyos.rst index f101fe778c5..f8ef7aa2ac5 100644 --- a/docs/docsite/rst/network/user_guide/platform_vyos.rst +++ b/docs/docsite/rst/network/user_guide/platform_vyos.rst @@ -4,7 +4,7 @@ VyOS Platform Options *************************************** -The `VyOS `_ collection supports the ``ansible.netcommon.network_cli`` connection type. This page offers details on connection options to manage VyOS using Ansible. +The `VyOS `_ collection supports the ``ansible.netcommon.network_cli`` connection type. This page offers details on connection options to manage VyOS using Ansible. .. contents:: :local: diff --git a/docs/docsite/rst/network/user_guide/platform_weos4.rst b/docs/docsite/rst/network/user_guide/platform_weos4.rst index dd5dc83290d..46890365226 100644 --- a/docs/docsite/rst/network/user_guide/platform_weos4.rst +++ b/docs/docsite/rst/network/user_guide/platform_weos4.rst @@ -4,7 +4,7 @@ WeOS 4 Platform Options *************************************** -Westermo WeOS 4 is part of the `community.network `_ collection and only supports CLI connections. +Westermo WeOS 4 is part of the `community.network `_ collection and only supports CLI connections. This page offers details on how to use ``ansible.netcommon.network_cli`` on WeOS 4 in Ansible. .. contents:: diff --git a/docs/docsite/rst/network/user_guide/validate.rst b/docs/docsite/rst/network/user_guide/validate.rst index 061819c0a82..37f79c6ab49 100644 --- a/docs/docsite/rst/network/user_guide/validate.rst +++ b/docs/docsite/rst/network/user_guide/validate.rst @@ -13,7 +13,7 @@ The :ansplugin:`validate ` module validates data Understanding the validate plugin ================================== -The `ansible.utils `_ collection includes the :ansplugin:`validate ` module. +The `ansible.utils `_ collection includes the :ansplugin:`validate ` module. To validate data: @@ -21,7 +21,7 @@ To validate data: #. Define the criteria to test that data against. #. Select a validation engine and test the data to see if it is valid based on the selected criteria and validation engine. -The structure of the data and the criteria depends on the validation engine you select. The examples here use the ``jsonschema`` validation engine provided in the `ansible.utils `_ collection.Red Hat Ansible Automation Platform subscription supports limited use if jsonschema public APIs as documented. +The structure of the data and the criteria depends on the validation engine you select. The examples here use the ``jsonschema`` validation engine provided in the `ansible.utils `_ collection.Red Hat Ansible Automation Platform subscription supports limited use if jsonschema public APIs as documented. Structuring the data ===================== From 2dad5161ddd957132220cf99815912b90137cc2a Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 14 Nov 2023 17:13:50 -0500 Subject: [PATCH 076/536] add ansible-galaxy to command cheatsheet --- docs/docsite/rst/command_guide/cheatsheet.rst | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 64380cebe6e..22c9db29ff0 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -31,3 +31,26 @@ Loads ``my_playbook.yml`` from the current working directory and: See :ref:`ansible-playbook` for detailed documentation. + +ansible-galaxy +============== + +Installing a collection: + +.. code-block:: bash + + ansible-galaxy collection install mynamespace.mycollection -p /path/to/collections --force-all-deps + +Downloads ``mynamespace.mycollection`` from the configured Galaxy server (``_ by default) and : + - ``-p`` - installs the collection to `/path/to/collections` (``~/.ansible/collections`` by default if this flag is not included). + - ``--force-with-deps`` - overwrites any existing collection and dependencies. + + +Listing all installed collections: + +.. code-block:: bash + + ansible-galaxy collection list + +See :ref:`ansible-galaxy` for detailed documentation. + From 09ac296b5f8400762cb9ad6db1b0fd7c580549e4 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 15 Nov 2023 20:31:55 +0100 Subject: [PATCH 077/536] communication.rst: remove inactive security WG (#828) --- docs/docsite/rst/community/communication.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index a654dc22f52..a4eebffd728 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -154,7 +154,6 @@ Many of them meet in chat. If you want to get involved in a working group, join - `PostgreSQL Working Group `_ - Matrix: `#postgresql:ansible.com `_ - `Release Management Working Group `_ - Matrix: `#release-management:ansible.com `_ - `Remote Management Working Group `_ - Matrix: `#devel:ansible.com `_ | IRC: ``#ansible-devel`` -- `Security Automation Working Group `_ - Matrix: `#security-automation:ansible.com `_ | IRC: ``#ansible-security`` - `Storage Working Group `_ - Matrix: `#storage:ansible.com `_ | IRC: ``#ansible-storage`` - `VMware Working Group `_ - Matrix: `#vmware:ansible.com `_ | IRC: ``#ansible-vmware`` - `Windows Working Group `_ - Matrix: `#windows:ansible.com `_ | IRC: ``#ansible-windows`` From 6093930f62be328c28ac3ba304f1f3a4b43a3d47 Mon Sep 17 00:00:00 2001 From: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> Date: Thu, 16 Nov 2023 14:57:55 -0500 Subject: [PATCH 078/536] Fix delegate_to details about inheriting vars from 'all' (#825) Co-authored-by: Abhijeet Kasurde --- docs/docsite/rst/playbook_guide/playbooks_delegation.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_delegation.rst b/docs/docsite/rst/playbook_guide/playbooks_delegation.rst index ae708bf3ec1..f4bae2d2e24 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_delegation.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_delegation.rst @@ -88,11 +88,12 @@ To specify more arguments, use the following syntax: run_once: True .. note:: - - The `ansible_host` variable and other connection variables, if present, reflects information about the host a task is delegated to, not the inventory_hostname. + - The ``ansible_host`` variable and other connection variables, if present, reflects information about the host a task is delegated to, not the inventory_hostname. + - The host to which a task is delegated does not inherit variables from the host that is delegating the task. .. warning:: - Although you can ``delegate_to`` a host that does not exist in inventory (by adding an IP address, DNS name or whatever requirement the connection plugin has), doing so does not add the host to your inventory and might cause issues. Hosts delegated to in this way do not inherit variables from the "all" group', so variables like connection user and key are missing. If you must ``delegate_to`` a non-inventory host, use the :ref:`add host module `. + Although you can ``delegate_to`` a host that does not exist in inventory (by adding an IP address, DNS name or whatever requirement the connection plugin has), doing so does not add the host to your inventory and might cause issues. Hosts delegated to in this way do inherit variables from the "all" group (assuming :ref:`VARIABLE_PRECEDENCE` includes ``all_inventory``). If you must ``delegate_to`` a non-inventory host, use the :ref:`add host module `. .. _delegate_templating: From cb0d590c60838fc3f9d7f1af9195168633d86478 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 16 Nov 2023 21:07:53 +0100 Subject: [PATCH 079/536] developing_collections.rst: add collection creator path (#775) Co-authored-by: Sandra McCann --- docs/docsite/rst/dev_guide/ansible_index.rst | 2 + docs/docsite/rst/dev_guide/core_index.rst | 2 + .../rst/dev_guide/developing_collections.rst | 2 + .../dev_guide/developing_collections_path.rst | 154 ++++++++++++++++++ 4 files changed, 160 insertions(+) create mode 100644 docs/docsite/rst/dev_guide/developing_collections_path.rst diff --git a/docs/docsite/rst/dev_guide/ansible_index.rst b/docs/docsite/rst/dev_guide/ansible_index.rst index a660df06e57..0ec3f1a456b 100644 --- a/docs/docsite/rst/dev_guide/ansible_index.rst +++ b/docs/docsite/rst/dev_guide/ansible_index.rst @@ -22,6 +22,7 @@ Find the task that best describes what you want to do: * I want to :ref:`add a custom plugin or module locally `. * I want to figure out if :ref:`developing a module is the right approach ` for my use case. + * I want to understand :ref:`what a successful collection creator path looks like `. * I want to :ref:`develop a collection `. * I want to :ref:`contribute to an Ansible-maintained collection `. * I want to :ref:`contribute to a community-maintained collection `. @@ -86,6 +87,7 @@ If you prefer to read the entire guide, here's a list of the pages in order. developing_api developing_rebasing developing_module_utilities + developing_collections_path developing_collections migrating_roles collections_galaxy_meta diff --git a/docs/docsite/rst/dev_guide/core_index.rst b/docs/docsite/rst/dev_guide/core_index.rst index 3c2fdb73d46..2bd630e3d51 100644 --- a/docs/docsite/rst/dev_guide/core_index.rst +++ b/docs/docsite/rst/dev_guide/core_index.rst @@ -22,6 +22,7 @@ Find the task that best describes what you want to do: * I want to :ref:`add a custom plugin or module locally `. * I want to figure out if :ref:`developing a module is the right approach ` for my use case. + * I want to understand :ref:`what a successful collection creator path looks like `. * I want to :ref:`develop a collection `. * I want to :ref:`contribute to an Ansible-maintained collection `. * I want to :ref:`contribute to a community-maintained collection `. @@ -83,6 +84,7 @@ If you prefer to read the entire guide, here's a list of the pages in order. developing_api developing_rebasing developing_module_utilities + developing_collections_path developing_collections migrating_roles collections_galaxy_meta diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index d3fb4f7fcad..b507cd3ef1b 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -8,6 +8,8 @@ Collections are a distribution format for Ansible content. You can package and d You can create a collection and publish it to `Ansible Galaxy `_ or to a private Automation Hub instance. You can publish certified collections to the Red Hat Automation Hub, part of the Red Hat Ansible Automation Platform. +Examine the :ref:`developing_collections_path` to understand how to go from creating a collection to having it included in the Ansible package distribution. + .. toctree:: :maxdepth: 2 :caption: Developing new collections diff --git a/docs/docsite/rst/dev_guide/developing_collections_path.rst b/docs/docsite/rst/dev_guide/developing_collections_path.rst new file mode 100644 index 00000000000..bb95840c956 --- /dev/null +++ b/docs/docsite/rst/dev_guide/developing_collections_path.rst @@ -0,0 +1,154 @@ +.. _developing_collections_path: + +******************************* +Ansible collection creator path +******************************* + +.. note:: + + If you are unfamiliar with Ansible collections, first take a look at the :ref:`Using Ansible collections guide`. + +Ansible collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins. +A typical collection addresses a set of related use cases. For example, the ``community.dns`` collection includes modules and plugins to work with DNS. + +You can install collections made by others or share yours with the community through a distribution server such as `Ansible Galaxy `_. Certified collections can be published to the Red Hat Automation Hub, a part of the Red Hat Ansible Automation Platform. + +Creating and sharing collections is a great way of contributing to the Ansible project. + +The Ansible community package consists of ``ansible-core``, which, among other core components, includes the ``ansible.builtin`` collection maintained by the Core team, and a set of collections maintained by the community. + +The purpose of this guide is to give you as a (potential) content creator a consistent overview of the Ansible collection creator journey from an idea for the first module/role to having your collection included in the Ansible community package. The :ref:`Collection development guidelines section` provides references to more detailed aspects of this journey. +The overall journey consists of the following milestones: + +.. contents:: + :local: + +.. _examine_existing_content: + +Examine currently available solutions +===================================== + +If you have an idea for a new role or module/plugin, there is no need to reinvent the wheel if there is already a sufficient solution that solves your automation issue. + +Therefore, first examine the currently available content including: + +* :ref:`Ansible builtin modules and plugins ` +* :ref:`Ansible package collection index` +* `Ansible Galaxy `_ +* `Ansible Automation Hub `_ if you have the Ansible Automation Platform subscription + +In case the solutions you found are not fully sufficient or have flaws, consider improving them rather than creating your own. Each collection includes information on where to create issues for that collection to propose your enhancement ideas. + +If you already have your content written and used in your workflows, you can still consider integrating it to the existing solutions. +However, if these options do not apply to your collection ideas, we encourage you to create and share your own. + +.. _create_content: + +Create your content +=================== + +You :ref:`tried ` but have not found any sufficient solution for your automation issue. + +Use one of the following guides: + +* :ref:`Roles guide`: if you want to create a role. +* :ref:`Developer guide`: if you want to create a new Ansible module or plugin for your personal use. + +Put your content in a collection +================================ + +You :ref:`created ` new content. + +Now it is time to create a reusable and sharable collection. +Use the :ref:`Developing collections guide` to learn how. + +We recommend you to use the `collection_template repository `_ as a basis for your collection. + +Write good user collection documentation +======================================== + +Your collection``README.md`` file should contain a quick-start installation and usage guides. +You can use the `community.general collection README file `_ as an example. + +If your collection contains modules or plugins, make sure their documentation is comprehensive. +Use the :ref:`Module format and documentation guide` and :ref:`Ansible documentation style guide` to learn more. + +Publish your collection source code +=================================== + +Publish your collection on a platform for software development and version control such as `GitHub `_. + +It can be your personal repository or your organization's one. +You can also `request `_ a repository under the `ansible-collections `_ organization. + +Make sure your collection contains exhaustive license information. +Ansible is an open source project, so we encourage you to license it under one of open source licenses. +If you plan to submit your collection for inclusion in the Ansible community package, your collection must satisfy the :ref:`licensing requirements`. + +If you have used the `collection_template repository `_ we recommended earlier as a skeleton for your collection, it already contains the ``GNU GPL v3`` license. + +Follow a versioning convention +============================== + +When releasing new versions of your collections, take the following recommended practices into consideration: + +* Follow a versioning convention. Using `SemVer `_ is highly recommended. +* Base your releases on `Git tags `_. + +Understand and implement testing and CI +======================================= + +This section is applicable to collections containing modules and plugins. + +For role testing, see the `Ansible Molecule `_ project. + +Add tests +--------- + +Testing your collection ensures that your code works well and integrates with other components such as ``ansible-core``. + +Take a look at the following documents: + +* :ref:`Testing Ansible guide`: provides general information about testing. +* :ref:`Testing collections guide`: contains collection-specific testing information. + +Implement continuous integration +-------------------------------- + +Now make sure when pull requests are created in your collection repository they are automatically tested using a CI tool such as GitHub Actions or Azure Pipelines. + +The `collection_template repository `_ contains GitHub Actions `templates `_ you can adjust and use to enable the workflows in your repository. + +Provide good contributor & maintainer documentation +=================================================== + +See the `collection_template/README.md `_ as an example. + +Publish your collection on distribution servers +=============================================== + +To distribute your collection and allow others to conveniently use it, publish your collection on one or more distribution servers. +See the :ref:`Distributing collections guide` to learn how. + +Make your collection a part of Ansible community package +======================================================== + +Make you collection satisfy the :ref:`Ansible community package collections requirements` and submit it for inclusion. +See the `inclusion process description `_ to learn how. + +Maintain +======== + +Maintain your collection. +See the :ref:`Ansible collection maintainer guidelines` for details. + +Communicate +=========== + +Engage with the community. +Take a look at the :ref:`Ansible communication guide` to see available communication options. + +.. seealso:: + + :ref:`developing_collections` + A set of guidelines about collection development aspects From c9406a8362ea059a4e61797337a2f80cb71048fa Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 16 Nov 2023 15:35:22 -0500 Subject: [PATCH 080/536] Update docs/docsite/rst/command_guide/cheatsheet.rst --- docs/docsite/rst/command_guide/cheatsheet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 22c9db29ff0..f9110d85228 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -39,7 +39,7 @@ Installing a collection: .. code-block:: bash - ansible-galaxy collection install mynamespace.mycollection -p /path/to/collections --force-all-deps + ansible-galaxy collection install mynamespace.mycollection Downloads ``mynamespace.mycollection`` from the configured Galaxy server (``_ by default) and : - ``-p`` - installs the collection to `/path/to/collections` (``~/.ansible/collections`` by default if this flag is not included). From 27c8a4d9bcea95d951a50aa290e8869810827edf Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 16 Nov 2023 15:36:40 -0500 Subject: [PATCH 081/536] Apply suggestions from code review --- docs/docsite/rst/command_guide/cheatsheet.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index f9110d85228..5c9186c2f51 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -42,8 +42,6 @@ Installing a collection: ansible-galaxy collection install mynamespace.mycollection Downloads ``mynamespace.mycollection`` from the configured Galaxy server (``_ by default) and : - - ``-p`` - installs the collection to `/path/to/collections` (``~/.ansible/collections`` by default if this flag is not included). - - ``--force-with-deps`` - overwrites any existing collection and dependencies. Listing all installed collections: From 3027208426b19703dea74d2887d6a5f4fda97706 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 16 Nov 2023 15:37:31 -0500 Subject: [PATCH 082/536] Update docs/docsite/rst/command_guide/cheatsheet.rst --- docs/docsite/rst/command_guide/cheatsheet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 5c9186c2f51..9f4f3c395f2 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -41,7 +41,7 @@ Installing a collection: ansible-galaxy collection install mynamespace.mycollection -Downloads ``mynamespace.mycollection`` from the configured Galaxy server (``_ by default) and : +Downloads ``mynamespace.mycollection`` from the configured Galaxy server (``_ by default). Listing all installed collections: From 96c99cd391482de4162592845bbdf7e714acdcf0 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Fri, 17 Nov 2023 09:40:25 -0600 Subject: [PATCH 083/536] update python versions in installation guide --- docs/docsite/rst/installation_guide/intro_installation.rst | 6 +++--- .../rst/reference_appendices/release_and_maintenance.rst | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 73a3c7cc5b0..121efd6ad41 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -17,14 +17,14 @@ From the control node, Ansible can manage an entire fleet of machines and other Control node requirements ========================= -For your *control* node (the machine that runs Ansible), you can use nearly any UNIX-like machine with Python 3.9 or newer installed. This includes Red Hat, Debian, Ubuntu, macOS, BSDs, and Windows under a `Windows Subsystem for Linux (WSL) distribution `_. Windows without WSL is not natively supported as a control node; see `Matt Davis' blog post `_ for more information. +For your *control* node (the machine that runs Ansible), you can use nearly any UNIX-like machine with Python installed. This includes Red Hat, Debian, Ubuntu, macOS, BSDs, and Windows under a `Windows Subsystem for Linux (WSL) distribution `_. Windows without WSL is not natively supported as a control node; see `Matt Davis' blog post `_ for more information. .. _managed_node_requirements: Managed node requirements ========================= -The *managed* node (the machine that Ansible is managing) does not require Ansible to be installed, but requires Python 2.7, or Python 3.5 - 3.11 to run Ansible-generated Python code. +The *managed* node (the machine that Ansible is managing) does not require Ansible to be installed, but requires Python to run Ansible-generated Python code. The managed node also needs a user account that can connect through SSH to the node with an interactive POSIX shell. .. note:: @@ -36,7 +36,7 @@ The managed node also needs a user account that can connect through SSH to the n Node requirement summary ======================== -You can find details about control and managed node requirements for each Ansible version in the :ref:`support_life`. +You can find details about control and managed node requirements, including Python versions, for each Ansible version in the :ref:`support_life` and :ref:`target_node_python_support` sections. .. _getting_ansible: diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 2f8dc7e4de9..c25f2414d03 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -125,6 +125,8 @@ You can install ``ansible-core`` with ``pip``. See :ref:`intro_installation_guid Starting with ``ansible-core`` version 2.12, each release includes control node support for the three most recently released Python versions. +.. _target_node_python_support: + ``ansible-core`` target node Python support ------------------------------------------- From bd4c4a1e5cf038a06b1a574931121827fe2d0da8 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 21 Nov 2023 10:41:14 -0600 Subject: [PATCH 084/536] Add Ansible community 9.0.0 porting guide (#843) --- .../rst/porting_guides/porting_guide_9.rst | 375 ++++++++---------- 1 file changed, 158 insertions(+), 217 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index ea75e6b4535..823129417a9 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -64,28 +64,67 @@ Networking ========== -Porting Guide for v9.0.0b1 -========================== +Porting Guide for v9.0.0 +======================== Added Collections ----------------- - ibm.storage_virtualize (version 2.1.0) +- telekom_mms.icinga_director (version 1.34.1) Known Issues ------------ +Ansible-core +~~~~~~~~~~~~ + +- ansible-galaxy - dies in the middle of installing a role when that role contains Java inner classes (files with $ in the file name). This is by design, to exclude temporary or backup files. (https://github.com/ansible/ansible/pull/81553). +- ansible-test - The ``pep8`` sanity test is unable to detect f-string spacing issues (E201, E202) on Python 3.10 and 3.11. They are correctly detected under Python 3.12. See (https://github.com/PyCQA/pycodestyle/issues/1190). + +community.crypto +~~~~~~~~~~~~~~~~ + +- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/crypto/. + +community.dns +~~~~~~~~~~~~~ + +- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/dns/. + +community.docker +~~~~~~~~~~~~~~~~ + +- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/docker/. + community.general ~~~~~~~~~~~~~~~~~ - Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/general/ (https://github.com/ansible-collections/community.general/pull/6539). +community.hrobot +~~~~~~~~~~~~~~~~ + +- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/hrobot/. + +community.routeros +~~~~~~~~~~~~~~~~~~ + +- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/routeros/. + +community.sops +~~~~~~~~~~~~~~ + +- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/sops/. + dellemc.openmanage ~~~~~~~~~~~~~~~~~~ - ca_path missing - Issue(275740) - The roles idrac_attributes, redfish_storage_volume, and idrac_server_powerstate have a missing parameter ca_path. +- idrac_firmware - Issue(276335) - This module fails on the Python 3.11.x version with NFS shares. Use a different Python version or Share type. - idrac_firmware - Issue(279282) - idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. - idrac_network_attributes - Issue(279049) - If unsupported values are provided for the parameter ``ome_network_attributes``, then this module does not provide a correct error message. +- idrac_redfish_storage_controller - Issue(256164) - If incorrect value is provided for one of the attributes in the provided attribute list for controller configuration, then this module does not exit with error. - ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the following parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. - ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` - ome_device_quick_deploy - Issue(275231) - This module does not deploy a new configuration to a slot that has disabled IPv6. @@ -94,6 +133,13 @@ dellemc.openmanage Breaking Changes ---------------- +Ansible-core +~~~~~~~~~~~~ + +- Any plugin using the config system and the `cli` entry to use the `timeout` from the command line, will see the value change if the use had configured it in any of the lower precedence methods. If relying on this behaviour to consume the global/generic timeout from the DEFAULT_TIMEOUT constant, please consult the documentation on plugin configuration to add the overlaping entries. +- ansible-test - Test plugins that rely on containers no longer support reusing running containers. The previous behavior was an undocumented, untested feature. +- service module will not permanently configure variables/flags for openbsd when doing enable/disable operation anymore, this module was never meant to do this type of work, just to manage the service state itself. A rcctl_config or similar module should be created and used instead. + amazon.aws ~~~~~~~~~~ @@ -142,6 +188,19 @@ community.vmware - vmware_host_acceptance - removed `acceptance_level` and used its options in `state`. This also means there will be no state `list` anymore. In order to get information about the current acceptance level, use the new module `vmware_host_acceptance_info` (https://github.com/ansible-collections/community.vmware/issues/1872). - vmware_vm_info - added prefix length to IP addresses in vm_network, so they now show up as for example 10.76.33.228/24 instead of just 10.76.33.228 (https://github.com/ansible-collections/community.vmware/issues/1761). +dellemc.enterprise_sonic +~~~~~~~~~~~~~~~~~~~~~~~~ + +- sonic_aaa - Add default_auth attribute to the argspec to replace the deleted group and local attributes. This change allows for ordered login authentication. (https://github.com/ansible-collections/dellemc.enterprise_sonic/pull/195). + +hetzner.hcloud +~~~~~~~~~~~~~~ + +- Drop support for ansible-core 2.12 +- Drop support for python 3.7 +- hcloud-python 1.20.0 is now required for full compatibility +- inventory plugin - Don't set the server image variables (`image_id`, `image_os_flavor` and `image_name`) when the server image is not defined. + purestorage.flasharray ~~~~~~~~~~~~~~~~~~~~~~ @@ -167,221 +226,6 @@ amazon.aws - s3_bucket_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.s3_bucket_info``. - sts_assume_role - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.sts_assume_role``. -community.mysql -~~~~~~~~~~~~~~~ - -- The community.mysql collection no longer supports ``ansible-core 2.12`` and ``ansible-core 2.13``. While we take no active measures to prevent usage and there are no plans to introduce incompatible code to the modules, we will stop testing those versions. Both are or will soon be End of Life and if you are still using them, you should consider upgrading to the ``latest Ansible / ansible-core 2.15 or later`` as soon as possible (https://github.com/ansible-collections/community.mysql/pull/574). -- mysql_role - the ``column_case_sensitive`` argument's default value will be changed to ``true`` in community.mysql 4.0.0. If your playbook expected the column to be automatically uppercased for your roles privileges, you should set this to false explicitly (https://github.com/ansible-collections/community.mysql/issues/578). -- mysql_user - the ``column_case_sensitive`` argument's default value will be changed to ``true`` in community.mysql 4.0.0. If your playbook expected the column to be automatically uppercased for your users privileges, you should set this to false explicitly (https://github.com/ansible-collections/community.mysql/issues/577). - -fortinet.fortios -~~~~~~~~~~~~~~~~ - -- Add new fortios version 7.4.1. -- Format the contents in the changelog.yml file. -- Update Ansible version from 2.9 to 2.14. -- Update Q&A with a resolution for Ansible Always Sending GET/PUT Requests as POST Requests. -- Update the requirement.txt file to specify the sphinx_rtd_theme==1.3.0 -- update the required Ansible version to 2.14.0 in the runtime.yml file. - -Removed Features ----------------- - -community.general -~~~~~~~~~~~~~~~~~ - -- The collection no longer supports ansible-core 2.11 and ansible-core 2.12. Parts of the collection might still work on these ansible-core versions, but others might not (https://github.com/ansible-collections/community.general/pull/7269). -- ansible_galaxy_install - support for Ansible 2.9 and ansible-base 2.10 has been removed (https://github.com/ansible-collections/community.general/pull/7358). -- consul - when ``state=absent``, the options ``script``, ``ttl``, ``tcp``, ``http``, and ``interval`` can no longer be specified (https://github.com/ansible-collections/community.general/pull/7358). -- gconftool2 - ``state=get`` has been removed. Use the module ``community.general.gconftool2_info`` instead (https://github.com/ansible-collections/community.general/pull/7358). -- gitlab_runner - remove the default value for the ``access_level`` option. To restore the previous behavior, explicitly set it to ``ref_protected`` (https://github.com/ansible-collections/community.general/pull/7358). -- htpasswd - removed code for passlib <1.6 (https://github.com/ansible-collections/community.general/pull/6901). -- manageiq_polices - ``state=list`` has been removed. Use the module ``community.general.manageiq_policies_info`` instead (https://github.com/ansible-collections/community.general/pull/7358). -- manageiq_tags - ``state=list`` has been removed. Use the module ``community.general.manageiq_tags_info`` instead (https://github.com/ansible-collections/community.general/pull/7358). -- mh.mixins.cmd module utils - the ``ArgFormat`` class has been removed (https://github.com/ansible-collections/community.general/pull/7358). -- mh.mixins.cmd module utils - the ``CmdMixin`` mixin has been removed. Use ``community.general.plugins.module_utils.cmd_runner.CmdRunner`` instead (https://github.com/ansible-collections/community.general/pull/7358). -- mh.mixins.cmd module utils - the mh.mixins.cmd module utils has been removed after all its contents were removed (https://github.com/ansible-collections/community.general/pull/7358). -- mh.module_helper module utils - the ``CmdModuleHelper`` and ``CmdStateModuleHelper`` classes have been removed. Use ``community.general.plugins.module_utils.cmd_runner.CmdRunner`` instead (https://github.com/ansible-collections/community.general/pull/7358). -- proxmox module utils - removed unused imports (https://github.com/ansible-collections/community.general/pull/6873). -- xfconf - the deprecated ``disable_facts`` option was removed (https://github.com/ansible-collections/community.general/pull/7358). - -community.hashi_vault -~~~~~~~~~~~~~~~~~~~~~ - -- The minimum supported version of ``ansible-core`` is now ``2.14``, support for ``2.13`` has been dropped (https://github.com/ansible-collections/community.hashi_vault/pull/403). - -community.vmware -~~~~~~~~~~~~~~~~ - -- Removed module util `version` (https://github.com/ansible-collections/community.vmware/issues/1639). -- vmware_guest - removed specifying CDROM configuration as a dict, instead use a list (https://github.com/ansible-collections/community.vmware/issues/1472). -- vmware_host_lockdown - removed deprecated states `absent` and `present` (https://github.com/ansible-collections/community.vmware/issues/1517). -- vmware_rest_client - removed deprecated method `get_tag_by_category()` (https://github.com/ansible-collections/community.vmware/issues/1898). - -Deprecated Features -------------------- - -- The collection ``ibm.spectrum_virtualize`` has been renamed to ``ibm.storage_virtualize``. For now, both collections are included in Ansible. The content in ``ibm.spectrum_virtualize`` will be replaced with deprecated redirects to the new collection in Ansible 10.0.0, and these redirects will eventually be removed from Ansible. Please update your FQCNs for ``ibm.spectrum_virtualize``. - -amazon.aws -~~~~~~~~~~ - -- ec2_instance - deprecation of ``tenancy`` and ``placement_group`` in favor of ``placement`` attribute (https://github.com/ansible-collections/amazon.aws/pull/1825). - -cisco.ios -~~~~~~~~~ - -- ios_snmp_server - deprecate traps.envmon.fan with traps.envmon.fan_enable -- ios_snmp_server - deprecate traps.mpls_vpn with traps.mpls - -community.general -~~~~~~~~~~~~~~~~~ - -- CmdRunner module utils - deprecate ``cmd_runner_fmt.as_default_type()`` formatter (https://github.com/ansible-collections/community.general/pull/6601). -- MH VarsMixin module utils - deprecates ``VarsMixin`` and supporting classes in favor of plain ``vardict`` module util (https://github.com/ansible-collections/community.general/pull/6649). -- ansible_galaxy_install - the ``ack_ansible29`` and ``ack_min_ansiblecore211`` options have been deprecated and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/7358). -- consul - the ``ack_params_state_absent`` option has been deprecated and will be removed in community.general 10.0.0 (https://github.com/ansible-collections/community.general/pull/7358). -- cpanm - value ``compatibility`` is deprecated as default for parameter ``mode`` (https://github.com/ansible-collections/community.general/pull/6512). -- ejabberd_user - deprecate the parameter ``logging`` in favour of producing more detailed information in the module output (https://github.com/ansible-collections/community.general/pull/7043). -- flowdock - module relies entirely on no longer responsive API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6930). -- proxmox - old feature flag ``proxmox_default_behavior`` will be removed in community.general 10.0.0 (https://github.com/ansible-collections/community.general/pull/6836). -- proxmox_kvm - deprecate the option ``proxmox_default_behavior`` (https://github.com/ansible-collections/community.general/pull/7377). -- redfish_info, redfish_config, redfish_command - the default value ``10`` for the ``timeout`` option is deprecated and will change to ``60`` in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/7295). -- redhat module utils - the ``module_utils.redhat`` module is deprecated, as - effectively unused: the ``Rhsm``, ``RhsmPool``, and ``RhsmPools`` classes - will be removed in community.general 9.0.0; the ``RegistrationBase`` class - will be removed in community.general 10.0.0 together with the - ``rhn_register`` module, as it is the only user of this class; this means - that the whole ``module_utils.redhat`` module will be dropped in - community.general 10.0.0, so importing it without even using anything of it - will fail - (https://github.com/ansible-collections/community.general/pull/6663). -- redhat_subscription - the ``autosubscribe`` alias for the ``auto_attach`` option has been - deprecated for many years, although only in the documentation. Officially mark this alias - as deprecated, and it will be removed in community.general 9.0.0 - (https://github.com/ansible-collections/community.general/pull/6646). -- redhat_subscription - the ``pool`` option is deprecated in favour of the - more precise and flexible ``pool_ids`` option - (https://github.com/ansible-collections/community.general/pull/6650). -- rhsm_repository - ``state=present`` has not been working as expected for many years, - and it seems it was not noticed so far; also, "presence" is not really a valid concept - for subscription repositories, which can only be enabled or disabled. Hence, mark the - ``present`` and ``absent`` values of the ``state`` option as deprecated, slating them - for removal in community.general 10.0.0 - (https://github.com/ansible-collections/community.general/pull/6673). -- stackdriver - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6887). -- webfaction_app - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). -- webfaction_db - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). -- webfaction_domain - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). -- webfaction_mailbox - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). -- webfaction_site - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). - -Porting Guide for v9.0.0a3 -========================== - -Deprecated Features -------------------- - -Ansible-core -~~~~~~~~~~~~ - -- Old style vars plugins which use the entrypoints `get_host_vars` or `get_group_vars` are deprecated. The plugin should be updated to inherit from `BaseVarsPlugin` and define a `get_vars` method as the entrypoint. - -cisco.ios -~~~~~~~~~ - -- ospfv2 - removed passive_interface to passive_interfaces that supports a list of interfaces - -community.general -~~~~~~~~~~~~~~~~~ - -- The next major release, community.general 8.0.0, will drop support for ansible-core 2.11 and 2.12, which have been End of Life for some time now. This means that this collection no longer supports Python 2.6 on the target. Individual content might still work with unsupported ansible-core versions, but that can change at any time. Also please note that from now on, for every new major community.general release, we will drop support for all ansible-core versions that have been End of Life for more than a few weeks on the date of the major release (https://github.com/ansible-community/community-topics/discussions/271, https://github.com/ansible-collections/community.general/pull/7259). -- redfish_info, redfish_config, redfish_command - the default value ``10`` for the ``timeout`` option is deprecated and will change to ``60`` in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/7295). - -Porting Guide for v9.0.0a1 -========================== - -Added Collections ------------------ - -- telekom_mms.icinga_director (version 1.34.1) - -Known Issues ------------- - -Ansible-core -~~~~~~~~~~~~ - -- ansible-galaxy - dies in the middle of installing a role when that role contains Java inner classes (files with $ in the file name). This is by design, to exclude temporary or backup files. (https://github.com/ansible/ansible/pull/81553). -- ansible-test - The ``pep8`` sanity test is unable to detect f-string spacing issues (E201, E202) on Python 3.10 and 3.11. They are correctly detected under Python 3.12. See (https://github.com/PyCQA/pycodestyle/issues/1190). - -community.crypto -~~~~~~~~~~~~~~~~ - -- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/crypto/. - -community.dns -~~~~~~~~~~~~~ - -- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/dns/. - -community.docker -~~~~~~~~~~~~~~~~ - -- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/docker/. - -community.hrobot -~~~~~~~~~~~~~~~~ - -- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/hrobot/. - -community.routeros -~~~~~~~~~~~~~~~~~~ - -- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/routeros/. - -community.sops -~~~~~~~~~~~~~~ - -- Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/sops/. - -dellemc.openmanage -~~~~~~~~~~~~~~~~~~ - -- ca_path missing - Issue(275740) - The roles idrac_attributes, redfish_storage_volume, and idrac_server_powerstate have a missing parameter ca_path. -- idrac_firmware - Issue(276335) - This module fails on the Python 3.11.x version with NFS shares. Use a different Python version or Share type. -- idrac_redfish_storage_controller - Issue(256164) - If incorrect value is provided for one of the attributes in the provided attribute list for controller configuration, then this module does not exit with error. -- ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the following parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. -- ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` -- ome_device_quick_deploy - Issue(275231) - This module does not deploy a new configuration to a slot that has disabled IPv6. -- ome_smart_fabric_uplink - Issue(186024) - Despite the module supported by OpenManage Enterprise Modular, it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. - -Breaking Changes ----------------- - -Ansible-core -~~~~~~~~~~~~ - -- Any plugin using the config system and the `cli` entry to use the `timeout` from the command line, will see the value change if the use had configured it in any of the lower precedence methods. If relying on this behaviour to consume the global/generic timeout from the DEFAULT_TIMEOUT constant, please consult the documentation on plugin configuration to add the overlaping entries. -- ansible-test - Test plugins that rely on containers no longer support reusing running containers. The previous behavior was an undocumented, untested feature. -- service module will not permanently configure variables/flags for openbsd when doing enable/disable operation anymore, this module was never meant to do this type of work, just to manage the service state itself. A rcctl_config or similar module should be created and used instead. - -dellemc.enterprise_sonic -~~~~~~~~~~~~~~~~~~~~~~~~ - -- sonic_aaa - Add default_auth attribute to the argspec to replace the deleted group and local attributes. This change allows for ordered login authentication. (https://github.com/ansible-collections/dellemc.enterprise_sonic/pull/195). - -hetzner.hcloud -~~~~~~~~~~~~~~ - -- Drop support for ansible-core 2.12 -- Drop support for python 3.7 -- hcloud-python 1.20.0 is now required for full compatibility -- inventory plugin - Don't set the server image variables (`image_id`, `image_os_flavor` and `image_name`) when the server image is not defined. - -Major Changes -------------- - chocolatey.chocolatey ~~~~~~~~~~~~~~~~~~~~~ @@ -404,6 +248,13 @@ cloudscale_ch.cloud - Bump minimum required Ansible version to 2.13.0 +community.mysql +~~~~~~~~~~~~~~~ + +- The community.mysql collection no longer supports ``ansible-core 2.12`` and ``ansible-core 2.13``. While we take no active measures to prevent usage and there are no plans to introduce incompatible code to the modules, we will stop testing those versions. Both are or will soon be End of Life and if you are still using them, you should consider upgrading to the ``latest Ansible / ansible-core 2.15 or later`` as soon as possible (https://github.com/ansible-collections/community.mysql/pull/574). +- mysql_role - the ``column_case_sensitive`` argument's default value will be changed to ``true`` in community.mysql 4.0.0. If your playbook expected the column to be automatically uppercased for your roles privileges, you should set this to false explicitly (https://github.com/ansible-collections/community.mysql/issues/578). +- mysql_user - the ``column_case_sensitive`` argument's default value will be changed to ``true`` in community.mysql 4.0.0. If your playbook expected the column to be automatically uppercased for your users privileges, you should set this to false explicitly (https://github.com/ansible-collections/community.mysql/issues/577). + community.postgresql ~~~~~~~~~~~~~~~~~~~~ @@ -434,13 +285,19 @@ fortinet.fortimanager fortinet.fortios ~~~~~~~~~~~~~~~~ +- Add new fortios version 7.4.1. - Add readthedocs.yaml file. +- Format the contents in the changelog.yml file. - Improve the `no_log` feature in some modules; - Improve the document for adding notes and examples in Q&A for modules using Integer number as the mkey. - Improve the documentation and example for `seq_num` in `fortios_router_static`; - Improve the documentation for `member_path` in all the modules; - Support new FOS versions. +- Update Ansible version from 2.9 to 2.14. - Update Q&A regarding setting up FortiToken multi-factor authentication; +- Update Q&A with a resolution for Ansible Always Sending GET/PUT Requests as POST Requests. +- Update the requirement.txt file to specify the sphinx_rtd_theme==1.3.0 +- update the required Ansible version to 2.14.0 in the runtime.yml file. grafana.grafana ~~~~~~~~~~~~~~~ @@ -522,6 +379,37 @@ community.ciscosmb - remove testing for Python 2.6 nad 2.7 - remove testing for ansible 2.9 +community.general +~~~~~~~~~~~~~~~~~ + +- The collection no longer supports ansible-core 2.11 and ansible-core 2.12. Parts of the collection might still work on these ansible-core versions, but others might not (https://github.com/ansible-collections/community.general/pull/7269). +- ansible_galaxy_install - support for Ansible 2.9 and ansible-base 2.10 has been removed (https://github.com/ansible-collections/community.general/pull/7358). +- consul - when ``state=absent``, the options ``script``, ``ttl``, ``tcp``, ``http``, and ``interval`` can no longer be specified (https://github.com/ansible-collections/community.general/pull/7358). +- gconftool2 - ``state=get`` has been removed. Use the module ``community.general.gconftool2_info`` instead (https://github.com/ansible-collections/community.general/pull/7358). +- gitlab_runner - remove the default value for the ``access_level`` option. To restore the previous behavior, explicitly set it to ``ref_protected`` (https://github.com/ansible-collections/community.general/pull/7358). +- htpasswd - removed code for passlib <1.6 (https://github.com/ansible-collections/community.general/pull/6901). +- manageiq_polices - ``state=list`` has been removed. Use the module ``community.general.manageiq_policies_info`` instead (https://github.com/ansible-collections/community.general/pull/7358). +- manageiq_tags - ``state=list`` has been removed. Use the module ``community.general.manageiq_tags_info`` instead (https://github.com/ansible-collections/community.general/pull/7358). +- mh.mixins.cmd module utils - the ``ArgFormat`` class has been removed (https://github.com/ansible-collections/community.general/pull/7358). +- mh.mixins.cmd module utils - the ``CmdMixin`` mixin has been removed. Use ``community.general.plugins.module_utils.cmd_runner.CmdRunner`` instead (https://github.com/ansible-collections/community.general/pull/7358). +- mh.mixins.cmd module utils - the mh.mixins.cmd module utils has been removed after all its contents were removed (https://github.com/ansible-collections/community.general/pull/7358). +- mh.module_helper module utils - the ``CmdModuleHelper`` and ``CmdStateModuleHelper`` classes have been removed. Use ``community.general.plugins.module_utils.cmd_runner.CmdRunner`` instead (https://github.com/ansible-collections/community.general/pull/7358). +- proxmox module utils - removed unused imports (https://github.com/ansible-collections/community.general/pull/6873). +- xfconf - the deprecated ``disable_facts`` option was removed (https://github.com/ansible-collections/community.general/pull/7358). + +community.hashi_vault +~~~~~~~~~~~~~~~~~~~~~ + +- The minimum supported version of ``ansible-core`` is now ``2.14``, support for ``2.13`` has been dropped (https://github.com/ansible-collections/community.hashi_vault/pull/403). + +community.vmware +~~~~~~~~~~~~~~~~ + +- Removed module util `version` (https://github.com/ansible-collections/community.vmware/issues/1639). +- vmware_guest - removed specifying CDROM configuration as a dict, instead use a list (https://github.com/ansible-collections/community.vmware/issues/1472). +- vmware_host_lockdown - removed deprecated states `absent` and `present` (https://github.com/ansible-collections/community.vmware/issues/1517). +- vmware_rest_client - removed deprecated method `get_tag_by_category()` (https://github.com/ansible-collections/community.vmware/issues/1898). + community.windows ~~~~~~~~~~~~~~~~~ @@ -555,6 +443,7 @@ Deprecated Features - The ``community.azure`` collection is officially unmaintained and has been archived. Therefore, it will be removed from Ansible 10. There is already a successor collection ``azure.azcollection`` in the community package which should cover the same functionality (https://github.com/ansible-community/community-topics/issues/263). - The ``hpe.nimble`` collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/254). - The collection ``community.sap`` has been renamed to ``community.sap_libs``. For now both collections are included in Ansible. The content in ``community.sap`` has deprecated redirects to the new collection in Ansible 9.0.0, and the collection will be removed from Ansible 10 completely. Please update your FQCNs for ``community.sap``. +- The collection ``ibm.spectrum_virtualize`` has been renamed to ``ibm.storage_virtualize``. For now, both collections are included in Ansible. The content in ``ibm.spectrum_virtualize`` will be replaced with deprecated redirects to the new collection in Ansible 10.0.0, and these redirects will eventually be removed from Ansible. Please update your FQCNs for ``ibm.spectrum_virtualize``. - The collection ``t_systems_mms.icinga_director`` has been renamed to ``telekom_mms.icinga_director``. For now both collections are included in Ansible. The content in ``t_systems_mms.icinga_director`` has been replaced with deprecated redirects to the new collection in Ansible 9.0.0, and these redirects will be removed from Ansible 11. Please update your FQCNs for ``t_systems_mms.icinga_director``. - The netapp.azure collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/234). - The netapp.elementsw collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/235). @@ -565,6 +454,7 @@ Ansible-core - Deprecated ini config option ``collections_paths``, use the singular form ``collections_path`` instead - Deprecated the env var ``ANSIBLE_COLLECTIONS_PATHS``, use the singular form ``ANSIBLE_COLLECTIONS_PATH`` instead +- Old style vars plugins which use the entrypoints `get_host_vars` or `get_group_vars` are deprecated. The plugin should be updated to inherit from `BaseVarsPlugin` and define a `get_vars` method as the entrypoint. - Support for Windows Server 2012 and 2012 R2 has been removed as the support end of life from Microsoft is October 10th 2023. These versions of Windows will no longer be tested in this Ansible release and it cannot be guaranteed that they will continue to work going forward. - ``STRING_CONVERSION_ACTION`` config option is deprecated as it is no longer used in the Ansible Core code base. - the 'smart' option for setting a connection plugin is being removed as it's main purpose (choosing between ssh and paramiko) is now irrelevant. @@ -574,6 +464,7 @@ Ansible-core amazon.aws ~~~~~~~~~~ +- ec2_instance - deprecation of ``tenancy`` and ``placement_group`` in favor of ``placement`` attribute (https://github.com/ansible-collections/amazon.aws/pull/1825). - s3_object - support for passing object keys with a leading ``/`` has been deprecated and will be removed in a release after 2025-12-01 (https://github.com/ansible-collections/amazon.aws/pull/1549). ansible.netcommon @@ -589,6 +480,13 @@ ansible.windows - win_domain_controller - Module is deprecated in favour of the ``microsoft.ad.domain_controller`` module, the ``ansible.windows.win_domain_controller`` module will be removed in the ``3.0.0`` release of this collection. - win_domain_membership - Module is deprecated in favour of the ``microsoft.ad.membership`` module, the ``ansible.windows.win_domain_membership`` module will be removed in the ``3.0.0`` release of this collection. +cisco.ios +~~~~~~~~~ + +- ios_snmp_server - deprecate traps.envmon.fan with traps.envmon.fan_enable +- ios_snmp_server - deprecate traps.mpls_vpn with traps.mpls +- ospfv2 - removed passive_interface to passive_interfaces that supports a list of interfaces + cisco.iosxr ~~~~~~~~~~~ @@ -606,6 +504,49 @@ community.crypto - get_certificate - the default ``false`` of the ``asn1_base64`` option is deprecated and will change to ``true`` in community.crypto 3.0.0 (https://github.com/ansible-collections/community.crypto/pull/600). +community.general +~~~~~~~~~~~~~~~~~ + +- CmdRunner module utils - deprecate ``cmd_runner_fmt.as_default_type()`` formatter (https://github.com/ansible-collections/community.general/pull/6601). +- MH VarsMixin module utils - deprecates ``VarsMixin`` and supporting classes in favor of plain ``vardict`` module util (https://github.com/ansible-collections/community.general/pull/6649). +- The next major release, community.general 8.0.0, will drop support for ansible-core 2.11 and 2.12, which have been End of Life for some time now. This means that this collection no longer supports Python 2.6 on the target. Individual content might still work with unsupported ansible-core versions, but that can change at any time. Also please note that from now on, for every new major community.general release, we will drop support for all ansible-core versions that have been End of Life for more than a few weeks on the date of the major release (https://github.com/ansible-community/community-topics/discussions/271, https://github.com/ansible-collections/community.general/pull/7259). +- ansible_galaxy_install - the ``ack_ansible29`` and ``ack_min_ansiblecore211`` options have been deprecated and will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/7358). +- consul - the ``ack_params_state_absent`` option has been deprecated and will be removed in community.general 10.0.0 (https://github.com/ansible-collections/community.general/pull/7358). +- cpanm - value ``compatibility`` is deprecated as default for parameter ``mode`` (https://github.com/ansible-collections/community.general/pull/6512). +- ejabberd_user - deprecate the parameter ``logging`` in favour of producing more detailed information in the module output (https://github.com/ansible-collections/community.general/pull/7043). +- flowdock - module relies entirely on no longer responsive API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6930). +- proxmox - old feature flag ``proxmox_default_behavior`` will be removed in community.general 10.0.0 (https://github.com/ansible-collections/community.general/pull/6836). +- proxmox_kvm - deprecate the option ``proxmox_default_behavior`` (https://github.com/ansible-collections/community.general/pull/7377). +- redfish_info, redfish_config, redfish_command - the default value ``10`` for the ``timeout`` option is deprecated and will change to ``60`` in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/7295). +- redhat module utils - the ``module_utils.redhat`` module is deprecated, as + effectively unused: the ``Rhsm``, ``RhsmPool``, and ``RhsmPools`` classes + will be removed in community.general 9.0.0; the ``RegistrationBase`` class + will be removed in community.general 10.0.0 together with the + ``rhn_register`` module, as it is the only user of this class; this means + that the whole ``module_utils.redhat`` module will be dropped in + community.general 10.0.0, so importing it without even using anything of it + will fail + (https://github.com/ansible-collections/community.general/pull/6663). +- redhat_subscription - the ``autosubscribe`` alias for the ``auto_attach`` option has been + deprecated for many years, although only in the documentation. Officially mark this alias + as deprecated, and it will be removed in community.general 9.0.0 + (https://github.com/ansible-collections/community.general/pull/6646). +- redhat_subscription - the ``pool`` option is deprecated in favour of the + more precise and flexible ``pool_ids`` option + (https://github.com/ansible-collections/community.general/pull/6650). +- rhsm_repository - ``state=present`` has not been working as expected for many years, + and it seems it was not noticed so far; also, "presence" is not really a valid concept + for subscription repositories, which can only be enabled or disabled. Hence, mark the + ``present`` and ``absent`` values of the ``state`` option as deprecated, slating them + for removal in community.general 10.0.0 + (https://github.com/ansible-collections/community.general/pull/6673). +- stackdriver - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6887). +- webfaction_app - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). +- webfaction_db - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). +- webfaction_domain - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). +- webfaction_mailbox - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). +- webfaction_site - module relies entirely on no longer existent API endpoints, and it will be removed in community.general 9.0.0 (https://github.com/ansible-collections/community.general/pull/6909). + community.postgresql ~~~~~~~~~~~~~~~~~~~~ From 031bfcf4733b87b517ae5d0533fe8083e64e36e3 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 21 Nov 2023 14:27:41 -0500 Subject: [PATCH 085/536] add Ansible 9 changelogs (#831) --- .../rst/reference_appendices/release_and_maintenance.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 2f8dc7e4de9..732a3daa156 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -81,9 +81,10 @@ This table links to the changelogs for each major Ansible release. These changel ================================== ============================================== ========================= Ansible Community Package Release Status Core version dependency ================================== ============================================== ========================= -9.0.0 In development (unreleased) 2.16 -`8.x Changelogs`_ Current 2.15 -`7.x Changelogs`_ Unmaintained (end of life) after Ansible 7.7.0 2.14 +10.0.0 In development (unreleased) 2.17 +`9.x Changelogs`_ Current 2.16 +`8.x Changelogs`_ Unmaintained (end of life) after Ansible 8.7.0 2.15 +`7.x Changelogs`_ Unmaintained (end of life) 2.14 `6.x Changelogs`_ Unmaintained (end of life) 2.13 `5.x Changelogs`_ Unmaintained (end of life) 2.12 `4.x Changelogs`_ Unmaintained (end of life) 2.11 @@ -91,6 +92,7 @@ Ansible Community Package Release Status `2.10 Changelogs`_ Unmaintained (end of life) 2.10 ================================== ============================================== ========================= +.. _9.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/9/CHANGELOG-v9.rst .. _8.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/8/CHANGELOG-v8.rst .. _7.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/7/CHANGELOG-v7.rst .. _6.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/6/CHANGELOG-v6.rst From d691b07735c55c7e2323303deb9546c1ab579f8f Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 21 Nov 2023 14:28:24 -0500 Subject: [PATCH 086/536] Set release version to 9 (#832) --- docs/docsite/rst/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index c4683441864..e401114822a 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -240,7 +240,7 @@ 'devel' if tags.has('all') else '2.16' if tags.has('core_lang') or tags.has('core') else '2.10' if tags.has('2.10') else - '8' if tags.has('ansible') + '9' if tags.has('ansible') else '' ), # list specifically out of order to make latest work From 4072c969d56141a1a850cf11e68285abe8b51117 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 21 Nov 2023 14:28:58 -0500 Subject: [PATCH 087/536] update backport instructions to match 2.16 (#799) --- docs/docsite/rst/community/development_process.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 8ff1bc033b2..91847e89421 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -206,7 +206,7 @@ Here are some examples: remote_src=True even if mode was not set as a parameter. This failed on filesystems which do not have permission bits (https://github.com/ansible/ansible/issues/29444). -You can find more example changelog fragments in the `changelog directory `_ for the 2.12 release. +You can find more example changelog fragments in the `changelog directory `_ for the 2.16 release. After you have written the changelog fragment for your PR, commit the file and include it with the pull request. @@ -241,7 +241,7 @@ We do **not** backport features. These instructions assume that: - * ``stable-2.15`` is the targeted release branch for the backport + * ``stable-2.16`` is the targeted release branch for the backport * ``https://github.com/ansible/ansible.git`` is configured as a ``git remote`` named ``upstream``. If you do not use a ``git remote`` named ``upstream``, adjust the instructions accordingly. * ``https://github.com//ansible.git`` is configured as a ``git remote`` named ``origin``. If you do not use a ``git remote`` named ``origin``, adjust the instructions accordingly. @@ -250,7 +250,7 @@ We do **not** backport features. .. code-block:: shell git fetch upstream - git checkout -b backport/2.15/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.15 + git checkout -b backport/2.16/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.16 #. Cherry pick the relevant commit SHA from the devel branch into your feature branch, handling merge conflicts as necessary: @@ -264,15 +264,15 @@ We do **not** backport features. .. code-block:: shell - git push origin backport/2.15/[PR_NUMBER_FROM_DEVEL] + git push origin backport/2.16/[PR_NUMBER_FROM_DEVEL] -#. Submit the pull request for ``backport/2.15/[PR_NUMBER_FROM_DEVEL]`` against the ``stable-2.15`` branch +#. Submit the pull request for ``backport/2.16/[PR_NUMBER_FROM_DEVEL]`` against the ``stable-2.16`` branch #. The Release Manager will decide whether to merge the backport PR before the next minor release. There isn't any need to follow up. Just ensure that the automated tests (CI) are green. .. note:: - The branch name ``backport/2.15/[PR_NUMBER_FROM_DEVEL]`` is somewhat arbitrary but conveys meaning about the purpose of the branch. This branch name format is not required, but it can be helpful, especially when making multiple backport PRs for multiple stable branches. + The branch name ``backport/2.16/[PR_NUMBER_FROM_DEVEL]`` is somewhat arbitrary but conveys meaning about the purpose of the branch. This branch name format is not required, but it can be helpful, especially when making multiple backport PRs for multiple stable branches. .. note:: From 6f9e846e1b0840f3e62c88f6030070eeb64d2ed2 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 21 Nov 2023 17:36:49 -0500 Subject: [PATCH 088/536] update logic to make it easier to patch for core vs ansible release (#849) --- docs/docsite/rst/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index e401114822a..80d38f64e83 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -43,7 +43,10 @@ ) VERSION = ( - 'devel' if tags.has('core_lang') or tags.has('core') or tags.has('ansible') or tags.has('all') else + # Controls branch version for core releases + 'devel' if tags.has('core_lang') or tags.has('core') else + # Controls branch version for Ansible package releases + 'devel' if tags.has('ansible') or tags.has('all') else '2.10' if tags.has('2.10') else '' ) From 89ef0d9d2a52a048615a6b19104eca9499eebfdd Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 22 Nov 2023 13:06:17 -0600 Subject: [PATCH 089/536] sphinx: remove usage of deprecated notfound-page options (#827) sphinx-notfound-page deprecated and removed notfound_no_urls_prefix, notfound_default_language, and notfound_default_version in favor of notfound_urls_prefix. We were still using these old options which caused our 404 pages to break. --- docs/docsite/rst/conf.py | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 80d38f64e83..a3e83f2b33a 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -337,15 +337,10 @@ # with no 'notfound_template' and no 'notfound_context' set, # the extension builds 404.rst into a location-agnostic 404 page # -# default is `en` - using this for the sub-site: -notfound_default_language = "ansible" -# default is `latest`: # setting explicitly - docsite serves up /ansible/latest/404.html # so keep this set to `latest` even on the `devel` branch # then no maintenance is needed when we branch a new stable_x.x -notfound_default_version = "latest" -# makes default setting explicit: -notfound_no_urls_prefix = False +notfound_urls_prefix = "/ansible/latest/" # Options for LaTeX output # ------------------------ From a55fa9c2b8f0a371176d0e0ebfe2e6107f709c7a Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 23 Nov 2023 10:31:05 +0100 Subject: [PATCH 090/536] Add the mission statement to the community guide --- docs/docsite/rst/community/index.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/docsite/rst/community/index.rst b/docs/docsite/rst/community/index.rst index b5ddb51d659..81136a4a6ae 100644 --- a/docs/docsite/rst/community/index.rst +++ b/docs/docsite/rst/community/index.rst @@ -12,6 +12,12 @@ Ansible Community Guide Welcome to the Ansible Community Guide! +In the Ansible community, our mission is to produce, maintain, and popularize simple, flexible, and powerful open-source software tools tailored to automating a large variety of tasks. +We strive to innovate in making infrastructure configuration and management as effortless and efficient as possible with automation, enabling people to focus on their core objectives. + +We welcome members from all skill levels to participate in our open, inclusive, and vibrant community. +Whether you are an expert or just beginning your journey with Ansible, you are encouraged to contribute, share insights, and collaborate with fellow enthusiasts! + The purpose of this guide is to teach you everything you need to know about being a contributing member of the Ansible community. All types of contributions are welcome and necessary for Ansible's continued success. From 60df49bff5da4bbf5b01d186cf6bde47e9ca8739 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 23 Nov 2023 11:13:40 +0100 Subject: [PATCH 091/536] developing_collections_structure.rst: Add EE collection-level metadata link to meta directory subsection --- .../dev_guide/developing_collections_structure.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index 3c852521db7..937312235b7 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -206,10 +206,14 @@ See :ref:`testing_collections` for specific information on how to test collectio When reading the :ref:`developing_testing` documentation, there will be content that applies to running Ansible from source code through a git clone, which is typical of an Ansible developer. However, it is not always typical for an Ansible Collection author to be running Ansible from source but instead from a stable release, and to create Collections it is not necessary to run Ansible from source. Therefore, when references of dealing with `ansible-test` binary paths, command completion, or environment variables are presented throughout the :ref:`developing_testing` documentation; keep in mind that it is not needed for Ansible Collection Testing because the act of installing the stable release of Ansible containing `ansible-test` is expected to setup those things for you. + +meta directory +-------------- + .. _meta_runtime_yml: -meta directory and runtime.yml ------------------------------- +runtime.yml +~~~~~~~~~~~ A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys: @@ -282,6 +286,12 @@ A collection can store some additional metadata in a ``runtime.yml`` file in the - my_module - another.collection.another_module +execution_environments.yml +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your collection has requirements, you can specify them in the ``execution-environment.yml`` file in the ``meta`` directory not to make users do it manually when building `Execution Environments `_ containing your collection. +See the `collection-level metadata guide `_ for details. + .. seealso:: :ref:`distributing_collections` From 11de19005f93456cfedd6cde3b5546c45b08e76f Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 23 Nov 2023 11:18:44 +0100 Subject: [PATCH 092/536] Fix --- .../rst/dev_guide/developing_collections_structure.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index 937312235b7..161a80581af 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -213,7 +213,7 @@ meta directory .. _meta_runtime_yml: runtime.yml -~~~~~~~~~~~ +^^^^^^^^^^^ A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys: @@ -287,7 +287,7 @@ A collection can store some additional metadata in a ``runtime.yml`` file in the - another.collection.another_module execution_environments.yml -~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^ If your collection has requirements, you can specify them in the ``execution-environment.yml`` file in the ``meta`` directory not to make users do it manually when building `Execution Environments `_ containing your collection. See the `collection-level metadata guide `_ for details. From f6d9440b7b9aabe534f76c3cfd6b5a0ecb9ad51b Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Fri, 24 Nov 2023 15:02:33 -0500 Subject: [PATCH 093/536] Update to sphinx-rtd-theme v2 to fix 404 pages (#851) Relates: https://github.com/ansible/ansible-documentation/issues/678 --- tests/constraints-base.in | 1 + tests/requirements-relaxed.txt | 6 ++++-- tests/requirements.txt | 6 ++++-- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/tests/constraints-base.in b/tests/constraints-base.in index 77cb17091f0..9eb05d0ea0c 100644 --- a/tests/constraints-base.in +++ b/tests/constraints-base.in @@ -1,3 +1,4 @@ # Known limitations for indirect/transitive dependencies. rstcheck < 6 # rstcheck 6.x has problem with rstcheck.core triggered by include files w/ sphinx directives https://github.com/rstcheck/rstcheck-core/issues/3 +sphinx-rtd-theme>=2.0.0rc4 # Fix 404 pages with new sphinx -- https://github.com/ansible/ansible-documentation/issues/678 diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index a458d3c7f2f..e0aceef13ad 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -136,8 +136,10 @@ sphinx-intl==2.1.0 # via -r tests/requirements-relaxed.in sphinx-notfound-page==1.0.0 # via -r tests/requirements-relaxed.in -sphinx-rtd-theme==1.3.0 - # via sphinx-ansible-theme +sphinx-rtd-theme==2.0.0rc4 + # via + # -c tests/constraints-base.in + # sphinx-ansible-theme sphinxcontrib-applehelp==1.0.7 # via sphinx sphinxcontrib-devhelp==1.0.5 diff --git a/tests/requirements.txt b/tests/requirements.txt index f72f73c7b3f..d9675fc5bcc 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -139,8 +139,10 @@ sphinx-intl==2.1.0 # via -r tests/requirements-relaxed.in sphinx-notfound-page==1.0.0 # via -r tests/requirements-relaxed.in -sphinx-rtd-theme==1.3.0 - # via sphinx-ansible-theme +sphinx-rtd-theme==2.0.0rc4 + # via + # -c tests/constraints-base.in + # sphinx-ansible-theme sphinxcontrib-applehelp==1.0.7 # via sphinx sphinxcontrib-devhelp==1.0.5 From 367f0b7bdded03c2ef0d3a0b1e40968aeed15159 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Fri, 24 Nov 2023 22:57:53 +0100 Subject: [PATCH 094/536] developing_collections_path.rst: fix formatting (#842) --- docs/docsite/rst/dev_guide/developing_collections_path.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections_path.rst b/docs/docsite/rst/dev_guide/developing_collections_path.rst index bb95840c956..2c4d108e070 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_path.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_path.rst @@ -67,7 +67,7 @@ We recommend you to use the `collection_template repository `_ as an example. If your collection contains modules or plugins, make sure their documentation is comprehensive. From bfeef95c8fa0ddd15252f54e5c412dd338372099 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Fri, 24 Nov 2023 16:58:43 -0500 Subject: [PATCH 095/536] installation_distros.rst: fix RST hyperlink syntax (#857) The link to OpenSUSE Support Portal was broken. --- docs/docsite/rst/installation_guide/installation_distros.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/installation_guide/installation_distros.rst b/docs/docsite/rst/installation_guide/installation_distros.rst index 9e71f73a983..980d8d54f4c 100644 --- a/docs/docsite/rst/installation_guide/installation_distros.rst +++ b/docs/docsite/rst/installation_guide/installation_distros.rst @@ -69,7 +69,7 @@ Installing Ansible on OpenSUSE Tumbleweed/Leap $ sudo zypper install ansible -See `OpenSUSE Support Portal ` for additional help with Ansible on OpenSUSE. +See `OpenSUSE Support Portal `_ for additional help with Ansible on OpenSUSE. .. _from_apt: From d1d49f6f851e696bbc25d9bbe23ab4514e592641 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Fri, 24 Nov 2023 23:48:37 +0100 Subject: [PATCH 096/536] Update the information on RouterOS network connections. (#841) --- .../rst/network/user_guide/platform_routeros.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/network/user_guide/platform_routeros.rst b/docs/docsite/rst/network/user_guide/platform_routeros.rst index 2db6c5ad1b8..0799bf5caab 100644 --- a/docs/docsite/rst/network/user_guide/platform_routeros.rst +++ b/docs/docsite/rst/network/user_guide/platform_routeros.rst @@ -4,8 +4,14 @@ RouterOS Platform Options *************************************** -RouterOS is part of the `community.network `_ collection and only supports CLI connections today. ``httpapi`` modules may be added in future. +RouterOS is part of the `community.network `_ collection and only supports CLI connections and direct API access. This page offers details on how to use ``ansible.netcommon.network_cli`` on RouterOS in Ansible. +Further information can be found in :ref:`the community.routeros collection's SSH guide +`. + +Information on how to use the RouterOS API can be found in :ref:`the community.routeros collection's API guide +`. + .. contents:: :local: @@ -37,7 +43,11 @@ Connections available .. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation) -RouterOS does not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. +The RouterOS SSH modules do not support ``ansible_connection: local``. You must use ``ansible_connection: ansible.netcommon.network_cli``. + +The RouterOS API modules require ``ansible_connection: local``. See the :ref:`the community.routeros collection's API guide +` for more information. + Using CLI in Ansible ==================== @@ -61,6 +71,7 @@ Example CLI ``group_vars/routeros.yml`` - If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. - If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords through environment variables. - If you are getting timeout errors you may want to add ``+cet1024w`` suffix to your username which will disable console colors, enable "dumb" mode, tell RouterOS not to try detecting terminal capabilities and set terminal width to 1024 columns. See article `Console login process `_ in MikroTik wiki for more information. +- More notes can be found in the :ref:`the community.routeros collection's SSH guide `. Example CLI task ---------------- From 21959a68196f803349ed4f38c3944c5c6bfd8a83 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sat, 25 Nov 2023 23:07:57 -0500 Subject: [PATCH 097/536] ci: refresh dev dependencies (#839) --- tests/static.txt | 2 +- tests/typing.txt | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index 9b732abb9df..4f763f33ffe 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.5 +ruff==0.1.6 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 05eb31d3593..69277e1d82d 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -4,9 +4,9 @@ # # pip-compile --allow-unsafe --output-file=tests/typing.txt --strip-extras tests/typing.in # -argcomplete==3.1.4 +argcomplete==3.1.6 # via nox -certifi==2023.7.22 +certifi==2023.11.17 # via requests cffi==1.16.0 # via @@ -28,13 +28,13 @@ distlib==0.3.7 # via virtualenv filelock==3.13.1 # via virtualenv -idna==3.4 +idna==3.6 # via requests jinja2==3.1.2 # via -r tests/../hacking/pr_labeler/requirements.txt markupsafe==2.1.3 # via jinja2 -mypy==1.7.0 +mypy==1.7.1 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy @@ -42,7 +42,7 @@ nox==2023.4.22 # via -r tests/typing.in packaging==23.2 # via nox -platformdirs==3.11.0 +platformdirs==4.0.0 # via virtualenv pycparser==2.21 # via cffi @@ -70,11 +70,11 @@ typing-extensions==4.8.0 # mypy # pygithub # typer -urllib3==2.0.7 +urllib3==2.1.0 # via # pygithub # requests -virtualenv==20.24.6 +virtualenv==20.24.7 # via nox wrapt==1.16.0 # via deprecated From a8f457e824fbd0829dc5bbec5835d1413aa210fe Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 26 Nov 2023 18:09:18 +0100 Subject: [PATCH 098/536] Fix Edit on GitHub for templated pages. --- docs/docsite/.templates/breadcrumbs.html | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/docsite/.templates/breadcrumbs.html b/docs/docsite/.templates/breadcrumbs.html index 0157624627c..16532867bb2 100644 --- a/docs/docsite/.templates/breadcrumbs.html +++ b/docs/docsite/.templates/breadcrumbs.html @@ -14,6 +14,12 @@ {% elif pagename.startswith('collections/') %}
+ {% elif pagename == 'reference_appendices/config' %} + {{ _('Edit on GitHub') }} + {% elif pagename == 'reference_appendices/playbooks_keywords' %} + {{ _('Edit on GitHub') }} + {% elif pagename == 'dev_guide/collections_galaxy_meta' %} + {{ _('Edit on GitHub') }} {% elif check_meta and pagename.startswith('cli') and meta.get('source', None) %} {{ _('Edit on GitHub') }} {% elif (not 'list_of' in pagename) and (not 'category' in pagename) %} From 8dce7764f9c4043e19a357118c7a252b27cd75fd Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 26 Nov 2023 18:09:24 +0100 Subject: [PATCH 099/536] Fix dead link. --- docs/docsite/rst/playbook_guide/playbooks_loops.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index 97d44d0f805..db360467c77 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -107,7 +107,7 @@ You can pass a list directly to a parameter for some plugins. Most of the packag state: present loop: "{{ list_of_packages }}" -Check the :ref:`module documentation ` to see if you can pass a list to any particular module's parameter(s). +Check the :ref:`module documentation ` to see if you can pass a list to any particular module's parameter(s). Iterating over a list of hashes ------------------------------- From efa9ab4c2513c2ffbc43d696bc73997704e86c74 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 26 Nov 2023 18:09:44 +0100 Subject: [PATCH 100/536] Remove template that is no longer used. --- docs/templates/modules_by_category.rst.j2 | 17 ----------------- 1 file changed, 17 deletions(-) delete mode 100644 docs/templates/modules_by_category.rst.j2 diff --git a/docs/templates/modules_by_category.rst.j2 b/docs/templates/modules_by_category.rst.j2 deleted file mode 100644 index 77635284484..00000000000 --- a/docs/templates/modules_by_category.rst.j2 +++ /dev/null @@ -1,17 +0,0 @@ -.. _modules_by_category: - -{# avoids rST "isn't included in any toctree" errors for module index docs #} -:orphan: - -Module Index -============ - - -.. toctree:: :maxdepth: 1 - -{% for name in categories %} -{# strip out empty category names as a result flattening the dir structure #} -{% if name %} - list_of_@{ name }@_modules -{% endif %} -{% endfor %} From 55e1835bc24f1f1c6a8f020145945f4d797f6db5 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 26 Nov 2023 18:26:53 +0100 Subject: [PATCH 101/536] Sanitize value of github_version. Move its path component to new variables. --- docs/docsite/.templates/breadcrumbs.html | 8 ++++---- docs/docsite/rst/conf.py | 5 +++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/docsite/.templates/breadcrumbs.html b/docs/docsite/.templates/breadcrumbs.html index 16532867bb2..a38fc35626f 100644 --- a/docs/docsite/.templates/breadcrumbs.html +++ b/docs/docsite/.templates/breadcrumbs.html @@ -15,15 +15,15 @@
{% elif pagename == 'reference_appendices/config' %} - {{ _('Edit on GitHub') }} + {{ _('Edit on GitHub') }} {% elif pagename == 'reference_appendices/playbooks_keywords' %} - {{ _('Edit on GitHub') }} + {{ _('Edit on GitHub') }} {% elif pagename == 'dev_guide/collections_galaxy_meta' %} - {{ _('Edit on GitHub') }} + {{ _('Edit on GitHub') }} {% elif check_meta and pagename.startswith('cli') and meta.get('source', None) %} {{ _('Edit on GitHub') }} {% elif (not 'list_of' in pagename) and (not 'category' in pagename) %} - {{ _('Edit on GitHub') }} + {{ _('Edit on GitHub') }} {% endif %} {%- endif %} {%- elif display_bitbucket %} diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index a3e83f2b33a..5923dbc57eb 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -233,8 +233,9 @@ 'is_eol': False, 'github_user': 'ansible', 'github_repo': 'ansible-documentation', - 'github_version': 'devel/docs/docsite/rst/', - 'github_module_version': 'devel/lib/ansible/modules/', + 'github_version': 'devel', + 'github_rst_path': 'docs/docsite/rst/', + 'github_template_path': 'docs/templates/', 'github_root_dir': 'devel/lib/ansible', 'github_cli_repo': 'ansible', 'github_cli_version': 'devel', From 12e9b15d1c6c1b289433c8dd0340bdc079476b59 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 28 Nov 2023 10:46:04 +0100 Subject: [PATCH 102/536] Update docs/docsite/rst/dev_guide/developing_collections_structure.rst Co-authored-by: Sandra McCann --- docs/docsite/rst/dev_guide/developing_collections_structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index 161a80581af..e04015108ae 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -289,7 +289,7 @@ A collection can store some additional metadata in a ``runtime.yml`` file in the execution_environments.yml ^^^^^^^^^^^^^^^^^^^^^^^^^^ -If your collection has requirements, you can specify them in the ``execution-environment.yml`` file in the ``meta`` directory not to make users do it manually when building `Execution Environments `_ containing your collection. +If your collection has requirements, you can specify them in the ``execution-environment.yml`` file in the ``meta`` directory. This ensures users do not need to add these requirements manually when building `Execution Environments `_ containing your collection. See the `collection-level metadata guide `_ for details. .. seealso:: From 1fc55c0c6efd86c09933518556c395ee1588d21d Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 28 Nov 2023 10:46:50 +0100 Subject: [PATCH 103/536] Update docs/docsite/rst/dev_guide/developing_collections_structure.rst --- .../docsite/rst/dev_guide/developing_collections_structure.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index e04015108ae..4b2139adc75 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -289,7 +289,8 @@ A collection can store some additional metadata in a ``runtime.yml`` file in the execution_environments.yml ^^^^^^^^^^^^^^^^^^^^^^^^^^ -If your collection has requirements, you can specify them in the ``execution-environment.yml`` file in the ``meta`` directory. This ensures users do not need to add these requirements manually when building `Execution Environments `_ containing your collection. +If your collection has requirements, you can specify them in the ``execution-environment.yml`` file in the ``meta`` directory. +This ensures users do not need to add these requirements manually when building `Execution Environments `_ containing your collection. See the `collection-level metadata guide `_ for details. .. seealso:: From ca0b2dfeaf9fa8502c23e9e0c1a497d7c1d32111 Mon Sep 17 00:00:00 2001 From: "Greg \"Gwmngilfen\" Sutcliffe" Date: Tue, 28 Nov 2023 14:42:49 +0000 Subject: [PATCH 104/536] Refs #340: Swap old 'CLA' for the DCO (#598) Co-authored-by: Maxwell G --- CONTRIBUTING.md | 11 ++++++ DCO | 37 +++++++++++++++++++ .../collection_requirements.rst | 1 - .../contributor_license_agreement.rst | 7 ---- .../developer_certificate_of_origin.rst | 11 ++++++ .../docsite/rst/community/getting_started.rst | 2 +- docs/docsite/rst/dev_guide/ansible_index.rst | 2 +- docs/docsite/rst/dev_guide/core_index.rst | 2 +- .../developing_modules_checklist.rst | 2 +- 9 files changed, 63 insertions(+), 12 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 DCO delete mode 100644 docs/docsite/rst/community/contributor_license_agreement.rst create mode 100644 docs/docsite/rst/community/developer_certificate_of_origin.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..713b64960a3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,11 @@ +# How to Contribute + +The ansible-documention project is [GPL-3.0 licensed](COPYING) and accepts contributions through +GitHub pull requests. + +## Certificate of Origin + +By contributing to ansible-documentation, you agree to the Developer Certificate of +Origin (DCO). This document was created by the Linux Kernel community and is a +simple statement that you, as a contributor, have the legal right to make the +contribution. See the [DCO](DCO) file for details. diff --git a/DCO b/DCO new file mode 100644 index 00000000000..8201f992154 --- /dev/null +++ b/DCO @@ -0,0 +1,37 @@ +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +1 Letterman Drive +Suite D4700 +San Francisco, CA, 94129 + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 28e16ef9e41..98cbcf446d4 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -333,7 +333,6 @@ prevent unwelcome licensing changes that can occur when one entity owns the copyrights for an entire project, and lower barriers to contribution. - .. _coll_repo_management: Repository management diff --git a/docs/docsite/rst/community/contributor_license_agreement.rst b/docs/docsite/rst/community/contributor_license_agreement.rst deleted file mode 100644 index b0a0f11736c..00000000000 --- a/docs/docsite/rst/community/contributor_license_agreement.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _contributor_license_agreement: - -****************************** -Contributors License Agreement -****************************** - -By contributing you agree that these contributions are your own (or approved by your employer) and you grant a full, complete, irrevocable copyright license to all users and developers of the project, present and future, pursuant to the license of the project. diff --git a/docs/docsite/rst/community/developer_certificate_of_origin.rst b/docs/docsite/rst/community/developer_certificate_of_origin.rst new file mode 100644 index 00000000000..1893c143852 --- /dev/null +++ b/docs/docsite/rst/community/developer_certificate_of_origin.rst @@ -0,0 +1,11 @@ +.. _developer_certificate_of_origin: + +******************************* +Developer Certificate Of Origin +******************************* + +By contributing to this project you agree to the Developer Certificate of +Origin (DCO). This document was created by the Linux Kernel community and is a +simple statement that you, as a contributor, have the legal right to make the +contribution. See the `DCO file `_ +file for details. diff --git a/docs/docsite/rst/community/getting_started.rst b/docs/docsite/rst/community/getting_started.rst index b35225163bd..5eb4c4689da 100644 --- a/docs/docsite/rst/community/getting_started.rst +++ b/docs/docsite/rst/community/getting_started.rst @@ -10,7 +10,7 @@ Welcome and thank you for getting more involved with the Ansible community. Here :maxdepth: 2 code_of_conduct - contributor_license_agreement + developer_certificate_of_origin communication how_can_I_help diff --git a/docs/docsite/rst/dev_guide/ansible_index.rst b/docs/docsite/rst/dev_guide/ansible_index.rst index 0ec3f1a456b..a5c6f90ae54 100644 --- a/docs/docsite/rst/dev_guide/ansible_index.rst +++ b/docs/docsite/rst/dev_guide/ansible_index.rst @@ -60,7 +60,7 @@ Find the task that best describes what you want to do: * I want to :ref:`understand how to contribute to Ansible `. * I want to :ref:`contribute my module or plugin `. - * I want to :ref:`understand the license agreement ` for contributions to Ansible. + * I want to :ref:`understand the DCO agreement ` for contributions to the `Ansible Core `_ and `Ansible Documentation `_ repositories. If you prefer to read the entire guide, here's a list of the pages in order. diff --git a/docs/docsite/rst/dev_guide/core_index.rst b/docs/docsite/rst/dev_guide/core_index.rst index 2bd630e3d51..1e9555cc50c 100644 --- a/docs/docsite/rst/dev_guide/core_index.rst +++ b/docs/docsite/rst/dev_guide/core_index.rst @@ -57,7 +57,7 @@ Find the task that best describes what you want to do: * I want to :ref:`understand how to contribute to Ansible `. * I want to :ref:`contribute my module or plugin `. - * I want to :ref:`understand the license agreement ` for contributions to Ansible. + * I want to :ref:`understand the DCO agreement ` for contributions to the `Ansible Core `_ and `Ansible Documentation `_ repositories. If you prefer to read the entire guide, here's a list of the pages in order. diff --git a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst index c11689f05c3..c64f3f4170d 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst @@ -20,7 +20,7 @@ To contribute a module to most Ansible collections, you must: * use proper :ref:`Python 3 syntax ` * follow `PEP 8 `_ Python style conventions - see :ref:`testing_pep8` for more information * license your module under the GPL license (GPLv3 or later) -* understand the :ref:`license agreement `, which applies to all contributions +* understand the :ref:`DCO agreement `, which applies to contributions to the `Ansible Core `_ and `Ansible Documentation `_ repositories. * conform to Ansible's :ref:`formatting and documentation ` standards * include comprehensive :ref:`tests ` for your module * minimize module dependencies From 9ce2cb93c902e27a262d1823dad8441961a17695 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 28 Nov 2023 15:50:39 -0500 Subject: [PATCH 105/536] add support for Ansible 9 intersphinx links --- docs/docsite/rst/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index a3e83f2b33a..7e339d7920a 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -395,19 +395,19 @@ 'python3': ('https://docs.python.org/3/', None, None), 'jinja2': ('http://jinja.palletsprojects.com/', None, None), 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None, None), - 'ansible_8': ('https://docs.ansible.com/ansible/8/', None, None), + 'ansible_9': ('https://docs.ansible.com/ansible/9/', None, None), } if tags.has('all') else { 'python': ('https://docs.python.org/2/', None, None), 'python3': ('https://docs.python.org/3/', None, None), 'jinja2': ('http://jinja.palletsprojects.com/', None, None), 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None, None), - 'ansible_8': ('https://docs.ansible.com/ansible/8/', None, None), + 'ansible_9': ('https://docs.ansible.com/ansible/8/', None, None), } if tags.has('core_lang') else { 'python': ('https://docs.python.org/2/', (None, None)), 'python3': ('https://docs.python.org/3/', (None, None)), 'jinja2': ('http://jinja.palletsprojects.com/', (None, None)), 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', (None, None)), - 'ansible_8': ('https://docs.ansible.com/ansible/8/', (None, None)), + 'ansible_9': ('https://docs.ansible.com/ansible/8/', (None, None)), } if tags.has('core') else { 'python': ('https://docs.python.org/2/', (None, '../python2.inv')), 'python3': ('https://docs.python.org/3/', (None, '../python3.inv')), @@ -423,7 +423,7 @@ 'python3': ('https://docs.python.org/3/', None, None), 'jinja2': ('http://jinja.palletsprojects.com/', None, None), 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None, None), - 'ansible_8': ('https://docs.ansible.com/ansible/8/', None, None), + 'ansible_9': ('https://docs.ansible.com/ansible/8/', None, None), } if tags.has('ansible') else {} # linckchecker settings From 33b1126aa07f7af4e95d4bc7917e3862b99458b5 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 29 Nov 2023 11:24:25 -0500 Subject: [PATCH 106/536] Apply suggestions from code review Co-authored-by: Don Naro --- docs/docsite/rst/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 7e339d7920a..39208ada158 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -401,13 +401,13 @@ 'python3': ('https://docs.python.org/3/', None, None), 'jinja2': ('http://jinja.palletsprojects.com/', None, None), 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None, None), - 'ansible_9': ('https://docs.ansible.com/ansible/8/', None, None), + 'ansible_9': ('https://docs.ansible.com/ansible/9/', None, None), } if tags.has('core_lang') else { 'python': ('https://docs.python.org/2/', (None, None)), 'python3': ('https://docs.python.org/3/', (None, None)), 'jinja2': ('http://jinja.palletsprojects.com/', (None, None)), 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', (None, None)), - 'ansible_9': ('https://docs.ansible.com/ansible/8/', (None, None)), + 'ansible_9': ('https://docs.ansible.com/ansible/9/', (None, None)), } if tags.has('core') else { 'python': ('https://docs.python.org/2/', (None, '../python2.inv')), 'python3': ('https://docs.python.org/3/', (None, '../python3.inv')), @@ -423,7 +423,7 @@ 'python3': ('https://docs.python.org/3/', None, None), 'jinja2': ('http://jinja.palletsprojects.com/', None, None), 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None, None), - 'ansible_9': ('https://docs.ansible.com/ansible/8/', None, None), + 'ansible_9': ('https://docs.ansible.com/ansible/9/', None, None), } if tags.has('ansible') else {} # linckchecker settings From a65735a04883507220910ffb5d7645955a422c34 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 30 Nov 2023 14:05:22 -0500 Subject: [PATCH 107/536] Update docs/docsite/rst/installation_guide/intro_installation.rst --- docs/docsite/rst/installation_guide/intro_installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 121efd6ad41..840b0f08366 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -36,7 +36,7 @@ The managed node also needs a user account that can connect through SSH to the n Node requirement summary ======================== -You can find details about control and managed node requirements, including Python versions, for each Ansible version in the :ref:`support_life` and :ref:`target_node_python_support` sections. +You can find details about control and managed node requirements, including Python versions, for each Ansible version in the :ref:`support_life` and :ref:`ansible_core_support_matrix` sections. .. _getting_ansible: From 12789b5faf9810abb46c102bf99c42604e2fb5b8 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 30 Nov 2023 21:22:38 +0100 Subject: [PATCH 108/536] intro_installation: add EE info (#870) * intro_installation: add EE info * Update docs/docsite/rst/installation_guide/intro_installation.rst Co-authored-by: Abhijeet Kasurde --- docs/docsite/rst/installation_guide/intro_installation.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 840b0f08366..4bd3395fda0 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -190,6 +190,12 @@ To upgrade an existing Ansible installation in this Python environment to the la $ python3 -m pip install --upgrade --user ansible +Installing Ansible to containers +================================ + +Instead of installing Ansible content manually, you can simply build an execution environment container image or use one of the available community images as your control node. +See the `Getting started with Execution Environments guide `_ for details. + .. _development_install: Installing for development From 3c79a2c5c748a31ea80e919812c0557a5dbb662e Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 30 Nov 2023 15:42:26 -0500 Subject: [PATCH 109/536] Updated loop docs (#838) * Updated loop docs * ssssssssssssssssssssssssssssssssss * itsnotpython * Apply suggestions from code review Co-authored-by: Maxwell G * Apply suggestions from code review --------- Co-authored-by: Maxwell G Co-authored-by: Sandra McCann --- .../rst/playbook_guide/playbooks_loops.rst | 189 ++++++++++++------ 1 file changed, 131 insertions(+), 58 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index db360467c77..93fd27d94eb 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -8,21 +8,28 @@ Ansible offers the ``loop``, ``with_``, and ``until`` keywords to execut repeating a polling step until a certain result is reached. .. note:: - * We added ``loop`` in Ansible 2.5. It is not yet a full replacement for ``with_``, but we recommend it for most use cases. + * We added ``loop`` in Ansible 2.5. as a simpler way to do loops, but we recommend it for most use cases. * We have not deprecated the use of ``with_`` - that syntax will still be valid for the foreseeable future. - * We are looking to improve ``loop`` syntax - watch this page and the `changelog `_ for updates. + * ``loop`` and ``with_`` are mutually exclusive. While it is possible to nest them under ``until``, this affects each loop iteration. .. contents:: :local: -Comparing ``loop`` and ``with_*`` -================================= +Comparing loops +=============== +* The normal use case for ``until`` has to do with tasks that are likely to fail, while ``loop`` and ``with_`` are meant for repeating tasks with slight variations. +* The ``loop`` and ``with_`` will run the task once per item in the list used as input, while ``until`` will rerun the task until a condition is met. + For programmers the former are "for loops" and the latter is a "while/until loop". * The ``with_`` keywords rely on :ref:`lookup_plugins` - even ``items`` is a lookup. * The ``loop`` keyword is equivalent to ``with_list``, and is the best choice for simple loops. * The ``loop`` keyword will not accept a string as input, see :ref:`query_vs_lookup`. +* The ``until`` keyword accepts an 'end conditional' (expression that returns ``True`` or ``False``) that is "implicitly templated" (no need for ``{{ }}``), + commonly based on the variable you ``register`` for the task. +* ``loop_control`` affects both ``loop`` and ``with_``, but not ``until``, which has its own companion keywords: ``retries`` and ``delay``. * Generally speaking, any use of ``with_*`` covered in :ref:`migrating_to_loop` can be updated to use ``loop``. -* Be careful when changing ``with_items`` to ``loop``, as ``with_items`` performed implicit single-level flattening. You may need to use ``flatten(1)`` with ``loop`` to match the exact outcome. For example, to get the same output as: +* Be careful when changing ``with_items`` to ``loop``, as ``with_items`` performs implicit single-level flattening. + You may need to use ``| flatten(1)`` with ``loop`` to match the exact outcome. For example, to get the same output as: .. code-block:: yaml @@ -49,10 +56,10 @@ it is cleaner to keep with_fileglob: '*.txt' -.. _standard_loops: +.. _using_loops: -Standard loops -============== +Using loops +=========== Iterating over a simple list ---------------------------- @@ -147,7 +154,7 @@ To loop over a dict, use the :ref:`dict2items `: Here, we are iterating over `tag_data` and printing the key and the value from it. Registering variables with a loop -================================= +--------------------------------- You can register the output of a loop as a variable. For example @@ -223,27 +230,6 @@ During iteration, the result of the current item will be placed in the variable. register: echo changed_when: echo.stdout != "one" -.. _complex_loops: - -Complex loops -============= - -Iterating over nested lists ---------------------------- - -You can use Jinja2 expressions to iterate over complex lists. For example, a loop can combine nested lists. - -.. code-block:: yaml+jinja - - - name: Give users access to multiple databases - community.mysql.mysql_user: - name: "{{ item[0] }}" - priv: "{{ item[1] }}.*:ALL" - append_privs: true - password: "foo" - loop: "{{ ['alice', 'bob'] | product(['clientdb', 'employeedb', 'providerdb']) | list }}" - - .. _do_until_loops: Retrying a task until a condition is met @@ -270,9 +256,12 @@ When you run a task with ``until`` and register the result as a variable, the re If ``until`` is not specified, the task will retry until the task succeeds but at most ``retries`` times. +.. _loop_over_inventory: + Looping over inventory ---------------------- +Normally the play itself is a loop over your inventory, but sometimes you need a task to do the same over a different set of hosts. To loop over your inventory, or just a subset of it, you can use a regular ``loop`` with the ``ansible_play_batch`` or ``groups`` variables. .. code-block:: yaml+jinja @@ -303,6 +292,7 @@ There is also a specific lookup plugin ``inventory_hostnames`` that can be used More information on the patterns can be found in :ref:`intro_patterns`. + .. _query_vs_lookup: Ensuring list input for ``loop``: using ``query`` rather than ``lookup`` @@ -395,34 +385,6 @@ To keep track of where you are in a loop, use the ``index_var`` directive with ` .. note:: `index_var` is 0 indexed. -Defining inner and outer variable names with ``loop_var`` ---------------------------------------------------------- -.. versionadded:: 2.1 - -You can nest two looping tasks using ``include_tasks``. However, by default, Ansible sets the loop variable ``item`` for each loop. This means the inner, nested loop will overwrite the value of ``item`` from the outer loop. -You can specify the name of the variable for each loop using ``loop_var`` with ``loop_control``. - -.. code-block:: yaml+jinja - - # main.yml - - include_tasks: inner.yml - loop: - - 1 - - 2 - - 3 - loop_control: - loop_var: outer_item - - # inner.yml - - name: Print outer and inner items - ansible.builtin.debug: - msg: "outer item={{ outer_item }} inner item={{ item }}" - loop: - - a - - b - - c - -.. note:: If Ansible detects that the current loop is using a variable that has already been defined, it will raise an error to fail the task. Extended loop variables ----------------------- @@ -474,6 +436,117 @@ For role authors, writing roles that allow loops, instead of dictating the requi "{{ lookup('vars', ansible_loop_var) }}" + +.. _nested_loops: + +Nested Loops +============ + +While we are using ``loop`` in these examples, the same applies to ``with_``. + +Iterating over nested lists +--------------------------- + +The simplest way to 'nest' loops is to avoid nesting loops, just format the data to achieve the same result. +You can use Jinja2 expressions to iterate over complex lists. For example, a loop can combine nested lists, which simulates a nested loop. + +.. code-block:: yaml+jinja + + - name: Give users access to multiple databases + community.mysql.mysql_user: + name: "{{ item[0] }}" + priv: "{{ item[1] }}.*:ALL" + append_privs: true + password: "foo" + loop: "{{ ['alice', 'bob'] | product(['clientdb', 'employeedb', 'providerdb']) | list }}" + +Stacking loops via include_tasks +-------------------------------- +.. versionadded:: 2.1 + +You can nest two looping tasks using ``include_tasks``. However, by default, Ansible sets the loop variable ``item`` for each loop. +This means the inner, nested loop will overwrite the value of ``item`` from the outer loop. +To avoid this, you can specify the name of the variable for each loop using ``loop_var`` with ``loop_control``. + +.. code-block:: yaml+jinja + + # main.yml + - include_task: inner.yml + loop: + - 1 + - 2 + - 3 + loop_control: + loop_var: outer_item + + # inner.yml + - name: Print outer and inner items + ansible.builtin.debug: + msg: "outer item={{ outer_item }} inner item={{ item }}" + loop: + - a + - b + - c + +.. note:: If Ansible detects that the current loop is using a variable that has already been defined, it will raise an error to fail the task. + +Until and loop +-------------- + +The ``until`` condition will apply per ``item`` of the ``loop``: + +.. code-block:: yaml+jinja + + - debug: msg={{item}} + loop: + - 1 + - 2 + - 3 + retries: 2 + until: item > 2 + +This will make Ansible retry the first 2 items twice, then fail the item on the 3rd attempt, +then succeed at the first attempt on the 3rd item, in the end failing the task as a whole. + +.. code-block:: none + + [started TASK: debug on localhost] + FAILED - RETRYING: [localhost]: debug (2 retries left).Result was: { + "attempts": 1, + "changed": false, + "msg": 1, + "retries": 3 + } + FAILED - RETRYING: [localhost]: debug (1 retries left).Result was: { + "attempts": 2, + "changed": false, + "msg": 1, + "retries": 3 + } + failed: [localhost] (item=1) => { + "msg": 1 + } + FAILED - RETRYING: [localhost]: debug (2 retries left).Result was: { + "attempts": 1, + "changed": false, + "msg": 2, + "retries": 3 + } + FAILED - RETRYING: [localhost]: debug (1 retries left).Result was: { + "attempts": 2, + "changed": false, + "msg": 2, + "retries": 3 + } + failed: [localhost] (item=2) => { + "msg": 2 + } + ok: [localhost] => (item=3) => { + "msg": 3 + } + fatal: [localhost]: FAILED! => {"msg": "One or more items failed"} + + .. _migrating_to_loop: Migrating from with_X to loop From a2d896a7c579520f2e64accc4d2c2d08063c1b6f Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Thu, 30 Nov 2023 13:33:12 -0800 Subject: [PATCH 110/536] Update links in plugin documentation (#859) * Update links in plugin documentation * Updated examples and links in the plugin documentation Fixes: #746 Signed-off-by: Abhijeet Kasurde Co-authored-by: Sandra McCann Co-authored-by: Maxwell G --- docs/docsite/rst/plugins/action.rst | 2 +- docs/docsite/rst/plugins/become.rst | 2 +- docs/docsite/rst/plugins/cache.rst | 2 +- docs/docsite/rst/plugins/callback.rst | 2 +- docs/docsite/rst/plugins/cliconf.rst | 4 +++- docs/docsite/rst/plugins/connection.rst | 2 +- docs/docsite/rst/plugins/docs_fragment.rst | 2 +- docs/docsite/rst/plugins/filter.rst | 2 +- docs/docsite/rst/plugins/httpapi.rst | 4 +++- docs/docsite/rst/plugins/lookup.rst | 2 +- docs/docsite/rst/plugins/module_util.rst | 2 +- docs/docsite/rst/plugins/netconf.rst | 4 +++- docs/docsite/rst/plugins/shell.rst | 7 ++++++- docs/docsite/rst/plugins/strategy.rst | 2 +- docs/docsite/rst/plugins/test.rst | 3 +-- 15 files changed, 26 insertions(+), 16 deletions(-) diff --git a/docs/docsite/rst/plugins/action.rst b/docs/docsite/rst/plugins/action.rst index d4a75958419..5086af12adf 100644 --- a/docs/docsite/rst/plugins/action.rst +++ b/docs/docsite/rst/plugins/action.rst @@ -31,7 +31,7 @@ Plugin list You cannot list action plugins directly, they show up as their counterpart modules: Use ``ansible-doc -l`` to see the list of available modules. -Use ``ansible-doc `` to see specific documentation and examples, this should note if the module has a corresponding action plugin. +Use ``ansible-doc `` to see plugin-specific documentation and examples. This should note if the module has a corresponding action plugin. .. seealso:: diff --git a/docs/docsite/rst/plugins/become.rst b/docs/docsite/rst/plugins/become.rst index c76308373b3..6cd7d402a1f 100644 --- a/docs/docsite/rst/plugins/become.rst +++ b/docs/docsite/rst/plugins/become.rst @@ -45,7 +45,7 @@ Plugin List ----------- You can use ``ansible-doc -t become -l`` to see the list of available plugins. -Use ``ansible-doc -t become `` to see specific documentation and examples. +Use ``ansible-doc -t become `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst index 5860df43d87..e819e158041 100644 --- a/docs/docsite/rst/plugins/cache.rst +++ b/docs/docsite/rst/plugins/cache.rst @@ -115,7 +115,7 @@ Plugin list ----------- You can use ``ansible-doc -t cache -l`` to see the list of available plugins. -Use ``ansible-doc -t cache `` to see specific documentation and examples. +Use ``ansible-doc -t cache `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst index 3134fb0fde7..607701854de 100644 --- a/docs/docsite/rst/plugins/callback.rst +++ b/docs/docsite/rst/plugins/callback.rst @@ -92,7 +92,7 @@ Plugin list ----------- You can use ``ansible-doc -t callback -l`` to see the list of available plugins. -Use ``ansible-doc -t callback `` to see specific documents and examples. +Use ``ansible-doc -t callback `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/cliconf.rst b/docs/docsite/rst/plugins/cliconf.rst index 8f47bdc1fc2..e175e9a3e99 100644 --- a/docs/docsite/rst/plugins/cliconf.rst +++ b/docs/docsite/rst/plugins/cliconf.rst @@ -34,7 +34,9 @@ Plugins are self-documenting. Each plugin should document its configuration opti Viewing cliconf plugins ----------------------- -These plugins have migrated to collections on `Ansible Galaxy `_. If you installed Ansible version 2.10 or later using ``pip``, you have access to several cliconf plugins. To list all available cliconf plugins on your control node, type ``ansible-doc -t cliconf -l``. To view plugin-specific documentation and examples, use ``ansible-doc -t cliconf``. +These plugins have migrated to collections on `Ansible Galaxy `_. If you installed Ansible version 2.10 or later using ``pip``, you have access to several cliconf plugins. +You can use ``ansible-doc -t cliconf -l`` to see the list of available plugins. +Use ``ansible-doc -t cliconf `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index 6681c106e38..33e176610b4 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -55,7 +55,7 @@ Plugin list ----------- You can use ``ansible-doc -t connection -l`` to see the list of available plugins. -Use ``ansible-doc -t connection `` to see detailed documentation and examples. +Use ``ansible-doc -t connection `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/docs_fragment.rst b/docs/docsite/rst/plugins/docs_fragment.rst index 5f4350bffe1..fc0d923b545 100644 --- a/docs/docsite/rst/plugins/docs_fragment.rst +++ b/docs/docsite/rst/plugins/docs_fragment.rst @@ -28,7 +28,7 @@ Only collection developers and maintainers use docs fragments. For more informat :ref:`developing_modules_general` An introduction to creating Ansible modules :ref:`developing_collections` - An guide to creating Ansible collections + A guide to creating Ansible collections `User Mailing List `_ Have a question? Stop by the Google group! :ref:`communication_irc` diff --git a/docs/docsite/rst/plugins/filter.rst b/docs/docsite/rst/plugins/filter.rst index 2985b1e42e2..8bbaa43d250 100644 --- a/docs/docsite/rst/plugins/filter.rst +++ b/docs/docsite/rst/plugins/filter.rst @@ -42,7 +42,7 @@ In the documentation, filters will always have a C(_input) option that correspon Plugin list ----------- -You can use ``ansible-doc -t filter -l`` to see the list of available plugins. Use ``ansible-doc -t filter `` to see specific documents and examples. +You can use ``ansible-doc -t filter -l`` to see the list of available plugins. Use ``ansible-doc -t filter `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/httpapi.rst b/docs/docsite/rst/plugins/httpapi.rst index 7900ff6cf6c..09e07677517 100644 --- a/docs/docsite/rst/plugins/httpapi.rst +++ b/docs/docsite/rst/plugins/httpapi.rst @@ -58,7 +58,9 @@ See the full working example `on GitHub `_. If you installed Ansible version 2.10 or later using ``pip``, you have access to several httpapi plugins. To list all available httpapi plugins on your control node, type ``ansible-doc -t httpapi -l``. To view plugin-specific documentation and examples, use ``ansible-doc -t httpapi``. +These plugins have migrated to collections on `Ansible Galaxy `_. If you installed Ansible version 2.10 or later using ``pip``, you have access to several httpapi plugins. +You can use ``ansible-doc -t httpapi -l`` to see the list of available plugins. +Use ``ansible-doc -t httpapi `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/lookup.rst b/docs/docsite/rst/plugins/lookup.rst index 570a333f38f..b6ab67bddd3 100644 --- a/docs/docsite/rst/plugins/lookup.rst +++ b/docs/docsite/rst/plugins/lookup.rst @@ -146,7 +146,7 @@ Additionally, ``q`` was introduced as a shortform of ``query``: Plugin list ----------- -You can use ``ansible-doc -t lookup -l`` to see the list of available plugins. Use ``ansible-doc -t lookup `` to see specific documents and examples. +You can use ``ansible-doc -t lookup -l`` to see the list of available plugins. Use ``ansible-doc -t lookup `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/module_util.rst b/docs/docsite/rst/plugins/module_util.rst index 8381fca2fd5..c9dc7747e2f 100644 --- a/docs/docsite/rst/plugins/module_util.rst +++ b/docs/docsite/rst/plugins/module_util.rst @@ -28,7 +28,7 @@ For information on using module utilities, see :ref:`developing_module_utilities :ref:`developing_modules_general` An introduction to creating Ansible modules :ref:`developing_collections` - An guide to creating Ansible collections + A guide to creating Ansible collections `User Mailing List `_ Have a question? Stop by the Google group! `irc.libera.chat `_ diff --git a/docs/docsite/rst/plugins/netconf.rst b/docs/docsite/rst/plugins/netconf.rst index 217fd7e159c..4fbf0f411dd 100644 --- a/docs/docsite/rst/plugins/netconf.rst +++ b/docs/docsite/rst/plugins/netconf.rst @@ -34,7 +34,9 @@ Plugins are self-documenting. Each plugin should document its configuration opti Listing netconf plugins ----------------------- -These plugins have migrated to collections on `Ansible Galaxy `_. If you installed Ansible version 2.10 or later using ``pip``, you have access to several netconf plugins. To list all available netconf plugins on your control node, type ``ansible-doc -t netconf -l``. To view plugin-specific documentation and examples, use ``ansible-doc -t netconf``. +These plugins have migrated to collections on `Ansible Galaxy `_. If you installed Ansible version 2.10 or later using ``pip``, you have access to several netconf plugins. +You can use ``ansible-doc -t netconf -l`` to see the list of available plugins. +Use ``ansible-doc -t netconf `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst index f17ecbb28ce..81965fc8769 100644 --- a/docs/docsite/rst/plugins/shell.rst +++ b/docs/docsite/rst/plugins/shell.rst @@ -30,8 +30,13 @@ In addition to the default configuration settings in :ref:`ansible_configuration the connection variable :ref:`ansible_shell_type ` to select the plugin to use. In this case, you will also want to update the :ref:`ansible_shell_executable ` to match. + +Plugin list +----------- + You can further control the settings for each plugin with other configuration options -detailed in the plugin themselves (linked below). +detailed in the plugin themselves. +You can use ``ansible-doc -t shell -l`` to see the list of available plugins. Use ``ansible-doc -t shell `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/strategy.rst b/docs/docsite/rst/plugins/strategy.rst index a65a92b8d24..d297d4738a1 100644 --- a/docs/docsite/rst/plugins/strategy.rst +++ b/docs/docsite/rst/plugins/strategy.rst @@ -57,7 +57,7 @@ Plugin list ----------- You can use ``ansible-doc -t strategy -l`` to see the list of available plugins. -Use ``ansible-doc -t strategy `` to see plugin-specific specific documentation and examples. +Use ``ansible-doc -t strategy `` to see plugin-specific documentation and examples. .. seealso:: diff --git a/docs/docsite/rst/plugins/test.rst b/docs/docsite/rst/plugins/test.rst index 19581d8461c..ee81bdd32ae 100644 --- a/docs/docsite/rst/plugins/test.rst +++ b/docs/docsite/rst/plugins/test.rst @@ -77,8 +77,7 @@ As mentioned above, one way to use tests is with the ``select`` family of filter Plugin list ----------- -You can use ``ansible-doc -t test -l`` to see the list of available plugins. Use ``ansible-doc -t test `` to see specific documents and examples. - +You can use ``ansible-doc -t test -l`` to see the list of available plugins. Use ``ansible-doc -t test `` to see plugin-specific documentation and examples. .. seealso:: From 2513a1d0bb09bdc226b142ff1e47723d6847c7d5 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Fri, 1 Dec 2023 16:39:56 +0100 Subject: [PATCH 111/536] installation_guide/intro: update seealso with respect to communication (#869) --- docs/docsite/rst/installation_guide/intro_installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 4bd3395fda0..0d477ab5764 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -362,7 +362,7 @@ See the `argcomplete documentation `_. Learning ansible's configuration management language :ref:`installation_faqs` Ansible Installation related to FAQs - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups + :ref:`forum` + Join the Ansible community forum to get help and share insights :ref:`communication_irc` How to join Ansible chat channels From e818e693ad444d63ebc60838e4e2cc7ab75e226b Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 25 Oct 2023 03:19:37 +0000 Subject: [PATCH 112/536] nox: add make session I know calling make via nox is a bit weird, but I think allowing to run the Makefile in an isolated environment without having to manually manage venvs and making it easy to choose between relaxed and stable dependencies is quite useful. We should eventually move away from the Makefile, but I think some level of integration is better than nothing. Translating the Makefile syntax and constructs into nox's Python syntax and untangling all of the different Python scripts that preprocess the documentation is a longer term project. --- noxfile.py | 43 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 5 deletions(-) diff --git a/noxfile.py b/noxfile.py index 2f6df57159d..d70a9735401 100644 --- a/noxfile.py +++ b/noxfile.py @@ -4,6 +4,7 @@ from argparse import ArgumentParser, BooleanOptionalAction from glob import iglob from pathlib import Path +from typing import cast import nox @@ -123,11 +124,9 @@ def clone_core(session: nox.Session): ] -@nox.session -@nox.parametrize(["test"], checker_tests, checker_tests) -def checkers(session: nox.Session, test: str): +def _relaxed_parser(session: nox.Session) -> ArgumentParser: """ - Run docs build checkers + Generate an argument parser with a --relaxed option. """ parser = ArgumentParser(prog=f"nox -e {session.name} --") parser.add_argument( @@ -136,8 +135,42 @@ def checkers(session: nox.Session, test: str): action=BooleanOptionalAction, help="Whether to use requirements-relaxed file. (Default: %(default)s)", ) - args = parser.parse_args(session.posargs) + return parser + + +def _env_python(session: nox.Session) -> str: + """ + Get the full path to an environment's python executable + """ + out = cast( + str, + session.run("python", "-c", "import sys; print(sys.executable)", silent=True), + ) + return out.strip() + + +@nox.session +@nox.parametrize(["test"], checker_tests, checker_tests) +def checkers(session: nox.Session, test: str): + """ + Run docs build checkers + """ + args = _relaxed_parser(session).parse_args(session.posargs) install(session, req="requirements-relaxed" if args.relaxed else "requirements") session.run("make", "-C", "docs/docsite", "clean", external=True) session.run("python", "tests/checkers.py", test) + + +@nox.session +def make(session: nox.Session): + """ + Run the docs build Makefile in an isolated environment + """ + parser = _relaxed_parser(session) + parser.add_argument("make_args", nargs="*", help="Arguments to pass on to make") + args = parser.parse_args(session.posargs) + + install(session, req="requirements-relaxed" if args.relaxed else "requirements") + make_args: list[str] = [f"PYTHON={_env_python(session)}", *(args.make_args or ())] + session.run("make", "-C", "docs/docsite", *make_args, external=True) From 08f2665f864e1338c09d86a27ea6be3c3e351882 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Thu, 30 Nov 2023 17:10:32 +0000 Subject: [PATCH 113/536] nox make: run `make clean coredocs` by default This way, `nox -s make` works by default without requiring developers to pass extra arguments. --- noxfile.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/noxfile.py b/noxfile.py index d70a9735401..7ae44d0d86b 100644 --- a/noxfile.py +++ b/noxfile.py @@ -14,7 +14,7 @@ *iglob("docs/bin/*.py"), ) PINNED = os.environ.get("PINNED", "true").lower() in {"1", "true"} -nox.options.sessions = ("clone-core", "lint", "checkers") +nox.options.sessions = ("clone-core", "lint", "checkers", "make") def install(session: nox.Session, *args, req: str, **kwargs): @@ -172,5 +172,8 @@ def make(session: nox.Session): args = parser.parse_args(session.posargs) install(session, req="requirements-relaxed" if args.relaxed else "requirements") - make_args: list[str] = [f"PYTHON={_env_python(session)}", *(args.make_args or ())] + make_args: list[str] = [ + f"PYTHON={_env_python(session)}", + *(args.make_args or ("clean", "coredocs")), + ] session.run("make", "-C", "docs/docsite", *make_args, external=True) From 554b35644e112f9e3b1ad0c8ba101e69a388b719 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Thu, 30 Nov 2023 17:09:05 +0000 Subject: [PATCH 114/536] README.md: document the nox make session --- README.md | 47 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index b88530961f9..5c8b79c389c 100644 --- a/README.md +++ b/README.md @@ -4,32 +4,33 @@ This repository holds the ReStructuredText (RST) source, and other files, for us > Documentation for modules and plugins that are officially supported by the Ansible Core engineering team is available in the [`ansible/ansible`](https://github.com/ansible/ansible) repository. -## Building Ansible community documentation - -Follow the documentation to [set up your environment](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally) and then [build Ansible community documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally) - ## Verifying your pull request We welcome all contributions to Ansible community documentation. If you plan to submit a pull request with changes, you should [verify your PR](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#verifying-your-documentation-pr) to ensure it conforms with style guidelines and can build successfully. -### Running automated tests +### Setting up nox This project includes a `nox` configuration to automate tests, checks, and other functions. You can use these automated tests to help you verify changes before you submit a PR. +You can manually +[set up your environment](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally) +if you prefer, but the `nox` configuration significantly simplifies this process. -1. Install `nox` using `python3 -m pip install nox` or your distribution's package manager. -2. Run `nox --list` from the repository root to view available sessions. +* Install `nox` using `python3 -m pip install nox` or your distribution's package manager. -Each `nox` session creates a temporary environment that installs all requirements and runs the test or check. -This means you only need to run one command to perform the test accurately and consistently. -The following are some of the `nox` sessions you can run: +* Execute `nox` from the repository root with no arguments to run + all docs checkers, Python code checkers, and a minimal HTML docs build. -* Run all available sessions. +* Alternatively, you can run only certain tasks as outlined in the following sections. + Run `nox --list` to view available sessions. - ``` - nox - ``` +### Building docs + +The different Makefile targets used to build the documentation are outlined in +[Building the documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally). +The `nox` configuration has a `make` session to automate setting up a docs build +environment and running the Makefile. * Clone required parts of the `ansible/ansible` repository. @@ -39,6 +40,22 @@ The following are some of the `nox` sessions you can run: See [Periodically cloning Ansible core](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#periodically-cloning-ansible-core) for more information. +* Run a minimal Ansible Core docs build. + + ``` + nox -s make + ``` + +* Run a specific Makefile target with options + + ``` + nox -s make -- clean htmlsingle rst=community/documentation_contributions.rst + ``` + +### Running automated tests + +The `nox` configuration also contains session to run automated docs checkers. + * Ensure there are no syntax errors in the reStructuredText source files. ``` @@ -63,7 +80,7 @@ The following are some of the `nox` sessions you can run: nox -s lint ``` -## Checking spelling +### Checking spelling Use [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source. From 696286e0fc92b05bc8931e11dc9e31b7ba86f25d Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Thu, 30 Nov 2023 17:16:03 +0000 Subject: [PATCH 115/536] README: declare bash syntax for codeblocks --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5c8b79c389c..220c2909a31 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ environment and running the Makefile. * Clone required parts of the `ansible/ansible` repository. - ``` + ``` bash nox -s clone-core ``` @@ -42,13 +42,13 @@ environment and running the Makefile. * Run a minimal Ansible Core docs build. - ``` + ``` bash nox -s make ``` * Run a specific Makefile target with options - ``` + ``` bash nox -s make -- clean htmlsingle rst=community/documentation_contributions.rst ``` @@ -58,7 +58,7 @@ The `nox` configuration also contains session to run automated docs checkers. * Ensure there are no syntax errors in the reStructuredText source files. - ``` + ``` bash nox -s "checkers(rstcheck)" ``` @@ -66,7 +66,7 @@ The `nox` configuration also contains session to run automated docs checkers. * Verify the docs build. - ``` + ``` bash nox -s "checkers(docs-build)" ``` @@ -76,7 +76,7 @@ The `nox` configuration also contains session to run automated docs checkers. * Lint, type check, and format Python scripts in this repository. - ``` + ``` bash nox -s lint ``` @@ -86,19 +86,19 @@ Use [`codespell`](https://github.com/codespell-project/codespell) to check for c * Check spelling. - ``` + ``` bash nox -s spelling ``` * Correct any detected spelling errors. - ``` + ``` bash nox -s spelling -- -w ``` * Select an option when `codespell` suggests more than one word as a correction. - ``` + ``` bash nox -s spelling -- -w -i 3 ``` @@ -120,7 +120,7 @@ For more details about using unpinned and tested dependencies for doc builds, se Use the following `nox` session to update the dependency lock files in `tests/`. - ``` + ``` bash nox -e pip-compile ``` From 352c8e9e472343bb9ebb70ff8946043ad1b23059 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Fri, 1 Dec 2023 11:50:25 -0600 Subject: [PATCH 116/536] improve nox make session docs Co-authored-by: Don Naro --- README.md | 9 ++++----- noxfile.py | 6 ++++-- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 220c2909a31..f4e6ace797e 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ This project includes a `nox` configuration to automate tests, checks, and other You can use these automated tests to help you verify changes before you submit a PR. You can manually [set up your environment](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#setting-up-your-environment-to-build-documentation-locally) -if you prefer, but the `nox` configuration significantly simplifies this process. +if you prefer, but `nox` is more straightforward and create an isolated environment for you. * Install `nox` using `python3 -m pip install nox` or your distribution's package manager. @@ -29,8 +29,7 @@ if you prefer, but the `nox` configuration significantly simplifies this process The different Makefile targets used to build the documentation are outlined in [Building the documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally). -The `nox` configuration has a `make` session to automate setting up a docs build -environment and running the Makefile. +The `nox` configuration has a `make` session that creates a build environment and uses the Makefile to generate HTML. * Clone required parts of the `ansible/ansible` repository. @@ -40,13 +39,13 @@ environment and running the Makefile. See [Periodically cloning Ansible core](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#periodically-cloning-ansible-core) for more information. -* Run a minimal Ansible Core docs build. +* Build minimal Ansible Core docs. ``` bash nox -s make ``` -* Run a specific Makefile target with options +* Run a specific Makefile target: ``` bash nox -s make -- clean htmlsingle rst=community/documentation_contributions.rst diff --git a/noxfile.py b/noxfile.py index 7ae44d0d86b..bc673dfff13 100644 --- a/noxfile.py +++ b/noxfile.py @@ -165,10 +165,12 @@ def checkers(session: nox.Session, test: str): @nox.session def make(session: nox.Session): """ - Run the docs build Makefile in an isolated environment + Generate HTML from documentation source using the Makefile """ parser = _relaxed_parser(session) - parser.add_argument("make_args", nargs="*", help="Arguments to pass on to make") + parser.add_argument( + "make_args", nargs="*", help="Specify make targets as arguments" + ) args = parser.parse_args(session.posargs) install(session, req="requirements-relaxed" if args.relaxed else "requirements") From 657be539343da13ea5e9333cc8662e27158f4fed Mon Sep 17 00:00:00 2001 From: Jaroslav Lichtblau Date: Mon, 4 Dec 2023 20:04:19 +0100 Subject: [PATCH 117/536] handlers notify example indentation fix (#915) --- docs/docsite/rst/playbook_guide/playbooks_handlers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst index 44a78a36f10..4d7c2d00a7a 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst @@ -33,7 +33,7 @@ This playbook, ``verify-apache.yml``, contains a single play with a handler. src: /srv/httpd.j2 dest: /etc/httpd.conf notify: - - Restart apache + - Restart apache - name: Ensure apache is running ansible.builtin.service: From e952dd436561bd801562e8f70e5db44caaa53097 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Mon, 4 Dec 2023 13:05:59 -0600 Subject: [PATCH 118/536] nox pip-compile: allow passing --no-upgrade flag (#883) * nox pip-compile: allow passing --no-upgrade flag This allows running `nox -e pip-compile -- --no-upgrade` to make sure that the requirements.txt files are in sync with the .in files but not updating any other transitive dependency. * README: make "## Updating dependencies" more concise Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- README.md | 6 ++++++ noxfile.py | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f4e6ace797e..0364ea347c2 100644 --- a/README.md +++ b/README.md @@ -123,6 +123,12 @@ Use the following `nox` session to update the dependency lock files in `tests/`. nox -e pip-compile ``` +To synchronize dependency lock files with base requirements files without changing transitive dependencies, use the `--no-upgrade` flag: + + ``` bash + nox -e pip-compile -- --no-upgrade + ``` + > This session requires Python 3.10. If you do not have Python 3.10 installed, you can use root-less podman with a Python 3.10 image as follows: diff --git a/noxfile.py b/noxfile.py index bc673dfff13..850045dbb9a 100644 --- a/noxfile.py +++ b/noxfile.py @@ -96,7 +96,7 @@ def pip_compile(session: nox.Session, req: str): # Use --upgrade by default unless a user passes -P. args = list(session.posargs) if not any( - arg.startswith("-P") or arg.startswith("--upgrade-package") for arg in args + arg.startswith(("-P", "--upgrade-package", "--no-upgrade")) for arg in args ): args.append("--upgrade") From 57764782a14b0d319530bcdad7514f383628cee9 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Mon, 4 Dec 2023 14:17:06 -0600 Subject: [PATCH 119/536] README: consistently use `nox -s` over `nox -e` (#923) Some examples use `nox -s` and others use `nox -e`. `-e` and `-s` are aliases, but we should stick to one for consistency. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0364ea347c2..e9392b53ba5 100644 --- a/README.md +++ b/README.md @@ -120,13 +120,13 @@ For more details about using unpinned and tested dependencies for doc builds, se Use the following `nox` session to update the dependency lock files in `tests/`. ``` bash - nox -e pip-compile + nox -s pip-compile ``` To synchronize dependency lock files with base requirements files without changing transitive dependencies, use the `--no-upgrade` flag: ``` bash - nox -e pip-compile -- --no-upgrade + nox -s pip-compile -- --no-upgrade ``` > This session requires Python 3.10. @@ -134,5 +134,5 @@ To synchronize dependency lock files with base requirements files without changi If you do not have Python 3.10 installed, you can use root-less podman with a Python 3.10 image as follows: ```bash -podman run --rm --tty --volume "$(pwd):/mnt:z" --workdir /mnt docker.io/library/python:3.10 bash -c 'pip install nox ; nox -e pip-compile' +podman run --rm --tty --volume "$(pwd):/mnt:z" --workdir /mnt docker.io/library/python:3.10 bash -c 'pip install nox ; nox -s pip-compile' ``` From 60c04b1ad0297f027af21b26589fcbc13a54561b Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 4 Dec 2023 16:55:54 -0600 Subject: [PATCH 120/536] ci: refresh dev dependencies (#914) --- tests/typing.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/typing.txt b/tests/typing.txt index 69277e1d82d..6b867b1d82f 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -18,9 +18,9 @@ click==8.1.7 # via typer codeowners==0.6.0 # via -r tests/../hacking/pr_labeler/requirements.txt -colorlog==6.7.0 +colorlog==6.8.0 # via nox -cryptography==41.0.5 +cryptography==41.0.7 # via pyjwt deprecated==1.2.14 # via pygithub @@ -74,7 +74,7 @@ urllib3==2.1.0 # via # pygithub # requests -virtualenv==20.24.7 +virtualenv==20.25.0 # via nox wrapt==1.16.0 # via deprecated From a5af353dc22caee40d1196cb744d02ba5aad66f4 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Tue, 5 Dec 2023 09:51:45 -0600 Subject: [PATCH 121/536] Add 2.14-2.16 devel porting guide entries for CVE-2023-5764 (#931) * Add porting guide for CVE-2023-5764 * Add porting guide for CVE-2023-5764 * Add porting guide for CVE-2023-5764 --- .../porting_guide_core_2.14.rst | 25 +++++++++++++++++++ .../porting_guide_core_2.15.rst | 24 +++++++++++++++++- .../porting_guide_core_2.16.rst | 24 ++++++++++++++++++ 3 files changed, 72 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.14.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.14.rst index c1325f74b83..bbfc66d1972 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.14.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.14.rst @@ -19,6 +19,31 @@ This document is part of a collection on porting. The complete list of porting g Playbook ======== +* Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.14.12, + conditional expressions with embedded template blocks can fail with the message + "``Conditional is marked as unsafe, and cannot be evaluated.``" when an embedded template + consults data from untrusted sources like module results or vars marked ``!unsafe``. + Conditionals with embedded templates can be a source of malicious template injection when + referencing untrusted data, and can nearly always be rewritten without embedded + templates. Playbook task conditional keywords such as ``when`` and ``until`` have long + displayed warnings discouraging use of embedded templates in conditionals; this warning + has been expanded to non-task conditionals as well, such as the ``assert`` action. + + .. code-block:: yaml + + - name: task with a module result (always untrusted by Ansible) + shell: echo "hi mom" + register: untrusted_result + + # don't do it this way... + # - name: insecure conditional with embedded template consulting untrusted data + # assert: + # that: '"hi mom" is in {{ untrusted_result.stdout }}' + + - name: securely access untrusted values directly as Jinja variables instead + assert: + that: '"hi mom" is in untrusted_result.stdout' + * Variables are now evaluated lazily; only when they are actually used. For example, in ansible-core 2.14 an expression ``{{ defined_variable or undefined_variable }}`` does not fail on ``undefined_variable`` if the first part of ``or`` is evaluated to ``True`` as it is not needed to evaluate the second part. One particular case of a change in behavior to note is the task below which uses the ``undefined`` test. Prior to version 2.14 this would result in a fatal error trying to access the undefined value in the dictionary. In 2.14 the assertion passes as the dictionary is evaluated as undefined through one of its undefined values: .. code-block:: yaml diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.15.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.15.rst index 8b4478cd1e4..8b560576b67 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.15.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.15.rst @@ -19,8 +19,30 @@ This document is part of a collection on porting. The complete list of porting g Playbook ======== -No notable changes +* Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.15.7, + conditional expressions with embedded template blocks can fail with the message + "``Conditional is marked as unsafe, and cannot be evaluated.``" when an embedded template + consults data from untrusted sources like module results or vars marked ``!unsafe``. + Conditionals with embedded templates can be a source of malicious template injection when + referencing untrusted data, and can nearly always be rewritten without embedded + templates. Playbook task conditional keywords such as ``when`` and ``until`` have long + displayed warnings discouraging use of embedded templates in conditionals; this warning + has been expanded to non-task conditionals as well, such as the ``assert`` action. + + .. code-block:: yaml + + - name: task with a module result (always untrusted by Ansible) + shell: echo "hi mom" + register: untrusted_result + + # don't do it this way... + # - name: insecure conditional with embedded template consulting untrusted data + # assert: + # that: '"hi mom" is in {{ untrusted_result.stdout }}' + - name: securely access untrusted values directly as Jinja variables instead + assert: + that: '"hi mom" is in untrusted_result.stdout' Command Line ============ diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.16.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.16.rst index de2b1d63bc3..d063da13565 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.16.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.16.rst @@ -19,6 +19,30 @@ This document is part of a collection on porting. The complete list of porting g Playbook ======== +* Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.16.1, + conditional expressions with embedded template blocks can fail with the message + "``Conditional is marked as unsafe, and cannot be evaluated.``" when an embedded template + consults data from untrusted sources like module results or vars marked ``!unsafe``. + Conditionals with embedded templates can be a source of malicious template injection when + referencing untrusted data, and can nearly always be rewritten without embedded + templates. Playbook task conditional keywords such as ``when`` and ``until`` have long + displayed warnings discouraging use of embedded templates in conditionals; this warning + has been expanded to non-task conditionals as well, such as the ``assert`` action. + + .. code-block:: yaml + + - name: task with a module result (always untrusted by Ansible) + shell: echo "hi mom" + register: untrusted_result + + # don't do it this way... + # - name: insecure conditional with embedded template consulting untrusted data + # assert: + # that: '"hi mom" is in {{ untrusted_result.stdout }}' + + - name: securely access untrusted values directly as Jinja variables instead + assert: + that: '"hi mom" is in untrusted_result.stdout' Command Line ============ From c1615925655ee976a920ebc196aa21548bd8655a Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Tue, 5 Dec 2023 18:02:30 +0100 Subject: [PATCH 122/536] Ansible 9: Follow ansible-core more closely (#856) * Ansible 9: Follow ansible-core more closely * Semicolon -> comma * Improvements from gotmax23 Co-authored-by: Maxwell G --------- Co-authored-by: Maxwell G --- docs/docsite/rst/roadmap/COLLECTIONS_9.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_9.rst b/docs/docsite/rst/roadmap/COLLECTIONS_9.rst index 242e6549bed..941e0909b31 100644 --- a/docs/docsite/rst/roadmap/COLLECTIONS_9.rst +++ b/docs/docsite/rst/roadmap/COLLECTIONS_9.rst @@ -67,7 +67,9 @@ You can install removed collections manually with ``ansible-galaxy collection in Ansible minor releases ======================= -Ansible 9.x minor releases will occur approximately every four weeks if changes to collections have been made or to align to a later ansible-core-2.16.x. Ansible 9.x minor releases may contain new features (including new collections) but not backwards incompatibilities. In practice, this means we will include new collection versions where either the patch or the minor version number has changed but not when the major number has changed. For example, if Ansible-9.0.0 ships with community.crypto 2.3.0; Ansible-9.1.0 could ship with community.crypto 2.4.0 but not community.crypto 3.0.0. +Ansible 9.x follows ansible-core-2.16.x releases, so releases will occur approximately every four weeks. If ansible-core delays a release for whatever reason, the next Ansible 9.x minor release will be delayed accordingly. + +Ansible 9.x minor releases may contain new features (including new collections) but not backwards incompatibilities. In practice, this means we will include new collection versions where either the patch or the minor version number has changed but not when the major number has changed. For example, if Ansible-9.0.0 ships with community.crypto 2.3.0, Ansible-9.1.0 could ship with community.crypto 2.4.0 but not community.crypto 3.0.0. .. note:: From 9d3c791eeb149c6411866fee2dbf8d3efe83ac9f Mon Sep 17 00:00:00 2001 From: Anwesha Das Date: Tue, 5 Dec 2023 13:00:33 +0000 Subject: [PATCH 123/536] Add Ansible community 9.1.0 porting guide --- .../rst/porting_guides/porting_guide_9.rst | 57 ++++++++++++++++--- 1 file changed, 50 insertions(+), 7 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 823129417a9..75d5d80142c 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -21,6 +21,30 @@ We suggest you read this page along with the `Ansible 9 Changelog Date: Tue, 5 Dec 2023 11:22:07 -0800 Subject: [PATCH 124/536] Proof reading II (#733) Co-authored-by: Maxwell G Signed-off-by: Abhijeet Kasurde --- .../collections_downloading.rst | 2 +- .../collections_installing.rst | 2 +- .../collections_guide/collections_listing.rst | 2 +- .../collections_using_playbooks.rst | 4 +- .../collections_verifying.rst | 4 +- .../collection_integration_about.rst | 6 +- .../collection_integration_updating.rst | 4 +- .../collection_release_with_branches.rst | 6 +- .../collection_release_without_branches.rst | 2 +- .../collection_releasing.rst | 6 +- .../collection_requirements.rst | 20 +++--- .../collection_reviewing.rst | 4 +- .../collection_unit_tests.rst | 2 +- .../collection_development_process.rst | 34 +++++----- docs/docsite/rst/community/communication.rst | 6 +- .../contributing_maintained_collections.rst | 4 +- .../rst/community/contributor_path.rst | 2 +- .../rst/community/create_pr_quick_start.rst | 10 +-- .../rst/community/maintainers_guidelines.rst | 4 +- .../rst/community/reporting_collections.rst | 2 +- .../steering_committee_membership.rst | 12 ++-- .../developing_collections_distributing.rst | 2 +- docs/docsite/rst/galaxy/dev_guide.rst | 2 +- .../getting_started/get_started_playbook.rst | 2 +- .../rst/module_plugin_guide/modules_intro.rst | 2 +- .../plugin_filtering_config.rst | 4 +- docs/docsite/rst/os_guide/index.rst | 4 +- docs/docsite/rst/os_guide/intro_bsd.rst | 14 ++-- docs/docsite/rst/os_guide/windows_dsc.rst | 8 +-- docs/docsite/rst/os_guide/windows_faq.rst | 10 +-- docs/docsite/rst/os_guide/windows_setup.rst | 40 +++++------ docs/docsite/rst/os_guide/windows_winrm.rst | 68 +++++++++---------- .../complex_data_manipulation.rst | 12 ++-- .../rst/playbook_guide/playbook_pathing.rst | 2 +- .../playbooks_advanced_syntax.rst | 4 +- .../rst/playbook_guide/playbooks_async.rst | 4 +- .../rst/playbook_guide/playbooks_debugger.rst | 16 ++--- .../playbooks_privilege_escalation.rst | 21 +++--- .../playbook_guide/playbooks_startnstep.rst | 2 +- .../playbook_guide/playbooks_strategies.rst | 30 ++++---- .../rst/playbook_guide/playbooks_tags.rst | 2 +- docs/docsite/rst/plugins/action.rst | 2 +- docs/docsite/rst/plugins/cache.rst | 6 +- docs/docsite/rst/plugins/callback.rst | 2 +- docs/docsite/rst/plugins/connection.rst | 6 +- docs/docsite/rst/plugins/filter.rst | 4 +- docs/docsite/rst/plugins/inventory.rst | 2 +- docs/docsite/rst/plugins/lookup.rst | 14 ++-- docs/docsite/rst/plugins/module.rst | 2 +- docs/docsite/rst/plugins/netconf.rst | 2 +- docs/docsite/rst/plugins/shell.rst | 2 +- docs/docsite/rst/plugins/strategy.rst | 16 +++-- docs/docsite/rst/plugins/terminal.rst | 2 +- .../rst/reference_appendices/logging.rst | 2 +- .../rst/scenario_guides/guide_azure.rst | 4 +- .../installing_older_collection.txt | 4 +- .../rst/tips_tricks/ansible_tips_tricks.rst | 10 +-- docs/docsite/rst/tips_tricks/index.rst | 2 +- docs/docsite/rst/tips_tricks/sample_setup.rst | 2 +- .../vault_guide/vault_managing_passwords.rst | 6 +- .../vault_using_encrypted_content.rst | 8 +-- 61 files changed, 245 insertions(+), 240 deletions(-) diff --git a/docs/docsite/rst/collections_guide/collections_downloading.rst b/docs/docsite/rst/collections_guide/collections_downloading.rst index ab17ce89412..4a804d594e8 100644 --- a/docs/docsite/rst/collections_guide/collections_downloading.rst +++ b/docs/docsite/rst/collections_guide/collections_downloading.rst @@ -10,7 +10,7 @@ are downloaded by default to the ``./collections`` folder. Just like the ``install`` command, the collections are sourced based on the :ref:`configured galaxy server config `. Even if a collection to download was specified by a URL -or path to a tarball, the collection will be redownloaded from the configured Galaxy server. +or path to a tarball, the collection will be re-downloaded from the configured Galaxy server. Collections can be specified as one or multiple collections or with a ``requirements.yml`` file just like ``ansible-galaxy collection install``. diff --git a/docs/docsite/rst/collections_guide/collections_installing.rst b/docs/docsite/rst/collections_guide/collections_installing.rst index 48da5a69013..50366b41928 100644 --- a/docs/docsite/rst/collections_guide/collections_installing.rst +++ b/docs/docsite/rst/collections_guide/collections_installing.rst @@ -23,7 +23,7 @@ Installing collections with ``ansible-galaxy`` Installing collections with signature verification --------------------------------------------------- -If a collection has been signed by a :term:`distribution server`, the server will provide ASCII armored, detached signatures to verify the authenticity of the ``MANIFEST.json`` before using it to verify the collection's contents. This option is not available on all distribution servers. See :ref:`distributing_collections` for a table listing which servers support collection signing. +If a collection has been signed by a :term:`distribution server`, the server will provide ASCII armored, detached signatures to verify the authenticity of the ``MANIFEST.json`` before using it to verify the collection's contents. This option is not available on all distribution servers. See :ref:`distributing_collections` for a table listing the servers that support collection signing. To use signature verification for signed collections: diff --git a/docs/docsite/rst/collections_guide/collections_listing.rst b/docs/docsite/rst/collections_guide/collections_listing.rst index 03cf125127d..a4de88a7162 100644 --- a/docs/docsite/rst/collections_guide/collections_listing.rst +++ b/docs/docsite/rst/collections_guide/collections_listing.rst @@ -3,7 +3,7 @@ Listing collections =================== -To list installed collections, run ``ansible-galaxy collection list``. This shows all of the installed collections found in the configured collections search paths. It will also show collections under development which contain a galaxy.yml file instead of a MANIFEST.json. The path where the collections are located are displayed as well as version information. If no version information is available, a ``*`` is displayed for the version number. +To list installed collections, run ``ansible-galaxy collection list``. This shows all of the installed collections found in the configured collections search paths. It will also show collections under development that contain a ``galaxy.yml`` file instead of a ``MANIFEST.json``. The path where the collections are located is displayed as well as version information. If no version information is available, a ``*`` is displayed for the version number. .. code-block:: shell diff --git a/docs/docsite/rst/collections_guide/collections_using_playbooks.rst b/docs/docsite/rst/collections_guide/collections_using_playbooks.rst index c5ba7ad5fbc..22f17477ece 100644 --- a/docs/docsite/rst/collections_guide/collections_using_playbooks.rst +++ b/docs/docsite/rst/collections_guide/collections_using_playbooks.rst @@ -85,7 +85,7 @@ In a playbook, you can control the collections Ansible searches for modules and ansible.builtin.debug: msg: '{{ lookup("my_namespace.my_collection.lookup1", "param1")| my_namespace.my_collection.filter1 }}' -The ``collections`` keyword merely creates an ordered 'search path' for non-namespaced plugin and role references. It does not install content or otherwise change Ansible's behavior around the loading of plugins or roles. Note that an FQCN is still required for non-action or module plugins (for example, lookups, filters, tests). +The ``collections`` keyword merely creates an ordered 'search path' for non-namespaced plugins and role references. It does not install content or otherwise change Ansible's behavior around the loading of plugins or roles. Note that an FQCN is still required for non-action or module plugins (for example, lookups, filters, and tests). When using the ``collections`` keyword, it is not necessary to add in ``ansible.builtin`` as part of the search list. When left omitted, the following content is available by default: @@ -132,4 +132,4 @@ This will have an implied entry in the ``collections:`` keyword of ``my_namespac Names can contain only lowercase alphanumeric characters, plus _ and must start with an alpha character. The dash ``-`` character is not valid for playbook names in collections. Playbooks whose names contain invalid characters are not addressable: this is a limitation of the Python importer that is used to load collection resources. - * Playbooks in collections do not support 'adjacent' plugins, all plugins must be in the collection specific directories. + * Playbooks in collections do not support 'adjacent' plugins, all plugins must be in the collection-specific directories. diff --git a/docs/docsite/rst/collections_guide/collections_verifying.rst b/docs/docsite/rst/collections_guide/collections_verifying.rst index e3f93d43d4c..ff36e816f5c 100644 --- a/docs/docsite/rst/collections_guide/collections_verifying.rst +++ b/docs/docsite/rst/collections_guide/collections_verifying.rst @@ -39,7 +39,7 @@ If you have a pre-release or non-latest version of a collection installed you sh ansible-galaxy collection verify my_namespace.my_collection:1.0.0 -In addition to the ``namespace.collection_name:version`` format, you can provide the collections to verify in a ``requirements.yml`` file. Dependencies listed in ``requirements.yml`` are not included in the verify process and should be verified separately. +In addition to the ``namespace.collection_name:version`` format, you can provide the collections to verify in a ``requirements.yml`` file. Dependencies listed in ``requirements.yml`` are not included in the ``verify`` process and should be verified separately. .. code-block:: bash @@ -52,7 +52,7 @@ Verifying against ``tar.gz`` files is not supported. If your ``requirements.yml` Verifying signed collections ----------------------------- -If a collection has been signed by a :term:`distribution server`, the server will provide ASCII armored, detached signatures to verify the authenticity of the MANIFEST.json before using it to verify the collection's contents. This option is not available on all distribution servers. See :ref:`distributing_collections` for a table listing which servers support collection signing. See :ref:`installing_signed_collections` for how to verify a signed collection when you install it. +If a collection has been signed by a :term:`distribution server`, the server will provide ASCII armored, detached signatures to verify the authenticity of the MANIFEST.json before using it to verify the collection's contents. This option is not available on all distribution servers. See :ref:`distributing_collections` for a table listing the servers that support collection signing. See :ref:`installing_signed_collections` for how to verify a signed collection when you install it. To verify a signed installed collection: diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst index 7733c4a9c73..c2904c21f81 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst @@ -80,7 +80,7 @@ If you use ``bash`` and the ``argcomplete`` package is installed with ``pip`` on ansible-test integration -Alternately, you can check if the ``tests/integration/targets`` directory contains a corresponding directory with the same name as the module. For example, the tests for the ``postgresql_user`` module of the ``community.postgresql`` collection are stored in the ``tests/integration/targets/postgresql_user`` directory of the collection repository. If there is no corresponding target there, then that module does not have integration tests. In this case, consider adding integration tests for the module. See :ref:`collection_creating_integration_tests` for details. +Alternatively, you can check if the ``tests/integration/targets`` directory contains a corresponding directory with the same name as the module. For example, the tests for the ``postgresql_user`` module of the ``community.postgresql`` collection are stored in the ``tests/integration/targets/postgresql_user`` directory of the collection repository. If there is no corresponding target there, then that module does not have integration tests. In this case, consider adding integration tests for the module. See :ref:`collection_creating_integration_tests` for details. .. _collection_integration_recommendations: @@ -91,9 +91,9 @@ Recommendations on coverage Bugfixes -------- -Before fixing code, create a test case in an :ref:`appropriate test target` that reproduces the bug provided by the issue reporter and described in the ``Steps to Reproduce`` issue section. :ref:`Run ` the tests. +Before fixing the code, create a test case in an :ref:`appropriate test target` that reproduces the bug provided by the issue reporter and described in the ``Steps to Reproduce`` issue section. :ref:`Run ` the tests. -If you failed to reproduce the bug, ask the reporter to provide additional information. The issue may be related to environment settings. Sometimes specific environment issues cannot be reproduced in integration tests, in that case, manual testing by issue reporter or other interested users is required. +If you failed to reproduce the bug, ask the reporter to provide additional information. The issue may be related to environment settings. Sometimes specific environment issues cannot be reproduced in integration tests, in that case, manual testing by the issue reporter or other interested users is required. Refactoring code ---------------- diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_updating.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_updating.rst index d8d8d187107..80f204c7447 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_integration_updating.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_integration_updating.rst @@ -30,7 +30,7 @@ We cloned the collection repository to the ``~/ansible_collections/community/pos We start with reproducing the bug. -First, we look into the ``tests/integration/targets/postgresql_user/tasks/main.yml`` file. In this particular case, the file imports other files from the ``tasks`` directory. The ``postgresql_user_general.yml`` looks like an appropriate one to add our tests. +First, we look into the ``tests/integration/targets/postgresql_user/tasks/main.yml`` file. In this particular case, the file imports other files from the ``tasks`` directory. The ``postgresql_user_general.yml`` looks like an appropriate one to add to our tests. .. code-block:: yaml @@ -93,7 +93,7 @@ The option is boolean. If set to ``yes``, it adds an additional attribute to a d We cloned the collection repository to the ``~/ansible_collections/community/postgresql`` directory and :ref:`prepared our environment`. From the collection's root directory, we run ``ansible-test integration --list-targets`` and it shows a target called ``postgresql_user``. Therefore, we already have some tests for the module. -First, we look at the ``tests/integration/targets//tasks/main.yml`` file. In this particular case, the file imports other files from the ``tasks`` directory. The ``postgresql_user_general.yml`` file looks like an appropriate one to add our tests. +First, we look at the ``tests/integration/targets//tasks/main.yml`` file. In this particular case, the file imports other files from the ``tasks`` directory. The ``postgresql_user_general.yml`` file looks like an appropriate one to add to our tests. .. code-block:: yaml diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst index f8ba7edf373..44d6e832b2a 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst @@ -221,7 +221,7 @@ Publishing the collection For every such deprecation, decide: - * Whether to remove them now. For example you remove the complete ``modules/plugins`` or you remove redirects. + * Whether to remove them now. For example, you remove the complete ``modules/plugins`` or you remove redirects. * Whether to add ignore entries to the corresponding ``tests/sanity/ignore-*.txt`` file and create issues, for example for removed features in ``modules/plugins``. Once the CI tests pass, merge the pull request. Make sure that this pull request is merged not too much later after the release @@ -235,7 +235,7 @@ Publishing the collection Releasing patch versions ------------------------- -The new version is assumed to be ``X.Y.Z``, and the previous patch version is assumed to be ``X.Y.z`` with ``z < Z``. ``z`` is frequently``0`` since patch releases are uncommon. +The new version is assumed to be ``X.Y.Z``, and the previous patch version is assumed to be ``X.Y.z`` with ``z < Z``. ``z`` is frequently ``0`` since patch releases are uncommon. Releasing when more minor versions are expected ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -286,7 +286,7 @@ Releasing when more minor versions are expected .. note:: The data for this release is only contained in a tag, and not in a branch, in particular not in ``stable-X``. - This is deliberate, since the next minor release ``X.(Y+1).0`` already contains the changes for ``X.Y.Z`` as well, since these were cherry-picked from ``stable-X``. + This is deliberate, since the next minor release ``X.(Y+1).0`` already contains the changes for ``X.Y.Z`` as well since these were cherry-picked from ``stable-X``. 4. Announce the release through the `Bullhorn Newsletter `_. diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst index 4cef33f03c8..74ec9fa58f7 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst @@ -69,7 +69,7 @@ Generating the changelog 2. If the content was recently moved from another collection (for example, migrating a module from one collection to another), ensure you have all related changelog fragments in the ``changelogs/fragments`` directory. If not, copy them previously. -3. Run ``antsibull-changelog release --reload-plugins`` . This package should previously be installed with ``pip install antsibull-changelog``. +3. Run ``antsibull-changelog release --reload-plugins`` . This package should be installed with ``pip install antsibull-changelog``. 4. Verify that the ``CHANGELOG.rst`` looks as expected. diff --git a/docs/docsite/rst/community/collection_contributors/collection_releasing.rst b/docs/docsite/rst/community/collection_contributors/collection_releasing.rst index 481208b007a..100042f0175 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_releasing.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_releasing.rst @@ -46,10 +46,10 @@ Collection versioning and deprecation To preserve backward compatibility for users, every Ansible minor version series (5.1.x, 5.2.x, and so on) will keep the major version of a collection constant. For example, if Ansible 5.0.0 includes ``community.general`` 4.0.2, then each Ansible 5.X.x release will include the latest ``community.general`` 4.y.z release available at build time. Ansible 5.x.x will **never** include a ``community.general`` 5.y.x release, even if it is available. Major collection version changes will be included in the next Ansible major release (6.0.0 in this case). Ensure that the current major release of your collection included in 6.0.0 receives at least bugfixes as long as new Ansible 6.X.X 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 `_. for more details. This means in particular: +Since new minor releases are included, you can include new features, modules and plugins. You must make sure that you do not break backward compatibility. See `semantic versioning `_. for more details. 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 add new features and deprecate things in **minor** releases, but not remove things or change the behavior of existing features. * You can only remove things or make breaking changes in **major** releases. Ensure that if a deprecation is added in a collection version that is included in 5.x.y, the removal itself will only happen in a collection version included in 7.0.0 or later. @@ -76,7 +76,7 @@ There are several approaches on how to release a collection. If you are not awar This section assumes that publishing the collection is done with `Zuul `_ and that `antsibull-changelog `_ is used for the changelog. Releasing without release branches -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use releasing without release branches when: diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 98cbcf446d4..f50338137a8 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -173,7 +173,7 @@ Modules & Plugins :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. + :sub_plugins: For other plugins that 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. @@ -200,11 +200,11 @@ 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. +* 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. +* 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 requests) 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. @@ -232,12 +232,12 @@ 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). +* 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: +* Since new minor releases are included, you can include new features, modules and plugins. You must make sure that you do not break backward 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 add new features and deprecate things in minor releases but not remove things or change the 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. @@ -387,7 +387,7 @@ CI Testing * 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. + * 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. @@ -432,8 +432,8 @@ 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. +* 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 no regular meetings) as a pinned issue in the repository. .. _coll_migrating_reqs: @@ -491,7 +491,7 @@ Collection 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 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 a collection depends on releases of 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 diff --git a/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst b/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst index 25f4f52a4f0..28aa8e1c083 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst @@ -47,7 +47,7 @@ Other standards to check for in a PR include: * 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. - * This is typically the next minor release, sometimes the next major release. For example: if 2.7.5 is the current release, the next minor release will be 2.8.0, and the next major release will be 3.0.0). + * This is typically the next minor release, sometimes the next major release. For example: if 2.7.5 is the current release, the next minor release will be 2.8.0, and the next major release will be 3.0.0). * FQCNs are used for ``extends_documentation_fragment:``, unless the author is referring to doc_fragments from ansible-core. * New features have corresponding examples in the :ref:`examples_block`. @@ -62,7 +62,7 @@ Review the following if tests are applicable and possible to implement for the c * Where applicable, the pull request has :ref:`testing_integration` and :ref:`testing_units`. * All changes are covered. For example, a bug case or a new option separately and in sensible combinations with other options. * Integration tests cover ``check_mode`` if supported. -* Integration tests check the actual state of the system, not only what the module reports. For example, if the module actually changes a file, check that the file was changed by using the ``ansible.builtin.stat`` module.. +* Integration tests check the actual state of the system, not only what the module reports. For example, if the module actually changes a file, check that the file was changed by using the ``ansible.builtin.stat`` module. * Integration tests check return values, if applicable. 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 7a758c50155..ea05a6190d4 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_unit_tests.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_unit_tests.rst @@ -38,7 +38,7 @@ Determine if unit tests exist Ansible collection unit tests are located in the ``tests/units`` directory. -The structure of the unit tests matches the structure of the code base, so the tests can reside in the ``tests/units/plugins/modules/`` and ``tests/units/plugins/module_utils`` directories. There can be sub-directories, if modules are organized by module groups. +The structure of the unit tests matches the structure of the code base, so the tests can reside in the ``tests/units/plugins/modules/`` and ``tests/units/plugins/module_utils`` directories. There can be sub-directories if modules are organized by module groups. If you are adding unit tests for ``my_module`` for example, check to see if the tests already exist in the collection source tree with the path ``tests/units/plugins/modules/test_my_module.py``. diff --git a/docs/docsite/rst/community/collection_development_process.rst b/docs/docsite/rst/community/collection_development_process.rst index 3c2f609cce7..c2f3279b87d 100644 --- a/docs/docsite/rst/community/collection_development_process.rst +++ b/docs/docsite/rst/community/collection_development_process.rst @@ -24,29 +24,29 @@ If you want to follow the conversation about what features will be added to the Micro development: the lifecycle of a PR ======================================== -If you want to contribute a feature or fix a bug in a collection, you must open a **pull request** ("PR" for short). GitHub provides a great overview of `how the pull request process works `_ in general. The ultimate goal of any pull request is to get merged and become part of a collection. Each collection has its own contributor guidelines so please check there for specific details. +If you want to contribute a feature or fix a bug in a collection, you must open a **pull request** ("PR" for short). GitHub provides a great overview of `how the pull request process works `_ in general. The ultimate goal of any pull request is to get merged and become part of a collection. Each collection has its own contributor guidelines so please check there for specific details. Here's an overview of the PR lifecycle: * :ref:`Contributor opens a PR ` * CI runs the test suite -* Developers, maintainers, community review the PR +* Developers, maintainers, and community review the PR * Contributor addresses any feedback from reviewers -* Developers, maintainers, community re-review +* Developers, maintainers, and community re-review * PR merged or closed Making your PR merge-worthy =========================== -We do not merge every PR. See :ref:`collection_quickstart` for tips to make your PR useful, attractive, and merge-worthy. +We do not merge every PR. See :ref:`collection_quickstart` for tips to make your PR useful, attractive, and merge-worthy. .. _collection_changelog_fragments: Creating changelog fragments ----------------------------- -Most changelogs should emphasize the impact of the change on the end user of the feature or collection, unless the change impacts developers directly. Consider what the user needs to know about this change and write the changelog to convey that detail. +Most changelogs should emphasize the impact of the change on the end user of the feature or collection unless the change impacts developers directly. Consider what the user needs to know about this change and write the changelog to convey that detail. Changelogs help users and developers keep up with changes to Ansible collections. Many collections build changelogs for each release from fragments. For collections that use this model, you **must** add a changelog fragment to any PR that changes functionality or fixes a bug. @@ -61,7 +61,7 @@ You do not need a changelog fragment for PRs that: More precisely: -* Every bugfix PR must have a changelog fragment. The only exception are fixes to a change that has not yet been included in a release. +* Every bugfix PR must have a changelog fragment. The only exception is fixes to a change that has not yet been included in a release. * Every feature PR must have a changelog fragment. * New modules and plugins (including jinja2 filter and test plugins) must have ``version_added`` entries set correctly in their documentation, and do not need a changelog fragment. The tooling detects new modules and plugins by their ``version_added`` values and announces them in the next release's changelog automatically. @@ -74,14 +74,14 @@ Creating a changelog fragment A basic changelog fragment is a ``.yaml`` or ``.yml`` file placed in the ``changelogs/fragments/`` directory. Each file contains a yaml dict with keys like ``bugfixes`` or ``major_changes`` followed by a list of changelog entries of bugfixes or features. Each changelog entry is rst embedded inside of the yaml file which means that certain constructs would need to be escaped so they can be interpreted by rst and not by yaml (or escaped for both yaml and rst if you prefer). Each PR **must** use a new fragment file rather than adding to an existing one, so we can trace the change back to the PR that introduced it. -PRs which add a new module or plugin do not necessarily need a changelog fragment. See :ref:`community_changelogs`. Also see :ref:`changelogs_how_to_format` for the precise format changelog fragments should have. +PRs that add a new module or plugin do not necessarily need a changelog fragment. See :ref:`community_changelogs`. Also see :ref:`changelogs_how_to_format` for the precise format changelog fragments should have. To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of the corresponding repository. The file name should include the PR number and a description of the change. It must end with the file extension ``.yaml`` or ``.yml``. For example: ``40696-user-backup-shadow-file.yaml`` A single changelog fragment may contain multiple sections but most will only contain one section. The toplevel keys (bugfixes, major_changes, and so on) are defined in the `config file `_ for our `release note tool `_. Here are the valid sections and a description of each: **breaking_changes** - MUST include changes that break existing playbooks or roles. This includes any change to existing behavior that forces users to update tasks. Breaking changes means the user MUST make a change when they update. Breaking changes MUST only happen in a major release of the collection. Write in present tense and clearly describe the new behavior that the end user must now follow. Displayed in both the changelogs and the :ref:`Porting Guides `. + MUST include changes that break existing playbooks or roles. This includes any change to existing behavior that forces users to update tasks. Breaking changes means the user MUST make a change when they update. Breaking changes MUST only happen in a major release of the collection. Write in the present tense and clearly describe the new behavior that the end user must now follow. Displayed in both the changelogs and the :ref:`Porting Guides `. .. code-block:: yaml @@ -90,15 +90,15 @@ A single changelog fragment may contain multiple sections but most will only con **major_changes** - Major changes to ansible-core or a collection. SHOULD NOT include individual module or plugin changes. MUST include non-breaking changes that impact all or most of a collection (for example, updates to support a new SDK version across the collection). Major changes mean the user can CHOOSE to make a change when they update but do not have to. Could be used to announce an important upcoming EOL or breaking change in a future release. (ideally 6 months in advance, if known. See `this example `_). Write in present tense and describe what is new. Optionally, include a 'Previously..." sentence to help the user identify where old behavior should now change. Displayed in both the changelogs and the :ref:`Porting Guides `. + Major changes to ansible-core or a collection. SHOULD NOT include individual module or plugin changes. MUST include non-breaking changes that impact all or most of a collection (for example, updates to support a new SDK version across the collection). Major changes mean the user can CHOOSE to make a change when they update but do not have to. Could be used to announce an important upcoming EOL or breaking change in a future release. (ideally, 6 months in advance, if known. See `this example `_). Write in the present tense and describe what is new. Optionally, include a 'Previously..." sentence to help the user identify where old behavior should now change. Displayed in both the changelogs and the :ref:`Porting Guides `. .. code-block:: yaml major_changes: - - bitbucket_* modules - client_id is no longer marked as ``no_log=true``. If you relied on its value not showing up in logs and output, mark the whole tasks with ``no_log: true`` (https://github.com/ansible-collections/community.general/pull/2045). + - bitbucket_* modules - client_id is no longer marked as ``no_log=true``. If you relied on its value not showing up in logs and output, mark the whole task with ``no_log: true`` (https://github.com/ansible-collections/community.general/pull/2045). **minor_changes** - Minor changes to ansible-core, modules, or plugins. This includes new parameters added to modules, or non-breaking behavior changes to existing parameters, such as adding new values to choices[]. Minor changes are enhancements, not bug fixes. Write in present tense. + Minor changes to ansible-core, modules, or plugins. This includes new parameters added to modules, or non-breaking behavior changes to existing parameters, such as adding new values to choices[]. Minor changes are enhancements, not bug fixes. Write in the present tense. .. code-block:: yaml @@ -107,7 +107,7 @@ A single changelog fragment may contain multiple sections but most will only con **deprecated_features** - Features that have been deprecated and are scheduled for removal in a future release. Write in past tense. Include an alternative, where available, for the feature being deprecated. Displayed in both the changelogs and the :ref:`Porting Guides `. + Features that have been deprecated and are scheduled for removal in a future release. Write in the past tense. Include an alternative, where available, for the feature being deprecated. Displayed in both the changelogs and the :ref:`Porting Guides `. .. code-block:: yaml @@ -116,7 +116,7 @@ A single changelog fragment may contain multiple sections but most will only con **removed_features** - Features that were previously deprecated and are now removed. Write in past tense. Include an alternative, where available, for the feature being deprecated. Displayed in both the changelogs and the :ref:`Porting Guides `. + Features that were previously deprecated and are now removed. Write in the past tense. Include an alternative, where available, for the feature being deprecated. Displayed in both the changelogs and the :ref:`Porting Guides `. .. code-block:: yaml @@ -125,7 +125,7 @@ A single changelog fragment may contain multiple sections but most will only con **security_fixes** - Fixes that address CVEs or resolve security concerns. MUST use security_fixes for any CVEs. Write in present tense. Include links to CVE information. + Fixes that address CVEs or resolve security concerns. MUST use security_fixes for any CVEs. Write in the present tense. Include links to CVE information. .. code-block:: yaml @@ -139,7 +139,7 @@ A single changelog fragment may contain multiple sections but most will only con .. code-block:: yaml bugfixes: - - apt_repository - fix crash caused by a timeout. The ``cache.update()`` was raising an ``IOError`` because of a timeout in ``apt update`` (https://github.com/ansible/ansible/issues/51995). + - apt_repository - fix crash caused by a timeout. The ``cache.update()`` was raising an ``IOError`` because of a timeout in ``apt update`` (https://github.com/ansible/ansible/issues/51995). **known_issues** @@ -152,7 +152,7 @@ A single changelog fragment may contain multiple sections but most will only con **trivial** - Changes where a formal release changelog entry isn't required. ``trivial`` changelog fragments are excluded from the published changelog output and may be used for changes such as housekeeping, documentation and test only changes. + Changes where a formal release changelog entry isn't required. ``trivial`` changelog fragments are excluded from the published changelog output and may be used for changes such as housekeeping, documentation and test-only changes. You can use ``trivial`` for collections that require a changelog fragment for each pull request. .. code-block:: yaml @@ -173,7 +173,7 @@ When writing a changelog entry, use the following format: .. code-block:: yaml - - scope - description starting with a lowercase letter and ending with a period at the very end. Multiple sentences are allowed (https://github.com/reference/to/an/issue or, if there is no issue, reference to a pull request itself). + - scope - description starting with a lowercase letter and ending with a period at the very end. Multiple sentences are allowed (https://github.com/reference/to/an/issue or if there is no issue, reference to a pull request itself). The scope is usually a module or plugin name or group of modules or plugins, for example, ``lookup plugins``. While module names can (and should) be mentioned directly (``foo_module``), plugin names should always be followed by the type (``foo inventory plugin``). diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index a4eebffd728..df67f648322 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -48,19 +48,19 @@ To join the community using Matrix, you need two things: * a Matrix account (from `Matrix.org `_ or any other Matrix homeserver) * a `Matrix client `_ (we recommend `Element Webchat `_) -The Ansible community maintains its own Matrix homeserver at ``ansible.im``, however public registration is currently unavailable. +The Ansible community maintains its own Matrix homeserver at ``ansible.im``, however, public registration is currently unavailable. Matrix chat supports: * persistence (when you log on, you see all messages since you last logged off) -* edits (Lets you fix typos and so on. **NOTE** Each edit you make on Matrix re-sends the message to IRC. Please try to avoid multiple edits!) +* edits (Let you fix typos and so on. **NOTE** Each edit you make on Matrix re-sends the message to IRC. Please try to avoid multiple edits!) * replies to individual users * reactions/emojis * bridging to IRC * no line limits * images -The room links in the :ref:`general_channels` or in the :ref:`working_group_list` list will take you directly to the relevant rooms. +The room links in the :ref:`general_channels` or the :ref:`working_group_list` list will take you directly to the relevant rooms. If there is no appropriate room for your community, please create it. diff --git a/docs/docsite/rst/community/contributing_maintained_collections.rst b/docs/docsite/rst/community/contributing_maintained_collections.rst index f7c0d1d9168..3df67f6f5e0 100644 --- a/docs/docsite/rst/community/contributing_maintained_collections.rst +++ b/docs/docsite/rst/community/contributing_maintained_collections.rst @@ -269,7 +269,7 @@ The following table shows: Deciding where your contribution belongs ========================================= -We welcome contributions to Ansible-maintained collections. Because these collections are part of a downstream supported Red Hat product, the criteria for contribution, testing, and release may be higher than other community collections. The related community collections (such as ``community.general`` and ``community.network``) have less-stringent requirements and are a great place for new functionality that may become part of the Ansible-maintained collection in a future release. +We welcome contributions to Ansible-maintained collections. Because these collections are part of a downstream-supported Red Hat product, the criteria for contribution, testing, and release may be higher than other community collections. The related community collections (such as ``community.general`` and ``community.network``) have less stringent requirements and are a great place for new functionality that may become part of the Ansible-maintained collection in a future release. The following scenarios use the ``arista.eos`` to help explain when to contribute to the Ansible-maintained collection, and when to propose your change or idea to the related community collection: @@ -299,6 +299,6 @@ Your PR must meet the following requirements before it can merge into an Ansible #. For network and security domains, the PR follows the :ref:`resource module development principles `. #. Passes :ref:`sanity tests and tox `. #. Passes unit, and integration tests, as listed in the :ref:`Ansible-maintained collection table ` and described in :ref:`testing_resource_modules`. -#. Follows Ansible guidelines. See :ref:`developing_modules` and :ref:`developing_collections`. +#. Follows Ansible guidelines. See :ref:`developing_modules` and :ref:`developing_collections`. #. Addresses all review comments. #. Includes an appropriate :ref:`changelog `. diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst index fde8f01230f..fb59a302f02 100644 --- a/docs/docsite/rst/community/contributor_path.rst +++ b/docs/docsite/rst/community/contributor_path.rst @@ -96,7 +96,7 @@ For some collections that use the `collection bot `_. +For information about permission levels, see the `GitHub official documentation `_. Become a steering committee member ================================== diff --git a/docs/docsite/rst/community/create_pr_quick_start.rst b/docs/docsite/rst/community/create_pr_quick_start.rst index b5a2a8d0b9a..c127c61a5f5 100644 --- a/docs/docsite/rst/community/create_pr_quick_start.rst +++ b/docs/docsite/rst/community/create_pr_quick_start.rst @@ -4,7 +4,7 @@ Creating your first collection pull request ******************************************** -This section describes all steps needed to create your first patch and submit a pull request on a collection. +This section describes all the steps needed to create your first patch and submit a pull request on a collection. .. _collection_prepare_local: @@ -142,7 +142,7 @@ If you need to run the tests against a specific distribution, see the :ref:`list If you are not sure whether you should use the default image for testing or a specific one, skip the entire step - the community can help you later. You can also try to use the collection repository's CI to figure out which containers are used. -If the tests ran successfully, there are usually two possible outcomes: +If the tests run successfully, there are usually two possible outcomes: - If the bug has not appeared and the tests have passed successfully, ask the reporter to provide more details. It may not be a bug or can relate to a particular software version used or specifics of the reporter's local environment configuration. - The bug has appeared and the tests have failed as expected showing the reported symptoms. @@ -232,11 +232,11 @@ Submit a pull request 4. Click the :guilabel:`Pull requests` tab. - GitHub is tracking your fork, so it should see the new branch in it and automatically offer to create a pull request. Sometimes GitHub does not do it, and you should click the :guilabel:`New pull request` button yourself. Then choose :guilabel:`compare across forks` under the :guilabel:`Compare changes` title. + GitHub is tracking your fork, so it should see the new branch in it and automatically offer to create a pull request. Sometimes GitHub does not do it, and you should click the :guilabel:`New pull request` button yourself. Then choose :guilabel:`compare across forks` under the :guilabel:`Compare changes` title. 5. Choose your repository and the new branch you pushed in the right drop-down list. Confirm. - a. Fill out the pull request template with all information you want to mention. + a. Fill out the pull request template with all the information you want to mention. b. Put ``Fixes + link to the issue`` in the pull request's description. @@ -261,7 +261,7 @@ Submit a pull request $ git commit -m "Add changelog fragment" $ git push origin name_of_my_branch -7. Verify the CI tests pass that run automatically on Red Hat infrastructure after every commit. +7. Verify the CI tests that run automatically on Red Hat infrastructure are successful after every commit. You will see the CI status at the bottom of your pull request. If they are green and you think that you do not want to add more commits before someone should take a closer look at it, remove ``[WIP]`` from the title. Mention the issue reporter in a comment and let contributors know that the pull request is "Ready for review". diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst index 4c3250c8a39..03fa5e8e270 100644 --- a/docs/docsite/rst/community/maintainers_guidelines.rst +++ b/docs/docsite/rst/community/maintainers_guidelines.rst @@ -121,7 +121,7 @@ Easy-fix items are the best way to attract and mentor new contributors. You shou For some easy-fix issues, you could ask the issue reporter whether they want to fix the issue themselves providing the link to a quick start guide for creating PRs. -Conduct pull request days regularly. You could plan PR days, for example, on the last Friday of every month when you and other maintainers go through all open issues and pull requests focusing on old ones, asking people if you can help, and so on. If there are pull requests that look abandoned (for example, there is no response on your help offers since the previous PR day), announce that anyone else interested can complete the pull request. +Conduct pull request days regularly. You could plan PR days, for example, on the last Friday of every month when you and other maintainers go through all open issues and pull requests focusing on old ones, asking people if you can help, and so on. If there are pull requests that look abandoned (for example, there has been no response on your help offers since the previous PR day), announce that anyone else interested can complete the pull request. Promote active contributors satisfying :ref:`requirements` to maintainers. Revise contributors' activity regularly. @@ -151,7 +151,7 @@ Maintainers look after the collection documentation to ensure it matches the :re * Collection user guides that follow the :ref:`Collection documentation format `. * Repository files that includes at least a ``README`` and ``CONTRIBUTING`` file. -A good ``README`` includes a description of the collection, a link to the :ref:`code_of_conduct`, and details on how to contribute or a pointer to the ``CONTRIBUTING`` file. If your collection is a part of Ansible (is shipped with Ansible package), highlight that fact at the top of the collection's ``README``. +A good ``README`` includes a description of the collection, a link to the :ref:`code_of_conduct`, and details on how to contribute or a pointer to the ``CONTRIBUTING`` file. If your collection is a part of Ansible (shipped with Ansible package), highlight that fact at the top of the collection's ``README``. The ``CONTRIBUTING`` file includes all the details or links to the details on how a new or continuing contributor can contribute to this collection. The ``CONTRIBUTING`` file should include: diff --git a/docs/docsite/rst/community/reporting_collections.rst b/docs/docsite/rst/community/reporting_collections.rst index 1d8c2e60f9f..fbcd6ca732e 100644 --- a/docs/docsite/rst/community/reporting_collections.rst +++ b/docs/docsite/rst/community/reporting_collections.rst @@ -25,7 +25,7 @@ Many bugs only affect a single module or plugin. If you find a bug that affects #. Click on the Issue Tracker link for that collection. #. Follow the contributor guidelines or instructions in the collection repo. -If you are not sure whether a bug is in ansible-core or in a collection, you can report the behavior on the :ref:`mailing list or community chat channel first `. +If you are not sure whether a bug is in ansible-core or a collection, you can report the behavior on the :ref:`mailing list or community chat channel first `. Requesting a feature ==================== diff --git a/docs/docsite/rst/community/steering/steering_committee_membership.rst b/docs/docsite/rst/community/steering/steering_committee_membership.rst index 0c1a19079d1..16922636a53 100644 --- a/docs/docsite/rst/community/steering/steering_committee_membership.rst +++ b/docs/docsite/rst/community/steering/steering_committee_membership.rst @@ -65,9 +65,9 @@ Voluntarily leaving the Steering Committee ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A Committee member can voluntarily leave the Committee. -In this case, they notify the other members, create an issue in the `Community Topics `_ repository announcing the resignation, and after that they are no longer considered Committee members. +In this case, they notify the other members, create an issue in the `Community Topics `_ repository announcing the resignation, and after that, they are no longer considered Committee members. -Committee members who resign and later change their mind can +Committee members who resign and later change their minds can rejoin the Committee by following the :ref:`Process for joining the Steering Committee`. Involuntarily leaving the Steering Committee @@ -93,7 +93,7 @@ In case of absence or irregular participation, the involuntarily removal process * The topic's title is ``Steering Committee member audit.``. It must not contain the person's name or other identifying information. - * The description must not contain or imply any forms of condemnation. + * The description must not contain or imply any form of condemnation. * It must mention that the person has been inactive for an unknown reason for the last N months and that, in accordance with the Steering Committee policies, their place should be freed for another person who can continue their great job. @@ -117,13 +117,13 @@ In case of the `Ansible Community Code of Conduct `_. Welcome to the Ansible guide for Microsoft Windows and BSD. -Because Windows is not a POSIX-compliant operating system, Ansible interacts with Windows hosts differently to Linux/Unix hosts. -Likewise managing hosts that run BSD is different to managing other Unix-like host operating systems. +Because Windows is not a POSIX-compliant operating system, Ansible interacts with Windows hosts differently than Linux/Unix hosts. +Likewise, managing hosts that run BSD is different than managing other Unix-like host operating systems. Find out everything you need to know about using Ansible on Windows and with BSD hosts. .. toctree:: diff --git a/docs/docsite/rst/os_guide/intro_bsd.rst b/docs/docsite/rst/os_guide/intro_bsd.rst index 7ee82ae8d4c..36ae0c9876b 100644 --- a/docs/docsite/rst/os_guide/intro_bsd.rst +++ b/docs/docsite/rst/os_guide/intro_bsd.rst @@ -11,8 +11,8 @@ Managing BSD machines is different from managing other Unix-like machines. If yo Connecting to BSD nodes ----------------------- -Ansible connects to managed nodes using OpenSSH by default. This works on BSD if you use SSH keys for authentication. However, if you use SSH passwords for authentication, Ansible relies on sshpass. Most -versions of sshpass do not deal well with BSD login prompts, so when using SSH passwords against BSD machines, use ``paramiko`` to connect instead of OpenSSH. You can do this in ansible.cfg globally or you can set it as an inventory/group/host variable. For example: +Ansible connects to managed nodes using OpenSSH by default. This works on BSD if you use SSH keys for authentication. However, if you use SSH passwords for authentication, Ansible relies on ``sshpass``. Most +versions of ``sshpass`` do not deal well with BSD login prompts, so when using SSH passwords against BSD machines, use ``paramiko`` to connect instead of OpenSSH. You can do this in ``ansible.cfg`` globally or you can set it as an inventory/group/host variable. For example: .. code-block:: text @@ -26,8 +26,8 @@ Bootstrapping BSD Ansible is agentless by default, however, it requires Python on managed nodes. Only the :ref:`raw ` module will operate without Python. Although this module can be used to bootstrap Ansible and install Python on BSD variants (see below), it is very limited and the use of Python is required to make full use of Ansible's features. -The following example installs Python which includes the json library required for full functionality of Ansible. -On your control machine you can execute the following for most versions of FreeBSD: +The following example installs Python which includes the json library required for the full functionality of Ansible. +On your control machine, you can execute the following for most versions of FreeBSD: .. code-block:: bash @@ -42,7 +42,7 @@ Or for OpenBSD: Once this is done you can now use other Ansible modules apart from the ``raw`` module. .. note:: - This example demonstrated using pkg on FreeBSD and pkg_add on OpenBSD, however you should be able to substitute the appropriate package tool for your BSD; the package name may also differ. Refer to the package list or documentation of the BSD variant you are using for the exact Python package name you intend to install. + This example demonstrated using pkg on FreeBSD and pkg_add on OpenBSD, however, you should be able to substitute the appropriate package tool for your BSD; the package name may also differ. Refer to the package list or documentation of the BSD variant you are using for the exact Python package name you intend to install. .. BSD_python_location: @@ -68,7 +68,7 @@ In FreeBSD, there is no guarantee that either ``/usr/local/bin/python`` executab This is a meta port to the Python 3.x interpreter and provides symbolic links to bin/python3, bin/pydoc3, bin/idle3 and so on to allow compatibility with - minor version agnostic python scripts. + minor version agnostic Python scripts. Quoting from */usr/ports/lang/python/pkg-descr*: @@ -269,7 +269,7 @@ Please feel free to report any issues or incompatibilities you discover with BSD :ref:`intro_adhoc` Examples of basic commands :ref:`working_with_playbooks` - Learning ansible's configuration management language + Learning Ansible's configuration management language :ref:`developing_modules` How to write modules `Mailing List `_ diff --git a/docs/docsite/rst/os_guide/windows_dsc.rst b/docs/docsite/rst/os_guide/windows_dsc.rst index 651548bcc4e..f140bf43f35 100644 --- a/docs/docsite/rst/os_guide/windows_dsc.rst +++ b/docs/docsite/rst/os_guide/windows_dsc.rst @@ -10,7 +10,7 @@ What is Desired State Configuration? ```````````````````````````````````` Desired State Configuration, or DSC, is a tool built into PowerShell that can be used to define a Windows host setup through code. The overall purpose of DSC -is the same as Ansible, it is just executed in a different manner. Since +is the same as Ansible, it is just executed differently. Since Ansible 2.4, the ``win_dsc`` module has been added and can be used to take advantage of existing DSC resources when interacting with a Windows host. @@ -327,7 +327,7 @@ modules can be installed to manage other resources that are not usually availabl Finding Custom DSC Resources ---------------------------- You can use the -`PSGallery `_ to find custom resources, along with documentation on how to install them on a Windows host. +`PSGallery `_ to find custom resources, along with documentation on how to install them on a Windows host. The ``Find-DscResource`` cmdlet can also be used to find custom resources. For example: @@ -366,7 +366,7 @@ with the ``resource_name`` option. The first two methods above only work when the host has access to the internet. When a host does not have internet access, the module must first be installed using the methods above on another host with internet access and then copied -across. To save a module to a local filepath, the following PowerShell cmdlet +across. To save a module to a local file path, the following PowerShell cmdlet can be run: .. code-block:: powershell @@ -501,7 +501,7 @@ Setup IIS Website :ref:`playbooks_best_practices` Tips and tricks for playbooks :ref:`List of Windows Modules ` - Windows specific module list, all implemented in PowerShell + Windows-specific module list, all implemented in PowerShell `User Mailing List `_ Have a question? Stop by the Google group! :ref:`communication_irc` diff --git a/docs/docsite/rst/os_guide/windows_faq.rst b/docs/docsite/rst/os_guide/windows_faq.rst index f4a8a1c8b68..231b5c661ed 100644 --- a/docs/docsite/rst/os_guide/windows_faq.rst +++ b/docs/docsite/rst/os_guide/windows_faq.rst @@ -3,7 +3,7 @@ Windows Frequently Asked Questions ================================== -Here are some commonly asked questions in regards to Ansible and Windows and +Here are some commonly asked questions in regard to Ansible and Windows and their answers. .. note:: This document covers questions about managing Microsoft Windows servers with Ansible. @@ -101,7 +101,7 @@ Ansible executes commands through WinRM. These processes are different from running a command locally in these ways: * Unless using an authentication option like CredSSP or Kerberos with - credential delegation, the WinRM process does not have the ability to + credential delegation, the WinRM process cannot delegate the user's credentials to a network resource, causing ``Access is Denied`` errors. @@ -130,7 +130,7 @@ Some ways to bypass these restrictions are to: CredSSP or Kerberos with credential delegation enabled. See :ref:`become` more info on how to use become. The limitations section at -:ref:`windows_winrm` has more details around WinRM limitations. +:ref:`windows_winrm` has more details about WinRM limitations. This program won't install on Windows with Ansible `````````````````````````````````````````````````` @@ -174,7 +174,7 @@ Ansible Windows modules exist in the :ref:`plugins_in_ansible.windows`, :ref:`pl Can I run Python modules on Windows hosts? `````````````````````````````````````````` No, the WinRM connection protocol is set to use PowerShell modules, so Python -modules will not work. A way to bypass this issue to use +modules will not work. A way to bypass this issue is to use ``delegate_to: localhost`` to run a Python module on the Ansible control node. This is useful if during a playbook, an external service needs to be contacted and there is no equivalent Windows module available. @@ -228,7 +228,7 @@ Why am I getting an error SSL CERTIFICATE_VERIFY_FAILED? When the Ansible control node is running on Python 2.7.9+ or an older version of Python that has backported SSLContext (like Python 2.7.5 on RHEL 7), the control node will attempt to validate the certificate WinRM is using for an HTTPS connection. If the -certificate cannot be validated (such as in the case of a self signed cert), it will +certificate cannot be validated (such as in the case of a self-signed cert), it will fail the verification process. To ignore certificate validation, add diff --git a/docs/docsite/rst/os_guide/windows_setup.rst b/docs/docsite/rst/os_guide/windows_setup.rst index 5e5cc95d925..38003b6d4e3 100644 --- a/docs/docsite/rst/os_guide/windows_setup.rst +++ b/docs/docsite/rst/os_guide/windows_setup.rst @@ -9,7 +9,7 @@ This document discusses the setup that is required before Ansible can communicat Host Requirements ````````````````` -For Ansible to communicate to a Windows host and use Windows modules, the +For Ansible to communicate with a Windows host and use Windows modules, the Windows host must meet these base requirements for connectivity: * With Ansible you can generally manage Windows versions under the current and extended support from Microsoft. You can also manage desktop OSs including Windows 10 and 11, and server OSs including Windows Server 2016, 2019, and 2022. @@ -22,8 +22,8 @@ Windows host must meet these base requirements for connectivity: Upgrading PowerShell and .NET Framework --------------------------------------- -Ansible requires PowerShell version 5.1 and .NET Framework 4.6 or newer to function. The base image for older unsupported OS' do not meet these -requirement. You can use the `Upgrade-PowerShell.ps1 `_ script to update these. +Ansible requires PowerShell version 5.1 and .NET Framework 4.6 or newer to function. The base image for older unsupported OS' does not meet these +requirements. You can use the `Upgrade-PowerShell.ps1 `_ script to update these. This is an example of how to run this script from PowerShell: @@ -64,9 +64,9 @@ Use the ``RemoteSigned`` value for Windows servers, or ``Restricted`` for Window The script determines what programs you need to install (such as .NET Framework 4.5.2) and what PowerShell version needs to be present. If a reboot is needed and the ``username`` and ``password`` parameters are set, the script will automatically reboot the machine and then logon. If the ``username`` and ``password`` parameters are not set, the script will prompt the user to manually reboot and logon when required. When the user is next logged in, the script will continue where it left off and the process continues until no more actions are required. -.. Note:: If you run the script on Server 2008, then you need to install SP2. For Server 2008 R2 or Windows 7 you need SP1. +.. Note:: If you run the script on Server 2008, then you need to install SP2. For Server 2008 R2 or Windows 7, you need SP1. - On Windows Server 2008 you can install only PowerShell 3.0. A newer version will result in the script failure. + On Windows Server 2008, you can install only PowerShell 3.0. A newer version will result in the script failure. The ``username`` and ``password`` parameters are stored in plain text in the registry. Run the cleanup commands after the script finishes to ensure no credentials are stored on the host. @@ -90,7 +90,7 @@ For more details, refer to the `"Out of memory" error on a computer that has a c WinRM Setup ``````````` -You need to configure the WinRM service so that Ansible can connect to it. There are two main components of the WinRM service that governs how Ansible can interface with the Windows host: the ``listener`` and the ``service`` configuration settings. +You need to configure the WinRM service so that Ansible can connect to it. There are two main components of the WinRM service that govern how Ansible can interface with the Windows host: the ``listener`` and the ``service`` configuration settings. .. _winrm_listener: @@ -134,9 +134,9 @@ In the example above there are two listeners activated. One is listening on port * ``Transport``: Whether the listener is run over HTTP or HTTPS. We recommend you use a listener over HTTPS because the data is encrypted without any further changes required. -* ``Port``: The port the listener runs on. By default it is ``5985`` for HTTP and ``5986`` for HTTPS. This port can be changed to whatever is required and corresponds to the host var ``ansible_port``. +* ``Port``: The port the listener runs on. By default, it is ``5985`` for HTTP and ``5986`` for HTTPS. This port can be changed to whatever is required and corresponds to the host var ``ansible_port``. -* ``URLPrefix``: The URL prefix to listen on. By default it is ``wsman``. If you change this option, you need to set the host var ``ansible_winrm_path`` to the same value. +* ``URLPrefix``: The URL prefix to listen on. By default, it is ``wsman``. If you change this option, you need to set the host var ``ansible_winrm_path`` to the same value. * ``CertificateThumbprint``: If you use an HTTPS listener, this is the thumbprint of the certificate in the Windows Certificate Store that is used in the connection. To get the details of the certificate itself, run this command with the relevant certificate thumbprint in PowerShell: @@ -149,7 +149,7 @@ Setup WinRM Listener ++++++++++++++++++++ There are three ways to set up a WinRM listener: -* Using ``winrm quickconfig`` for HTTP or ``winrm quickconfig -transport:https`` for HTTPS. This is the easiest option to use when running outside of a domain environment and a simple listener is required. Unlike the other options, this process also has the added benefit of opening up the firewall for the ports required and starts the WinRM service. +* Using ``winrm quickconfig`` for HTTP or ``winrm quickconfig -transport:https`` for HTTPS. This is the easiest option to use when running outside of a domain environment and a simple listener is required. Unlike the other options, this process also has the added benefit of opening up the firewall for the ports required and starting the WinRM service. * Using Group Policy Objects (GPO). This is the best way to create a listener when the host is a member of a domain because the configuration is done automatically without any user input. For more information on group policy objects, see the `Group Policy Objects documentation `_. @@ -276,7 +276,7 @@ For example, to change ``Winrs\MaxShellRunTime``: Set-Item -Path WSMan:\localhost\Shell\MaxShellRunTime -Value 2147483647 .. Note:: If you run the command in a domain environment, some of these options are set by - GPO and cannot be changed on the host itself. When you configured a key with GPO, it contains the text ``[Source="GPO"]`` next to the value. + GPO and cannot be changed on the host itself. When you configure a key with GPO, it contains the text ``[Source="GPO"]`` next to the value. Common WinRM Issues ------------------- @@ -318,7 +318,7 @@ connection. You can check the following to troubleshoot: * The credentials are correct and set properly in your inventory with the ``ansible_user`` and ``ansible_password`` variables. -* The user is a member of the local Administrators group, or has been explicitly granted access. You can perform a connection test with the ``winrs`` command to rule this out. +* The user is a member of the local Administrators group or has been explicitly granted access. You can perform a connection test with the ``winrs`` command to rule this out. * The authentication option set by the ``ansible_winrm_transport`` variable is enabled under ``Service\Auth\*``. @@ -346,10 +346,10 @@ Sometimes Ansible is unable to reach the host. These instances usually indicate Connection Refused Errors +++++++++++++++++++++++++ -When you communicate with the WinRM service on the host you can encounter some problems. Check the following to help the troubleshooting: +When you communicate with the WinRM service on the host you may encounter some problems. Check the following to help with the troubleshooting: * The WinRM service is up and running on the host. Use the ``(Get-Service -Name winrm).Status`` command to get the status of the service. -* The host firewall is allowing traffic over the WinRM port. By default this is ``5985`` for HTTP and ``5986`` for HTTPS. +* The host firewall is allowing traffic over the WinRM port. By default, this is ``5985`` for HTTP and ``5986`` for HTTPS. Sometimes an installer may restart the WinRM or HTTP service and cause this error. The best way to deal with this is to use the ``win_psexec`` module from another Windows host. @@ -375,7 +375,7 @@ See `KB4076842 `_ for more inf Windows SSH Setup ````````````````` -Ansible 2.8 has added an experimental SSH connection for Windows managed nodes. +Ansible 2.8 has added an experimental SSH connection for Windows-managed nodes. .. warning:: Use this feature at your own risk! Using SSH with Windows is experimental. This implementation may make @@ -383,7 +383,7 @@ Ansible 2.8 has added an experimental SSH connection for Windows managed nodes. Installing OpenSSH using Windows Settings ----------------------------------------- -You can use OpenSSH to connect Window 10 clients to Windows Server 2019. OpenSSH Client is available to install on Windows 10 build 1809 and later. OpenSSH Server is available to install on Windows Server 2019 and later. +You can use OpenSSH to connect Windows 10 clients to Windows Server 2019. OpenSSH Client is available to install on Windows 10 build 1809 and later. OpenSSH Server is available to install on Windows Server 2019 and later. For more information, refer to `Get started with OpenSSH for Windows `_. @@ -427,12 +427,12 @@ Ansible, select one of these installation options: - role: jborean93.win_openssh opt_openssh_setup_service: True -.. note:: ``Win32-OpenSSH`` is still a beta product and is constantly being updated to include new features and bugfixes. If you use SSH as a connection option for Windows, we highly recommend you install the latest version. +.. note:: ``Win32-OpenSSH`` is still a beta product and is constantly being updated to include new features and bug fixes. If you use SSH as a connection option for Windows, we highly recommend you install the latest version. Configuring the Win32-OpenSSH shell ----------------------------------- -By default ``Win32-OpenSSH`` uses ``cmd.exe`` as a shell. +By default, ``Win32-OpenSSH`` uses ``cmd.exe`` as a shell. * To configure a different shell, use an Ansible playbook with a task to define the registry setting: @@ -446,7 +446,7 @@ By default ``Win32-OpenSSH`` uses ``cmd.exe`` as a shell. type: string state: present -* To revert the settings back to the default shell: +* To revert the settings to the default shell: .. code-block:: yaml @@ -482,7 +482,7 @@ The ``ansible_shell_type`` variable should reflect the ``DefaultShell`` configur Known issues with SSH on Windows -------------------------------- -Using SSH with Windows is experimental. Currently existing issues are: +Using SSH with Windows is experimental. Currently, existing issues are: * Win32-OpenSSH versions older than ``v7.9.0.0p1-Beta`` do not work when ``powershell`` is the shell type. * While Secure Copy Protocol (SCP) should work, SSH File Transfer Protocol (SFTP) is the recommended mechanism to use when copying or fetching a file. @@ -494,7 +494,7 @@ Using SSH with Windows is experimental. Currently existing issues are: :ref:`playbooks_best_practices` Tips and tricks for playbooks :ref:`List of Windows Modules ` - Windows specific module list, all implemented in PowerShell + Windows-specific module list, all implemented in PowerShell `User Mailing List `_ Have a question? Stop by the Google group! :ref:`communication_irc` diff --git a/docs/docsite/rst/os_guide/windows_winrm.rst b/docs/docsite/rst/os_guide/windows_winrm.rst index fbebe93a71d..538f5c2db53 100644 --- a/docs/docsite/rst/os_guide/windows_winrm.rst +++ b/docs/docsite/rst/os_guide/windows_winrm.rst @@ -14,9 +14,9 @@ What is WinRM? ---------------- WinRM is a management protocol used by Windows to remotely communicate with -another server. It is a SOAP-based protocol that communicates over HTTP/HTTPS, and is +another server. It is a SOAP-based protocol that communicates over HTTP/HTTPS and is included in all recent Windows operating systems. Since Windows -Server 2012, WinRM has been enabled by default, but in most cases extra +Server 2012, WinRM has been enabled by default, but in most cases, extra configuration is required to use WinRM with Ansible. Ansible uses the `pywinrm `_ package to @@ -37,12 +37,12 @@ Or, if you chose the ``pip`` install instructions: pip install "pywinrm>=0.3.0" -.. Note:: on distributions with multiple python versions, use pip2 or pip2.x, - where x matches the python minor version Ansible is running under. +.. Note:: on distributions with multiple Python versions, use pip2 or pip2.x, + where x matches the Python minor version Ansible is running under. .. Warning:: Using the ``winrm`` or ``psrp`` connection plugins in Ansible on MacOS in - the latest releases typically fail. This is a known problem that occurs + the latest releases typically fails. This is a known problem that occurs deep within the Python stack and cannot be changed by Ansible. The only workaround today is to set the environment variable ``no_proxy=*`` and avoid using Kerberos auth. @@ -53,11 +53,11 @@ Or, if you chose the ``pip`` install instructions: WinRM authentication options ----------------------------- -When connecting to a Windows host, there are several different options that can be used +When connecting to a Windows host, several different options can be used when authenticating with an account. The authentication type may be set on inventory hosts or groups with the ``ansible_winrm_transport`` variable. -The following matrix is a high level overview of the options: +The following matrix is a high-level overview of the options: +-------------+----------------+---------------------------+-----------------------+-----------------+ | Option | Local Accounts | Active Directory Accounts | Credential Delegation | HTTP Encryption | @@ -78,7 +78,7 @@ The following matrix is a high level overview of the options: Basic ^^^^^^ -Basic authentication is one of the simplest authentication options to use, but is +Basic authentication is one of the simplest authentication options to use but is also the most insecure. This is because the username and password are simply base64 encoded, and if a secure channel is not in use (eg, HTTPS) then it can be decoded by anyone. Basic authentication can only be used for local accounts (not domain accounts). @@ -334,7 +334,7 @@ As of Ansible version 2.3, the Kerberos ticket will be created based on Ansible or when ``ansible_winrm_kinit_mode`` is ``manual``, a Kerberos ticket must already be obtained. See below for more details. -There are some extra host variables that can be set: +Some extra host variables can be set: .. code-block:: yaml @@ -342,14 +342,14 @@ There are some extra host variables that can be set: ansible_winrm_kinit_cmd: the kinit binary to use to obtain a Kerberos ticket (default to kinit) ansible_winrm_service: overrides the SPN prefix that is used, the default is ``HTTP`` and should rarely ever need changing ansible_winrm_kerberos_delegation: allows the credentials to traverse multiple hops - ansible_winrm_kerberos_hostname_override: the hostname to be used for the kerberos exchange + ansible_winrm_kerberos_hostname_override: the hostname to be used for the Kerberos exchange .. _winrm_kerberos_install: Installing the Kerberos Library +++++++++++++++++++++++++++++++ -Some system dependencies that must be installed prior to using Kerberos. The script below lists the dependencies based on the distro: +Some system dependencies must be installed before using Kerberos. The script below lists the dependencies based on the distro: .. code-block:: shell @@ -460,7 +460,7 @@ when both ``ansible_user`` and ``ansible_password`` are specified for a host. In this process, a new ticket is created in a temporary credential cache for each host. This is done before each task executes to minimize the chance of ticket expiration. The temporary credential caches are deleted after each task -completes and will not interfere with the default credential cache. +is completed and will not interfere with the default credential cache. To disable automatic ticket management, set ``ansible_winrm_kinit_mode=manual`` through the inventory. @@ -501,7 +501,7 @@ To destroy all the tickets that have been acquired, use the following command: Troubleshooting Kerberos ++++++++++++++++++++++++ -Kerberos is reliant on a properly-configured environment to +Kerberos is reliant on a properly configured environment to work. To troubleshoot Kerberos issues, ensure that: * The hostname set for the Windows host is the FQDN and not an IP address. @@ -509,12 +509,12 @@ work. To troubleshoot Kerberos issues, ensure that: * To determine if you are connecting using an IP address or an FQDN run your playbook (or call the ``win_ping`` module) using the `-vvv` flag. * The forward and reverse DNS lookups are working properly in the domain. To - test this, ping the windows host by name and then use the ip address returned + test this, ping the Windows host by name and then use the IP address returned with ``nslookup``. The same name should be returned when using ``nslookup`` on the IP address. * The Ansible host's clock is synchronized with the AD domain controller. Kerberos - is time sensitive, and a little clock drift can cause the ticket generation + is time-sensitive, and a little clock drift can cause the ticket generation process to fail. * Ensure that the fully qualified domain name for the domain is configured in @@ -529,7 +529,7 @@ work. To troubleshoot Kerberos issues, ensure that: an alias is being used. The ``krb5.conf`` file needs to be updated so that the fully qualified domain name is used and not an alias. -* If the default kerberos tooling has been replaced or modified (some IdM solutions may do this), this may cause issues when installing or upgrading the Python Kerberos library. As of the time of this writing, this library is called ``pykerberos`` and is known to work with both MIT and Heimdal Kerberos libraries. To resolve ``pykerberos`` installation issues, ensure the system dependencies for Kerberos have been met (see: `Installing the Kerberos Library`_), remove any custom Kerberos tooling paths from the PATH environment variable, and retry the installation of Python Kerberos library package. +* If the default Kerberos tooling has been replaced or modified (some IdM solutions may do this), this may cause issues when installing or upgrading the Python Kerberos library. As of the time of this writing, this library is called ``pykerberos`` and is known to work with both MIT and Heimdal Kerberos libraries. To resolve ``pykerberos`` installation issues, ensure the system dependencies for Kerberos have been met (see: `Installing the Kerberos Library`_), remove any custom Kerberos tooling paths from the PATH environment variable, and retry the installation of Python Kerberos library package. .. _winrm_credssp: @@ -557,7 +557,7 @@ To use CredSSP authentication, the host vars are configured like so: ansible_connection: winrm ansible_winrm_transport: credssp -There are some extra host variables that can be set as shown below: +Some extra host variables that can be set as shown below: .. code-block:: yaml @@ -586,7 +586,7 @@ The ``requests-credssp`` wrapper can be installed using ``pip``: CredSSP and TLS 1.2 +++++++++++++++++++ -By default the ``requests-credssp`` library is configured to authenticate over +By default, the ``requests-credssp`` library is configured to authenticate over the TLS 1.2 protocol. TLS 1.2 is installed and enabled by default for Windows Server 2012 and Windows 8 and more recent releases. @@ -649,9 +649,9 @@ tasks require some level of administrative access, so the utility is usually lim WinRM Encryption ----------------- -By default WinRM will fail to work when running over an unencrypted channel. +By default, WinRM will fail to work when running over an unencrypted channel. The WinRM protocol considers the channel to be encrypted if using TLS over HTTP -(HTTPS) or using message level encryption. Using WinRM with TLS is the +(HTTPS) or using message-level encryption. Using WinRM with TLS is the recommended option as it works with all authentication options, but requires a certificate to be created and used on the WinRM listener. @@ -670,8 +670,8 @@ in the host vars. A last resort is to disable the encryption requirement on the Windows host. This should only be used for development and debugging purposes, as anything sent -from Ansible can be viewed, manipulated and also the remote session can completely -be taken over by anyone on the same network. To disable the encryption +from Ansible can be viewed or manipulated, and the remote session can +be completely taken over by anyone on the same network. To disable the encryption requirement: .. code-block:: powershell @@ -733,7 +733,7 @@ for additional configuration of WinRM connections: * ``ansible_winrm_transport``: Specify one or more authentication transport options as a comma-separated list. By default, Ansible will use ``kerberos, basic`` if the ``kerberos`` module is installed and a realm is defined, - otherwise it will be ``plaintext`` + otherwise, it will be ``plaintext`` * ``ansible_winrm_server_cert_validation``: Specify the server certificate validation mode (``ignore`` or ``validate``). Ansible defaults to @@ -762,7 +762,7 @@ for additional configuration of WinRM connections: * ``ansible_winrm_send_cbt``: When using ``ntlm`` or ``kerberos`` over HTTPS, the authentication library will try to send channel binding tokens to - mitigate against man in the middle attacks. This flag controls whether these + mitigate against man-in-the-middle attacks. This flag controls whether these bindings will be sent or not (default: ``true``). * ``ansible_winrm_*``: Any additional keyword arguments supported by @@ -790,7 +790,7 @@ IPv6 Addresses IPv6 addresses can be used instead of IPv4 addresses or hostnames. This option is normally set in an inventory. Ansible will attempt to parse the address using the `ipaddress `_ -package and pass to pywinrm correctly. +package and pass to ``pywinrm`` correctly. When defining a host using an IPv6 address, just add the IPv6 address as you would an IPv4 address or hostname: @@ -819,11 +819,11 @@ As part of the TLS protocol, the certificate is validated to ensure the host matches the subject and the client trusts the issuer of the server certificate. When using a self-signed certificate or setting ``ansible_winrm_server_cert_validation: ignore`` these security mechanisms are -bypassed. While self signed certificates will always need the ``ignore`` flag, +bypassed. While self-signed certificates will always need the ``ignore`` flag, certificates that have been issued from a certificate authority can still be validated. -One of the more common ways of setting up a HTTPS listener in a domain +One of the more common ways of setting up an HTTPS listener in a domain environment is to use Active Directory Certificate Service (AD CS). AD CS is used to generate signed certificates from a Certificate Signing Request (CSR). If the WinRM HTTPS listener is using a certificate that has been signed by @@ -831,7 +831,7 @@ another authority, like AD CS, then Ansible can be set up to trust that issuer as part of the TLS handshake. To get Ansible to trust a Certificate Authority (CA) like AD CS, the issuer -certificate of the CA can be exported as a PEM encoded certificate. This +certificate of the CA can be exported as a PEM-encoded certificate. This certificate can then be copied locally to the Ansible control node and used as a source of certificate validation, otherwise known as a CA chain. @@ -984,8 +984,8 @@ from Nartac Software. WinRM limitations ------------------ -Due to the design of the WinRM protocol , there are a few limitations -when using WinRM that can cause issues when creating playbooks for Ansible. +Due to the design of the WinRM protocol, there are a few limitations +when using WinRM which can cause issues when creating playbooks for Ansible. These include: * Credentials are not delegated for most authentication types, which causes @@ -995,7 +995,7 @@ These include: * Many calls to the Windows Update API are blocked when running over WinRM. * Some programs fail to install with WinRM due to no credential delegation or - because they access forbidden Windows API like WUA over WinRM. + because they access forbidden Windows APIs like WUA over WinRM. * Commands under WinRM are done under a non-interactive session, which can prevent certain commands or executables from running. @@ -1006,7 +1006,7 @@ These include: Some of these limitations can be mitigated by doing one of the following: * Set ``ansible_winrm_transport`` to ``credssp`` or ``kerberos`` (with - ``ansible_winrm_kerberos_delegation=true``) to bypass the double hop issue + ``ansible_winrm_kerberos_delegation=true``) to bypass the double-hop issue and access network resources * Use ``become`` to bypass all WinRM restrictions and run a command as it would @@ -1014,7 +1014,7 @@ Some of these limitations can be mitigated by doing one of the following: also remove the non-interactive restriction and API restrictions like WUA and DPAPI -* Use a scheduled task to run a command which can be created with the +* Use a scheduled task to run a command that can be created with the ``win_scheduled_task`` module. Like ``become``, this bypasses all WinRM restrictions but can only run a command and not modules. @@ -1026,7 +1026,7 @@ Some of these limitations can be mitigated by doing one of the following: :ref:`playbooks_best_practices` Tips and tricks for playbooks :ref:`List of Windows Modules ` - Windows specific module list, all implemented in PowerShell + Windows-specific module list, all implemented in PowerShell `User Mailing List `_ Have a question? Stop by the Google group! :ref:`communication_irc` diff --git a/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst b/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst index d828bd42204..d311979b275 100644 --- a/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst +++ b/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst @@ -3,7 +3,7 @@ Manipulating data ################# -In many cases, you need to do some complex operation with your variables, while Ansible is not recommended as a data processing/manipulation tool, you can use the existing Jinja2 templating in conjunction with the many added Ansible filters, lookups and tests to do some very complex transformations. +In many cases, you will need to perform complex operations with your variables. While Ansible is not recommended as a data processing/manipulation tool, you can use the existing Jinja2 templating in conjunction with the many added Ansible filters, lookups and tests to perform some very complex transformations. Let's start with a quick definition of each type of plugin: - lookups: Mainly used to query 'external data', in Ansible these were the primary part of loops using the ``with_`` construct, but they can be used independently to return data for processing. They normally return a list due to their primary function in loops as mentioned previously. Used with the ``lookup`` or ``query`` Jinja2 operators. @@ -114,7 +114,7 @@ Find mount point In this case, we want to find the mount point for a given path across our machines, since we already collect mount facts, we can use the following: .. code-block:: YAML+Jinja - :caption: Use selectattr to filter mounts into list I can then sort and select the last from + :caption: Use selectattr to filter mounts into the list I can then sort and select the last from :emphasize-lines: 8 - hosts: all @@ -169,7 +169,7 @@ Another way is to avoid adding elements to the list in the first place, so you c Combine values from same list of dicts --------------------------------------- -Combining positive and negative filters from examples above, you can get a 'value when it exists' and a 'fallback' when it doesn't. +Combining positive and negative filters from the examples above, you can get a 'value when it exists' and a 'fallback' when it doesn't. .. code-block:: YAML+Jinja :caption: Use selectattr and rejectattr to get the ansible_host or inventory_hostname as needed @@ -225,7 +225,7 @@ You can use loops and list comprehensions as shown above to help, also other fil Create dictionary from list --------------------------- -In most languages it is easy to create a dictionary (a.k.a. map/associative array/hash and so on) from a list of pairs, in Ansible there are a couple of ways to do it and the best one for you might depend on the source of your data. +In most languages, it is easy to create a dictionary (also known as map/associative array/hash and so on) from a list of pairs. In Ansible there are a couple of ways to do it, and the best one for you might depend on the source of your data. These example produces ``{"a": "b", "c": "d"}`` @@ -292,7 +292,7 @@ A quick explanation, since there is a lot to unpack from these two lines: - The dict function then takes this 'list of pairs' to create the dictionary. -An example on how to use facts to find a host's data that meets condition X: +An example of how to use facts to find a host's data that meets condition X: .. code-block:: YAML+Jinja @@ -300,7 +300,7 @@ An example on how to use facts to find a host's data that meets condition X: vars: uptime_of_host_most_recently_rebooted: "{{ansible_play_hosts_all | map('extract', hostvars, 'ansible_uptime_seconds') | sort | first}}" -An example to show a host uptime in days/hours/minutes/seconds (assumes facts were gathered). +An example to show a host uptime in days/hours/minutes/seconds (assuming facts were gathered). .. code-block:: YAML+Jinja diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index 11df3cc068d..9fcd0429059 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -12,7 +12,7 @@ You can control the paths Ansible searches to find resources on your control nod Config paths ============ -By default these should be relative to the config file, some are specifically relative to the current working directory or the playbook and should have this noted in their description. Things like ssh keys are left to use the current working directory because it mirrors how the underlying tools would use it. +By default, these should be relative to the config file. Some are specifically relative to the current working directory or the playbook and should have this noted in their description. Things like SSH keys are left to use the current working directory because it mirrors how the underlying tools would use it. .. _playbook_task_paths: diff --git a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst index 1a84cb41e29..f76260e4e3b 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst @@ -49,7 +49,7 @@ For complex variables such as hashes or arrays, use ``!unsafe`` on the individua YAML anchors and aliases: sharing variable values ================================================= -`YAML anchors and aliases `_ help you define, maintain, and use shared variable values in a flexible way. +`YAML anchors and aliases `_ help you define, maintain, and flexibly use shared variable values. You define an anchor with ``&``, then refer to it using an alias, denoted with ``*``. Here's an example that sets three values with an anchor, uses two of those values with an alias, and overrides the third value: .. code-block:: yaml @@ -108,7 +108,7 @@ Now, you can reuse the value of ``app_version`` within the value of ``custom_na ansible.builtin.debug: msg: My app is called "{{ webapp.custom_name | join('-') }}". -You've anchored the value of ``version`` with the ``&my_version`` anchor, and re-used it with the ``*my_version`` alias. Anchors and aliases let you access nested values inside dictionaries. +You've anchored the value of ``version`` with the ``&my_version`` anchor and reused it with the ``*my_version`` alias. Anchors and aliases let you access nested values inside dictionaries. .. seealso:: diff --git a/docs/docsite/rst/playbook_guide/playbooks_async.rst b/docs/docsite/rst/playbook_guide/playbooks_async.rst index 87842db72b9..7ce38faf979 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_async.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_async.rst @@ -3,7 +3,7 @@ Asynchronous actions and polling ================================ -By default Ansible runs tasks synchronously, holding the connection to the remote node open until the action is completed. This means within a playbook, each task blocks the next task by default, meaning subsequent tasks will not run until the current task completes. This behavior can create challenges. For example, a task may take longer to complete than the SSH session allows for, causing a timeout. Or you may want a long-running process to execute in the background while you perform other tasks concurrently. Asynchronous mode lets you control how long-running tasks execute. +By default, Ansible runs tasks synchronously, holding the connection to the remote node open until the action is completed. This means that, within a playbook, each task blocks the next task by default, and subsequent tasks will not run until the current task is completed. This behavior can create challenges. For example, a task may take longer to complete than the SSH session allows for, causing a timeout. Or you may want a long-running process to execute in the background while you perform other tasks concurrently. Asynchronous mode lets you control how long-running tasks are executed. .. contents:: :local: @@ -102,7 +102,7 @@ To run a playbook task asynchronously: Using a higher value for ``--forks`` will result in kicking off asynchronous tasks even faster. This also increases the efficiency of polling. .. note:: - When running with ``poll: 0``, Ansible will not automatically cleanup the async job cache file. + When running with ``poll: 0``, Ansible will not automatically clean up the async job cache file. You will need to manually clean this up with the :ref:`async_status ` module with ``mode: cleanup``. diff --git a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst index 97e6463d3dc..4f32c04a2d0 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst @@ -45,7 +45,7 @@ You can use the ``debugger`` keyword to enable (or disable) the debugger for a s ========================= ====================================================== -When you use the ``debugger`` keyword, the value you specify overrides any global configuration to enable or disable the debugger. If you define ``debugger`` at multiple levels, such as in a role and in a task, Ansible honors the most granular definition. The definition at the play or role level applies to all blocks and tasks within that play or role, unless they specify a different value. The definition at the block level overrides the definition at the play or role level, and applies to all tasks within that block, unless they specify a different value. The definition at the task level always applies to the task; it overrides the definitions at the block, play, or role level. +When you use the ``debugger`` keyword, the value you specify overrides any global configuration to enable or disable the debugger. If you define ``debugger`` at multiple levels, such as in a role and in a task, Ansible honors the most granular definition. The definition at the play or role level applies to all blocks and tasks within that play or role unless they specify a different value. A definition at the block level overrides a definition at the play or role level and applies to all tasks within that block unless they specify a different value. A definition at the task level always applies to the task; it overrides definitions at the block, play, or role level. Examples of using the ``debugger`` keyword ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -82,16 +82,16 @@ Example of setting the ``debugger`` keyword at multiple levels: ansible.builtin.command: "false" debugger: on_failed -In this example, the debugger is set to ``never`` at the play level and to ``on_failed`` at the task level. If the task fails, Ansible invokes the debugger, because the definition on the task overrides the definition on its parent play. +In this example, the debugger is set to ``never`` at the play level and to ``on_failed`` at the task level. If the task fails, Ansible invokes the debugger, because the task's definition overrides that of its parent play. Enabling the debugger in configuration or an environment variable ----------------------------------------------------------------- .. versionadded:: 2.5 -You can enable the task debugger globally with a setting in ansible.cfg or with an environment variable. The only options are ``True`` or ``False``. If you set the configuration option or environment variable to ``True``, Ansible runs the debugger on failed tasks by default. +You can enable the task debugger globally with a setting in ``ansible.cfg`` or with an environment variable. The only options are ``True`` or ``False``. If you set the configuration option or environment variable to ``True``, Ansible runs the debugger on failed tasks by default. -To enable the task debugger from ansible.cfg, add this setting to the defaults section: +To enable the task debugger from ``ansible.cfg``, add this setting to the ``[defaults]`` section: .. code-block:: yaml @@ -109,7 +109,7 @@ When you enable the debugger globally, every failed task invokes the debugger, u Enabling the debugger as a strategy ----------------------------------- -If you are running legacy playbooks or roles, you may see the debugger enabled as a :ref:`strategy `. You can do this at the play level, in ansible.cfg, or with the environment variable ``ANSIBLE_STRATEGY=debug``. For example: +If you are running legacy playbooks or roles, you may see the debugger enabled as a :ref:`strategy `. You can do this at the play level, in ``ansible.cfg``, or with the environment variable ``ANSIBLE_STRATEGY=debug``. For example: .. code-block:: yaml @@ -260,7 +260,7 @@ Update args command - name: Install a package ansible.builtin.apt: name={{ pkg_name }} -When you run the playbook, the invalid package name triggers an error, and Ansible invokes the debugger. You can fix the package name by viewing, then updating the module argument. +When you run the playbook, the invalid package name triggers an error, and Ansible invokes the debugger. You can fix the package name by viewing, and then updating the module argument. .. code-block:: ansible-output @@ -278,7 +278,7 @@ After you update the module argument, use ``redo`` to run the task again with th Update vars command ------------------- -``task_vars[*key*] = *value*`` updates the ``task_vars``. You could fix the playbook above by viewing, then updating the task variables instead of the module args. +``task_vars[*key*] = *value*`` updates the ``task_vars``. You could fix the playbook above by viewing and then updating the task variables instead of the module args. .. code-block:: ansible-output @@ -328,7 +328,7 @@ Quit command How the debugger interacts with the free strategy ================================================= -With the default ``linear`` strategy enabled, Ansible halts execution while the debugger is active, and runs the debugged task immediately after you enter the ``redo`` command. With the ``free`` strategy enabled, however, Ansible does not wait for all hosts, and may queue later tasks on one host before a task fails on another host. With the ``free`` strategy, Ansible does not queue or execute any tasks while the debugger is active. However, all queued tasks remain in the queue and run as soon as you exit the debugger. If you use ``redo`` to reschedule a task from the debugger, other queued tasks may execute before your rescheduled task. For more information about strategies, see :ref:`playbooks_strategies`. +With the default ``linear`` strategy enabled, Ansible halts execution while the debugger is active, and runs the debugged task immediately after you enter the ``redo`` command. With the ``free`` strategy enabled, however, Ansible does not wait for all hosts and may queue later tasks on one host before a task fails on another host. With the ``free`` strategy, Ansible does not queue or execute any tasks while the debugger is active. However, all queued tasks remain in the queue and run as soon as you exit the debugger. If you use ``redo`` to reschedule a task from the debugger, other queued tasks may execute before your rescheduled task. For more information about strategies, see :ref:`playbooks_strategies`. .. seealso:: diff --git a/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst b/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst index cb1e8afac99..56169edc36e 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst @@ -26,10 +26,10 @@ become set to ``true`` to activate privilege escalation. become_user - set to user with desired privileges — the user you `become`, NOT the user you login as. Does NOT imply ``become: true``, to allow it to be set at host level. The default value is ``root``. + set to user with desired privileges — the user you `become`, NOT the user you login as. Does NOT imply ``become: true``, to allow it to be set at the host level. The default value is ``root``. become_method - (at play or task level) overrides the default method set in ansible.cfg, set to use any of the :ref:`become_plugins`. + (at play or task level) overrides the default method set in ``ansible.cfg``, set to use any of the :ref:`become_plugins`. become_flags (at play or task level) permit the use of specific flags for the tasks or role. One common use is to change the user to nobody when the shell is set to nologin. Added in Ansible 2.2. @@ -73,7 +73,7 @@ Become connection variables You can define different ``become`` options for each managed node or group. You can define these variables in inventory or use them as normal variables. ansible_become - overrides the ``become`` directive, decides if privilege escalation is used or not. + overrides the ``become`` directive and decides if privilege escalation is used or not. ansible_become_method which privilege escalation method should be used @@ -94,7 +94,7 @@ For example, if you want to run all tasks as ``root`` on a server named ``webser webserver ansible_user=manager ansible_become=true .. note:: - The variables defined above are generic for all become plugins but plugin specific ones can also be set instead. + The variables defined above are generic for all become plugins but plugin-specific ones can also be set instead. Please see the documentation for each plugin for a list of all options the plugin has and how they can be defined. A full list of become plugins in Ansible can be found at :ref:`become_plugins`. @@ -102,7 +102,7 @@ Become command-line options --------------------------- --ask-become-pass, -K - ask for privilege escalation password; does not imply become will be used. Note that this password will be used for all hosts. + ask for the privilege escalation password; does not imply become will be used. Note that this password will be used for all hosts. --become, -b run operations with become (no password implied) @@ -208,8 +208,7 @@ Ansible defaults to issuing an error if it cannot execute securely with ``become If you cannot use pipelining or POSIX ACLs, must connect as an unprivileged user, must use ``become`` to execute as a different unprivileged user, and decide that your managed nodes are secure enough for the -modules you want to run there to be world readable, you can turn on `the -``world_readable_temp`` option`_, which will change this from an error into +modules you want to run there to be world readable, you can turn on `the world_readable_temp option`_, which will change this from an error into a warning and allow the task to run as it did prior to 2.1. .. versionchanged:: 2.10 @@ -421,7 +420,7 @@ task: .. code-block:: yaml - - Check my username + - name: Check my username ansible.windows.win_whoami: become: true @@ -518,7 +517,7 @@ has Administrative rights. Here are the labels that can be returned and what they represent: * ``Medium``: Ansible failed to get an elevated token and ran under a limited - token. Only a subset of the privileges assigned to user are available during + token. Only a subset of the privileges assigned to the user are available during the module execution and the user does not have administrative rights. * ``High``: An elevated token was used and all the privileges assigned to the @@ -529,7 +528,7 @@ they represent: The output will also show the list of privileges that have been granted to the user. When the privilege value is ``disabled``, the privilege is assigned to -the logon token but has not been enabled. In most scenarios these privileges +the logon token but has not been enabled. In most scenarios, these privileges are automatically enabled when required. If running on a version of Ansible that is older than 2.5 or the normal @@ -711,7 +710,7 @@ the new process. The value can be set to none or multiple of the following: resource. This is useful in inter-domain scenarios where there is no trust relationship, and should be used with the ``new_credentials`` ``logon_type``. -By default ``logon_flags=with_profile`` is set, if the profile should not be +By default, ``logon_flags=with_profile`` is set, if the profile should not be loaded set ``logon_flags=`` or if the profile should be loaded with ``netcredentials_only``, set ``logon_flags=with_profile,netcredentials_only``. diff --git a/docs/docsite/rst/playbook_guide/playbooks_startnstep.rst b/docs/docsite/rst/playbook_guide/playbooks_startnstep.rst index e6c78d24edd..22fade9760e 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_startnstep.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_startnstep.rst @@ -30,7 +30,7 @@ To execute a playbook interactively, use ``--step``. ansible-playbook playbook.yml --step -With this option, Ansible stops on each task, and asks if it should execute that task. For example, if you have a task called "configure ssh", the playbook run will stop and ask. +With this option, Ansible stops on each task and asks if it should execute that task. For example, if you have a task called "configure ssh", the playbook run will stop and ask. .. code-block:: shell diff --git a/docs/docsite/rst/playbook_guide/playbooks_strategies.rst b/docs/docsite/rst/playbook_guide/playbooks_strategies.rst index 4bcb6db58e8..97b620a4898 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_strategies.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_strategies.rst @@ -72,37 +72,37 @@ In the above example, if we had 6 hosts in the group 'webservers', Ansible would .. code-block:: ansible-output - PLAY [webservers] **************************************** + PLAY [webservers] *********************************************************************** - TASK [first task] **************************************** + TASK [first task] *********************************************************************** + changed: [web1] changed: [web3] changed: [web2] - changed: [web1] - TASK [second task] *************************************** + TASK [second task] ********************************************************************** changed: [web1] changed: [web2] changed: [web3] - PLAY [webservers] **************************************** + PLAY [webservers] *********************************************************************** - TASK [first task] **************************************** + TASK [first task] *********************************************************************** changed: [web4] changed: [web5] changed: [web6] - TASK [second task] *************************************** + TASK [second task] ********************************************************************** changed: [web4] changed: [web5] changed: [web6] - PLAY RECAP *********************************************** - web1 : ok=2 changed=2 unreachable=0 failed=0 - web2 : ok=2 changed=2 unreachable=0 failed=0 - web3 : ok=2 changed=2 unreachable=0 failed=0 - web4 : ok=2 changed=2 unreachable=0 failed=0 - web5 : ok=2 changed=2 unreachable=0 failed=0 - web6 : ok=2 changed=2 unreachable=0 failed=0 + PLAY RECAP ****************************************************************************** + web1 : ok=2 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + web2 : ok=2 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + web3 : ok=2 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + web4 : ok=2 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + web5 : ok=2 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + web6 : ok=2 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 .. note:: @@ -190,7 +190,7 @@ shuffle: Randomly ordered on each run .. note:: - the 'inventory' order does not equate to the order in which hosts/groups are defined in the inventory source file, but the 'order in which a selection is returned from the compiled inventory'. This is a backwards compatible option and while reproducible it is not normally predictable. Due to the nature of inventory, host patterns, limits, inventory plugins and the ability to allow multiple sources it is almost impossible to return such an order. For simple cases this might happen to match the file definition order, but that is not guaranteed. + the 'inventory' order does not equate to the order in which hosts/groups are defined in the inventory source file, but the 'order in which a selection is returned from the compiled inventory'. This is a backwards compatible option and while reproducible it is not normally predictable. Due to the nature of inventory, host patterns, limits, inventory plugins and the ability to allow multiple sources, it is almost impossible to return such an order. For simple cases, this might happen to match the file definition order, but that is not guaranteed. .. _run_once: diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst index c5aec6d55d1..5069e09fdfb 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst @@ -416,7 +416,7 @@ These command-line flags have one limitation: they cannot show tags or tasks wit Selectively running tagged tasks in reusable files --------------------------------------------------- -If you have a role or a tasks file with tags defined at the task or block level, you can selectively run or skip those tagged tasks in a playbook if you use a dynamic include instead of a static import. You must use the same tag on the included tasks and on the include statement itself. For example you might create a file with some tagged and some untagged tasks: +If you have a role or a tasks file with tags defined at the task or block level, you can selectively run or skip those tagged tasks in a playbook if you use a dynamic include instead of a static import. You must use the same tag on the included tasks and on the include statement itself. For example, you might create a file with some tagged and some untagged tasks: .. code-block:: yaml diff --git a/docs/docsite/rst/plugins/action.rst b/docs/docsite/rst/plugins/action.rst index 5086af12adf..e61ded2dc52 100644 --- a/docs/docsite/rst/plugins/action.rst +++ b/docs/docsite/rst/plugins/action.rst @@ -23,7 +23,7 @@ You can enable a custom action plugin by either dropping it into the ``action_pl Using action plugins -------------------- -Action plugin are executed by default when an associated module is used; no action is required. +Action plugins are executed by default when an associated module is used; no additional action is required. Plugin list ----------- diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst index e819e158041..c9ca686ef69 100644 --- a/docs/docsite/rst/plugins/cache.rst +++ b/docs/docsite/rst/plugins/cache.rst @@ -7,9 +7,9 @@ Cache plugins :local: :depth: 2 -Cache plugins allow Ansible to store gathered facts or inventory source data without the performance hit of retrieving them from source. +Cache plugins allow Ansible to store gathered facts or inventory source data without the performance hit of retrieving them from the source. -The default cache plugin is the :ref:`memory ` plugin, which only caches the data for the current execution of Ansible. Other plugins with persistent storage are available to allow caching the data across runs. Some of these cache plugins write to files, others write to databases. +The default cache plugin is the :ref:`memory ` plugin, which only caches the data for the current execution of Ansible. Other plugins with persistent storage are available to allow caching of the data across runs. Some of these cache plugins write to files, and others write to databases. You can use different cache plugins for inventory and facts. If you enable inventory caching without setting an inventory-specific cache plugin, Ansible uses the fact cache plugin for both facts and inventory. If necessary, you can :ref:`create custom cache plugins `. @@ -72,7 +72,7 @@ Only one inventory cache plugin can be active at a time. You can set it with an export ANSIBLE_INVENTORY_CACHE_PLUGIN=jsonfile -or in the ansible.cfg file: +or in the ``ansible.cfg`` file: .. code-block:: ini diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst index 607701854de..76172fc2d3e 100644 --- a/docs/docsite/rst/plugins/callback.rst +++ b/docs/docsite/rst/plugins/callback.rst @@ -16,7 +16,7 @@ Example callback plugins The :ref:`log_plays ` callback is an example of how to record playbook events to a log file, and the :ref:`mail ` callback sends email on playbook failures. -The :ref:`say ` callback responds with computer synthesized speech in relation to playbook events. +The :ref:`say ` callback responds with a computer-synthesized speech in relation to playbook events. .. _enabling_callbacks: diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index 33e176610b4..4fc0d9d0dbb 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -18,7 +18,7 @@ The basics of these connection types are covered in the :ref:`getting started`, at the command line (``-c``, ``--connection``), as a :ref:`keyword ` in your play, or by setting a :ref:`variable`, most often in your inventory. -For example, for Windows machines you might want to set the :ref:`winrm ` plugin as an inventory variable. +For example, for Windows machines, you might want to set the :ref:`winrm ` plugin as an inventory variable. -Most connection plugins can operate with minimal configuration. By default they use the :ref:`inventory hostname` and defaults to find the target host. +Most connection plugins can operate with minimal configuration. By default, they use the :ref:`inventory hostname` and defaults to find the target host. Plugins are self-documenting. Each plugin should document its configuration options. The following are connection variables common to most connection plugins: diff --git a/docs/docsite/rst/plugins/filter.rst b/docs/docsite/rst/plugins/filter.rst index 8bbaa43d250..2923ce5e6f6 100644 --- a/docs/docsite/rst/plugins/filter.rst +++ b/docs/docsite/rst/plugins/filter.rst @@ -7,7 +7,7 @@ Filter plugins :local: :depth: 2 -Filter plugins manipulate data. With the right filter you can extract a particular value, transform data types and formats, perform mathematical calculations, split and concatenate strings, insert dates and times, and do much more. Ansible uses the :ref:`standard filters ` shipped with Jinja2 and adds some specialized filter plugins. You can :ref:`create custom Ansible filters as plugins `. +Filter plugins manipulate data. With the right filter, you can extract a particular value, transform data types and formats, perform mathematical calculations, split and concatenate strings, insert dates and times, and do much more. Ansible uses the :ref:`standard filters ` shipped with Jinja2 and adds some specialized filter plugins. You can :ref:`create custom Ansible filters as plugins `. .. _enabling_filter: @@ -21,7 +21,7 @@ You can add a custom filter plugin by dropping it into a ``filter_plugins`` dire Using filter plugins -------------------- -You can use filters anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the :ref:`template ` module. For more information on using filter plugins, see :ref:`playbooks_filters`. Filters can return any type of data, but if you want to always return a boolean (``True`` or ``False``) you should be looking at a test instead. +You can use filters anywhere you can use templating in Ansible: in a play, in variables file, or a Jinja2 template for the :ref:`template ` module. For more information on using filter plugins, see :ref:`playbooks_filters`. Filters can return any type of data, but if you want to always return a boolean, (``true`` or ``false``) you should be looking at a test instead. .. code-block:: YAML+Jinja diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst index 8d9b12d9090..5ea035cb42f 100644 --- a/docs/docsite/rst/plugins/inventory.rst +++ b/docs/docsite/rst/plugins/inventory.rst @@ -14,7 +14,7 @@ Inventory plugins allow users to point at data sources to compile the inventory Enabling inventory plugins -------------------------- -Most inventory plugins shipped with Ansible are enabled by default or can be used by with the ``auto`` plugin. +Most inventory plugins shipped with Ansible are enabled by default or can be used with the ``auto`` plugin. In some circumstances, for example, if the inventory plugin does not use a YAML configuration file, you may need to enable the specific plugin. You can do this by setting ``enable_plugins`` in your :ref:`ansible.cfg ` file in the ``[inventory]`` section. Modifying this will override the default list of enabled plugins. Here is the default list of enabled plugins that ships with Ansible: diff --git a/docs/docsite/rst/plugins/lookup.rst b/docs/docsite/rst/plugins/lookup.rst index b6ab67bddd3..4f9cd860953 100644 --- a/docs/docsite/rst/plugins/lookup.rst +++ b/docs/docsite/rst/plugins/lookup.rst @@ -11,9 +11,9 @@ Lookup plugins are an Ansible-specific extension to the Jinja2 templating langua .. note:: - Lookups are executed with a working directory relative to the role or play, - as opposed to local tasks, which are executed relative the executed script. + as opposed to local tasks, which are executed relative to the executed script. - Pass ``wantlist=True`` to lookups to use in Jinja2 template "for" loops. - - By default, lookup return values are marked as unsafe for security reasons. If you trust the outside source your lookup accesses, pass ``allow_unsafe=True`` to allow Jinja2 templates to evaluate lookup values. + - By default, lookup return values are marked as unsafe for security reasons. If you trust the outside source for your lookup accesses, pass ``allow_unsafe=True`` to allow Jinja2 templates to evaluate lookup values. .. warning:: - Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the `|quote` filter to ensure safe usage. @@ -32,7 +32,7 @@ Ansible enables all lookup plugins it can find. You can activate a custom lookup Using lookup plugins -------------------- -You can use lookup plugins anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the :ref:`template ` module. For more information on using lookup plugins, see :ref:`playbooks_lookups`. +You can use lookup plugins anywhere you can use templating in Ansible: in a play, in variables file, or a Jinja2 template for the :ref:`template ` module. For more information on using lookup plugins, see :ref:`playbooks_lookups`. .. code-block:: YAML+Jinja @@ -53,7 +53,7 @@ You can combine lookups with :ref:`filters `, :ref:`tests `_ Have a question? Stop by the Google group! `irc.libera.chat `_ diff --git a/docs/docsite/rst/plugins/netconf.rst b/docs/docsite/rst/plugins/netconf.rst index 4fbf0f411dd..eeba1061faa 100644 --- a/docs/docsite/rst/plugins/netconf.rst +++ b/docs/docsite/rst/plugins/netconf.rst @@ -25,7 +25,7 @@ Using netconf plugins The netconf plugin to use is determined automatically from the ``ansible_network_os`` variable. There should be no reason to override this functionality. -Most netconf plugins can operate without configuration. A few have additional options that can be set to affect how tasks are translated into netconf commands. A ncclient device specific handler name can be set in the netconf plugin or else the value of ``default`` is used as per ncclient device handler. +Most netconf plugins can operate without configuration. A few have additional options that can be set to affect how tasks are translated into netconf commands. A ncclient device-specific handler name can be set in the netconf plugin or else the value of ``default`` is used as per ncclient device handler. Plugins are self-documenting. Each plugin should document its configuration options. diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst index 81965fc8769..96597e76262 100644 --- a/docs/docsite/rst/plugins/shell.rst +++ b/docs/docsite/rst/plugins/shell.rst @@ -19,7 +19,7 @@ You can add a custom shell plugin by dropping it into a ``shell_plugins`` direct or by putting it in one of the shell plugin directory sources configured in :ref:`ansible.cfg `. .. warning:: You should not alter which plugin is used unless you have a setup in which the default ``/bin/sh`` - is not a POSIX compatible shell or is not available for execution. + is not a POSIX-compatible shell or is not available for execution. .. _using_shell: diff --git a/docs/docsite/rst/plugins/strategy.rst b/docs/docsite/rst/plugins/strategy.rst index d297d4738a1..3a3ea8a95e6 100644 --- a/docs/docsite/rst/plugins/strategy.rst +++ b/docs/docsite/rst/plugins/strategy.rst @@ -22,13 +22,13 @@ putting it in one of the lookup directory sources configured in :ref:`ansible.cf Using strategy plugins ---------------------- -Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or ansible run. By default Ansible uses the :ref:`linear ` plugin. You can change this default in Ansible :ref:`configuration ` using an environment variable: +Only one strategy plugin can be used in a play, but you can use different ones for each play in a playbook or ansible run. By default, Ansible uses the :ref:`linear ` plugin. You can change this default in Ansible :ref:`configuration ` using an environment variable: .. code-block:: shell export ANSIBLE_STRATEGY=free -or in the `ansible.cfg` file: +or in the ``ansible.cfg`` file: .. code-block:: ini @@ -42,14 +42,20 @@ You can also specify the strategy plugin in the play with the :ref:`strategy key - hosts: all strategy: debug tasks: - - copy: src=myhosts dest=/etc/hosts + - copy: + src: myhosts + dest: /etc/hosts notify: restart_tomcat - - package: name=tomcat state=present + - package: + name: tomcat + state: present handlers: - name: restart_tomcat - service: name=tomcat state=restarted + service: + name: tomcat + state: restarted .. _strategy_plugin_list: diff --git a/docs/docsite/rst/plugins/terminal.rst b/docs/docsite/rst/plugins/terminal.rst index ea0457d352d..7bc4c39aa3b 100644 --- a/docs/docsite/rst/plugins/terminal.rst +++ b/docs/docsite/rst/plugins/terminal.rst @@ -7,7 +7,7 @@ Terminal plugins :local: :depth: 2 -Terminal plugins contain information on how to prepare a particular network device's SSH shell is properly initialized to be used with Ansible. This typically includes disabling automatic paging, detecting errors in output, and enabling privileged mode if supported and required on the device. +Terminal plugins contain information on how to ensure that a particular network device's SSH shell is properly initialized to be used with Ansible. This typically includes disabling automatic paging, detecting errors in output, and enabling privileged mode if the device supports and requires it. These plugins correspond one-to-one to network device platforms. Ansible loads the appropriate terminal plugin automatically based on the ``ansible_network_os`` variable. diff --git a/docs/docsite/rst/reference_appendices/logging.rst b/docs/docsite/rst/reference_appendices/logging.rst index 2ac2a624d88..a266c64987a 100644 --- a/docs/docsite/rst/reference_appendices/logging.rst +++ b/docs/docsite/rst/reference_appendices/logging.rst @@ -2,7 +2,7 @@ Logging Ansible output ********************** -By default Ansible sends output about plays, tasks, and module arguments to your screen (STDOUT) on the control node. If you want to capture Ansible output in a log, you have three options: +By default, Ansible sends output about plays, tasks, and module arguments to your screen (STDOUT) on the control node. If you want to capture Ansible output in a log, you have three options: * To save Ansible output in a single log on the control node, set the ``log_path`` :ref:`configuration file setting `. You may also want to set ``display_args_to_stdout``, which helps to differentiate similar tasks by including variable values in the Ansible output. * To save Ansible output in separate logs, one on each managed node, set the ``no_target_syslog`` and ``syslog_facility`` :ref:`configuration file settings `. diff --git a/docs/docsite/rst/scenario_guides/guide_azure.rst b/docs/docsite/rst/scenario_guides/guide_azure.rst index 5e7dc578a1e..648ea56c65b 100644 --- a/docs/docsite/rst/scenario_guides/guide_azure.rst +++ b/docs/docsite/rst/scenario_guides/guide_azure.rst @@ -353,7 +353,7 @@ For a given host, the inventory script provides the following host variables: Host Groups ........... -By default hosts are grouped by: +By default, hosts are grouped by: * azure (all hosts) * location name @@ -407,7 +407,7 @@ An .ini file will contain the following: .. code-block:: ini [azure] - # Control which resource groups are included. By default all resources groups are included. + # Control which resource groups are included. By default, all resources groups are included. # Set resource_groups to a comma separated list of resource groups names. #resource_groups= diff --git a/docs/docsite/rst/shared_snippets/installing_older_collection.txt b/docs/docsite/rst/shared_snippets/installing_older_collection.txt index 511dd2a7375..3869d1f3047 100644 --- a/docs/docsite/rst/shared_snippets/installing_older_collection.txt +++ b/docs/docsite/rst/shared_snippets/installing_older_collection.txt @@ -1,5 +1,5 @@ -You can only have one version of a collection installed at a time. By default ``ansible-galaxy`` installs the latest available version. If you want to install a specific version, you can add a version range identifier. For example, to install the 1.0.0-beta.1 version of the collection: +You can only have one version of a collection installed at a time. By default, ``ansible-galaxy`` installs the latest available version. If you want to install a specific version, you can add a version range identifier. For example, to install the 1.0.0-beta.1 version of the collection: .. code-block:: bash @@ -22,4 +22,4 @@ Ansible will always install the most recent version that meets the range identif * ``<``: Less than the version specified. .. note:: - By default ``ansible-galaxy`` ignores pre-release versions. To install a pre-release version, you must use the ``==`` range identifier to require it explicitly. + By default, ``ansible-galaxy`` ignores pre-release versions. To install a pre-release version, you must use the ``==`` range identifier to require it explicitly. diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index 0a1163ebb88..6ce3c4f0c3e 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -55,15 +55,15 @@ Explicitly setting ``state: present`` or ``state: absent`` makes playbooks and r Use comments ------------ -Even with task names and explicit state, sometimes a part of a playbook or role (or inventory/variable file) needs more explanation. -Adding a comment (any line starting with ``#``) helps others (and possibly yourself in future) understand what a play or task (or variable setting) does, how it does it, and why. +Even with task names and explicit states, sometimes a part of a playbook or role (or inventory/variable file) needs more explanation. +Adding a comment (any line starting with ``#``) helps others (and possibly yourself in the future) understand what a play or task (or variable setting) does, how it does it, and why. Use fully qualified collection names ------------------------------------ Use `fully qualified collection names (FQCN) `_ to avoid ambiguity in which collection to search for the correct module or plugin for each task. -For `builtin modules and plugins `_, use the ``ansible.builtin`` collection name as prefix, for example, ``ansible.builtin.copy``. +For `builtin modules and plugins `_, use the ``ansible.builtin`` collection name as a prefix, for example, ``ansible.builtin.copy``. .. _inventory_tips: @@ -82,7 +82,7 @@ Group inventory by function --------------------------- A system can be in multiple groups. See :ref:`intro_inventory` and :ref:`intro_patterns`. -If you create groups named for the function of the nodes in the group, for example *webservers* or *dbservers*, your playbooks can target machines based on function. +If you create groups named for the function of the nodes in the group, for example, ``webservers`` or ``dbservers``, your playbooks can target machines based on function. You can assign function-specific variables using the group variable system, and design Ansible roles to handle function-specific use cases. See :ref:`playbooks_reuse_roles`. @@ -133,7 +133,7 @@ Try it in staging first ----------------------- Testing changes in a staging environment before rolling them out in production is always a great idea. -Your environments need not be the same size and you can use group variables to control the differences between those environments. you can also check for any syntax errors in staging environment using flag ``--syntax-check`` +Your environments need not be the same size, and you can use group variables to control the differences between environments. You can also check for any syntax errors in the staging environment using the flag ``--syntax-check`` .. code-block:: yaml diff --git a/docs/docsite/rst/tips_tricks/index.rst b/docs/docsite/rst/tips_tricks/index.rst index 36d83252699..dc7fed5e118 100644 --- a/docs/docsite/rst/tips_tricks/index.rst +++ b/docs/docsite/rst/tips_tricks/index.rst @@ -14,7 +14,7 @@ Ansible tips and tricks Welcome to the Ansible tips and tricks guide. These tips and tricks have helped us optimize our Ansible usage and we offer them here as suggestions. We hope they will help you organize content, write playbooks, maintain inventory, and execute Ansible. -Ultimately, though, you should use Ansible in the way that makes most sense for your organization and your goals. +Ultimately, though, you should use Ansible in the way that makes the most sense for your organization and your goals. .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/tips_tricks/sample_setup.rst b/docs/docsite/rst/tips_tricks/sample_setup.rst index 9385aa69e29..60386cc8807 100644 --- a/docs/docsite/rst/tips_tricks/sample_setup.rst +++ b/docs/docsite/rst/tips_tricks/sample_setup.rst @@ -4,7 +4,7 @@ Sample Ansible setup ******************** -You have learned about playbooks, inventory, roles, and variables. This section combines all those elements, and outlines a sample setup for automating a web service. You can find more example playbooks that illustrate these patterns in our `ansible-examples repository `_. (NOTE: These examples do not use all of the latest features, but are still an excellent reference.). +You have learned about playbooks, inventory, roles, and variables. This section combines all those elements and outlines a sample setup for automating a web service. You can find more example playbooks that illustrate these patterns in our `ansible-examples repository `_. (NOTE: These examples do not use all of the latest features, but are still an excellent reference.). The sample setup organizes playbooks, roles, inventory, and files with variables by function. Tags at the play and task level provide greater granularity and control. This is a powerful and flexible approach, but there are other ways to organize Ansible content. Your usage of Ansible should fit your needs, so feel free to modify this approach and organize your content accordingly. diff --git a/docs/docsite/rst/vault_guide/vault_managing_passwords.rst b/docs/docsite/rst/vault_guide/vault_managing_passwords.rst index 9c2375b1db2..e83eecf1c29 100644 --- a/docs/docsite/rst/vault_guide/vault_managing_passwords.rst +++ b/docs/docsite/rst/vault_guide/vault_managing_passwords.rst @@ -13,7 +13,7 @@ Choosing between a single password and multiple passwords If you have a small team or few sensitive values, you can use a single password for everything you encrypt with Ansible Vault. Store your vault password securely in a file or a secret manager as described below. -If you have a larger team or many sensitive values, you can use multiple passwords. For example, you can use different passwords for different users or different levels of access. Depending on your needs, you might want a different password for each encrypted file, for each directory, or for each environment. For example, you might have a playbook that includes two vars files, one for the dev environment and one for the production environment, encrypted with two different passwords. When you run the playbook, select the correct vault password for the environment you are targeting, using a vault ID. +If you have a larger team or many sensitive values, you can use multiple passwords. For example, you can use different passwords for different users or different levels of access. Depending on your needs, you might want a different password for each encrypted file, for each directory, or each environment. You might have a playbook that includes two vars files, one for the dev environment and one for the production environment, encrypted with two different passwords. When you run the playbook, you can select the correct vault password for the environment you are targeting using a vault ID. .. _vault_ids: @@ -56,7 +56,7 @@ Ansible does not enforce using the same password every time you use a particular Enforcing vault ID matching ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -By default, the vault ID label is only a hint to remind you which password you used to encrypt a variable or file. Ansible does not check that the vault ID in the header of the encrypted content matches the vault ID you provide when you use the content. Ansible decrypts all files and variables called by your command or playbook that are encrypted with the password you provide. To check the encrypted content and decrypt it only when the vault ID it contains matches the one you provide with ``--vault-id``, set the config option :ref:`DEFAULT_VAULT_ID_MATCH`. When you set :ref:`DEFAULT_VAULT_ID_MATCH`, each password is only used to decrypt data that was encrypted with the same label. This is efficient, predictable, and can reduce errors when different values are encrypted with different passwords. +By default, the vault ID label is only a hint to remind you which password you used to encrypt a variable or file. Ansible does not check that the vault ID in the header of the encrypted content matches the vault ID you provide when you use the content. Ansible decrypts all files and variables called by your command or playbook that are encrypted with the password you provide. To check the encrypted content and decrypt it only when the vault ID it contains matches the one you provide with ``--vault-id``, set the config option :ref:`DEFAULT_VAULT_ID_MATCH`. When you set :ref:`DEFAULT_VAULT_ID_MATCH`, each password is only used to decrypt data that was encrypted with the same label. This is efficient and predictable and can reduce errors when different values are encrypted with different passwords. .. note:: Even with the :ref:`DEFAULT_VAULT_ID_MATCH` setting enabled, Ansible does not enforce using the same password every time you use a particular vault ID label. @@ -66,7 +66,7 @@ By default, the vault ID label is only a hint to remind you which password you u Storing and accessing vault passwords ------------------------------------- -You can memorize your vault password, or manually copy vault passwords from any source and paste them at a command-line prompt, but most users store them securely and access them as needed from within Ansible. You have two options for storing vault passwords that work from within Ansible: in files, or in a third-party tool such as the system keyring or a secret manager. If you store your passwords in a third-party tool, you need a vault password client script to retrieve them from within Ansible. +You can memorize your vault password or manually copy vault passwords from any source and paste them at a command-line prompt, but most users store them securely and access them as needed from within Ansible. You have two options for storing vault passwords that work from within Ansible: in files or a third-party tool, such as the system keyring or a secret manager. If you store your passwords in a third-party tool, you need a vault password client script to retrieve them from within Ansible. Storing passwords in files ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/docsite/rst/vault_guide/vault_using_encrypted_content.rst b/docs/docsite/rst/vault_guide/vault_using_encrypted_content.rst index e4b12bfc953..ba01da5a453 100644 --- a/docs/docsite/rst/vault_guide/vault_using_encrypted_content.rst +++ b/docs/docsite/rst/vault_guide/vault_using_encrypted_content.rst @@ -10,7 +10,7 @@ When you run a task or playbook that uses encrypted variables or files, you must Passing a single password ------------------------- -If all the encrypted variables and files your task or playbook need to use a single password, you can use the :option:`--ask-vault-pass ` or :option:`--vault-password-file ` cli options. +If all the encrypted variables and files in your task or playbook need to use a single password, you can use the :option:`--ask-vault-pass ` or :option:`--vault-password-file ` cli options. To prompt for the password: @@ -141,7 +141,7 @@ The header contains up to four elements, separated by semi-colons (``;``). Note: In the future, the header could change. Fields after the format ID and format version depend on the format version. Future vault format versions may add more cipher algorithm options and/or additional fields. -The rest of the content of the file is the 'vaulttext'. The vaulttext is a text armored version of the +The rest of the content of the file is the 'vaulttext'. The vaulttext is a text-armored version of the encrypted ciphertext. Each line is 80 characters wide, except for the last line which may be shorter. Ansible Vault payload format 1.1 - 1.2 @@ -168,7 +168,7 @@ hexlify()'ed result of: - SHA256() algorithm - the first 32 bytes are the cipher key - the second 32 bytes are the HMAC key - - remaining 16 bytes are the cipher IV + - the remaining 16 bytes are the cipher IV - hexlify()'ed string of the ciphertext. The ciphertext is: @@ -177,7 +177,7 @@ hexlify()'ed result of: - AES-CTR stream cipher - cipher key - IV - - a 128 bit counter block seeded from an integer IV + - a 128-bit counter block seeded from an integer IV - the plaintext - the original plaintext From 3bcf565bf6e622a988dabd200ed5cf11576a93c7 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 6 Dec 2023 09:03:59 +0100 Subject: [PATCH 125/536] documentation_contribution.rst: add ansible-documentation open PRs link --- docs/docsite/rst/community/documentation_contributions.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 5946337f44b..ed44b0d928b 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -48,6 +48,7 @@ Reviewing open PRs Review open documentation pull requests for: +- Ansible `docsite `_ - Ansible `projects `_ - Ansible `collections `_ From 84711bc941af02eed636d89d492066d2fadd12db Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 6 Dec 2023 14:02:47 +0100 Subject: [PATCH 126/536] Update docs/docsite/rst/community/documentation_contributions.rst Co-authored-by: Don Naro --- docs/docsite/rst/community/documentation_contributions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index ed44b0d928b..3b4c634d850 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -48,7 +48,7 @@ Reviewing open PRs Review open documentation pull requests for: -- Ansible `docsite `_ +- Ansible `documentation `_ - Ansible `projects `_ - Ansible `collections `_ From c053acd5d343babd1966bc83575779aacb87fe58 Mon Sep 17 00:00:00 2001 From: Anwesha Das Date: Wed, 6 Dec 2023 14:17:26 +0100 Subject: [PATCH 127/536] Add Ansible community 8.7.0 porting guide (#938) --- .../rst/porting_guides/porting_guide_8.rst | 35 ++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_8.rst b/docs/docsite/rst/porting_guides/porting_guide_8.rst index 7be215c91a8..a0090d44dcd 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_8.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_8.rst @@ -21,8 +21,30 @@ We suggest you read this page along with the `Ansible 8 Changelog Date: Thu, 7 Dec 2023 19:14:53 +0100 Subject: [PATCH 128/536] Improve module developing documenation for deprecation and linking (#943) * 'why' isn't optional, and there are more ways to reference entities. * Mention that P(...) can reference roles as well. * Mention how to deprecate action plugins. * Improve language. Co-authored-by: Don Naro --- .../rst/dev_guide/developing_modules_documenting.rst | 2 +- docs/docsite/rst/dev_guide/module_lifecycle.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index fc45afbb1cf..161b84533f7 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -261,7 +261,7 @@ You can link from your module documentation to other module docs, other resource * ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform) for an overview.`` * ``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options)``. Use the RST anchor for the cross-reference. See :ref:`adding_anchors_rst` for details. * ``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)``. A FQCN **must** be used, short names will create broken links; use ``ansible.builtin`` for modules in ansible-core. -* ``P()`` for plugin names. For example: ``See also P(ansible.builtin.file#lookup) or P(community.general.json_query#filter)``. This is supported since ansible-core 2.15. FQCNs must be used; use ``ansible.builtin`` for plugins in ansible-core. +* ``P()`` for plugin names. For example: ``See also P(ansible.builtin.file#lookup) or P(community.general.json_query#filter)``. This can also reference roles: ``P(community.sops.install#role)``. This is supported since ansible-core 2.15. FQCNs must be used; use ``ansible.builtin`` for plugins in ansible-core. .. note:: diff --git a/docs/docsite/rst/dev_guide/module_lifecycle.rst b/docs/docsite/rst/dev_guide/module_lifecycle.rst index 823e2b37388..fe19f82da1e 100644 --- a/docs/docsite/rst/dev_guide/module_lifecycle.rst +++ b/docs/docsite/rst/dev_guide/module_lifecycle.rst @@ -53,7 +53,7 @@ To deprecate a module in a collection, you must: removal_version: 2.0.0 warning_text: Use foo.bar.new_cloud instead. - For other plugin types, you have to replace ``modules:`` with ``:``, for example ``lookup:`` for lookup plugins. + For other plugin types, you have to replace ``modules:`` with ``:``, for example ``lookup:`` for lookup plugins. When deprecating action plugins, you need to add two entries: one for the action plugin and one for the module file that contains the documentation. Instead of ``removal_version``, you can also use ``removal_date`` with an ISO 8601 formatted date after which the module will be removed in a new major version of the collection. @@ -62,8 +62,8 @@ To deprecate a module in a collection, you must: :removed_in: A ``string``, such as ``"2.10"``; the version of Ansible where the module will be replaced with a docs-only module stub. Usually current release +4. Mutually exclusive with :removed_by_date:. :remove_by_date: (Added in ansible-base 2.10). An ISO 8601 formatted date when the module will be removed. Usually 2 years from the date the module is deprecated. Mutually exclusive with :removed_in:. - :why: Optional string that used to detail why this has been removed. - :alternative: Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``. + :why: String that used to detail why this has been removed. + :alternative: Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``. See :ref:`module_documents_linking` for ways to reference entities other than modules. Changing a module or plugin name in the Ansible main repository =============================================================== From 9645588bef1e173d994943134bac64d74fb00136 Mon Sep 17 00:00:00 2001 From: Conner Crosby Date: Thu, 7 Dec 2023 14:12:55 -0500 Subject: [PATCH 129/536] Improve the last sentence in the 'Try it in staging first' section (#941) * Improve the 'Try it in staging first' section The last sentence in the the 'Try it in staging first' section has been appended with additional verbiage to follow other sentences that contain a subsequent example code snippet. * Update docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst --------- Co-authored-by: Sandra McCann --- docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index 6ce3c4f0c3e..defa5c194bc 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -133,7 +133,7 @@ Try it in staging first ----------------------- Testing changes in a staging environment before rolling them out in production is always a great idea. -Your environments need not be the same size, and you can use group variables to control the differences between environments. You can also check for any syntax errors in the staging environment using the flag ``--syntax-check`` +Your environments need not be the same size, and you can use group variables to control the differences between environments. You can also check for any syntax errors in the staging environment using the flag ``--syntax-check`` such as in the following example: .. code-block:: yaml From 5c0ed474aa70413ac042a6f24f29844c5e38260f Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Thu, 7 Dec 2023 14:46:40 -0600 Subject: [PATCH 130/536] documentation_contributions: show how to set up a venv and remove outdated notes (#911) * documentation_contributions: show how to set up a venv The current steps that advise installing docs dependencies in a user's global environment are a very bad idea. They won't work on newer versions of Debian that have adopted PEP 668 that disables `pip install --user`. On systems where it does work, it's likely to pollute or entirely break developers' global Python environment. * documentation_contributions: remove outdated notes * documentation_contributions: improve sentence structure Co-authored-by: Don Naro * documentation_contributions: use `source` instead of `.` `source` is not part of POSIX sh, but I most people are using bash or zsh or whatever which does have it. Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- .../community/documentation_contributions.rst | 27 +++++-------------- 1 file changed, 6 insertions(+), 21 deletions(-) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 3b4c634d850..1f88377e47e 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -92,13 +92,13 @@ To build documentation locally, ensure you have a working :ref:`development envi To work with documentation on your local machine, you should use a version of Python that meets the minimum requirement for ``ansible-core``. For more information on minimum Python versions, see the :ref:`support matrix `. -Drop the ``--user`` option in the following commands if you use a virtual environment (venv/virtenv). -#. Upgrade pip before installing dependencies (recommended). +#. Set up a virtual environment in which to install dependencies. .. code-block:: bash - pip install --user --upgrade pip + python3 -m venv ./venv + source ./venv/bin/activate #. Clone required parts of Ansible Core for the docs build. @@ -110,24 +110,9 @@ Drop the ``--user`` option in the following commands if you use a virtual enviro .. code-block:: bash - pip install --user -r tests/requirements.in -c tests/requirements.txt # Installs tested dependency versions. - pip install --user -r tests/requirements.in # Installs the unpinned dependency versions. - pip install --user -r tests/requirements-relaxed.in # Installs the unpinned dependency versions including untested antsibull-docs. - -.. note:: - - You may need to install these general pre-requisites separately on some systems: - - ``gcc`` - - ``libyaml`` - - ``make`` - - ``pyparsing`` - - ``wheel`` - - ``six`` - On macOS with Xcode, you may need to install ``six`` and ``pyparsing`` with ``--ignore-installed`` to get versions that work with ``sphinx``. - -.. note:: - - After checking out ``ansible/ansible-documentation``, make sure the ``docs/docsite/rst`` directory has strict enough permissions. It should only be writable by the owner's account. If your default ``umask`` is not 022, you can use ``chmod go-w docs/docsite/rst`` to set the permissions correctly in your new branch. Optionally, you can set your ``umask`` to 022 to make all newly created files on your system (including those created by ``git clone``) have the correct permissions. + pip install -r tests/requirements.in -c tests/requirements.txt # Installs tested dependency versions. + pip install -r tests/requirements.in # Installs the unpinned dependency versions. + pip install -r tests/requirements-relaxed.in # Installs the unpinned dependency versions including untested antsibull-docs. .. _testing_documentation_locally: From a7e5482eab02a8493ad4eadd5db0d53cb48bde68 Mon Sep 17 00:00:00 2001 From: Michael Mehl <2124017+michaelmehl@users.noreply.github.com> Date: Thu, 7 Dec 2023 15:51:01 -0600 Subject: [PATCH 131/536] Update windows_winrm.rst (#910) * Update windows_winrm.rst --- docs/docsite/rst/os_guide/windows_winrm.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/os_guide/windows_winrm.rst b/docs/docsite/rst/os_guide/windows_winrm.rst index 538f5c2db53..909955679fd 100644 --- a/docs/docsite/rst/os_guide/windows_winrm.rst +++ b/docs/docsite/rst/os_guide/windows_winrm.rst @@ -359,9 +359,12 @@ Some system dependencies must be installed before using Kerberos. The script bel # Through DNF (RHEL/Centos/Fedora for the newer version) dnf -y install gcc python3-devel krb5-devel krb5-libs krb5-workstation - # Through Apt (Ubuntu) + # Through Apt (Ubuntu older than 20.04 LTS (focal)) sudo apt-get install python-dev libkrb5-dev krb5-user + # Through Apt (Ubuntu newer than 20.04 LTS) + sudo apt-get install python3-dev libkrb5-dev krb5-user + # Through Portage (Gentoo) emerge -av app-crypt/mit-krb5 emerge -av dev-python/setuptools From f472c557c74af3f3bba6c509c44ef12135c7651d Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Sat, 9 Dec 2023 16:40:48 -0600 Subject: [PATCH 132/536] bump minimum antsibull-docs version to 2.6.0 (#958) This fixes the build failures causes by https://github.com/ansible/ansible/pull/82361. --- tests/constraints.in | 2 +- tests/requirements-relaxed.in | 2 +- tests/requirements-relaxed.txt | 2 +- tests/requirements.txt | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/constraints.in b/tests/constraints.in index d4db956cba1..28ed46552a4 100644 --- a/tests/constraints.in +++ b/tests/constraints.in @@ -2,4 +2,4 @@ # and antsibull-docs that production builds rely upon. sphinx == 7.2.5 -antsibull-docs == 2.5.0 # currently approved version +antsibull-docs == 2.6.0 # currently approved version diff --git a/tests/requirements-relaxed.in b/tests/requirements-relaxed.in index ffc37e73cc2..a5792f7af9d 100644 --- a/tests/requirements-relaxed.in +++ b/tests/requirements-relaxed.in @@ -12,5 +12,5 @@ sphinx-intl # translation utility used by docs/docsite/Makefile sphinx-notfound-page sphinx-ansible-theme rstcheck -antsibull-docs ~= 2.0 +antsibull-docs ~= 2.6 # 2.6.0 has a fix for EXAMPLES parsing that previously caused docs builds to fail sphinx-copybutton diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index e0aceef13ad..c5cb0b7daf2 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -20,7 +20,7 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-core==2.1.0 # via antsibull-docs -antsibull-docs==2.5.0 +antsibull-docs==2.6.0 # via -r tests/requirements-relaxed.in antsibull-docs-parser==1.0.0 # via antsibull-docs diff --git a/tests/requirements.txt b/tests/requirements.txt index d9675fc5bcc..751de12722c 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -20,7 +20,7 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-core==2.1.0 # via antsibull-docs -antsibull-docs==2.5.0 +antsibull-docs==2.6.0 # via # -c tests/constraints.in # -r tests/requirements-relaxed.in From 3f12228c79f2e1aafd52e3f9be15444a4746ec3e Mon Sep 17 00:00:00 2001 From: Martin Krizek Date: Sun, 10 Dec 2023 05:02:30 +0100 Subject: [PATCH 133/536] Retroactivelly add a 2.15 porting guide note about handlers (#882) Co-authored-by: Sandra McCann Co-authored-by: Maxwell G --- .../porting_guide_core_2.15.rst | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.15.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.15.rst index 8b560576b67..74a045932e3 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.15.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.15.rst @@ -44,6 +44,47 @@ Playbook assert: that: '"hi mom" is in untrusted_result.stdout' +Handlers +-------- +As documented, if multiple handlers of a specific name have been defined, the last one added into the play is the one that is executed when being notified. Prior to ``ansible-core`` 2.15, this was not the case for handlers included dynamically into the play with the ``include_role`` task. This issue has been addressed in ``ansible-core`` 2.15, and users relying on the ``ansible-core`` 2.14 and older behavior may need to adjust their playbooks accordingly. + + As an example of the behavior change, consider the following: + + .. code-block:: yaml + + - include_role: + name: foo + vars: + invocation: 1 + + - block: + - include_role: + name: foo + vars: + invocation: 2 + when: inventory_hostname == "bar" + + - meta: flush_handlers + +.. note:: + + The example assumes there is a task within the role ``foo`` that notifies a handler named ``foo_handler`` within the role ``foo``. + +.. note:: + + The fact that different variables and/or their values are attached to ``include_role`` tasks including the same role makes them distinct roles. + +.. note:: + + The second invocation of the ``include_role`` task results in including tasks and handlers from the role regardless of the ``when`` conditional evaluation result. The ``when`` conditional is attached to the ``block`` wrapping the ``include_role`` task and as such the ``when`` conditional is applied to all tasks and handlers from the role after they are included into the play. + +By the time the ``flush_handlers`` task runs, all hosts notified ``foo_handler`` within the first invocation of ``include_role``. Additionally the host ``bar`` (due to ``when`` restricting all other hosts) notified ``foo_handler`` again during the second invocation of ``include_role``. + +On ``ansible-core`` 2.15, the last handler named ``foo_handler`` added into the play is from the second ``include_role`` invocation and therefore has ``when: inventory_hostname == "bar"`` attached to it, resulting in the handler being actually run only on the host ``bar`` and skipped on all other hosts. Consequently the notifications from the host ``bar`` have been de-duplicated. + +On ``ansible-core`` 2.14 and older, ``foo_handler`` from the first invocation runs on all hosts. Additionally, ``foo_handler`` from the second invocation is run on the host ``bar`` again. + + Command Line ============ From c829f6e0e5cb5b89ce7eb4c8e36768ed39f1f484 Mon Sep 17 00:00:00 2001 From: Akira Yokochi Date: Sat, 9 Dec 2023 13:57:36 +0900 Subject: [PATCH 134/536] fix example role name --- .../network/getting_started/network_roles.rst | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/docsite/rst/network/getting_started/network_roles.rst b/docs/docsite/rst/network/getting_started/network_roles.rst index 4ffb833026f..b9ee041ff3e 100644 --- a/docs/docsite/rst/network/getting_started/network_roles.rst +++ b/docs/docsite/rst/network/getting_started/network_roles.rst @@ -74,9 +74,9 @@ The next step is to convert this playbook into a reusable role. You can create t .. code-block:: bash - [user@ansible ~]$ ansible-galaxy init system-demo - [user@ansible ~]$ cd system-demo/ - [user@ansible system-demo]$ tree + [user@ansible ~]$ ansible-galaxy init system_demo + [user@ansible ~]$ cd system_demo/ + [user@ansible system_demo]$ tree . ├── defaults │ └── main.yml @@ -99,7 +99,7 @@ This first demonstration uses only the **tasks** and **vars** directories. The .. code-block:: bash - [user@ansible system-demo]$ tree + [user@ansible system_demo]$ tree . ├── tasks │ └── main.yml @@ -110,7 +110,7 @@ Next, move the content of the ``vars`` and ``tasks`` sections from the original .. code-block:: bash - [user@ansible system-demo]$ cat tasks/main.yml + [user@ansible system_demo]$ cat tasks/main.yml --- - name: configure hostname cisco.ios.ios_config: @@ -124,11 +124,11 @@ Next, move the variables into the ``vars/main.yml`` file: .. code-block:: bash - [user@ansible system-demo]$ cat vars/main.yml + [user@ansible system_demo]$ cat vars/main.yml --- dns: "8.8.8.8 8.8.4.4" -Finally, modify the original Ansible Playbook to remove the ``tasks`` and ``vars`` sections and add the keyword ``roles`` with the name of the role, in this case ``system-demo``. You'll have this playbook: +Finally, modify the original Ansible Playbook to remove the ``tasks`` and ``vars`` sections and add the keyword ``roles`` with the name of the role, in this case ``system_demo``. You'll have this playbook: .. code-block:: yaml @@ -136,19 +136,19 @@ Finally, modify the original Ansible Playbook to remove the ``tasks`` and ``vars - name: configure cisco routers hosts: routers connection: ansible.netcommon.network_cli - gather_facts: no + gather_facts: false roles: - - system-demo + - system_demo -To summarize, this demonstration now has a total of three directories and three YAML files. There is the ``system-demo`` folder, which represents the role. This ``system-demo`` contains two folders, ``tasks`` and ``vars``. There is a ``main.yml`` is each respective folder. The ``vars/main.yml`` contains the variables from ``playbook.yml``. The ``tasks/main.yml`` contains the tasks from ``playbook.yml``. The ``playbook.yml`` file has been modified to call the role rather than specifying vars and tasks directly. Here is a tree of the current working directory: +To summarize, this demonstration now has a total of three directories and three YAML files. There is the ``system_demo`` folder, which represents the role. This ``system_demo`` contains two folders, ``tasks`` and ``vars``. There is a ``main.yml`` is each respective folder. The ``vars/main.yml`` contains the variables from ``playbook.yml``. The ``tasks/main.yml`` contains the tasks from ``playbook.yml``. The ``playbook.yml`` file has been modified to call the role rather than specifying vars and tasks directly. Here is a tree of the current working directory: .. code-block:: bash [user@ansible ~]$ tree . ├── playbook.yml - └── system-demo + └── system_demo ├── tasks │ └── main.yml └── vars @@ -162,16 +162,16 @@ Running the playbook results in identical behavior with slightly different outpu PLAY [configure cisco routers] ************************************************* - TASK [system-demo : configure hostname] **************************************** + TASK [system_demo : configure hostname] **************************************** ok: [rtr1] - TASK [system-demo : configure DNS] ********************************************* + TASK [system_demo : configure DNS] ********************************************* ok: [rtr1] PLAY RECAP ********************************************************************* rtr1 : ok=2 changed=0 unreachable=0 failed=0 -As seen above each task is now prepended with the role name, in this case ``system-demo``. When running a playbook that contains several roles, this will help pinpoint where a task is being called from. This playbook returned ``ok`` instead of ``changed`` because it has identical behavior for the single file playbook we started from. +As seen above each task is now prepended with the role name, in this case ``system_demo``. When running a playbook that contains several roles, this will help pinpoint where a task is being called from. This playbook returned ``ok`` instead of ``changed`` because it has identical behavior for the single file playbook we started from. As before, the playbook will generate the following configuration on a Cisco IOS-XE router: @@ -182,7 +182,7 @@ As before, the playbook will generate the following configuration on a Cisco IOS ip name-server 8.8.8.8 8.8.4.4 -This is why Ansible roles can be simply thought of as deconstructed playbooks. They are simple, effective and reusable. Now another user can simply include the ``system-demo`` role instead of having to create a custom "hard coded" playbook. +This is why Ansible roles can be simply thought of as deconstructed playbooks. They are simple, effective and reusable. Now another user can simply include the ``system_demo`` role instead of having to create a custom "hard coded" playbook. Variable precedence ------------------- @@ -192,12 +192,12 @@ What if you want to change the DNS servers? You aren't expected to change the ` Lowest precedence ^^^^^^^^^^^^^^^^^ -The lowest precedence is the ``defaults`` directory within a role. This means all the other 20 locations you could potentially specify the variable will all take higher precedence than ``defaults``, no matter what. To immediately give the vars from the ``system-demo`` role the least precedence, rename the ``vars`` directory to ``defaults``. +The lowest precedence is the ``defaults`` directory within a role. This means all the other 20 locations you could potentially specify the variable will all take higher precedence than ``defaults``, no matter what. To immediately give the vars from the ``system_demo`` role the least precedence, rename the ``vars`` directory to ``defaults``. .. code-block:: bash - [user@ansible system-demo]$ mv vars defaults - [user@ansible system-demo]$ tree + [user@ansible system_demo]$ mv vars defaults + [user@ansible system_demo]$ tree . ├── defaults │ └── main.yml @@ -216,7 +216,7 @@ Add a new ``vars`` section to the playbook to override the default behavior (whe vars: dns: 1.1.1.1 roles: - - system-demo + - system_demo Run this updated playbook on **rtr2**: From 466b1fdc43b6a065b86a4b0da23bd1fd59794a31 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 11 Dec 2023 11:21:38 -0600 Subject: [PATCH 135/536] Bump actions/setup-python from 4 to 5 (#966) Bumps [actions/setup-python](https://github.com/actions/setup-python) from 4 to 5. - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](https://github.com/actions/setup-python/compare/v4...v5) --- updated-dependencies: - dependency-name: actions/setup-python dependency-type: direct:production update-type: version-update:semver-major ... --- .github/workflows/labeler.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml index 3affdf14ec5..ad509d96b42 100644 --- a/.github/workflows/labeler.yml +++ b/.github/workflows/labeler.yml @@ -41,7 +41,7 @@ jobs: - name: Checkout parent repository uses: actions/checkout@v4 - name: Install Python 3.11 - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: "3.11" - name: Setup venv From fc5295a986cb155143b5f68f17698ac0d8d004a5 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Mon, 11 Dec 2023 21:36:43 +0100 Subject: [PATCH 136/536] Remove some scenario guides (#965) * Remove some scenario guides * Add stubs for moved scenario guides * Add Online.net Guide stub * Update docs/docsite/rst/scenario_guides/cloud_guides.rst Co-authored-by: Felix Fontein * Remove deleted guide_vultr scenario guide Co-authored-by: Sandra McCann --------- Co-authored-by: Felix Fontein Co-authored-by: Sandra McCann --- .../rst/scenario_guides/cloud_guides.rst | 7 - .../rst/scenario_guides/guide_alicloud.rst | 129 +-- .../rst/scenario_guides/guide_online.rst | 38 +- .../rst/scenario_guides/guide_oracle.rst | 103 --- .../rst/scenario_guides/guide_packet.rst | 308 +------ .../docsite/rst/scenario_guides/guide_rax.rst | 809 ------------------ .../rst/scenario_guides/guide_scaleway.rst | 288 +------ docs/docsite/rst/scenario_guides/guides.rst | 6 - 8 files changed, 4 insertions(+), 1684 deletions(-) delete mode 100644 docs/docsite/rst/scenario_guides/guide_oracle.rst delete mode 100644 docs/docsite/rst/scenario_guides/guide_rax.rst diff --git a/docs/docsite/rst/scenario_guides/cloud_guides.rst b/docs/docsite/rst/scenario_guides/cloud_guides.rst index a0e6e8ed975..b0b8f370148 100644 --- a/docs/docsite/rst/scenario_guides/cloud_guides.rst +++ b/docs/docsite/rst/scenario_guides/cloud_guides.rst @@ -13,13 +13,6 @@ Guides for using public clouds are moving into collections. We are migrating the .. toctree:: :maxdepth: 1 - guide_alicloud guide_cloudstack guide_gce guide_azure - guide_online - guide_oracle - guide_packet - guide_rax - guide_scaleway - guide_vultr diff --git a/docs/docsite/rst/scenario_guides/guide_alicloud.rst b/docs/docsite/rst/scenario_guides/guide_alicloud.rst index fd78bf19cfb..d8e7d044bf7 100644 --- a/docs/docsite/rst/scenario_guides/guide_alicloud.rst +++ b/docs/docsite/rst/scenario_guides/guide_alicloud.rst @@ -3,131 +3,4 @@ Alibaba Cloud Compute Services Guide .. _alicloud_intro: -Introduction -```````````` - -Ansible contains several modules for controlling and managing Alibaba Cloud Compute Services (Alicloud). This guide -explains how to use the Alicloud Ansible modules together. - -All Alicloud modules require ``footmark`` - install it on your control machine with ``pip install footmark``. - -Cloud modules, including Alicloud modules, execute on your local machine (the control machine) with ``connection: local``, rather than on remote machines defined in your hosts. - -Normally, you'll use the following pattern for plays that provision Alicloud resources: - -.. code-block:: yaml - - - hosts: localhost - connection: local - vars: - - ... - tasks: - - ... - -.. _alicloud_authentication: - -Authentication -`````````````` - -You can specify your Alicloud authentication credentials (access key and secret key) by passing them as -environment variables or by storing them in a vars file. - -To pass authentication credentials as environment variables: - -.. code-block:: shell - - export ALICLOUD_ACCESS_KEY='Alicloud123' - export ALICLOUD_SECRET_KEY='AlicloudSecret123' - -To store authentication credentials in a vars_files, encrypt them with :ref:`Ansible Vault` to keep them secure, then list them: - -.. code-block:: yaml - - --- - alicloud_access_key: "--REMOVED--" - alicloud_secret_key: "--REMOVED--" - -Note that if you store your credentials in a vars_files, you need to refer to them in each Alicloud module. For example: - -.. code-block:: yaml - - - ali_instance: - alicloud_access_key: "{{alicloud_access_key}}" - alicloud_secret_key: "{{alicloud_secret_key}}" - image_id: "..." - -.. _alicloud_provisioning: - -Provisioning -```````````` - -Alicloud modules create Alicloud ECS instances, disks, virtual private clouds, virtual switches, security groups and other resources. - -You can use the ``count`` parameter to control the number of resources you create or terminate. For example, if you want exactly 5 instances tagged ``NewECS``, -set the ``count`` of instances to 5 and the ``count_tag`` to ``NewECS``, as shown in the last task of the example playbook below. -If there are no instances with the tag ``NewECS``, the task creates 5 new instances. If there are 2 instances with that tag, the task -creates 3 more. If there are 8 instances with that tag, the task terminates 3 of those instances. - -If you do not specify a ``count_tag``, the task creates the number of instances you specify in ``count`` with the ``instance_name`` you provide. - -.. code-block:: yaml - - # alicloud_setup.yml - - - hosts: localhost - connection: local - - tasks: - - - name: Create VPC - ali_vpc: - cidr_block: '{{ cidr_block }}' - vpc_name: new_vpc - register: created_vpc - - - name: Create VSwitch - ali_vswitch: - alicloud_zone: '{{ alicloud_zone }}' - cidr_block: '{{ vsw_cidr }}' - vswitch_name: new_vswitch - vpc_id: '{{ created_vpc.vpc.id }}' - register: created_vsw - - - name: Create security group - ali_security_group: - name: new_group - vpc_id: '{{ created_vpc.vpc.id }}' - rules: - - proto: tcp - port_range: 22/22 - cidr_ip: 0.0.0.0/0 - priority: 1 - rules_egress: - - proto: tcp - port_range: 80/80 - cidr_ip: 192.168.0.54/32 - priority: 1 - register: created_group - - - name: Create a set of instances - ali_instance: - security_groups: '{{ created_group.group_id }}' - instance_type: ecs.n4.small - image_id: "{{ ami_id }}" - instance_name: "My-new-instance" - instance_tags: - Name: NewECS - Version: 0.0.1 - count: 5 - count_tag: - Name: NewECS - allocate_public_ip: true - max_bandwidth_out: 50 - vswitch_id: '{{ created_vsw.vswitch.id}}' - register: create_instance - -In the example playbook above, data about the vpc, vswitch, group, and instances created by this playbook -are saved in the variables defined by the "register" keyword in each task. - -Each Alicloud module offers a variety of parameter options. Not all options are demonstrated in the above example. -See each individual module for further details and examples. +The content on this page has moved to :ref:`ansible_collections.community.general.docsite.guide_alicloud`. diff --git a/docs/docsite/rst/scenario_guides/guide_online.rst b/docs/docsite/rst/scenario_guides/guide_online.rst index 2c181a949c1..69cadc4e9b5 100644 --- a/docs/docsite/rst/scenario_guides/guide_online.rst +++ b/docs/docsite/rst/scenario_guides/guide_online.rst @@ -2,40 +2,4 @@ Online.net Guide **************** -Introduction -============ - -Online is a French hosting company mainly known for providing bare-metal servers named Dedibox. -Check it out: `https://www.online.net/en `_ - -Dynamic inventory for Online resources --------------------------------------- - -Ansible has a dynamic inventory plugin that can list your resources. - -1. Create a YAML configuration such as ``online_inventory.yml`` with this content: - -.. code-block:: yaml - - plugin: online - -2. Set your ``ONLINE_TOKEN`` environment variable with your token. - You need to open an account and log into it before you can get a token. - You can find your token at the following page: `https://console.online.net/en/api/access `_ - -3. You can test that your inventory is working by running: - -.. code-block:: bash - - $ ansible-inventory -v -i online_inventory.yml --list - - -4. Now you can run your playbook or any other module with this inventory: - -.. code-block:: console - - $ ansible all -i online_inventory.yml -m ping - sd-96735 | SUCCESS => { - "changed": false, - "ping": "pong" - } +The content on this page has moved to :ref:`ansible_collections.community.general.docsite.guide_online`. diff --git a/docs/docsite/rst/scenario_guides/guide_oracle.rst b/docs/docsite/rst/scenario_guides/guide_oracle.rst deleted file mode 100644 index 170ea9031ba..00000000000 --- a/docs/docsite/rst/scenario_guides/guide_oracle.rst +++ /dev/null @@ -1,103 +0,0 @@ -=================================== -Oracle Cloud Infrastructure Guide -=================================== - -************ -Introduction -************ - -Oracle provides a number of Ansible modules to interact with Oracle Cloud Infrastructure (OCI). In this guide, we will explain how you can use these modules to orchestrate, provision and configure your infrastructure on OCI. - -************ -Requirements -************ -To use the OCI Ansible modules, you must have the following prerequisites on your control node, the computer from which Ansible playbooks are executed. - -1. `An Oracle Cloud Infrastructure account. `_ - -2. A user created in that account, in a security group with a policy that grants the necessary permissions for working with resources in those compartments. For guidance, see `How Policies Work `_. - -3. The necessary credentials and OCID information. - -************ -Installation -************ -1. Install the Oracle Cloud Infrastructure Python SDK (`detailed installation instructions `_): - -.. code-block:: bash - - pip install oci - -2. Install the Ansible OCI Modules in one of two ways: - -a. From Galaxy: - -.. code-block:: bash - - ansible-galaxy install oracle.oci_ansible_modules - -b. From GitHub: - -.. code-block:: bash - - $ git clone https://github.com/oracle/oci-ansible-modules.git - -.. code-block:: bash - - $ cd oci-ansible-modules - - -Run one of the following commands: - -- If Ansible is installed only for your user: - -.. code-block:: bash - - $ ./install.py - -- If Ansible is installed as root: - -.. code-block:: bash - - $ sudo ./install.py - -************* -Configuration -************* - -When creating and configuring Oracle Cloud Infrastructure resources, Ansible modules use the authentication information outlined `here `_. -. - -******** -Examples -******** -Launch a compute instance -========================= -This `sample launch playbook `_ -launches a public Compute instance and then accesses the instance from an Ansible module over an SSH connection. The sample illustrates how to: - -- Generate a temporary, host-specific SSH key pair. -- Specify the public key from the key pair for connecting to the instance, and then launch the instance. -- Connect to the newly launched instance using SSH. - -Create and manage Autonomous Data Warehouses -============================================ -This `sample warehouse playbook `_ creates an Autonomous Data Warehouse and manage its lifecycle. The sample shows how to: - -- Set up an Autonomous Data Warehouse. -- List all of the Autonomous Data Warehouse instances available in a compartment, filtered by the display name. -- Get the "facts" for a specified Autonomous Data Warehouse. -- Stop and start an Autonomous Data Warehouse instance. -- Delete an Autonomous Data Warehouse instance. - -Create and manage Autonomous Transaction Processing -=================================================== -This `sample playbook `_ -creates an Autonomous Transaction Processing database and manage its lifecycle. The sample shows how to: - -- Set up an Autonomous Transaction Processing database instance. -- List all of the Autonomous Transaction Processing instances in a compartment, filtered by the display name. -- Get the "facts" for a specified Autonomous Transaction Processing instance. -- Delete an Autonomous Transaction Processing database instance. - -You can find more examples here: `Sample Ansible Playbooks `_. diff --git a/docs/docsite/rst/scenario_guides/guide_packet.rst b/docs/docsite/rst/scenario_guides/guide_packet.rst index 839515a5fda..ff0a9224780 100644 --- a/docs/docsite/rst/scenario_guides/guide_packet.rst +++ b/docs/docsite/rst/scenario_guides/guide_packet.rst @@ -2,310 +2,4 @@ Packet.net Guide ********************************** -Introduction -============ - -`Packet.net `_ is a bare metal infrastructure host that's supported by Ansible (>=2.3) through a dynamic inventory script and two cloud modules. The two modules are: - -- packet_sshkey: adds a public SSH key from file or value to the Packet infrastructure. Every subsequently-created device will have this public key installed in .ssh/authorized_keys. -- packet_device: manages servers on Packet. You can use this module to create, restart and delete devices. - -Note, this guide assumes you are familiar with Ansible and how it works. If you're not, have a look at their :ref:`docs ` before getting started. - -Requirements -============ - -The Packet modules and inventory script connect to the Packet API using the packet-python package. You can install it with pip: - -.. code-block:: bash - - $ pip install packet-python - -In order to check the state of devices created by Ansible on Packet, it is a good idea to install one of the `Packet CLI clients `_. Otherwise you can check them through the `Packet portal `_. - -To use the modules and inventory script you'll need a Packet API token. You can generate an API token through the Packet portal `here `__. The simplest way to authenticate yourself is to set the Packet API token in an environment variable: - -.. code-block:: bash - - $ export PACKET_API_TOKEN=Bfse9F24SFtfs423Gsd3ifGsd43sSdfs - -If you're not comfortable exporting your API token, you can pass it as a parameter to the modules. - -On Packet, devices and reserved IP addresses belong to `projects `_. In order to use the packet_device module, you need to specify the UUID of the project in which you want to create or manage devices. You can find a project's UUID in the Packet portal `here `_ (it is just under the project table) or through one of the available `CLIs `_. - - -If you want to use a new SSH key pair in this tutorial, you can generate it to ``./id_rsa`` and ``./id_rsa.pub`` as: - -.. code-block:: bash - - $ ssh-keygen -t rsa -f ./id_rsa - -If you want to use an existing key pair, just copy the private and public key over to the playbook directory. - - -Device Creation -=============== - -The following code block is a simple playbook that creates one `Type 0 `_ server (the 'plan' parameter). You have to supply 'plan' and 'operating_system'. 'location' defaults to 'ewr1' (Parsippany, NJ). You can find all the possible values for the parameters through a `CLI client `_. - -.. code-block:: yaml - - # playbook_create.yml - - - name: create ubuntu device - hosts: localhost - tasks: - - - packet_sshkey: - key_file: ./id_rsa.pub - label: tutorial key - - - packet_device: - project_id: - hostnames: myserver - operating_system: ubuntu_16_04 - plan: baremetal_0 - facility: sjc1 - -After running ``ansible-playbook playbook_create.yml``, you should have a server provisioned on Packet. You can verify through a CLI or in the `Packet portal `__. - -If you get an error with the message "failed to set machine state present, error: Error 404: Not Found", please verify your project UUID. - - -Updating Devices -================ - -The two parameters used to uniquely identify Packet devices are: "device_ids" and "hostnames". Both parameters accept either a single string (later converted to a one-element list), or a list of strings. - -The 'device_ids' and 'hostnames' parameters are mutually exclusive. The following values are all acceptable: - -- device_ids: a27b7a83-fc93-435b-a128-47a5b04f2dcf - -- hostnames: mydev1 - -- device_ids: [a27b7a83-fc93-435b-a128-47a5b04f2dcf, 4887130f-0ccd-49a0-99b0-323c1ceb527b] - -- hostnames: [mydev1, mydev2] - -In addition, hostnames can contain a special '%d' formatter along with a 'count' parameter that lets you easily expand hostnames that follow a simple name and number pattern; in other words, ``hostnames: "mydev%d", count: 2`` will expand to [mydev1, mydev2]. - -If your playbook acts on existing Packet devices, you can only pass the 'hostname' and 'device_ids' parameters. The following playbook shows how you can reboot a specific Packet device by setting the 'hostname' parameter: - -.. code-block:: yaml - - # playbook_reboot.yml - - - name: reboot myserver - hosts: localhost - tasks: - - - packet_device: - project_id: - hostnames: myserver - state: rebooted - -You can also identify specific Packet devices with the 'device_ids' parameter. The device's UUID can be found in the `Packet Portal `_ or by using a `CLI `_. The following playbook removes a Packet device using the 'device_ids' field: - -.. code-block:: yaml - - # playbook_remove.yml - - - name: remove a device - hosts: localhost - tasks: - - - packet_device: - project_id: - device_ids: - state: absent - - -More Complex Playbooks -====================== - -In this example, we'll create a CoreOS cluster with `user data `_. - - -The CoreOS cluster will use `etcd `_ for discovery of other servers in the cluster. Before provisioning your servers, you'll need to generate a discovery token for your cluster: - -.. code-block:: bash - - $ curl -w "\n" 'https://discovery.etcd.io/new?size=3' - -The following playbook will create an SSH key, 3 Packet servers, and then wait until SSH is ready (or until 5 minutes passed). Make sure to substitute the discovery token URL in 'user_data', and the 'project_id' before running ``ansible-playbook``. Also, feel free to change 'plan' and 'facility'. - -.. code-block:: yaml - - # playbook_coreos.yml - - - name: Start 3 CoreOS nodes in Packet and wait until SSH is ready - hosts: localhost - tasks: - - - packet_sshkey: - key_file: ./id_rsa.pub - label: new - - - packet_device: - hostnames: [coreos-one, coreos-two, coreos-three] - operating_system: coreos_beta - plan: baremetal_0 - facility: ewr1 - project_id: - wait_for_public_IPv: 4 - user_data: | - #cloud-config - coreos: - etcd2: - discovery: https://discovery.etcd.io/ - advertise-client-urls: http://$private_ipv4:2379,http://$private_ipv4:4001 - initial-advertise-peer-urls: http://$private_ipv4:2380 - listen-client-urls: http://0.0.0.0:2379,http://0.0.0.0:4001 - listen-peer-urls: http://$private_ipv4:2380 - fleet: - public-ip: $private_ipv4 - units: - - name: etcd2.service - command: start - - name: fleet.service - command: start - register: newhosts - - - name: wait for ssh - wait_for: - delay: 1 - host: "{{ item.public_ipv4 }}" - port: 22 - state: started - timeout: 500 - loop: "{{ newhosts.results[0].devices }}" - - -As with most Ansible modules, the default states of the Packet modules are idempotent, meaning the resources in your project will remain the same after re-runs of a playbook. Thus, we can keep the ``packet_sshkey`` module call in our playbook. If the public key is already in your Packet account, the call will have no effect. - -The second module call provisions 3 Packet Type 0 (specified using the 'plan' parameter) servers in the project identified by the 'project_id' parameter. The servers are all provisioned with CoreOS beta (the 'operating_system' parameter) and are customized with cloud-config user data passed to the 'user_data' parameter. - -The ``packet_device`` module has a ``wait_for_public_IPv`` that is used to specify the version of the IP address to wait for (valid values are ``4`` or ``6`` for IPv4 or IPv6). If specified, Ansible will wait until the GET API call for a device contains an Internet-routeable IP address of the specified version. When referring to an IP address of a created device in subsequent module calls, it is wise to use the ``wait_for_public_IPv`` parameter, or ``state: active`` in the packet_device module call. - -Run the playbook: - -.. code-block:: bash - - $ ansible-playbook playbook_coreos.yml - -Once the playbook quits, your new devices should be reachable through SSH. Try to connect to one and check if etcd has started properly: - -.. code-block:: bash - - tomk@work $ ssh -i id_rsa core@$one_of_the_servers_ip - core@coreos-one ~ $ etcdctl cluster-health - -Once you create a couple of devices, you might appreciate the dynamic inventory script... - - -Dynamic Inventory Script -======================== - -The dynamic inventory script queries the Packet API for a list of hosts, and exposes it to Ansible so you can easily identify and act on Packet devices. - -You can find it in Ansible Community General Collection's git repo at `scripts/inventory/packet_net.py `_. - -The inventory script is configurable through an `ini file `_. - -If you want to use the inventory script, you must first export your Packet API token to a PACKET_API_TOKEN environment variable. - -You can either copy the inventory and ini config out from the cloned git repo, or you can download it to your working directory like so: - -.. code-block:: bash - - $ wget https://raw.githubusercontent.com/ansible-community/contrib-scripts/main/inventory/packet_net.py - $ chmod +x packet_net.py - $ wget https://raw.githubusercontent.com/ansible-community/contrib-scripts/main/inventory/packet_net.ini - -In order to understand what the inventory script gives to Ansible you can run: - -.. code-block:: bash - - $ ./packet_net.py --list - -It should print a JSON document looking similar to following trimmed dictionary: - -.. code-block:: json - - { - "_meta": { - "hostvars": { - "147.75.64.169": { - "packet_billing_cycle": "hourly", - "packet_created_at": "2017-02-09T17:11:26Z", - "packet_facility": "ewr1", - "packet_hostname": "coreos-two", - "packet_href": "/devices/d0ab8972-54a8-4bff-832b-28549d1bec96", - "packet_id": "d0ab8972-54a8-4bff-832b-28549d1bec96", - "packet_locked": false, - "packet_operating_system": "coreos_beta", - "packet_plan": "baremetal_0", - "packet_state": "active", - "packet_updated_at": "2017-02-09T17:16:35Z", - "packet_user": "core", - "packet_userdata": "#cloud-config\ncoreos:\n etcd2:\n discovery: https://discovery.etcd.io/e0c8a4a9b8fe61acd51ec599e2a4f68e\n advertise-client-urls: http://$private_ipv4:2379,http://$private_ipv4:4001\n initial-advertise-peer-urls: http://$private_ipv4:2380\n listen-client-urls: http://0.0.0.0:2379,http://0.0.0.0:4001\n listen-peer-urls: http://$private_ipv4:2380\n fleet:\n public-ip: $private_ipv4\n units:\n - name: etcd2.service\n command: start\n - name: fleet.service\n command: start" - } - } - }, - "baremetal_0": [ - "147.75.202.255", - "147.75.202.251", - "147.75.202.249", - "147.75.64.129", - "147.75.192.51", - "147.75.64.169" - ], - "coreos_beta": [ - "147.75.202.255", - "147.75.202.251", - "147.75.202.249", - "147.75.64.129", - "147.75.192.51", - "147.75.64.169" - ], - "ewr1": [ - "147.75.64.129", - "147.75.192.51", - "147.75.64.169" - ], - "sjc1": [ - "147.75.202.255", - "147.75.202.251", - "147.75.202.249" - ], - "coreos-two": [ - "147.75.64.169" - ], - "d0ab8972-54a8-4bff-832b-28549d1bec96": [ - "147.75.64.169" - ] - } - -In the ``['_meta']['hostvars']`` key, there is a list of devices (uniquely identified by their public IPv4 address) with their parameters. The other keys under ``['_meta']`` are lists of devices grouped by some parameter. Here, it is type (all devices are of type baremetal_0), operating system, and facility (ewr1 and sjc1). - -In addition to the parameter groups, there are also one-item groups with the UUID or hostname of the device. - -You can now target groups in playbooks! The following playbook will install a role that supplies resources for an Ansible target into all devices in the "coreos_beta" group: - -.. code-block:: yaml - - # playbook_bootstrap.yml - - - hosts: coreos_beta - gather_facts: false - roles: - - defunctzombie.coreos-boostrap - -Don't forget to supply the dynamic inventory in the ``-i`` argument! - -.. code-block:: bash - - $ ansible-playbook -u core -i packet_net.py playbook_bootstrap.yml - - -If you have any questions or comments let us know! help@packet.net +The content on this page has moved to :ref:`ansible_collections.community.general.docsite.guide_packet`. diff --git a/docs/docsite/rst/scenario_guides/guide_rax.rst b/docs/docsite/rst/scenario_guides/guide_rax.rst deleted file mode 100644 index 439ba187250..00000000000 --- a/docs/docsite/rst/scenario_guides/guide_rax.rst +++ /dev/null @@ -1,809 +0,0 @@ -Rackspace Cloud Guide -===================== - -.. _rax_introduction: - -Introduction -```````````` - -.. note:: Rackspace functionality in Ansible is not maintained and users should consider the `OpenStack collection `_ instead. - -Ansible contains a number of core modules for interacting with Rackspace Cloud. - -The purpose of this section is to explain how to put Ansible modules together -(and use inventory scripts) to use Ansible in a Rackspace Cloud context. - -Prerequisites for using the rax modules are minimal. In addition to ansible itself, -all of the modules require and are tested against pyrax 1.5 or higher. -You'll need this Python module installed on the execution host. - -``pyrax`` is not currently available in many operating system -package repositories, so you will likely need to install it through pip: - -.. code-block:: bash - - $ pip install pyrax - -Ansible creates an implicit localhost that executes in the same context as the ``ansible-playbook`` and the other CLI tools. -If for any reason you need or want to have it in your inventory you should do something like the following: - -.. code-block:: ini - - [localhost] - localhost ansible_connection=local ansible_python_interpreter=/usr/local/bin/python2 - -For more information see :ref:`Implicit Localhost ` - -In playbook steps, we'll typically be using the following pattern: - -.. code-block:: yaml - - - hosts: localhost - gather_facts: False - tasks: - -.. _credentials_file: - -Credentials File -```````````````` - -The `rax.py` inventory script and all `rax` modules support a standard `pyrax` credentials file that looks like: - -.. code-block:: ini - - [rackspace_cloud] - username = myraxusername - api_key = d41d8cd98f00b204e9800998ecf8427e - -Setting the environment parameter ``RAX_CREDS_FILE`` to the path of this file will help Ansible find how to load -this information. - -More information about this credentials file can be found at -https://github.com/pycontribs/pyrax/blob/master/docs/getting_started.md#authenticating - - -.. _virtual_environment: - -Running from a Python Virtual Environment (Optional) -++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Most users will not be using virtualenv, but some users, particularly Python developers sometimes like to. - -There are special considerations when Ansible is installed to a Python virtualenv, rather than the default of installing at a global scope. Ansible assumes, unless otherwise instructed, that the python binary will live at /usr/bin/python. This is done through the interpreter line in modules, however when instructed by setting the inventory variable 'ansible_python_interpreter', Ansible will use this specified path instead to find Python. This can be a cause of confusion as one may assume that modules running on 'localhost', or perhaps running through 'local_action', are using the virtualenv Python interpreter. By setting this line in the inventory, the modules will execute in the virtualenv interpreter and have available the virtualenv packages, specifically pyrax. If using virtualenv, you may wish to modify your localhost inventory definition to find this location as follows: - -.. code-block:: ini - - [localhost] - localhost ansible_connection=local ansible_python_interpreter=/path/to/ansible_venv/bin/python - -.. note:: - - pyrax may be installed in the global Python package scope or in a virtual environment. There are no special considerations to keep in mind when installing pyrax. - -.. _provisioning: - -Provisioning -```````````` - -Now for the fun parts. - -The 'rax' module provides the ability to provision instances within Rackspace Cloud. Typically the provisioning task will be performed from your Ansible control server (in our example, localhost) against the Rackspace cloud API. This is done for several reasons: - - - Avoiding installing the pyrax library on remote nodes - - No need to encrypt and distribute credentials to remote nodes - - Speed and simplicity - -.. note:: - - Authentication with the Rackspace-related modules is handled by either - specifying your username and API key as environment variables or passing - them as module arguments, or by specifying the location of a credentials - file. - -Here is a basic example of provisioning an instance in ad hoc mode: - -.. code-block:: bash - - $ ansible localhost -m rax -a "name=awx flavor=4 image=ubuntu-1204-lts-precise-pangolin wait=yes" - -Here's what it would look like in a playbook, assuming the parameters were defined in variables: - -.. code-block:: yaml - - tasks: - - name: Provision a set of instances - rax: - name: "{{ rax_name }}" - flavor: "{{ rax_flavor }}" - image: "{{ rax_image }}" - count: "{{ rax_count }}" - group: "{{ group }}" - wait: true - register: rax - delegate_to: localhost - -The rax module returns data about the nodes it creates, like IP addresses, hostnames, and login passwords. By registering the return value of the step, it is possible used this data to dynamically add the resulting hosts to inventory (temporarily, in memory). This facilitates performing configuration actions on the hosts in a follow-on task. In the following example, the servers that were successfully created using the above task are dynamically added to a group called "raxhosts", with each nodes hostname, IP address, and root password being added to the inventory. - -.. code-block:: yaml - - - name: Add the instances we created (by public IP) to the group 'raxhosts' - add_host: - hostname: "{{ item.name }}" - ansible_host: "{{ item.rax_accessipv4 }}" - ansible_password: "{{ item.rax_adminpass }}" - groups: raxhosts - loop: "{{ rax.success }}" - when: rax.action == 'create' - -With the host group now created, the next play in this playbook could now configure servers belonging to the raxhosts group. - -.. code-block:: yaml - - - name: Configuration play - hosts: raxhosts - user: root - roles: - - ntp - - webserver - -The method above ties the configuration of a host with the provisioning step. This isn't always what you want, and leads us -to the next section. - -.. _host_inventory: - -Host Inventory -`````````````` - -Once your nodes are spun up, you'll probably want to talk to them again. The best way to handle this is to use the "rax" inventory plugin, which dynamically queries Rackspace Cloud and tells Ansible what nodes you have to manage. You might want to use this even if you are spinning up cloud instances through other tools, including the Rackspace Cloud user interface. The inventory plugin can be used to group resources by metadata, region, OS, and so on. Utilizing metadata is highly recommended in "rax" and can provide an easy way to sort between host groups and roles. If you don't want to use the ``rax.py`` dynamic inventory script, you could also still choose to manually manage your INI inventory file, though this is less recommended. - -In Ansible it is quite possible to use multiple dynamic inventory plugins along with INI file data. Just put them in a common directory and be sure the scripts are chmod +x, and the INI-based ones are not. - -.. _raxpy: - -rax.py -++++++ - -To use the Rackspace dynamic inventory script, copy ``rax.py`` into your inventory directory and make it executable. You can specify a credentials file for ``rax.py`` utilizing the ``RAX_CREDS_FILE`` environment variable. - -.. note:: Dynamic inventory scripts (like ``rax.py``) are saved in ``/usr/share/ansible/inventory`` if Ansible has been installed globally. If installed to a virtualenv, the inventory scripts are installed to ``$VIRTUALENV/share/inventory``. - -.. note:: Users of :ref:`ansible_platform` will note that dynamic inventory is natively supported by the controller in the platform, and all you have to do is associate a group with your Rackspace Cloud credentials, and it will easily synchronize without going through these steps:: - - $ RAX_CREDS_FILE=~/.raxpub ansible all -i rax.py -m setup - -``rax.py`` also accepts a ``RAX_REGION`` environment variable, which can contain an individual region, or a comma separated list of regions. - -When using ``rax.py``, you will not have a 'localhost' defined in the inventory. - -As mentioned previously, you will often be running most of these modules outside of the host loop, and will need 'localhost' defined. The recommended way to do this, would be to create an ``inventory`` directory, and place both the ``rax.py`` script and a file containing ``localhost`` in it. - -Executing ``ansible`` or ``ansible-playbook`` and specifying the ``inventory`` directory instead -of an individual file, will cause ansible to evaluate each file in that directory for inventory. - -Let's test our inventory script to see if it can talk to Rackspace Cloud. - -.. code-block:: bash - - $ RAX_CREDS_FILE=~/.raxpub ansible all -i inventory/ -m setup - -Assuming things are properly configured, the ``rax.py`` inventory script will output information similar to the -following information, which will be utilized for inventory and variables. - -.. code-block:: json - - { - "ORD": [ - "test" - ], - "_meta": { - "hostvars": { - "test": { - "ansible_host": "198.51.100.1", - "rax_accessipv4": "198.51.100.1", - "rax_accessipv6": "2001:DB8::2342", - "rax_addresses": { - "private": [ - { - "addr": "192.0.2.2", - "version": 4 - } - ], - "public": [ - { - "addr": "198.51.100.1", - "version": 4 - }, - { - "addr": "2001:DB8::2342", - "version": 6 - } - ] - }, - "rax_config_drive": "", - "rax_created": "2013-11-14T20:48:22Z", - "rax_flavor": { - "id": "performance1-1", - "links": [ - { - "href": "https://ord.servers.api.rackspacecloud.com/111111/flavors/performance1-1", - "rel": "bookmark" - } - ] - }, - "rax_hostid": "e7b6961a9bd943ee82b13816426f1563bfda6846aad84d52af45a4904660cde0", - "rax_human_id": "test", - "rax_id": "099a447b-a644-471f-87b9-a7f580eb0c2a", - "rax_image": { - "id": "b211c7bf-b5b4-4ede-a8de-a4368750c653", - "links": [ - { - "href": "https://ord.servers.api.rackspacecloud.com/111111/images/b211c7bf-b5b4-4ede-a8de-a4368750c653", - "rel": "bookmark" - } - ] - }, - "rax_key_name": null, - "rax_links": [ - { - "href": "https://ord.servers.api.rackspacecloud.com/v2/111111/servers/099a447b-a644-471f-87b9-a7f580eb0c2a", - "rel": "self" - }, - { - "href": "https://ord.servers.api.rackspacecloud.com/111111/servers/099a447b-a644-471f-87b9-a7f580eb0c2a", - "rel": "bookmark" - } - ], - "rax_metadata": { - "foo": "bar" - }, - "rax_name": "test", - "rax_name_attr": "name", - "rax_networks": { - "private": [ - "192.0.2.2" - ], - "public": [ - "198.51.100.1", - "2001:DB8::2342" - ] - }, - "rax_os-dcf_diskconfig": "AUTO", - "rax_os-ext-sts_power_state": 1, - "rax_os-ext-sts_task_state": null, - "rax_os-ext-sts_vm_state": "active", - "rax_progress": 100, - "rax_status": "ACTIVE", - "rax_tenant_id": "111111", - "rax_updated": "2013-11-14T20:49:27Z", - "rax_user_id": "22222" - } - } - } - } - -.. _standard_inventory: - -Standard Inventory -++++++++++++++++++ - -When utilizing a standard ini formatted inventory file (as opposed to the inventory plugin), it may still be advantageous to retrieve discoverable hostvar information from the Rackspace API. - -This can be achieved with the ``rax_facts`` module and an inventory file similar to the following: - -.. code-block:: ini - - [test_servers] - hostname1 rax_region=ORD - hostname2 rax_region=ORD - -.. code-block:: yaml - - - name: Gather info about servers - hosts: test_servers - gather_facts: False - tasks: - - name: Get facts about servers - rax_facts: - credentials: ~/.raxpub - name: "{{ inventory_hostname }}" - region: "{{ rax_region }}" - delegate_to: localhost - - name: Map some facts - set_fact: - ansible_host: "{{ rax_accessipv4 }}" - -While you don't need to know how it works, it may be interesting to know what kind of variables are returned. - -The ``rax_facts`` module provides facts as following, which match the ``rax.py`` inventory script: - -.. code-block:: json - - { - "ansible_facts": { - "rax_accessipv4": "198.51.100.1", - "rax_accessipv6": "2001:DB8::2342", - "rax_addresses": { - "private": [ - { - "addr": "192.0.2.2", - "version": 4 - } - ], - "public": [ - { - "addr": "198.51.100.1", - "version": 4 - }, - { - "addr": "2001:DB8::2342", - "version": 6 - } - ] - }, - "rax_config_drive": "", - "rax_created": "2013-11-14T20:48:22Z", - "rax_flavor": { - "id": "performance1-1", - "links": [ - { - "href": "https://ord.servers.api.rackspacecloud.com/111111/flavors/performance1-1", - "rel": "bookmark" - } - ] - }, - "rax_hostid": "e7b6961a9bd943ee82b13816426f1563bfda6846aad84d52af45a4904660cde0", - "rax_human_id": "test", - "rax_id": "099a447b-a644-471f-87b9-a7f580eb0c2a", - "rax_image": { - "id": "b211c7bf-b5b4-4ede-a8de-a4368750c653", - "links": [ - { - "href": "https://ord.servers.api.rackspacecloud.com/111111/images/b211c7bf-b5b4-4ede-a8de-a4368750c653", - "rel": "bookmark" - } - ] - }, - "rax_key_name": null, - "rax_links": [ - { - "href": "https://ord.servers.api.rackspacecloud.com/v2/111111/servers/099a447b-a644-471f-87b9-a7f580eb0c2a", - "rel": "self" - }, - { - "href": "https://ord.servers.api.rackspacecloud.com/111111/servers/099a447b-a644-471f-87b9-a7f580eb0c2a", - "rel": "bookmark" - } - ], - "rax_metadata": { - "foo": "bar" - }, - "rax_name": "test", - "rax_name_attr": "name", - "rax_networks": { - "private": [ - "192.0.2.2" - ], - "public": [ - "198.51.100.1", - "2001:DB8::2342" - ] - }, - "rax_os-dcf_diskconfig": "AUTO", - "rax_os-ext-sts_power_state": 1, - "rax_os-ext-sts_task_state": null, - "rax_os-ext-sts_vm_state": "active", - "rax_progress": 100, - "rax_status": "ACTIVE", - "rax_tenant_id": "111111", - "rax_updated": "2013-11-14T20:49:27Z", - "rax_user_id": "22222" - }, - "changed": false - } - - -Use Cases -````````` - -This section covers some additional usage examples built around a specific use case. - -.. _network_and_server: - -Network and Server -++++++++++++++++++ - -Create an isolated cloud network and build a server - -.. code-block:: yaml - - - name: Build Servers on an Isolated Network - hosts: localhost - gather_facts: False - tasks: - - name: Network create request - rax_network: - credentials: ~/.raxpub - label: my-net - cidr: 192.168.3.0/24 - region: IAD - state: present - delegate_to: localhost - - - name: Server create request - rax: - credentials: ~/.raxpub - name: web%04d.example.org - flavor: 2 - image: ubuntu-1204-lts-precise-pangolin - disk_config: manual - networks: - - public - - my-net - region: IAD - state: present - count: 5 - exact_count: true - group: web - wait: true - wait_timeout: 360 - register: rax - delegate_to: localhost - -.. _complete_environment: - -Complete Environment -++++++++++++++++++++ - -Build a complete webserver environment with servers, custom networks and load balancers, install nginx and create a custom index.html - -.. code-block:: yaml - - --- - - name: Build environment - hosts: localhost - gather_facts: False - tasks: - - name: Load Balancer create request - rax_clb: - credentials: ~/.raxpub - name: my-lb - port: 80 - protocol: HTTP - algorithm: ROUND_ROBIN - type: PUBLIC - timeout: 30 - region: IAD - wait: true - state: present - meta: - app: my-cool-app - register: clb - - - name: Network create request - rax_network: - credentials: ~/.raxpub - label: my-net - cidr: 192.168.3.0/24 - state: present - region: IAD - register: network - - - name: Server create request - rax: - credentials: ~/.raxpub - name: web%04d.example.org - flavor: performance1-1 - image: ubuntu-1204-lts-precise-pangolin - disk_config: manual - networks: - - public - - private - - my-net - region: IAD - state: present - count: 5 - exact_count: true - group: web - wait: true - register: rax - - - name: Add servers to web host group - add_host: - hostname: "{{ item.name }}" - ansible_host: "{{ item.rax_accessipv4 }}" - ansible_password: "{{ item.rax_adminpass }}" - ansible_user: root - groups: web - loop: "{{ rax.success }}" - when: rax.action == 'create' - - - name: Add servers to Load balancer - rax_clb_nodes: - credentials: ~/.raxpub - load_balancer_id: "{{ clb.balancer.id }}" - address: "{{ item.rax_networks.private|first }}" - port: 80 - condition: enabled - type: primary - wait: true - region: IAD - loop: "{{ rax.success }}" - when: rax.action == 'create' - - - name: Configure servers - hosts: web - handlers: - - name: restart nginx - service: name=nginx state=restarted - - tasks: - - name: Install nginx - apt: pkg=nginx state=latest update_cache=yes cache_valid_time=86400 - notify: - - restart nginx - - - name: Ensure nginx starts on boot - service: name=nginx state=started enabled=yes - - - name: Create custom index.html - copy: content="{{ inventory_hostname }}" dest=/usr/share/nginx/www/index.html - owner=root group=root mode=0644 - -.. _rackconnect_and_manged_cloud: - -RackConnect and Managed Cloud -+++++++++++++++++++++++++++++ - -When using RackConnect version 2 or Rackspace Managed Cloud there are Rackspace automation tasks that are executed on the servers you create after they are successfully built. If your automation executes before the RackConnect or Managed Cloud automation, you can cause failures and unusable servers. - -These examples show creating servers, and ensuring that the Rackspace automation has completed before Ansible continues onwards. - -For simplicity, these examples are joined, however both are only needed when using RackConnect. When only using Managed Cloud, the RackConnect portion can be ignored. - -The RackConnect portions only apply to RackConnect version 2. - -.. _using_a_control_machine: - -Using a Control Machine -*********************** - -.. code-block:: yaml - - - name: Create an exact count of servers - hosts: localhost - gather_facts: False - tasks: - - name: Server build requests - rax: - credentials: ~/.raxpub - name: web%03d.example.org - flavor: performance1-1 - image: ubuntu-1204-lts-precise-pangolin - disk_config: manual - region: DFW - state: present - count: 1 - exact_count: true - group: web - wait: true - register: rax - - - name: Add servers to in memory groups - add_host: - hostname: "{{ item.name }}" - ansible_host: "{{ item.rax_accessipv4 }}" - ansible_password: "{{ item.rax_adminpass }}" - ansible_user: root - rax_id: "{{ item.rax_id }}" - groups: web,new_web - loop: "{{ rax.success }}" - when: rax.action == 'create' - - - name: Wait for rackconnect and managed cloud automation to complete - hosts: new_web - gather_facts: false - tasks: - - name: ensure we run all tasks from localhost - delegate_to: localhost - block: - - name: Wait for rackconnnect automation to complete - rax_facts: - credentials: ~/.raxpub - id: "{{ rax_id }}" - region: DFW - register: rax_facts - until: rax_facts.ansible_facts['rax_metadata']['rackconnect_automation_status']|default('') == 'DEPLOYED' - retries: 30 - delay: 10 - - - name: Wait for managed cloud automation to complete - rax_facts: - credentials: ~/.raxpub - id: "{{ rax_id }}" - region: DFW - register: rax_facts - until: rax_facts.ansible_facts['rax_metadata']['rax_service_level_automation']|default('') == 'Complete' - retries: 30 - delay: 10 - - - name: Update new_web hosts with IP that RackConnect assigns - hosts: new_web - gather_facts: false - tasks: - - name: Get facts about servers - rax_facts: - name: "{{ inventory_hostname }}" - region: DFW - delegate_to: localhost - - name: Map some facts - set_fact: - ansible_host: "{{ rax_accessipv4 }}" - - - name: Base Configure Servers - hosts: web - roles: - - role: users - - - role: openssh - opensshd_PermitRootLogin: "no" - - - role: ntp - -.. _using_ansible_pull: - -Using Ansible Pull -****************** - -.. code-block:: yaml - - --- - - name: Ensure Rackconnect and Managed Cloud Automation is complete - hosts: all - tasks: - - name: ensure we run all tasks from localhost - delegate_to: localhost - block: - - name: Check for completed bootstrap - stat: - path: /etc/bootstrap_complete - register: bootstrap - - - name: Get region - command: xenstore-read vm-data/provider_data/region - register: rax_region - when: bootstrap.stat.exists != True - - - name: Wait for rackconnect automation to complete - uri: - url: "https://{{ rax_region.stdout|trim }}.api.rackconnect.rackspace.com/v1/automation_status?format=json" - return_content: true - register: automation_status - when: bootstrap.stat.exists != True - until: automation_status['automation_status']|default('') == 'DEPLOYED' - retries: 30 - delay: 10 - - - name: Wait for managed cloud automation to complete - wait_for: - path: /tmp/rs_managed_cloud_automation_complete - delay: 10 - when: bootstrap.stat.exists != True - - - name: Set bootstrap completed - file: - path: /etc/bootstrap_complete - state: touch - owner: root - group: root - mode: 0400 - - - name: Base Configure Servers - hosts: all - roles: - - role: users - - - role: openssh - opensshd_PermitRootLogin: "no" - - - role: ntp - -.. _using_ansible_pull_with_xenstore: - -Using Ansible Pull with XenStore -******************************** - -.. code-block:: yaml - - --- - - name: Ensure Rackconnect and Managed Cloud Automation is complete - hosts: all - tasks: - - name: Check for completed bootstrap - stat: - path: /etc/bootstrap_complete - register: bootstrap - - - name: Wait for rackconnect_automation_status xenstore key to exist - command: xenstore-exists vm-data/user-metadata/rackconnect_automation_status - register: rcas_exists - when: bootstrap.stat.exists != True - failed_when: rcas_exists.rc|int > 1 - until: rcas_exists.rc|int == 0 - retries: 30 - delay: 10 - - - name: Wait for rackconnect automation to complete - command: xenstore-read vm-data/user-metadata/rackconnect_automation_status - register: rcas - when: bootstrap.stat.exists != True - until: rcas.stdout|replace('"', '') == 'DEPLOYED' - retries: 30 - delay: 10 - - - name: Wait for rax_service_level_automation xenstore key to exist - command: xenstore-exists vm-data/user-metadata/rax_service_level_automation - register: rsla_exists - when: bootstrap.stat.exists != True - failed_when: rsla_exists.rc|int > 1 - until: rsla_exists.rc|int == 0 - retries: 30 - delay: 10 - - - name: Wait for managed cloud automation to complete - command: xenstore-read vm-data/user-metadata/rackconnect_automation_status - register: rsla - when: bootstrap.stat.exists != True - until: rsla.stdout|replace('"', '') == 'DEPLOYED' - retries: 30 - delay: 10 - - - name: Set bootstrap completed - file: - path: /etc/bootstrap_complete - state: touch - owner: root - group: root - mode: 0400 - - - name: Base Configure Servers - hosts: all - roles: - - role: users - - - role: openssh - opensshd_PermitRootLogin: "no" - - - role: ntp - -.. _advanced_usage: - -Advanced Usage -`````````````` - -.. _awx_autoscale: - -Autoscaling with AWX or Red Hat Ansible Automation Platform -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The GUI component of :ref:`Red Hat Ansible Automation Platform ` also contains a very nice feature for auto-scaling use cases. In this mode, a simple curl script can call -a defined URL and the server will "dial out" to the requester and configure an instance that is spinning up. This can be a great way -to reconfigure ephemeral nodes. See `the documentation on provisioning callbacks `_ for more details. - -A benefit of using the callback approach over pull mode is that job results are still centrally recorded -and less information has to be shared with remote hosts. - -.. _pending_information: - -Orchestration in the Rackspace Cloud -++++++++++++++++++++++++++++++++++++ - -Ansible is a powerful orchestration tool, and rax modules allow you the opportunity to orchestrate complex tasks, deployments, and configurations. The key here is to automate provisioning of infrastructure, like any other piece of software in an environment. Complex deployments might have previously required manual manipulation of load balancers, or manual provisioning of servers. Utilizing the rax modules included with Ansible, one can make the deployment of additional nodes contingent on the current number of running nodes, or the configuration of a clustered application dependent on the number of nodes with common metadata. One could automate the following scenarios, for example: - -* Servers that are removed from a Cloud Load Balancer one-by-one, updated, verified, and returned to the load balancer pool -* Expansion of an already-online environment, where nodes are provisioned, bootstrapped, configured, and software installed -* A procedure where app log files are uploaded to a central location, like Cloud Files, before a node is decommissioned -* Servers and load balancers that have DNS records created and destroyed on creation and decommissioning, respectively - - - - diff --git a/docs/docsite/rst/scenario_guides/guide_scaleway.rst b/docs/docsite/rst/scenario_guides/guide_scaleway.rst index 354daddcf1e..9dc4391651d 100644 --- a/docs/docsite/rst/scenario_guides/guide_scaleway.rst +++ b/docs/docsite/rst/scenario_guides/guide_scaleway.rst @@ -4,290 +4,4 @@ Scaleway Guide ************** -.. _scaleway_introduction: - -Introduction -============ - -`Scaleway `_ is a cloud provider supported by Ansible, version 2.6 or higher through a dynamic inventory plugin and modules. -Those modules are: - -- :ref:`scaleway_sshkey_module`: adds a public SSH key from a file or value to the Packet infrastructure. Every subsequently-created device will have this public key installed in .ssh/authorized_keys. -- :ref:`scaleway_compute_module`: manages servers on Scaleway. You can use this module to create, restart and delete servers. -- :ref:`scaleway_volume_module`: manages volumes on Scaleway. - -.. note:: - This guide assumes you are familiar with Ansible and how it works. - If you're not, have a look at :ref:`ansible_documentation` before getting started. - -.. _scaleway_requirements: - -Requirements -============ - -The Scaleway modules and inventory script connect to the Scaleway API using `Scaleway REST API `_. -To use the modules and inventory script you'll need a Scaleway API token. -You can generate an API token through the Scaleway console `here `__. -The simplest way to authenticate yourself is to set the Scaleway API token in an environment variable: - -.. code-block:: bash - - $ export SCW_TOKEN=00000000-1111-2222-3333-444444444444 - -If you're not comfortable exporting your API token, you can pass it as a parameter to the modules using the ``api_token`` argument. - -If you want to use a new SSH key pair in this tutorial, you can generate it to ``./id_rsa`` and ``./id_rsa.pub`` as: - -.. code-block:: bash - - $ ssh-keygen -t rsa -f ./id_rsa - -If you want to use an existing key pair, just copy the private and public key over to the playbook directory. - -.. _scaleway_add_sshkey: - -How to add an SSH key? -====================== - -Connection to Scaleway Compute nodes use Secure Shell. -SSH keys are stored at the account level, which means that you can reuse the same SSH key in multiple nodes. -The first step to configure Scaleway compute resources is to have at least one SSH key configured. - -:ref:`scaleway_sshkey_module` is a module that manages SSH keys on your Scaleway account. -You can add an SSH key to your account by including the following task in a playbook: - -.. code-block:: yaml - - - name: "Add SSH key" - scaleway_sshkey: - ssh_pub_key: "ssh-rsa AAAA..." - state: "present" - -The ``ssh_pub_key`` parameter contains your ssh public key as a string. Here is an example inside a playbook: - - -.. code-block:: yaml - - - name: Test SSH key lifecycle on a Scaleway account - hosts: localhost - gather_facts: false - environment: - SCW_API_KEY: "" - - tasks: - - - scaleway_sshkey: - ssh_pub_key: "ssh-rsa AAAAB...424242 developer@example.com" - state: present - register: result - - - assert: - that: - - result is success and result is changed - -.. _scaleway_create_instance: - -How to create a compute instance? -================================= - -Now that we have an SSH key configured, the next step is to spin up a server! -:ref:`scaleway_compute_module` is a module that can create, update and delete Scaleway compute instances: - -.. code-block:: yaml - - - name: Create a server - scaleway_compute: - name: foobar - state: present - image: 00000000-1111-2222-3333-444444444444 - organization: 00000000-1111-2222-3333-444444444444 - region: ams1 - commercial_type: START1-S - -Here are the parameter details for the example shown above: - -- ``name`` is the name of the instance (the one that will show up in your web console). -- ``image`` is the UUID of the system image you would like to use. - A list of all images is available for each availability zone. -- ``organization`` represents the organization that your account is attached to. -- ``region`` represents the Availability Zone which your instance is in (for this example, par1 and ams1). -- ``commercial_type`` represents the name of the commercial offers. - You can check out the Scaleway pricing page to find which instance is right for you. - -Take a look at this short playbook to see a working example using ``scaleway_compute``: - -.. code-block:: yaml - - - name: Test compute instance lifecycle on a Scaleway account - hosts: localhost - gather_facts: false - environment: - SCW_API_KEY: "" - - tasks: - - - name: Create a server - register: server_creation_task - scaleway_compute: - name: foobar - state: present - image: 00000000-1111-2222-3333-444444444444 - organization: 00000000-1111-2222-3333-444444444444 - region: ams1 - commercial_type: START1-S - wait: true - - - debug: var=server_creation_task - - - assert: - that: - - server_creation_task is success - - server_creation_task is changed - - - name: Run it - scaleway_compute: - name: foobar - state: running - image: 00000000-1111-2222-3333-444444444444 - organization: 00000000-1111-2222-3333-444444444444 - region: ams1 - commercial_type: START1-S - wait: true - tags: - - web_server - register: server_run_task - - - debug: var=server_run_task - - - assert: - that: - - server_run_task is success - - server_run_task is changed - -.. _scaleway_dynamic_inventory_tutorial: - -Dynamic Inventory Script -======================== - -Ansible ships with :ref:`scaleway_inventory`. -You can now get a complete inventory of your Scaleway resources through this plugin and filter it on -different parameters (``regions`` and ``tags`` are currently supported). - -Let's create an example! -Suppose that we want to get all hosts that got the tag web_server. -Create a file named ``scaleway_inventory.yml`` with the following content: - -.. code-block:: yaml - - plugin: scaleway - regions: - - ams1 - - par1 - tags: - - web_server - -This inventory means that we want all hosts that got the tag ``web_server`` on the zones ``ams1`` and ``par1``. -Once you have configured this file, you can get the information using the following command: - -.. code-block:: bash - - $ ansible-inventory --list -i scaleway_inventory.yml - -The output will be: - -.. code-block:: yaml - - { - "_meta": { - "hostvars": { - "dd8e3ae9-0c7c-459e-bc7b-aba8bfa1bb8d": { - "ansible_verbosity": 6, - "arch": "x86_64", - "commercial_type": "START1-S", - "hostname": "foobar", - "ipv4": "192.0.2.1", - "organization": "00000000-1111-2222-3333-444444444444", - "state": "running", - "tags": [ - "web_server" - ] - } - } - }, - "all": { - "children": [ - "ams1", - "par1", - "ungrouped", - "web_server" - ] - }, - "ams1": {}, - "par1": { - "hosts": [ - "dd8e3ae9-0c7c-459e-bc7b-aba8bfa1bb8d" - ] - }, - "ungrouped": {}, - "web_server": { - "hosts": [ - "dd8e3ae9-0c7c-459e-bc7b-aba8bfa1bb8d" - ] - } - } - -As you can see, we get different groups of hosts. -``par1`` and ``ams1`` are groups based on location. -``web_server`` is a group based on a tag. - -In case a filter parameter is not defined, the plugin supposes all values possible are wanted. -This means that for each tag that exists on your Scaleway compute nodes, a group based on each tag will be created. - -Scaleway S3 object storage -========================== - -`Object Storage `_ allows you to store any kind of objects (documents, images, videos, and so on). -As the Scaleway API is S3 compatible, Ansible supports it natively through the modules: :ref:`s3_bucket_module`, :ref:`aws_s3_module`. - -You can find many examples in the `scaleway_s3 integration tests `_. - -.. code-block:: yaml+jinja - - - hosts: myserver - vars: - scaleway_region: nl-ams - s3_url: https://s3.nl-ams.scw.cloud - environment: - # AWS_ACCESS_KEY matches your scaleway organization id available at https://cloud.scaleway.com/#/account - AWS_ACCESS_KEY: 00000000-1111-2222-3333-444444444444 - # AWS_SECRET_KEY matches a secret token that you can retrieve at https://cloud.scaleway.com/#/credentials - AWS_SECRET_KEY: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - module_defaults: - group/aws: - s3_url: '{{ s3_url }}' - region: '{{ scaleway_region }}' - tasks: - # use a fact instead of a variable, otherwise template is evaluate each time variable is used - - set_fact: - bucket_name: "{{ 99999999 | random | to_uuid }}" - - # "requester_pays:" is mandatory because Scaleway doesn't implement related API - # another way is to use aws_s3 and "mode: create" ! - - s3_bucket: - name: '{{ bucket_name }}' - requester_pays: - - - name: Another way to create the bucket - aws_s3: - bucket: '{{ bucket_name }}' - mode: create - encrypt: false - register: bucket_creation_check - - - name: add something in the bucket - aws_s3: - mode: put - bucket: '{{ bucket_name }}' - src: /tmp/test.txt # needs to be created before - object: test.txt - encrypt: false # server side encryption must be disabled +The content on this page has moved to :ref:`ansible_collections.community.general.docsite.guide_scaleway`. diff --git a/docs/docsite/rst/scenario_guides/guides.rst b/docs/docsite/rst/scenario_guides/guides.rst index 4d3d62fc869..a66dc3a691e 100644 --- a/docs/docsite/rst/scenario_guides/guides.rst +++ b/docs/docsite/rst/scenario_guides/guides.rst @@ -18,15 +18,9 @@ We are migrating these guides into collections. Please update your links for the :maxdepth: 1 :caption: Legacy Public Cloud Guides - guide_alicloud guide_cloudstack guide_gce guide_azure - guide_online - guide_oracle - guide_packet - guide_rax - guide_scaleway .. toctree:: :maxdepth: 1 From 54234dc1d4c3b64fb427d1d429ac9372a019f6a1 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Mon, 11 Dec 2023 16:19:04 -0600 Subject: [PATCH 137/536] clone-core.py: allow specifying custom branch and repo (#954) This will be used to run docs-build tests in ansible-core's CI. --- docs/bin/clone-core.py | 62 ++++++++++++++++++++++++++++++------------ 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/docs/bin/clone-core.py b/docs/bin/clone-core.py index 7c675ad3818..4ef29087948 100755 --- a/docs/bin/clone-core.py +++ b/docs/bin/clone-core.py @@ -6,6 +6,8 @@ from __future__ import annotations +import argparse +import dataclasses import pathlib import shutil import subprocess @@ -13,9 +15,42 @@ import tempfile ROOT = pathlib.Path(__file__).resolve().parent.parent.parent - - -def main() -> None: +DEFAULT_BRANCH = (ROOT / "docs" / "ansible-core-branch.txt").read_text().strip() +DEFAULT_ANSIBLE_CORE_REPO = "https://github.com/ansible/ansible" + + +@dataclasses.dataclass() +class Args: + branch: str | None + repo: str + + +def parse_args(args: list[str] | None = None) -> Args: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "-b", + "--branch", + help="Set the branch of ansible-core to clone." + " Defaults to current branch (%(default)s)", + default=DEFAULT_BRANCH, + ) + parser.add_argument( + "--no-branch", + help="Checkout the default git branch of --remote." + " This is useful when cloning a local ansible-core fork", + dest="branch", + action="store_const", + const=None, + ) + parser.add_argument( + "--repo", + help="ansible-core repository to check out. Default: %(default)s", + default=DEFAULT_ANSIBLE_CORE_REPO, + ) + return Args(**vars(parser.parse_args(args))) + + +def main(args: Args) -> None: keep_dirs = [ "bin", "lib", @@ -31,21 +66,12 @@ def main() -> None: "setup.py", ] - branch = (ROOT / "docs" / "ansible-core-branch.txt").read_text().strip() - with tempfile.TemporaryDirectory() as temp_dir: - subprocess.run( - [ - "git", - "clone", - "https://github.com/ansible/ansible", - "--depth=1", - "-b", - branch, - temp_dir, - ], - check=True, - ) + cmd: list[str] = ["git", "clone", args.repo, "--depth=1"] + if args.branch is not None: + cmd.append(f"--branch={args.branch}") + cmd.append(temp_dir) + subprocess.run(cmd, check=True) for keep_dir in keep_dirs: src = pathlib.Path(temp_dir, keep_dir) @@ -70,4 +96,4 @@ def main() -> None: if __name__ == "__main__": - main() + main(parse_args()) From 4e3dff07816e4ab1e5d09af5c0899efc0b02b3e6 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 12 Dec 2023 16:01:57 -0500 Subject: [PATCH 138/536] remove more Old scenarios (#971) * remove google, cloudstack, and azure scenario guides (cherry picked from commit 4d43890efa8592512c4b9e31b863587dcf7a67b0) * remove google, azure, and cloudstack guides --- .../rst/scenario_guides/cloud_guides.rst | 7 +- .../rst/scenario_guides/guide_azure.rst | 484 ------------------ .../rst/scenario_guides/guide_cloudstack.rst | 377 -------------- .../docsite/rst/scenario_guides/guide_gce.rst | 309 ----------- docs/docsite/rst/scenario_guides/guides.rst | 8 - 5 files changed, 1 insertion(+), 1184 deletions(-) delete mode 100644 docs/docsite/rst/scenario_guides/guide_azure.rst delete mode 100644 docs/docsite/rst/scenario_guides/guide_cloudstack.rst delete mode 100644 docs/docsite/rst/scenario_guides/guide_gce.rst diff --git a/docs/docsite/rst/scenario_guides/cloud_guides.rst b/docs/docsite/rst/scenario_guides/cloud_guides.rst index b0b8f370148..ba75c0a3c95 100644 --- a/docs/docsite/rst/scenario_guides/cloud_guides.rst +++ b/docs/docsite/rst/scenario_guides/cloud_guides.rst @@ -10,9 +10,4 @@ Guides for using public clouds are moving into collections. We are migrating the :ref:`ansible_collections.amazon.aws.docsite.aws_intro` -.. toctree:: - :maxdepth: 1 - - guide_cloudstack - guide_gce - guide_azure + diff --git a/docs/docsite/rst/scenario_guides/guide_azure.rst b/docs/docsite/rst/scenario_guides/guide_azure.rst deleted file mode 100644 index 648ea56c65b..00000000000 --- a/docs/docsite/rst/scenario_guides/guide_azure.rst +++ /dev/null @@ -1,484 +0,0 @@ -Microsoft Azure Guide -===================== - -.. important:: - - Red Hat Ansible Automation Platform will soon be available on Microsoft Azure. `Sign up to preview the experience `_. - -Ansible includes a suite of modules for interacting with Azure Resource Manager, giving you the tools to easily create -and orchestrate infrastructure on the Microsoft Azure Cloud. - -Requirements ------------- - -Using the Azure Resource Manager modules requires having specific Azure SDK modules -installed on the host running Ansible. - -.. code-block:: bash - - $ pip install 'ansible[azure]' - -If you are running Ansible from source, you can install the dependencies from the -root directory of the Ansible repo. - -.. code-block:: bash - - $ pip install .[azure] - -You can also directly run Ansible in `Azure Cloud Shell `_, where Ansible is pre-installed. - -Authenticating with Azure -------------------------- - -Using the Azure Resource Manager modules requires authenticating with the Azure API. You can choose from two authentication strategies: - -* Active Directory Username/Password -* Service Principal Credentials - -Follow the directions for the strategy you wish to use, then proceed to `Providing Credentials to Azure Modules`_ for -instructions on how to actually use the modules and authenticate with the Azure API. - - -Using Service Principal -....................... - -There is now a detailed official tutorial describing `how to create a service principal `_. - -After stepping through the tutorial you will have: - -* Your Client ID, which is found in the "client id" box in the "Configure" page of your application in the Azure portal -* Your Secret key, generated when you created the application. You cannot show the key after creation. - If you lost the key, you must create a new one in the "Configure" page of your application. -* And finally, a tenant ID. It is a UUID (for example, ABCDEFGH-1234-ABCD-1234-ABCDEFGHIJKL) pointing to the AD containing your - application. You will find it in the URL from within the Azure portal, or in the "view endpoints" of any given URL. - - -Using Active Directory Username/Password -........................................ - -To create an Active Directory username/password: - -* Connect to the Azure Classic Portal with your admin account -* Create a user in your default AAD. You must NOT activate Multi-Factor Authentication -* Go to Settings - Administrators -* Click on Add and enter the email of the new user. -* Check the checkbox of the subscription you want to test with this user. -* Login to Azure Portal with this new user to change the temporary password to a new one. You will not be able to use the - temporary password for OAuth login. - -Providing Credentials to Azure Modules -...................................... - -The modules offer several ways to provide your credentials. For a CI/CD tool such as Ansible AWX or Jenkins, you will -most likely want to use environment variables. For local development you may wish to store your credentials in a file -within your home directory. And of course, you can always pass credentials as parameters to a task within a playbook. The -order of precedence is parameters, then environment variables, and finally a file found in your home directory. - -Using Environment Variables -``````````````````````````` - -To pass service principal credentials through the environment, define the following variables: - -* AZURE_CLIENT_ID -* AZURE_SECRET -* AZURE_SUBSCRIPTION_ID -* AZURE_TENANT - -To pass Active Directory username/password through the environment, define the following variables: - -* AZURE_AD_USER -* AZURE_PASSWORD -* AZURE_SUBSCRIPTION_ID - -To pass Active Directory username/password in ADFS through the environment, define the following variables: - -* AZURE_AD_USER -* AZURE_PASSWORD -* AZURE_CLIENT_ID -* AZURE_TENANT -* AZURE_ADFS_AUTHORITY_URL - -"AZURE_ADFS_AUTHORITY_URL" is optional. It is necessary only when you have own ADFS authority like https://yourdomain.com/adfs. - -Storing in a File -````````````````` - -When working in a development environment, it may be desirable to store credentials in a file. The modules will look -for credentials in ``$HOME/.azure/credentials``. This file is an ini style file. It will look as follows: - -.. code-block:: ini - - [default] - subscription_id=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - client_id=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - secret=xxxxxxxxxxxxxxxxx - tenant=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - -.. note:: If your secret values contain non-ASCII characters, you must `URL Encode `_ them to avoid login errors. - -It is possible to store multiple sets of credentials within the credentials file by creating multiple sections. Each -section is considered a profile. The modules look for the [default] profile automatically. Define AZURE_PROFILE in the -environment or pass a profile parameter to specify a specific profile. - -Passing as Parameters -````````````````````` - -If you wish to pass credentials as parameters to a task, use the following parameters for service principal: - -* client_id -* secret -* subscription_id -* tenant - -Or, pass the following parameters for Active Directory username/password: - -* ad_user -* password -* subscription_id - -Or, pass the following parameters for ADFS username/password: - -* ad_user -* password -* client_id -* tenant -* adfs_authority_url - -"adfs_authority_url" is optional. It is necessary only when you have own ADFS authority like https://yourdomain.com/adfs. - - -Other Cloud Environments ------------------------- - -To use an Azure Cloud other than the default public cloud (for example, Azure China Cloud, Azure US Government Cloud, Azure Stack), -pass the "cloud_environment" argument to modules, configure it in a credential profile, or set the "AZURE_CLOUD_ENVIRONMENT" -environment variable. The value is either a cloud name as defined by the Azure Python SDK (for example, "AzureChinaCloud", -"AzureUSGovernment"; defaults to "AzureCloud") or an Azure metadata discovery URL (for Azure Stack). - -Creating Virtual Machines -------------------------- - -There are two ways to create a virtual machine, both involving the azure_rm_virtualmachine module. We can either create -a storage account, network interface, security group and public IP address and pass the names of these objects to the -module as parameters, or we can let the module do the work for us and accept the defaults it chooses. - -Creating Individual Components -.............................. - -An Azure module is available to help you create a storage account, virtual network, subnet, network interface, -security group and public IP. Here is a full example of creating each of these and passing the names to the -``azure.azcollection.azure_rm_virtualmachine`` module at the end: - -.. code-block:: yaml - - - name: Create storage account - azure.azcollection.azure_rm_storageaccount: - resource_group: Testing - name: testaccount001 - account_type: Standard_LRS - - - name: Create virtual network - azure.azcollection.azure_rm_virtualnetwork: - resource_group: Testing - name: testvn001 - address_prefixes: "10.10.0.0/16" - - - name: Add subnet - azure.azcollection.azure_rm_subnet: - resource_group: Testing - name: subnet001 - address_prefix: "10.10.0.0/24" - virtual_network: testvn001 - - - name: Create public ip - azure.azcollection.azure_rm_publicipaddress: - resource_group: Testing - allocation_method: Static - name: publicip001 - - - name: Create security group that allows SSH - azure.azcollection.azure_rm_securitygroup: - resource_group: Testing - name: secgroup001 - rules: - - name: SSH - protocol: Tcp - destination_port_range: 22 - access: Allow - priority: 101 - direction: Inbound - - - name: Create NIC - azure.azcollection.azure_rm_networkinterface: - resource_group: Testing - name: testnic001 - virtual_network: testvn001 - subnet: subnet001 - public_ip_name: publicip001 - security_group: secgroup001 - - - name: Create virtual machine - azure.azcollection.azure_rm_virtualmachine: - resource_group: Testing - name: testvm001 - vm_size: Standard_D1 - storage_account: testaccount001 - storage_container: testvm001 - storage_blob: testvm001.vhd - admin_username: admin - admin_password: Password! - network_interfaces: testnic001 - image: - offer: CentOS - publisher: OpenLogic - sku: '7.1' - version: latest - -Each of the Azure modules offers a variety of parameter options. Not all options are demonstrated in the above example. -See each individual module for further details and examples. - - -Creating a Virtual Machine with Default Options -............................................... - -If you simply want to create a virtual machine without specifying all the details, you can do that as well. The only -caveat is that you will need a virtual network with one subnet already in your resource group. Assuming you have a -virtual network already with an existing subnet, you can run the following to create a VM: - -.. code-block:: yaml - - azure.azcollection.azure_rm_virtualmachine: - resource_group: Testing - name: testvm10 - vm_size: Standard_D1 - admin_username: chouseknecht - ssh_password_enabled: false - ssh_public_keys: "{{ ssh_keys }}" - image: - offer: CentOS - publisher: OpenLogic - sku: '7.1' - version: latest - - -Creating a Virtual Machine in Availability Zones -.................................................. - -If you want to create a VM in an availability zone, -consider the following: - -* Both OS disk and data disk must be a 'managed disk', not an 'unmanaged disk'. -* When creating a VM with the ``azure.azcollection.azure_rm_virtualmachine`` module, - you need to explicitly set the ``managed_disk_type`` parameter - to change the OS disk to a managed disk. - Otherwise, the OS disk becomes an unmanaged disk. -* When you create a data disk with the ``azure.azcollection.azure_rm_manageddisk`` module, - you need to explicitly specify the ``storage_account_type`` parameter - to make it a managed disk. - Otherwise, the data disk will be an unmanaged disk. -* A managed disk does not require a storage account or a storage container, - unlike an unmanaged disk. - In particular, note that once a VM is created on an unmanaged disk, - an unnecessary storage container named "vhds" is automatically created. -* When you create an IP address with the ``azure.azcollection.azure_rm_publicipaddress`` module, - you must set the ``sku`` parameter to ``standard``. - Otherwise, the IP address cannot be used in an availability zone. - - -Dynamic Inventory Script ------------------------- - -If you are not familiar with Ansible's dynamic inventory scripts, check out :ref:`Intro to Dynamic Inventory `. - -The Azure Resource Manager inventory script is called `azure_rm.py `_. It authenticates with the Azure API exactly the same as the -Azure modules, which means you will either define the same environment variables described above in `Using Environment Variables`_, -create a ``$HOME/.azure/credentials`` file (also described above in `Storing in a File`_), or pass command line parameters. To see available command -line options execute the following: - -.. code-block:: bash - - $ wget https://raw.githubusercontent.com/ansible-community/contrib-scripts/main/inventory/azure_rm.py - $ ./azure_rm.py --help - -As with all dynamic inventory scripts, the script can be executed directly, passed as a parameter to the ansible command, -or passed directly to ansible-playbook using the -i option. No matter how it is executed the script produces JSON representing -all of the hosts found in your Azure subscription. You can narrow this down to just hosts found in a specific set of -Azure resource groups, or even down to a specific host. - -For a given host, the inventory script provides the following host variables: - -.. code-block:: JSON - - { - "ansible_host": "XXX.XXX.XXX.XXX", - "computer_name": "computer_name2", - "fqdn": null, - "id": "/subscriptions/subscription-id/resourceGroups/galaxy-production/providers/Microsoft.Compute/virtualMachines/object-name", - "image": { - "offer": "CentOS", - "publisher": "OpenLogic", - "sku": "7.1", - "version": "latest" - }, - "location": "westus", - "mac_address": "00-00-5E-00-53-FE", - "name": "object-name", - "network_interface": "interface-name", - "network_interface_id": "/subscriptions/subscription-id/resourceGroups/galaxy-production/providers/Microsoft.Network/networkInterfaces/object-name1", - "network_security_group": null, - "network_security_group_id": null, - "os_disk": { - "name": "object-name", - "operating_system_type": "Linux" - }, - "plan": null, - "powerstate": "running", - "private_ip": "172.26.3.6", - "private_ip_alloc_method": "Static", - "provisioning_state": "Succeeded", - "public_ip": "XXX.XXX.XXX.XXX", - "public_ip_alloc_method": "Static", - "public_ip_id": "/subscriptions/subscription-id/resourceGroups/galaxy-production/providers/Microsoft.Network/publicIPAddresses/object-name", - "public_ip_name": "object-name", - "resource_group": "galaxy-production", - "security_group": "object-name", - "security_group_id": "/subscriptions/subscription-id/resourceGroups/galaxy-production/providers/Microsoft.Network/networkSecurityGroups/object-name", - "tags": { - "db": "mysql" - }, - "type": "Microsoft.Compute/virtualMachines", - "virtual_machine_size": "Standard_DS4" - } - -Host Groups -........... - -By default, hosts are grouped by: - -* azure (all hosts) -* location name -* resource group name -* security group name -* tag key -* tag key_value -* os_disk operating_system_type (Windows/Linux) - -You can control host groupings and host selection by either defining environment variables or creating an -azure_rm.ini file in your current working directory. - -NOTE: An .ini file will take precedence over environment variables. - -NOTE: The name of the .ini file is the basename of the inventory script (in other words, 'azure_rm') with a '.ini' -extension. This allows you to copy, rename and customize the inventory script and have matching .ini files all in -the same directory. - -Control grouping using the following variables defined in the environment: - -* AZURE_GROUP_BY_RESOURCE_GROUP=yes -* AZURE_GROUP_BY_LOCATION=yes -* AZURE_GROUP_BY_SECURITY_GROUP=yes -* AZURE_GROUP_BY_TAG=yes -* AZURE_GROUP_BY_OS_FAMILY=yes - -Select hosts within specific resource groups by assigning a comma separated list to: - -* AZURE_RESOURCE_GROUPS=resource_group_a,resource_group_b - -Select hosts for specific tag key by assigning a comma separated list of tag keys to: - -* AZURE_TAGS=key1,key2,key3 - -Select hosts for specific locations by assigning a comma separated list of locations to: - -* AZURE_LOCATIONS=eastus,eastus2,westus - -Or, select hosts for specific tag key:value pairs by assigning a comma separated list key:value pairs to: - -* AZURE_TAGS=key1:value1,key2:value2 - -If you don't need the powerstate, you can improve performance by turning off powerstate fetching: - -* AZURE_INCLUDE_POWERSTATE=no - -A sample azure_rm.ini file is included along with the inventory script in -`here `_. -An .ini file will contain the following: - -.. code-block:: ini - - [azure] - # Control which resource groups are included. By default, all resources groups are included. - # Set resource_groups to a comma separated list of resource groups names. - #resource_groups= - - # Control which tags are included. Set tags to a comma separated list of keys or key:value pairs - #tags= - - # Control which locations are included. Set locations to a comma separated list of locations. - #locations= - - # Include powerstate. If you don't need powerstate information, turning it off improves runtime performance. - # Valid values: yes, no, true, false, True, False, 0, 1. - include_powerstate=yes - - # Control grouping with the following boolean flags. Valid values: yes, no, true, false, True, False, 0, 1. - group_by_resource_group=yes - group_by_location=yes - group_by_security_group=yes - group_by_tag=yes - group_by_os_family=yes - -Examples -........ - -Here are some examples using the inventory script: - -.. code-block:: bash - - # Download inventory script - $ wget https://raw.githubusercontent.com/ansible-community/contrib-scripts/main/inventory/azure_rm.py - - # Execute /bin/uname on all instances in the Testing resource group - $ ansible -i azure_rm.py Testing -m shell -a "/bin/uname -a" - - # Execute win_ping on all Windows instances - $ ansible -i azure_rm.py windows -m win_ping - - # Execute ping on all Linux instances - $ ansible -i azure_rm.py linux -m ping - - # Use the inventory script to print instance specific information - $ ./azure_rm.py --host my_instance_host_name --resource-groups=Testing --pretty - - # Use the inventory script with ansible-playbook - $ ansible-playbook -i ./azure_rm.py test_playbook.yml - -Here is a simple playbook to exercise the Azure inventory script: - -.. code-block:: yaml - - - name: Test the inventory script - hosts: azure - connection: local - gather_facts: false - tasks: - - debug: - msg: "{{ inventory_hostname }} has powerstate {{ powerstate }}" - -You can execute the playbook with something like: - -.. code-block:: bash - - $ ansible-playbook -i ./azure_rm.py test_azure_inventory.yml - - -Disabling certificate validation on Azure endpoints -................................................... - -When an HTTPS proxy is present, or when using Azure Stack, it may be necessary to disable certificate validation for -Azure endpoints in the Azure modules. This is not a recommended security practice, but may be necessary when the system -CA store cannot be altered to include the necessary CA certificate. Certificate validation can be controlled by setting -the "cert_validation_mode" value in a credential profile, through the "AZURE_CERT_VALIDATION_MODE" environment variable, or -by passing the "cert_validation_mode" argument to any Azure module. The default value is "validate"; setting the value -to "ignore" will prevent all certificate validation. The module argument takes precedence over a credential profile value, -which takes precedence over the environment value. diff --git a/docs/docsite/rst/scenario_guides/guide_cloudstack.rst b/docs/docsite/rst/scenario_guides/guide_cloudstack.rst deleted file mode 100644 index 6d3f2b4d5ec..00000000000 --- a/docs/docsite/rst/scenario_guides/guide_cloudstack.rst +++ /dev/null @@ -1,377 +0,0 @@ -CloudStack Cloud Guide -====================== - -.. _cloudstack_introduction: - -Introduction -```````````` -The purpose of this section is to explain how to put Ansible modules together to use Ansible in a CloudStack context. You will find more usage examples in the details section of each module. - -Ansible contains a number of extra modules for interacting with CloudStack based clouds. All modules support check mode, are designed to be idempotent, have been created and tested, and are maintained by the community. - -.. note:: Some of the modules will require domain admin or root admin privileges. - -Prerequisites -````````````` -Prerequisites for using the CloudStack modules are minimal. In addition to Ansible itself, all of the modules require the python library ``cs`` https://pypi.org/project/cs/ - -You'll need this Python module installed on the execution host, usually your workstation. - -.. code-block:: bash - - $ pip install cs - -Or alternatively starting with Debian 9 and Ubuntu 16.04: - -.. code-block:: bash - - $ sudo apt install python-cs - -.. note:: cs also includes a command line interface for ad hoc interaction with the CloudStack API, for example ``$ cs listVirtualMachines state=Running``. - -Limitations and Known Issues -```````````````````````````` -VPC support has been improved since Ansible 2.3 but is still not yet fully implemented. The community is working on the VPC integration. - -Credentials File -```````````````` -You can pass credentials and the endpoint of your cloud as module arguments, however in most cases it is a far less work to store your credentials in the cloudstack.ini file. - -The python library cs looks for the credentials file in the following order (last one wins): - -* A ``.cloudstack.ini`` (note the dot) file in the home directory. -* A ``CLOUDSTACK_CONFIG`` environment variable pointing to an .ini file. -* A ``cloudstack.ini`` (without the dot) file in the current working directory, same directory as your playbooks are located. - -The structure of the ini file must look like this: - -.. code-block:: bash - - $ cat $HOME/.cloudstack.ini - [cloudstack] - endpoint = https://cloud.example.com/client/api - key = api key - secret = api secret - timeout = 30 - -.. Note:: The section ``[cloudstack]`` is the default section. ``CLOUDSTACK_REGION`` environment variable can be used to define the default section. - -.. versionadded:: 2.4 - -The ENV variables support ``CLOUDSTACK_*`` as written in the documentation of the library ``cs``, like ``CLOUDSTACK_TIMEOUT``, ``CLOUDSTACK_METHOD``, and so on. has been implemented into Ansible. It is even possible to have some incomplete config in your cloudstack.ini: - -.. code-block:: bash - - $ cat $HOME/.cloudstack.ini - [cloudstack] - endpoint = https://cloud.example.com/client/api - timeout = 30 - -and fulfill the missing data by either setting ENV variables or tasks params: - -.. code-block:: yaml - - --- - - name: provision our VMs - hosts: cloud-vm - tasks: - - name: ensure VMs are created and running - delegate_to: localhost - cs_instance: - api_key: your api key - api_secret: your api secret - ... - -Regions -``````` -If you use more than one CloudStack region, you can define as many sections as you want and name them as you like, for example: - -.. code-block:: bash - - $ cat $HOME/.cloudstack.ini - [exoscale] - endpoint = https://api.exoscale.ch/compute - key = api key - secret = api secret - - [example_cloud_one] - endpoint = https://cloud-one.example.com/client/api - key = api key - secret = api secret - - [example_cloud_two] - endpoint = https://cloud-two.example.com/client/api - key = api key - secret = api secret - -.. Hint:: Sections can also be used to for login into the same region using different accounts. - -By passing the argument ``api_region`` with the CloudStack modules, the region wanted will be selected. - -.. code-block:: yaml - - - name: ensure my ssh public key exists on Exoscale - cs_sshkeypair: - name: my-ssh-key - public_key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}" - api_region: exoscale - delegate_to: localhost - -Or by looping over a regions list if you want to do the task in every region: - -.. code-block:: yaml - - - name: ensure my ssh public key exists in all CloudStack regions - local_action: cs_sshkeypair - name: my-ssh-key - public_key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}" - api_region: "{{ item }}" - loop: - - exoscale - - example_cloud_one - - example_cloud_two - -Environment Variables -````````````````````` -.. versionadded:: 2.3 - -Since Ansible 2.3 it is possible to use environment variables for domain (``CLOUDSTACK_DOMAIN``), account (``CLOUDSTACK_ACCOUNT``), project (``CLOUDSTACK_PROJECT``), VPC (``CLOUDSTACK_VPC``) and zone (``CLOUDSTACK_ZONE``). This simplifies the tasks by not repeating the arguments for every tasks. - -Below you see an example how it can be used in combination with Ansible's block feature: - -.. code-block:: yaml - - - hosts: cloud-vm - tasks: - - block: - - name: ensure my ssh public key - cs_sshkeypair: - name: my-ssh-key - public_key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}" - - - name: ensure my ssh public key - cs_instance: - display_name: "{{ inventory_hostname_short }}" - template: Linux Debian 7 64-bit 20GB Disk - service_offering: "{{ cs_offering }}" - ssh_key: my-ssh-key - state: running - - delegate_to: localhost - environment: - CLOUDSTACK_DOMAIN: root/customers - CLOUDSTACK_PROJECT: web-app - CLOUDSTACK_ZONE: sf-1 - -.. Note:: You are still able overwrite the environment variables using the module arguments, for example ``zone: sf-2`` - -.. Note:: Unlike ``CLOUDSTACK_REGION`` these additional environment variables are ignored in the CLI ``cs``. - -Use Cases -````````` -The following should give you some ideas how to use the modules to provision VMs to the cloud. As always, there isn't only one way to do it. But as always: keep it simple for the beginning is always a good start. - -Use Case: Provisioning in a Advanced Networking CloudStack setup -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Our CloudStack cloud has an advanced networking setup, we would like to provision web servers, which get a static NAT and open firewall ports 80 and 443. Further we provision database servers, to which we do not give any access to. For accessing the VMs by SSH we use a SSH jump host. - -This is how our inventory looks like: - -.. code-block:: none - - [cloud-vm:children] - webserver - db-server - jumphost - - [webserver] - web-01.example.com public_ip=198.51.100.20 - web-02.example.com public_ip=198.51.100.21 - - [db-server] - db-01.example.com - db-02.example.com - - [jumphost] - jump.example.com public_ip=198.51.100.22 - -As you can see, the public IPs for our web servers and jumphost has been assigned as variable ``public_ip`` directly in the inventory. - -The configure the jumphost, web servers and database servers, we use ``group_vars``. The ``group_vars`` directory contains 4 files for configuration of the groups: cloud-vm, jumphost, webserver and db-server. The cloud-vm is there for specifying the defaults of our cloud infrastructure. - -.. code-block:: yaml - - # file: group_vars/cloud-vm - --- - cs_offering: Small - cs_firewall: [] - -Our database servers should get more CPU and RAM, so we define to use a ``Large`` offering for them. - -.. code-block:: yaml - - # file: group_vars/db-server - --- - cs_offering: Large - -The web servers should get a ``Small`` offering as we would scale them horizontally, which is also our default offering. We also ensure the known web ports are opened for the world. - -.. code-block:: yaml - - # file: group_vars/webserver - --- - cs_firewall: - - { port: 80 } - - { port: 443 } - -Further we provision a jump host which has only port 22 opened for accessing the VMs from our office IPv4 network. - -.. code-block:: yaml - - # file: group_vars/jumphost - --- - cs_firewall: - - { port: 22, cidr: "17.17.17.0/24" } - -Now to the fun part. We create a playbook to create our infrastructure we call it ``infra.yml``: - -.. code-block:: yaml - - # file: infra.yaml - --- - - name: provision our VMs - hosts: cloud-vm - tasks: - - name: run all enclosed tasks from localhost - delegate_to: localhost - block: - - name: ensure VMs are created and running - cs_instance: - name: "{{ inventory_hostname_short }}" - template: Linux Debian 7 64-bit 20GB Disk - service_offering: "{{ cs_offering }}" - state: running - - - name: ensure firewall ports opened - cs_firewall: - ip_address: "{{ public_ip }}" - port: "{{ item.port }}" - cidr: "{{ item.cidr | default('0.0.0.0/0') }}" - loop: "{{ cs_firewall }}" - when: public_ip is defined - - - name: ensure static NATs - cs_staticnat: vm="{{ inventory_hostname_short }}" ip_address="{{ public_ip }}" - when: public_ip is defined - -In the above play we defined 3 tasks and use the group ``cloud-vm`` as target to handle all VMs in the cloud but instead SSH to these VMs, we use ``delegate_to: localhost`` to execute the API calls locally from our workstation. - -In the first task, we ensure we have a running VM created with the Debian template. If the VM is already created but stopped, it would just start it. If you like to change the offering on an existing VM, you must add ``force: yes`` to the task, which would stop the VM, change the offering and start the VM again. - -In the second task we ensure the ports are opened if we give a public IP to the VM. - -In the third task we add static NAT to the VMs having a public IP defined. - - -.. Note:: The public IP addresses must have been acquired in advance, also see ``cs_ip_address`` - -.. Note:: For some modules, for example ``cs_sshkeypair`` you usually want this to be executed only once, not for every VM. Therefore you would make a separate play for it targeting localhost. You find an example in the use cases below. - -Use Case: Provisioning on a Basic Networking CloudStack setup -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -A basic networking CloudStack setup is slightly different: Every VM gets a public IP directly assigned and security groups are used for access restriction policy. - -This is how our inventory looks like: - -.. code-block:: none - - [cloud-vm:children] - webserver - - [webserver] - web-01.example.com - web-02.example.com - -The default for your VMs looks like this: - -.. code-block:: yaml - - # file: group_vars/cloud-vm - --- - cs_offering: Small - cs_securitygroups: [ 'default'] - -Our webserver will also be in security group ``web``: - -.. code-block:: yaml - - # file: group_vars/webserver - --- - cs_securitygroups: [ 'default', 'web' ] - -The playbook looks like the following: - -.. code-block:: yaml - - # file: infra.yaml - --- - - name: cloud base setup - hosts: localhost - tasks: - - name: upload ssh public key - cs_sshkeypair: - name: defaultkey - public_key: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}" - - - name: ensure security groups exist - cs_securitygroup: - name: "{{ item }}" - loop: - - default - - web - - - name: add inbound SSH to security group default - cs_securitygroup_rule: - security_group: default - start_port: "{{ item }}" - end_port: "{{ item }}" - loop: - - 22 - - - name: add inbound TCP rules to security group web - cs_securitygroup_rule: - security_group: web - start_port: "{{ item }}" - end_port: "{{ item }}" - loop: - - 80 - - 443 - - - name: install VMs in the cloud - hosts: cloud-vm - tasks: - - delegate_to: localhost - block: - - name: create and run VMs on CloudStack - cs_instance: - name: "{{ inventory_hostname_short }}" - template: Linux Debian 7 64-bit 20GB Disk - service_offering: "{{ cs_offering }}" - security_groups: "{{ cs_securitygroups }}" - ssh_key: defaultkey - state: Running - register: vm - - - name: show VM IP - debug: msg="VM {{ inventory_hostname }} {{ vm.default_ip }}" - - - name: assign IP to the inventory - set_fact: ansible_ssh_host={{ vm.default_ip }} - - - name: waiting for SSH to come up - wait_for: port=22 host={{ vm.default_ip }} delay=5 - -In the first play we setup the security groups, in the second play the VMs will created be assigned to these groups. Further you see, that we assign the public IP returned from the modules to the host inventory. This is needed as we do not know the IPs we will get in advance. In a next step you would configure the DNS servers with these IPs for accessing the VMs with their DNS name. - -In the last task we wait for SSH to be accessible, so any later play would be able to access the VM by SSH without failure. diff --git a/docs/docsite/rst/scenario_guides/guide_gce.rst b/docs/docsite/rst/scenario_guides/guide_gce.rst deleted file mode 100644 index 7e98d026d51..00000000000 --- a/docs/docsite/rst/scenario_guides/guide_gce.rst +++ /dev/null @@ -1,309 +0,0 @@ -Google Cloud Platform Guide -=========================== - -.. gce_intro: - -Introduction --------------------------- - -Ansible + Google have been working together on a set of auto-generated -Ansible modules designed to consistently and comprehensively cover the entirety -of the Google Cloud Platform (GCP). - -Ansible contains modules for managing Google Cloud Platform resources, -including creating instances, controlling network access, working with -persistent disks, managing load balancers, and a lot more. - -These new modules can be found under a new consistent name scheme "gcp_*" -(Note: gcp_target_proxy and gcp_url_map are legacy modules, despite the "gcp_*" -name. Please use gcp_compute_target_proxy and gcp_compute_url_map instead). - -Additionally, the gcp_compute inventory plugin can discover all -Google Compute Engine (GCE) instances -and make them automatically available in your Ansible inventory. - -You may see a collection of other GCP modules that do not conform to this -naming convention. These are the original modules primarily developed by the -Ansible community. You will find some overlapping functionality such as with -the "gce" module and the new "gcp_compute_instance" module. Either can be -used, but you may experience issues trying to use them together. - -While the community GCP modules are not going away, Google is investing effort -into the new "gcp_*" modules. Google is committed to ensuring the Ansible -community has a great experience with GCP and therefore recommends adopting -these new modules if possible. - - -Requisites ---------------- -The GCP modules require both the ``requests`` and the -``google-auth`` libraries to be installed. - -.. code-block:: bash - - $ pip install requests google-auth - -Alternatively for RHEL / CentOS, the ``python-requests`` package is also -available to satisfy ``requests`` libraries. - -.. code-block:: bash - - $ yum install python-requests - -Similarly, for Ubuntu (>= 22.04) (and Debian), install the ``python3-google-auth`` and the ``python3-requests`` packages: - -.. code-block:: bash - - $ sudo apt install python3-google-auth python3-requests - - -Credentials ------------ -It is easy to create a GCP account with credentials for Ansible. You have multiple options to -get your credentials - here are two of the most common options: - -* Service Accounts (Recommended): Use JSON service accounts with specific permissions. -* Machine Accounts: Use the permissions associated with the GCP Instance you're using Ansible on. - -For the following examples, we'll be using service account credentials. - -To work with the GCP modules, you'll first need to get some credentials in the -JSON format: - -1. `Create a Service Account `_ -2. `Download JSON credentials `_ - -Once you have your credentials, there are two different ways to provide them to Ansible: - -* by specifying them directly as module parameters -* by setting environment variables - -Providing Credentials as Module Parameters -`````````````````````````````````````````` - -For the GCE modules you can specify the credentials as arguments: - -* ``auth_kind``: type of authentication being used (choices: machineaccount, serviceaccount, application) -* ``service_account_email``: email associated with the project -* ``service_account_file``: path to the JSON credentials file -* ``project``: id of the project -* ``scopes``: The specific scopes that you want the actions to use. - -For example, to create a new IP address using the ``gcp_compute_address`` module, -you can use the following configuration: - -.. code-block:: yaml - - - name: Create IP address - hosts: localhost - gather_facts: false - - vars: - service_account_file: /home/my_account.json - project: my-project - auth_kind: serviceaccount - scopes: - - https://www.googleapis.com/auth/compute - - tasks: - - - name: Allocate an IP Address - gcp_compute_address: - state: present - name: 'test-address1' - region: 'us-west1' - project: "{{ project }}" - auth_kind: "{{ auth_kind }}" - service_account_file: "{{ service_account_file }}" - scopes: "{{ scopes }}" - -Providing Credentials as Environment Variables -`````````````````````````````````````````````` - -Set the following environment variables before running Ansible in order to configure your credentials: - -.. code-block:: bash - - GCP_AUTH_KIND - GCP_SERVICE_ACCOUNT_EMAIL - GCP_SERVICE_ACCOUNT_FILE - GCP_SCOPES - -GCE Dynamic Inventory ---------------------- - -The best way to interact with your hosts is to use the gcp_compute inventory plugin, which dynamically queries GCE and tells Ansible what nodes can be managed. - -To be able to use this GCE dynamic inventory plugin, you need to enable it first by specifying the following in the ``ansible.cfg`` file: - -.. code-block:: ini - - [inventory] - enable_plugins = gcp_compute - -Then, create a file that ends in ``.gcp.yml`` in your root directory. - -The gcp_compute inventory script takes in the same authentication information as any module. - -Here's an example of a valid inventory file: - -.. code-block:: yaml - - plugin: gcp_compute - projects: - - graphite-playground - auth_kind: serviceaccount - service_account_file: /home/alexstephen/my_account.json - - -Executing ``ansible-inventory --list -i .gcp.yml`` will create a list of GCP instances that are ready to be configured using Ansible. - -Create an instance -`````````````````` - -The full range of GCP modules provide the ability to create a wide variety of -GCP resources with the full support of the entire GCP API. - -The following playbook creates a GCE Instance. This instance relies on other GCP -resources like Disk. By creating other resources separately, we can give as -much detail as necessary about how we want to configure the other resources, for example -formatting of the Disk. By registering it to a variable, we can simply insert the -variable into the instance task. The gcp_compute_instance module will figure out the -rest. - -.. code-block:: yaml - - - name: Create an instance - hosts: localhost - gather_facts: false - vars: - gcp_project: my-project - gcp_cred_kind: serviceaccount - gcp_cred_file: /home/my_account.json - zone: "us-central1-a" - region: "us-central1" - - tasks: - - name: create a disk - gcp_compute_disk: - name: 'disk-instance' - size_gb: 50 - source_image: 'projects/ubuntu-os-cloud/global/images/family/ubuntu-1604-lts' - zone: "{{ zone }}" - project: "{{ gcp_project }}" - auth_kind: "{{ gcp_cred_kind }}" - service_account_file: "{{ gcp_cred_file }}" - scopes: - - https://www.googleapis.com/auth/compute - state: present - register: disk - - name: create a address - gcp_compute_address: - name: 'address-instance' - region: "{{ region }}" - project: "{{ gcp_project }}" - auth_kind: "{{ gcp_cred_kind }}" - service_account_file: "{{ gcp_cred_file }}" - scopes: - - https://www.googleapis.com/auth/compute - state: present - register: address - - name: create a instance - gcp_compute_instance: - state: present - name: test-vm - machine_type: n1-standard-1 - disks: - - auto_delete: true - boot: true - source: "{{ disk }}" - network_interfaces: - - network: null # use default - access_configs: - - name: 'External NAT' - nat_ip: "{{ address }}" - type: 'ONE_TO_ONE_NAT' - zone: "{{ zone }}" - project: "{{ gcp_project }}" - auth_kind: "{{ gcp_cred_kind }}" - service_account_file: "{{ gcp_cred_file }}" - scopes: - - https://www.googleapis.com/auth/compute - register: instance - - - name: Wait for SSH to come up - wait_for: host={{ address.address }} port=22 delay=10 timeout=60 - - - name: Add host to groupname - add_host: hostname={{ address.address }} groupname=new_instances - - - - name: Manage new instances - hosts: new_instances - connection: ssh - become: True - roles: - - base_configuration - - production_server - -Note that use of the "add_host" module above creates a temporary, in-memory group. This means that a play in the same playbook can then manage machines -in the 'new_instances' group, if so desired. Any sort of arbitrary configuration is possible at this point. - -For more information about Google Cloud, please visit the `Google Cloud website `_. - -Migration Guides ----------------- - -gce.py -> gcp_compute_instance.py -````````````````````````````````` -As of Ansible 2.8, we're encouraging everyone to move from the ``gce`` module to the -``gcp_compute_instance`` module. The ``gcp_compute_instance`` module has better -support for all of GCP's features, fewer dependencies, more flexibility, and -better supports GCP's authentication systems. - -The ``gcp_compute_instance`` module supports all of the features of the ``gce`` -module (and more!). Below is a mapping of ``gce`` fields over to -``gcp_compute_instance`` fields. - -============================ ========================================== ====================== - gce.py gcp_compute_instance.py Notes -============================ ========================================== ====================== - state state/status State on gce has multiple values: "present", "absent", "stopped", "started", "terminated". State on gcp_compute_instance is used to describe if the instance exists (present) or does not (absent). Status is used to describe if the instance is "started", "stopped" or "terminated". - image disks[].initialize_params.source_image You'll need to create a single disk using the disks[] parameter and set it to be the boot disk (disks[].boot = true) - image_family disks[].initialize_params.source_image See above. - external_projects disks[].initialize_params.source_image The name of the source_image will include the name of the project. - instance_names Use a loop or multiple tasks. Using loops is a more Ansible-centric way of creating multiple instances and gives you the most flexibility. - service_account_email service_accounts[].email This is the service_account email address that you want the instance to be associated with. It is not the service_account email address that is used for the credentials necessary to create the instance. - service_account_permissions service_accounts[].scopes These are the permissions you want to grant to the instance. - pem_file Not supported. We recommend using JSON service account credentials instead of PEM files. - credentials_file service_account_file - project_id project - name name This field does not accept an array of names. Use a loop to create multiple instances. - num_instances Use a loop For maximum flexibility, we're encouraging users to use Ansible features to create multiple instances, rather than letting the module do it for you. - network network_interfaces[].network - subnetwork network_interfaces[].subnetwork - persistent_boot_disk disks[].type = 'PERSISTENT' - disks disks[] - ip_forward can_ip_forward - external_ip network_interfaces[].access_configs.nat_ip This field takes multiple types of values. You can create an IP address with ``gcp_compute_address`` and place the name/output of the address here. You can also place the string value of the IP address's GCP name or the actual IP address. - disks_auto_delete disks[].auto_delete - preemptible scheduling.preemptible - disk_size disks[].initialize_params.disk_size_gb -============================ ========================================== ====================== - -An example playbook is below: - -.. code:: yaml - - gcp_compute_instance: - name: "{{ item }}" - machine_type: n1-standard-1 - ... # any other settings - zone: us-central1-a - project: "my-project" - auth_kind: "service_account_file" - service_account_file: "~/my_account.json" - state: present - loop: - - instance-1 - - instance-2 diff --git a/docs/docsite/rst/scenario_guides/guides.rst b/docs/docsite/rst/scenario_guides/guides.rst index a66dc3a691e..4ef06912503 100644 --- a/docs/docsite/rst/scenario_guides/guides.rst +++ b/docs/docsite/rst/scenario_guides/guides.rst @@ -14,14 +14,6 @@ We are migrating these guides into collections. Please update your links for the :ref:`ansible_collections.amazon.aws.docsite.aws_intro` -.. toctree:: - :maxdepth: 1 - :caption: Legacy Public Cloud Guides - - guide_cloudstack - guide_gce - guide_azure - .. toctree:: :maxdepth: 1 :caption: Network Technology Guides From 0b2e359247bcb461dbd54389f9ec5ecf92258233 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Tue, 12 Dec 2023 22:24:22 +0100 Subject: [PATCH 139/536] Remove Virtualization and Containerization Guides (#975) * Remove broken VMware REST Scenarios * Remove Virtualization and Containerization Guides --- docs/docsite/rst/ansible_index.rst | 1 - .../rst/scenario_guides/guide_vagrant.rst | 136 ---------------- .../rst/scenario_guides/guide_vmware_rest.rst | 7 - docs/docsite/rst/scenario_guides/guides.rst | 6 - .../rst/scenario_guides/virt_guides.rst | 14 -- .../vmware_rest_scenarios/authentication.rst | 47 ------ .../collect_information.rst | 108 ------------- .../vmware_rest_scenarios/create_vm.rst | 39 ----- .../vmware_rest_scenarios/installation.rst | 44 ----- .../vmware_rest_scenarios/run_a_vm.rst | 52 ------ .../Add_a_floppy_disk_drive.result.json | 15 -- .../Add_a_floppy_disk_drive.task.yaml | 5 - .../Attach_a_VM_to_a_dvswitch.result.json | 23 --- .../Attach_a_VM_to_a_dvswitch.task.yaml | 9 -- ...ach_an_ISO_image_to_a_guest_VM.result.json | 19 --- ...ttach_an_ISO_image_to_a_guest_VM.task.yaml | 12 -- ...ild_a_list_of_all_the_clusters.result.json | 11 -- ...Build_a_list_of_all_the_clusters.task.yaml | 3 - ...uild_a_list_of_all_the_folders.result.json | 10 -- .../Build_a_list_of_all_the_folders.task.yaml | 3 - ..._VIRTUAL_MACHINE_and_called_vm.result.json | 10 -- ...pe_VIRTUAL_MACHINE_and_called_vm.task.yaml | 6 - ...tools_upgrade_policy_to_MANUAL.result.json | 4 - ...m-tools_upgrade_policy_to_MANUAL.task.yaml | 5 - ...licy_to_UPGRADE_AT_POWER_CYCLE.result.json | 4 - ...policy_to_UPGRADE_AT_POWER_CYCLE.task.yaml | 5 - ...nformation_about_a_specific_VM.result.json | 77 --------- ..._information_about_a_specific_VM.task.yaml | 4 - ...llect_the_hardware_information.result.json | 8 - ...Collect_the_hardware_information.task.yaml | 4 - ..._a_SATA_adapter_at_PCI_slot_34.result.json | 10 -- ...te_a_SATA_adapter_at_PCI_slot_34.task.yaml | 5 - .../task_outputs/Create_a_VM.result.json | 77 --------- .../task_outputs/Create_a_VM.task.yaml | 14 -- .../Create_a_new_disk.result.json | 17 -- .../task_outputs/Create_a_new_disk.task.yaml | 7 - .../Dedicate_one_core_to_the_VM.result.json | 10 -- .../Dedicate_one_core_to_the_VM.task.yaml | 5 - .../Get_VM_storage_policy.result.json | 6 - .../Get_VM_storage_policy.task.yaml | 4 - ...t_guest_filesystem_information.result.json | 13 -- ...Get_guest_filesystem_information.task.yaml | 8 - ...Get_guest_identity_information.result.json | 14 -- .../Get_guest_identity_information.task.yaml | 4 - ...network_interfaces_information.result.json | 23 --- ...t_network_interfaces_information.task.yaml | 4 - ...est_network_routes_information.result.json | 31 ---- ...guest_network_routes_information.task.yaml | 4 - ...t_guest_networking_information.result.json | 17 -- ...Get_guest_networking_information.task.yaml | 4 - .../Get_guest_power_information.result.json | 6 - .../Get_guest_power_information.task.yaml | 4 - .../Increase_the_memory_of_a_VM.result.json | 4 - .../Increase_the_memory_of_a_VM.task.yaml | 5 - ...the_SCSI_adapter_of_a_given_VM.result.json | 14 -- ...t_the_SCSI_adapter_of_a_given_VM.task.yaml | 4 - ...the_cdrom_devices_on_the_guest.result.json | 4 - ...t_the_cdrom_devices_on_the_guest.task.yaml | 4 - ...lled_test_vm1_in_the_inventory.result.json | 12 -- ...called_test_vm1_in_the_inventory.task.yaml | 5 - ...ve_SATA_adapter_at_PCI_slot_34.result.json | 3 - ...e_a_list_of_all_the_datastores.result.json | 26 --- ...eve_a_list_of_all_the_datastores.task.yaml | 3 - ...etails_about_the_first_cluster.result.json | 8 - ..._details_about_the_first_cluster.task.yaml | 4 - ...e_disk_information_from_the_VM.result.json | 18 --- ...the_disk_information_from_the_VM.task.yaml | 4 - ...memory_information_from_the_VM.result.json | 7 - ...e_memory_information_from_the_VM.task.yaml | 4 - ..._NIC's_start_connected_flag_on.result.json | 4 - ...he_NIC's_start_connected_flag_on.task.yaml | 5 - .../Turn_the_power_of_the_VM_on.result.json | 3 - .../Turn_the_power_of_the_VM_on.task.yaml | 4 - ...pgrade_the_VM_hardware_version.result.json | 4 - .../Upgrade_the_VM_hardware_version.task.yaml | 6 - .../Wait_until_my_VM_is_ready.result.json | 13 -- .../Wait_until_my_VM_is_ready.task.yaml | 9 -- ...lect_a_list_of_the_datacenters.result.json | 9 -- ...ollect_a_list_of_the_datacenters.task.yaml | 3 - .../vm_hardware_tuning.rst | 150 ------------------ .../vmware_rest_scenarios/vm_info.rst | 129 --------------- .../vm_tool_configuration.rst | 45 ------ .../vm_tool_information.rst | 90 ----------- 83 files changed, 1581 deletions(-) delete mode 100644 docs/docsite/rst/scenario_guides/guide_vagrant.rst delete mode 100644 docs/docsite/rst/scenario_guides/guide_vmware_rest.rst delete mode 100644 docs/docsite/rst/scenario_guides/virt_guides.rst delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/authentication.rst delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/collect_information.rst delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/create_vm.rst delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/installation.rst delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/run_a_vm.rst delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Add_a_floppy_disk_drive.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Add_a_floppy_disk_drive.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_a_VM_to_a_dvswitch.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_a_VM_to_a_dvswitch.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_an_ISO_image_to_a_guest_VM.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_an_ISO_image_to_a_guest_VM.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_clusters.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_clusters.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders_with_the_type_VIRTUAL_MACHINE_and_called_vm.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders_with_the_type_VIRTUAL_MACHINE_and_called_vm.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_MANUAL.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_MANUAL.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_UPGRADE_AT_POWER_CYCLE.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_UPGRADE_AT_POWER_CYCLE.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_information_about_a_specific_VM.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_information_about_a_specific_VM.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_the_hardware_information.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_the_hardware_information.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_SATA_adapter_at_PCI_slot_34.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_SATA_adapter_at_PCI_slot_34.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_VM.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_VM.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_new_disk.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_new_disk.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Dedicate_one_core_to_the_VM.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Dedicate_one_core_to_the_VM.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_VM_storage_policy.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_VM_storage_policy.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_filesystem_information.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_filesystem_information.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_identity_information.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_identity_information.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_interfaces_information.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_interfaces_information.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_routes_information.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_routes_information.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_networking_information.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_networking_information.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_power_information.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_power_information.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Increase_the_memory_of_a_VM.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Increase_the_memory_of_a_VM.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_SCSI_adapter_of_a_given_VM.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_SCSI_adapter_of_a_given_VM.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_cdrom_devices_on_the_guest.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_cdrom_devices_on_the_guest.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Look_up_the_VM_called_test_vm1_in_the_inventory.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Look_up_the_VM_called_test_vm1_in_the_inventory.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Remove_SATA_adapter_at_PCI_slot_34.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_a_list_of_all_the_datastores.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_a_list_of_all_the_datastores.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_details_about_the_first_cluster.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_details_about_the_first_cluster.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_disk_information_from_the_VM.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_disk_information_from_the_VM.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_memory_information_from_the_VM.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_memory_information_from_the_VM.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_NIC's_start_connected_flag_on.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_NIC's_start_connected_flag_on.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_power_of_the_VM_on.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_power_of_the_VM_on.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Upgrade_the_VM_hardware_version.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Upgrade_the_VM_hardware_version.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Wait_until_my_VM_is_ready.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Wait_until_my_VM_is_ready.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/collect_a_list_of_the_datacenters.result.json delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/collect_a_list_of_the_datacenters.task.yaml delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_hardware_tuning.rst delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_info.rst delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_tool_configuration.rst delete mode 100644 docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_tool_information.rst diff --git a/docs/docsite/rst/ansible_index.rst b/docs/docsite/rst/ansible_index.rst index d724cfdf8c3..aee632ed003 100644 --- a/docs/docsite/rst/ansible_index.rst +++ b/docs/docsite/rst/ansible_index.rst @@ -64,7 +64,6 @@ Contributors develop and change modules and plugins, hosted in collections, much scenario_guides/cloud_guides scenario_guides/network_guides - scenario_guides/virt_guides .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/scenario_guides/guide_vagrant.rst b/docs/docsite/rst/scenario_guides/guide_vagrant.rst deleted file mode 100644 index f49477b0400..00000000000 --- a/docs/docsite/rst/scenario_guides/guide_vagrant.rst +++ /dev/null @@ -1,136 +0,0 @@ -Vagrant Guide -============= - -.. _vagrant_intro: - -Introduction -```````````` - -`Vagrant `_ is a tool to manage virtual machine -environments, and allows you to configure and use reproducible work -environments on top of various virtualization and cloud platforms. -It also has integration with Ansible as a provisioner for these virtual -machines, and the two tools work together well. - -This guide will describe how to use Vagrant 1.7+ and Ansible together. - -If you're not familiar with Vagrant, you should visit `the documentation -`_. - -This guide assumes that you already have Ansible installed and working. -Running from a Git checkout is fine. Follow the :ref:`installation_guide` -guide for more information. - -.. _vagrant_setup: - -Vagrant Setup -````````````` - -The first step once you've installed Vagrant is to create a ``Vagrantfile`` -and customize it to suit your needs. This is covered in detail in the Vagrant -documentation, but here is a quick example that includes a section to use the -Ansible provisioner to manage a single machine: - -.. code-block:: ruby - - # This guide is optimized for Vagrant 1.8 and above. - # Older versions of Vagrant put less info in the inventory they generate. - Vagrant.require_version ">= 1.8.0" - - Vagrant.configure(2) do |config| - - config.vm.box = "ubuntu/bionic64" - - config.vm.provision "ansible" do |ansible| - ansible.verbose = "v" - ansible.playbook = "playbook.yml" - end - end - -Notice the ``config.vm.provision`` section that refers to an Ansible playbook -called ``playbook.yml`` in the same directory as the ``Vagrantfile``. Vagrant -runs the provisioner once the virtual machine has booted and is ready for SSH -access. - -There are a lot of Ansible options you can configure in your ``Vagrantfile``. -Visit the `Ansible Provisioner documentation -`_ for more -information. - -.. code-block:: bash - - $ vagrant up - -This will start the VM, and run the provisioning playbook (on the first VM -startup). - - -To re-run a playbook on an existing VM, just run: - -.. code-block:: bash - - $ vagrant provision - -This will re-run the playbook against the existing VM. - -Note that having the ``ansible.verbose`` option enabled will instruct Vagrant -to show the full ``ansible-playbook`` command used behind the scene, as -illustrated by this example: - -.. code-block:: bash - - $ PYTHONUNBUFFERED=1 ANSIBLE_FORCE_COLOR=true ANSIBLE_HOST_KEY_CHECKING=false ANSIBLE_SSH_ARGS='-o UserKnownHostsFile=/dev/null -o IdentitiesOnly=yes -o ControlMaster=auto -o ControlPersist=60s' ansible-playbook --connection=ssh --timeout=30 --limit="default" --inventory-file=/home/someone/coding-in-a-project/.vagrant/provisioners/ansible/inventory -v playbook.yml - -This information can be quite useful to debug integration issues and can also -be used to manually execute Ansible from a shell, as explained in the next -section. - -.. _running_ansible: - -Running Ansible Manually -```````````````````````` - -Sometimes you may want to run Ansible manually against the machines. This is -faster than kicking ``vagrant provision`` and pretty easy to do. - -With our ``Vagrantfile`` example, Vagrant automatically creates an Ansible -inventory file in ``.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory``. -This inventory is configured according to the SSH tunnel that Vagrant -automatically creates. A typical automatically-created inventory file for a -single machine environment may look something like this: - -.. code-block:: none - - # Generated by Vagrant - - default ansible_host=127.0.0.1 ansible_port=2222 ansible_user='vagrant' ansible_ssh_private_key_file='/home/someone/coding-in-a-project/.vagrant/machines/default/virtualbox/private_key' - -If you want to run Ansible manually, you will want to make sure to pass -``ansible`` or ``ansible-playbook`` commands the correct arguments, at least -for the *inventory*. - -.. code-block:: bash - - $ ansible-playbook -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory playbook.yml - -Advanced Usages -``````````````` - -The "Tips and Tricks" chapter of the `Ansible Provisioner documentation -`_ provides detailed information about more advanced Ansible features like: - - - how to execute a playbook in parallel within a multi-machine environment - - how to integrate a local ``ansible.cfg`` configuration file - -.. seealso:: - - `Vagrant Home `_ - The Vagrant homepage with downloads - `Vagrant Documentation `_ - Vagrant Documentation - `Ansible Provisioner `_ - The Vagrant documentation for the Ansible provisioner - `Vagrant Issue Tracker `_ - The open issues for the Ansible provisioner in the Vagrant project - :ref:`working_with_playbooks` - An introduction to playbooks diff --git a/docs/docsite/rst/scenario_guides/guide_vmware_rest.rst b/docs/docsite/rst/scenario_guides/guide_vmware_rest.rst deleted file mode 100644 index bf6838baa4e..00000000000 --- a/docs/docsite/rst/scenario_guides/guide_vmware_rest.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _vmware_rest_scenarios: - -**************************** -VMware REST Scenarios -**************************** - -The content on this page has moved to :ref:`ansible_collections.vmware.vmware_rest.docsite.guide_vmware_rest`. diff --git a/docs/docsite/rst/scenario_guides/guides.rst b/docs/docsite/rst/scenario_guides/guides.rst index 4ef06912503..0919d1c44a0 100644 --- a/docs/docsite/rst/scenario_guides/guides.rst +++ b/docs/docsite/rst/scenario_guides/guides.rst @@ -21,9 +21,3 @@ We are migrating these guides into collections. Please update your links for the guide_aci guide_meraki guide_infoblox - -.. toctree:: - :maxdepth: 1 - :caption: Virtualization & Containerization Guides - - guide_vagrant diff --git a/docs/docsite/rst/scenario_guides/virt_guides.rst b/docs/docsite/rst/scenario_guides/virt_guides.rst deleted file mode 100644 index bc9007861c7..00000000000 --- a/docs/docsite/rst/scenario_guides/virt_guides.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _virtualization_guides: - -****************************************** -Virtualization and Containerization Guides -****************************************** - -The guides in this section cover integrating Ansible with popular tools for creating virtual machines and containers. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features. - -.. toctree:: - :maxdepth: 1 - - guide_docker - guide_vagrant - guide_vmware_rest diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/authentication.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/authentication.rst deleted file mode 100644 index 5c778e429c4..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/authentication.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _vmware_rest_authentication: - -******************************************* -How to configure the vmware_rest collection -******************************************* - -.. contents:: - :local: - - -Introduction -============ - -The vcenter_rest modules need to be authenticated. There are two different - -Environment variables -===================== - -.. note:: - This solution requires that you call the modules from the local machine. - -You need to export some environment variables in your shell before you call the modules. - -.. code-block:: shell - - $ export VMWARE_HOST=vcenter.test - $ export VMWARE_USER=myvcenter-user - $ export VMWARE_password=mypassword - $ ansible-playbook my-playbook.yaml - -Module parameters -================= - -All the vcenter_rest modules accept the following arguments: - -- ``vcenter_hostname`` -- ``vcenter_username`` -- ``vcenter_password`` - - -Ignore SSL certificate error -============================ - -It is common to run a test environment without a proper SSL certificate configuration. - -To ignore the SSL error, you can use the ``vcenter_validate_certs: no`` argument or -``export VMWARE_VALIDATE_CERTS=no`` to set the environment variable. diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/collect_information.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/collect_information.rst deleted file mode 100644 index d6c2b86afd1..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/collect_information.rst +++ /dev/null @@ -1,108 +0,0 @@ -.. _vmware_rest_collect_info: - -************************************************* -How to collect information about your environment -************************************************* - -.. contents:: - :local: - - -Introduction -============ - -This section shows you how to utilize Ansible to collect information about your environment. -This information is useful for the other tutorials. - -Scenario requirements -===================== - -In this scenario we've got a vCenter with an ESXi host. - -Our environment is pre-initialized with the following elements: - -- A datacenter called ``my_dc`` -- A cluster called ``my_cluster`` -- An ESXi host called ``esxi1`` is in the cluster -- Two datastores on the ESXi: ``rw_datastore`` and ``ro_datastore`` -- A dvswitch based guest network - -Finally, we use the environment variables to authenticate ourselves as explained in :ref:`vmware_rest_authentication`. - -How to collect information -========================== - -In these examples, we use the ``vcenter_*_info`` module to collect information about the associated resources. - -All these modules return a ``value`` key. Depending on the context, this ``value`` key will be either a list or a dictionary. - -Datacenter ----------- - -Here we use the ``vcenter_datacenter_info`` module to list all the datacenters: - -.. literalinclude:: task_outputs/collect_a_list_of_the_datacenters.task.yaml - -Result -______ - -As expected, the ``value`` key of the output is a list. - -.. literalinclude:: task_outputs/collect_a_list_of_the_datacenters.result.json - -Cluster -------- - -Here we do the same with ``vcenter_cluster_info``: - -.. literalinclude:: task_outputs/Build_a_list_of_all_the_clusters.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Build_a_list_of_all_the_clusters.result.json - -And we can also fetch the details about a specific cluster, with the ``cluster`` parameter: - -.. literalinclude:: task_outputs/Retrieve_details_about_the_first_cluster.task.yaml - -Result -______ - -And the ``value`` key of the output is this time a dictionary. - - -.. literalinclude:: task_outputs/Retrieve_details_about_the_first_cluster.result.json - -Datastore ---------- - -Here we use ``vcenter_datastore_info`` to get a list of all the datastores: - -.. literalinclude:: task_outputs/Retrieve_a_list_of_all_the_datastores.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Retrieve_a_list_of_all_the_datastores.result.json - -Folder ------- - -And here again, you use the ``vcenter_folder_info`` module to retrieve a list of all the folders. - -.. literalinclude:: task_outputs/Build_a_list_of_all_the_folders.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Build_a_list_of_all_the_folders.result.json - -Most of the time, you will just want one type of folder. In this case we can use filters to reduce the amount to collect. Most of the ``_info`` modules come with similar filters. - -.. literalinclude:: task_outputs/Build_a_list_of_all_the_folders_with_the_type_VIRTUAL_MACHINE_and_called_vm.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Build_a_list_of_all_the_folders_with_the_type_VIRTUAL_MACHINE_and_called_vm.result.json diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/create_vm.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/create_vm.rst deleted file mode 100644 index 6d19f61f559..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/create_vm.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _vmware_rest_create_vm: - -******************************* -How to create a Virtual Machine -******************************* - -.. contents:: - :local: - - -Introduction -============ - -This section shows you how to use Ansible to create a virtual machine. - -Scenario requirements -===================== - -You've already followed :ref:`vmware_rest_collect_info` and you've got the following variables defined: - -- ``my_cluster_info`` -- ``my_datastore`` -- ``my_virtual_machine_folder`` -- ``my_cluster_info`` - -How to create a virtual machine -=============================== - -In this example, we will use the ``vcenter_vm`` module to create a new guest. - -.. literalinclude:: task_outputs/Create_a_VM.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Create_a_VM.result.json - -.. note:: - ``vcenter_vm`` accepts more parameters, however you may prefer to start with a simple VM and use the ``vcenter_vm_hardware`` modules to tune it up afterwards. It is easier this way to identify a potential problematical step. diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/installation.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/installation.rst deleted file mode 100644 index 7516d0fd455..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/installation.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _vmware_rest_installation: - -***************************************** -How to install the vmware_rest collection -***************************************** - -.. contents:: - :local: - - -Requirements -============ - -The collection depends on: - -- Ansible >=2.9.10 or greater -- Python 3.6 or greater - -aiohttp -======= - -aiohttp_ is the only dependency of the collection. You can install it with ``pip`` if you use a virtualenv to run Ansible. - -.. code-block:: shell - - $ pip install aiohttp - -Or using an RPM. - -.. code-block:: shell - - $ sudo dnf install python3-aiohttp - -.. _aiohttp: https://docs.aiohttp.org/en/stable/ - -Installation -============ - -The best option to install the collection is to use the ``ansible-galaxy`` command: - -.. code-block:: shell - - - $ ansible-galaxy collection install vmware.vmware_rest diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/run_a_vm.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/run_a_vm.rst deleted file mode 100644 index be723866e78..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/run_a_vm.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. _vmware_rest_run_a_vm: - -**************************** -How to run a virtual machine -**************************** - -.. contents:: - :local: - - -Introduction -============ - -This section covers the power management of your virtual machine. - -Power information -================= - -Use ``vcenter_vm_power_info`` to know the power state of the VM. - -.. literalinclude:: task_outputs/Get_guest_power_information.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Get_guest_power_information.result.json - - -How to start a virtual machine -============================== - -Use the ``vcenter_vm_power`` module to start your VM: - -.. literalinclude:: task_outputs/Turn_the_power_of_the_VM_on.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Turn_the_power_of_the_VM_on.result.json - -How to wait until my virtual machine is ready -============================================= - -If your virtual machine runs VMware Tools, you can build a loop -around the ``center_vm_tools_info`` module: - -.. literalinclude:: task_outputs/Wait_until_my_VM_is_ready.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Wait_until_my_VM_is_ready.result.json diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Add_a_floppy_disk_drive.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Add_a_floppy_disk_drive.result.json deleted file mode 100644 index c4bf5cd0e22..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Add_a_floppy_disk_drive.result.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "value": { - "start_connected": false, - "backing": { - "auto_detect": true, - "type": "HOST_DEVICE", - "host_device": "" - }, - "allow_guest_control": true, - "label": "Floppy drive 1", - "state": "NOT_CONNECTED" - }, - "id": "8000", - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Add_a_floppy_disk_drive.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Add_a_floppy_disk_drive.task.yaml deleted file mode 100644 index 807b61692b1..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Add_a_floppy_disk_drive.task.yaml +++ /dev/null @@ -1,5 +0,0 @@ -- name: Add a floppy disk drive - vmware.vmware_rest.vcenter_vm_hardware_floppy: - vm: '{{ test_vm1_info.id }}' - allow_guest_control: true - register: my_floppy_drive diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_a_VM_to_a_dvswitch.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_a_VM_to_a_dvswitch.result.json deleted file mode 100644 index fbb5a6f15d9..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_a_VM_to_a_dvswitch.result.json +++ /dev/null @@ -1,23 +0,0 @@ -{ - "value": { - "start_connected": false, - "pci_slot_number": 4, - "backing": { - "connection_cookie": 2145337177, - "distributed_switch_uuid": "50 33 88 3a 8c 6e f9 02-7a fd c2 c0 2c cf f2 ac", - "distributed_port": "2", - "type": "DISTRIBUTED_PORTGROUP", - "network": "dvportgroup-1649" - }, - "mac_address": "00:50:56:b3:49:5c", - "mac_type": "ASSIGNED", - "allow_guest_control": false, - "wake_on_lan_enabled": false, - "label": "Network adapter 1", - "state": "NOT_CONNECTED", - "type": "VMXNET3", - "upt_compatibility_enabled": false - }, - "id": "4000", - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_a_VM_to_a_dvswitch.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_a_VM_to_a_dvswitch.task.yaml deleted file mode 100644 index d35cd83cb47..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_a_VM_to_a_dvswitch.task.yaml +++ /dev/null @@ -1,9 +0,0 @@ -- name: Attach a VM to a dvswitch - vmware.vmware_rest.vcenter_vm_hardware_ethernet: - vm: '{{ test_vm1_info.id }}' - pci_slot_number: 4 - backing: - type: DISTRIBUTED_PORTGROUP - network: "{{ my_portgroup_info.dvs_portgroup_info.dvswitch1[0].key }}" - start_connected: false - register: vm_hardware_ethernet_1 diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_an_ISO_image_to_a_guest_VM.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_an_ISO_image_to_a_guest_VM.result.json deleted file mode 100644 index ee456cb1fe6..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_an_ISO_image_to_a_guest_VM.result.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "value": { - "start_connected": true, - "backing": { - "iso_file": "[ro_datastore] fedora.iso", - "type": "ISO_FILE" - }, - "allow_guest_control": false, - "label": "CD/DVD drive 1", - "state": "NOT_CONNECTED", - "type": "SATA", - "sata": { - "bus": 0, - "unit": 2 - } - }, - "id": "16002", - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_an_ISO_image_to_a_guest_VM.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_an_ISO_image_to_a_guest_VM.task.yaml deleted file mode 100644 index b328788fa5b..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Attach_an_ISO_image_to_a_guest_VM.task.yaml +++ /dev/null @@ -1,12 +0,0 @@ -- name: Attach an ISO image to a guest VM - vmware.vmware_rest.vcenter_vm_hardware_cdrom: - vm: '{{ test_vm1_info.id }}' - type: SATA - sata: - bus: 0 - unit: 2 - start_connected: true - backing: - iso_file: '[ro_datastore] fedora.iso' - type: ISO_FILE - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_clusters.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_clusters.result.json deleted file mode 100644 index 3415fae6f6e..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_clusters.result.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "value": [ - { - "drs_enabled": false, - "cluster": "domain-c1636", - "name": "my_cluster", - "ha_enabled": false - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_clusters.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_clusters.task.yaml deleted file mode 100644 index cd12250cf91..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_clusters.task.yaml +++ /dev/null @@ -1,3 +0,0 @@ -- name: Build a list of all the clusters - vmware.vmware_rest.vcenter_cluster_info: - register: all_the_clusters diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders.result.json deleted file mode 100644 index 516234d4c69..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders.result.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "value": [ - { - "folder": "group-d1", - "name": "Datacenters", - "type": "DATACENTER" - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders.task.yaml deleted file mode 100644 index 12646e73b45..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders.task.yaml +++ /dev/null @@ -1,3 +0,0 @@ -- name: Build a list of all the folders - vmware.vmware_rest.vcenter_folder_info: - register: my_folders diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders_with_the_type_VIRTUAL_MACHINE_and_called_vm.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders_with_the_type_VIRTUAL_MACHINE_and_called_vm.result.json deleted file mode 100644 index ecf53f73ebb..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders_with_the_type_VIRTUAL_MACHINE_and_called_vm.result.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "value": [ - { - "folder": "group-v1631", - "name": "vm", - "type": "VIRTUAL_MACHINE" - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders_with_the_type_VIRTUAL_MACHINE_and_called_vm.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders_with_the_type_VIRTUAL_MACHINE_and_called_vm.task.yaml deleted file mode 100644 index 0ab8854d611..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Build_a_list_of_all_the_folders_with_the_type_VIRTUAL_MACHINE_and_called_vm.task.yaml +++ /dev/null @@ -1,6 +0,0 @@ -- name: Build a list of all the folders with the type VIRTUAL_MACHINE and called vm - vmware.vmware_rest.vcenter_folder_info: - filter_type: VIRTUAL_MACHINE - filter_names: - - vm - register: my_folders diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_MANUAL.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_MANUAL.result.json deleted file mode 100644 index e15f41c5fae..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_MANUAL.result.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "id": null, - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_MANUAL.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_MANUAL.task.yaml deleted file mode 100644 index a8f411e8790..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_MANUAL.task.yaml +++ /dev/null @@ -1,5 +0,0 @@ -- name: Change vm-tools upgrade policy to MANUAL - vmware.vmware_rest.vcenter_vm_tools: - vm: '{{ test_vm1_info.id }}' - upgrade_policy: MANUAL - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_UPGRADE_AT_POWER_CYCLE.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_UPGRADE_AT_POWER_CYCLE.result.json deleted file mode 100644 index e15f41c5fae..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_UPGRADE_AT_POWER_CYCLE.result.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "id": null, - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_UPGRADE_AT_POWER_CYCLE.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_UPGRADE_AT_POWER_CYCLE.task.yaml deleted file mode 100644 index e7396035288..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Change_vm-tools_upgrade_policy_to_UPGRADE_AT_POWER_CYCLE.task.yaml +++ /dev/null @@ -1,5 +0,0 @@ -- name: Change vm-tools upgrade policy to UPGRADE_AT_POWER_CYCLE - vmware.vmware_rest.vcenter_vm_tools: - vm: '{{ test_vm1_info.id }}' - upgrade_policy: UPGRADE_AT_POWER_CYCLE - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_information_about_a_specific_VM.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_information_about_a_specific_VM.result.json deleted file mode 100644 index d0f17cbb719..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_information_about_a_specific_VM.result.json +++ /dev/null @@ -1,77 +0,0 @@ -{ - "value": { - "instant_clone_frozen": false, - "cdroms": [], - "memory": { - "size_MiB": 1024, - "hot_add_enabled": true - }, - "disks": [ - { - "value": { - "scsi": { - "bus": 0, - "unit": 0 - }, - "backing": { - "vmdk_file": "[local] test_vm1_8/test_vm1.vmdk", - "type": "VMDK_FILE" - }, - "label": "Hard disk 1", - "type": "SCSI", - "capacity": 17179869184 - }, - "key": "2000" - } - ], - "parallel_ports": [], - "sata_adapters": [], - "cpu": { - "hot_remove_enabled": false, - "count": 1, - "hot_add_enabled": false, - "cores_per_socket": 1 - }, - "scsi_adapters": [ - { - "value": { - "scsi": { - "bus": 0, - "unit": 7 - }, - "label": "SCSI controller 0", - "sharing": "NONE", - "type": "PVSCSI" - }, - "key": "1000" - } - ], - "power_state": "POWERED_OFF", - "floppies": [], - "identity": { - "name": "test_vm1", - "instance_uuid": "5033c296-6954-64df-faca-d001de53763d", - "bios_uuid": "42330d17-e603-d925-fa4b-18827dbc1409" - }, - "nvme_adapters": [], - "name": "test_vm1", - "nics": [], - "boot": { - "delay": 0, - "retry_delay": 10000, - "enter_setup_mode": false, - "type": "BIOS", - "retry": false - }, - "serial_ports": [], - "boot_devices": [], - "guest_OS": "DEBIAN_8_64", - "hardware": { - "upgrade_policy": "NEVER", - "upgrade_status": "NONE", - "version": "VMX_11" - } - }, - "id": "vm-1650", - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_information_about_a_specific_VM.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_information_about_a_specific_VM.task.yaml deleted file mode 100644 index a113ecc5fe5..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_information_about_a_specific_VM.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Collect information about a specific VM - vmware.vmware_rest.vcenter_vm_info: - vm: '{{ search_result.value[0].vm }}' - register: test_vm1_info diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_the_hardware_information.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_the_hardware_information.result.json deleted file mode 100644 index c2e162c5db2..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_the_hardware_information.result.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "value": { - "upgrade_policy": "NEVER", - "upgrade_status": "NONE", - "version": "VMX_11" - }, - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_the_hardware_information.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_the_hardware_information.task.yaml deleted file mode 100644 index c6401eced1a..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Collect_the_hardware_information.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Collect the hardware information - vmware.vmware_rest.vcenter_vm_hardware_info: - vm: '{{ search_result.value[0].vm }}' - register: my_vm1_hardware_info diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_SATA_adapter_at_PCI_slot_34.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_SATA_adapter_at_PCI_slot_34.result.json deleted file mode 100644 index 62ae281ec05..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_SATA_adapter_at_PCI_slot_34.result.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "value": { - "bus": 0, - "pci_slot_number": 34, - "label": "SATA controller 0", - "type": "AHCI" - }, - "id": "15000", - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_SATA_adapter_at_PCI_slot_34.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_SATA_adapter_at_PCI_slot_34.task.yaml deleted file mode 100644 index 37d3f355ed7..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_SATA_adapter_at_PCI_slot_34.task.yaml +++ /dev/null @@ -1,5 +0,0 @@ -- name: Create a SATA adapter at PCI slot 34 - vmware.vmware_rest.vcenter_vm_hardware_adapter_sata: - vm: '{{ test_vm1_info.id }}' - pci_slot_number: 34 - register: _sata_adapter_result_1 diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_VM.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_VM.result.json deleted file mode 100644 index d309d076a04..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_VM.result.json +++ /dev/null @@ -1,77 +0,0 @@ -{ - "value": { - "instant_clone_frozen": false, - "cdroms": [], - "memory": { - "size_MiB": 1024, - "hot_add_enabled": true - }, - "disks": [ - { - "value": { - "scsi": { - "bus": 0, - "unit": 0 - }, - "backing": { - "vmdk_file": "[local] test_vm1_8/test_vm1.vmdk", - "type": "VMDK_FILE" - }, - "label": "Hard disk 1", - "type": "SCSI", - "capacity": 17179869184 - }, - "key": "2000" - } - ], - "parallel_ports": [], - "sata_adapters": [], - "cpu": { - "hot_remove_enabled": false, - "count": 1, - "hot_add_enabled": false, - "cores_per_socket": 1 - }, - "scsi_adapters": [ - { - "value": { - "scsi": { - "bus": 0, - "unit": 7 - }, - "label": "SCSI controller 0", - "sharing": "NONE", - "type": "PVSCSI" - }, - "key": "1000" - } - ], - "power_state": "POWERED_OFF", - "floppies": [], - "identity": { - "name": "test_vm1", - "instance_uuid": "5033c296-6954-64df-faca-d001de53763d", - "bios_uuid": "42330d17-e603-d925-fa4b-18827dbc1409" - }, - "nvme_adapters": [], - "name": "test_vm1", - "nics": [], - "boot": { - "delay": 0, - "retry_delay": 10000, - "enter_setup_mode": false, - "type": "BIOS", - "retry": false - }, - "serial_ports": [], - "boot_devices": [], - "guest_OS": "DEBIAN_8_64", - "hardware": { - "upgrade_policy": "NEVER", - "upgrade_status": "NONE", - "version": "VMX_11" - } - }, - "id": "vm-1650", - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_VM.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_VM.task.yaml deleted file mode 100644 index 02a6128d1fe..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_VM.task.yaml +++ /dev/null @@ -1,14 +0,0 @@ -- name: Create a VM - vmware.vmware_rest.vcenter_vm: - placement: - cluster: "{{ my_cluster_info.id }}" - datastore: "{{ my_datastore.datastore }}" - folder: "{{ my_virtual_machine_folder.folder }}" - resource_pool: "{{ my_cluster_info.value.resource_pool }}" - name: test_vm1 - guest_OS: DEBIAN_8_64 - hardware_version: VMX_11 - memory: - hot_add_enabled: true - size_MiB: 1024 - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_new_disk.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_new_disk.result.json deleted file mode 100644 index 7b4275ca7a1..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_new_disk.result.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "value": { - "backing": { - "vmdk_file": "[local] test_vm1_8/test_vm1_1.vmdk", - "type": "VMDK_FILE" - }, - "label": "Hard disk 2", - "type": "SATA", - "sata": { - "bus": 0, - "unit": 0 - }, - "capacity": 320000 - }, - "id": "16000", - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_new_disk.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_new_disk.task.yaml deleted file mode 100644 index 06f34b6f9a6..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Create_a_new_disk.task.yaml +++ /dev/null @@ -1,7 +0,0 @@ -- name: Create a new disk - vmware.vmware_rest.vcenter_vm_hardware_disk: - vm: '{{ test_vm1_info.id }}' - type: SATA - new_vmdk: - capacity: 320000 - register: my_new_disk diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Dedicate_one_core_to_the_VM.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Dedicate_one_core_to_the_VM.result.json deleted file mode 100644 index 8d2169bbb26..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Dedicate_one_core_to_the_VM.result.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "value": { - "hot_remove_enabled": false, - "count": 1, - "hot_add_enabled": false, - "cores_per_socket": 1 - }, - "id": null, - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Dedicate_one_core_to_the_VM.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Dedicate_one_core_to_the_VM.task.yaml deleted file mode 100644 index 9eb9ff947cc..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Dedicate_one_core_to_the_VM.task.yaml +++ /dev/null @@ -1,5 +0,0 @@ -- name: Dedicate one core to the VM - vmware.vmware_rest.vcenter_vm_hardware_cpu: - vm: '{{ test_vm1_info.id }}' - count: 1 - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_VM_storage_policy.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_VM_storage_policy.result.json deleted file mode 100644 index 204ad5f9afb..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_VM_storage_policy.result.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "value": { - "disks": [] - }, - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_VM_storage_policy.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_VM_storage_policy.task.yaml deleted file mode 100644 index c54620cb820..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_VM_storage_policy.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Get VM storage policy - vmware.vmware_rest.vcenter_vm_storage_policy_info: - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_filesystem_information.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_filesystem_information.result.json deleted file mode 100644 index ad87f76d203..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_filesystem_information.result.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "value": [ - { - "value": { - "mappings": [], - "free_space": 774766592, - "capacity": 2515173376 - }, - "key": "/" - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_filesystem_information.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_filesystem_information.task.yaml deleted file mode 100644 index e14685998f9..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_filesystem_information.task.yaml +++ /dev/null @@ -1,8 +0,0 @@ -- name: Get guest filesystem information - vmware.vmware_rest.vcenter_vm_guest_localfilesystem_info: - vm: '{{ test_vm1_info.id }}' - register: _result - until: - - _result is not failed - retries: 60 - delay: 5 diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_identity_information.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_identity_information.result.json deleted file mode 100644 index 01e8a8fd1c9..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_identity_information.result.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "value": { - "full_name": { - "args": [], - "default_message": "Red Hat Fedora (64-bit)", - "id": "vmsg.guestos.fedora64Guest.label" - }, - "name": "FEDORA_64", - "ip_address": "192.168.122.242", - "family": "LINUX", - "host_name": "localhost.localdomain" - }, - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_identity_information.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_identity_information.task.yaml deleted file mode 100644 index cb0f69f9520..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_identity_information.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Get guest identity information - vmware.vmware_rest.vcenter_vm_guest_identity_info: - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_interfaces_information.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_interfaces_information.result.json deleted file mode 100644 index 2c973374afc..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_interfaces_information.result.json +++ /dev/null @@ -1,23 +0,0 @@ -{ - "value": [ - { - "mac_address": "00:50:56:b3:49:5c", - "ip": { - "ip_addresses": [ - { - "ip_address": "192.168.122.242", - "prefix_length": 24, - "state": "PREFERRED" - }, - { - "ip_address": "fe80::b8d0:511b:897f:65a2", - "prefix_length": 64, - "state": "UNKNOWN" - } - ] - }, - "nic": "4000" - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_interfaces_information.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_interfaces_information.task.yaml deleted file mode 100644 index ec7e49861eb..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_interfaces_information.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Get guest network interfaces information - vmware.vmware_rest.vcenter_vm_guest_networking_interfaces_info: - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_routes_information.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_routes_information.result.json deleted file mode 100644 index 68e2033dd73..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_routes_information.result.json +++ /dev/null @@ -1,31 +0,0 @@ -{ - "value": [ - { - "gateway_address": "192.168.122.1", - "interface_index": 0, - "prefix_length": 0, - "network": "0.0.0.0" - }, - { - "interface_index": 0, - "prefix_length": 24, - "network": "192.168.122.0" - }, - { - "interface_index": 0, - "prefix_length": 64, - "network": "fe80::" - }, - { - "interface_index": 0, - "prefix_length": 128, - "network": "fe80::b8d0:511b:897f:65a2" - }, - { - "interface_index": 0, - "prefix_length": 8, - "network": "ff00::" - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_routes_information.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_routes_information.task.yaml deleted file mode 100644 index 5f0148fa4e6..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_network_routes_information.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Get guest network routes information - vmware.vmware_rest.vcenter_vm_guest_networking_routes_info: - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_networking_information.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_networking_information.result.json deleted file mode 100644 index fe757b647cc..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_networking_information.result.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "value": { - "dns": { - "ip_addresses": [ - "10.0.2.3" - ], - "search_domains": [ - "localdomain" - ] - }, - "dns_values": { - "domain_name": "localdomain", - "host_name": "localhost.localdomain" - } - }, - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_networking_information.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_networking_information.task.yaml deleted file mode 100644 index 7184971cb72..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_networking_information.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Get guest networking information - vmware.vmware_rest.vcenter_vm_guest_networking_info: - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_power_information.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_power_information.result.json deleted file mode 100644 index da317782489..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_power_information.result.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "value": { - "state": "POWERED_ON" - }, - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_power_information.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_power_information.task.yaml deleted file mode 100644 index a4ceffd956b..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Get_guest_power_information.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Get guest power information - vmware.vmware_rest.vcenter_vm_power_info: - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Increase_the_memory_of_a_VM.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Increase_the_memory_of_a_VM.result.json deleted file mode 100644 index e15f41c5fae..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Increase_the_memory_of_a_VM.result.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "id": null, - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Increase_the_memory_of_a_VM.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Increase_the_memory_of_a_VM.task.yaml deleted file mode 100644 index bd53b184969..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Increase_the_memory_of_a_VM.task.yaml +++ /dev/null @@ -1,5 +0,0 @@ -- name: Increase the memory of a VM - vmware.vmware_rest.vcenter_vm_hardware_memory: - vm: '{{ test_vm1_info.id }}' - size_MiB: 1080 - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_SCSI_adapter_of_a_given_VM.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_SCSI_adapter_of_a_given_VM.result.json deleted file mode 100644 index 3ecaa4bdbcf..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_SCSI_adapter_of_a_given_VM.result.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "value": [ - { - "scsi": { - "bus": 0, - "unit": 7 - }, - "label": "SCSI controller 0", - "type": "PVSCSI", - "sharing": "NONE" - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_SCSI_adapter_of_a_given_VM.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_SCSI_adapter_of_a_given_VM.task.yaml deleted file mode 100644 index 8b7d0eeae2e..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_SCSI_adapter_of_a_given_VM.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: List the SCSI adapter of a given VM - vmware.vmware_rest.vcenter_vm_hardware_adapter_scsi_info: - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_cdrom_devices_on_the_guest.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_cdrom_devices_on_the_guest.result.json deleted file mode 100644 index a838aa542fc..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_cdrom_devices_on_the_guest.result.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "value": [], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_cdrom_devices_on_the_guest.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_cdrom_devices_on_the_guest.task.yaml deleted file mode 100644 index e31ac100fa3..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/List_the_cdrom_devices_on_the_guest.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: List the cdrom devices on the guest - vmware.vmware_rest.vcenter_vm_hardware_cdrom_info: - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Look_up_the_VM_called_test_vm1_in_the_inventory.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Look_up_the_VM_called_test_vm1_in_the_inventory.result.json deleted file mode 100644 index 3b5e197e5a1..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Look_up_the_VM_called_test_vm1_in_the_inventory.result.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "value": [ - { - "memory_size_MiB": 1024, - "vm": "vm-1650", - "name": "test_vm1", - "power_state": "POWERED_OFF", - "cpu_count": 1 - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Look_up_the_VM_called_test_vm1_in_the_inventory.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Look_up_the_VM_called_test_vm1_in_the_inventory.task.yaml deleted file mode 100644 index 43372ac3834..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Look_up_the_VM_called_test_vm1_in_the_inventory.task.yaml +++ /dev/null @@ -1,5 +0,0 @@ -- name: Look up the VM called test_vm1 in the inventory - register: search_result - vmware.vmware_rest.vcenter_vm_info: - filter_names: - - test_vm1 diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Remove_SATA_adapter_at_PCI_slot_34.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Remove_SATA_adapter_at_PCI_slot_34.result.json deleted file mode 100644 index aac751af72e..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Remove_SATA_adapter_at_PCI_slot_34.result.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_a_list_of_all_the_datastores.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_a_list_of_all_the_datastores.result.json deleted file mode 100644 index 48c3cf80b78..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_a_list_of_all_the_datastores.result.json +++ /dev/null @@ -1,26 +0,0 @@ -{ - "value": [ - { - "datastore": "datastore-1644", - "name": "local", - "type": "VMFS", - "free_space": 13523484672, - "capacity": 15032385536 - }, - { - "datastore": "datastore-1645", - "name": "ro_datastore", - "type": "NFS", - "free_space": 24638349312, - "capacity": 26831990784 - }, - { - "datastore": "datastore-1646", - "name": "rw_datastore", - "type": "NFS", - "free_space": 24638349312, - "capacity": 26831990784 - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_a_list_of_all_the_datastores.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_a_list_of_all_the_datastores.task.yaml deleted file mode 100644 index 1ded56f0869..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_a_list_of_all_the_datastores.task.yaml +++ /dev/null @@ -1,3 +0,0 @@ -- name: Retrieve a list of all the datastores - vmware.vmware_rest.vcenter_datastore_info: - register: my_datastores diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_details_about_the_first_cluster.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_details_about_the_first_cluster.result.json deleted file mode 100644 index 7c86727a827..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_details_about_the_first_cluster.result.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "value": { - "name": "my_cluster", - "resource_pool": "resgroup-1637" - }, - "id": "domain-c1636", - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_details_about_the_first_cluster.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_details_about_the_first_cluster.task.yaml deleted file mode 100644 index 4b097889525..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_details_about_the_first_cluster.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Retrieve details about the first cluster - vmware.vmware_rest.vcenter_cluster_info: - cluster: "{{ all_the_clusters.value[0].cluster }}" - register: my_cluster_info diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_disk_information_from_the_VM.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_disk_information_from_the_VM.result.json deleted file mode 100644 index 922250ed0ca..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_disk_information_from_the_VM.result.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "value": [ - { - "scsi": { - "bus": 0, - "unit": 0 - }, - "backing": { - "vmdk_file": "[local] test_vm1_8/test_vm1.vmdk", - "type": "VMDK_FILE" - }, - "label": "Hard disk 1", - "type": "SCSI", - "capacity": 17179869184 - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_disk_information_from_the_VM.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_disk_information_from_the_VM.task.yaml deleted file mode 100644 index e9c39a32124..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_disk_information_from_the_VM.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Retrieve the disk information from the VM - vmware.vmware_rest.vcenter_vm_hardware_disk_info: - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_memory_information_from_the_VM.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_memory_information_from_the_VM.result.json deleted file mode 100644 index 88436c13af0..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_memory_information_from_the_VM.result.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "value": { - "size_MiB": 1024, - "hot_add_enabled": true - }, - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_memory_information_from_the_VM.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_memory_information_from_the_VM.task.yaml deleted file mode 100644 index bccf589e530..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Retrieve_the_memory_information_from_the_VM.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Retrieve the memory information from the VM - vmware.vmware_rest.vcenter_vm_hardware_memory_info: - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_NIC's_start_connected_flag_on.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_NIC's_start_connected_flag_on.result.json deleted file mode 100644 index 9c0c9c1f407..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_NIC's_start_connected_flag_on.result.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "id": "4000", - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_NIC's_start_connected_flag_on.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_NIC's_start_connected_flag_on.task.yaml deleted file mode 100644 index a06bbd9db33..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_NIC's_start_connected_flag_on.task.yaml +++ /dev/null @@ -1,5 +0,0 @@ -- name: Turn the NIC's start_connected flag on - vmware.vmware_rest.vcenter_vm_hardware_ethernet: - nic: '{{ vm_hardware_ethernet_1.id }}' - start_connected: true - vm: '{{ test_vm1_info.id }}' diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_power_of_the_VM_on.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_power_of_the_VM_on.result.json deleted file mode 100644 index a661aa055d3..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_power_of_the_VM_on.result.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_power_of_the_VM_on.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_power_of_the_VM_on.task.yaml deleted file mode 100644 index fc3b21164bf..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Turn_the_power_of_the_VM_on.task.yaml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Turn the power of the VM on - vmware.vmware_rest.vcenter_vm_power: - state: start - vm: '{{ test_vm1_info.id }}' diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Upgrade_the_VM_hardware_version.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Upgrade_the_VM_hardware_version.result.json deleted file mode 100644 index e15f41c5fae..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Upgrade_the_VM_hardware_version.result.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "id": null, - "changed": true -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Upgrade_the_VM_hardware_version.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Upgrade_the_VM_hardware_version.task.yaml deleted file mode 100644 index 6a5ad0dc48b..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Upgrade_the_VM_hardware_version.task.yaml +++ /dev/null @@ -1,6 +0,0 @@ -- name: Upgrade the VM hardware version - vmware.vmware_rest.vcenter_vm_hardware: - upgrade_policy: AFTER_CLEAN_SHUTDOWN - upgrade_version: VMX_13 - vm: '{{ test_vm1_info.id }}' - register: _result diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Wait_until_my_VM_is_ready.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Wait_until_my_VM_is_ready.result.json deleted file mode 100644 index 849bde48318..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Wait_until_my_VM_is_ready.result.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "value": { - "auto_update_supported": false, - "upgrade_policy": "MANUAL", - "install_attempt_count": 0, - "version_status": "UNMANAGED", - "version_number": 10346, - "run_state": "RUNNING", - "version": "10346", - "install_type": "OPEN_VM_TOOLS" - }, - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Wait_until_my_VM_is_ready.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Wait_until_my_VM_is_ready.task.yaml deleted file mode 100644 index f6f64e844b5..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/Wait_until_my_VM_is_ready.task.yaml +++ /dev/null @@ -1,9 +0,0 @@ -- name: Wait until my VM is ready - vmware.vmware_rest.vcenter_vm_tools_info: - vm: '{{ test_vm1_info.id }}' - register: vm_tools_info - until: - - vm_tools_info is not failed - - vm_tools_info.value.run_state == "RUNNING" - retries: 60 - delay: 5 diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/collect_a_list_of_the_datacenters.result.json b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/collect_a_list_of_the_datacenters.result.json deleted file mode 100644 index 1225ad7f93a..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/collect_a_list_of_the_datacenters.result.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "value": [ - { - "name": "my_dc", - "datacenter": "datacenter-1630" - } - ], - "changed": false -} \ No newline at end of file diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/collect_a_list_of_the_datacenters.task.yaml b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/collect_a_list_of_the_datacenters.task.yaml deleted file mode 100644 index beb2cc62160..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/task_outputs/collect_a_list_of_the_datacenters.task.yaml +++ /dev/null @@ -1,3 +0,0 @@ -- name: collect a list of the datacenters - vmware.vmware_rest.vcenter_datacenter_info: - register: my_datacenters diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_hardware_tuning.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_hardware_tuning.rst deleted file mode 100644 index c6b5febd720..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_hardware_tuning.rst +++ /dev/null @@ -1,150 +0,0 @@ -.. _vmware_rest_vm_hardware_tuning: - -******************************* -How to modify a virtual machine -******************************* - -.. contents:: - :local: - - -Introduction -============ - -This section shows you how to use Ansible to modify an existing virtual machine. - -Scenario requirements -===================== - -You've already followed :ref:`vmware_rest_create_vm` and created a VM. - -How to add a CDROM drive to a virtual machine -============================================= - -In this example, we use the ``vcenter_vm_hardware_*`` modules to add a new CDROM to an existing VM. - -Add a new SATA adapter -______________________ - -First we create a new SATA adapter. We specify the ``pci_slot_number``. This way if we run the task again it won't do anything if there is already an adapter there. - -.. literalinclude:: task_outputs/Create_a_SATA_adapter_at_PCI_slot_34.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Create_a_SATA_adapter_at_PCI_slot_34.result.json - -Add a CDROM drive -_________________ - -Now we can create the CDROM drive: - -.. literalinclude:: task_outputs/Attach_an_ISO_image_to_a_guest_VM.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Attach_an_ISO_image_to_a_guest_VM.result.json - - -.. _vmware_rest_attach_a_network: - -How to attach a VM to a network -=============================== - -Attach a new NIC -________________ - -Here we attach the VM to the network (through the portgroup). We specify a ``pci_slot_number`` for the same reason. - -The second task adjusts the NIC configuration. - -.. literalinclude:: task_outputs/Attach_a_VM_to_a_dvswitch.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Attach_a_VM_to_a_dvswitch.result.json - -Adjust the configuration of the NIC -___________________________________ - -.. literalinclude:: task_outputs/Turn_the_NIC's_start_connected_flag_on.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Turn_the_NIC's_start_connected_flag_on.result.json - -Increase the memory of the VM -============================= - -We can also adjust the amount of memory that we dedicate to our VM. - -.. literalinclude:: task_outputs/Increase_the_memory_of_a_VM.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Increase_the_memory_of_a_VM.result.json - -Upgrade the hardware version of the VM -====================================== - -Here we use the ``vcenter_vm_hardware`` module to upgrade the version of the hardware: - -.. literalinclude:: task_outputs/Upgrade_the_VM_hardware_version.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Upgrade_the_VM_hardware_version.result.json - -Adjust the number of CPUs of the VM -=================================== - -You can use ``vcenter_vm_hardware_cpu`` for that: - -.. literalinclude:: task_outputs/Dedicate_one_core_to_the_VM.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Dedicate_one_core_to_the_VM.result.json - -Remove a SATA controller -========================== - -In this example, we remove the SATA controller of the PCI slot 34. - -.. literalinclude:: task_outputs/Remove_SATA_adapter_at_PCI_slot_34.result.json - -Result -______ - -.. literalinclude:: task_outputs/Remove_SATA_adapter_at_PCI_slot_34.result.json - -Attach a floppy drive -===================== - -Here we attach a floppy drive to a VM. - -.. literalinclude:: task_outputs/Add_a_floppy_disk_drive.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Add_a_floppy_disk_drive.result.json - -Attach a new disk -================= - -Here we attach a tiny disk to the VM. The ``capacity`` is in bytes. - -.. literalinclude:: task_outputs/Create_a_new_disk.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Create_a_new_disk.result.json diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_info.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_info.rst deleted file mode 100644 index 08daceb929a..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_info.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. _vmware_rest_vm_info: - -*************************************** -Retrieve information from a specific VM -*************************************** - -.. contents:: - :local: - - -Introduction -============ - -This section shows you how to use Ansible to retrieve information about a specific virtual machine. - -Scenario requirements -===================== - -You've already followed :ref:`vmware_rest_create_vm` and you've got create a new VM called ``test_vm1``. - -How to collect virtual machine information -========================================== - -List the VM -___________ - -In this example, we use the ``vcenter_vm_info`` module to collect information about our new VM. - -In this example, we start by asking for a list of VMs. We use a filter to limit the results to just the VM called ``test_vm1``. So we are in a list context, with one single entry in the ``value`` key. - -.. literalinclude:: task_outputs/Look_up_the_VM_called_test_vm1_in_the_inventory.task.yaml - -Result -______ - -As expected, we get a list. And thanks to our filter, we just get one entry. - -.. literalinclude:: task_outputs/Look_up_the_VM_called_test_vm1_in_the_inventory.result.json - -Collect the details about a specific VM -_______________________________________ - -For the next steps, we pass the ID of the VM through the ``vm`` parameter. This allow us to collect more details about this specific VM. - -.. literalinclude:: task_outputs/Collect_information_about_a_specific_VM.task.yaml - -Result -______ - -The result is a structure with all the details about our VM. You will note this is actually the same information that we get when we created the VM. - -.. literalinclude:: task_outputs/Collect_information_about_a_specific_VM.result.json - - -Get the hardware version of a specific VM -_________________________________________ - -We can also use all the ``vcenter_vm_*_info`` modules to retrieve a smaller amount -of information. Here we use ``vcenter_vm_hardware_info`` to know the hardware version of -the VM. - -.. literalinclude:: task_outputs/Collect_the_hardware_information.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Collect_the_hardware_information.result.json - -List the SCSI adapter(s) of a specific VM -_________________________________________ - -Here for example, we list the SCSI adapter(s) of the VM: - -.. literalinclude:: task_outputs/List_the_SCSI_adapter_of_a_given_VM.task.yaml - -You can do the same for the SATA controllers with ``vcenter_vm_adapter_sata_info``. - -Result -______ - -.. literalinclude:: task_outputs/List_the_SCSI_adapter_of_a_given_VM.result.json - -List the CDROM drive(s) of a specific VM -________________________________________ - -And we list its CDROM drives. - -.. literalinclude:: task_outputs/List_the_cdrom_devices_on_the_guest.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/List_the_cdrom_devices_on_the_guest.result.json - -Get the memory information of the VM -____________________________________ - -Here we collect the memory information of the VM: - -.. literalinclude:: task_outputs/Retrieve_the_memory_information_from_the_VM.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Retrieve_the_memory_information_from_the_VM.result.json - -Get the storage policy of the VM --------------------------------- - -We use the ``vcenter_vm_storage_policy_info`` module for that: - -.. literalinclude:: task_outputs/Get_VM_storage_policy.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Get_VM_storage_policy.result.json - -Get the disk information of the VM ----------------------------------- - -We use the ``vcenter_vm_hardware_disk_info`` for this operation: - -.. literalinclude:: task_outputs/Retrieve_the_disk_information_from_the_VM.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Retrieve_the_disk_information_from_the_VM.result.json diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_tool_configuration.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_tool_configuration.rst deleted file mode 100644 index b29447aec52..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_tool_configuration.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _vmware_rest_vm_tool_configuration: - -************************************************************** -How to configure the VMware tools of a running virtual machine -************************************************************** - -.. contents:: - :local: - - -Introduction -============ - -This section show you how to collection information from a running virtual machine. - -Scenario requirements -===================== - -You've already followed :ref:`vmware_rest_run_a_vm` and your virtual machine runs VMware Tools. - -How to change the upgrade policy -================================ - -Change the upgrade policy to MANUAL ---------------------------------------------------- - -You can adjust the VMware Tools upgrade policy with the ``vcenter_vm_tools`` module. - -.. literalinclude:: task_outputs/Change_vm-tools_upgrade_policy_to_MANUAL.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Change_vm-tools_upgrade_policy_to_MANUAL.result.json - - -Change the upgrade policy to UPGRADE_AT_POWER_CYCLE ------------------------------------------------------------------------------------------- - -.. literalinclude:: task_outputs/Change_vm-tools_upgrade_policy_to_UPGRADE_AT_POWER_CYCLE.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Change_vm-tools_upgrade_policy_to_UPGRADE_AT_POWER_CYCLE.result.json diff --git a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_tool_information.rst b/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_tool_information.rst deleted file mode 100644 index 2f92871db37..00000000000 --- a/docs/docsite/rst/scenario_guides/vmware_rest_scenarios/vm_tool_information.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. _vmware_rest_vm_tool_information: - -***************************************************** -How to get information from a running virtual machine -***************************************************** - -.. contents:: - :local: - - -Introduction -============ - -This section shows you how to collection information from a running virtual machine. - -Scenario requirements -===================== - -You've already followed :ref:`vmware_rest_run_a_vm` and your virtual machine runs VMware Tools. - -How to collect information -========================== - -In this example, we use the ``vcenter_vm_guest_*`` module to collect information about the associated resources. - -Filesystem ----------- - -Here we use ``vcenter_vm_guest_localfilesystem_info`` to retrieve the details -about the filesystem of the guest. In this example we also use a ``retries`` -loop. The VMware Tools may take a bit of time to start and by doing so, we give -the VM a bit more time. - -.. literalinclude:: task_outputs/Get_guest_filesystem_information.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Get_guest_filesystem_information.result.json - -Guest identity --------------- - -You can use ``vcenter_vm_guest_identity_info`` to get details like the OS family or the hostname of the running VM. - -.. literalinclude:: task_outputs/Get_guest_identity_information.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Get_guest_identity_information.result.json - -Network -------- - -``vcenter_vm_guest_networking_info`` will return the OS network configuration. - -.. literalinclude:: task_outputs/Get_guest_networking_information.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Get_guest_networking_information.result.json - -Network interfaces ------------------- - -``vcenter_vm_guest_networking_interfaces_info`` will return a list of NIC configurations. - -See also :ref:`vmware_rest_attach_a_network`. - -.. literalinclude:: task_outputs/Get_guest_network_interfaces_information.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Get_guest_network_interfaces_information.result.json - -Network routes --------------- - -Use ``vcenter_vm_guest_networking_routes_info`` to explore the route table of your virtual machine. - -.. literalinclude:: task_outputs/Get_guest_network_routes_information.task.yaml - -Result -______ - -.. literalinclude:: task_outputs/Get_guest_network_routes_information.result.json - From e3ae8ba3f15b16277d1261234fb302c19b354990 Mon Sep 17 00:00:00 2001 From: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> Date: Wed, 13 Dec 2023 01:56:15 -0500 Subject: [PATCH 140/536] Add documentation for the custom Jinja2 global function `undef` (#953) * Add documentation for the custom Jinja2 global undef * Fix plugin references refer to undef as a function everywhere * use an example that won't immediately become inaccurate * remove docs encouraging undef() for resetting role defaults when setting public (or using the config) is better --- docs/docsite/rst/playbook_guide/playbooks.rst | 1 + .../rst/playbook_guide/playbooks_filters.rst | 2 +- .../playbooks_templating_now.rst | 2 +- .../playbooks_templating_undef.rst | 31 +++++++++++++++++++ 4 files changed, 34 insertions(+), 2 deletions(-) create mode 100644 docs/docsite/rst/playbook_guide/playbooks_templating_undef.rst diff --git a/docs/docsite/rst/playbook_guide/playbooks.rst b/docs/docsite/rst/playbook_guide/playbooks.rst index 924e4e357d8..7f6659238dd 100644 --- a/docs/docsite/rst/playbook_guide/playbooks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks.rst @@ -26,6 +26,7 @@ These illustrate best practices as well as how to put many of the various concep playbooks_lookups playbooks_python_version playbooks_templating_now + playbooks_templating_undef playbooks_loops playbooks_delegation playbooks_conditionals diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index 21c48725096..ac01a6010f3 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -76,7 +76,7 @@ If you configure Ansible to ignore undefined variables, you may want to define s The variable value will be used as is, but the template evaluation will raise an error if it is undefined. -A convenient way of requiring a variable to be overridden is to give it an undefined value using the ``undef`` keyword. This can be useful in a role's defaults. +A convenient way of requiring a variable to be overridden is to give it an undefined value using the :ref:`undef() ` function. .. code-block:: yaml+jinja diff --git a/docs/docsite/rst/playbook_guide/playbooks_templating_now.rst b/docs/docsite/rst/playbook_guide/playbooks_templating_now.rst index 1ca608016f5..380995b49b1 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_templating_now.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_templating_now.rst @@ -7,7 +7,7 @@ The now function: get the current time The ``now()`` Jinja2 function retrieves a Python datetime object or a string representation for the current time. -The ``now()`` function supports 2 arguments: +The ``now()`` function supports two arguments: utc Specify ``True`` to get the current time in UTC. Defaults to ``False``. diff --git a/docs/docsite/rst/playbook_guide/playbooks_templating_undef.rst b/docs/docsite/rst/playbook_guide/playbooks_templating_undef.rst new file mode 100644 index 00000000000..d38febb5565 --- /dev/null +++ b/docs/docsite/rst/playbook_guide/playbooks_templating_undef.rst @@ -0,0 +1,31 @@ +.. _templating_undef: + +The undef function: add hint for undefined variables +==================================================== + +.. versionadded:: 2.12 + +The Jinja2 ``undef()`` function returns a Python ``AnsibleUndefined`` object, derived from ``jinja2.StrictUndefined``. Use ``undef()`` to undefine variables of :ref:`lesser precedence `. For example, a host variable can be overridden for a block of tasks: + +.. code-block:: yaml + + --- + - hosts: localhost + gather_facts: no + module_defaults: + group/ns.col.auth: "{{ vaulted_credentials | default({}) }}" + tasks: + - ns.col.module1: + - ns.col.module2: + + - name: override host variable + vars: + vaulted_credentials: "{{ undef() }}" + block: + - ns.col.module1: + + +The ``undef`` function accepts one optional argument: + +hint + Give a custom hint about the undefined variable if :ref:`DEFAULT_UNDEFINED_VAR_BEHAVIOR` is configured to give an error. From e64915d95d53983b0b2923178b5fdc29f4a13b26 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Wed, 13 Dec 2023 18:23:18 +0100 Subject: [PATCH 141/536] Remove Cisco ACI Scenario Guide (#983) --- .../docsite/rst/scenario_guides/guide_aci.rst | 659 ------------------ docs/docsite/rst/scenario_guides/guides.rst | 1 - .../rst/scenario_guides/network_guides.rst | 1 - 3 files changed, 661 deletions(-) delete mode 100644 docs/docsite/rst/scenario_guides/guide_aci.rst diff --git a/docs/docsite/rst/scenario_guides/guide_aci.rst b/docs/docsite/rst/scenario_guides/guide_aci.rst deleted file mode 100644 index 95e76b54b5c..00000000000 --- a/docs/docsite/rst/scenario_guides/guide_aci.rst +++ /dev/null @@ -1,659 +0,0 @@ -.. _aci_guide: - -Cisco ACI Guide -=============== - - -.. _aci_guide_intro: - -What is Cisco ACI ? -------------------- - -Application Centric Infrastructure (ACI) -........................................ -The Cisco Application Centric Infrastructure (ACI) allows application requirements to define the network. This architecture simplifies, optimizes, and accelerates the entire application deployment life cycle. - - -Application Policy Infrastructure Controller (APIC) -..................................................... -The APIC manages the scalable ACI multi-tenant fabric. The APIC provides a unified point of automation and management, policy programming, application deployment, and health monitoring for the fabric. The APIC, which is implemented as a replicated synchronized clustered controller, optimizes performance, supports any application anywhere, and provides unified operation of the physical and virtual infrastructure. - -The APIC enables network administrators to easily define the optimal network for applications. Data center operators can clearly see how applications consume network resources, easily isolate and troubleshoot application and infrastructure problems, and monitor and profile resource usage patterns. - -The Cisco Application Policy Infrastructure Controller (APIC) API enables applications to directly connect with a secure, shared, high-performance resource pool that includes network, compute, and storage capabilities. - - -ACI Fabric -.......... -The Cisco Application Centric Infrastructure (ACI) Fabric includes Cisco Nexus 9000 Series switches with the APIC to run in the leaf/spine ACI fabric mode. These switches form a "fat-tree" network by connecting each leaf node to each spine node; all other devices connect to the leaf nodes. The APIC manages the ACI fabric. - -The ACI fabric provides consistent low-latency forwarding across high-bandwidth links (40 Gbps, with a 100-Gbps future capability). Traffic with the source and destination on the same leaf switch is handled locally, and all other traffic travels from the ingress leaf to the egress leaf through a spine switch. Although this architecture appears as two hops from a physical perspective, it is actually a single Layer 3 hop because the fabric operates as a single Layer 3 switch. - -The ACI fabric object-oriented operating system (OS) runs on each Cisco Nexus 9000 Series node. It enables programming of objects for each configurable element of the system. The ACI fabric OS renders policies from the APIC into a concrete model that runs in the physical infrastructure. The concrete model is analogous to compiled software; it is the form of the model that the switch operating system can execute. - -All the switch nodes contain a complete copy of the concrete model. When an administrator creates a policy in the APIC that represents a configuration, the APIC updates the logical model. The APIC then performs the intermediate step of creating a fully elaborated policy that it pushes into all the switch nodes where the concrete model is updated. - -The APIC is responsible for fabric activation, switch firmware management, network policy configuration, and instantiation. While the APIC acts as the centralized policy and network management engine for the fabric, it is completely removed from the data path, including the forwarding topology. Therefore, the fabric can still forward traffic even when communication with the APIC is lost. - - -More information -................ -Various resources exist to start learning ACI, here is a list of interesting articles from the community. - -- `Adam Raffe: Learning ACI `_ -- `Luca Relandini: ACI for dummies `_ -- `Cisco DevNet Learning Labs about ACI `_ - - -.. _aci_guide_modules: - -Using the ACI modules ---------------------- -The Ansible ACI modules provide a user-friendly interface to managing your ACI environment using Ansible playbooks. - -For example ensuring that a specific tenant exists, is done using the following Ansible task using the aci_tenant module: - -.. code-block:: yaml - - - name: Ensure tenant customer-xyz exists - aci_tenant: - host: my-apic-1 - username: admin - password: my-password - - tenant: customer-xyz - description: Customer XYZ - state: present - -A complete list of existing ACI modules is available on the content tab of the `ACI collection on Ansible Galaxy `_. - -If you want to learn how to write your own ACI modules to contribute, look at the :ref:`Developing Cisco ACI modules ` section. - -Querying ACI configuration -.......................... - -A module can also be used to query a specific object. - -.. code-block:: yaml - - - name: Query tenant customer-xyz - aci_tenant: - host: my-apic-1 - username: admin - password: my-password - - tenant: customer-xyz - state: query - register: my_tenant - -Or query all objects. - -.. code-block:: yaml - - - name: Query all tenants - aci_tenant: - host: my-apic-1 - username: admin - password: my-password - - state: query - register: all_tenants - -After registering the return values of the aci_tenant task as shown above, you can access all tenant information from variable ``all_tenants``. - - -Running on the controller locally -................................... -As originally designed, Ansible modules are shipped to and run on the remote target(s), however the ACI modules (like most network-related modules) do not run on the network devices or controller (in this case the APIC), but they talk directly to the APIC's REST interface. - -For this very reason, the modules need to run on the local Ansible control node (or are delegated to another system that *can* connect to the APIC). - - -Gathering facts -``````````````` -Because we run the modules on the Ansible control node gathering facts will not work. That is why when using these ACI modules it is mandatory to disable facts gathering. You can do this globally in your ``ansible.cfg`` or by adding ``gather_facts: false`` to every play. - -.. code-block:: yaml - :emphasize-lines: 3 - - - name: Another play in my playbook - hosts: my-apic-1 - gather_facts: false - tasks: - - name: Create a tenant - aci_tenant: - ... - -Delegating to localhost -``````````````````````` -So let us assume we have our target configured in the inventory using the FQDN name as the ``ansible_host`` value, as shown below. - -.. code-block:: yaml - :emphasize-lines: 3 - - apics: - my-apic-1: - ansible_host: apic01.fqdn.intra - ansible_user: admin - ansible_password: my-password - -One way to set this up is to add to every task the directive: ``delegate_to: localhost``. - -.. code-block:: yaml - :emphasize-lines: 8 - - - name: Query all tenants - aci_tenant: - host: '{{ ansible_host }}' - username: '{{ ansible_user }}' - password: '{{ ansible_password }}' - - state: query - delegate_to: localhost - register: all_tenants - -If one would forget to add this directive, Ansible will attempt to connect to the APIC using SSH and attempt to copy the module and run it remotely. This will fail with a clear error, yet may be confusing to some. - - -Using the local connection method -````````````````````````````````` -Another option frequently used, is to tie the ``local`` connection method to this target so that every subsequent task for this target will use the local connection method (hence run it locally, rather than use SSH). - -In this case the inventory may look like this: - -.. code-block:: yaml - :emphasize-lines: 6 - - apics: - my-apic-1: - ansible_host: apic01.fqdn.intra - ansible_user: admin - ansible_password: my-password - ansible_connection: local - -But used tasks do not need anything special added. - -.. code-block:: yaml - - - name: Query all tenants - aci_tenant: - host: '{{ ansible_host }}' - username: '{{ ansible_user }}' - password: '{{ ansible_password }}' - - state: query - register: all_tenants - -.. hint:: For clarity we have added ``delegate_to: localhost`` to all the examples in the module documentation. This helps to ensure first-time users can easily copy&paste parts and make them work with a minimum of effort. - - -Common parameters -................. -Every Ansible ACI module accepts the following parameters that influence the module's communication with the APIC REST API: - - host - Hostname or IP address of the APIC. - - port - Port to use for communication. (Defaults to ``443`` for HTTPS, and ``80`` for HTTP) - - username - username used to log on to the APIC. (Defaults to ``admin``) - - password - Password for ``username`` to log on to the APIC, using password-based authentication. - - private_key - Private key for ``username`` to log on to APIC, using signature-based authentication. - This could either be the raw private key content (include header/footer) or a file that stores the key content. - *New in version 2.5* - - certificate_name - Name of the certificate in the ACI Web GUI. - This defaults to either the ``username`` value or the ``private_key`` file base name). - *New in version 2.5* - - timeout - Timeout value for socket-level communication. - - use_proxy - Use system proxy settings. (Defaults to ``true``) - - use_ssl - Use HTTPS or HTTP for APIC REST communication. (Defaults to ``true``) - - validate_certs - Validate certificate when using HTTPS communication. (Defaults to ``true``) - - output_level - Influence the level of detail ACI modules return to the user. (One of ``normal``, ``info`` or ``debug``) *New in version 2.5* - - -Proxy support -............. -By default, if an environment variable ``_proxy`` is set on the target host, requests will be sent through that proxy. This behavior can be overridden by setting a variable for this task (see :ref:`playbooks_environment`), or by using the ``use_proxy`` module parameter. - -HTTP redirects can redirect from HTTP to HTTPS so ensure that the proxy environment for both protocols is correctly configured. - -If proxy support is not needed, but the system may have it configured nevertheless, use the parameter ``use_proxy: false`` to avoid accidental system proxy usage. - -.. hint:: Selective proxy support using the ``no_proxy`` environment variable is also supported. - - -Return values -............. - -.. versionadded:: 2.5 - -The following values are always returned: - - current - The resulting state of the managed object, or results of your query. - -The following values are returned when ``output_level: info``: - - previous - The original state of the managed object (before any change was made). - - proposed - The proposed config payload, based on user-supplied values. - - sent - The sent config payload, based on user-supplied values and the existing configuration. - -The following values are returned when ``output_level: debug`` or ``ANSIBLE_DEBUG=1``: - - filter_string - The filter used for specific APIC queries. - - method - The HTTP method used for the sent payload. (Either ``GET`` for queries, ``DELETE`` or ``POST`` for changes) - - response - The HTTP response from the APIC. - - status - The HTTP status code for the request. - - url - The url used for the request. - -.. note:: The module return values are documented in detail as part of each module's documentation. - - -More information -................ -Various resources exist to start learn more about ACI programmability, we recommend the following links: - -- :ref:`Developing Cisco ACI modules ` -- `Jacob McGill: Automating Cisco ACI with Ansible `_ -- `Cisco DevNet Learning Labs about ACI and Ansible `_ - - -.. _aci_guide_auth: - -ACI authentication ------------------- - -Password-based authentication -............................. -If you want to log on using a username and password, you can use the following parameters with your ACI modules: - -.. code-block:: yaml - - username: admin - password: my-password - -Password-based authentication is very simple to work with, but it is not the most efficient form of authentication from ACI's point-of-view as it requires a separate login-request and an open session to work. To avoid having your session time-out and requiring another login, you can use the more efficient Signature-based authentication. - -.. note:: Password-based authentication also may trigger anti-DoS measures in ACI v3.1+ that causes session throttling and results in HTTP 503 errors and login failures. - -.. warning:: Never store passwords in plain text. - -The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :ref:`playbooks_vault` for more information. - - -Signature-based authentication using certificates -................................................. - -.. versionadded:: 2.5 - -Using signature-based authentication is more efficient and more reliable than password-based authentication. - -Generate certificate and private key -```````````````````````````````````` -Signature-based authentication requires a (self-signed) X.509 certificate with private key, and a configuration step for your AAA user in ACI. To generate a working X.509 certificate and private key, use the following procedure: - -.. code-block:: bash - - $ openssl req -new -newkey rsa:1024 -days 36500 -nodes -x509 -keyout admin.key -out admin.crt -subj '/CN=Admin/O=Your Company/C=US' - -Configure your local user -````````````````````````` -Perform the following steps: - -- Add the X.509 certificate to your ACI AAA local user at :guilabel:`ADMIN` » :guilabel:`AAA` -- Click :guilabel:`AAA Authentication` -- Check that in the :guilabel:`Authentication` field the :guilabel:`Realm` field displays :guilabel:`Local` -- Expand :guilabel:`Security Management` » :guilabel:`Local Users` -- Click the name of the user you want to add a certificate to, in the :guilabel:`User Certificates` area -- Click the :guilabel:`+` sign and in the :guilabel:`Create X509 Certificate` enter a certificate name in the :guilabel:`Name` field - - * If you use the basename of your private key here, you don't need to enter ``certificate_name`` in Ansible - -- Copy and paste your X.509 certificate in the :guilabel:`Data` field. - -You can automate this by using the following Ansible task: - -.. code-block:: yaml - - - name: Ensure we have a certificate installed - aci_aaa_user_certificate: - host: my-apic-1 - username: admin - password: my-password - - aaa_user: admin - certificate_name: admin - certificate: "{{ lookup('file', 'pki/admin.crt') }}" # This will read the certificate data from a local file - -.. note:: Signature-based authentication only works with local users. - - -Use signature-based authentication with Ansible -``````````````````````````````````````````````` -You need the following parameters with your ACI module(s) for it to work: - -.. code-block:: yaml - :emphasize-lines: 2,3 - - username: admin - private_key: pki/admin.key - certificate_name: admin # This could be left out ! - -or you can use the private key content: - -.. code-block:: yaml - :emphasize-lines: 2,3 - - username: admin - private_key: | - -----BEGIN PRIVATE KEY----- - <> - -----END PRIVATE KEY----- - certificate_name: admin # This could be left out ! - - -.. hint:: If you use a certificate name in ACI that matches the private key's basename, you can leave out the ``certificate_name`` parameter like the example above. - - -Using Ansible Vault to encrypt the private key -`````````````````````````````````````````````` -.. versionadded:: 2.8 - -To start, encrypt the private key and give it a strong password. - -.. code-block:: bash - - ansible-vault encrypt admin.key - -Use a text editor to open the private-key. You should have an encrypted cert now. - -.. code-block:: bash - - $ANSIBLE_VAULT;1.1;AES256 - 56484318584354658465121889743213151843149454864654151618131547984132165489484654 - 45641818198456456489479874513215489484843614848456466655432455488484654848489498 - .... - -Copy and paste the new encrypted cert into your playbook as a new variable. - -.. code-block:: yaml - - private_key: !vault | - $ANSIBLE_VAULT;1.1;AES256 - 56484318584354658465121889743213151843149454864654151618131547984132165489484654 - 45641818198456456489479874513215489484843614848456466655432455488484654848489498 - .... - -Use the new variable for the private_key: - -.. code-block:: yaml - - username: admin - private_key: "{{ private_key }}" - certificate_name: admin # This could be left out ! - -When running the playbook, use "--ask-vault-pass" to decrypt the private key. - -.. code-block:: bash - - ansible-playbook site.yaml --ask-vault-pass - - -More information -```````````````` -- Detailed information about Signature-based Authentication is available from `Cisco APIC Signature-Based Transactions `_. -- More information on Ansible Vault can be found on the :ref:`Ansible Vault ` page. - - -.. _aci_guide_rest: - -Using ACI REST with Ansible ---------------------------- -While already a lot of ACI modules exists in the Ansible distribution, and the most common actions can be performed with these existing modules, there's always something that may not be possible with off-the-shelf modules. - -The aci_rest module provides you with direct access to the APIC REST API and enables you to perform any task not already covered by the existing modules. This may seem like a complex undertaking, but you can generate the needed REST payload for any action performed in the ACI web interface effortlessly. - - -Built-in idempotency -.................... -Because the APIC REST API is intrinsically idempotent and can report whether a change was made, the aci_rest module automatically inherits both capabilities and is a first-class solution for automating your ACI infrastructure. As a result, users that require more powerful low-level access to their ACI infrastructure don't have to give up on idempotency and don't have to guess whether a change was performed when using the aci_rest module. - - -Using the aci_rest module -......................... -The aci_rest module accepts the native XML and JSON payloads, but additionally accepts inline YAML payload (structured like JSON). The XML payload requires you to use a path ending with ``.xml`` whereas JSON or YAML require the path to end with ``.json``. - -When you're making modifications, you can use the POST or DELETE methods, whereas doing just queries require the GET method. - -For example, if you would like to ensure a specific tenant exists on ACI, these below four examples are functionally identical: - -**XML** (Native ACI REST) - -.. code-block:: yaml - - - aci_rest: - host: my-apic-1 - private_key: pki/admin.key - - method: post - path: /api/mo/uni.xml - content: | - - -**JSON** (Native ACI REST) - -.. code-block:: yaml - - - aci_rest: - host: my-apic-1 - private_key: pki/admin.key - - method: post - path: /api/mo/uni.json - content: - { - "fvTenant": { - "attributes": { - "name": "customer-xyz", - "descr": "Customer XYZ" - } - } - } - -**YAML** (Ansible-style REST) - -.. code-block:: yaml - - - aci_rest: - host: my-apic-1 - private_key: pki/admin.key - - method: post - path: /api/mo/uni.json - content: - fvTenant: - attributes: - name: customer-xyz - descr: Customer XYZ - -**Ansible task** (Dedicated module) - -.. code-block:: yaml - - - aci_tenant: - host: my-apic-1 - private_key: pki/admin.key - - tenant: customer-xyz - description: Customer XYZ - state: present - - -.. hint:: The XML format is more practical when there is a need to template the REST payload (inline), but the YAML format is more convenient for maintaining your infrastructure-as-code and feels more naturally integrated with Ansible playbooks. The dedicated modules offer a more simple, abstracted, but also a more limited experience. Use what feels best for your use-case. - - -More information -................ -Plenty of resources exist to learn about ACI's APIC REST interface, we recommend the links below: - -- `The ACI collection on Ansible Galaxy `_ -- `APIC REST API Configuration Guide `_ -- Detailed guide on how the APIC REST API is designed and used, incl. many examples -- `APIC Management Information Model reference `_ -- Complete reference of the APIC object model -- `Cisco DevNet Learning Labs about ACI and REST `_ - - -.. _aci_guide_ops: - -Operational examples --------------------- -Here is a small overview of useful operational tasks to reuse in your playbooks. - -Feel free to contribute more useful snippets. - - -Waiting for all controllers to be ready -......................................... -You can use the below task after you started to build your APICs and configured the cluster to wait until all the APICs have come online. It will wait until the number of controllers equals the number listed in the ``apic`` inventory group. - -.. code-block:: yaml - - - name: Waiting for all controllers to be ready - aci_rest: - host: my-apic-1 - private_key: pki/admin.key - method: get - path: /api/node/class/topSystem.json?query-target-filter=eq(topSystem.role,"controller") - register: topsystem - until: topsystem|success and topsystem.totalCount|int >= groups['apic']|count >= 3 - retries: 20 - delay: 30 - - -Waiting for cluster to be fully-fit -................................... -The below example waits until the cluster is fully-fit. In this example you know the number of APICs in the cluster and you verify each APIC reports a 'fully-fit' status. - -.. code-block:: yaml - - - name: Waiting for cluster to be fully-fit - aci_rest: - host: my-apic-1 - private_key: pki/admin.key - method: get - path: /api/node/class/infraWiNode.json?query-target-filter=wcard(infraWiNode.dn,"topology/pod-1/node-1/av") - register: infrawinode - until: > - infrawinode|success and - infrawinode.totalCount|int >= groups['apic']|count >= 3 and - infrawinode.imdata[0].infraWiNode.attributes.health == 'fully-fit' and - infrawinode.imdata[1].infraWiNode.attributes.health == 'fully-fit' and - infrawinode.imdata[2].infraWiNode.attributes.health == 'fully-fit' - retries: 30 - delay: 30 - - -.. _aci_guide_errors: - -APIC error messages -------------------- -The following error messages may occur and this section can help you understand what exactly is going on and how to fix/avoid them. - - APIC Error 122: unknown managed object class 'polUni' - In case you receive this error while you are certain your aci_rest payload and object classes are seemingly correct, the issue might be that your payload is not in fact correct JSON (for example, the sent payload is using single quotes, rather than double quotes), and as a result the APIC is not correctly parsing your object classes from the payload. One way to avoid this is by using a YAML or an XML formatted payload, which are easier to construct correctly and modify later. - - - APIC Error 400: invalid data at line '1'. Attributes are missing, tag 'attributes' must be specified first, before any other tag - Although the JSON specification allows unordered elements, the APIC REST API requires that the JSON ``attributes`` element precede the ``children`` array or other elements. So you need to ensure that your payload conforms to this requirement. Sorting your dictionary keys will do the trick just fine. If you don't have any attributes, it may be necessary to add: ``attributes: {}`` as the APIC does expect the entry to precede any ``children``. - - - APIC Error 801: property descr of uni/tn-TENANT/ap-AP failed validation for value 'A "legacy" network' - Some values in the APIC have strict format-rules to comply to, and the internal APIC validation check for the provided value failed. In the above case, the ``description`` parameter (internally known as ``descr``) only accepts values conforming to Regex: ``[a-zA-Z0-9\\!#$%()*,-./:;@ _{|}~?&+]+``, in general it must not include quotes or square brackets. - - -.. _aci_guide_known_issues: - -Known issues ------------- -The aci_rest module is a wrapper around the APIC REST API. As a result any issues related to the APIC will be reflected in the use of this module. - -All below issues either have been reported to the vendor, and most can simply be avoided. - - Too many consecutive API calls may result in connection throttling - Starting with ACI v3.1 the APIC will actively throttle password-based authenticated connection rates over a specific threshold. This is as part of an anti-DDOS measure but can act up when using Ansible with ACI using password-based authentication. Currently, one solution is to increase this threshold within the nginx configuration, but using signature-based authentication is recommended. - - **NOTE:** It is advisable to use signature-based authentication with ACI as it not only prevents connection-throttling, but also improves general performance when using the ACI modules. - - - Specific requests may not reflect changes correctly (`#35401 `_) - There is a known issue where specific requests to the APIC do not properly reflect changed in the resulting output, even when we request those changes explicitly from the APIC. In one instance using the path ``api/node/mo/uni/infra.xml`` fails, where ``api/node/mo/uni/infra/.xml`` does work correctly. - - **NOTE:** A workaround is to register the task return values (for example, ``register: this``) and influence when the task should report a change by adding: ``changed_when: this.imdata != []``. - - - Specific requests are known to not be idempotent (`#35050 `_) - The behavior of the APIC is inconsistent to the use of ``status="created"`` and ``status="deleted"``. The result is that when you use ``status="created"`` in your payload the resulting tasks are not idempotent and creation will fail when the object was already created. However this is not the case with ``status="deleted"`` where such call to an non-existing object does not cause any failure whatsoever. - - **NOTE:** A workaround is to avoid using ``status="created"`` and instead use ``status="modified"`` when idempotency is essential to your workflow.. - - - Setting user password is not idempotent (`#35544 `_) - Due to an inconsistency in the APIC REST API, a task that sets the password of a locally-authenticated user is not idempotent. The APIC will complain with message ``Password history check: user dag should not use previous 5 passwords``. - - **NOTE:** There is no workaround for this issue. - - -.. _aci_guide_community: - -ACI Ansible community ---------------------- -If you have specific issues with the ACI modules, or a feature request, or you like to contribute to the ACI project by proposing changes or documentation updates, look at the Ansible Community wiki ACI page at: https://github.com/ansible/community/wiki/Network:-ACI - -You will find our roadmap, an overview of open ACI issues and pull-requests, and more information about who we are. If you have an interest in using ACI with Ansible, feel free to join! We occasionally meet online (on the #ansible-network chat channel, using Matrix at ansible.im or using IRC at `irc.libera.chat `_) to track progress and prepare for new Ansible releases. - - -.. seealso:: - - `ACI collection on Ansible Galaxy `_ - View the content tab for a complete list of supported ACI modules. - :ref:`Developing Cisco ACI modules ` - A walkthrough on how to develop new Cisco ACI modules to contribute back. - `ACI community `_ - The Ansible ACI community wiki page, includes roadmap, ideas and development documentation. - :ref:`network_guide` - A detailed guide on how to use Ansible for automating network infrastructure. - `Network Working Group `_ - The Ansible Network community page, includes contact information and meeting information. - `User Mailing List `_ - Have a question? Stop by the Google group! diff --git a/docs/docsite/rst/scenario_guides/guides.rst b/docs/docsite/rst/scenario_guides/guides.rst index 0919d1c44a0..6682cb36154 100644 --- a/docs/docsite/rst/scenario_guides/guides.rst +++ b/docs/docsite/rst/scenario_guides/guides.rst @@ -18,6 +18,5 @@ We are migrating these guides into collections. Please update your links for the :maxdepth: 1 :caption: Network Technology Guides - guide_aci guide_meraki guide_infoblox diff --git a/docs/docsite/rst/scenario_guides/network_guides.rst b/docs/docsite/rst/scenario_guides/network_guides.rst index 2b538ff05ed..96860a1366f 100644 --- a/docs/docsite/rst/scenario_guides/network_guides.rst +++ b/docs/docsite/rst/scenario_guides/network_guides.rst @@ -9,7 +9,6 @@ The guides in this section cover using Ansible with specific network technologie .. toctree:: :maxdepth: 1 - guide_aci guide_meraki guide_infoblox From 44d65652705a6067a8de30ee3a079291750914b3 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Wed, 13 Dec 2023 13:10:58 -0800 Subject: [PATCH 142/536] Add documentation about --exclude flag (#978) * Add documentation about --exclude flag * Added an example of --exclude flag in ansible-test integration sub-command * Fixed minor typos * Fixed grammatical errors Fixes: #977 Signed-off-by: Abhijeet Kasurde * Review request Signed-off-by: Abhijeet Kasurde --------- Signed-off-by: Abhijeet Kasurde --- .../rst/dev_guide/testing_integration.rst | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/docsite/rst/dev_guide/testing_integration.rst b/docs/docsite/rst/dev_guide/testing_integration.rst index 915281d02cb..73cad3c0a52 100644 --- a/docs/docsite/rst/dev_guide/testing_integration.rst +++ b/docs/docsite/rst/dev_guide/testing_integration.rst @@ -23,7 +23,7 @@ Some tests may require root. Quick Start =========== -It is highly recommended that you install and activate the ``argcomplete`` python package. +It is highly recommended that you install and activate the ``argcomplete`` Python package. It provides tab completion in ``bash`` for the ``ansible-test`` test runner. Configuration @@ -80,7 +80,13 @@ Run as follows for all POSIX platform tests executed by our CI system in a Fedor ansible-test integration shippable/ --docker fedora34 -You can target a specific tests as well, such as for individual modules: +You can exclude a specific test as well, such as for individual modules: + +.. code-block:: shell-session + + ansible-test integration --exclude git + +You can target a specific test as well, such as for individual modules: .. code-block:: shell-session @@ -142,7 +148,7 @@ Run the Windows tests executed by our CI system: ansible-test windows-integration -v shippable/ Tests in containers -========================== +=================== If you have a Linux system with Docker or Podman installed, running integration tests using the same containers used by the Ansible continuous integration (CI) system is recommended. @@ -190,21 +196,21 @@ The list is under the **target docker images and supported python version** head Other configuration for Cloud Tests =================================== -In order to run some tests, you must provide access credentials in a file named +To run some tests, you must provide access credentials in a file named ``cloud-config-aws.yml`` or ``cloud-config-cs.ini`` in the test/integration -directory. Corresponding .template files are available for for syntax help. The newer AWS -tests now use the file test/integration/cloud-config-aws.yml +directory. Corresponding ``.template`` files are available for syntax help. The newer AWS +tests now use the file ``test/integration/cloud-config-aws.yml``. IAM policies for AWS ==================== -Ansible needs fairly wide ranging powers to run the tests in an AWS account. This rights can be provided to a dedicated user. These need to be configured before running the test. +Ansible needs fairly wide ranging powers to run the tests in an AWS account. These rights can be provided to a dedicated user. These need to be configured before running the test. testing-policies ---------------- The GitHub repository `mattclay/aws-terminator `_ -contains two sets of policies used for all existing AWS module integratoin tests. +contains two sets of policies used for all existing AWS module integration tests. The `hacking/aws_config/setup_iam.yml` playbook can be used to setup two groups: - `ansible-integration-ci` will have the policies applied necessary to run any @@ -217,7 +223,7 @@ The `hacking/aws_config/setup_iam.yml` playbook can be used to setup two groups: Once the groups have been created, you'll need to create a user and make the user a member of these groups. The policies are designed to minimize the rights of that user. Please note that while this policy does limit the user to one region, this does not fully restrict the user (primarily due to the limitations of the Amazon ARN -notation). The user will still have wide privileges for viewing account definitions, and will also able to manage +notation). The user will still have wide privileges for viewing account definitions, and will also be able to manage some resources that are not related to testing (for example, AWS lambdas with different names). Tests should not be run in a primary production account in any case. From d6a9e394dc52ab600ccde5e4d6efd7ca0c188998 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 13 Dec 2023 22:16:51 +0100 Subject: [PATCH 143/536] Collection requirements: add seealso with link to Collection creator path (#976) --- .../collection_contributors/collection_requirements.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index f50338137a8..d3f0a1a8a3e 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -528,3 +528,8 @@ 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, see `Adding a new collection `_ in the `ansible-build-data repository `_'s README. + +.. seealso:: + + :ref:`developing_collections_path` + A consistent overview of the Ansible collection creator journey From 44cfd929000b9b86799cdd5e516df183a4d437ee Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 14 Dec 2023 13:53:37 -0500 Subject: [PATCH 144/536] remove remaining network scenario guides (#986) --- .../rst/scenario_guides/guide_infoblox.rst | 292 ------------------ .../rst/scenario_guides/guide_meraki.rst | 193 ------------ docs/docsite/rst/scenario_guides/guides.rst | 6 - .../rst/scenario_guides/network_guides.rst | 15 - .../rst/scenario_guides/scenario_template.rst | 53 ---- 5 files changed, 559 deletions(-) delete mode 100644 docs/docsite/rst/scenario_guides/guide_infoblox.rst delete mode 100644 docs/docsite/rst/scenario_guides/guide_meraki.rst delete mode 100644 docs/docsite/rst/scenario_guides/network_guides.rst delete mode 100644 docs/docsite/rst/scenario_guides/scenario_template.rst diff --git a/docs/docsite/rst/scenario_guides/guide_infoblox.rst b/docs/docsite/rst/scenario_guides/guide_infoblox.rst deleted file mode 100644 index c7227c50b53..00000000000 --- a/docs/docsite/rst/scenario_guides/guide_infoblox.rst +++ /dev/null @@ -1,292 +0,0 @@ -.. _nios_guide: - -************************ - Infoblox Guide -************************ - -.. contents:: Topics - -This guide describes how to use Ansible with the Infoblox Network Identity Operating System (NIOS). With Ansible integration, you can use Ansible playbooks to automate Infoblox Core Network Services for IP address management (IPAM), DNS, and inventory tracking. - -You can review simple example tasks in the documentation for any of the :ref:`NIOS modules ` or look at the `Use cases with modules`_ section for more elaborate examples. See the `Infoblox `_ website for more information on the Infoblox product. - -.. note:: You can retrieve most of the example playbooks used in this guide from the `network-automation/infoblox_ansible `_ GitHub repository. - -Prerequisites -============= -Before using Ansible ``nios`` modules with Infoblox, you must install the ``infoblox-client`` on your Ansible control node: - -.. code-block:: bash - - $ sudo pip install infoblox-client - -.. note:: - You need an NIOS account with the WAPI feature enabled to use Ansible with Infoblox. - -.. _nios_credentials: - -Credentials and authenticating -============================== - -To use Infoblox ``nios`` modules in playbooks, you need to configure the credentials to access your Infoblox system. The examples in this guide use credentials stored in ``/group_vars/nios.yml``. Replace these values with your Infoblox credentials: - -.. code-block:: yaml - - --- - nios_provider: - host: 192.0.0.2 - username: admin - password: ansible - -NIOS lookup plugins -=================== - -Ansible includes the following lookup plugins for NIOS: - -- :ref:`nios ` Uses the Infoblox WAPI API to fetch NIOS specified objects, for example network views, DNS views, and host records. -- :ref:`nios_next_ip ` Provides the next available IP address from a network. You'll see an example of this in `Creating a host record`_. -- :ref:`nios_next_network ` - Returns the next available network range for a network-container. - -You must run the NIOS lookup plugins locally by specifying ``connection: local``. See :ref:`lookup plugins ` for more detail. - - -Retrieving all network views ----------------------------- - -To retrieve all network views and save them in a variable, use the :ref:`set_fact ` module with the :ref:`nios ` lookup plugin: - -.. code-block:: yaml - - --- - - hosts: nios - connection: local - tasks: - - name: fetch all networkview objects - set_fact: - networkviews: "{{ lookup('nios', 'networkview', provider=nios_provider) }}" - - - name: check the networkviews - debug: - var: networkviews - - -Retrieving a host record ------------------------- - -To retrieve a set of host records, use the ``set_fact`` module with the ``nios`` lookup plugin and include a filter for the specific hosts you want to retrieve: - -.. code-block:: yaml - - --- - - hosts: nios - connection: local - tasks: - - name: fetch host leaf01 - set_fact: - host: "{{ lookup('nios', 'record:host', filter={'name': 'leaf01.ansible.com'}, provider=nios_provider) }}" - - - name: check the leaf01 return variable - debug: - var: host - - - name: debug specific variable (ipv4 address) - debug: - var: host.ipv4addrs[0].ipv4addr - - - name: fetch host leaf02 - set_fact: - host: "{{ lookup('nios', 'record:host', filter={'name': 'leaf02.ansible.com'}, provider=nios_provider) }}" - - - name: check the leaf02 return variable - debug: - var: host - - -If you run this ``get_host_record.yml`` playbook, you should see results similar to the following: - -.. code-block:: none - - $ ansible-playbook get_host_record.yml - - PLAY [localhost] *************************************************************************************** - - TASK [fetch host leaf01] ****************************************************************************** - ok: [localhost] - - TASK [check the leaf01 return variable] ************************************************************* - ok: [localhost] => { - < ...output shortened...> - "host": { - "ipv4addrs": [ - { - "configure_for_dhcp": false, - "host": "leaf01.ansible.com", - } - ], - "name": "leaf01.ansible.com", - "view": "default" - } - } - - TASK [debug specific variable (ipv4 address)] ****************************************************** - ok: [localhost] => { - "host.ipv4addrs[0].ipv4addr": "192.168.1.11" - } - - TASK [fetch host leaf02] ****************************************************************************** - ok: [localhost] - - TASK [check the leaf02 return variable] ************************************************************* - ok: [localhost] => { - < ...output shortened...> - "host": { - "ipv4addrs": [ - { - "configure_for_dhcp": false, - "host": "leaf02.example.com", - "ipv4addr": "192.168.1.12" - } - ], - } - } - - PLAY RECAP ****************************************************************************************** - localhost : ok=5 changed=0 unreachable=0 failed=0 - -The output above shows the host record for ``leaf01.ansible.com`` and ``leaf02.ansible.com`` that were retrieved by the ``nios`` lookup plugin. This playbook saves the information in variables which you can use in other playbooks. This allows you to use Infoblox as a single source of truth to gather and use information that changes dynamically. See :ref:`playbooks_variables` for more information on using Ansible variables. See the :ref:`nios ` examples for more data options that you can retrieve. - -You can access these playbooks at `Infoblox lookup playbooks `_. - -Use cases with modules -====================== - -You can use the ``nios`` modules in tasks to simplify common Infoblox workflows. Be sure to set up your :ref:`NIOS credentials` before following these examples. - -Configuring an IPv4 network ---------------------------- - -To configure an IPv4 network, use the :ref:`nios_network ` module: - -.. code-block:: yaml - - --- - - hosts: nios - connection: local - tasks: - - name: Create a network on the default network view - nios_network: - network: 192.168.100.0/24 - comment: sets the IPv4 network - options: - - name: domain-name - value: ansible.com - state: present - provider: "{{nios_provider}}" - -Notice the last parameter, ``provider``, uses the variable ``nios_provider`` defined in the ``group_vars/`` directory. - -Creating a host record ----------------------- - -To create a host record named `leaf03.ansible.com` on the newly-created IPv4 network: - -.. code-block:: yaml - - --- - - hosts: nios - connection: local - tasks: - - name: configure an IPv4 host record - nios_host_record: - name: leaf03.ansible.com - ipv4addrs: - - ipv4addr: - "{{ lookup('nios_next_ip', '192.168.100.0/24', provider=nios_provider)[0] }}" - state: present - provider: "{{nios_provider}}" - -Notice the IPv4 address in this example uses the :ref:`nios_next_ip ` lookup plugin to find the next available IPv4 address on the network. - -Creating a forward DNS zone ---------------------------- - -To configure a forward DNS zone use, the ``nios_zone`` module: - -.. code-block:: yaml - - --- - - hosts: nios - connection: local - tasks: - - name: Create a forward DNS zone called ansible-test.com - nios_zone: - name: ansible-test.com - comment: local DNS zone - state: present - provider: "{{ nios_provider }}" - -Creating a reverse DNS zone ---------------------------- - -To configure a reverse DNS zone: - -.. code-block:: yaml - - --- - - hosts: nios - connection: local - tasks: - - name: configure a reverse mapping zone on the system using IPV6 zone format - nios_zone: - name: 100::1/128 - zone_format: IPV6 - state: present - provider: "{{ nios_provider }}" - -Dynamic inventory script -======================== - -You can use the Infoblox dynamic inventory script to import your network node inventory with Infoblox NIOS. To gather the inventory from Infoblox, you need two files: - -- `infoblox.yaml `_ - A file that specifies the NIOS provider arguments and optional filters. - -- `infoblox.py `_ - The python script that retrieves the NIOS inventory. - -.. note:: - - Please note that the inventory script only works when Ansible 2.9, 2.10 or 3 have been installed. The inventory script will eventually be removed from `community.general `_, and will not work if `community.general` is only installed with `ansible-galaxy collection install`. Please use the inventory plugin from `infoblox.nios_modules `_ instead. - -To use the Infoblox dynamic inventory script: - -#. Download the ``infoblox.yaml`` file and save it in the ``/etc/ansible`` directory. - -#. Modify the ``infoblox.yaml`` file with your NIOS credentials. - -#. Download the ``infoblox.py`` file and save it in the ``/etc/ansible/hosts`` directory. - -#. Change the permissions on the ``infoblox.py`` file to make the file an executable: - -.. code-block:: bash - - $ sudo chmod +x /etc/ansible/hosts/infoblox.py - -You can optionally use ``./infoblox.py --list`` to test the script. After a few minutes, you should see your Infoblox inventory in JSON format. You can explicitly use the Infoblox dynamic inventory script as follows: - -.. code-block:: bash - - $ ansible -i infoblox.py all -m ping - -You can also implicitly use the Infoblox dynamic inventory script by including it in your inventory directory (``etc/ansible/hosts`` by default). See :ref:`dynamic_inventory` for more details. - -.. seealso:: - - `Infoblox website `_ - The Infoblox website - `Infoblox and Ansible Deployment Guide `_ - The deployment guide for Ansible integration provided by Infoblox. - `Infoblox Integration in Ansible 2.5 `_ - Ansible blog post about Infoblox. - :ref:`Ansible NIOS modules ` - The list of supported NIOS modules, with examples. - `Infoblox Ansible Examples `_ - Infoblox example playbooks. diff --git a/docs/docsite/rst/scenario_guides/guide_meraki.rst b/docs/docsite/rst/scenario_guides/guide_meraki.rst deleted file mode 100644 index a99e569d0e2..00000000000 --- a/docs/docsite/rst/scenario_guides/guide_meraki.rst +++ /dev/null @@ -1,193 +0,0 @@ -.. _meraki_guide: - -****************** -Cisco Meraki Guide -****************** - -.. contents:: - :local: - - -.. _meraki_guide_intro: - -What is Cisco Meraki? -===================== - -Cisco Meraki is an easy-to-use, cloud-based, network infrastructure platform for enterprise environments. While most network hardware uses command-line interfaces (CLIs) for configuration, Meraki uses an easy-to-use Dashboard hosted in the Meraki cloud. No on-premises management hardware or software is required - only the network infrastructure to run your business. - -MS Switches ------------ - -Meraki MS switches come in multiple flavors and form factors. Meraki switches support 10/100/1000/10000 ports, as well as Cisco's mGig technology for 2.5/5/10Gbps copper connectivity. 8, 24, and 48 port flavors are available with PoE (802.3af/802.3at/UPoE) available on many models. - -MX Firewalls ------------- - -Meraki's MX firewalls support full layer 3-7 deep packet inspection. MX firewalls are compatible with a variety of VPN technologies including IPSec, SSL VPN, and Meraki's easy-to-use AutoVPN. - -MR Wireless Access Points -------------------------- - -MR access points are enterprise-class, high-performance access points for the enterprise. MR access points have MIMO technology and integrated beamforming built-in for high performance applications. BLE allows for advanced location applications to be developed with no on-premises analytics platforms. - -Using the Meraki modules -======================== - -Meraki modules provide a user-friendly interface to manage your Meraki environment using Ansible. For example, details about SNMP settings for a particular organization can be discovered using the module `meraki_snmp `. - -.. code-block:: yaml - - - name: Query SNMP settings - meraki_snmp: - api_key: abc123 - org_name: AcmeCorp - state: query - delegate_to: localhost - -Information about a particular object can be queried. For example, the `meraki_admin ` module supports - -.. code-block:: yaml - - - name: Gather information about Jane Doe - meraki_admin: - api_key: abc123 - org_name: AcmeCorp - state: query - email: janedoe@email.com - delegate_to: localhost - -Common Parameters -================= - -All Ansible Meraki modules support the following parameters which affect communication with the Meraki Dashboard API. Most of these should only be used by Meraki developers and not the general public. - - host - Hostname or IP of Meraki Dashboard. - - use_https - Specifies whether communication should be over HTTPS. (Defaults to ``true``) - - use_proxy - Whether to use a proxy for any communication. - - validate_certs - Determine whether certificates should be validated or trusted. (Defaults to ``true``) - -These are the common parameters which are used for most every module. - - org_name - Name of organization to perform actions in. - - org_id - ID of organization to perform actions in. - - net_name - Name of network to perform actions in. - - net_id - ID of network to perform actions in. - - state - General specification of what action to take. ``query`` does lookups. ``present`` creates or edits. ``absent`` deletes. - -.. hint:: Use the ``org_id`` and ``net_id`` parameters when possible. ``org_name`` and ``net_name`` require additional behind-the-scenes API calls to learn the ID values. ``org_id`` and ``net_id`` will perform faster. - -Meraki Authentication -===================== - -All API access with the Meraki Dashboard requires an API key. An API key can be generated from the organization's settings page. Each play in a playbook requires the ``api_key`` parameter to be specified. - -The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :ref:`playbooks_vault` for more information. - -Meraki's API returns a 404 error if the API key is not correct. It does not provide any specific error saying the key is incorrect. If you receive a 404 error, check the API key first. - -Returned Data Structures -======================== - -Meraki and its related Ansible modules return most information in the form of a list. For example, this is returned information by ``meraki_admin`` querying administrators. It returns a list even though there's only one. - -.. code-block:: json - - [ - { - "orgAccess": "full", - "name": "John Doe", - "tags": [], - "networks": [], - "email": "john@doe.com", - "id": "12345677890" - } - ] - -Handling Returned Data -====================== - -Since Meraki's response data uses lists instead of properly keyed dictionaries for responses, certain strategies should be used when querying data for particular information. For many situations, use the ``selectattr()`` Jinja2 function. - -Merging Existing and New Data -============================= - -Ansible's Meraki modules do not allow for manipulating data. For example, you may need to insert a rule in the middle of a firewall ruleset. Ansible and the Meraki modules lack a way to directly merge to manipulate data. However, a playlist can use a few tasks to split the list where you need to insert a rule and then merge them together again with the new rule added. The steps involved are as follows: - -1. Create blank "front" and "back" lists. - :: - - vars: - - front_rules: [] - - back_rules: [] -2. Get existing firewall rules from Meraki and create a new variable. - :: - - - name: Get firewall rules - meraki_mx_l3_firewall: - auth_key: abc123 - org_name: YourOrg - net_name: YourNet - state: query - delegate_to: localhost - register: rules - - set_fact: - original_ruleset: '{{rules.data}}' -3. Write the new rule. The new rule needs to be in a list so it can be merged with other lists in an upcoming step. The blank `-` puts the rule in a list so it can be merged. - :: - - - set_fact: - new_rule: - - - - comment: Block traffic to server - src_cidr: 192.0.1.0/24 - src_port: any - dst_cidr: 192.0.1.2/32 - dst_port: any - protocol: any - policy: deny -4. Split the rules into two lists. This assumes the existing ruleset is 2 rules long. - :: - - - set_fact: - front_rules: '{{front_rules + [ original_ruleset[:1] ]}}' - - set_fact: - back_rules: '{{back_rules + [ original_ruleset[1:] ]}}' -5. Merge rules with the new rule in the middle. - :: - - - set_fact: - new_ruleset: '{{front_rules + new_rule + back_rules}}' -6. Upload new ruleset to Meraki. - :: - - - name: Set two firewall rules - meraki_mx_l3_firewall: - auth_key: abc123 - org_name: YourOrg - net_name: YourNet - state: present - rules: '{{ new_ruleset }}' - delegate_to: localhost - -Error Handling -============== - -Ansible's Meraki modules will often fail if improper or incompatible parameters are specified. However, there will likely be scenarios where the module accepts the information but the Meraki API rejects the data. If this happens, the error will be returned in the ``body`` field for HTTP status of 400 return code. - -Meraki's API returns a 404 error if the API key is not correct. It does not provide any specific error saying the key is incorrect. If you receive a 404 error, check the API key first. 404 errors can also occur if improper object IDs (ex. ``org_id``) are specified. diff --git a/docs/docsite/rst/scenario_guides/guides.rst b/docs/docsite/rst/scenario_guides/guides.rst index 6682cb36154..cea3d45b9e5 100644 --- a/docs/docsite/rst/scenario_guides/guides.rst +++ b/docs/docsite/rst/scenario_guides/guides.rst @@ -14,9 +14,3 @@ We are migrating these guides into collections. Please update your links for the :ref:`ansible_collections.amazon.aws.docsite.aws_intro` -.. toctree:: - :maxdepth: 1 - :caption: Network Technology Guides - - guide_meraki - guide_infoblox diff --git a/docs/docsite/rst/scenario_guides/network_guides.rst b/docs/docsite/rst/scenario_guides/network_guides.rst deleted file mode 100644 index 96860a1366f..00000000000 --- a/docs/docsite/rst/scenario_guides/network_guides.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _network_guides: - -************************* -Network Technology Guides -************************* - -The guides in this section cover using Ansible with specific network technologies. They explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features. - -.. toctree:: - :maxdepth: 1 - - guide_meraki - guide_infoblox - -To learn more about Network Automation with Ansible, see :ref:`network_getting_started` and :ref:`network_advanced`. diff --git a/docs/docsite/rst/scenario_guides/scenario_template.rst b/docs/docsite/rst/scenario_guides/scenario_template.rst deleted file mode 100644 index 14695bed648..00000000000 --- a/docs/docsite/rst/scenario_guides/scenario_template.rst +++ /dev/null @@ -1,53 +0,0 @@ -:orphan: - -.. _scenario_template: - -************************************* -Sample scenario for Ansible platforms -************************************* - -*Use this ``rst`` file as a starting point to create a scenario guide for your platform. The sections below are suggestions on what should be in a scenario guide.* - -Introductory paragraph. - -.. contents:: - :local: - -Prerequisites -============= - -Describe the requirements and assumptions for this scenario. This should include applicable subsections for hardware, software, and any other caveats to using the scenarios in this guide. - -Credentials and authenticating -============================== - -Describe credential requirements and how to authenticate to this platform. - -Using dynamic inventory -========================= - -If applicable, describe how to use a dynamic inventory plugin for this platform. - - -Example description -=================== - -Description and code here. Change the section header to something descriptive about this example, such as "Renaming a virtual machine". The goal is that this is the text someone would search for to find your example. - - -Example output --------------- - -What the user should expect to see. - - -Troubleshooting ---------------- - -What to look for if it breaks. - - -Conclusion and where to go next -=============================== - -Recap of important points. For more information please see: links. From 6e0d206ee39e7f242585d0521fccb078eebff377 Mon Sep 17 00:00:00 2001 From: Akira Yokochi Date: Thu, 21 Dec 2023 05:38:18 +0900 Subject: [PATCH 145/536] Fix argument_specs.yml example (#956) --- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 950db9d570b..316d164c729 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -371,7 +371,8 @@ Sample specification - Here we can describe what this entrypoint does in lengthy words. - Every new list item is a new paragraph. You can have multiple sentences per paragraph. - author: Daniel Ziegenberg + author: + - Daniel Ziegenberg options: myapp_int: type: "int" @@ -413,6 +414,7 @@ Sample specification - "grains" - "meat" required: false + description: "A string value with a limited list of allowed choices." myapp_food_boiling_required: type: "bool" @@ -462,6 +464,8 @@ Sample specification # roles/myapp/tasks/alternate.yml entry point alternate: short_description: Alternate entry point for the myapp role + description: + - This is the alternate entrypoint for the C(myapp) role. version_added: 1.2.0 options: myapp_int: From ea56d9ddf91d9cae02bd8751c01650c559e1005f Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sat, 23 Dec 2023 21:13:17 -0600 Subject: [PATCH 146/536] ci: refresh dev dependencies (#961) --- tests/formatters.txt | 10 +++++----- tests/static.txt | 2 +- tests/typing.txt | 10 +++++----- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 18f8c1b047d..ebaeeb4b99e 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,21 +4,21 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==23.11.0 +black==23.12.1 # via -r tests/formatters.in click==8.1.7 # via black -isort==5.12.0 +isort==5.13.2 # via -r tests/formatters.in mypy-extensions==1.0.0 # via black packaging==23.2 # via black -pathspec==0.11.2 +pathspec==0.12.1 # via black -platformdirs==4.0.0 +platformdirs==4.1.0 # via black tomli==2.0.1 # via black -typing-extensions==4.8.0 +typing-extensions==4.9.0 # via black diff --git a/tests/static.txt b/tests/static.txt index 4f763f33ffe..d4498020d51 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.6 +ruff==0.1.9 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 6b867b1d82f..33bc13c6926 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/typing.txt --strip-extras tests/typing.in # -argcomplete==3.1.6 +argcomplete==3.2.1 # via nox certifi==2023.11.17 # via requests @@ -24,7 +24,7 @@ cryptography==41.0.7 # via pyjwt deprecated==1.2.14 # via pygithub -distlib==0.3.7 +distlib==0.3.8 # via virtualenv filelock==3.13.1 # via virtualenv @@ -34,7 +34,7 @@ jinja2==3.1.2 # via -r tests/../hacking/pr_labeler/requirements.txt markupsafe==2.1.3 # via jinja2 -mypy==1.7.1 +mypy==1.8.0 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy @@ -42,7 +42,7 @@ nox==2023.4.22 # via -r tests/typing.in packaging==23.2 # via nox -platformdirs==4.0.0 +platformdirs==4.1.0 # via virtualenv pycparser==2.21 # via cffi @@ -64,7 +64,7 @@ tomli==2.0.1 # via mypy typer==0.9.0 # via -r tests/../hacking/pr_labeler/requirements.txt -typing-extensions==4.8.0 +typing-extensions==4.9.0 # via # codeowners # mypy From 9eafad92f36c04ec110788d8b148179987d6c579 Mon Sep 17 00:00:00 2001 From: Sumanth Lingappa <42572246+sumanth-lingappa@users.noreply.github.com> Date: Tue, 2 Jan 2024 20:21:59 +0530 Subject: [PATCH 147/536] corrected `test/` folder to `tests/` (#993) --- docs/docsite/rst/dev_guide/testing_integration.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/dev_guide/testing_integration.rst b/docs/docsite/rst/dev_guide/testing_integration.rst index 73cad3c0a52..7b244d79f5e 100644 --- a/docs/docsite/rst/dev_guide/testing_integration.rst +++ b/docs/docsite/rst/dev_guide/testing_integration.rst @@ -53,7 +53,7 @@ Making your own version of ``integration_config.yml`` can allow for setting some tunable parameters to help run the tests better in your environment. Some tests (for example, cloud tests) will only run when access credentials are provided. For more information about supported credentials, refer to the various ``cloud-config-*.template`` -files in the ``test/integration/`` directory. +files in the ``tests/integration/`` directory. Prerequisites ============= @@ -197,9 +197,9 @@ Other configuration for Cloud Tests =================================== To run some tests, you must provide access credentials in a file named -``cloud-config-aws.yml`` or ``cloud-config-cs.ini`` in the test/integration +``cloud-config-aws.yml`` or ``cloud-config-cs.ini`` in the tests/integration directory. Corresponding ``.template`` files are available for syntax help. The newer AWS -tests now use the file ``test/integration/cloud-config-aws.yml``. +tests now use the file ``tests/integration/cloud-config-aws.yml``. IAM policies for AWS ==================== From 0ef3fc9c28d0f1128e0e4028dd2576c3f5aa0e5b Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 2 Jan 2024 18:35:55 +0100 Subject: [PATCH 148/536] Document collection naming (#987) * Document collection naming. * Fix RST link title. --- .../developing_collections_creating.rst | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/docsite/rst/dev_guide/developing_collections_creating.rst b/docs/docsite/rst/dev_guide/developing_collections_creating.rst index 7b2a85093cd..8b1a9b1f873 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_creating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_creating.rst @@ -17,6 +17,33 @@ A user can then install your collection on their systems. :local: :depth: 2 +Naming your collection +====================== + +Collection names consist of a namespace and a name, separated by a period (``.``). Both namespace and name should be valid Python identifiers. This means that they should consist of ASCII letters, digits, and underscores. + +.. note:: + + Usually namespaces and names use lower-case letters, digits, and underscores, but no upper-case letters. + +You should make sure that the namespace you use is not registered by someone else by checking on `Ansible Galaxy's namespace list `__. If you chose a namespace or even a full collection name that collides with another collection on Galaxy, it can happen that if you or someone else runs ``ansible-galaxy collection install`` with your collection name, you end up with another collection. Even if the namespace currently does not exist, it could be created later by someone else. + +If you want to request a new namespace on Ansible Galaxy, `create an issue on github.com/ansible/galaxy `__. + +There are a few special namespaces: + +:ansible: + + The `ansible namespace `__ is owned by Red Hat and reserved for official Ansible collections. Two special members are the synthetic ``ansible.builtin`` and ``ansible.legacy`` collections. These cannot be found on Ansible Galaxy, but are built-in into ansible-core. + +:community: + + The `community namespace `__ is owned by the Ansible community. Collections from this namespace generally live in the `GitHub ansible-collection organization `__. If you want to create a collection in this namespace, it is best to `create an issue in github.com/ansible-collections/overview `__. + +:local: + + The `local namespace `__ does not contain any collection on Ansible Galaxy, and the intention is that this will never change. You can use the ``local`` namespace for collections that are locally on your machine or locally in your git repositories, without having to fear collisions with actually existing collections on Ansible Galaxy. + .. _creating_collections_skeleton: Creating a collection skeleton From 174433647983b310e727297c4fce6d24a7fd5b77 Mon Sep 17 00:00:00 2001 From: JaroslavKlech Date: Tue, 2 Jan 2024 11:25:48 -0800 Subject: [PATCH 149/536] Adds note for more details about variable precedence (#930) * Adds note for more details about variable precedence * Applies SME review feedback * fixup! Applies SME review feedback --------- Co-authored-by: Jaroslav Klech --- docs/docsite/rst/inventory_guide/intro_inventory.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index 93c36dd1126..fb6d007c326 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -523,6 +523,8 @@ By default, variables are merged/flattened to the specific host before a play is By default, Ansible merges groups at the same parent/child level in ASCII order, and variables from the last group loaded overwrite variables from the previous groups. For example, an ``a_group`` will be merged with ``b_group`` and ``b_group`` vars that match will overwrite the ones in ``a_group``. +.. note:: Ansible merges variables from different sources and applies precedence to some variables over others according to a set of rules. For example, variables that occur higher in an inventory can override variables that occur lower in the inventory. See :ref:`ansible_variable_precedence` for more information. + You can change this behavior by setting the group variable ``ansible_group_priority`` to change the merge order for groups of the same level (after the parent/child order is resolved). The larger the number, the later it will be merged, giving it higher priority. This variable defaults to ``1`` if not set. For example: .. code-block:: yaml From c90275c1d4e7d65866f9ac077331806fdd515f1a Mon Sep 17 00:00:00 2001 From: Prakyath Raj Date: Fri, 5 Jan 2024 01:47:06 +0530 Subject: [PATCH 150/536] Fixed DCO file link (#1005) --- docs/docsite/rst/community/developer_certificate_of_origin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/developer_certificate_of_origin.rst b/docs/docsite/rst/community/developer_certificate_of_origin.rst index 1893c143852..8c0a5e89d51 100644 --- a/docs/docsite/rst/community/developer_certificate_of_origin.rst +++ b/docs/docsite/rst/community/developer_certificate_of_origin.rst @@ -7,5 +7,5 @@ Developer Certificate Of Origin By contributing to this project you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the -contribution. See the `DCO file `_ +contribution. See the `DCO file `_ file for details. From c970e0452ad3983cb9b76e0edb0d7aa537bf644f Mon Sep 17 00:00:00 2001 From: Kelechi Ebiri <56020538+TG199@users.noreply.github.com> Date: Thu, 4 Jan 2024 21:17:56 +0100 Subject: [PATCH 151/536] docs: Document removal of ConfigureRemotingForAnsible.ps1 #794 (#984) --- docs/docsite/rst/os_guide/windows_setup.rst | 6 +++++ examples/README.md | 15 ++++++++++++ examples/scripts/README.md | 26 +++++++++++++++++++++ 3 files changed, 47 insertions(+) create mode 100644 examples/README.md create mode 100644 examples/scripts/README.md diff --git a/docs/docsite/rst/os_guide/windows_setup.rst b/docs/docsite/rst/os_guide/windows_setup.rst index 38003b6d4e3..c31d20138f4 100644 --- a/docs/docsite/rst/os_guide/windows_setup.rst +++ b/docs/docsite/rst/os_guide/windows_setup.rst @@ -92,6 +92,12 @@ WinRM Setup ``````````` You need to configure the WinRM service so that Ansible can connect to it. There are two main components of the WinRM service that govern how Ansible can interface with the Windows host: the ``listener`` and the ``service`` configuration settings. +.. Note:: + The script for setting up this service is `available to download on GitHub `_. + Reason being that using it can cause several issues for the user. Chances are it will be completely taken down in the future. + + + .. _winrm_listener: WinRM Listener diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000000..307066dd8af --- /dev/null +++ b/examples/README.md @@ -0,0 +1,15 @@ +# Update on maintenance of scripts `ConfigureRemotingForAnsible.ps1` + +## Important Notice +This is to notify users that the aforementioned script is currently unmaintained and may be removed in the future. Please read this notice carefully before using the script. + +### Why Unmaintained ? +The script is designed to check the current WinRM (PS Remoting) configuration and make the necessary changes to allow Ansible to connect, authenticate and execute PowerShell commands. As of now, Ansible can connect to Windows host that has already run `Enable-PSRemoting` in PowerShell already. + +There's really no need to use this script at all as the defaults in Windows are just fine. Also, using the scripts may result in potential security issues. + + + +### Use at Your Own Risk +- The script is provided as-is, without ongoing support or updates. +- Use them at your own risk, and carefully consider the potential consequences. \ No newline at end of file diff --git a/examples/scripts/README.md b/examples/scripts/README.md new file mode 100644 index 00000000000..63c3912fe10 --- /dev/null +++ b/examples/scripts/README.md @@ -0,0 +1,26 @@ +# Cautionary Note on ConfigureRemotingForAnsible.ps1 +`ConfigureRemotingForAnsible.ps1` is a script designed to check the current WinRM (PS Remoting) configuration and makes the necessary changes to allow Ansible to connect, authenticate and execute PowerShell commands. However, recent user experiences have raised concerns about its reliability and potential for causing issues. + + +**Warning:** +We strongly advised against using `ConfigureRemotingForAnsible.ps1` due to several potential issues which are: + +* It enables Basic authentication: + + * Windows has this disabled by default because it is not secure when running over HTTP. + * Over HTTP this is an issue because the messages are not encrypted, even the credentials are just base64 encoded + * Anyone sniffing the network will be able to get your credentials as well as any data that Ansible sends to the remote host and what it receives back. + * Requires HTTPS to be set up to be secure, even then it's problematic because it only supports local account and not domain accounts. +* It creates a self signed certificate + * Fine for basic testing but in a domain environment you should be using your own CA issued certificates for the host. + * Also it creates both a HTTP and HTTPS listener, where only the latter is enabled by default. Not really an issue but some places like to reduce the amount of inbound entrypoints as much as they can. +* It allows WinRM traffic in all network profiles + * Usually you want to restrict traffic to just the network/profile you will be managing it from. + +A lot of these settings are done (Basic auth and HTTPS with self signed certificate) because it was created in a time where the WinRM support on Python was very basic and barebones. There was no *NTLM* or *Kerberos* support, no message encryption over HTTP. This is no longer the case and the Python WinRM library that is used supports the full gauntlet of authentication protocols WinRM supports as well as message encryption when it's run over HTTP. In fact, Ansible has been able to connect to a Windows host that has already run `Enable-PSRemoting` in PowerShell already. There's really no need to use this script at all as the defaults in Windows are just fine. + +The reason why we still have this script is simple, people still use it and have their scripts set to download it directly from GitHub. If we were to remove it, or even just some of the default behaviour to be a bit more secure we will be breaking plenty of scripts that still rely on its current behaviour. + + +**TLDR:** We are trying to discourage users from using the script as much as we can. It was created for a time where Ansible couldn't work with the default WinRM settings. If you do wish to use it then take a copy of the script and only run the parts you need, i.e. self signed certificates and so on. + From 362f1622c33031a3b2df9131fe2e1a9c8efe66cb Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 7 Jan 2024 17:03:41 -0600 Subject: [PATCH 152/536] ci: refresh dev dependencies (#1021) --- tests/static.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/static.txt b/tests/static.txt index d4498020d51..68d776260c2 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.9 +ruff==0.1.11 # via -r tests/static.in From 2d1ed766f9f6c652e144fdd7cbe0421bfd40e104 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Mon, 8 Jan 2024 10:58:08 -0500 Subject: [PATCH 153/536] convert core docs to use Ansible sphinx theme (#922) * convert core docs to use Ansible sphinx theme * add back _static dir --- docs/docsite/_static/.keep | 0 docs/docsite/_static/css/core-color-scheme.css | 17 ----------------- docs/docsite/rst/conf.py | 14 +++++++------- 3 files changed, 7 insertions(+), 24 deletions(-) create mode 100644 docs/docsite/_static/.keep delete mode 100644 docs/docsite/_static/css/core-color-scheme.css diff --git a/docs/docsite/_static/.keep b/docs/docsite/_static/.keep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/docs/docsite/_static/css/core-color-scheme.css b/docs/docsite/_static/css/core-color-scheme.css deleted file mode 100644 index c61c0b1837f..00000000000 --- a/docs/docsite/_static/css/core-color-scheme.css +++ /dev/null @@ -1,17 +0,0 @@ -.DocSiteProduct-header--core { - background-color: #161b1f; - border-color: #161b1f; -} - -.wy-nav-top, .wy-side-nav-search { - background-color: #161b1f; -} -.wy-nav-side { - background-color: #999999; -} -.wy-menu-vertical header, .wy-menu-vertical p.caption { - color: #161b1f; -} -.ansibleNav ul li a:hover { - color: #161b1f; -} diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 680970356c7..b2d4dcf2cc6 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -82,7 +82,13 @@ root_doc = master_doc = 'index' # Sphinx 4+ / 3- # General substitutions. -project = 'Ansible' +project = ( + 'Ansible Core' if ( + tags.has('all') or tags.has('core_lang') or tags.has('core') + ) else 'Ansible' if tags.has('2.10') or tags.has('ansible') + else '' +) + copyright = "Ansible project contributors" # The default replacements for |version| and |release|, also used in various @@ -258,12 +264,6 @@ ), } -# Add extra CSS styles to the resulting HTML pages -html_css_files = [ - 'css/core-color-scheme.css', -] if ( - tags.has('core_lang') or tags.has('core') -) else [] if tags.has('all') or tags.has('2.10') or tags.has('ansible') else [] # The style sheet to use for HTML and HTML Help pages. A file of that name # must exist either in Sphinx' static/ path, or in one of the custom paths From 763815d1ad4e1054226077c72a5719054637fe0b Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 10 Jan 2024 13:27:28 -0600 Subject: [PATCH 154/536] pr_labeler: refactor new_contributor_welcome code (#990) * pr_labeler: add GlobalArgs.full_repo property * pr_labeler: refactor new_contributor_welcome code As of https://github.com/ansible/ansible-documentation/issues/69, the pr_labeler responds with a welcome message when an issue or PR is opened by a new contributor. It turns out this never actually worked properly. The previous method that relied on Github's `author_association` flag did not work with the app token that the pr_labeler uses. This refactors the code to figure out whether a user is a new contributor by searching the list of issues and PRs. Fixes: https://github.com/ansible/ansible-documentation/issues/204 * pr_labeler: address potential race condition --- hacking/pr_labeler/label.py | 86 ++++++++++++++++++++++++++++--------- 1 file changed, 65 insertions(+), 21 deletions(-) diff --git a/hacking/pr_labeler/label.py b/hacking/pr_labeler/label.py index 29c4a468071..160b20fbd62 100644 --- a/hacking/pr_labeler/label.py +++ b/hacking/pr_labeler/label.py @@ -7,7 +7,7 @@ import json import os import re -from collections.abc import Collection +from collections.abc import Callable, Collection from contextlib import suppress from functools import cached_property from pathlib import Path @@ -36,6 +36,7 @@ trim_blocks=True, undefined=StrictUndefined, ) +NEW_CONTRIBUTOR_LABEL = "new_contributor" IssueOrPrCtx = Union["IssueLabelerCtx", "PRLabelerCtx"] IssueOrPr = Union["github.Issue.Issue", "github.PullRequest.PullRequest"] @@ -48,12 +49,12 @@ def log(ctx: IssueOrPrCtx, *args: object) -> None: def get_repo( - *, authed: bool = True, owner: str, repo: str + args: GlobalArgs, authed: bool = True ) -> tuple[github.Github, github.Repository.Repository]: gclient = github.Github( auth=github.Auth.Token(os.environ["GITHUB_TOKEN"]) if authed else None, ) - repo_obj = gclient.get_repo(f"{owner}/{repo}") + repo_obj = gclient.get_repo(args.full_repo) return gclient, repo_obj @@ -70,6 +71,11 @@ def get_event_info() -> dict[str, Any]: class GlobalArgs: owner: str repo: str + use_author_association: bool + + @property + def full_repo(self) -> str: + return f"{self.owner}/{self.repo}" @dataclasses.dataclass() @@ -79,6 +85,7 @@ class LabelerCtx: dry_run: bool event_info: dict[str, Any] issue: github.Issue.Issue + global_args: GlobalArgs TYPE: ClassVar[str] @@ -211,24 +218,57 @@ def add_label_if_new(ctx: IssueOrPrCtx, labels: Collection[str] | str) -> None: ctx.member.add_to_labels(*labels) -def new_contributor_welcome(ctx: IssueOrPrCtx) -> None: +def is_new_contributor_assoc(ctx: IssueOrPrCtx) -> bool: """ - Welcome a new contributor to the repo with a message and a label + Determine whether a user has previously contributed. + Requires authentication as a regular user and does not work with an app + token. """ - # This contributor has already been welcomed! - if "new_contributor" in ctx.previously_labeled: - return author_association = ctx.event_member.get( "author_association", ctx.member.raw_data["author_association"] ) log(ctx, "author_association is", author_association) - if author_association not in { - "FIRST_TIMER", - "FIRST_TIME_CONTRIBUTOR", - }: + return author_association in {"FIRST_TIMER", "FIRST_TIME_CONTRIBUTOR"} + + +def is_new_contributor_manual(ctx: IssueOrPrCtx) -> bool: + """ + Determine whether a user has previously opened an issue or PR in this repo + without needing special API access. + """ + query_data = { + "repo": "ansible/ansible-documentation", + "author": ctx.issue.user.login, + # Avoid potential race condition where a new contributor opens multiple + # PRs or issues at once. + # Better to welcome twice than not at all. + "is": "closed", + } + issues = ctx.client.search_issues("", **query_data) + for issue in issues: + if issue.number != ctx.issue.number: + return False + return True + + +def new_contributor_welcome(ctx: IssueOrPrCtx) -> None: + """ + Welcome a new contributor to the repo with a message and a label + """ + is_new_contributor: Callable[[IssueOrPrCtx], bool] = ( + is_new_contributor_assoc + if ctx.global_args.use_author_association + else is_new_contributor_manual + ) + if ( + # Contributor has already been welcomed + NEW_CONTRIBUTOR_LABEL in ctx.previously_labeled + # + or not is_new_contributor(ctx) + ): return log(ctx, "Welcoming new contributor") - add_label_if_new(ctx, "new_contributor") + add_label_if_new(ctx, NEW_CONTRIBUTOR_LABEL) create_comment(ctx, get_data_file("docs_team_info.md")) @@ -277,11 +317,17 @@ def warn_porting_guide_change(ctx: PRLabelerCtx) -> None: @APP.callback() -def cb(*, click_ctx: typer.Context, owner: str = OWNER, repo: str = REPO): +def cb( + *, + click_ctx: typer.Context, + owner: str = OWNER, + repo: str = REPO, + use_author_association: bool = False, +): """ Basic triager for ansible/ansible-documentation """ - click_ctx.obj = GlobalArgs(owner, repo) + click_ctx.obj = GlobalArgs(owner, repo, use_author_association) @APP.command(name="pr") @@ -300,9 +346,7 @@ def process_pr( dry_run = True authed = True - gclient, repo = get_repo( - authed=authed, owner=global_args.owner, repo=global_args.repo - ) + gclient, repo = get_repo(global_args, authed) pr = repo.get_pull(pr_number) ctx = PRLabelerCtx( client=gclient, @@ -311,6 +355,7 @@ def process_pr( dry_run=dry_run, event_info=get_event_info(), issue=pr.as_issue(), + global_args=global_args, ) if not force_process_closed and pr.state != "open": log(ctx, "Refusing to process closed ticket") @@ -337,9 +382,7 @@ def process_issue( if authed_dry_run: dry_run = True authed = True - gclient, repo = get_repo( - authed=authed, owner=global_args.owner, repo=global_args.repo - ) + gclient, repo = get_repo(global_args, authed) issue = repo.get_issue(issue_number) ctx = IssueLabelerCtx( client=gclient, @@ -347,6 +390,7 @@ def process_issue( issue=issue, dry_run=dry_run, event_info=get_event_info(), + global_args=global_args, ) if not force_process_closed and issue.state != "open": log(ctx, "Refusing to process closed ticket") From b5ffdcd41a40c061781cdb2c968140ade1dc82db Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Thu, 11 Jan 2024 14:43:00 -0500 Subject: [PATCH 155/536] ci: refresh docs build dependencies (#840) sphinx-rtd-theme 2.0.0 was released, so let's make that the minimum supported version in the constraints input file. Relates: f6d9440b7b9aabe534f76c3cfd6b5a0ecb9ad51b --------- Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Co-authored-by: Maxwell G --- tests/constraints-base.in | 2 +- tests/requirements-relaxed.txt | 34 ++++++++++++++++------------------ tests/requirements.txt | 32 +++++++++++++++----------------- 3 files changed, 32 insertions(+), 36 deletions(-) diff --git a/tests/constraints-base.in b/tests/constraints-base.in index 9eb05d0ea0c..1928c3a06d1 100644 --- a/tests/constraints-base.in +++ b/tests/constraints-base.in @@ -1,4 +1,4 @@ # Known limitations for indirect/transitive dependencies. rstcheck < 6 # rstcheck 6.x has problem with rstcheck.core triggered by include files w/ sphinx directives https://github.com/rstcheck/rstcheck-core/issues/3 -sphinx-rtd-theme>=2.0.0rc4 # Fix 404 pages with new sphinx -- https://github.com/ansible/ansible-documentation/issues/678 +sphinx-rtd-theme>=2.0.0 # Fix 404 pages with new sphinx -- https://github.com/ansible/ansible-documentation/issues/678 diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index c5cb0b7daf2..303d557eaa0 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -6,7 +6,7 @@ # aiofiles==23.2.1 # via antsibull-core -aiohttp==3.8.6 +aiohttp==3.9.1 # via # antsibull-core # antsibull-docs @@ -18,9 +18,9 @@ ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-core==2.1.0 +antsibull-core==2.2.0 # via antsibull-docs -antsibull-docs==2.6.0 +antsibull-docs==2.6.1 # via -r tests/requirements-relaxed.in antsibull-docs-parser==1.0.0 # via antsibull-docs @@ -28,20 +28,18 @@ async-timeout==4.0.3 # via aiohttp asyncio-pool==0.6.0 # via antsibull-docs -attrs==23.1.0 +attrs==23.2.0 # via aiohttp -babel==2.13.1 +babel==2.14.0 # via # sphinx # sphinx-intl build==1.0.3 # via antsibull-core -certifi==2023.7.22 +certifi==2023.11.17 # via requests charset-normalizer==3.3.2 - # via - # aiohttp - # requests + # via requests click==8.1.7 # via sphinx-intl docutils==0.18.1 @@ -50,11 +48,11 @@ docutils==0.18.1 # rstcheck # sphinx # sphinx-rtd-theme -frozenlist==1.4.0 +frozenlist==1.4.1 # via # aiohttp # aiosignal -idna==3.4 +idna==3.6 # via # requests # yarl @@ -83,7 +81,7 @@ pydantic==1.10.13 # via # antsibull-core # antsibull-docs -pygments==2.16.1 +pygments==2.17.2 # via # ansible-pygments # sphinx @@ -128,7 +126,7 @@ sphinx==7.2.6 # sphinxcontrib-jquery # sphinxcontrib-qthelp # sphinxcontrib-serializinghtml -sphinx-ansible-theme==0.10.2 +sphinx-ansible-theme==0.10.3 # via -r tests/requirements-relaxed.in sphinx-copybutton==0.5.2 # via -r tests/requirements-relaxed.in @@ -136,7 +134,7 @@ sphinx-intl==2.1.0 # via -r tests/requirements-relaxed.in sphinx-notfound-page==1.0.0 # via -r tests/requirements-relaxed.in -sphinx-rtd-theme==2.0.0rc4 +sphinx-rtd-theme==2.0.0 # via # -c tests/constraints-base.in # sphinx-ansible-theme @@ -164,15 +162,15 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.8.0 +typing-extensions==4.9.0 # via # pydantic # rstcheck -urllib3==2.0.7 +urllib3==2.1.0 # via requests -yarl==1.9.2 +yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==68.2.2 +setuptools==69.0.3 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index 751de12722c..c499411c652 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -6,7 +6,7 @@ # aiofiles==23.2.1 # via antsibull-core -aiohttp==3.8.6 +aiohttp==3.9.1 # via # antsibull-core # antsibull-docs @@ -18,7 +18,7 @@ ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-core==2.1.0 +antsibull-core==2.2.0 # via antsibull-docs antsibull-docs==2.6.0 # via @@ -30,20 +30,18 @@ async-timeout==4.0.3 # via aiohttp asyncio-pool==0.6.0 # via antsibull-docs -attrs==23.1.0 +attrs==23.2.0 # via aiohttp -babel==2.13.1 +babel==2.14.0 # via # sphinx # sphinx-intl build==1.0.3 # via antsibull-core -certifi==2023.7.22 +certifi==2023.11.17 # via requests charset-normalizer==3.3.2 - # via - # aiohttp - # requests + # via requests click==8.1.7 # via sphinx-intl docutils==0.18.1 @@ -52,11 +50,11 @@ docutils==0.18.1 # rstcheck # sphinx # sphinx-rtd-theme -frozenlist==1.4.0 +frozenlist==1.4.1 # via # aiohttp # aiosignal -idna==3.4 +idna==3.6 # via # requests # yarl @@ -85,7 +83,7 @@ pydantic==1.10.13 # via # antsibull-core # antsibull-docs -pygments==2.16.1 +pygments==2.17.2 # via # ansible-pygments # sphinx @@ -131,7 +129,7 @@ sphinx==7.2.5 # sphinxcontrib-jquery # sphinxcontrib-qthelp # sphinxcontrib-serializinghtml -sphinx-ansible-theme==0.10.2 +sphinx-ansible-theme==0.10.3 # via -r tests/requirements-relaxed.in sphinx-copybutton==0.5.2 # via -r tests/requirements-relaxed.in @@ -139,7 +137,7 @@ sphinx-intl==2.1.0 # via -r tests/requirements-relaxed.in sphinx-notfound-page==1.0.0 # via -r tests/requirements-relaxed.in -sphinx-rtd-theme==2.0.0rc4 +sphinx-rtd-theme==2.0.0 # via # -c tests/constraints-base.in # sphinx-ansible-theme @@ -167,15 +165,15 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.8.0 +typing-extensions==4.9.0 # via # pydantic # rstcheck -urllib3==2.0.7 +urllib3==2.1.0 # via requests -yarl==1.9.2 +yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==68.2.2 +setuptools==69.0.3 # via sphinx-intl From c4dfb9ca27facff65402ef5c1ac216a0fb49774a Mon Sep 17 00:00:00 2001 From: Jill R <4121322+jillr@users.noreply.github.com> Date: Thu, 11 Jan 2024 13:39:23 -0700 Subject: [PATCH 156/536] Update task definition in playbook getting started doc (#1029) --- docs/docsite/rst/getting_started/get_started_playbook.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/getting_started/get_started_playbook.rst b/docs/docsite/rst/getting_started/get_started_playbook.rst index e5f7a356742..0aba4392842 100644 --- a/docs/docsite/rst/getting_started/get_started_playbook.rst +++ b/docs/docsite/rst/getting_started/get_started_playbook.rst @@ -13,7 +13,7 @@ Play An ordered list of tasks that maps to managed nodes in an inventory. Task - A list of one or more modules that defines the operations that Ansible performs. + A reference to a single module that defines the operations that Ansible performs. Module A unit of code or binary that Ansible runs on managed nodes. From 4fbadf70486d10ded0547002301be13485a057f1 Mon Sep 17 00:00:00 2001 From: Robin Candau <53110319+Antiz96@users.noreply.github.com> Date: Thu, 11 Jan 2024 21:42:04 +0100 Subject: [PATCH 157/536] Update Arch Linux bugtracker link (#1027) Arch Linux bugtracker has recently [moved away from Flyspray to GitLab](https://archlinux.org/news/bugtracker-migration-to-gitlab-completed/). This commit aims to update the Arch's bugtracker link accordingly in the installation guide. --- docs/docsite/rst/installation_guide/installation_distros.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/installation_guide/installation_distros.rst b/docs/docsite/rst/installation_guide/installation_distros.rst index 980d8d54f4c..26a69f5fc7f 100644 --- a/docs/docsite/rst/installation_guide/installation_distros.rst +++ b/docs/docsite/rst/installation_guide/installation_distros.rst @@ -163,7 +163,7 @@ standalone packages that users can install alongside ``ansible-core``. See the `Arch Linux Packages index `_ for a full list of Ansible packages in Arch Linux. -Please `file a bug `__ to reach the package maintainers. +Please `open an issue `_ in the related package GitLab repository to reach the package maintainers. .. _from_windows: From 788e8a4f07651343407e07fe19a18cda7efc5435 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 11 Jan 2024 15:53:23 -0500 Subject: [PATCH 158/536] fix intersphinx tuples (#880) * remove cached .inv and references to them * trim down the tuple and remove reference to old script --- docs/docsite/jinja2.inv | Bin 3594 -> 0 bytes docs/docsite/python2.inv | Bin 85381 -> 0 bytes docs/docsite/python3.inv | Bin 129639 -> 0 bytes docs/docsite/rst/conf.py | 67 ++++++++++++++++++--------------------- 4 files changed, 30 insertions(+), 37 deletions(-) delete mode 100644 docs/docsite/jinja2.inv delete mode 100644 docs/docsite/python2.inv delete mode 100644 docs/docsite/python3.inv diff --git a/docs/docsite/jinja2.inv b/docs/docsite/jinja2.inv deleted file mode 100644 index 37ed796899811eec2e69f09294418bfd92b3f7b0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3594 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 diff --git a/docs/docsite/python3.inv b/docs/docsite/python3.inv deleted file mode 100644 index d7ab8c267d95d843fc7552ccd883f402231fb0f5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 129639 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

^0?bd$*Ntch6u;UB2H;*q{Wa(}$ z%QwJvW{2(OxZ&`!YXwp0KK4++{)8MjxQ;7_?^4~)CG`=iWlhv)sPZ4uj8+SabV`-n z2pBAlz!nL1S&=%x7v|=d@k=AWWrl9{cVR|a0Zq9t^(a&xyh`^|1)2#Hk+OG3XY6_Au<;2B0?N zlMfNPE){6r1XN(?((p<~HGCh0x}^|5&D)9galb@Hr!)eOP?x1OwzyN8^;XL%Rh;dn~4z*|9 zgm!Klswa^8ew_(+jNhTK18Hb{>~7?N09ls05}6VOWSJ6!L*!!)J0au{amgU?{LjWz z7^zbZh19GDYg;@J>T*3h2zCUQv!*rFj1+L#?l1p=QDZQa+F!3wYJa^#s=bnTq##40H2>oll;D5-f>Oif zl^rgxV5C}%Xn$cqjKLOz5aaiAr{X3ZT=I?a7~`ip=U+9j@*_A*J>97*sB|~4o!GN4 zsq)sm;q}pb!H(b19>vAS8yhmHM=b^%43oq~S!4+Sz)#iXXIDo;j$)8vT!Vw}s@+F% zI_@-UB238s-g`SxKWG!11`#mx=1ntJduE3jRu9*5S^~>Re@3zru@{%Bw;M9~o)67p z5+#UJvA|R`pHO zjBc9<%TSGhe4ZL7DNYFhE3)FAV)RnN*RS3auprCC+F585juZ|sR1o_mb6^~++4~a? zpxD<;e^8wXmmP}kD<>4$7g;E-A;+rZZ&`zrSCaf3M~-TMF$IzRo(xwl+5n_Fd=a3X zj_Ds!>E)OvS*9NGbU)6AJ^c^H!wO`$gu5K>jsVA3yXZ2Jq>2tR_LaQjfPYjt-01|z z?XF^UAUPHlNDjmVlH)LeOzPyXS14HY`UfI>EK>6BiYFNGRKTIM|Li?4R{SSLp%RZT zK&8$FI>SUc+2eq9c6bFMvx0WVR6sEZn;j5jvs9mkr>X;`9+hRidCGD&q@d~q?tYvn z@khf3<#nt)YJ@gv^M85!*6zf0q}^Y1nAtruIdeV|Lb`c3feet{yXT9SumyO>w%n4P zg#PtMk}nvrjH;x(Yt8KL#(EyzOI5m59dp{vq)9#sNgfv@F?qunglY#4a2P8Mn%5BO zv`+_u(JT_`93Bq*$VnCzWGleXo#_VBAc(WHmaHHg1|!RdK?#ybB_D;$4+Mj2^#>R( ziuZAWz$NS*F`i=~?aYuOa7A1s7+l%h?EvA7ffa^8$zP>_Hzlqi6Cu^&91KgzE7jg4 z!AKqS$7r_?A*+{{Ij6h$0|^%84hPN?%xL2%sl;)jf}=(acjyn1Cx|J}aU%|wnMRo% zCJjQ>s}0;bhOFT`$wQOl{~;hwr0MCKn69o5A#tMc*Ut3zq8}yfwJL$rs03V_5@1bA zz_loW(VzrQdlFF1Ng%W)F@mOtia>$TlmtRc5(o`RAhaWa(2N8^D-sBeNFcN!0o8;A zSPK#(c!PnpAA!<*1WM}>SdB+uwH<-bbOcz-5pWGhfVCTe(`*D>s}XRGMvUN@pfnkQ z(_+L3Q6sqaB1Ul0gV9>V2rjNb+RCpl{ToNWzFhAa$=~k(`(?sXIjx0Yz0U<&U@tb7U!#_47H^B%B4D5nTEX~SpETAv-4V?VFHU5)>cB+6$9 z?*%mfjE;31K z99wXxUx#|3%veN@-q?=yrBH8VUMow5Kc=9TDP9U#U43fD3S^Y`@Ej?8vKVM`vZqk0 zIa7aim`N4EhJF-Cf~VyIJoDG%&C3dodV%M(`S!9}!%;6&1PI@TU8u|W?BT(T&oi2w zyB8(rm|}dNJ}eOZ&|SiMwAcZpk}zbu<*@t|s<|;{kJ`mt6t!4`moyd$H9qzoz$sLt zo57InAV9znjauR0&8l(u5uo9mWP1w7<~$?`28L`}K?}D*q#X6^Q#cNtp#mOSx4yR6 zq`6mXcbg~N_g{dNzh7IH^0!CjR&HG|E>~am+C#T#zo^>BXW3jqo4e7skvTEHAns2b z3^!aqCM}a9Ry(2AFdfM)iaBk4(AvXj_7-!a3&mkjPztiAFsNGKY!TAhvTcN7YZ^br zwr>Q*Zvk#U#?q7|2k<P>M-^{xAhK&G7TD5vt{-_*)42NO-M2~y55`HFI@|BBAHA!w>? zaYj%5I`8;Fc{OrGLXXvnjVw^ zu!W!v)T`n4Cj7`Dym7X(WtK_*vQ8^nxolk$u~X5Cftb4d_J9mF4idHpCjag45I|iV zn>Lk6t=m685LoNyu{AYI%tlimfSX@8^ri=j0;nVqKRKv4K*0f(8wDwCT0Sz!?5Ia# zN25vF>)ftQ-bpu-e>M*0u9tHI;Acro<9oY)5KGE5Gb&I0kUCak6;8q)2nVpRV>wyZ ziKcmRG(HyYg~Sofitr%qE>KR=kg3!HYlQ6iq8>HYm{dw_OgpfQHUreE5pvd+%^m<7 zqd5l_iBo6>aX5wW6Y}hhGj?7Y;^_;v9UTioAHrG$DB#iuUEn?J1 zsbaGJ>kKFS08ou@{ZoJYTT$euODlG8*;=Q2AXpCNnWG9ej9}4!mE*AJ_YZ0f);>8* zw~0Y4f|WdUF2=oFPq2T?hp`g!73D@c-1>(AOur9i9!_b z-}Z=!`eWz~!61%iDBP?LC)g*ahA^FS_O42|;52iB$63f}DwQyjR0ZKasH#HYsfHYF z+yqy#VEC|>U`KKaSqLDR>dHsWg+_yr>jBPA4ft^C3(Em@4Mxm>9ul?3Tadz)#_Xlb zomx?&GX~ThO)3u%(t9F7}wq_SLu$ylQHrts10^z^_Z2KIaTBg0Taf94p$ABK`*NYjFbhP zg%^bDtg;|n|C*1bz?Om!9?ctJrzP1QR{7CF4Fi=KW+*5eW;i5_y_Pu!bBYgRk5qb= z%On|i_h3NWh>mdsg{h-U{nVSTus}g?1_CkQKGH<(hjO|@7o2VXQl5Z97UWFm=X?Ti zV5|O+^bjR5qU5E7Gz?_(7K>?_SECk4AHk6K0})l6+yZ%wNcn8~?JD&(efdG3z|wd?ai znn~xLF`lITw?49a-w2;!Z4nhTk`7!8*6D9CWGpBc|`JEZj#?+#BV0xw1P~ zM=CtI>)5Y3+{;qx>FlLQ71f&lER}ZehpTX+S?RD}vFp(BQYF{Atm9uaa$@*{Bqenl zzV%(62&=Yq@ai^jEQB0&hAX)svik2q6|C@x)&nBd)yS$z!Pmc<-> z#+HEPM>o95>zXA2{U{t;vSM&;Nweo8YXYgGIu#)$A4#>-g&)((R&gnVguAw6<>ShY zp$+4RreFoy4psY=QBmdtC#yFY1WW0OWfTz6h*EfIF1dEX)gKa}HV*iHYwrCH#W_~Ip|KLAurhl*R=lCH$M`24D?#x3 zw%f3lZ)Yk%6Nu=#Lz~Y%UD|$XwsND`yitD6V<6ZK-M6q}$cgzyv4J6}RwfG{`ytE1 zlB-SD(XK2?PEE7mGFeaKT_w5a?3HHI4;q$*IUI?J+dw)|56$E(js|0#07<)Lyw>ng zRB9*PAcJsx;!qY5d(ZrmmfJKgd{92>KRq;HMWmw02NBDt4kM`VtMLT~j1bVK%CaszvU_8iJ5$}$HztK9& z-bfNhYo+S?6razWg;a=V#uAT`baPObF?^H8DP?8hv-U&;?IS4TLJeZftM;rH&`#@m zDsiD(wx&NdvnO_S7JzGqUA))MF1SevX%qCRAE%G^M8skBh=3);yorCwcSSVO|9Ec8 z=4Xfu-IKn_^ibwW97mm0|Uk-OI;DY&Sy9M(!6Vzmvm2{<9k#`UJ@&$_zZS;~7 zEFG&WJj&6Py6tW4DM|wAM`}Qh(s?B&2q80ou3Jzpg4N6bu7Vx7 z9MVwqTkVR;w1}$jrd3pbo1D7OAev4T2JFz)CrgHb%_}>C!Tl0Dih)NcmJGbi+z8(E zg+nKfKL~f}O9^-G48<|*5yGBl=ryxF3z}o2&H+&Esga|n*?K)&d_}iJ#ln&(&_lzK z=WQUA$}I*p#{(-_f5}nHhHC+pAA2N|{PBjl)xg^HO%}aHx=I~Unu8FW?u`|Y-+Jqy zewWQ5ZHh812428+7`o6r4qpdu$Mm7%{h{c$DjJO~l`}Wvp&Bi{cC##ns7*MT_ub`TcRW?%hT?p|4<*)sN>55cBl#FCb$5ZT#h5cW}_Ze*0nzY8$U_sP+M> zzBgZx?8UqalGx@_-QBzHOYwHylk&HRm?YG2J->lmq?JM>iPJ$}Lq;Skw+a1OvVwxK zDwtYM)pK(&R5|5P(eL7{F=9b*U0zhi3R&AIAe?gRuKX#>f3^{yVFcP2000&i11@s< zk`MT4F(ApPrmXNRP_ z#8*F$`My-%Du$)$?TdpkddDzW{R0ZUkN49|Hhs3%c8BTK z@eS}xW;(9z2TmTU#l|-Iz5%rBy!t$6MjgfiH&TDpzx2ys6G>4d6hHX7c zlZfqLa)%`GK2z#747NRT3d|`Cw)KMy%O;V4V?jZHW}^!P2yzgl+6M$d+I#fYi2AZT zBz+b20D`Cj5kL@k|AZp`4FV+0;F)I#fankf1LvhrGhhg{5dnlCFeP}Nl+f{2!UtFh zA7LeYh?U?mR)RaeL=Be`K3?8f908@#J6Pns!(|>3z~!Mi|I=?LItm(?q0D0CToy&4 zHua>^k})_;1u+|Tf!vQxY1%k`0fFjk4)&P*q!j@`$68qj^u5$6>ezYq`3PLY3x|eR zg@md;_2?wPrdKD|qg|XuL2}w|!N61T7II+b@8Ck0T$r|9^{4A?*Xrl#YSnk@)4_BS zFMqdBOGFsQLj}?aOvS1`4jd_8aa@C&0^s1vF5oO_k9GQMJ;+e-1fPE_NKzjQ;R*5s zaUyVQ!dPq*QUzSc5`>v!Bf54%6z}80g<#J~esCd3*t>ZJupvlk;WP?z9%oKXkSm-E zL3_afOHk&yTN{2jjspe44a6-eBTkAN)xSbfn!^ww$&{I#?Nt!?_UC_gb zbB%+GR|OLx6eI$5@iC}O&ZmInwcwVFVHBT?!I#>M!OQkD)=Lu< z#>qPjq67s_kJCtLf^KiFWDMhIA1XtD7G{)U8S_9U`4@F zH;zLbMKp8faBPg!xj6^jAls6tT}CO^cwTTvqJwMS7A8OCwgg`4A!T8NuSqpNgLc}P zXX+4(3a;izAsf?`qOy%D7J;IXCK*gzp(HU_4(qp=SWC46V{KK9E{h*tk=2t zaGniv6tQl2Op_43#iCw4y5RSuI8g4wppKSuy`yTr^EAw)d^wP8pFle?*1jgm9s#>~ z64Hwj1$0p71UiA#K^!?ysC8nqA$*NdTR-pN0RcmS5W7Y7;;LheE3pC;4>G?d;0J0~ zN8xGq1_Oc3(Mp$6ck#jlWGbF;nJ738i3G}7&P;FVZX+`!(CF7;5V?KbM@SelL&hV@ zQNRxbDm?57rkDdEux{hnD+k05{U-l za6;>%1uMe?jc^3=Z+N_v2RXq2<)ZyYQDgAd7OV;OhF;0iHykcw?Y0USSyb^*P}s8I zbjPW{OgY)O99L$A9Pmp%h|S9a*TkGgoV+J^C^lPc`<|{M1A!vsEJ@Hn)KpVDbs=v& zkO8p;$s(FX0EIw$zgQ@4@QZSblSdMW8wyI7H-~?_3B~mb)_%ZC6}?0t^&5@FwQiX? zfZxF7<>dBN$`+({Q}k}D;c9y4`_=w!_uHd-dfvBndqr@C3G#Y-a6QG&};z*y=*3?orD2Yb2+tVJ`X`gL9o-VUJTy7 zZo{P!fy9PwcR-O*r7R+vNc$a#1q(?c^#sF4ktIjfaA*d`qc|f88n6B(g>agq7+l-H zt^N}IPU&l8Q2KAdQ}TiB|Fl}wQBamu(U&pcp({AIv4SOK6ZHg>yPTvu^lVdqYu7wD znqhmnU@lX{Wqci}+3n{IY}3j>IjsNUCW~tdv^>^-k=l*?mBOh(*-kxsjrTzd@!9ibe(-mBnYWHQ@ZHabTp4}w7 zgH(5ur0PErP5Qk?+Ta|-0N@G?OOkSPedFJ1dlz#cY%{c8mKgaVKDjBF;%BUoEZlHZK&aC^-Uz%3M4R! zaKKQ-V2DH0F2+r`dczT@*K@*!px`9O60kHUoH~I65$`i}6Vx19ar8hDq-2k!$&Yws zfF67r-4zNrhK%lw=T24xsuz*)%HOYB9nLrc9h;$by$+{~;y07i3rlR{#vO&1q8o>$ zA4u7^O9>7bi@;HeNrs(r5=GH)shPVGWF*65)y5RQ>OWobR&$OS7F1tcyduLkeT@6D!8$qARVn z5Q#2WK(l=vngdOt97^uFTnp%jOG!i+qe}8{G83$~6>5w$)c-0)0o9mVw5aMX2RtW5 z%+M?Y2j#cWNL{;yW9;<{Fv?!PIu?959JsF`?)|G*M}?aU4kznFmS%nlHrE7sgQ!^2IUGdRZF zYYA}XUJFN?dkq85@@mis%d3Stm`*JR!gOk|c+;t6K$uP~7H&GV(4SbzrC( znE+!w_0hEPg26P?_GleuN@+)on8V$N_$^jG74MJ#tyg4g=(G;Xfywq!DV@ulYMTvK z*>B@Nrom*n*i8T2{L%jkdJww#wwjI~))3q*YX^pPF=v?^1#yI{P4;E;Nhiw2cAS%-xVJd zGEtBBkXV7pRa>|+)hGzmHOcCULf^eoQA8K2tPd3w4@INn$-%TQIfIzO&QxtYhf0i^0=@Ti!1F)wruyy!o zmhGvK#yc_jl(ptlUUc`Il{t+9maB;A!kti;OUG}Q>(8qPLN6uzS;pb((AkSEkq-(g zjW2Hn(qUHU&)>YTeDT5p?5kSQ2%=grL8h1bGuR#rDxgR;wDcYBYQ(|`GE8~7oVtut zD6GulT`XrQEK86&q@r*zehjMXke5!@qF59v2EF*(wv3ZP{j&=;_~VOv{P4-&?qz?4 zbxfdZVR%-mQ{s{O58M9Lr`sDbP06muq6wiNT?CCEL+gz68I?L;r&|)f0`qJhLfwWa z&x5=Sjh6aA`VrxKn<`yEIL$c%R!5D5pkfjHRi?RI;d!mtLeQtDRUlN}j6)czc?JeS z8Gp7L8T)$`}l1j|t_7s?3s`DVe@{ zy<me{tJ`$yOca)BcbwYN{#D=6ut~~kVwqI$%2=kg6*DYPNp6?WmQuy33_^3@zH2}s z7ruZ>+tln{_5xFB6eiW7`r4;J)L#gfhQ=EW)W6P1PRa_&rCzhMYw~@RjQKF}> zIVlc)sMs6zH({zew&PHEAX7LhC;sT9oN&U6 za@$0Nzlx-8#np)>kLjVh7+dv|7n0!0BN>`0C*i9!Q@9^Co~O=4Wt>D_NP_V4?g*Nx zzOCg>R9{{4z;i|jn)N24;7h^&;l?IH9_NK{tz&qg^--S-NkZ!vPA()Y+r@iV7PVJj z?^b%C(Q&SPaUCd$>NU#;orf9MP+DVIN{qt#=n^+tvj7 zqQAhR<%b-j7byZX__%+UHk<4Iy54cbgL9`-lm@SKRg{u?PEcJ+bEnBk%->^y zIWtklzEg|T`0BNFQ6D-Y3(;&+yV9JtgRl&o>U|(|LGZFkyY)niS=yBi7=j(i!ebz9 zJ83ES;21rse|&BEAo9w@qpVr=jEBnQGReWV$N+6o8%P1;mo8sinVa@R^Ii4~a7>_^1B|=SBo324Vdy0-6>rXK>S-4Z13n5j zwY()5P5+!u)T6n_S@)@(O$VGf9N}Rp3YMy^5{Ip*6P><%tN$7t&UQY1FuoD)kxDpo zsp}hhLV2rbew5NOQ(OJMsA`J{O(jlL?bZm8Oy2=-PnZxBrX?6{{SSX7w@+9+#`&HxPr`gjtnY zW_ajl#IaBby>%HE#{0Gd*iGHsko**8B>#PKYSJ44=oSP0AZcD-UqBIbbs`kOK4DvY z_NRvgD7Z_>A4!~))rMkXufXI~e~)ijv?snn;L)ZZSa z8_5HqkOWWT`Ru>b;QP1PX1abJPeA(HvMlnlm?*OcD8|l^wc*6{Z?JiF&QmeyH`|oc zECf!{)%1C}+RPST;i_;24JHq>$43Nify6Br^B=+EY_;A5Y7D)srU;T3Xy)tRXU~xI zFRchab7Ke6!Fo8*ida8a7z{?Dg^;22vi3X~vNlxDUIY)Jz~=fxea@ufl7T78ENJbS zGffJ@QeEe$f#s;Z8k@iOu)L*Ww z{OZ^6pfuEC09U6N#*Zc^o=ZXBLu15`f`I-s_%s6YWYiCjIleoHXv?BwAlDsc2uFq_ z8`v%YF)D-Siq)-<`lPyAb-Sa?iL<(T=B*vi=z{CbcV|*x-4kaQ&FG6!);sjVciq$8 zD4olw-qMmJCMKb8P132I6HQYiFo|-`loct-uI^u7;Lj48WcPWZN%haC6S+Z>_i$U1 z>e?&0a3EQf7~&QA$whp6F7?TDL9^nMauEJ=_=G}p@~*EJ2c2Pgq5dOSebl{@>s$;> zlqQK`inO2WCF1`w{_kx(EC9|a&0Jd|=-ofPP-TqeUWk5{Eax$f>iSOL1yCn2HFWjy zUitr(km*p|@N2p&o^N^$)|;@dR8Le0Ik-I0_$iVOE=aiY-d>*~qABZZifm{#Y10@w z@AO@HQ4?Rgl>KYS1>rN6LSh@0vL0pr0N2q`#N?w$~Op5h|BZ zjhhSar5){968V~l9aTw}!MTw6bo@P(eKdS8*ue0!qR~G)S%B1%+VtR6jvro>UbN$^@9?yi!iBwQ^ z1us$=dhG=RySm~@QlGM6EtlwoeufI)!`w(WkL7=3h%?YtV$hAnaq(2j%LtIB0%zWmIA)QX#U{uC60%TJ1Csv{{|P&|=NksruK`iLAc| z&$xz3q*T|zVFqP7j8AEVQdjdy8PVkC!UJQpS;}CH3C%pR3Gd~*rG-J*s>Az2?U59< zD|lb5MM1(tI()(iCGBh``yu2im?DjQF^W@wCO>ooftcZZ=E#mnE{ii{2&dIP4~#Gg zv8kc5%*wjMom99E{_DES@Lyc8zE1&L)j#X3w;Zms`)Yy^fIGD3xCTb*0-AWi0$J_D#*oEuswx_gcQsJcrtyb2{Yn%1RoQY*NfWEg&yvn*o{*6G)m4T61yp!n z?ZoFuO6_pRqZTLpi^+i?+HkUWlDy)n)aKc9Em={U3O6?;bi}&iA7B2D9g)?>1f0`q za{^9lvq1r8wb`VAv)yJ3W57%dil46VhxF+8jAO>1pMyRh3?(k?kzSko@_w=HTH_D`U; z)E6<-7S=U}*0)@1IfZx9W5P(}nbksbhSFMY2!LsCYzjd6ZW!E9Iy=h~%4%(WLW#xa zEJWf{79#O^l0|%i2oRq#TNUdkRQ?kLz)kZRN_fMBwxp|kV{GHB8$s20WgxGdk_}Qd z28IiXkAj@c5-3Z3NzruoL4Gz}d{CcAo+oigw67MmQ87OKdtkq!CB0-TqnK4Z>Td`J z^-5F|sH@coe4I90F0*v_B8Q2gyKQs(I*5^_Sw1VC?qUjL%2;+zwqThHpYnICc{X*d z0egJjx+^q{w(bzU8gKPS{e^uv-G&ib|Bl)!QJfJT%Gs0P8IaUFyNRG zLv(9fW{}Of>pe8C2e4a{b~&Wzhtn`ArH7u@RS8TpvHCcv7u|t&=&%^!w;t@+lhiA_ zGgs}BW=D(g5Zvr12xaA?$}?xdxG&0-s4K6PN-=E44D#vIkLPxbAqGc>VRYJQX&q*` zm&<9?UGg{%ye?fc_DCqZ_2{Xt{swdp>)FFNPnC-a+%@&CU-LewR5GQI-GIk@;044&t(6T z*!%pg3AOV&n!67&Pb+52_EEi*NNBdNqLw%kHk$;_>q#T?NGxc;vd&0$By8NLx=oGs z6ISpk&&>!WO3tP2@Y3h*Ey#-7@clIfvdALCxU+m z;v$mgO}Hp!G2^^{ooK$Aaic9`g*^L(Cr|H8fKnEEAvY7qn zWeS9DYSZ4bqAIz?-QYnmcoNn)rT!EJ8as6Fb`Yx{mSBJb*M|pjoGOt^BYW^;9pu8I z7gbW32g!i+s9vvujDsN`aE$yLl@?efJ0Z~f&aE5E7HlAD&Oa_!Pk>o>2A}@Vbh5#M zf1ggDvDo!yH3Q{5%L>3EEmH%=>@i=*vxR-?`AU}Phjse<@xv67_z{%&0h0P@{S}gY1xoy%2_*S?Zr?xmk5ZYm zPyMpC@0`iE+57>JdbO}`!O8OJ36OZP7~jiLJAD9QR?|m0|Dc%l)V@6*|tf!?z8zC(4(`(^J@83j?6UxvRMHV|1q{-ab`>Vq-!;$0LdR_fKsoeA#9y` z{^c8Bc+I~o);|{ZLVNxX5c@w?fQd1m-Al~_l3Xq!kmS=pry%;L@t=_7>xumcm@goU z$b7kcwod%?IGfw+8c*}t!d^^E-C;fZFMwT&y4g2C;nkMUX1Sa%0j;xuDUypROh(G| zu(eVGpfYs<>a)diyjTKK-@iPr0m&!p86fq;cr%71pZ)RX;teSE56Cdz+|MB$x|xih z$M>LFx&bK#GCf2qkjbY{&zm0*07Q?F$=6HJ4B5a6qju-*)Bg$3#+J{j@Y4RbNBl8e zJlHx3S+AY|OSx=IfS{F&1gPMf z*%K`B!}7(x>~i&d8ZUmVrhpFK{JFUY>{q=^=F_qLXn0wSH-N5sSx;B?MgP8hnLpfv z_Imz==zxDhWQY!l*j#_P0eB+`VAuV_7~r=zb=-IBF_ei4k`>!_<3zx+1l@$3=FH&9#||ocFi8US$i9vzg5^<83u59(74Hw|w$xy!-l!N{ zxkynHTh|N*xoHHdzp2Mm)rAfW zy1D*|!lH6LF!ma#H%0o@MTDlP-m;+ZZ9jv7VkgH`p_&{A7g9aQFi?Cit82&u{&)JZ z11jOQwIUTY(m&`8X_c4JI4kI$@_;K(I=w9rf?S?cD{Rp-wp>U?DL}922xqVMCLF%Vt+Vea{~-kfeF0f9h|>=IeDs zwqG9Wzx9sBb9_Hg-N~h~=^2DAg&ai2%eJ;0T-_^m;;@=!c2toRK53jaG01vXR4XF= zia4TSoRY+$Je60mM(!X%n9$})`yw21x}#h!Z}e|!|3{8<+BHNu z`$eAR+hCGbM&P_6w8lbkg{Q_T0204GH>1>0vSX|IJ|w-^x}es zM(4Y>U~Iu-A&dSOiwzD9hM`hLHo36811n9B6(@q)w1>LbB+ zRheN12`sZBmmm8VPyOk7<*a^wtUL=`t(YCqdFm0_8qH-h$n1h{2*k3?Ts~=KLLqxvywgP5K;X<0wvRI?D18MtMVbgOCQAgkm$IS`MIWZ%{Bn2?|14v0 z5xLnR_aLg^173A*AhqunFc98^f@V>Ofho0VTkaG3MiUG=C*lo^i+_Q;LAlexb%R2p zy1`*Yzp)t69l>V4hDmRQP>;9{h@3`Y7-C>KXGMTV<`|?9NpK^oxPd{vgx6=mqURXa zfYIp#sTt{)ZuBFh`K8G_2$a=iD5UbAencS)TAjRD0hPVZn8CG9`}JDIXuk}eM4jV% zfKhPc&E7DDI{jtAD@CCbUIysW*Bkl{&=KK#^G>!6f%?UXKsMYvgj9RC^Vrt zjmi+!@IncFOD-kQFFcL6ShW9v$#tKFCm60l_;bc|N=|YhqAPVGrDgy|a8D zUQKWL)5G-sL;oI7w`*78&AUm}yMGM|WXS7dV z6&sof+y2!A2eSjz+ihS7ryKwg1%c#H95@w++P&v(NGyV#RC5!lBHJU>ZKzlK^urgH zE|LpacMEux%glaQS1x%N9|e_Hp1`o*N2C$=UIW8?^Ym&?lOYVgR$FeAs1l_2Y;L(5+W_uD9_H|dQi;h%75y$LV zyfo}6&UVb1LTW^Yu%q@YnVfOM!GdLVg1LE>cjQgsD7j(B)L(kZ((ivCJVdNF(^4n z1VHuUBtMvrUz?BDb#6XPj$uNF^}jQYGw_DxOdSnMeR<7z(I2=8f;Zk40g*(eSQ#Le z%HSr^(Va>fz3LXun}<>CNuQ z`_pG6wMzfX;B;AixGuf=@t#Cq<)4rBCDz`#@hiT_W7LIQO$BrEQQ9~j@3S(8fH|cG z9q$^{+`HGaeU*R8HMD5+}{B z=f&pa8I1wIFNs{jiaKrG&Ad}BrN`}7AI|2$o- zmkTs}J)UFBE^w_T+*?gJwwiEjHGyk2{mL+k_f!d5tdP*& zpd|m>7 zZ4m%Ua)2^WJ;kw1T+f2*u_8ZQ4;A&}x2N&sLJ;=O^_JiqX_kWqz|hzqgrJIdW3m}g zgF?@M84`Eb5FI3p-&(w`anSSw0`)wx{7e79ksq!Hj{1>iMO?&Gm|;zdVf;wFOU%`s z{4Y(rU#@P~WY;YEFUN@P1eQVl>t9%~D*BhUCQz24O`KB?wCM-Jrgy&gH+vKFdh;|l z2d%zhF~bLLsY6(d5z-+f^~C{R6l5P5H8y!ninian2^nmrn zMZ?4w7tNxg3gqC2P00z5y^zPgnDo%~Tia$fIP-C8I!uGGl-X;>-ZRYbC^L|hEOLW* zEb<c2b9NIDFgN>gCnlqhGuB!`cc%qw+g)o#wDgWs}H*IIN%M@RA z#ujRVHw4vejGX3n%XQw|?tCX_FSxdDiR5f_ojuoF!Vj5fmp*r{k|!RBI@NRUL*tbl z7)>hne#)axbUl%Yj;2t`^MheIx9x6NqK{$(Ub*jdNKAI)4vEGumqbV24k@OJkftMOO|sUBf+S%lVlckK(gSb zAhsp!xSR1nrZ4m9;MnS=L&OTNy!r*jE~cJJOF#0MQ{jh9ZI5P^PwYsxXVBbXF(?AI zvy|moR>qe2+Z73%~sK_y6aIOwh3Q&FX{eQ%3P% zkai%IjpArY_CJI>i+9PPUshDV2RBVh0Ik{M8ICFt)%(1zE^G~G)0Ky?fUPouMkZSDhTO z35PQ&Gig#t+pc-c@i`gQ3$oAL)c&ClJLZf>IUXg)gptT+>CVDCcq45}iJh+JY@EuT zDg5yX^5$e}%)dYT=-s(&q`{}0mOM}FS1c#IYmvmQjaf0YEh|R%L{O`ZS<#<;hhX%V z2v}J(VO9pZ$%4yfELzZbE05lBQCGq00|qa2RhSbjT}5R(7ELTqjEm|n0iyFO@Mx)9 zS!t))9$TB5O2>T(Z1=ZrlI2Io^2B0A1?6uv`klIRInR%pr*?Gd);3;BV!mbxV2G+! z-jQhNNrN?s>$qF%<4BY|)q`x{n63KWFU;$2O1@N=0`yg}Z>Pwiz2)dK+EI<3s1RgN zCrRyq$=FN?ZW2Z61#}>8h!F&Jb+j4OIruKPzTFjsXLl#O^0PE0S>&5mdmUBp;Xk9r zX%+=HZ*XCFwQFP9)`jX&}gkZqk1Or8?e}!#nux z?|=Ucc9zlL<_%X2y~Q;<1Z~3h!Kcn2l|k$L&ns&^vc2duN7RG+rX?I=^MS&Z||wEpEXIu zQG6D4P5T)#|J`YtOuo)M>HfV;qi`Rqc-m42U_5q^5&i5D3!azj4X!=)z2kP6g6mru zZJrv>M5b!^b&9Ou5b3w+_`x$P{gB$Vc03)VBuDqOk>Atg-yEt30((UN8~va4_^F5^ z6^Oat!-k@ni zzxC}V-ooa&>0Q|^q(_V!MTAC57gj-_ZHCjO!5}cw6k~%CxiFS9)=+Z}DfJOhEsmprbG6jHrQCdM$Mw+Vih%-{^c z63ZDYF!&@EIGi!kp$#wyIZ1;w`WKRcmAFESa*M&GM;`AFg}`9d5wFNeh#JiqGel&) zfonWVLUEl~SYRk;A4g-*x*K5QYeNfMV@G4Kjj4r@QBsXI`9isgG)Anvi5xIKZ(s!_ z948qCO-$YcZX$8Ygh0z;;VO%TgDe(@vWVC_E?;%y3fIV{NWZsm+Eq&;kXX}W?3+l& zapSk#ico4zC~$GWN|-Xn!7}`;kyw|ymc{PhK_?g#LfQNv1xpcm2kZ45ZuqE;7+QI! zwg+a#m+`Z~031S5o{>cD`+q6Q+!&zE$e{fSJtkx?pvX;}(l6Zt*c0pz5jR+(>Qj#) zs(&t|z25g!w2SH_e?O4ISf)!vZYWRQQ;rg8&`5BB<-pKi)6U&%b{S9%ifQWV2lTuqog3k6^NVdY;Xv50=RvSIhrS z7nX_F%a_$;YLl3RKg*cYK;7*%_VWcs2UQJroTY(aB@d}B@SVBwEm<;BB$x+40>|FHi z6EMS!>ISVtfllx$#3wPTwlE@JmAaf_PFzFRsUbW=ht?K68NRa=)Mil{=9y*cadzP_ zY|a=)RE}zY1*${SM&7tiOOq>GECLnClI*>(IS=h~x>_g~%%SldhD2S8YWv%%TE0e= zuV$`!DvE&9oa1<&XhEK(=x~q#=M?UeppQ?DDKBhslF z7qK%kXW@Frrkw?}5xjhmwQ<`W$pm_sUWgi~)lyqLw=BQ`g1(s#B}pYR&L}^kEvS}Z zbpK;Boh%=w!TRO#arWnQjZ&pMd@AsFoZZ;uv0-|c-oJbee3!4?uJT6MT;6f8{RY`w zmAGMYCn-BjjTgDMdGQwQZEmb=A7*wD^ux?(LwcANZC9UY6&q4d>?3hg6wQn{#jcmn zgJ##u>$Nkg#rVM3t5fMX`$c^S`X?=Y)^#U1lT`cQkz;Fh_>>F7goR}2tr?v4G>m=n zX%&n5WAz|gI&6%```BX}swi1z$E0vRQEuyfh3W!E+wHM|1M)h_ody@S`13 z&IyiiOGy(wjla$&!Q$oVe!4>0FPa5#>G=jz;g*OI9I{hpOsH0JvY!)4+p$@H(y1KMiS&q#KR|aDFciMmih`}vULmS0IFf||IT3v=>%W7;4?9mLM_cWuN6pW)=x@Ew&beu^7-2#~G zQ<`omcR=E2pzRbS&OPUMu3Y6};HcFh7U=m=bZsjL^lYma1S}A_>0&}b zWv2Q8fGS89sw+NPxK$T?`V1UVL@F-L+1W(VXPfq(Vif9bfc%5*DG#`^D|#*K-b_Z@ zSlym24W1><7^yhy4Yy_bL3;bae1D`LR4^EX^&jT2>vJ47x>xRu;%q-#4#vZ4zzwS0 z?I@?wY^hxG_wFAI0Y;H>HEFnIGzjG6-Dn>V1C5>tZ^C{<;$+t`2Ph`ncOIMERrljo z-=9g$0UfwfTMa1$V7@Ur1Q_L%zJhAf+=GPma|Z@$@b9XnA=Rn?RRk+|Mu47Gl47>B zDOr_LY4=;58Gv4a+L(W~82d)<0Ia9N!}M|dGT#LEFOQGYRj{7@xA*Aq9Hg$_TQydd zP~F6!mIA0o3~p_nBdn!qJ==pIqKWCkY%gNKZNE8v1S)>DpUVK5SWk&My|m1V;s^k! zVPxL!H$u!Vt_L9kfDx8Lu9F;Ck%A@(BsrJ56)7M&D9HpYlon?8ZIy+bs@+SHEa}IY$t?mOcmBDhVf)^-55M6}FOYO;V6p-_Vc3x^Yj5N2kTc zLa20b_DW+1q$5Sw0jFTu=};O1j?1bsia^>9y9ycVvzMrgn ztHD&K*GF$bHK?E+-B55TP_kXTFFCxtRW*a+z*)IJSZ4o{i89v?7oufOd3%6sVS6y*LJ*5G+^b&eZ!=gTcf-iZr*ZEiMSudUAZ%eeaU4<&Ji&ChePbC%ij+ds#r zl3a})ORQ9Y>y zmNz?Pu3TxEs9;#4@IjXI_-)7s2Y^ccsp6=4>BmyKPFYa;CQPxHI34aCtX*bohW>y-^C5E-iW#=k7(2+C}ls_^St|_gMQ55=Bac zH$GWBpLFhHb8%`faM#t?QTgiH7z1|Q`gL-HPxAJ*d zy&5X#)vFZ07r1`F8Etw0rxa3zt(TxN&=gEG&^JhQa`LZ8dqBwv1r;2Hv``~i5Men@YqIVu`(L0~E=$$`X z^vOf-}$xK?|j?rcMdlDoll$n&b!Ti=hbGv^JlZ)`LfyXeA(=G z?l$|KSDXFLqs@Nj(`LW(XS3gVwAs5{9`ppiI{X5sDixxQ&mI- zZ#-FWV2(R9hiD!@0NgPNDTan#f%RbumYV{OJ#r>6kHSAXPJS#ZiGIdh~f-4wH z4A(@Ouh-W^+AkywOQ|Idyl6cqIY);FVt$Et6Ii|2&~-Q7aU3LJsq#NK_{`lFA81im z`;AEJfEftFd`K<~V@qVF$1p*4Uc_1ceu#14U7TnkmIxGl&smvoj~Hkyk~l4}_C2qy~_y z`ENhrrH(Ik<){}>e=}j^O4C926z&Xv4is!xAi=NiNn8oQi|18FgwD(wl^Cx$_b9aT z)0cw%qqq6ghpVyU@q3z7?Tq9T}K z(bAes%n#THp$YkQ1m`PyA8cP61uCT+6WsQ}wca~4bbemuhvPt)~!{B^p9f#jOI8LxhTK#P~B>1s9sVK%cT zKy?<&>7UPl0lykQ%>GnU(H^q-wtQJnp8){a*wV>^@ze8@J?4iL44`_GqT2NB6S+o2 z3_~bSoa(tx#8UI-hyh!<4GfPkR20gkXdrBY308TXi+@od4wYMVe+z>NM8VCkrVLQ! z*{;&WPs0c%M{%NX6_8fdh}5EC~{l?FZcdnSg2-!1Ggw ztf=0=!U_%ssB;Z4=wruI7zihi0NdmV+wbc!+oMG4Z#`OM_4|GEy!25|cZ2JXGnQd^ zN7h`azi^sI#tMV~4mjC2YK+TnBvZ~VzL6|SZZu4lL<|xPc&UK#&@?XaG|)b-AoZp* zu=P-b%55xNqNlC8>_oF}+>qfZHgQT}3^pUrfKjJlS!_DZx``&?&obr|367#i#ApFb z6C;#UQqVbrc9s3iG9h;k6*fDHxeZ0kkOo^x2^VZ@lfnr&O(?;3Gp8wgqb_4isu^d( z3B@p{Z#03S=WM@{N?)}zX+5V~lu|XHs1T;m(nAb;pdhIr*vWiCcZ3)i9`ab-Axu!< zh;GY03Q6JPxaM5Y!tAl!IG(pe#NkAHr-DL5IgLtAzgKfu zfZ=VX#_f_SiE-DY{v5?&VO4`JT@R1)Ea`(s9X`^`jYAYHpKG3>ZO|K39jy)0F|EP| z0>xq=mVpu0s(2t!SG$7%_w`zZnJ8VXcp`azyJLDe8XMyA6ciawv8NmjoDAIlHKGq) zz0SD1c_yKHCTyEP`R`ll@J!j>X|)())V^^Y#Ofe7XNAd+sSjq^EkQSO*{5W}yfjX; z&+DllFX&t}05hqJHehBI2UaH0qYv%}Qjk4&RHaO8UfT4MQ<*|*smW6B%z|c-E9bY( z=GjkMc9^`hW0x-_`Pt5t3-6P(?D)}7ozJ+O&QA=KUgqODrBu^5gzw#l;{~n1IlkCT z-)N>*Wk0=i#pkD|u4#P?`)gLUeWiYy$aQsJYet`w!{(UNPhqe3gl7+~?EfigN&Sq9 zE|r&_J15M3s(*Ur%sExg3%qbvHk6-6Y`CO>JI14 zbCjMjdl{wYjQT;@GmjaMi=$s|Y3%tTR#%!L|4WpK*5f*5%)&=s8p-AQp#CW~?13iK zeH-sPDZ&Gd{I&cwp_c~fq2*MC@tExvl-6#!5E%^KXEy98%f=~Iw0WZiI{dCr>p{6) zT?XvEn0H|B1v9g#HQ;Q622up!zWFbl_VC4_EF$&}J~ina(p$lPrKJCuKz_JB8c;vZ z|NAta)Q%%q|J-S@2GE(~iR&SJ6F#s5)sIz=s}Uvc!m6j6#^G;45K&CE&nRg190*&2 zOv()v7&k8q7n(9F1&spzgb7A7{2;F%^H@7|uJE7}uS97}g{hn-(Nnbmk0k06+N7XJiDDW28gluUdFzCc| z73T)7%#g^=EmBw`)j)OkqpB}HbGJ6@lDx$t-lF=gVX5w;IoC+|sFCneqcWF5jpB#~ zWt$oGA@!S#BuYs*;3z6J35R|91{%#z->N{faY0kVGl?Or8vi?%m|heOLCv=95GsmA zNDRkwLpZa7F@(a2!Ul+I7X=k+i#rRc0Hf9Ir#fc@7%W94C?^O|C1{W^Y|9F#mc=YG zPv0;rOpDUft0^%uXSeZmu`sxn#ia+H9v)$>C;`|Bte}YARxs2skwDZyIpHcvoRB>_ z=c=tFgK(taEX6Z4Gu){r!o4N}SCf;vZr_RZpFt3^tRQhF!0T|!fL+L20@;CX1OrY- zEzk+g@L=Iqb~%A?K<&c`3x(@I^`AIJsQwe94b^{|uJqUdgYB^Z%l!@NSSU)!D=1P^7kOHX7fD{~8 z6kzMU%YdHiT@vA56Zk$vSh?HpJuZ~rdXEd$@5*;Zs&1$l4kpj=U7&32kQkkF_rP*{ zuWl*f;y@BZh4iJUSb3kG~jG}5ChJr6YuH5+h`A@I2c;3IP^4`{E>vr zT%rbamiholE{vZ445=aH1<7Ekzrd0M$`WpQ0Z2{b1dy7gTS)5sDB^tvK?neGK#spq zVnDM*bk8XT&_}TVv?J}E6W7W34#3HGAt3cf4odt5lsf&*KKYJp1thh)3l|f>Fx(}~ z=ry1(xfC>j)Ev~3J5i?gsrMwUZpT?B4*>-~9CHR3u~O@{8?&)!HxMkD#ZKL=1R?6u z*e1^)@-`MfAtEse0Uat$e8^}?fCIpM)wMtIZ-0j+&q2unB129&K!?`dd3!9X&~RjD z4oKGnQDLh9sbjl>I5dh=6p(HILg6?i5zCSz5^Q!vI|!6kXO3%I zb($I>8&{NDw%dt1o--I;F!Mq54PX-l35x6Xjtw@JiPTU1HhlB-+K_L*JjuUp8iuQ# zymJBra?}KZ5JA0Z)7R3LT>DbR`XxycNF9P^q6uSpy{QG^Yq{L13X@w3OBU6`uK3_x zDiZ8n1f1^WKr?vZ01)nS7Y0%8cJYUY&e#9;$rHp?#1Jr-+MaHDx=)1|!iFqOSr)YO z@=~=K!d^`!2-q}tpcUwuGdK!t3o5%5i>uz(K$`6}WAB+dbpiL5o{Q?Ar_P2J`F!p` zGC!LvHb6i$#WXdY4y1iY1M0`8@xvd%_+_(P|5)@z5IZ5yA(Q253P}F2e0X_!1_2(I ztKUI@#Riua=wXWCK8~#*2sL69h1QTK)m4^?LfBm+4|N z1J!)JeB1=f$H)0>0my>vo+4*E(MJ<2Z_*N%%_k^trx2(5LoZ(OvO8>3=-7MY@{p zFp5$2#kko6rQ$nsfiJ6 z5974;)@0q2HKw|aYP@%Q3%yU+7Kf~_kLJe^hu3~s1Lc&4Wk5mmIGI%f112gSC8XpO z(8@JJUs0{XhJ(tf=5#Z`VMSf3@prFB@7HD&T9)||YJN~;z*hkXC+f-PL+vdIi2bU( z-_azRuoBi_C;Tic=-%|UvkrQpOQRV5s#Nu2*Q(^n-?F0mnVk`g%GDB|B@vk}}O^#)mEgXsPYT zJ5YnFHK*~UX5XCJ)kix+V7NlXeiAU;o@PNQyB>zpP8%bX)D}`ds_x!h?h+Z&cYKZ5 zAsW@a=@NC`@`MiTOI#80EPuvWk*X_Z4?%5AfkGITTKMf$|RuJ1!c?s?)2>~~{ zR2JpL0+y}J5W`4=0Oc!_BCcbSHmb&zcsNgUEhjF%k2xnMFSET|y(DFEP(dj|y~+%uqM;Nyf%!j5B1KRQ~f60tsQisrp+D?n&E#~ ztRo};rwLf%hiUW|iw%Z5j;|o%HHesLE5Vku38jm!r6L%S@Mjrw4@DWg)o9K1L^5Iy z_-IY@9GkDqSaY00CZn6U<`@wvR$i&`wkViy;Ghml6%m?NQ`bw$=to?H^_t^_FjjZ5 z;x|vVb)U-((`#%xn1V7jaWB0zR~|>+xOnNQt-5iZyp+rwISEYF1f}*f!2DKaI$b%D;}&+=ph|;qf5{x^y0-L6^>XE_cbCCyffv!^*=sb zQ=QN>k!74LjXrL_bGxNg(ZPbMJ!s^!;3O08luHp$5-B_O)T0blzOUatiMvrMo#^s1 z2%E!VC!*@EMUbC%gIwsMGEI+OR>&Qv^cQX7A-R@InJntbTXhwt8sEYPsk&@cpA@=M zB|03O52kJ{UHN3Gf`UoPh;rw`rPcPQ@G?RgveCUXLOL6(XgS_T=uP1ElGjqfP3HD8 zSAjaXDXga(dG(<9Q>eRv4SiF)Z>pW~K6CbQ^f%x%-6#k+&5c11oQOs7DZHVSt0z(8 zms^hFx5gOsz`P(S6*&p1pI%!Z2&d7L_RIi~KSINT%A*4=o9Z`p)$>n z(_y)b zc~_s*7N0rf{_rT#ySz~xe#U4^Y$dFbHYYw!temmLi~g*LMq?qXx}rjUbCS51WbXUZ zSB&a}=;)bKl%e{zD-+Me?k7i@@|hW4qk&n}8@lA^sYn%BKvac&QF_>YI+4Z3S64W$ zpv)MT7BG!`vAW;XIB|Kbtg5TmZdF#7$MV&5e#_|Tj)W%M=#y;cd8^(*QT?)kY!m0* zN8x!>=uEG-T8w%ufq|vzJoS~an&tVq#PjC7AbyvyXLSiCs z5lvD$*prv3btpZ$BXV2?5mS!hZSzUZF_n7Knx99VC(er8c(-A-Ew%jN5jV2g^1UL5e4nmO#928U4 zk3)p%j}KfwDjzJvs?`wM5vd#+=2GBO)X06NJSEDx555%7oE0o&37$bYpF85=8=B@! zCBst$>-8L@RYX)h<_px?W4wBG4KCBI=@L`@?ON}tf1fZV=z4>`obB5d<=&`~ z+=9nx6@IjLaNPoPN)j+wd-&lb0o8V){{%r+deH#p(}3g{$e7;#tp**ahAoNwfpQ!L zwJbQ>{#D-NA>QE{NhwyYUN!uCiUP97kqNX`Tjhbtz>uJjzc(sKu+gVU%C!P--ef~#vi zC-t`FR0k#$SxF~Vh&xCv?jS-qx=+zLBBvNv?|*Pe^el5w4xFG!y@I=_2OO&&2&5IN zaO#d77K}Dwg@XkukfxwWSb@=ZGBsL3CNa)ZD0T-5(>t;~u_T=K~JgfP5 zb)eOL=o~The}r~Pa&l4W7D)rG)zc9o&%vwd19xY@#l;?7rgD7x9) zgX0Q(Rrko=iP6I_MvueTWjMudopZJY1qOE&FF2TC+Y6uPX&VX-eM1A=-5@ZwSr@>- zR^Wp( zund#!F@cSf#TfP+Gx2;k2%bL6%vu z+`)mhf(r-IpKwg0JHe4gCxC;P0#~&?qU&PRfL2N@0)-u4F}?$8#T5apmQf6lVcG_l zSMw$p0mIBXsidMnlw*2;Aq1b&Xb~um9VH?_fus_G!IfJCO3D)KGSaBq2;>K*_Y#W1 zwCA7*FtXnh1O_Wms?9#NqGP%cC5=$!%qRx4M}VXT4@XHQ5e~|kz<>}U2rGdER$D*` z6SO>#z~TUh!K6r$tC!A(J?ZLW&z^MsVX0q@jK-7AY`IvQuBo2$^b*X!kAJL#&5!5l zL*UG|-Yi#BcN$NnQ8bS5VDfD``F*;=vygD;x!-NPlB8QwxxjN{(05rp(7e7o5*=6^ zQWpZ2i2@I=-cG#;{9fIb zCW?h}`}6;4`_?W;aU|`3`PN`pR?Qa<2HB<)1C1ar{p(*zT#Rib z6d~rEnXW1m&!c-Nbc^8EC`nGU>Sjq(rD#@?{0B%y7-I7hUuit~!*>W-N&OQsX6d|w zM)RC~Iz|m;Ilt9tUaX2|jDqFllD?BM%0{maIjAuasEYCsaKPXHR5g8krOJMqE$7~B zv)Yd&Y3-S4Wwbhlie%d=-+3)spsVmEDtF3k>cFt5!cpl|eQuMnOlZZ~D zqz(`I*o-m+<HZnhiG~ z7hZ4HPs>eji25FB*IG@tFU(Na5dZ1Trt96zv8Fpc>CJj!KWmB3r@N`;I9jsyMptsZ zdD*x-O;LNj-RsJ3EoY@Ex?61a>$#@z-nH~fw)w6n=IU0}#$DJ;y-u)oHoMJiv(yrH zH;ditRI_{Stkrfgwe^_y>*)_BJAKm3_THU7Ye+6Uy}`54YJ&wUlTHt0a=OXx^#q@t zHAEK(ac8=oZ!|jgiYboia=CeB>SMaJ*Ux$oZ8gS)U-r+|Zuz7y?EUtyXPEd3Bn~47 zaewd%2g-x^|Md?L{r`Z-S5x;pK-_(?7aC)E<8gCKN9Qw1 z_t$!+Blu*mr_L`ON$pX_MD?cfjW@R)YX*?q=w)@TTYBrqZnIu$aauoTOFcO~#klbn zy187>t>siJlk3fNXRj+v)B_M^1NY zVv=*+uHwvJ9W6QC4&YjU>@BvIoNDzz_eHmoTxOu}yruoa(o!n!uN9k=^_VqF#x1jr zqp5**)=#Z|vSZesmeI*XoxNU0Umd;H-)>y{r?;5Se|W6F?ADe})pkH@wq#<~Iux_g z=^7n~Zny71Af2!Sd$pHKNG-VA>Fb(LHu{xNLFW7IHyDB~x7Hd6$7br}+1cufI-8m0 zx|-5@E3+*(i*>~2)^0j`(UDwlUZ*;0w~^fFh;DvZj@DGQWi@KgwdAzL7FvRurS^;S zGI}E#J64S-f9*l}j*aAj*B#8+@hv~g+A<4FBjZB+dAWJg8Gb@|IsNx9UD3@0Db_!^m)67utp}m(?@|x#)|{#-yI8?(pHVniMhCdR@}pF727+u{>*S)O`Vd#Z%%n$EKP}I?fG+=Q-Nj6--;9Q>y4pRo_ zW9*-(uCU@B>Ah$jid#oCPgBiGZbKSrispWD(v?q>BQ0`}uyDyhH5w$%zQnPs2gy)Y zdTlT<4RH~RPPci=yzV0EjECgdoX8FdzDL~uOcJDFl$`W(!9Yn_Jy9B9udc^vFqYXj zJxP+hM|pLLL!EXlc+ikkc^|)*1YUle+yRk2C$LN^q$|kz~y}9?S?!XCKFYEE?8`oS?+hopsy*+@&6zh8iz`ymq z1rWdchXG6YitfS=J~OxLDum#I^m0iPOo}x!C&%a$ie*)Z$t?Md>S(nvRL17nl9C*U zeD`y3nj(fp1TP`CVUf5C5~nuC`(gau8HIzCIz|R+9$vsu>X}Z4x~O*!`(b~kDzmm9 z6XUuv)907Krv!t;jBy@@4u?a*DANg;=H@uA#j#kmDImeIwG|E&=FvMrA?0DT<+w7- z(!8Kv$)-*ody&_XVgtUHMSqK^k=EVg=ki*XD_e&h`I}kYNj-~nw-~vk=Jt2SEmuuZ zKvq*4eR@Yfe2;XGX&Ok(GNf$|Rv>0wd?a9i=IT1r-)tA6nuc;#>hHf~fZh8_R+Cu2 zXk1c%r3I*moSfLKL2}P8JpC=<>isQ5R)0}a$phAY`GA%BD65^5EcSI52l+*NxkCeH z0s@7vC$2-c`)F_`p@_29Y#wkbePU#9zvo!`KRx=U%nF%|_X~A476Vag|9Cl}VA6`4y2^Q-`tDWT-Z$ZlyJ* za0))ypa!QD6mv>JA*TWqvUyJdoA(s96;C0XR1I4|$ z7KTi{J=#J*snR)@5_=*E5?Ebj*SfEmdc;K#3gFI8Hwr=Sn)sT-`8fRGRh`F#1LHH%4n=-F;CeuJBBID_aDh8!$xxS_3>> z+8VG^ZsaFH8kZMsO?8VEw;FVjk@iLr?BZTgeCcmkl^36CcC!+|n&|i5GNFLGY9-_X zQmH;)?23N)x=%&8$X>w>z5=SU% z%KC5n^k{5v_LO>&}Z~U}kb|L?H9wJqT>BuVaug zGP4({eKrWCtfmPTt8hR*0A>maSHm%OnB)6#EOlnC#@G8JrQg>&7Jz zD2#b@kFU^(F3+#K!i}ObCuq>bPl9vW_nb%rND8*utNb`nnyd;5> zZqDD}!17qXh(kgNuC6|!;_M+N-5Y#UYBatrJdgpcdtaj@Og|_X3&w?#Rd(33!e+m1 zEBOcB@RpOyP4ZG=PD+FW*+!QPK>iTI4iFzDQ*mV`mmh6EKeEhg1cgDGBEb-_M2fW81n<|L;=4qJR^QlQRi@ZsxQCudl4fW$ zk8*jDzo?hsGa@T4`_fZT{_Bohvbes-^f)?N+#_J(XBkOk{Za)C;xr)`T$+6$U?Dk_ zCj?HuJ*R|aIYHKo{4n_*_jW3aDDH3T>f2*$*T37BjQx)rPyGt93%|oH*$4!pRw4s- zQf-xM!^kJod!fn^ofIk*cHHI^0_A6q!q!3HqE4McvAEpwt@Sopib7Z21B|VANIk{f zLn)SDUt{eWy!j_U!fbdP)BMuk;p>l&J-+$i=fRnkHz?RTPnP5j$qky{VF?L+E7HtM z#ikLFyUtMX{OP~@JP07e{1GL;fAdHf6$bE#dXdyu{2&^phSmp2g~L?qEHw&{Sei*2OMH54s_N(MX8U_@<#kYZ z;%wECO13@}puo?3FeoIlqg4fn*>fKx4x~3?6wt=WE(nyQi0a5#b$ejcUu6W(Urve~ z4#Ko?E?qn+Kzut^tPf-IPGUG*dW^0FNv`IpKn0>k$|!^vNq%8X1uBmJ0|j}my95k= z@nF$o=3aG%*SnwffNajSAJr23(xa95uk!be9aJU$AyJXdPu(SZmPhr~t%uBrPmj5& ze%`VXRD5l7;Y+5szB+Ijj{Eb!$hxWyKBD{*PqSl<=Lkw>!Mq!gWTqwQG=wJpw(NZ~ zq8!&LuRgF-MgS;-$~X0(kD>mN?W!_FjelHk)8Eo73o^vGEQC_jGI0T-Vztl|V%0jZPG zL}eteTpZo^!M@&pt#$3rE+7-P0S@={4uHo!)2y*B3fw!pV7|F2{_S=zWw8*2(YrHUOfUC~?*dL3p$G*sZQ}~W-A&sos zJNkpT%Dw2VaQ&#`A+{eL(;(A8|yOB?%e)an0Rew_-_1qLChmiR0kceIFV^h4HTPbo?u+#10i1ScuPk>r zt)i`t#JOLOkl9Xy_BDSmIEW9qqzCX%J*_W(p7GY11m`FYbGfUdF2@77(aB&Scd8+G zcBF(>dWhn%RSjXFs<+ol;PtjE7)r~G_YzB;^Sxp&kL;5_oF4Gq&kqAS>!2UYP`Ny`4&MSSU(pIDcAs_vUgI>0Mp zQHK)M1}vjv`bU$w`+24pv8`Q*!cYk532BP|U@|E{$5OJIQD9`xrqvKHNgK~N5M&cy z0)olP0s%p0@Gq(N6a}d8>6;hI?i2L_U2$d#>lhsjw0m@+pa#DKf@`&l2Q}m!&?sR* zqegu%ECRM@F8rjRUCA`7pBz0ZHU6nbtBIeLVMn{r2Mk|HNxe-=kjk*7N(?BqtM9Fc z+NeG~)JFZY(*o~DKo{2mxZ=ng3_Fm*fA{l9?ki0K49=U61GWK&Au1q4u9We>$JxwkVB^1@8J_uU^ z#PE)M>NPBA5pqwk^iH($3@%%9$U#-C1Q;fTVEWe$`QxI2{WR^Fx^vPcn@ruAZ4Zmh zt*8C7hS+8|T`q^^G*Yym*Bi&0O5~r*!^b6jqCSCEyaMj4qdb3zgHAecDagjU`7yD%=h6+ejNDf|P7?rbn8HP;~ z@|XA$kmyj5{&53@W)Ymdtojp}3?=-sJtUnr0HQXaJOIVDI=n+pP3sSS z7<%W3S-|<1G_fwnEm*vCZ1CPuH5jENLCh)|p9j7Jc;G>?K5BxTM|Y1-z9NpdRAI4;(#=o)R(kK_+XG#N}v!2jYMTCWQ*f+(RRFFZv= zUXaT0=nn24z^^LA?|xh=ma;1N#sBp4-2XzOL-LnF+Rfer3Vh7d zze!R*T|qIlFIRBrh#DlFs#g00;Iuf)FUJg`O=@gtn_>XoK2e3En}OJ~7#)KB2E+Ny zNPJjYN&xL!1y7+Z6le&Brez+;EcxnVkA|r~I7@qF@4RXMBD{<4gUvRMg#&K)DBOIy zo1%aV*ZwyytKa|FTYC#vKPzjs+|0h?u)0D4l;5*OLER^G_jT>(t+k%p>t`H%H%0be_jS5O0e`Sj0|$EcdSS2a-7g?? z?@pgB?`gApK>=qk_Hyo6YZTbEmJ1Yc_u^R7ISe|ml_|yXJNVqajNE^g8qB7vi(;Eg z2`#CALZq5u)1-*(iYF-{U_lVytPLOM?CbZ(X}j}n*8Z*et>31(rxQGBnLx5!CRzVu z7V+gVo8njYUr%|Hw*$UKDLhr(VJKV7_CHw>UmkK+{VM)jN}L#WfIWyw;3t9PZTkRH ze$#OXn8;4ubb$VWVzBL9=id7bYOL%X<2{T7Igz~DtG_)qVEy~h^|>2-7pS}kCr7a{ zn#QiBxn$8>-pE~~20VgpE4YtiuwgKX*uip$A~ zJ6X*!*fPPO3A{N8t}zL|DG9P6Yh0dQjv*WeZ+?Pme1dLzV$$#`b5??RW5!xizHY2vz}bwTRRiD3yWM7zPUCYHDcLNt#oIX~MortP}p_$*07v|J84x-f+mlgMD0w zgP(1`k*^V0E`DanGT6s-NHltY4o%1Y#FJ?CM+woK9Q`sb&^={dSx;l(hgFn>$1=)= zHA)`73uTGU#4Q}1i>*mTR6s*`ntvx>CRhz?M}tHd1k{-37@AYCrc4iif_MtOM<+~> zQ|j-f(KBh{AwEni;?v`tQvLiy!}-Bwe?Ru-tb^@<<_FP@{R@F2QSz#}N(Ga~FPEU2 zU;=$J`2!**pOWfkUwUer|Jpq7?oFVDUFH8OQ|XhYUO=0z$Lf_y^G&FW*wT{^Dml1~ z+W^Fo^oT(T|B^BBWsaIu*!DUxG*JNzMO$F1h?_TJ7Ymx>C{eiwQ37d^lgb|w5URd4 zt^j6f=5?+N0E(IMzFi6zKO#~zrjE0cp3%uOD5`zXJ)(-!i%IfYL|~E?u({L*NwUo+ zFvSlZ&Vgn=D!W&(*Is9bQlxo^=uV2u^A7-Ne3$A|&m4C@;if9((ceRZq zxv4TB#|7TID$K-xPot1}O_Xp}=PVNnCE3eWXB}1T*L@A6YV6P$R3w{dr0=R8AgrJI z5``~5Ju3X_=h@C#dQXlu{q9*mto5$vhE12?9yx=eUi>6%JgGh`1o|O1zeMKnh@uPq zbZQVQ*b)r-VLQ7$2vb2Lmjf6$l_Y0}QcuLGrVgcmF^ z5l&6GiUz~3^Qt~9^Gj(YF&QKZkD*8TBVkmE#aXP|-=Y|aq*cqoz_}k$g32&|&Gx~J z<1+J(AsC8jOZJC|-;tMD0Y<{h7oGTvZ@CvfIgXbtZ2TpHkZ4d;hgSsviyTue!eMsZ zVW>8=kenT`4?R{b`_WoYpO%)lcbP5c+PnUVt{}H*Oty}-uzy;vp0pr;>i7916W7m+ zABOzTFp~H32aM2G1sRBq+7IMGn-0E0Yso;k6feH~tl?HVu5Yet1jG=s6Yf7FxC``< z6CQRZ3CREBHP821y8Y`?WRm;T{L5nx6Ti;+*#grjCzs^!l3UeR_!YM;bF$6T&o6C+ zyV`AMXFo}*E7(vB?@IFPR72n(O%gQt_*aMrvn~?zJ3wfHj1YXe^B^kNDu{ZoLwQ4pi11UaJY1v zFu~r1{iogoeLSdmnXo^jqnGeV+?e#wKK00Fkzk+%mGwA1MVREIK{nMevGf?~+-f-2 z*eK{=1kC{g?iE885>pLjBU^eePX(N^aYK?K3dG5)80T*JaVgHlN>eJ)=RQ+5KTAicauVgx?j`+t}e)J(n)LGL3rNJAKJgE|&9?Mbv zJY9IxW$*rb2X-qzo326f_S)Kk0sjIamiGEP2(X>bz5{dhhrOLSI|qbu<}OHnzqWsZ z06$#G?qomWX+E9L9dEk+1;z-U%=#$SNxY}o3I?#<&29^W{NHc?`}_aGAkOsFTg<(M zGhJCO9QuD7d+jak<<4>-=#~5IEi0D+edAeya#?4!V7Ql=Exe|9a~sfMIjSlc48xBM zy*8Ab9?ss(c1!Qa%Hti_+PU7dwX6D=H?!yZJT=6zAS0~<^0urQZFeU*!R^Oyfl6=- zS2$as@^ELXszBcW7<=P=x2)}SY5%aiAJe4^!!9?Q?Gr1Px0t#+R>EFy8VbBK`_b=! zUWQ>^#hWcR)=z5&M9rVsXa{1}8~Ndn0>*R%6fuWp&9(l3cBl%sb1YarEMevW2f+I6 zW;Oje+pO0R2(u7oo0YwOmbjFX0mUD?+H0yFroG#)uYBuZ*tG>)+tOh8b)QKes(v2Z zkGZ}w)K7qs}0NXq#!Mk@1fhe)5ia;4DZi>}s*Ikr{jUyFc;s<vA0cg369|qv%l6S zlyEdZ?rr)!9L@h`hE7pKfPp)M90-ompokGT?y_0-yh{n>&l#FWF+iv=cyPUv>s~~P zLS;uuks`6p# zR3tS~Q`AIFwQFTCt}Md(bs!Mh#D)PYo6L`Z>()-a=&w|++Z&Ptt4cs}Y*l~c4p|%? zcz_o5qZ+yG*5%V6;$f&Fsxn%jglF;Rh=i<5D(#~|KE;J12*KnwUo+(;BM>p)L*ZAB zbSye;&Nxm#yquIg@J_`)4)LJrs87Uu9?PPr)e#7}Z8{!X)sMY)cVZm6(epQ~t#t{T zi*Ms)v1amw@1gcZuXz^~zwn2aZ-XES9SHVU+<+Wn3ZT0#8o4ci^Mgq;CwPF7uWGabVGuGuN~FQeETi!|qk>?-=S z6Elk4Y-==?*EIXN8I3Ev+Kf^+rX|{mCtZfM+meiy8`By##wXEd(}#_Ts^*5%+RTjOZJL&B6_lWy(Q=Jj(EWm}%@bWDklUO1vWX6Y95J zq}RyQV(Pr9#^r^k)d2F8fhe`8SYE>Nf>&)L^|YMn1g>Na2-pDjgC-U)wm!^9U>zCw zoaT%rH=@b%^d$DP&R63YO~!gJTUG|XVLemRfy4t}kI_;^TKF;dFqxbb4?U$st*X{H z2Lxmy!rm&kU&ap?uLYi^X7wxqH2LLq-9Z4z!-*~{i%@L(E|=` zfSOeQs&>wU+SMhf;vZ?68yg@Rn^`O;w(R=C6^6re*7t}3Jn>^3TL00cjA4_JTv%J! zENrKaYk9NHaxHs6q(;uI*>d-53xwu`$D-TvOC&)WgJ!xdw>x~cW=u}F5<688JM9FS z{N#;%0hNOL$I{;M>gj)-HUP7q*Zpy+hk%>!5YVfiC-wCMP!;-F)Ef7?X*DrCD}NCe zMHDMJLwn&50;^Y@jd5Aonuo>_DTImjS^q+dub4mze)T{a`dJ}=1u=+c<$otRf}z&2 zJj`otTj}Qg7U?y2<8|ScGcq1cu?icii$mlToJA_}u1b4ctFqswOUv1@;q1;Fd%LqY zYwu;cp1Uv8@0Pci+RJ_aaHa80l07u`dS^N7>C&?tXX9vbu+>&EzcrR0wAnpq#?xJI z)>^p~!W)sl{%5ki0LS`cZ#&jp3&3h`Z7sbgTLkv@q*KTPkd-|;a!(BdGxj}jZaH4S zz+RDhTWcl$E*nVq*q5p6O_$rXP6oNGHJiWa%C4;+EN8P9i$4e4tX8Z`@TpiEuAeJ+ zZEK6V%lB^(;oo(IcT4yEH;}Lg6#oVj*UI^dT-e&=$=+yakj>pg?Iu9-^twAxIuy3^{`+3YrK>8amIZV|tOAuz;l=|bhb+0vGHUr@p- zJpzU4_2pZHhr#GIPMK#ZC6lTOyy<@T0)f@4R2Swj^P6A2)9q|RUKvlm7m-m?hA9Hb zm${`jgmq4C+5X@+yR_Vp=@K-T#gtogP_m9=Ic>f);fE_)I^`-p5vqk2JY);6P^xEc zbP3Lct@*nzD1kW^7mfp8C^mTV0vu)MIzk2r+hp1kWuP9vDZy5_*mAs)uQ)w}S)moh*{k+qaPYbp$7$8I;Vc*bGrE+Q?v4tyDlbuDN|7*l z5s7fQO1|qqaLYi+K*f#`POpfQ^f*hr zrVuy^tZt~hY*quQ?#`KCoN+`XU;~O(=Q}~c6XRN_?p0R0u5$+f+@eWjhNp3Q_>;d3 zSNj%LQ`C3I(G+!a9%KJxg1UK||>e*@v2qoly` zz)Y4dPWAAj4=Q(@A(fs~id?(nH>mWI<=4i9L0f|wRxpVd|KO$P#j;jY23UJY^KL$rzCBLfI z8-wE2X#uwdim;pZOkd>H)z<0$161a$A!JLyy=eh;-~$N{mq%Z*gtwtq*@9Y zwmHJ=zil!IpIbld87}3y?O3zj#`%RpTkDzgYr8{c`^BEmtu+eDuNgf%_U@O$ZSo+= zdgHA6F9c~ocODPp%TI>v_1yZ2tO9;UJahI>!XrG2VY65)?KQ6PS*X&bxVkdC z-AKX#4>GtF0sj?;|HWnkT+=fgGkvDWZm)>I{fOnx)a$C+O`pB#cFTRF%c5co;#ZqJ z>vMogzr(w~R{CkX3z6UTTwlD>g8Be^wc79a?GbInn$-ZP2=02ibze4`_2uqZOWP|; zTY3hPX1ZEi_Sv3m%i8OWw(M#%*U#_@R6Iz_>^#^0w?6e=yEfRov{>mjw`a>@7W4`) zo|fPBg=a60zOW=9h(vg^0Z7}6jlS@54Jct%&wb`qzdT=Y>a#o6v%at_-cG;t>x+Iq zngOF-Og^(}vpdhuR$qA2f1#vbc<<_W66f{jGemd;5#DPHyY&Fmu4}g*Wcq-5paB5& zVADr5BTgTouk4v{Jw)}{n_;JqsE3|Dpc#Jph&`mpKXyO$h3mnsot0O}5PXFU!Bh>7Ux!*uyMDCJtTeG6-a$xCfh*du~$B_p2>H9Abeoz-BxBW3QPV zexs>5?bhnQQBd!z>pO1ZD9V6Ty5&)Q?%nvPKdsaJ;>Yud_Ma`@aY(_FAe7v?*Jcn7 zt*Or+*6 z79n{zuiSS(XH6Z9&`f{RAeH&ER+G5xU)6_MY8IAyPOdJeBnnJP(5(zO{@4sYIP^qP zR%v+@czBMppI_3%h$4;>;^$sYPMy0Ha2k9Du8IeX^-g(OW>Q~*dK~BIbT%T0tEce@ zyn6aoA$a2>IXC)UNq%N(mZ?6288q@D$WqdXXYni;U6dfbdB>_-PRa`qk)3@Qf(B6pLWCrU*z69&M5m|#A)=7=-sl*CI&egpiUlHA6%#haf-qSg zC5pHt5){q+0EQ@{0+>dbWuWr^nabXo^oqxSmK4&C(B_EQeD^g<_IrGdZuTC`5s|M<|b$2W~$|-E|Ien8Axq{q=7k z_2Pv!>cxaN8|~emR>8Qj(WpcSQ0Ocekgef9(p-MCvL7YPU_iOfg8~YKZeMTbn&xBJ(x29 z`(hc$u7~qaeM*u4?6$xjqo&0@06K=JWHMJ^d6)raJ!ewS^GdV>qvY=f@Fv z{WN{r{Ah0bdt1leh=&8S<<#wcm37B?NA_g#hg~C)%^YjGv%Dwv$M@;$^q04AHY@M{ zHcx1(`XN{4epPzWSBq+Gz4A8>?q+Gmv2`{x%XPhHXS3hpnKs_5y`FDg5e$ADlW<%8 zOMSQvC7J{m`9okZS>0FH8P{%6K%pyQ#BVaHqHK z%jOkp3w2m_bMEthX<_rS-!@LHftsR&o`fF@rDrgGrn6gIeSeI=WhZ!B?4E05V%T-b z;%wRwEbE)shKwKXIsJGQQ903U^UZ#T=|uB-nNsyb9D}{y?srBEEb~Sbul#)i2H5`9 zWKFWGJc3!DS(H~7E{#bH7BzQ7MhludE~B~Vkt-c5Uqde0)MSAo81?{CtSwCO*A{{^ zoSG1EXn5sS+Jq!86Ac$U*w?|)1f*z6;D>!r)ESZ?}*Rp=6M4;)j+`|V#N zkbL{c2qeFM8-c{ARaSd!!>*>!_Dmn=aes)aNUtgw(?Q&6W#d=~1?IP=P~c70B>FNvyflod8b zq*oB>wnINk_+>&1w(mp%x>vDZO@LM9;RY|H{ zPOxZd0G4h8tL~2G0DVA$zl5L@77V92J@~O12M zcL-GFUus=w!xe8?U>wN8^9!;}+on9&ZD>G2`Hr*+Lr7Q~a3{)D-^3H~(Sb*srXF3Y zFxhwpF(UAA(@w=H>S2jzXon=8A}2?ZlO(`a<*u0-z(ZRgYY*~K9Ofi3$U%LH-JD_I z8oWLge}t2yrYv~Xcjchs-^K-!8>)I7Jlw<>EzL&`p@mV0}d(IxuZj3-Xhw=#n= zbS#e6B9FWNh)H-w#^mG&UmxNWjUK6Zs9!&w(@MG7 z4AKUCcEX(v<9dJs<8Ft37e^MW^*Uxr{zr?ewgCr?*h4?`$?@H_%QeUOWn(#K$r z()uGpd&nQ-)GxFZUL~EAEN8RMmtMBH_2tvABsek6%4=U+B@631&DrF}tWhsz{gpo= zVIBRA^>n7_v*HY)Vq@34_@6B2xp#fFr->F53Sa&n*q@*xuwjs=QONXU8{JV8SqEK! z&LsnSA1jnJHX=fXCMRjwXaZ z{78=wz(-UBXJIYA`;b=W9UM{%wcXK~gLQyxJ#*F`_Gj`5nBpUTBbfDoLi%F$0g>pd zAW@^*#pGK(QNrCn0Xk#s(?aMO(gfce%2b7@mzY|@?c4kzX{NE7M@Jf>{O+vg^vRZd zz6j)^B`gdWtr>;uX;0V8(@metT_+DM>3WkbzphvYVX|+>dnP~bZK}LVm z6Z@tm_9Y4rFi9wSwx;9F*3@XWrl|Rkf@dI#oq;HJcA&u7;d*Iqu-Th?+8ToF8+bu; zy>d4sS)BQCw)S+;s_C``h7h+KAi7lvnEz@~?IL{mc>-9_v-$pAYhf6q$uT;~cHXM5 zefw|q7f&3Ui5+%+;zF4oQSQTZ32&JyJD&g5J9~VDCCbeXEuwcnH)lYXrU{2uRSK4c zyHn%UVO%H8EQ-Zm$1#=x5AMvlDEwUqMe}?WXEtUBt!On%l?Qxv@>8)YBYfv5#83#& zP3>?4F~q4KfbGcPEh^%ZHaNZ*KbYhHn8!{w0n zdUEOm<&AaKQ?24#PpwwJ&#s}xmG_Enc)A45!}tY%Te<7auLRj#X$4_Exmi-+viiK< zBeMCzj3$!fQru2|B2pZTwk$=u%x?BCIPA{P(ZEI2f7m~S;pZZ~hom~dw$FpX@~fGH zP*Qb3Bd{;IY^aOJ7o6WxCYOWcVu(JRqVb9JvZM~0{nXh0aC{t5WV!`Q~qN1-Enh~IFTj+k+p zW1+Qse-t!Ar+SPKqo~DVTQ{O{g0AD7oUl;(b-_X7D0wsLRjL?4!(jdd5{)*>_XyfY z>3?hxT%>3v)SMQe(k%@XP>HJYJ%2ThuoBsdwxeo$R~Hhb;yJ)0hQtZs`|k<(EBr|w*DPsTcFEa*u@WjA2BS|mBjG^SQh|DP7N&YoPoeCbKilt(| z_)wnO>mO*E>Xg7s$SEx%ak?%%032j)Fm-svy(@k6C6jOB)E|4aZ2e))W}c9HEl)XM zp_mkIsBSpiEKTDcmPfTMrD(D9C})Z{&A+e&xFYZ+BKv!77-O*qH28WNYyd|je|Zb} z-!VXn1>$g>=D9a?dO-OlN~vT>h;Kb3qWZlE!rYIfW=iA+bK~cJ;P!A5?fK^ zDBwqwD17EBu-t>0xO9twBJ)cT`K5)V^x{_nemG$IMigie4YMsJ?oF&zDbMQ zthKNwpGLus{o<5K(*Jf=AKkcJ>6tO46fe^smN(zb+?`{upIun)?e)%b*4EDBuGIRy zO)1dJsq<{PP|#-mj7)B`**;BY-*M>G^ryG|@+j|wUIE0~uFIWo%+M9R@{8aM?jAL2 za^Zg}qR!}2$hKbP@U`{Ba=?RP`@8`H>@9at^3!wee_Jr9Lugv&0hyB|k~`{B5V$WJ z2RQ)T)pWT8j{tYW`Y^7ruK!M4;e3(;yHW?q>~C7gq8V#aQ1*8)zRbi~<1F{-*&&Ut z1{7k)>e`!6cT;a}JFuD)(3j21!a{eut+#iU2&lW?Zh04jC(Qn_@R?17>DGS8L*41$ z_ES-@RbvokenGq=%TAdS1V?_N!b5$vr@%S_zd@?HNT?t?L?=HCbMer+F%-ZI7ji*j z>!&o{nZ!+$IJmuW$1-`U|IHhHRtIqc42>bW31cF8VJA>K-O;g;ozAb3Dr_ zfMa5pP{@|cJi9*4vw+4QU))Yqlzj|k4 zHp|{{OlC3h6Z?X&Ja2jCQBF6B`$f0){a`fHG0jh;Fsz&AUrckc4p-OGIF#d%@%z|b z^_btwz5-*q>dlmJo{*H;Sag&W=453Or+$cF;f|ohdsf&Qf#LoXS{e+?>xFaeYXOmG zUQ&;Tp7Kw`<6jUOuG-qb8RC3h!>stS|DLP@7g5TePH{hrOta_S?Q?NhCX#f(MSud! zPe;8nkDI2zFci_n8+CD&QZtp?;wM(}9_4AmU#$M{^XJmfL!h!$a`BTpsNJt7EE6Nj zh3l<1>!~}lZCHowP%ur2m{hI=?(~N>pS{kp8Q?n>i?tcrxE5-f{d#WAHuGt}8)_Jn zxNSZPlRfK?{-(te_z8Es#V?i_j7&lEsXU6&Az}73Q{2HvXvD%y+k#CZ+-0qYGnB7n z$Iw&x576VF9-G~G9BjTGBngeUODPjZVZI#LTz538sr;fknARdFYVV3z2Kp9dY~ddB zrzs3v^v{+cJpei@Rt&>IYbB{lGMHwRXLjT_V9gKu2 zg4n~_WDK0$_yL5b9i(|^zF=(}m>@0EocvWrIiYx@XIqx#{r5lrVL);C`N zpeXs1eUFxhYITBRD3hqbr~eTZ=gPM)F(4@ZhJ!2Lhh|Hv8;<&*rFqYcK9N(Arf;Tv z-Gyk|`N(z6Wy;S(QP#ONr4r^{_I4VDr}}9WDyH~G%NFMvCu@8#)V)O9CT5KqnsU<2 z|48tyDLg(j+ej2iKrSj*GitP!(-{>7x1*z@cgXp3aqm*bMO42a=lfLLYtWgE8`N=Q z^#Z|A|8zMf_V&lWJZsGt)4*+pTOKwYgkG~3Z&0X;h|Le5o#z%Ne8-B9*|6i}ue(ed zJFi9VvlT8$>bDvRjxjI72y@0nKbX~yTlfiR#1>l!sPKfyhDqh_EeiPtL_jbNRXIiC zgUo1v+|$%YL>k|W} zoCvP*Is+{alr4-a(`|$*aTEX0JfwPPLLGRuj+OQz9g4)`HcDLw zXqJo_qme?1=x{Lmff&>UF9rggmaL10F1h&GxqhnwYe~@rbtcq~y;L-_l+6vYh>3d0 zi64mVKX@fvDU!5^j$h^sa&H29EIDC|5NcEuTz|O5d&e|~b6D@S&I7fhKutuPB4m>M zvKeX!RcHe!uCAA9_39r~O&o;p=>pB;Ur54^4TI4=(?J#2F)OcQmS?tnQLH~IyP(oYS@Lu79#>3T@V(rK=J!_0YO*}gK-d* z=qebZ`bL}z-vs(o?-i>UNK#&7$%DZ|VZoH>Hts4Gd^1uI1nQs_Lugev2_?3T{R`@* z7k}_fKn15p#ia(tWrLaTr7Dg#d(gFC#K)yE`|!9b=0DDs{L%f>X0zjSZ{I*{p?8=U z`}xJOTnJ>fS#NfmwLL?DJZJg}0dAem%yM0Cw%zlxdG;KLUO?m>Yr2G1;cjY!#94h$ z=g9Kxx6s^G2>n|3S#%owMATIPOQr(? zRX8ve486YAF8*$oX*#l0e&^;vJSwDyOH}llF6?Ld%B2Ilm!J4$k>>n`Pyez-1+88a zF#8=2%}GZ50*>ocjwY@N6;(8~BWZvh=rxo2m}>@gFmF+#7a!ZY`u5n^_3zftnZ-kx)-o-N9Io8t0?-_zB&wXD8quVQcS)O*M^h%{PW=!S`@h%jIV$>UF99FP_zrqS zPn0f|Wu2>o=N^^eUA&i|?kU`V!o^QQP|k58NBT(Rc45P~$a6P9_ zm$M%KHEIUG2$eq($R1u z<@yM)2IXUL4>s*H9?*~6OcbpBQbg*RgMF7aEdTbz9|}q?_TN)HU_}EwRSf_} z&-hEnWgU(gj!rL!6rD7ii`j@lVdqhf&NRciV(pF1cuOE3hB_R(+JPJxYkl%Hs#zI0 zgT?Cq3yn5RKg};F;0wCl?IbIUP3=D&j9&T&660%3z!%LF1&6ajuhW7&)i*f71S?Xg zPbH*CqhvSYh0}^8B?`Xv6B52gNmw1^!0~BTX6V$b9*%<+p_yLZp}YAG*HUP0#Qs0K zZju?m`CmOh3=dIp@iS>ebs*v3wuCm3*q#{L9MEOEJBu=U^MZ^Ga?42BBa?>iI?L=xo zQuqgR28yHD=IM!t%d2+*z+JwBS3Q}6(U5EmmK4e2W>JDwgf$kg!5RXz0&|P6nBelx zkrPd0Kuy9%1$V#cRTtLAU~0F~O^LK7ST$Abf7NcE(F|vkq^`WYQU3&Y|~JmB1q%%k{FUy*F23$3O_g-l911+ zcA9EHa!iBLltVni>D(4JpgMQl=iph)ETRV*ZPd4phNsB<+`PYJIe9mv;4|9@dW#Zb%%Hjqhv4zhi_0Fa zoQ%+Iu5@UtwTG)nPp8;CYvvgmZNe!0lkm(u0*#@Se#3S4O()gQ#$+yLf^<*QzV`)fVZ z7T)Pg!gBFCwY9ltwlmwW7E9|V90AJJY_sftawioA(yvxih_JQRuA{j%he&S#qWh<% zEYR%3fD_(g$Kt%O__#vvfu|Hxm1Ks=3^2xPaZufCm->y*WkKZ5lqt?vZE27S zaO~$7m=3riV1)pTQwK0kU2A1)%R+1ixYgip7CY~|_3L%x%(XE98v|@zxH|`6E9~s$ zT)W@wer+ueXc-EO{k+~d+R6NQ(ytya3#uOWUr***rANN@3fI4cVjufgQT)S>|3&Tg z`iA2M9Fjsj#Z7`VRD|}B6P!pQye4|$7YZjxGr5y_IjUP{Fl3n^u$Q=wCE3$H;#*Ji zRKM>wtL2=q+9d-`)S>C(<5ceEP=%q|pvIlyW6}7R$AXDpXX!g@_7iakE#sp1QE3M* z#ZAgAl3q6`$Q)sPB3+V|i5xE0eB_t?55h&i?+OUHkyvf_0f9-F3 z@kLyhylHc&-BQcOHA@JmW6_rASvb>M_)!XNaENtvVtp<@#Auv7d-&-j^TQ-N1} zWn?VA?%V27_>dz*N_CA6=%w{j0dr3KbPh(M~$76k(GzOb+ zem6>m3E#$JWvh7|3FZ=^J1P|{wSQFjdOGpi(qIXS0|tE^B4%iH_)Q2$J4lg4&E$oI zquZgzDY5#zJyq zzOm|9$7WEnNFOh1A@xkZVH(3yxQU<9b6TJZ(tx?QNq&XPD^j^}qD2&zm&}l&_AV#B zQA4g~Gsl2}-_2l?s?-6FHc_ik*(8053gZ@^Tx$r&(-aKXbsF@f4IyKei-|J8s6Nfj zR*MY`5O()Qb#HfZVijiufVZhZ! z$Ii!T!YfOW7Jlp{Y7aL=tcrub3rG)t@)MbxI>vJK=y)Tl(7TX}+|{B! zQT1;_wulNc#j({8gLv%hWyD9u$N$*&dra-(ZUMVCF-?pc z!3I)YJuzQEh1n1r*fhcgzh4Oh+2KWGW zAd-X#y}(g$tw27bB29ugf-1cuP~GtYA$lE$DNHvBD9z#em|LCj`V)Tp`6Ppa2JOTS zf@M&Z#4s35#$mi{@El$ZF#s$rQW&E1su=)^LW0TOIlVv;Kur-*xUPukdqkrHv@kI_ z0yD?Y=%D>42ByLHE#fo<&YSQ#DJd@zcS8t6q10rWgt>o$V&2FX0wQjoAaI>nKoBGn zRw*J>RVoA9^@B3tEC5!m8NU<@p4J!&KGqpX6&6|wDuDwkODPx-sgAKFs1hchGiC25 zz^rjE4m@U_hgb=UeIEn_Gu1L6Yg)J}%bS?K00>aNDh|Bov6?u;5tu2R2WyA+*$RW` zw!-sI%+?yG7+xVI8}^6tc!a7k4$Z)jk2H_NAWd^trG7!+HS`Ha0Ou{lsH`kfcyHve zB4-NZSUWw2VA;z2==1nNP+10a3 zlHj>|SC;0xI=TBdba&@N;-60?(=So7sB?mVuEfa*1UMsc43g*7RwXkh%mRxtU?FGB zl-x<$KndWnz~knz*TV@=KQd2CRx1ROzxh|L);#9n~8ie!f zmLxY}5EqRN@R=XH`6nX^wqk%*!a9X%>~&h$JW3OHvPnQa!xhn;*8FyOCcE3#himU% zf%?Wi=_qV1MBQg`10`r?Kgi^jkPolQ8UU2BnVH{r1_N_K)A*fu2cHssVB;^g$0%c; z`m8ek^YlQ)<0e<)<*oznqLL)#?&QM$TJMK^frQ;62gq~da#p?LT=|KAlDv*kpj$Hl z3bYG`JH!Nq1E%-kM+Gpgrzl}x?F|I-RS>t0=%xvp`ElH2O|Q{rXP=qom9uf(M7Y=w zAJ8*q{6sKx4F6fL*}Mlih*iC zg!22&40&M2q~XA1;yhP?zEuORx>65TFERi*s}aEBul%C&Qmrdripd3$y$a~^fu95f zgM_pbw@kyG?3%F*MBWKt-dK|lg-zOvNF9DrB>|+777nYjD2LclRd7H^FWuy9y+lHw zn%(-je{tC|1%sLR`H3o4H)=4yor{N0Yph=7w6O1OqPoELp{j1}9ELyRORpts$no)_mqn)jL2agV>eQZ=rpX)$dUB9DXL%qve+hBtWiqo3f|EDrS{ z{7QH;^}|qU9-X2Dfx}gfcxTC4&^t#-0mSlGm3&O7&Z_&7Nm?Zu@R;`oP%k7w+OGNZ zNt()np>j4x*rCE7|KE#e5@=Jk(1gxV(7kvJCKf4Uv6&xmEBfG$Y2~(P$ zPa{83UPu|_VS_f|PvPUn9>$Pd<3VE3mx%kf#i!o*u0dg&vZD#gOS8L%ftNw({qBA9 z{;OwN9|k88|I-tzv0h6;M!}YqwQtZKH6T9r>454(d;fv`V^&}Gzc(&!S#IDqO=Etl zBhDwHbX*qxzPCE3VHQFn2~mon<^N_2%>B5GJ7&hr>pTBrkn&U5yn9YH7O~6~v4YBd zi?Uta%liCQE1<|e(d`7{5C_=_Zh4F;_&UM*t7KZH_*%%^ENgKI1A7`@Qd$T?Lnd)n zGX@b~1dYKn2FJpWCBbv`Ii5va;d~sHF$!fTrUcZOz)r4@sf~!%_4{f=l41;w5%RLE zAJ`dEjL}W_QPe0r>B+Q6t1>R4Wt5OH^0Q7y$PsJp@l+=x8;QnvXmgIS2B$bII!Qtb z>(e-XL*WR&cTz|ovXjM3`MjvRw#mzSpPEw*mQ$jhsrCv*%Bv$hgW1)G22^AnOo zc``tY3oZQLRjd&_Q`$9SsS%GMg;-fsxxuY0?wAZoj(!vyfy)gu(Tr}cROzD;Qv6{PLh zc%Guo)ix)`=+m5y*L{6k2%ER7u>u@-6_9UrwSnrOE!Ls<%t%m>a8XUtW@Mv~@QqAE z2E0!0k^}*AtKmwrPe@(A=5$w|73j`prf3_E+a6=c#*M>ceIdb&#XK*}swm^ot$qC( z@UR}7Rp)C4B-~%IVK;6$9GtP&(xjOo+_)eWg;_a@gBPcP9~*WP{%>061kY05s|M5F z`{C1?=~$u`Yi?P4O#seE0yptIesR9KlZ8rIoZTS1$qfO;Gnj8^R6OV%jS7xhn|&4r zR>fzdCKAL_pbMUO7ypf5H)3v>5VgR1KxMCY&Jp{s3CI{ayGhrD(c>w<6rSFsPvIF5 z`!zKQZr6r9nsl%%M0|HUj$iyFjHR~{75FCh1rU`=qTJp{$nQyruhaD}RfAm_dZ7Fa zewFq|x_~h>cQgIu%k%mBPIVK)I5{5)$7l4?!2=C6t@jaCSEfeh9+~#+(~6poNSdVM zHX5h$RF7%Ugl!PW(O8ucjDU<)2#{7wpsI0hEvEbB4yz&-_Ht)A-rRPu3@iT>nJF1# zFc0M{u48*f4O3Hv(V)#Y%))O$2j?gb4V(8~_cB{Q9*2!HnT+2@E<<%IAvDy8J*?vq za_!1V={R&;ua46!Md1hMF}fblj=5^Sr7~B_S3Yxf+;VAbZw&LK$uT-H6LpNbub|fs zW|lSnH;=6*gi{~WoN=y^@-@aJSQGJg&7N?DWu7e>g~TJrBMHp9*E&rapCjfoWtYr^ zXPc)PQ#fBnB+XQ$S`!W7t3ll816<<=;+CZ6mqpriZETiAzfR@e+O?01hPhxrWh#qVnvyc5-CgRiMUP<*cX^#yhI3b`!S6+^iVwa{azl+hHMD{*C zcwl{?d)e)_qj5}v+J}GdJOm-)uJDQCzzo906fad=ej29QJ4@3lYA8%HlleI%s@@|6 zWWA^QI48&4KPmRAADEOBQg;s;JX`)>qnvaYOfuqTaa0&(q{Cp65%FK|FR3EZXNd6> zf0e1!7qKqfJLc)dJABE*E@(4lacRI&CWghS3C78WSEQzuQYIg{pBdouI27a8h=Pax z35gNKpQ-$)LW`hx^zqAR>|4K;u0`7_S#-uI&yEp8nV9FIOwjq@-a@3WW^Y7fb4~NP z@rU~4(ctG{`eCI17EwHc{_C*taJR$2A$5p&3$zl9xLJTCid zRGjP4>JUG^j8`9=d7DRR&Ij3li1t5K=eLRc#~a|9R7Az1gP%79enI|o301N0#!bv2 zm7lh8M*SUIS3m!5uAi0c-~OZQzyC+s|NB46{y$^0=k>q6?p}uhzdKInbGxOd#*@xQ z*wu4UQX^~NmPn|-^R>X^WUq5LHV&U@?TN5uBbw^He7E-Be;em_OoO$baO@nL=hL~4 zVKauRW0U6b0k&9OwlZl{4H=WVac*j`U}~t2WgL6;p7{uL{6=Y)(zK+UZ@hZrY&FLS zZ2Vs3czLUsJb8#lC|^p8ks9?{Wh0PPj-L6<>y4Pj>dMK8%|S`rPMag-kKZ25xV{@B zZ;dDB5%N_g?<9|oQRAK2fO3p2!Rv0I>GXZe`i2PJ?h>0n2K9ZuLbMzse`nBCCdCL6a%-u78tEW9Y6Z_}4hRv8M zP`}31=22ZX)h6kV8Vpfqa}awhT~Tn$EJ}`P-B#dn^1z~V?+rr7dN}KvMTxWndI{0? z*dv?XvlvO{&#*bwQZSYUHG0@k8u+C ziFYLR{cvfUV99g;BlbcP`(OVFdRBMLoEg|w#B%d!7XJz2>($PYiF4wI{~2D<N++*H%d;%lTo=y~TdFcPt=i zWzU?AyIJgjxb;l4;+)0I`^RtJzUfK3{*mnWRSiEVd%5_8vcE_tF9oi%T!KS^i2}+c z5@@f`0{APC7en(kVN*#Qf>S$_Pbef(+y;|DsE4TPNgY-d0(tlI$cJZeXl45dV}@#? zQg06c{-57q;=jYh{{a*KrLFH5LlVm0CWrM&P9$*%r6y@s_m!(!3`3SO1BV$RlBg(Zu)ulQ z7Xu||I6m)XcFNfzjhWeO_?^He1*00uk1e_U*{;UlPh6t&f!7s5}Ai!9dNTF4+bA|maKFY zHH5zS`5PKoZ{dKkNpSX)gv3a+C@~J3@%Z96DD^K{8$S?+=KsNFIwv1d62fszx3K94 zjw^`7@s14jkqh^W;E_||D6;prXk7Pi;kd4Ng(I4^1tU6Ri^cWE3XW`I@n3X#JLug1 z&?QhD8{A0~|1BrS{+Xis_BdJ8zc;Q%#BGu$;`rT)`i7$mHUm)z${|OR^Uylb5Q+3?*&!50YM>qFJ@q06?j`qyS??NN9mO4%t>%k7jbqiF z3>bx%kdKjQyuv?Vs7^%Q!<4{gmC)aIN~mf!97Z;khDSGb1!rj72|>_N!chHPR(yKw zuGP;oZi=!AOO{p#+(o6#3=DV#JeJWM3Kkn4@H88k^$7#cNlXywwJ=fwigki1qeq}iw zI55-JPiwZ{SuoIgv$Ge#jQ+8=oL}CL>2eQDj8)DYhH$MNCZX5O>%act{r(Ny1{LsM z|9}G>8&dT=QUX}j@OLs;5OnIEL%9ipntH{ z<(HitQ*gx!q`?F!@QBIoii5VPV?BFM_Im07`ZmYRUpLMi0bz+fGp#nar)vy)Y43JR z3q@f4+)meX&;2(Hw%D`z!m-@V-r-Y}<<1;?yW2Q07TB!85v%=jXM=OQ-auwxj`#!K zkbjsqMO&Rq+ub3dj`hdhcB~aMbzB4wq+(tF9d6*eq(BVh1_c?$G%b@*wm1_X`<7?b zhbKZZc}gAd4Qln|*~~Vbx;x9UT}j6t09!wqfxMdT?9Cd5e_?|e1!R_ri%N9^Eoc=c z8CS*I*#B~yhJ`_0rsbwfd+NfnD`4)g^$ZSM*h`Dw>VqSfo6Q!ET3M@&Y{F9E)*E@~ zl0m4u!(?^6d7avb^tOBFS+hRrDUu$yRNo%QfAf3wE{Ga|h3B%_v#ofobVDWO7>i)y z9r?1o-{gZ4iKDU+i1_p2;1qeyRWU=l>c#dU4Zoz@mk7Rrryv;0YmoL)O00ek0%PRQ zhiPyomoeH`kQJ=<^6|)`WCSkpz<=QCCX6voPu}(9!90ic6Jkp8cX?o5ASGohMzQfX z4xcQBB8-KSB;;=AMxo-B<^DWN?Bb~>{Og#Cb@G|A`Zyn=%P5h1d;NOo^amB zeJ5vQ^%y~01+J+4n2k+aoSWA>BeAkR*#^JDQJPNKw(XiyxZ>`k5e2W-Zl~?Dm8B%t z2@h`lRM^SOl|w)Cx7Z<9CE7fE;*bSvlaf^TPdoY-TopGAlUMiIt{oC!8g__G6cVMR zw3soI_#koBSxrgZwuKBTvm&W_N|ue2CGo(|kS!#awBdjZ;ae6SHM!H1Aw)%U1q|H% z1+u!8;TB9CT|iA#q4|@>*Xx7^MB527ve9X~Jifitd65sq^Nujh_+9e$jmZ6?b(o-Y zPzxa_izr4l8V90lU4Z>-k-ajHp#4p7oS2rNomB{!Afnzm&Ah`G{{zL)JpRQNp|Toz zOr6{lF|wgUMKb6EhX>eEA-_0O|3 zsTXF-8(m$J4jO~mGGn~It1AIwwm6i>qr^T@gEPJY@bg^aAwUD%z7fTM!?Zj|=3Wi- z(J14`IQ0uOIL-XON_@_#xbK36OXDMIV9hd)&bN5P1;Oo;3_2hh$Rtb?f=LTGmTur# zN+ap!%Mby&mMX7jCP|kGP8Zx0fc3#W0bD2CGaQWz0oDx<1n^<@Kmi|X_Y_b)agR4I z1f&d?eq)jS{y0gq-@^1Fm1o~%n8~y#_&#ai$7{t6;~SO-c!EY|%sh!caad&}V<~i& zUbx||^kgap&o?WpyPe!?&nUn)UjXvtg(+S?c%G-h|EKL;mm5c}HPQci3Y-|niSBVj z<-Tm&yUy9$K~Yo{-MU$%x~e@f!GK7Rgara@0F;XL%kMDr<4nZN%lS!8u1j73BtRrc z{pcbA*Ex*t^EeusH=4mkvhs5ux+H5tWG2`(d~H0zIisjU!KqWO4n z97?{=i*VBmWkZ|nB>EbTvdnpv9^Kqef1RngPZkAFGb@cT7;Zh6JR5@RK(%5x&*vtT zBU*FhY;Hs9+bXfa9r>k9gubny5Yk6BqyloHw)7u3`O%XgKfxr(PcjMe6HS6bk9(&@ z?PC-Qg86#ScQt+1wQ;ftzw})c$H^|&gQ6b-Dk}$bkXDWW7_I}zV;W{hVBBD&PEv;- z0W&FretiLBU;*RkCfJ@s*nPLrRAP_AWJS>&oJJI2cWW_?~i$|tb*_v^bjII8RVYfO+mk@N5IVcZiz9MdL|khMvl)B^xE zvi>h1{x@yO2634CmtN`{X3sV%Jci?Ur~JpaEpgKi@b}YLN#2(z-Q`DpHY-=(G$ZMbT0#MnehbVxVP zG>tlXS&lQfNX0Tz6nl9=&@>B6pe<;p!PzBZMSDI05PC5j-6j>+zU5PO1DU8Rn?6w6 zT^t|!`b^XK^<_C+KD+E8=0O^AO`t92BHnVL?;#a!5_?3fgif+!gU&{Ck-m z*MpP6=O0ANj>2FAB)DSFS(s^9nGQmA8SmXdI*s>6C>gNlsAV%0UpkaZlW{VScZ*PU zR-8)P;|4h54v8E8J`5hwzb8VSioY9Yd;?Hr-q-NXhu{Bn`w7;@Y^nqX+sJcm=(%wp zcA|GbH|~B;(nP60qmzE)62Dpu>JCB9U-Ujt;h8ZBg&1iTI_ixa@-~kXGuq5aWPHKYFrvn*JwjE0XG#7x*xTrBaC302 zd_(AycF5r>8a0Y|9-PYBqYB=O1xzzjdb4zRr>jy3ORyAcBe(m!_x~VAh;j82XF>G zIiS2Dm?;yOQ=%8?=?9j?JZ@M~PUjr&+6wFKz;=&i*86}Gw~F7;{GuhS1`zmvt7o+#iih@n5bo6jLxMuv>!|3WnbzBTCXTy(!hf_jgAnnsPbvS@z5FZD(A4apQ(Eu`_ z&+Z^&!u{Z3GQRzAqG~Q5#Yh=KvH{iqCqm{Pxf~6z2M?pm+4y#Le=_XK2!X)B*Qe_g z+20&*dNPBe%jv0R=hgUjJo$LC$v(av-ii4>65sG-9SoQc52N8!^ziWR@^oE0zWrq& z&WN+Y!-q$R<9%Y->D|wx+Y@2__3`%S+2BfywAtmISnRGxCv5P|cyfO|7>aoT&+f-3 zg1x<)&L&ea8wS_*sPMf(A1C*t+sl&;+S|L?#pBhLHC;_lJpMqF(;+s-obH1s*6qQ~ z>Guf%I~|La5Vo~bK|WrHJz;#RPc4>_N3mu7GCKXsi?w<5@Qav4$}DxpjsT|wzZVT2 zf1a_f>}`;5Pc>{$Jy99&bX$v%9H)cNCjy%eKEP6XGnk%Cw4Dm!0;QG{;XU47+&$jP zZ+$Y*;q~1_jG!ST(3(xePHj(ba1{6{cT>>?C>l2(3*GbeP7wO>(>2JT-^m?t^`w~`>*i@EDnbsAQzF;UPCV%m^~6(t^o61T(O0Ufn~(fVCG3ZAd9nfUAuJ%w|4D!_ zB=j&%8cp$>0Kwt22*7GEO~RAC?=441I_WIBZ#0H;hq-FX*5L+av+_FG`%X?ZXataW z>0qPhOjB4zH(0P!d6QiTk>6q;Lf}*HLYd>FIa$zQK5Hmgs%(c6qos30|5l!Yo|O4hL9qg3Y(#JX%Kmf%D)?qjR1p zv!2!9`DF09Q|wQL(Zq~?v8_p|I>T_~c{bd`v~xH#&qO5qib0V4b5-Uw@B znl^q}m1oTUg=IO4B1v0D7%SposPnlzhv)5|%n>%kGfsOD*`BzEBAp%w+Y(5vC-6On zXSoTs+r~i4J;BAkl4ikE9DZ6yg|=Ke8UEHOl53wD^01J@HO#{|-*WT$D^`BI#i;?apgUxO?;dTd{ZU%(*x6g^mmI_OW+2NS{= z!oAq3L7UD)eIaoLI(=}hl=jGv8OirU^&j;5TjmOGS9yi_0 z64s9&4HnbXJ81(&fsx_F6%O+uZk4xCgO$DY@OQ{bp_%Dmv?D94_z#l6<*lbpq-Z>A zN(i_Mzlvfpnx$s6X@fHGnt(opNtj8wzAsLg&x7ru-aG^%77z%uDdy>RSIqKsm(7ob z{B4&OA!vDy#MvdsyrK9v)7fvEzCDpNetZRTuEXzwI_Fx2$86mGOyn+*sKq@gVrycV zK7c9^>`4$I>{#3Icfq=y$S%Ct|E)D+K|kcb5%gOj=O+fm4|V#UIR1-`lX*s=<_@@< z_Jlj&XWAFF)xoqcXnTCbuBecsS1sDd^rQlU0R#pEI(p@48VI<`yy-2#N69>096E?P zquv{7a!!XjG1BIo2sMAB&z8UCXUpH@v*mB{+47TpHbbe~f66ilPOFOf%<)Y_A*W0uAZ zdp;ze46{9umMdERX2U9flVO#=*|5srXjtW^A65bqR;>7>hD8oT_oN(R}7`-!0m>dUl38^`w#t3QM0giql1$68yU4dzO z@ApCOb2M)swg=O5!qOVS-e@-hCK__o%3kj#CSj4z)3`1Cpd$)g`pu8+ryAlWU!4$e zjmt`YLd0DbAB8pvGqJe{%rE`dBLjo;nx2D$&kfF*y#MsE;1bZsFy6ia>?B$xtsB^3 zY=|V4H!EHb13>iuegHYXR@>f06is^*mkvLSVY|E^aw^95o8>BOXFR?pnPv2}t;hS} zt1wKeBj2uyD9MW;nTKy$MUkao8j81W@}2TGtZ@U2{2VWvkFV`Aou7JOHA8}wHzTT< z%+?(oHw3y>mbB=NPgRFF6U4_=a_X-@coVh!oC4=v=z#1jm75|!Q$`HR{Epa ztoTa^b=GAc)@#U$)VJRIfUe!E^RSiSJp3ZYkbStcGe-Gr5oP@tmrZ_t2ROyI?^owP z(kR&m4Q2`LtVv6H*>=u!8zwy}#IU+g`=)Hh9he(^P}_NP&WTzvdOE+%x6}Ee~p85Oues&@L_k&AIf$4H|bv>|0m2Bm^{`<|qm1i=&dvL6& zM^DOrY&Ik~%&HBJo#vC|UxZJ)Rc~%FE#R)UU(=bnDUZuRe)!RAEs+3X6O58&+OKxt zl(B!^xi`5~B)^a)^SsrSxjRbHl12V73P}J*K)Aogq^CR< zMM(B}OWK@+Fbe=FqD}wTQ5OBu&b2Q}797VtFOKdF_;K72IcC`>fH+vqo}wb}kC3IC z9wN77rwff)dl2%2DCF#L?5OB-=#ac%R45LcAbe3;nTE@G4-IePy zocF2BU|WQ)uV*la>9X+~v@-U6NwGDhNiO!d#jGvq>>&_{zB6mHT(SWC{d#;cdw9H^ zj&DY@Uq%lTdqmwPPA854u0nqNp=md+Gnn7djU#>fhXYeKcWG65Y`O9{wX8L5ONBm7 zLZzmtEeBj!UlL@&n3mS*-$6_GNqf&*D=wjxUQNI|zXDPOPQN zXtm2&uvY}k1ni=t=gl&XT+Apm?4<FRt|M|Cz<^z5LU4Rdvu9V-A50VwuJDiiw>T<7 zAG91vj#sVy8ruSBR0}+t=xb0MQBxVi0N-Y*SZiQ~?FX#+P0)Q_1ie3@^ z4;Bj$&HOw_q9XblX0GjNK+zTCIYff#v6NKV6(nwEV%iE(A?XEL0w}>2QGy$r*oN`n zFz;P~1xi%~60s1J7XB(N(tcG`AT;!sFa9QooIBRx8rY}snHF;kcV}8U%+7CtWDUeOLNwfWti)IZ(!NV1Fp2xjV zC2tkX&+uq+1SBIU;O+CuC&pf=2D^rggF<{RxNqqNso6E;o(wp8;W4iQ13?D1)m~_d zS;0Z4E-2H8pYPxGAn9F`2%V5`#Uwh9@W>rwTM2rM6$QJ%nxDH;TG&^#YY6Uc^E>r5Fz0;jve7e^`dEEX$Un9ZYp@~IujtVRsT zXd^mmPRT!Bf~;>n7Nk-|>D;H#bb0R@3$@M$e) zMOLXu-fIB?^JvN|{D+u@WE^H;G7r1(YhrBRzyA3@y}_$av2s z9w&#Pk0?sc{`iys6cv6jhh!Ii7OmDrLl?hBNfxfCraBAZcoRwoG(Y>#|NPHG9~Oj; z!Q|K5;q1fccJ}FEK)Y$W#Xi*)FCuo@qY@kt7lX-Ycy&GaKzn1Dynu+=ATm*@=DWY| z!+Cji-DRj=jIQn;Ml*V`PvhxFhnFH&N2c-Z;NjQV-Mur*dMojn#stymdW*aIC5s1Li%b~uIc0bwL?|I z!SJIK`SrCM_3Y~L7Sn~#MxPxxhi;>1IP5d#`Ya8^BW7U#3TK1s@n9mqtt<2G-K8Ao z-B~}5hCk0nA7+%gzWZk&zRyEv#=Dz)(LGMIF{oTV9+wTBQOm1rcGfk!ghfW&1?KOXWyt$uU42C~{ z8a!O~WD}d~Y=TG+v*R3md>CK->dG_uh#J80?bV$_BZ2Mq(Wx7M6&uzqp1Q|( zm!peEyMENX0yf);+!qg{!O!=1h<#g#3uCc2 zII+4ZuzB1zB}it?(c+j=~&hM0PTdFS=^PGVD`uwLe#Z5ydK@)I?ndLhl!Uiy>9j+ zg4j=&yv7RV*=)Ik+*`9*mj!k<%j2}jyAcOZ>5d#B7vP2Ty@wBw$Qxi;u@3XllZj?> z!I4um@RHr`+z+>D%SM@g^IGbH(O!KS{*eiSiC?InT3ze z$*Y&W z_ZHK{`xpjW37cmAB83&xJ*@_77naWc+o(CBL;xgWc1EkD z2`0ysJhQym6bfgMBx!*j55$W>%E8xAjxH*Xx*6YT>fB$auN*BwH3c8NGl(j!z(_3@ zkb3VP{adhCx6z@oT4X9L+NGkrfG{n@9&Vn(#i9%QNKw)rK~IA@ww4K1V&n<*oj2WY*`et{xx)<89e#R&CkD?Pel0=> zuz47_0wTT#@|CchQ53t)w?}OH#jX%_yc0x%Mh&U^vBp7w0$=q|-Pj>OA3Q~7l%(qN zWD=NlLRSth#@;VfB*u~e+s4s6unZx&Fo>;WXYAevJu>f+3p|I==gDjEGr~fehuKq9 z009pOed$|9yTgie5CQ+rG-L(P^R1n>Gmu4Fv%)%iF|M?6TmA zuD1pOA-cJMAo-41gNf*QVmzY=T`n6Iv_x^~w!i~_!`Xf9lA(}k3PUFJnJagmT;@jE zeWSH+uR^Gu$I(G)bI9NM8o~=a!XzYC(ZOQN$b3k;kas~ra_u2YAv@K9pSdK+2F`?z5Xd6|k`#9epEI^NzfX;yfrH*1v+n(Q zBInMOoEzspM9zIOcUugGX(kT4VpQkMy$F{s2*?Bhj5Ly`!slY}nTUiV1Yf3^J2)`W zs-q$F!UNBEWpuo~G{ z_sn{xTOkhQdQfx^wG z;KiYRFJYW+0T9=0COIp$z=tL{wsZs!yle5qg5{%3sdA3zy|E$ChY4h>t5uNhQpZhY zB53TlXn2EyriQKPZ2B4|B8~q6BqEY1S36_-5~ZY|_MhT({@i>fT?Px{9#6+NB^ZScDJ1>pa1UuDUB9reQ7WNL z4lF=St-fY8{>fQssd8MGxyaB ztZKjx@4MIcA(ALdi*%mG2cVcrf$?vR^V=@m9r^%BBO(5V42oX}mtn9u06;`);U^Xi zv3nBj#5m?0q=`aJ{jHBPH)i`RVgkr4#A{)Vs>Hh*#1)(db z9R_P{7XK(LmaI7MgXocH6G4b84Oq;#emGyJpfQ2%q{o<;4(~mH@Cd?_A)Lx1MOB0e z7_*})B8aAnWUsmPyQQ=BC+s^KH7E|3`iR^u%H7{@X?VQ6_eRh$Lqw^gbDtlHK0y?P z{u&fQ49whCL>}6om{)^E$s&EtJ1;1;jmnreGE|os@t+7*Rx{&6@a!qbvgpvxucwlh zc97kd?0yXx#Ne4|+ac`Aj$N$)V0?nPjB@d^d)%2wY$!ZPJ4k}EuJ4;~>y4pwnc~Qu zgl#w4)(>B65`y^#*pUAelW_DU%IN}Eh*@EgA8v~K0&uWF3i2UbiROsDqsv_J+Sn?H zI|m0f)Hh*HFzX6ZZL=PdGe{chwq-Ol+Sn)%vp$eW9PTbMS1V%vI`Ar}hiYs-J6BMxwfVYuzvjl^sL#i7`LPB6a(SPx>H=EtlARVmHGuUMHT-+W7QwR$QyzqY33@Uf4Z zU`FEz&C(a*=M0Bm-}N7LvxHEGhp#U7fn*-WeTN5>_zYpGV7{Hfwmu`FVb*6`uhlqj z5JW)evd9+o#*mD0+QwAn7S))tD54s(OQJ6`xDyNqNxMLTrYi2v+Cw;`2QC zat;$B%uL$}g`D3`D0=iV00SwFeKfEMyThyq?U?y433lquA7?m=l_F~Azh;nc(g^}t z42%WLsh2Qm)NlX=?X%`Mf~SqzQZUysNLM|KFLx_YXEz&P?h3K5Y{U7yu@TCuWh0Ia z8n;L#+Zku5jl?A0+c8S^Z?`FYK`_xW_|EXs$YuN@y)HOYH(_0-B;3susdWv+tfQcM zey9FYR#buuj!kg*l&c|Ht@B3MK7#Cq;}?RzYATMH8QQBRt9EO2Wm?Buu?hRY2n>&~ zfBZ>^5#r$7_^F6U=@BHYINj!A&6g%{Kt)+oTy2}4q6BRI9PE&ZA;9c!VIg)i!xWFv zaHl@-*@@IgQrV1yD^a$cpVO9HX^#3-goDa4)WF!Gz*}TqeWj^lVwgPqt;u?GfwrX; zfC&sGuvaA;TZk|Jv=@`>JNzfevS9z6M+WIHQTVEAA#?JE?~gQJ{(SAim}_2FtzENQSW!5tde_&za>^I(^Z=17l&SF(Gvy{_H~>V^a2#)ugiPr@Cz3a(!P zgP#Bx5t?_wgeBxob>|)~oEs=M(y?YQH#6DAu{)q(D#M_iq0<+Dkze@&7PI)qVIcd8 zClHScry*p_NLUfYF#XO;v+q37+Y&H8&JPAqTKpiOxYj7yBWaeUui|T!oekRdE#@%X z6U2hGP5mGL_=i9Ln=d`M8k2hb*;wX~>(Af+$$@LB6Rhz?!hev3Vi+%d={pFEg3)!j z94nWavnL^LKf79BOD1Wps6m`e)}KV*i46}8?XonE8*gY{!zZRypN@W_Z6mSjub40X zP=%R?iMF@@`{?1$A6^e0CnN7-a_K>Ohg&^Y6bu|ATjV zH^kt+=m&oGv|BD&>~oQ?kjrN&v)Ltu==8k9x|qu=X!a3QcdJWAsheGvkZOwjmIf&f zh7i+$Hz${Ui@<*zT0U!v+jG7iiNP#PMENoNtP)ORW<+Jk;wHCx~z( zjy~VfM*1XM$5pkhEVe#Us$?p8B)McCF8)QnRGxb;6{|xBB~o<1BC@I zFB(rHqAV~J5o+5V$`TC(My?Gw%Ko*6bEPa}*_w$CK(;Y0x*7^CO#zNGb&_eD7LrDR zhzFvt#S^_`i$`;5Bzj0Yz_bmoz0jgHJMv#h@Nq&b7QH&0#lX0K6BI2xGwC1_^cf6z+6r( zfe@O)AXFX9Eih&0^FyxZ7MD;9X3b-?$zN1CDq29;d$FVMqLz5;P)ZK2Nx|lBX5rJj zTy2l5On3`(X)Um=1jdN8v*(&MuW-Q?dz}fM63-CID~+88+kD5Ghzc7PNKX8rDhjO? zg{q=Z9n}SA1vMq}6lo=x& z6Q+ukNGf`h5_?5wq7@|`s;+g+L^r6^yNuJo(qeqfOzu`L`>_}1JlKz2pMlNAqNmpiH%}w+462B_q5l25z`rXgPA=LX2WKUv86oW{dSSf4+ zbB31Yh=&C9K{+**n<7r<)^^Zy;vH{f8)Pn5W7oB?s?E65Rt)}?Hjqfx4*r+octcjb z--$7h7{5%rWX(CFNO^WxE;L(MsRR}c473**{j1|?R1oFWS2>mjmln1SFp?^6g7=LUFO;Z+ihfHi&$)V{DKjQ%Vqt@)#6(JDwa-W{+L`No_?$R-_pW>} z@#0M~ohl;!yLizc+8L*sDuBGQkqV|dC+HHbtWZ$mEqi(?e;#6xab&C`*C-^!N-P<@ zTM5cIY}f~MnF1*<*SWmgtFg)w-T@?Cr8lJaPlZ+P8)0>R=b*u~aKK~cL5d2OzHu+J z;d2&eaCM&)@}^%>NbR7FTb3!Aaica#Q?JP6dm9GZPSnF`Jr>Z8NU;~Yt?d=?G0zjE zD8D(Jjx9{$Df5{3Ai8iJ$-B)O9~PN|li2t~1IKy)udO>R!CKAif6E=aP*78V1i9$8jjZ zZ~>uwf-3_(J#}Afvrvf@mcVqT1b}WDNR9h{C?x_^rQYvF83_Xd^)(aw7^u0^W$_wR zwcN|#x4L5RQ%2@LLodp`b&xIo9}gJ8syr0^E)HBVgs}dai}X?1Ew-qN`l{5_R6&(w97*l ze0XFk-K)3E(v3Gfv-q^P-gp8YwLABN+{cA5cQ6j4_b8$!Q;KL2hh|+sDOk3V-({%q zE+Ai;J}~J{?5tYJg7rx?OR$AKq-TVwA#v+4Q=pk?i;br=H^5xd-K?yk_>`)C6&c+s zXxpu~4Dw-s$_Nev%Uox3yu69iRl~iHDpxS_0kh`v_N4jl=*RQ#|4?Sny@-^VJVf!M zt;6}VZ^*W-<3zmtI&HREs)r%fv1hw~RAkX1ee$zT0c>?`FRVj4#DUblqGomujv>#O zeT;;u8R%7ok|e@%fIj)OJFvWGLSH*XPWhaGxIA3s7IorkfZ%NSuV^s zi*_S6L7-l3vrq=9z}LEaSNPOIv{^u4!$pvm> z6x(_5WHePh)^})?4~0{qN0iD^SUm?b$szM00Qt{0*}YT_sLX6XqKdUhEc7{=H56>yK+#z%2TpsIhQmy z^zVCd?t+G}aafQLnKXi7Ut`=^7>|Skj2~&)r`p6{g9k>)b(B2goiN3s1kus=;cO)) z>9fDsZCfHp8a$N9fmIQoNm~fxE~V`}NYp-4`;xs? zPSZ9Os_wc~1s{Z5BjzeD9Y?Y(^*i7*3_@hDxEx)VxY0 zWI+TO0k6qkQxepo=7C=}J6oM8!{t6gGqbkO8Woq%Xa`rR#~i4`Q5%yTIt*z_15Z4= z$7dBt(AK3k*Bfi{yWgoxdhpSbvogukI6QnrGqPWVm?z`~kD|bAHmWh0N?jWz?P|NE z?a@ZKcvwz~Zd!TiIL*Wc8er74^7OcTg~QKErVp3w<3R$pBvJg3&Weyaebzgy_a``PPUOO05A4mr;@fW0#bM`xDW32oi$^2n%&@|1 z-Q&u(dU7z^t@Ub8e*VMcA={ul))!m zp-ND$t33M(hyhllzU`t(d5st`K}FpeMReBuFvNL@fRPUVU}xI$(J2&#cI`F*7z~># zRl|PCDx$-E;80_7&F zpw-_19{e?+W`l{QexheD*3cC_FJo6>y2Pk$YilJ^?L6J?G3j1;ujGf)M1_BzfgNw_ zO<<}+VOT7E)sxQQ+>HbmW$uG3QZ1du!QE3viB}v3jQyqC?tv_CPX<(i$=Y{S+pBse zFC6aMc$dR}omGg^48!mn0}rI%|6X8`X=`(`IZ2_z9A{-LX%%ZMm_MG)`Et$Aw$+#s zU0lB&?r+55Vg8J{vgTO|w}*7vwmZ+YVruT{GMMeRO~LV~OoPC$RTga5Vii}BBIfyv zUlKIyF!@WPa44ADU4jf|=@Nuo%S{0Zx*FqY8hn>g5Gx}m?PmqvFJgTyP~t&T5RTmh zpG;k*_+Vh+$7!&DbeD~Z1Lh@9s)5AOmoj9iK{(z5jW4QolDm!Q4;XEtHmupbN)E{& zVW{F#jo>QN4HPNMd{R(y0KkryY!Xcz-~DA2#)}+05cO>f_-i)mV&>KO93DY<7)xDQ z8$x{qBWsfuI!&oT>=g{9U5|0MrtwPSq$^x$P&A_XQvO@?!u?K(l#Avn@Tw|(O=Q9j zSi9TeI2@>xuCVYxBtThWp`f$mYF=pw9?urhyk8dzZeX@_CH>Qo=g|&Izw|a%!Lq09 zYlV_563MM^FKeB)q#!tcz7Eho9@(O9XjdGGhj=~3tFY57j8=);ceo;^djBhvJ`7>m z`IVKIjAkxwQYFcq}h9KE1#;Z+k4vU ziTkap(WR!!#*~F(6G^&%xd)^#j{u097cKWF{E2gD1YN2QxSf$F3I%V`C6Yel64E!z z`s7hPp?1ZE!gs=17L<-0r8@qA5CFxej09?XqnaS!IZ%thrSjWoqj(EO$=GgZ+ijGSrz zsrd0L!)+d2+kEq_tbya+vyq*9J)UAsmmY%UCFm|0s~PFK%q@m!I2Wr=-*>-GR}Tol zh`7~ko4&WEsAj~IE~-$L@tL)kDe(mci!Sjhq|hgiN1r2C)RKDE+$zmMBwZ{Aiunvz zrz6}=KoG88Y5^wNB(~y}-C!=6rvw6vPrtycm&`4LuBuM%{1wQd6`p8j3{mapaq6I6 zQ*n05)^0XK_Spj*VKQjjrjfwhk49ul?|Z$V*of5W1YUwqLb=ng{UR-~_K;?SC}X<}>9*ZMta zBMQ-0F$Z2cQHgRBuHz%j|%sMXccd38o&zgr!;$3(m69~pjNF|1?g|QX#VWu z6|*;$x-miHY|I5boiauf@zTvI?y8>i9bR}D?BdR5Kuqo*eNTBwK-TL@SxFChjbUxl z8iR`6GeK2x6gOsdW175*`iY*y6>x!z7CxTY!bJ1YP>Agj`;5p2Ftxg$@#H7qfMoP_ zL<^Jf)pq#Rw}65G%V%=58tp|0;|dR@pZDhQT<-F4A;bZnui=_)vJ7Jm%_d#|+0I%d z!zPmuVv*J$;#WvU5;{FbcVFF0<~EXR03u|@Y_S?@a-q3YoB~A5UNLyWh5zIEPltS~ zOltopfg^vKIIWwTdOOt=$>%ZO83nm|g1!p%MX$>)F8Mvh&lXK3@bVnVyG{}XUY;is zdfSq+(6Z2!VtpN43newUo0u^RyPPw|f(5q%9W*RAA=~7=a@aA|4W+hh4M?4Xp0xC>1Kk@{SHGKlHX(R`Mc(_!H^UVgs*)E-Y5upCG{gI2Uyr7@#5} zjK2tQ%oo3D%;9DbRC3HC&ooU@3V2cON;ZUzVHm3fPz`dEV*kE~P3?ecj;s|W6hOZN zCP)w+8v!uSRIItKcH%1Z+=5NUHH1S1ZQ$`Cuv5p-s7AdnX85Ote%@scYU+}u{2^Y= z=a>0PkSc~%HzXt{fVSBi>91&s`?rWN=y$sb2N0Rc801lgXAIFgn(PQ>BSfhm$%Ijz zKn9*XJ%R_brZb3aG$P$;M5JvrkLi268JWJ1u+nLlo4#l*yoof586RkBnX4X7RuNxFGn;kq4Uyw zV?nJ)WNg6fh}i5Fg%KfPLJ1i?fE~5oR6IUOamx=DGUPt`iMfbn7(9=I!6+28Gc_xq zfcIqRFUCrBA<#9DGRWM2eFFwual&oU*uKb!@o4($AkY8pO>qNH<8-w*K(&n9A)<<6 zGXNS!i)>Q2q2hgW9j*d#kmO6sZ%Y-(K9=Vlyj|?~mH6m`dS!bZ#M*NZOo+LJT#K*M z{>27KDOe{g`AG;PXk=Y1C@Ae)iNEBT$${iSpV{v^l;7d|c4P2J$#TlP#t5=hh_n;;u z)AX4%97t^$-}ddIx~TMAQc7dFsgBBM?>H~t@e)9OTB!^=XX!-`wx-$7aKg z)yEEAU7jpsVZzFP&4a!o%@aVES7t!qO|Ymm2@K%fHkKAxHe6NA@fsC1cS0`nU6wjU zv1~&d~^M9KcuYO`XrLhjf|OxPJ`(jlvzS7dV#pWmP|eBk z|H?V-E-du6tK;urdJ9n;0V~b{r~q$T4J&>QG@pmZnF?A;SXfBSm{c~t9a#QLgzK}kr_(Mrd08F8|6%_x!2Kr?WjV@`MsIk7jLsNQVhrQ=YC)#GD18o-Mo_fF3^E_7{MwSPH!F=gOZ8>NQQ#7&xem-j ze6orNt+}@RWHseREu!8uo2AQTZ*+|Ss2lbhOSASIUvN1osLNhrX~sziazZMK4q+!u z6v1F@BO84!387n@pl-#-Slp(I@Fv)nAUVRH6BtMLtKd+?hDKMQ8it}rewqH%sUb3+ zMyVwd>2SW?2DDPJcR&p3&dLdFL_B4jHYq~#!=;qjsJk1j*g%YSDWcj8ohKQ%qf)8{ zx8AwCsU&(ZUoAP9Ub;FU&48E^!F^Z@rc#0xKym?)@rO93vUo{^*hWq$_bNVsk+iVX zCJZ3r0*SjlW(&9+Ob3(D0*U7_BPq;5NEp|g9|jO8IeZ~bza9H*yNl!Uh`>DY6NE6@ z_Sz$8(xO-#6`JRAdRenz-p!wVx_9VwPGrxoWfVYY9XnwxAE~D-s1SS{ufEDbh zNr%`^iP#gL;*`!rj9IGeHxO!%==8tcnhEYqpwZ1ia+@4nVt&z9z66-jk6eP#VHN zX%fJakhBFLhX4uZ^!7IJ<#{ZLp&DhLHZZ1I=~|&{l|C_129JdyAs*n98rqR~#$kFu z7wSof;x7!$o|cF300-lI0Wqb#TP6TUqvFU51T zCJMLdykU_wJ)wLcbTh0REmq{{M(NY0S%ls@(#rB11pHQy$Sg~<27lg$Ndp`npI`*Q zOAuRp@mp;+M_{#2;|*EQ@O~eD3?Okuh5wI~ynI~6 z4(9jJG?+oo^xD=%ZKJ8d8gbXSf)wc%V-(DA(k3c4Gc`k2h!6&*OYBt*lbZsl98uwB7!M_-N?XaM2jd@Q8ScmX}qq+%!xV#^K3j2 zC|LS1)|uY|U$c?afEb>x$3aXrnEJ#x5!EcWO>?ORyKeFfr}V9;_5S_ujR>M=mWJ3t z%kAubT&#Cp1AdduU;AgPoB!E{TkpZ9?5^xJl&rE^Trvl6WeK{aX}SfguNE7z_KM1; zWL=yszXG_1k!I`9WK8174RFn&`vKUkl;8ng1 ze$#QyUUFZ>W$U0(|6NIGu1|~J6JICjWRa-rP$A#`Le=h8PzZK&c`k#6VIEsrpgXo; z?=4aYNH#;({}%ms@Av=V{kMPp^Z$d)j{o}S|N8G<7DRc7+0B&T`nnG3UQW6+cxWv| z4Z}Rkd@Ju;^71w`1BnPn{M^&T0gFPf)p^Al41T|PE9re>B-urqmbsm{GFff>hIMJ`adH1cnjn$(Z z+nz2(Q&bGTO&BE9glvaVFfq;$W-_wJZH6XPF4xqX3JCo@7>lza@gjm%fpaWG<22SL z{Zy`XNC7kHqi8g^{zGVtQpWNsf77P&PVWE`V-+T_B2*FhG4X$38aYlR>n^IX?ILF3 zXw#3NzaA?WJ;_?zy~<;<+lYL}PAPosEg^9Mq5bQh{~Oi|v0$k^Pcp)H-(xzYooM4< z{`JrQquR&^mnt?tCgf|TA-Pa)3KGE>pH-CV&@Bbkll+#Qt2*Z78|lr7xgi{bd$go0 zjMgBvHHaeb(3{*TO(G>Z=eam!py-0fbi=dzY`K_4i4d2fqS>@Zx@ayJzDYYa{uXl= zOczT&-}Z}kdt|XId5ew>q@Fso7XvAGD(uSe%gDaanrhV^DWsflA!ijNhuNH`e!7(k zU+l}*@X341#5V?w9#-Eg3L4ZZBcPcmeFD81SbEq1X5XVTepEU%BMzpIbNDl$IURM;B8i09{RX399qC|lV-l3ULnPfh5ARqX|1ma5&v{5PP$GOWYbnPn* zw;XQM^Y4_e*)?d922ud|j+Xi4CCXBiT6LzQv$l{sm3WmDImG-*lG8zzNL--yg&6$X zaNh8F;;);)5|x;PymQ@%B3qLCM%FCnG&md<1@5aNP%#w^Ik;415T}6L^PD1evb!Dz zvga!6K}y9TF^C~LX8YChYZyFBH$w`$j$Gy^5>Mj2+f{;OVpYB2*>dQ#hm<*vYfL-Q z91ex1u^BI3UJ5ef*%IQRy%!x1QL*-R8|KQAQ?_D80AB(4jF<#TZ!q9hIB=&K&1dFe zxDR9*rizXV)1$!&MPe(ty$>WZGg1#Vw~BIy_sqtr9-g;t6;R#~Do+jeI2G&hB6^9s zD9n-CSJdK_(l}0EXZe0(NzGN0?~vG6#K4}p8=#Ux=w!*++QCz&0IzadLVkA!^>j>4)@u-?DN zK_mCb_MSE!`@qLX|6m zI1t99=vRdXDTC)ne$Bl8F+p>B3?%ZGAzz~fTb=d9BmfPHOz(qi)#5937?})v6-o_W z+Qyusk}_7cDxF5)xM~cXY87nMH`6+l-nEpWsuf{|rW16Tfm5sE_{D+iur3c&3BFyc zgweH@5>mCAEX2??*rE8!$JJGbGb-FSSTr>Y=cq9WKvD+7_m|K}7vK>dqqob-X6x04 zC0Q6jea&v%6ON2RijEtxHT%~=vf4oaP6ljqvb1B;Cz|Y&BKX262eZys&uNlNi$?Ov z4D~c!!VBuEiA8=x^seah9odk)h~~RE$m(Aa!u_VZ)fz+@jAa!Vx01`O(b~Kv#-dMr zEq>Lyykf)XU8xcQB9*y5#93`p>^J9&HMGHEJTLUYTtG+RAO8JNf@^q>bmJP(mCjhE zd|7Od(wI%}YYMaCQ1rQCYpO1%_nK9lH89f-=J@NbQj%=B8%sUv;~@?(Japp_AL(nD zC9^pQy6orgnnT zxgev&pRXd{Fhi)@1+OA2g35zu&$~VclMq|lJlzW!n7tfOu9X5?`&IvqE5gvGzRMll z%DAl2SCT^+kQo>bBYPEOPY^?Cp2l(5X<#ykZ*T~huyt&SVx7M|p<$qUbfunjm=c<} zyLqGH@eLjmN)F`iK#IeFu}3y&H7NX02V@Wfwk0o4HSVwOT*{4uAV%8JPA_QWIF+vl z0sPdl`Y<~mq2*6?c=R_xB8E;qD0Fk=s}EegiUsf8C=6La-X&Bj15uxdFVW{K8DkD{ zELJA+DP2=jWU^IQ%wHEf=cyTzyqxA=Y%au`V6GcjDF0(4>f}u@XInxEg&8fH?B(0n zEYY4Q#^vUaX7N_+GkiZ!mM;sHj6;l>r@%S6fZ~#}C_jj_4W9?zrU!>7viSy^k8C~z zV(<;fSa?u*`hglSFNIHhQP*O!ZqtOJ)E)r9Uu9A~ib{?Dok0$&I)962t7ZdeyEyUz zc)fe(JzIT^w&F+vOL_ZV2831T6gXBRFT$Mr{*w%aHs35*jc7wqr9M`VT)xE630B;Z z78+(5^l1umDU5X(Z{0E03Se=}8?2A0S^0-Jv5P|~UNQ?5I^+3>*si<@uhy zuGF^P%}9d{$SOxedC)|6z7EL{mBW`b`k?Fa12JAGFOiv>4h)JY1CfHP8o#fDeD)mf zT^Dn~w)TT~m1a?~-ZYuZ2qNRe`%(P#G!J1wUciO7-OmrLcADA;YHEV=hdm%>aZ6BT zu@oYEINxRRCiPIW1$P*1ZDI>8q);G+mwHP<%;Jigbse%-C|W1aUf}X6aA|({X6hr> zLDXmKXtn0dpYCSF?;XuS1yF4mK2&XDYe+KGz@oFY7?8g5 zYU(m+KmI)Wb@pG4TwUulFJ`Rru}u}RPlmkx0jZCqqCfEazM|SZDpfBZ)z3VhQM-KKYhx2y2Bhey^s!fbHlW!_VLsCk`HZ7A$j6 z!pjkzGR8N%pw4Y{O>4)zn?qk$j48_{Y!k_3+9FeiJT6jcF!|$|nc>)isB-}y%6nW* zb5jSaq`+xPfTO*V>k!IUnS7)_-hGGN_q&A?(9X7>awxu(HZ*0l{53nd+uYmr4NCUsPaNey=3 z8h{ih5;sp{G>NFDpek2kq2jlZCH0YaR+_hUP;){-|bb62Brw0O{CZ__v%$!KqHmNf@ zXG~P=CGbVG!l185wEhwy8kq^k9OE_a|7bQNuQiC*^F04nXZO_aV3w7z_6FjBN$ zHxQI=4q3NBp1-Eq!r!c%Kgj@RK$yQh^WLl~?J+^grF5G`;-kR#KcbRP0_h%rU=);V z%tDF-+jn$5Fu%2XDGWWxhb=u^j#ck7r`RudV3fNEyM7&F@sQ=rK=u!uUaD;{Tdr6q z@(&Q1h14Pq^?1r?Ni0O z!Khhyl0RK~VyFlyZyAAdBC5uAt0{6}9~@tf&I~TsMvM(skRrv=5EcQbJxVvuH=l4E zK73FfUtWtw9~)CGTF#s_^U)G7bYM!V99yP_K3XMd)+79vIEJn)uBsjSUNI`$WP!E) zsXf97kQnNd@y+1=Clz3T_*E_UZmT`2uV(heN z?mn9V%xosH#W~j31|0{H$HbL|u@U;yj3Gzl-5gekwjqp^tzNv6<8yJDxl>JWIBH78 z_hZ>oPBR4L5nhQnF7_pAl7>ET$kL;sdc@KQokOqQhOa8@s$yrLyx+{of9T0au6dnC zk2#%@4KT7)Z1{e@4&#_Y6BW@@6gLW+`8w7C2*%8gj@X(J^*|Fq6up}`+*99Bc*J$I z^)T^=xg=72*!w_wamtnp z3KygpPLFFtr=l7@h1Zd3b)y6%3tO-iGrj8f8U@H@U?^?OgZyXO<=kcU117!*>o*w$ zKWF*V(*R813we4v6#1OVl|Pyh13+;qOzOF2MM4$K^ki0XIBICAzr?t$-5_0L;uNQ8^ZXu8z9COC=AX5O2a4lr@M8 z0|_gnBA7pS0>b^zFu6fah0|iCR>eU|_&glXS7M+END;`$cQy-#5|lP#kd2V+Fu*}; z8W%E!Z@FdsupAG_IKoh|Tv5tM{yN=+PH>R{_a471LCn`;KdIx3?iCXi5`KL-q8dzY z@ePLmK|HSR+s68=!G4^ol%ZHU)w-)?D0J>cf-rhfhQjk}dHk%{D)5;OclO?!Mq3)3 z(=3`l=LAd}51Pn;Lsyqhx=z`(2e61qh~2!wQG|&qbQf5inzWv~w~Uyh7f=UCau;f7 z9Y#!Wm_$Pgu~45ukfx9lo?AR>tWXeDN`*coXBvehN0AGbIe<(&ON2=)hMDG&|por?BudU#8@&m@3XfAe@bXjLQ}fD@IE zMvInR+FHjwb9tJJ;PNoY=4-#6oWTks4#6CdgCrWvq&Yzd6c8D6D^5eGG}>*ujABWS zOT$0XCvUf9ApSxQqj(}eDlQSGT`fTt5In;sJXq1DK#e;*e~)+I_b=A2r4%7>EQ{@| zDdKA-D|k7%JWG|dCdzk|+RkOLiQ>Jg1N1m<6*1=wI2DY=@VQ~is8$}z!Y!fWV4v<} zK2n>yyb^oPr~+=ezya_weN8xLw1WL@7lp^6K8_U_nX%;kI+B^sN*z`{iC25FM?d21 zoWX=_GJf3W=5fko^NGz|!%_37+T0NOSC@7i1!q+bOE*+PyB@$wz;zfSS+;ni5JjnV z5L=CMOq$1;nrTnP9?fRl!-y{CJz@izZ36VLo-LwPRCMz8h#;7H@CAJ4eCC3a&I-k< zjFubaO)un@m8d?BHj&acAg%lT64#+`I5=Zlk9!uG>+L1%5i)ITa8u;8D&8TrD&GFN zpPbo-rQxVUrR5t&vfL@sc^Z>!IpIV^`Z%@d++un9TJH*#BCzc`!0>iZJSC{ZS~gpk z8v&G!DN|&Dx?WIUv4Sjv8ndp%{Ggg!99t##S;>~o;ZCY7u%$Y78fQUn_=KsE=UQ~1 zO2otIkO8SZkB@=CbijkDE8D}eX+}(2DJwoxhI{0AXSzNPZ5yH%hyty! zFF;<_E=Kt2(bNZ3Enq6ft4bz530*kO=7C!R5rfx9-m!k*4dKBBxa)}V;NoIO_u<99 z6#QQxBx%w8qB#eJcoUS|c$`-fm`q)7W=#*pszS3c^m39;t~Y00eH+bM+BQ!~Q>#%e z0^&iDrg7exvZGZ=+;!uG>n&S8AmZJjM>L=BXx2`}j{s|k0 z{RKUq_e3=S%E$?9COK$(gM1!EJ>jb;wK`7UC14NiKZpCiJ)-%`xMDn>u$k+V3@M1- z*y0S=4h0@@3}9l4gW!>%5<#HuHa$F;o;#!?D<@t1IV>e31Lw7_{@~zOWcY%!Et$%6 z(19I|Srxs4z##XthV%<%B$LBP*r1@CPcT1Ai@4|CcHu5`>PqBLT^R?Pr$yi(j9eo_ ziSfXeOq6-AIw+b{gVi;cRxVRz2r6#^f-4B$aUj0`y84N%N)v^_9AL2{wT`6LX>ink z#?#1oQE-Kn$eC_QQ& ztEO`|j?h_ZJ;IrCmZ>SK$zL8){Oh0p(;JAh<_4`8lp~Kg2>ply!4t>LB1JZBuB0H6nG8El1^ zIM^GEudeW?_+!X7Q;ItlYo-+z3XCKk(OjJ6(H07$dY;|LkG>X9JjnD^y{5+4Z2jG$8nT5wf3~D0{I-1PxGB zCh?dOLGgze_bFtDCZ9Nd^>@-OK?c#R?VBT(d?=35hT7j5`pr){el2!zkBBkZ7L6hLzf{O$M`ZxHq z4w3DWB+S|{h=Sd2@$Wi{Se3$H(}qG6>@tggTToP(&Q_#yFi*&~&A%Mq1%yg9W&wdRZjYpdMh)@GvQRk{ zxg{uGO@`yKfuBn&%NlwvPwXC3;aEgrhaRBBCgbX8$XyhR31I!uvW#IRC4MFN0rx~{ z`3Uyz>FWs?}9)v$nZkwzUT;1q$6#G999_D#GhU!1Asvz8-eX>GnHsyUYUnvC?yZ=q_$BkGVW+YQ&q8q)%3i? z6yjJdIspa(8dTV@&l^s@6_Q#V=dCAV8q=}`rHa!`W*e*5h-IoOqSVVJMQo8vCK9lR zl34-vs5F18RUu1dC5jrCxP1{yV?_B)h&3v8UNYZhpbFdD>rll~;@}5`*we%LuB3;V z>%ulHUgtsOWN@$zfd%ZG#Q*#NC{xMKsBxp_1l61zm>$w<#$Hhpnn(pl4o403sd815 z=HTyZ*!beT0hOAS7*W6KHBg~W^o%=|4*O+Lf_;MYF|6ZoscNUBhE_fn;J6m?=*FlO zS_Q_mwW?H@O?zEXT&fJ|<@^Qf2%Uvavu+zk-gYmswxsZwtU*Wgic8ia47XHbILw*6 zVu5Rdl_AwUNk=;lEQsP0Zln2gtoB9QmYeOj_5ltBjEpp-UQCoN$9x@%of3`wWz3KY zY}$y+`i>#~z2cO$H3@E>TNM%FF}F*U8)3EqUoSdHNS(Jzd*#nVvGgsXTpYyr zd8L~3M#0uBH>*6?0&aP(piHZ)t<|&*k}z(m3Cl}05eN04Q_9HAKk=F)>3Hn8aHQZhT%A92QSjm4bN8aH3qvU?41GP(GZ#|N7_uhK7USl>h6W z|3^c@`OFFm1yTtJXE-_O?z2>E5$3cL;u*wLw4-1VH;?J)Tu6U|0n36@?V%-kIs2Xt zy&S$!7xHn6ly`3gXn>iCDtY1KmG*m-x(R zMYLQt?1)^%y~lLWdk``dtZL9< zC}b08>5fp=Cq6<_$isU}yG*)Lca%!rQ>1^4ngRVkq|!>Q94R1gu1`{!HOXi1J&qMn z?PiS3)dq^?B}jboUSD<4dHVHx;}ykcM`UIZHjg~`^FY4<))<*26MPC)kw((Rv{}A6>+nf4$s_h%#yzQ z9w$%nu-rT>Em4AO7`m#E;T0_^e0W2vDgP@OBGRm_ZJkgYFa63%iw7;lE-X|BBT5A2?y!kW~JVJxn=hD3-8D?Rq^bVL+ln9U3J? zW#z7E`Q@3GUuFf{z;1iMMXCySC_4%mJG_}#(|leJgMn9GgIi6vHO<WI!D&_kODgk!=G1{d?UnjBa9IN+B4}DXwxP|#26a?A3@fPFDc9_ z6c^nW!LPESA8V!xb6bu1f%@`VZMl9UN|L8j9iCYtjW^;Ofyh0RUZdl0-D(x-x`L+S zT-&2un^Byt>@vDD#dfa58n$v6VTe6RhcY7uByRf7(Pp(?WOhI(k$6Z&^Qgefn-E2N zOf?BP-V>$HEeb}c&o^$b9N*hkj|5IbkjqB$Dot0N}8o05;a64gv6l$5+$dZ1~m4j zvHQ~4?c$|LJX^yL!Jv~QZM@;obwzv;Ua~;;B`9n@brPY2aTSBeWMi`OBk1^)IIFMvx+5emCaGmlXT=z#XfYw zoWeO<%oQZF;iT69Z-i*_DqLn|r9`x6O__CC-^0wl{rPc+UiwIrPRcyNXvDh6VO3n*P+hs)+21N5<+f;`r(sckG z)j@xwJ(iR!4MaRmSOK9#ITp}qav_f&oI45AVU;e!1zWzh>uR`2Hj(Iz@vSDN3`!ej zQC$XXGJ(|=um=oaHBuy`k0$dBRmhl%mVmdO4zDR@IbJ}NjVv}+)%S)K->8e&gp0^x zjlS75eBzDzz8m>*!wsb4gxm;VB^|}}^B|prmLNn}1y{42(M=B0_9im_Kn`(C7v9s} z3)s@RQc>Pqhs?lN%P*kF@~A;KahDtY?RZz^82yx4blGq-$~R55 zor@_YCh2U0!=g*wB?fCtDwu4K2ulG!fh~iwYRPRcfX|S7b?+e|8a5pmxTqpWqE*z# z>Y^n|vUvkY#)1{mKx^qQGDlT!rLpYREs3;lN!YqYI}V8HKG{(i(A)9E`{vgWjWh4z zLhxISn=~rHxrp%-tp>lnZBa3>w%!V8B%YC4eF9{!*uZuSF_DqVjtoUCt4cJuaW$9L z>O3Z;r2TGRmJy_)EM3~kr#WNfagnTm=nUr-rB61G8YXg%-e3*RxJI$8LDQQ`h19#7OjKSFxZ5Hh zv#`89L2DXDHWyJfk`Ah%i*4;C!uM#1d*)6tBh=!n{!m#h%<@mRVJTVc73aU~@H8$%ZJ zHN_a8S(4z=%t`66prl|Dt8Lz-9g}6UN~YAVX>3zVi^^aNTI+KptH>GKv}y6D60RUs zOaJ}d{f~`H|2EB|FLp3dAhGi3i<%mnG^bbt;Bb348Gp84{cpEfWLJk%2}2W=GIIvo zX>nAq2#xx@4@~cy0GH=}Ke+Q>BclsV$CS96`M@Qug!sDYJt^i3CO}V~yc-U{6{4iq|d` zseii%G%KojAVHxFKP#Kgk!C^L=HYcT=5z5Vb{=Jt(pYe@X&*mSL=}Be*FE_;ap0)} zf^U50iyoM!bi^J3fl&o@ovj8aDJgUwNEWZ3s2ctG4L^ROAzy@C`K*h*iV9F@G5}LC z{OyQPA|a6q{lHNnX6VD{$S5cv(GgB1yzVY7RT(LhEVWPx)xuPzMQTgagNv$$9(LDw z=@ifI@G=v)4%%h&ID#lVDokVzkjf-1Q({AJAN7N}NkSHGvxfDPizFt|;a5|+H{j_v z-&Sri3~VDEO%0sNBsx=4ckquL-snaN>1ImEF}c+i_Jg)j%=iYqTrR|~$jq7q`@Gp% zy0Tqj_aDOot^jFB8#WILsbmhxf3exJ9kP^I7f&o8Y@)%Tjqz9T_s+Eb%fopV+6}+B zh>@7CG=Ouu>n{&r?2V1Ivt~ZCK1_N%~~e6iJWHIc!)!{0Jbz|`(mDJL5_Q|4st4CT%xMWu3L*ZjOhUF zh%!&0M>NKzeq0MDrM?3h@>m_$V;B|16>1(Gv^fKXrz z1HG_!sCX`si;!Qw2z|IxionCio%yEN+NT;6Fe=g@?9KEZcQ9DUa ze2CWc!}%X{Utpsrf4hdkr=0V2ExCO{DpssAoLFljdo%}Ks-c;>rsFrt>S`mIkiuSxk*q>ne3tz& zIZ=g`JyVKYrZUtw{KU3iVTtITZ8IvAn#f44Z%xGKnGpWHCMkc&wbX z#1To%=5Wy<+Ne?){Yp_+)tmW#qa&JEVYrMNC@IToHtCxNM_*J{kYfTxU^45mcdN8N zmvJ>HMx@?uRM_Eaeo6xYlkLpF#IKw?XbXgY`)Mn+zvhO9}M!bK9F=q!^!6nPX0w5oF`!dR>u4MKw|C2h-?p)}Tqe<&vLx)o)0CnmU}8Z$C9_XORBE>nGwkYlE|Rqn9VymO`-OJd z1!ltl!=l*0w7c+X|6S$0D^A4nBusIgW%d_~(L|GRy0%P5V_xGLy{5DPQrL`}V4zI4 zkSXaC3EWrdoE4B9R=PgZv2$(6vXG$_Er~VotK~kjDO`aLRiMHYOyLiCVVEq8{7-oa z&b~rXiH78GdpBVKj%xCV3ttMV0g-e=iRQphKZ%5dV+bIHH9i-|_x3(e%#i?$7lmA8 z1VuoTvgz|#B{aAljG~59gPG1ac15NRemale)nU&uR?=J?AM*A(OuABqWdxE?VvHmr zo}i)}V+zzNUL=dQ`b2TL8lcDZE(>S`E;0zHRZ&q&>SbzIL7U}eeB{6}#2twbSa7Z3 zvy(uBZBCu4T$jOZ)+jv>gaotM{{OXoTXWn-vgSK~1!B)etbM|eMN%Xs#-2SvQo${2z87_C)OdIscNaywnY-0t!v&Va8%3^UFe^E?HT5 zv4#?{RnrneZf4$fz(HpVwh(Ze=O1W>|CY_}({^XpS?62US>yF;zBEupWyPQdU^)#u z24U@+EOu7>$fT!^17%?;n$H3>a`BKlExh=E(U67{Dsc)abVR`^$a9EpWoj#RGcsm> zq+WdS%n$*Tbje14Scxpi0BArjbKf3Hk0dbBsXOTC_RFWs=9Y|=_FPc#fPs)kWgm=0 z%iyO6)jpNRDs5#bQ_-Ye8Sv1MgS4c8!Q~HnEMsZz6g+=0OHVsO6@P(+)_wP2JT@dT zy?!tDE5V-|2d3J6Jygrdq*3?Sd3(l}9S z*Rl88Rk9RHI+{wz57#QYjCnQX`P23&6My+OZG56c$?e*V!9sb9%(Q2LZ?V`9eI7Z+ zV?s9RSyjgU^nKH?Axm3$P<7dhNKrCgjhYo2PFs0i73Z>W4`YkK#wQ*Sg8yJ6XVY2R zqK>-~UbrcJG9d_&?H^^G&P;jF9&}!&@icNH4|XjTaZ~zMAbP?LD%JY)_4-oB7B$WO z%!9c>Ixz9MiOd|djmUf=GS;C?GIkhb;xhexBYLMP)$7q?KDVScJbU2X;4B5{=2ZF3 zrW6+5A%`g}Ns`OhDB)0Vrg$sXDHdsjMzn+$cSY?Fk84xe!VPZpeK7o(@LBb$em1(( zX*Aie#bmSb+(vFTv$Eb`{GqBQqFdT^>0{sZC`!7gq2ij&W8qWczC3~7 zCCsDq*!|ntuZ>QGg4$&|cf!#lMr1l{m-x3X)?;GbsVjdMoO~(~6}3vhy21bt@g$ay z_}$IBJFb=Flwp)n0xwvunbfgL2@X$EN_xU=B`SP*hSa%w?X(Jllx`T@koZi25+!bj z@Gq!Vu(hrd?8;9Prn=93-;5ry0H(uc-~4=Gq)db%q3Xhd*R$(3`g!KN=%y#^KrvI- z-0i9R_xIPfRrc8(Rs1Z2ioxf?Fg!HPn?UDrJK#s!t3x^-fOSwhk+8EL=C;eN)LW8W zsAgG@1SYX0DL!(*Tw&tB_g_BwZu%wLdXwip;+Vu1C;3`w&t;xCu_}W-6x(1QI{+eu zpI)WZGWfTz0WCt^40`l|9zjtW)!XK8@IjmXTqVywd03xIN&vd%3*Mal{eZ)-t36L; zuTF3?(M^+2)(WtqA%(kh)y$QT*3R|A|FEiRcjv(&uD!jZc&6{n>BCutN|LHV> z@Gf6l?r6{)cPt=1QGh@NFrtmuSLb{QNft5+Mqjq)EAab6+bsf9jv3xA#Kj6_ zOz*#DwFoR3#ziY-CY6$!*QtyY;cG43GAA}*@1Y5o>c%O}$ zA1MLKLj47O!W2BS*;>1?%Uclbl?4S&d;!HiZj zoVY17h!C$ag>DRYB~Dy^#@Lb)+kE!8Jrq-92)w4!SlY$5C60*=_`AQ&j-ZU#xIS5|3Af2`7a zv!=Kz{kC)<779xCn9V=|)++#k@;$^Zs85Rm6V?y_B6gJ1hQ}s?k+7~+=d!!(Comfs zt04?Ik2zgVHKYzZU?I0S7ZJCFtA>v&;@ji01H;Bsp*E?$5k-N$Dc8d39ZpCdD{=`C zn<QL{#8^^v}B8Ufr{~qd} z%h>RMa;MisZ2;UiYrl5XN;NZU;-7IcOV;%ugfr$afnZ7|v&Te?wOK5tU;$wu0mV(v zm`BAf-!iX4y@L&O2qf*eUOc)#hpFBD%EtA)QG_+ITve+k>MWbWI=EVy^-lst@Dak` zcA`UI2?P#{K{o_lPX`I0U7Q?JvemSt<3&D1%7wvpZil=(g}m@pBtYk@Y=qJ^<6~{0 z1i18!u{5k0nH|{R0K80gA4h-z2@W7`6`}k>V)FB-WjJJ@yts*|^H08D_=B!UAO?K# za3}uPF+mkgvv~74|E|E&N3kblw~^MdFRmmoS0?y4f<<>Zg{I%H6bKto6T|q|03HU8Dk=s z=<;U}K)Y8gh9;(^Ppg3&nPwDdtQtUdXsB*bMvmIi{~{luvqQDsekR0L|9NwLCl|sw#hr>4H%;N4om6z(Z>&j7S|BrK;M!~ ze|PJ|&6i-Aa;H^Ti!kuuvkjY{O>=S}z*dlq=SR>aRy9^YdgW^hty2KR>zo<{NUbl7^V&+Hs zrHN9ele1WRj@eAQqftRgmPQ2$M|LOYn}dsm=$Ix1pJi@zMqVT7l4E$Qv`a9g`V%j4 zA|==yV{N-`^{Y<3Bw#U&+hA12Je{sQxTi4OoY~m_h+w*>ahd9V0%kopo@13KqoEO) zSC4}6I$aiza<+Xs`}^eT?Dm)F63R={Icu3>*x({t$FS>)Q;Zmi`4BtRCxt+6z(x#* zkz=RX**cjHK>*z+9pXUGWAh@#uOgb6&J@}&T$Y-U+?%wkEqaH>pY;`J=v%036h@Fb zT|dAVrTyX0@Xxqo7131sI0LytF{~gmvRQTMXM!HbQq1%O5i5tMFjJ|aaVmBM!V9dy zYp=!Fw}z#5RXWF@h1Nicv0Q&C#j|H+Xl;!#PmWetAIu6}Dn%>&<1z6J*rdGIE;{ma zL21o0{*NN_oDHq8E6qe^!VbQc9g!IORd$2YIC@eR{{GP<*o@;YC-0Yl-J=;Oj4uQY zP%9q(2}i$O29sdb!AP#Nn*5i!UelF7hR|?hZV`i0kXk`LGHK|Z%7E9So>_VG;BCbZ z7)PgHn6B|-FrCYLd8f&_=?DO7HoE{|WkYZ}`0@$%9n2f0fO~D(4qyP%4SYtM7r3!> zgEez2;rqg;dymW-@j)C+CNNL$GCvk8r9c}iTJe=BPoPInQ*s>{1qDcKdLOmeP5&c- z(dB`(gzE>Hp;!T}x3PS{9zhfYb^*Wa$%wFkNy(H_aqpUlNJ?tEWQ>iHt*UKLi=?hr z>C=w~ua3;o&$O~K9wVg6MWYwM^u1`Hm~{<$aU^jAgW`R|AY^QC1HyD)>cx=6HU{mP z(gNTaea+mFTF2l#8O5AO#787z?5?E}3AAklhlQF(uG>>rl1XJ@G##9TMvSh=G_ZJEB!uU2|oQYRTj@w9m))D@$S%!YKaN!~X#( zk?DSug>d}*^+II}1U3p#4dJ{3Qz#S^6(<)CYo)B3cfXIVY5tpJ=HW0`%~v#i<&l};~7%-#{N#afWYjR4#J z>7jWW!MS@fDTvs{;HE$6Gyi)pB;e9m*2^-nv;>vsb4PfwwTXY_Dc_}76}of|(MDR* zn3J)`W__{tH+7_1C6yi%xyw>xE$ofZLLbuYKvb*B3nVCSBlj3o-N5?T)*Vv z{e6?<6l9Z(tnSm!J9(>_wGC`P0^l$$b{WnSb-w3-XC-XeHuR>0s2wapgF<|!8 zqKxn_1QXlRX5If@NE#C+XF2nPqfGNYe9vhwxJSiL^1%0&DHJa+ryw`Qp=& zS{jo?cdK+dxwL?xq|$Op;EX}BS%M*OAH1Q{Irg+zNz&}mxNGMOR5GDJnjpI7n;ysr z0MVPjVDx5(fcS8K-!Ei;pb&YortjKys6Dn$*P5OX5R4LV1Q|XRc}(On0+8vcF4i(l zl*85~=q%F{6|uvdqB6Q2Em5b@Syh3D$t=1>z&*+7Qn|&V00AZq*EBnxN0m5QNsr7y zE8p`D4$P1^zGuNQ^320$hwSod#VS^*OjF%{Wq4|BV&L%oh4-&wh0dkE{iMQZoc0}& z!6&bY#7}>uTnTDOe--tBE1aJSafD2)19(irab6@L7g}$V>PbTTB}& zPJ!|+YqiPq9kB$biLx$muc(4e;-9}>UPf2UwMWTDoznuJXt7AA?xyMKfD2*}k^CAZ^Z>%$T& z9|%Av+5ndX`L1d)+$^n_fdOk#F%d^|@vV~8%q3YU#>7;_noe+eS6+J3*lW}fGx&NA z4$j`_=v?lKAEL)3-*E6Mb#IZ+V#+)y-EO^S_vQe=wAORp`#DSDM}@IhtRa4NGNszo zei!kX9OA?fn+#v@r^xte4?^)liNGKul?%@eZI}ASlMArJ?GGDUySG?J(g5g8gplT1 zHO#ECC_}~=^TpEDr+sx~7F97_PgEflq26g*rUI-su*Po(?4}YCiU3U08RiGpgfMJDeN4Irm{l}}Z~S4I5qff> zx~z@qSiS-fc~(h0$e#n%wpX(-q@NVM#(<&@fFrGo@qQTAIrByGl4t)k60`IXVoM}u zhm?aIr5v0_(?tqtSl0Uby+h97j&crNa-#3Jj5Xx;|Gq=&n;oUTky4ZLE~_y?h}eI~ zg``8=(T?JdP9s<;W6cH)6HVhD*pMZ;-sj;XSMUfZx+dwGIV4ygIti2F2 zvRd(DT{`SAW6%!z9A8ZY?>7N6yxiU5c@a1xeiK}{>&SgkaQ=G(6e`M*-?Lulc95W9 z^tz|S1>9J{&ah;!7V+NY%S^xG(7Rhe$d_v!3sRK#ViEZRJ}e~y?+*5p2#SmB$6&bF zE1U)^nc`oakugCyRq)fPg$nUGU@rFfld><=`;^?;!60GuM};m`u{TW5Mj^w{dm}eH z15onPkapmO_zzecgHpn*(&$VMj2{sHgHG@l{mSPKlq80R*n-kz877L&XEKK%AhbhE z+PrpcSMK%;qqqRz7-cUypg3B`jQ(I|m4GLJ`$`pb*pm*&yLu;|VM*79cXClZ!|oH) z0I7O{aj!QkJQhf5OfZyyuizeOSlLp%;A2V)#^I|s-YdyBY}RvdiQ_lvUKhsCj4!^- zeZabb?3aRe18xxV7T8h((bS|p?|Y|k%HOpUYY z!>V`^2L&2Uls)ZYH7!c0pa3_TH^sbu5(_U$7+@8b_CY-?o>p|R0mvR_n(SWg@iIddj)wae&QB>P^g5}kq1X1z zBd_e&7}<#l%CpswECLm;U$q69NvxhVayVXr#Xrc>-abj>-hK-$^wghF{{a832GWqfJYU51c&hi z5&^9EvYPQvUI*fzygr5c@0cA4YdGqRdMf5ZV(y1x?$i4>9BbwBFX0aQec1@^;8b2B zi380SxXDOC5mz~rFzva%1ZDWQq3~}{`DRu|C~$`H+lA19A-zp>L)GPq60r|ozwKAS z5c;)%K9?6DVln!l_Xb9K7mD=m6c$Nb(v-3SMcCQnp5XRhhkhbKd8(7HweP1H?kE`U z=#;L!qciZ;RFRW}vmZJd1?8#E!W1iGwA5f3?jRUW3?0}-bbdodI1WY-^ADT`q1fyt z*GyoHx4{@<7+j~1m{97c&3tZp&Pc3yvz{g1$T!2)QbR(sbgXzI6EwLmlQ327bY|8% zm!jVVzlIotXLl7UA(Y1Woa3Vi>EI+3>EPs4Wnq#jEM*dAX!p%lwDDQO1~>3PG!UC4 z4tdjpuh$9WP2fD+e{+flC(Qdp&%25(+5Zn-_=6L~M5p)*56r1web_-9Q^?Z(#rY zm1}%_Fl&4ujCaFp!oYqf&TjF|BEdJ*N)iE`9QPTd80ZAl&Q)@UyYDm=ipLx@jTElK z=%28z+-)QF28h@=4zBMI|I4}5q5Z0ux?9^e2&@!6S4I`~^G8L-*oj7vi6RIh*S@B>0 zu3%Y_se(Qlg++nMTqY@H7%}O^0x%7F;cKRaZ}4+o+@TK10grV{VRK_BHTDKL=9^}B zk>MhalNI`!6XtX|<9n|rtYPO+M6vNGPTMjhjO1F=1$=bW-YmFJE}VsI3`q;#Ut@hvd481 zukqLT(61Do__4%8iA6Y6fw)(ZVIW4qt73%dFF%1sdNhm$y?U%NQYiaE`@+80HraL+ zz*eYVi&egzczp3~yatouz)yhB6p*;`4~Z&!He;+{nd3Av=gi4KxoB(Jl~KgPx&&&v zSC+wk;yD`^Fe7#aw!diQx}wt<#-KtS`jtkv7? z5F?!;&beYEGq1td2hA!)Ptq#5_uiCn8~JL!LE}aP`bt23U?^jF7piK&Ajou+$YKG=DRIi!jARY$AA><`+~`N!_-dYP#pa53r3hi6g+kVN zg-{mvp(!(fcG6oE%ayJJIE`{zDv}gVr%A*qclP+d-j$&i$`l-qCc1pCjOH6E8N(&{4M`0Olq$Rx$b&iZ!glBkxpekS*3QX4&6iNRrb66N}Bt7xU1A z#;geUm{p`^on2k@YFL^)267u9&|k&`(dl6**AbN#!o*jdLD=qyN6e6f#fBgW76)US zpHoPfW%rPT`9&h$BZgnbuDC6sjS2rJ{%Zu|5pKm@yXFp$m`0(k&=iBHb zIE(({_Lnc8Bh0(;dT+hC%QK9Imd6Qy%{Fp7THXI>c@SMw!dqOPEKee=It>@siNbXKI)v45cas!2vDG6s7HP|H_wy`953ksxB2b@3vb`3(R%A5Mca)|~LYmf~Di zO#9QDfBpt;=ue=u9Q`Z#AB5>5PE?a8HTZAj}|xI7ldaDizu%*D=aCh(qZ!Q7>nI% zi<$_iYO&uOriq%?Fak1h@U>m=@$Z`~t;Z1(|Lzs@`?r?x-$85rA0tT-8Y&t`v@p&I zbDB)x80X6+(>mhWsbp-dn6cV2RZTmXx!d45MAPAhwEM& zsb8JYT`d^*rF#ZawOvgo^P=pOy2GcnV0~hR3Lr~ajwqE;Jwm~m7_2RplQmn@lTdbWTYPg#i@$DF| zE$S)B>M^%vjn|TeX=m>T{NA)++hPUaM5YON`FxOQ zZaLX}L^0XiC#54N>n?KY)b~DCiokKCDM+Wpq|BXea!%M2`oBi=HRib z5&god@ugKRaq~vp_$UJBmg`niWIpEbRB&xU*|eT~gLS}x>y`~J_Ia`$QL03A$Q$># zn~sBMv@k-%^yc@nZMY~A)33T7g<#Hlda z(T{3QLgSD|dww$KeE{TxjgqP2u9(&w>tUj^wBHvZAm0Bs4( zW)pe*9#Nu+>Jo`HBgd6TkPcx`G!-+>j44imwgt||-Gn4wThKDOAAN&0Kpg_XV{6P6 z#YAk2TP@Nu!(i<3I@7>(2poIj`DY!3)g)MgU25&Wr&U168eyCCo`d> zj^uKn;rxcqF3HGcvTCxPjL0EBv)S1)x^%s zKUPnhxGmXvvb>v(=^AMQwxx*yKCW@mLUhRMyu}|X%5!(m4<^$^GUh68!Fq*`JyDvt zZNbIrUMC41=~We`U)1p}}pZ8_r7y7a87OG*Si`clxubqKDfBYTz_kPdO%J8=krNH~H04PMs? z?`y`lxY}_*x5ZOD*ElC725SlFvYibZv~Hsr{5mPh$*6w37HC@}mvSESplM^eL_(?P zvCTXdtV3u$Vr+;)Yso35_1G__AYH=7KSmp%ZGr1__3f4#H+s7f<%qk71anCl{r$?$ zml|()O0brc@qI%&97EKjPOHG~5wy3rq=pje$K(96PIT)f9#A zY6#S90RPL8EEX1`Lta&lxuk&W-yVSqXW z%0yvf8+)9{UGm4X=ruvRq>le_9oUWrJdNcHO;BwKn2u^Bqm~47NCC&_Nd*Z##u8;9 zw&X!I$x*Mi4ZyZAPEkG?^@P(zb%i&N4EW%fNg1uY(8expMmF)Rh0GEHcu^#I$V%@h<*zrWViVd zo|X_qE)cEibT5BP7qVCW*xqjrT(9gAhpUO`l{ey$H4$C%sM^VxV~G(R!j|>8_7aWg z5LU`Mjp!0~FuJeh-wkJuR{xrG2nO1F|hH%V*Q%8@TDUfE}Xi zMW+I`gG`C&7B+6L`g3NfM-!`9#Hdm=bW8m6w{h8j?)2Gz{svC_&wj7{=TUD|pS@SA zTd?&_#!G@`;CWX)2Uc~WIu2L5bSHptq=q0 zwBu<}Jlu)@snQ_P-|Fb+uNPS0kBRnv-y}Je-P9gF{?zM=T6*#PzDYM}cfN9#^oog8 z^4`AzD`zZcoE+=X?F4kmtc29rwMbzx>rUOU`^undGkAwFv?9G^lI27-$bh0HrD#I2 zl!Zb(?@L6j@`YvcWQ2qa68a?8?|DX*A9~6qn3O6BeDZXTKVRX`s`ty(%nlPbR0>x(Fj zZi{tH^=tJL5C9c8J)47mYOF>4i(tJ^pZ)b8@NvhM`^%T#ZodFXS$m5s)kdYA>&0>5l8t+T_=!nt;Wex&hpUpRT#ImkE^#1tzp!8`CfS zwMc1Xf#_vgC$J$I#ng3CA`?iURz?1pPV|=xECR=jF)?1lUj$#wsoW$$EBnx}V;a~0 zo`BqeZ9>Kv8GnNMrGO*b%|laWhP6=&fGnv>P1Nf z$rRKjWOP<@32KqR3WD~Uova+!3<0(qY3wLByL{EnD&|^|0fsA}HoPW#sH^0eOCNT= z?I>KOIRb472cZ%UPO*j`sg%(#P~*); zItoP+uZ>24xPs!+I8tDtY`~p_!kvg$M>CH2wz?vr26NWIbHXttj6JL@4`sbmX~~Mt zRAoE~jh=r2U;6{vR0PruG64TZtRLI>DJfU&v8>iLCYwkyW9?3t$$C-r8bDiH-Hl{a zc0&y{Y}3?8YN2J{Z)X`lex|vZRu<8?Luc+Lvh@K`-&C_k2O^W*+2u9aHZBK3oHy336KmleMH`@oyxhX+Q3uu2J<(ueo0fw4Io74rnZjjK0}iuoDUjl zh{TV5gU|P>1uWxFlgDZ@OVjmaTCBIeqs^MXAoGBl1UxbFh>x&H;au8zAwx9H>lo&g zYj_ANh|A`6tMF_0n3XJ4D+5ij)gn)ydvs_&hv z5fD-k44PV;0*16&@-!PQ7NHsLetwCbeA`)($>WJC3QIcRqE&*aNB?VSVzaf!$TUqgC)&^e|kv3HtE6WxP zp`ET|S%?7pA(Cip0QBC~f{7~Tb2^%*dJS3fLi7@-wbv4o#PB91E>+&j$Qn!6M8;NV z*4RR;q+9uLw2FMljmYC3MI8v^EDD3~ZBU=Dm_DR+&pRMZOLZd7-P(`5>J1plcS}gm8_aMd#an9F@9Cb9ak~4$dKZRj zbOtyo7Mn1H&jrN%!m)#(B(K1l*Rd6I=NMXUhgoRXypH}SGYcrZE9>YVe6E@CPw12g zdj-vEgN@q6hfYdfbstIKZ-zU%VsGkHwRLB|5DAOX}ELT;0w~du=Z6DCJXmcB9rBW9K zzVj2@Nzj|)UgdyXvE{O%>kW}2^Z@pJkZ4UM$R%({zn*L4j#t1C_UWdshBn@4xWwQI zW61&ELvRs@LD8$Ilu4MZTg?zLkO@qqd{DEQ%O1G+pgq8~s7)!>?_oWUEUjJ_noP3E z>!FQ*Pi&Ezzt%L@@Y)G92v*$_nh4^!yh>`X*Ki9$(JKsG3FESOiiP@J7v*-)2ZG&+ z&IT~V1WH6GnejnTLhyHw1?>GMn;8J;RTjh_D;_!*!KV|a*;U{;_(Ye;iphairvt&} z(qpy>rXIWu4O8qaihMS3Zo&7mc*So}Y+cT>Yz5OU`hAmHAJgOc>RaKJ7op-8UwFvW zbnOvBSrQ{G$-`D9Cf3~B&~2KR9T?rtm1a|BF*w9L4C;8HfY7JjBYP)qWxEgdzJUtNl#QSL}ynQ(T(^m6Mem9zF7Pj=PfTanu@O+Mz7VU)EGcKcTYPPbnWa;$9W$4Cch5he|H|N-70K+`cYL7< zx*f(2#J{nT8%E(huKEKZe`6#0xdPZjhc`4{i9LSp@eW*NHM*%T#gLVtWL0C8<}@P5 zxddI&i#5TDo~Y9$e9&}QFxmO#MUs&Jk{&c;=*|ios{c=a!1oA4|1R;Tmx<8!Co({lxjeOd`V4>kjpd1SJ z8*#NDfn%o@B4ZPe+BO`n-MTrLMBtKrjsLhy7s+E*_?!X6ummz?repr^zUQeyDB{nb z7-x?XkbtrS)7qt82H0CDtC+k4wy+EVW(D&0tvNq!U>a=j22|b=Oe7Ll|Kgh+rD5FR zXeS2$*g{)Mr??=42BCbC$141@+OhNC?S8@xc-)N&FfAY39yr>4|5;g&ZsB-(RTfh) z7z@Z7<^-TZ{B3JjA8WZHH}^y>|=L>DU>t(HIYW-S)% zbmoiG(9boR;-K$dx}Cy3su-Bw7^?dz(;JA)9-Rwzp-%mrly~4adS2u*xT@L+ zz4~5kRFrHiWRpgJ@Q9Tg(aLQF{&b5NCX?rFw^++>F)`;G2Jwl%(f2ZuF(5c3x78~k zkEDk?`8dN*AZ;R)>%j+st(e01J1TSA>aw_3${Yq9dMp`yLfV?VkY`5CyS+N;bHfu9 zreBp>>}yrnIgF7%zZg&A0qYEeB4!GF(IAwsOq*5Jh8lsf61~^n4H&-pjvF`M60X}H z)rPuFN-I%@d>qGYn)BUvTR8g4TfGu-#|EHKC7}A{u85M|gj7fL9q>2>ng&w=jXQvG z6%7q0G|aoA+PV84O|a?CAHhV~xh>XL%y;f?6J_^)Hc=j5*t?n7YKBf0*q)5ZQaxZT zY!7=j_7;Co&H{|l{rVmZ_5SH{ z&2zJJ4Q8_TA}slr5AaWLu@k3e3~UGjdavpA7LuR|TDsp#`%3qVt~28db}J1$=4&EG z-aRclHw-DpdGRq`jIa1E znLbqFytDvA_5CL8O$z|J=1-CdY}SHFAPM!ed8^Zr9_3chM;D;Aptos^h2X$qTgtfq zj??8W@#cp7>JLDS_FgO;;d-!-jiz&r<@=;A$|s_B*%v3jmkO$g%v0-W%Fe-x{9NGooc zr_qX8JVF#TV9#8k)RgZpHgj(bOA+Whco1%n7GNQ19e{q0<3*aU{R*AIZ0K_&cfrE} zVOE>v9e3DZpp^+E?KnFjtxcpdU8hOC8&GKiVKC2bIF*UBk+y}wFdGx5_l(np^k^V0 zUjE%zFaP4}mw)Q=+^tqvyZ1txO(3V9LL za>VA?+Xo3`Ev3FD5vf|?LE%$IIf)~q1dA@Os|J#c4*bGqSIpfiGvxS1f{tTIN=8POTDe zc`WR{lwB~MT}iv@HQjs!M@0Pf=l`wO7#C6f_2>WF1M`LEQa3;z#BQ1I^u=!tB-80)AdF;HVCOHK{?{)YF1Ii2 zjOh!P!TAf9u9uFj{Dsqh`NDZ$zHp*eFPx$Ei>4Kr&U%cnlFSHlpdXAQu!3@G&7B$G z>N11)YRnigi_8j-9VShaCsy?v>vB^s0u7T$`YSkkqg@x=o$99Ne_sL^Fe4I^%;8tp z4^_R*y^dE>wXXFc;I@82l8O*UA_%yc=~8ShPfh61iHgiKUrGE*=m|^S`HlwQ2c5r<3C9@p~?~)p=B#@ zGI3txH;`0{wcm>JLFX?;07?_h+1D?VEe4AszPgOvytSRE?Za-$L4_| zrjRnJDE)(@Rr2F24kiwYNUA7_&J_%yf&&*iac5{B1>Hej>iIqidB0iCaM) zbuB1G%+fi!%{0A$x>4V2F0MhK00%YCY>9L6>28L(0!<<1Uo!+(v7^7gk;E6851vfG z6br7isa|~;36s49!CjRpcB7chZa@k?5UX?=KAZ5+x=jE0qkyb;cxwmie9DN11v}xD zrV5%mR@Ml)NL30|{E;*_GJBbW07ad9=q!iaW$3tx5l}E?E;N~W*&$_sC%tzig)P2P zNz5Al_jq$hw}F*WK7suD37rdqRD<9@K{h(79Kq~_hMvu>>uT>l1RMG}^NF#i2Dp|johMink|z&p0C3e$M-}Zeas6AslO`3 zh!BHFOq69>XH!PS=*?lr+$GzP7kABYqNr4bp0ASxH|bdhv@{05-P1bohH4K$atk_YQL$toE{AYU;0B*rM5 z9ip$Rl5^GiT3!unF>%l1?hlC-n1p^N{@-@Khn8^E!=;RMK)?*MmQhv2u$2N$|G!BV zh2jk3=xUfuhAi|b+ryFp2S8oZZ3%u0nZ1uPzYZX7Yi;Qwhz2oU z)c|#l;BJuXws^w6HnPDGuypm}$a(=ab9oAn1H#bv_6^dMHLexFB09#466=Il)A7-?Q;qH=Em^K2! zQ|heVsD0f)3b#A>TMh26$yE7t^z8!|%p;C6z@u^2;f=XnSSJ8FjfzkBL8pq9xMk7t zS!yHg-ERxNQT_*<($DxQ!#oxbgRC?clA~U<&nj6FzS7cX#WM;1P5||w#pR+l*OvdN zyk`W5{F~&FUYxbfS%eAP@eB({2>Fn1Awxx{g3%hhx5*uzK=QPfA)|7{@+g+rkQ;26 z+Rq8a8t2eFS>DZ(aFk1;Z?39v!xz^@kq4T_ZjlsrUdu?P&42(12e@JCKJfDqj`KTf zv>`f%-41d7t75E8I;=HhctR|&J7Gc72C7&%TNycqq23?@p>hJSpf7OAWoC)7SZA}W zSPtxMU=#9g)9GTB{Vre5QNp5YL=kyoixfXDQuHVYTR=Z)dg4cgc+f6JI<&Qi@sTj> zz-ZbZ_>sWJ7|1{buKEWl+*q*qzKp=I5a^FRIPieZbvi)_e4@#x0K4W!w+Tnj62KYQ zSp;Eq8XWjy<*yYsj6c~-8fcvdszBP zg1EaGL$R360>|+epu}_jijR~<<@3Dt%%(4tWg1L?6a{H`^#C63hW&@6#;0;0jJTX$ z;JD%XDHXF;1NJ|pZY(q6J@GBDOhuYhn=)-@2k>;#mF5*|hvFsNhx?d{v%v};`xauoohH*o8rGb@{`|kNlZvDN?5{unpS(Yr zD^mbg9Iv-=_kv{i+24pql??`*l8rw@3`LFOSedNu2blY*$hTl=8u!E(Ov;DAd3KG( znV}XU@F0IRE!L^?irxou0~|D6ao(@dr&I+%NX)<{@i%gUGFaDk)Ur6@euNH$3R!PP z6x)r_-oXY{P7J3?U)2kS8n^@9q_Po|rq+tg3ObCq%1sd>-$4%A&eX-Fxu0R$CGRbn z>q5gkPu?&$R^K2v$fOlC&B#>D>+LlZP~hYPm>rI6WkPGi06#VOt%Nk;hoM`%w?%6x zv5HAWs+5V!WqU|B?AtLKsb#okPxOg-4csA{vuStNBWl=f0vz*;jV_p3!nO%MzkeYs=!5&=g zV|m-#Sn@Z+JVd^#V!*tTHSG_N>FUt~2ahDqubG&XNp2cds2eTCCj=kkLt$!_png_}@xb0{wZY?r?Va6iVy9Bj&E+1~AYJJ$< zfTg!MkxiY(RAkK6%E@T#+JW9;)&kgpc@PTP^c2%8w-a40>0t}HwcI)Z&865}h_}AP zOzm>tinb>oC(?;yR8sZ&-U`Z?D4A`M_2>LVE+ix-LP(%-7KLB|2J3P0~mP1wx7 zz>>pjGooN+FA;y-ZEJDJD3fiNlkrcAya`f;15_3>C*1GO-rvf7N=f=ZF%x@RQK1@7 z%(JsUw7<9b9X@84yD^h!3lh_Uc^*6VmuyAaruf63w6ys$@`}ZHi)FeLE9zsGK7~Pi zLV7Vt($ z)>kH|R=rGbg3pwyB~_HkBdvdcTG)T2EAdap5);pxj=zES6-jkF`clF-*bQF*_?d1= zy=l>#LrGFw-*hR|$Bx9QjiJQExfv4azgNStb6U9!G-FuSlP$!wQb! zyR3f7s?;o#xmj_w;9Z)evn>u-@R`kD(ToY2i5jVl89yAF_g;c%w@kTIG9a&U;@!L{ zaU1QDPK9VCf`WN^31`ZV-PrSvQnkPZ2a{LrN!@Qys+gw2=t&l1V0RTmX`va*;@o^` z0uuuY1Ii(B3)?1rfqgczj_qq5<`7U9Hlm9}ixg zsFh?rLtk*xyiOyDU_d=&9eQE2JvWk?5>#X4+_N~nVWP(*%h61yu&v(M4oF7$Uh*g` zF$eB8^La=9sNT#LiaOM&^YDxOv{!%|OD&l1z@l%N>v`S_I}IOCF`C)HWL zgOa%3h3CFRcO}T~gl53lpVqr+Df}v#Bgq^A^B%qIU}Y7#deZ5+`%y9b6y+;BD>jgW{e@pedcUw37Qa(ll|4*6rVba&I+ROvxoI_^tlq!TPQO>! z_t%IcfU9)A$vv6Btcp#>^`_v^nZGv1b*Ho!1zBCKds1fP>Tix~Qi(zSN$`T=Xpn#% z%)TsbKPNP?&8(}o(W4{%>Qz}hW)xJ!HPFDan5@KCk(J@OfCUL~+*;B~VO?2DmlVuX z2=k8eMiB%=vn?G-?g@tiEOj7c_ zCQ+rctZrPMTMzi^oT)G_=KTlm+V%~0bE)ZEXnvGK-eQ&mzH7Mus79y7s>Wu}$o$b9 zU>1%!y!?Z!o_f7_yNe8JC*FwS;%TG#dV3yy_w%RQ@1w^oiR9NKAG1w8e+vV+Hz7T@ z^Xu)$_$`H1LB08`_7rSX57p?EKkRKb*{tVuDkz#s>#?S+wCq&F@(fX$BKBCT7^1WBSVl_j2_XH1IgH&mFvXs=GE7)np$kzbulgSJ-99R z=YlldqaZanQVVUQpE@Sm-onr(57ecFzbh ziP%7?mT^KogY}g?(;OBH?Q?l|R#oZpPBcw#txsS_6KAm9v*Q0o2xdO~r{pn>`>Q$t znMQd`Css`d1i|9015uDi!=%YWsU1o@7(~?E9VKtKe4E#HZEZEfS>{onCs*l{b<@~D zlchKqt>aEAuvH5&C3d*LL}NAB&cuEcAG|vDnzE0H-KLL^(QWLnKmW7BIhd`a9wZp{ zBzMeJo;=uxuinU)V?xa-4%$L-UT5omUPWqhZ`-==!({@7|2L$BcETIc31Ya4ed8Rf56&p@&ij-?tl*$| zCeEp!i&ZS+O7CFxw57f6|G*^eZ4^gmGfJ2SMF>=+1tmI>eb#)Pqy50wIocQBl&x@J z$R`gvFwuX_&arEoRwI9x0*i%0Kz%8G<0xpLYtN>W(Dyrm_Y-IH zYAV`~>CmLE8vXU>|B906F0Ey@5x6ZB|J2?CGABnWJwrQz;IfK?t&6Xl)F`nVCzc!CSb$PrVr-kQKdP~u&SR`ks91$u;eLt z#kCW4^r$9Pm6HqiU55^O)bQT^>Eer4(iIZer>b^-59d25T7zE~Kksdarq%p)Ud8+S z@&3V}_gC4|`-Ljf2KO=n-J@TsL97w}$kt+(_X{VwJ>$^v+B6ZHzw3|{=h@@639|12 z+3x|_H$e_OAO}4l2PVj&2js8^6Xe7L za?%5GvS$n-_c%Fpj*|-oa%hf|L(e!lbdD1fWZweuHD$lAE&Fz3yshbNj@6z656nRi z%7F=T=m9zG0XZ~5-grRX^nkoEL5@5iM?D}%Cdjb|-1~7d6DPj7 zSc9XNU*X{e4dR8wxL|4b1P{csU3FS zHJ~Q8FyIE-nQ7YzVo*0xQt;3SgFsT7e}tK!F>nbHgC^vSE=4zQ#G3u%Pt4=P%$aaZ zOlMrD6H*3sdVq|y3EeoYGzlhP=k<%mu0jl;B<- zG!6L^ToZ!}%b8fL3yX7!*;vz69kPKSoy|GIb~eYfD@D*kplEFbFoCuc4!aQ~t%a~i zszun`WJ-%Wo8=*2^Wy#G2h_cFEqj z`5VBH$0KCAGo{6yCx2{XIor!*8Mw`+$vQ26h=5x)5xH$})VTuyiLk-zNSN$lrfkV3 z_p+7x(8&s979ZXd2Y+ywLauMEu6+6-Bx!>m>c#$%gwDb*CcTXm!d^6ZAXxy6|2$Qd zaRwX)DA#~I5?oj?PPLxofu=B6iqsjLxP5o-8mxKgj@;i;ou>mccw(ky8Kl0!Wd@wF zm&rC-6?Jq+*FSSS-?y;ey$OJfn{3AiyRmg#%-b(;3^((b_I4(=Wf?}(!aI5sig)zp z)QGD8nW`F5m?-@CuWjg~VCW;bWuyG}P%Gduo56J&+!D^9aur;lE-?!@gfnIE6~%-X zpC*=nw}qbs3qLspe~UD}FB9Abs6GukM&Ozt#+JIoaCG3iU_tLrDL4==+AurhELpb- z)-~}@UhgzcP7Xtxb#e&q0r?ywrP?^b9}zC8bw$&hDniNXxNhvX!Psw&u~&(Wc?FX) zU5O#R5MK;08pUu(+n?v{eyEJM`=^wa5RZ@W$yXKoL7JFjng!$$VkAq80rzcJR71`; z>W-J0N(iV*=IJ_2H?ikW8KOotc7m5R_}f@t%5Mcz26v+nq0L)N zAJP!TnFwv(-(fWgSm%EtnFVfv(d$1vd+be8|QB8Ykgu z8}cOtRg;V2h{AY@)yu8>ZCUZ{li| z4RNgjjw+Y8b;B4%U&PZCYi$(eAP4coV=9t7tvkJ~kIf;9l=jKh#1qQbo8!0rP~^@j z^t&sl@mOL-v1W;`=nJ@lH__jo1fstc8vYHow2Y=rk7&~Nrr^Bnc!RemLNn8@%;EC1 z1GI`Cj6SRukW#QQz(~-$qd@R?Le0Je6Al(thM2r$d6$WkxvTl_LO;Me@d0#ISKcyn zS=H4>J$ilIk6NXoOIxpbv>*7Ig77r@x)NVq>}0SG3UyQ_f4uZGYyVv+wm67^6FDYg zpqWi>wWuvhhr}lQ!RtWygV)wzrhJlTHHA*5W*vLius%9C43%?ez6MwXqZ9&dX=ua6 zuGlnMHyA7=^gA5DsSfVI7iF=6>;gZxJ%AXwku0d(-LB?SF*X%zL!ISd_1hp!u*-ze#4;^JrSajMkl|G53- z%jZvLmzQ78t*BY~EllWs{pq+veIouY^+|ERzXf*6vxr@Jo2+3v-Wh=e7I3#(cI?y2 zj=Qy$W4E$$BE3dJ&gv&#{}BxXMYs9^Vv}{2K6b`_oiuU>yoU(uVvU~`G6+Q9#ea_k z$oD2F4#~Fxm^dWG{JKolB~@sm9)+Tcl~H!HRoMO(EJw|l9Y#Mo2t+?RIK{}E z_)eT8XVI(mcFN_)n}~;@h+?}?S&8pN_da0li|<-vp~G}~(&=VF?8l*>@_yNO*&o_`)%4QE)5j{6>CzC#}z7r$h*jkDmtMo*r!I+dPGg~;Y z;*K@9POPDRQvxTc=*)b=>3N;C651y?9hD5saf2B)j+Bpq0|U4PTU-~hBQBT`&xe(#&rnfdB3?Y-R+$cv*PM50{gkFq z3g#ijL9>mg$to6WAr$0_#XrSbmffQg1aau%2c2u%mOD>=|52O?1+kX1g)51_{`}86 zx`+fGS88t>mxeg$_f0mw_SYDItj`G0_3h=7Za4QvT1$B^b*5I||IqnSEf z(A^xmFbH{BKAR@xY{zUqzcIT`=!2#P&V}U5SJ24pbtV>jW;lZgy#$7cfSI+NG`tX$ zzv=zuC7uVb&>v=+B8n%gk~_y3DgjH}{MmezF7MLWteqCc$q%E{VBpHF3ajPF1>dy+ z(aJ$Zj$IOAljni$K+=rDgyAg72&>I~)7tKZK-yPDc`x6jQZR5JhF%Ro`bb6I%|OXi z)y-6Z4$G9cU7xaPSyaWmMg_3d&yzVxoH%_*9H^>yiBI{S$d)gqcS+W~GYVR^h)bEpY$FF$vRF}!yZARu<4UaX>xDFg)DCea*6WHXd9z!hkp}cPB8OaR zHD-{hRE#?sfmK&m6WkewW>bBhmA#pY1dUm$Q&({V<~3&6>rSp>16)xqKbgG*K&Xi0 zFqp5*qk)#5+AQLMWcvH3OR(~BvJ2&=Bq-v?O%C>wJ7?lH4^)E(a4`33&x@?LVoOMB z0|_&;TCW0wuD3%(YpUe=710`S*Z6}4x1Pq+JcCWMGlve5z9P~_CLK&mfe$#L;Il5& zF=WU=b9I8}0i4?`&1b#|U!mQ&J>4afoPhW@Z1Dq1cl-k}j0byvq-C-EJtTQ2E6A{2!eCW<|d?0WG?$$b-#dG zr1^R`n1u(pUFvw{j!69%rq@@XCRK6SxWVOd|@gEGdHh`ut|5%Hcf2iflyS8|F zr>)gN^Q2)%^WAh&@`G0H(<2V~?m zz@|HY9usBfk8FM4eCH2gqU_!^ghKYI{;inkT)Qzn>C-P;5C*3?NnxiMI? zDS%91M8QF3Er=&z`JcF4sT3-+5v=?R;}By8K~JWbLC%fe8o8dEEij(#BHLt_IlxtB wR`ma2v!X56xZs;SCgpI+1^^^iwi5k!y)XxR?cCeUFFRUZ+t?!iKT@F33=xCa2mk;8 diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index b2d4dcf2cc6..6947dea822b 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -383,48 +383,41 @@ autoclass_content = 'both' # Note: Our strategy for intersphinx mappings is to have the upstream build location as the -# canonical source and then cached copies of the mapping stored locally in case someone is building -# when disconnected from the internet. We then have a script to update the cached copies. -# -# Because of that, each entry in this mapping should have this format: -# name: ('http://UPSTREAM_URL', (None, 'path/to/local/cache.inv')) -# -# The update script depends on this format so deviating from this (for instance, adding a third -# location for the mapping to live) will confuse it. +# canonical source. intersphinx_mapping = { - 'python': ('https://docs.python.org/2/', None, None), - 'python3': ('https://docs.python.org/3/', None, None), - 'jinja2': ('http://jinja.palletsprojects.com/', None, None), - 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None, None), - 'ansible_9': ('https://docs.ansible.com/ansible/9/', None, None), + 'python': ('https://docs.python.org/2/', None), + 'python3': ('https://docs.python.org/3/', None), + 'jinja2': ('http://jinja.palletsprojects.com/', None), + 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), + 'ansible_9': ('https://docs.ansible.com/ansible/9/', None), } if tags.has('all') else { - 'python': ('https://docs.python.org/2/', None, None), - 'python3': ('https://docs.python.org/3/', None, None), - 'jinja2': ('http://jinja.palletsprojects.com/', None, None), - 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None, None), - 'ansible_9': ('https://docs.ansible.com/ansible/9/', None, None), + 'python': ('https://docs.python.org/2/', None), + 'python3': ('https://docs.python.org/3/', None), + 'jinja2': ('http://jinja.palletsprojects.com/', None), + 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), + 'ansible_9': ('https://docs.ansible.com/ansible/9/', None), } if tags.has('core_lang') else { - 'python': ('https://docs.python.org/2/', (None, None)), - 'python3': ('https://docs.python.org/3/', (None, None)), - 'jinja2': ('http://jinja.palletsprojects.com/', (None, None)), - 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', (None, None)), - 'ansible_9': ('https://docs.ansible.com/ansible/9/', (None, None)), + 'python': ('https://docs.python.org/2/', None), + 'python3': ('https://docs.python.org/3/', None), + 'jinja2': ('http://jinja.palletsprojects.com/', None), + 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), + 'ansible_9': ('https://docs.ansible.com/ansible/9/', None), } if tags.has('core') else { - 'python': ('https://docs.python.org/2/', (None, '../python2.inv')), - 'python3': ('https://docs.python.org/3/', (None, '../python3.inv')), - 'jinja2': ('http://jinja.palletsprojects.com/', (None, '../jinja2.inv')), - 'ansible_2_10': ('https://docs.ansible.com/ansible/2.10/', (None, '../ansible_2_10.inv')), - 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', (None, '../ansible_2_9.inv')), - 'ansible_2_8': ('https://docs.ansible.com/ansible/2.8/', (None, '../ansible_2_8.inv')), - 'ansible_2_7': ('https://docs.ansible.com/ansible/2.7/', (None, '../ansible_2_7.inv')), - 'ansible_2_6': ('https://docs.ansible.com/ansible/2.6/', (None, '../ansible_2_6.inv')), - 'ansible_2_5': ('https://docs.ansible.com/ansible/2.5/', (None, '../ansible_2_5.inv')), + 'python': ('https://docs.python.org/2/', None), + 'python3': ('https://docs.python.org/3/', None), + 'jinja2': ('http://jinja.palletsprojects.com/', None), + 'ansible_2_10': ('https://docs.ansible.com/ansible/2.10/', None), + 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), + 'ansible_2_8': ('https://docs.ansible.com/ansible/2.8/', None), + 'ansible_2_7': ('https://docs.ansible.com/ansible/2.7/', None), + 'ansible_2_6': ('https://docs.ansible.com/ansible/2.6/', None), + 'ansible_2_5': ('https://docs.ansible.com/ansible/2.5/', None), } if tags.has('2.10') else { - 'python': ('https://docs.python.org/2/', None, None), - 'python3': ('https://docs.python.org/3/', None, None), - 'jinja2': ('http://jinja.palletsprojects.com/', None, None), - 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None, None), - 'ansible_9': ('https://docs.ansible.com/ansible/9/', None, None), + 'python': ('https://docs.python.org/2/', None), + 'python3': ('https://docs.python.org/3/', None), + 'jinja2': ('http://jinja.palletsprojects.com/', None), + 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), + 'ansible_9': ('https://docs.ansible.com/ansible/9/', None), } if tags.has('ansible') else {} # linckchecker settings From 7d8a69b39eda93f323f10b05d430c753c4c083ae Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 11 Jan 2024 16:09:28 -0500 Subject: [PATCH 159/536] Add how to request a working group (#912) * port over WG details from wiki; ` * add WG details from defunct wiki * Update docs/docsite/rst/community/communication.rst --- docs/docsite/rst/community/communication.rst | 94 +++++++++++++------- 1 file changed, 63 insertions(+), 31 deletions(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index df67f648322..37204a9e38b 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -12,7 +12,7 @@ Code of Conduct All communication and interactions in the Ansible Community are governed by our :ref:`code_of_conduct`. Please read and understand it! -.. _forum: +.. _ansible_forum: Forum ===== @@ -103,7 +103,7 @@ The clickable links will take you directly to the relevant Matrix room in your b - `Discussions on developer topics and code related to features or bugs `_ - ``Matrix: #devel:ansible.com | IRC: #ansible-devel`` - `Discussions on community and collections related topics `_ - ``Matrix: #community:ansible.com | IRC: #ansible-community`` - `For public community meetings `_ - ``Matrix: #meeting:ansible.im | IRC: #ansible-meeting`` - - We will generally announce these on one or more of the above mailing lists. See the `meeting schedule and agenda page `_ + - We will generally announce these on one or more of the above mailing lists. See the `meeting schedule `_ Working group-specific channels ------------------------------- @@ -121,45 +121,75 @@ Regional and Language-specific channels Meetings on chat ---------------- -The Ansible community holds regular meetings on various topics on Matrix/IRC, and anyone who is interested is invited to participate. For more information about Ansible meetings, consult the `meeting schedule and agenda page `_. +The Ansible community holds regular meetings on various topics on Matrix/IRC, and anyone who is interested is invited to participate. For more information about Ansible meetings, consult the `meeting schedule and agenda page `_. .. _working_group_list: Working groups ============== -Our community working groups are represented in forms of `Forum groups `_ (new style) or `wiki pages `_ (deprecated). +Working Groups are a way for Ansible community members to self-organize around particular topics of interest. + +Our community working groups are represented in Matrix rooms and `Forum groups `_. Many of them meet in chat. If you want to get involved in a working group, join the Matrix room or IRC channel where it meets or comment on the agenda. - `AAP Configuration as Code `_ - Matrix: `#aap_config_as_code:ansible.com `_ -- `Amazon (AWS) Working Group `_ - Matrix: `#aws:ansible.com `_ | IRC: ``#ansible-aws`` -- `AWX Working Group `_ - Matrix: `#awx:ansible.com `_ | IRC: ``#ansible-awx`` -- `Azure Working Group `_ - Matrix: `#azure:ansible.com `_ | IRC: ``#ansible-azure`` -- `Community Working Group `_ (including Meetups) - Matrix: `#community:ansible.com `_ | IRC: ``#ansible-community`` -- `Container Working Group `_ - Matrix: `#container:ansible.com `_ | IRC: ``#ansible-container`` -- `Contributor Experience Working Group `_ - Matrix: `#community:ansible.com `_ | IRC: ``#ansible-community`` -- `DigitalOcean Working Group `_ - Matrix: `#digitalocean:ansible.im `_ | IRC: ``#ansible-digitalocean`` -- `Diversity Working Group `_ - Matrix: `#diversity:ansible.com `_ | IRC: ``#ansible-diversity`` -- `Docker Working Group `_ - Matrix: `#devel:ansible.com `_ | IRC: ``#ansible-devel`` +- `Amazon (AWS) Working Group `_ - Matrix: `#aws:ansible.com `_ | IRC: ``#ansible-aws`` +- `AWX Working Group `_ - Matrix: `#awx:ansible.com `_ | IRC: ``#ansible-awx`` +- Azure Working Group - Matrix: `#azure:ansible.com `_ | IRC: ``#ansible-azure`` +- `Community Working Group `_ (including Meetups) - Matrix: `#community:ansible.com `_ | IRC: ``#ansible-community`` +- Container Working Group - Matrix: `#container:ansible.com `_ | IRC: ``#ansible-container`` +- DigitalOcean Working Group - Matrix: `#digitalocean:ansible.im `_ | IRC: ``#ansible-digitalocean`` +- Diversity Working Group - Matrix: `#diversity:ansible.com `_ | IRC: ``#ansible-diversity`` +- Docker Working Group - Matrix: `#devel:ansible.com `_ | IRC: ``#ansible-devel`` - `Documentation Working Group `_ - Matrix: `#docs:ansible.com `_ | IRC: ``#ansible-docs`` - `Execution Environments Group `_ -- `Galaxy Working Group `_ - Matrix: `#galaxy:ansible.com `_ | IRC: ``#ansible-galaxy`` -- `JBoss Working Group `_ - Matrix: `#jboss:ansible.com `_ | IRC: ``#ansible-jboss`` -- `Kubernetes Working Group `_ - Matrix: `#kubernetes:ansible.com `_ | IRC: ``#ansible-kubernetes`` -- `Linode Working Group `_ - Matrix: `#linode:ansible.com `_ | IRC: ``#ansible-linode`` -- `Molecule Working Group `_ (`testing platform for Ansible playbooks and roles `_) - Matrix: `#molecule:ansible.im `_ | IRC: ``#ansible-molecule`` -- `MySQL Working Group `_ - Matrix: `#mysql:ansible.com `_ -- `Network Working Group `_ - Matrix: `#network:ansible.com `_ | IRC: ``#ansible-network`` +- `Galaxy Working Group `_ - Matrix: `#galaxy:ansible.com `_ | IRC: ``#ansible-galaxy`` +- JBoss Working Group - Matrix: `#jboss:ansible.com `_ | IRC: ``#ansible-jboss`` +- Kubernetes Working Group - Matrix: `#kubernetes:ansible.com `_ | IRC: ``#ansible-kubernetes`` +- Linode Working Group - Matrix: `#linode:ansible.com `_ | IRC: ``#ansible-linode`` +- Molecule Working Group (`testing platform for Ansible playbooks and roles `_) - Matrix: `#molecule:ansible.im `_ | IRC: ``#ansible-molecule`` +- MySQL Working Group - Matrix: `#mysql:ansible.com `_ +- `Network Working Group `_ - Matrix: `#network:ansible.com `_ | IRC: ``#ansible-network`` - `PostgreSQL Working Group `_ - Matrix: `#postgresql:ansible.com `_ - `Release Management Working Group `_ - Matrix: `#release-management:ansible.com `_ -- `Remote Management Working Group `_ - Matrix: `#devel:ansible.com `_ | IRC: ``#ansible-devel`` -- `Storage Working Group `_ - Matrix: `#storage:ansible.com `_ | IRC: ``#ansible-storage`` -- `VMware Working Group `_ - Matrix: `#vmware:ansible.com `_ | IRC: ``#ansible-vmware`` -- `Windows Working Group `_ - Matrix: `#windows:ansible.com `_ | IRC: ``#ansible-windows`` -- `Ansible developer tools Group `_ - Matrix: `#devtools:ansible.com `_ | IRC: ``#ansible-devtools`` +- Remote Management Working Group - Matrix: `#devel:ansible.com `_ | IRC: ``#ansible-devel`` +- Storage Working Group - Matrix: `#storage:ansible.com `_ | IRC: ``#ansible-storage`` +- VMware Working Group - Matrix: `#vmware:ansible.com `_ | IRC: ``#ansible-vmware`` +- Windows Working Group - Matrix: `#windows:ansible.com `_ | IRC: ``#ansible-windows`` +- Ansible developer tools Group - Matrix: `#devtools:ansible.com `_ | IRC: ``#ansible-devtools`` + +Forming a new working group +---------------------------- + +The basic components of a working group are: + +* Group name and charter (why the group exists). +* Registered :ref:`real-time chat channel`. +* Group of users (at least two!) who will be driving the agenda of the working group. +* Dedicated `forum group `_. + +The basic responsibilities of a working group are: + +* Follow the :ref:`code_of_conduct`. +* Be responsive on your real-time chat channel. +* Be responsive on the `forum `_ in related topics. +* Report semi-regularly on the cool stuff that your working group is working on. +* Keep your forum group information updated. + + +Requesting a working group +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Anyone can request to start a Working Group, for any reason. + +If you need only a `Forum group `_, +request it in the `forum topic `_. + + +If you also need a real-time chat channel, you can `request one `_. -Want to `form a new Working Group `_? Ansible Community Topics ======================== @@ -184,13 +214,15 @@ If you have a question about Ansible Automation Platform, visit `Red Hat support The Bullhorn ============ -**The Bullhorn** is our newsletter for the Ansible contributor community. Please `subscribe `_ to receive it. - -If you have any content you would like to share, please `contribute/suggest it `_ for upcoming releases. +**The Bullhorn** is our newsletter for the Ansible contributor community. You can get Bullhorn updates +from the :ref:`forum` or `subscribe `_ to receive it. -If you have any questions, please reach out to us at ``the-bullhorn@redhat.com``. +If you have any questions or content you would like to share, you are welcome to chat with us +in the `Ansible Social room on Matrix, and mention +`newsbot `_ to have your news item tagged for review for +the next weekly issue. -Read past issues on the official Bullhorn's `wiki page `_. +Read past issues of `the Bullhorn `_. Asking questions over email =========================== From e36fd8bd8a52db7cfda5e5285f5b6ef1b263fc30 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Thu, 11 Jan 2024 19:44:03 +0000 Subject: [PATCH 160/536] ci: refresh dev dependencies --- tests/typing.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/typing.txt b/tests/typing.txt index 33bc13c6926..850b6cd2275 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -30,7 +30,7 @@ filelock==3.13.1 # via virtualenv idna==3.6 # via requests -jinja2==3.1.2 +jinja2==3.1.3 # via -r tests/../hacking/pr_labeler/requirements.txt markupsafe==2.1.3 # via jinja2 From b762087d6dfb059e1c30555af957b81323dd4200 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 14 Jan 2024 00:06:26 +0000 Subject: [PATCH 161/536] ci: refresh dev dependencies --- tests/static.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/static.txt b/tests/static.txt index 68d776260c2..4c7916f08d7 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.11 +ruff==0.1.13 # via -r tests/static.in From 930858fa68d1dc98be5a86f165b0eecbd34838df Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Thu, 11 Jan 2024 19:43:58 +0000 Subject: [PATCH 162/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 303d557eaa0..98177128aeb 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -12,7 +12,7 @@ aiohttp==3.9.1 # antsibull-docs aiosignal==1.3.1 # via aiohttp -alabaster==0.7.13 +alabaster==0.7.16 # via sphinx ansible-pygments==0.1.1 # via @@ -58,7 +58,7 @@ idna==3.6 # yarl imagesize==1.4.1 # via sphinx -jinja2==3.1.2 +jinja2==3.1.3 # via # -r tests/requirements-relaxed.in # antsibull-docs diff --git a/tests/requirements.txt b/tests/requirements.txt index c499411c652..d44695224fa 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -12,7 +12,7 @@ aiohttp==3.9.1 # antsibull-docs aiosignal==1.3.1 # via aiohttp -alabaster==0.7.13 +alabaster==0.7.16 # via sphinx ansible-pygments==0.1.1 # via @@ -60,7 +60,7 @@ idna==3.6 # yarl imagesize==1.4.1 # via sphinx -jinja2==3.1.2 +jinja2==3.1.3 # via # -r tests/requirements-relaxed.in # antsibull-docs From 16bd82acbe3ebbde3a73d7076bf862e7875f6b59 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 14 Jan 2024 00:10:42 +0000 Subject: [PATCH 163/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 15 +++++---------- tests/requirements.txt | 15 +++++---------- 2 files changed, 10 insertions(+), 20 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 98177128aeb..aa4f6d245ca 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -120,12 +120,7 @@ sphinx==7.2.6 # sphinx-intl # sphinx-notfound-page # sphinx-rtd-theme - # sphinxcontrib-applehelp - # sphinxcontrib-devhelp - # sphinxcontrib-htmlhelp # sphinxcontrib-jquery - # sphinxcontrib-qthelp - # sphinxcontrib-serializinghtml sphinx-ansible-theme==0.10.3 # via -r tests/requirements-relaxed.in sphinx-copybutton==0.5.2 @@ -138,19 +133,19 @@ sphinx-rtd-theme==2.0.0 # via # -c tests/constraints-base.in # sphinx-ansible-theme -sphinxcontrib-applehelp==1.0.7 +sphinxcontrib-applehelp==1.0.8 # via sphinx -sphinxcontrib-devhelp==1.0.5 +sphinxcontrib-devhelp==1.0.6 # via sphinx -sphinxcontrib-htmlhelp==2.0.4 +sphinxcontrib-htmlhelp==2.0.5 # via sphinx sphinxcontrib-jquery==4.1 # via sphinx-rtd-theme sphinxcontrib-jsmath==1.0.1 # via sphinx -sphinxcontrib-qthelp==1.0.6 +sphinxcontrib-qthelp==1.0.7 # via sphinx -sphinxcontrib-serializinghtml==1.1.9 +sphinxcontrib-serializinghtml==1.1.10 # via sphinx tomli==2.0.1 # via diff --git a/tests/requirements.txt b/tests/requirements.txt index d44695224fa..c6860dd2ec0 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -123,12 +123,7 @@ sphinx==7.2.5 # sphinx-intl # sphinx-notfound-page # sphinx-rtd-theme - # sphinxcontrib-applehelp - # sphinxcontrib-devhelp - # sphinxcontrib-htmlhelp # sphinxcontrib-jquery - # sphinxcontrib-qthelp - # sphinxcontrib-serializinghtml sphinx-ansible-theme==0.10.3 # via -r tests/requirements-relaxed.in sphinx-copybutton==0.5.2 @@ -141,19 +136,19 @@ sphinx-rtd-theme==2.0.0 # via # -c tests/constraints-base.in # sphinx-ansible-theme -sphinxcontrib-applehelp==1.0.7 +sphinxcontrib-applehelp==1.0.8 # via sphinx -sphinxcontrib-devhelp==1.0.5 +sphinxcontrib-devhelp==1.0.6 # via sphinx -sphinxcontrib-htmlhelp==2.0.4 +sphinxcontrib-htmlhelp==2.0.5 # via sphinx sphinxcontrib-jquery==4.1 # via sphinx-rtd-theme sphinxcontrib-jsmath==1.0.1 # via sphinx -sphinxcontrib-qthelp==1.0.6 +sphinxcontrib-qthelp==1.0.7 # via sphinx -sphinxcontrib-serializinghtml==1.1.9 +sphinxcontrib-serializinghtml==1.1.10 # via sphinx tomli==2.0.1 # via From 940152cdf7502e6be7905a6f35a002fd441636df Mon Sep 17 00:00:00 2001 From: Sumanth Lingappa <42572246+sumanth-lingappa@users.noreply.github.com> Date: Tue, 16 Jan 2024 00:57:57 +0530 Subject: [PATCH 164/536] added `gather_facts/(yes/no)` (#1003) * added `gather_facts/(yes/no)` Co-authored-by: Don Naro --- .../rst/dev_guide/testing/sanity/integration-aliases.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst b/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst index 1d70dbc78e8..08e6e65c3e0 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst @@ -98,6 +98,8 @@ There are several other aliases available as well: - ``destructive`` - Requires ``--allow-destructive`` to run without ``--docker`` or ``--remote``. - ``hidden`` - Target is ignored. Usable as a dependency. Automatic for ``setup_`` and ``prepare_`` prefixed targets. - ``retry/never`` - Target is excluded from retries enabled by the ``--retry-on-error`` option. +- ``gather_facts/yes`` - Enables gathering facts before running the target (default option). +- ``gather_facts/no`` - Disables gathering facts before running the target. Unstable -------- From d9e034c86253cfd97550405ce6ca9bfba0d15729 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 16 Jan 2024 21:28:44 +0100 Subject: [PATCH 165/536] collection requirements/steering committee inclusion policy: change (#995) * collection requirements/steering committee inclusion policy: change * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein * Update docs/docsite/rst/community/steering/community_steering_committee.rst Co-authored-by: Felix Fontein * Incorporate feedback --------- Co-authored-by: Felix Fontein --- .../collection_contributors/collection_requirements.rst | 1 + .../rst/community/steering/community_steering_committee.rst | 6 ++++++ 2 files changed, 7 insertions(+) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index d3f0a1a8a3e..69339cdf65e 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -528,6 +528,7 @@ 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, see `Adding a new collection `_ in the `ansible-build-data repository `_'s README. +* :ref:`The Steering Committee ` can reject a collection inclusion request or exclude a collection from the Ansible package even if the collection satisfies the requirements listed in this document. See the :ref:`Collection inclusion request workflow` for details. .. seealso:: diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index e7ec234c616..21d229e13d6 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -133,11 +133,17 @@ A person starting the triage: #. Establishes a vote date considering a number of topics, their complexity and comment-history size giving the Community sufficient time to go through and discuss them. #. The Community and the Committee vote on each topic-candidate listed in the triage topic whether to close it or keep it open. +.. _steering_inclusion: + Collection inclusion requests workflow ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When reviewing community collection `inclusion requests `_, the Committee members check if a collection adheres to the :ref:`collections_requirements`. +.. note:: + + The Steering Committee can reject a collection inclusion request or exclude a collection from the Ansible package even when the collection satisfies the requirements if the Steering Committee agrees that presence of the collection will significantly deteriorate the Ansible package user experience or the package build process. In case of rejection/removal, the collection maintainers receive comprehensive feedback from the Committee explaining the reasons of starting the process. In case the reasons are fixable, the feedback will contain information what the maintainers need to change. + #. A Committee member who conducts the inclusion review copies the `Ansible community collection checklist `_ into a corresponding `discussion `_. #. In the course of the review, the Committee member marks items as completed or leaves a comment saying whether the reviewer expects an issue to be addressed or whether it is optional (for example, it could be **MUST FIX:** or **SHOULD FIX:** under an item). From bed2f270055721d0a2b5d879f51c9a6e71239f5d Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 17 Jan 2024 13:00:51 +0100 Subject: [PATCH 166/536] collection_requirements: add meta/execution-environments.yml (#871) * collection_requirements: add requirements.txt and bindep.txt * Change * Fix * Update wrt recent builder docs update --- .../collection_contributors/collection_requirements.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 69339cdf65e..58bbacb0411 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -156,6 +156,7 @@ Your collection repository MUST have a ``README.md`` in the root of the collecti meta/runtime.yml ---------------- + Example: `meta/runtime.yml `_ * The ``meta/runtime.yml`` MUST define the minimum version of Ansible which this collection works with. @@ -165,6 +166,13 @@ Example: `meta/runtime.yml `_ building, they SHOULD be listed in corresponding files under the ``meta`` directory, specified in ``meta/execution-environment.yml``, and `verified `_. + +See the `Collection-level dependencies guide `_ for more information and `collection_template/meta ` directory content as an example. + Modules & Plugins ------------------ From 5dc4643aadff459d1a2465666658cfa8fcce0d16 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 21 Jan 2024 00:10:47 +0000 Subject: [PATCH 167/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index aa4f6d245ca..2c6cbeefe56 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -63,7 +63,7 @@ jinja2==3.1.3 # -r tests/requirements-relaxed.in # antsibull-docs # sphinx -markupsafe==2.1.3 +markupsafe==2.1.4 # via jinja2 multidict==6.0.4 # via @@ -77,7 +77,7 @@ packaging==23.2 # sphinx perky==0.9.2 # via antsibull-core -pydantic==1.10.13 +pydantic==1.10.14 # via # antsibull-core # antsibull-docs diff --git a/tests/requirements.txt b/tests/requirements.txt index c6860dd2ec0..96648d0c559 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -65,7 +65,7 @@ jinja2==3.1.3 # -r tests/requirements-relaxed.in # antsibull-docs # sphinx -markupsafe==2.1.3 +markupsafe==2.1.4 # via jinja2 multidict==6.0.4 # via @@ -79,7 +79,7 @@ packaging==23.2 # sphinx perky==0.9.2 # via antsibull-core -pydantic==1.10.13 +pydantic==1.10.14 # via # antsibull-core # antsibull-docs From 351cb62aac638c32d12a9e945b0c9d0739ce3629 Mon Sep 17 00:00:00 2001 From: Akira Yokochi Date: Wed, 24 Jan 2024 01:33:15 +0900 Subject: [PATCH 168/536] fix internal links for ansible forum (#1052) --- docs/docsite/rst/community/communication.rst | 4 ++-- docs/docsite/rst/installation_guide/intro_installation.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 37204a9e38b..0a47bc5b582 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -215,7 +215,7 @@ The Bullhorn ============ **The Bullhorn** is our newsletter for the Ansible contributor community. You can get Bullhorn updates -from the :ref:`forum` or `subscribe `_ to receive it. +from the :ref:`ansible_forum` or `subscribe `_ to receive it. If you have any questions or content you would like to share, you are welcome to chat with us in the `Ansible Social room on Matrix, and mention @@ -229,7 +229,7 @@ Asking questions over email .. note:: - This form of communication is deprecated. Consider using the :ref:`forum` instead. + This form of communication is deprecated. Consider using the :ref:`ansible_forum` instead. Your first post to the mailing list will be moderated (to reduce spam), so please allow up to a day or so for your first post to appear. diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 0d477ab5764..51e63165e25 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -362,7 +362,7 @@ See the `argcomplete documentation `_. Learning ansible's configuration management language :ref:`installation_faqs` Ansible Installation related to FAQs - :ref:`forum` + :ref:`ansible_forum` Join the Ansible community forum to get help and share insights :ref:`communication_irc` How to join Ansible chat channels From ad312dab02263cfb602d046a223374e4ae01f727 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Tue, 23 Jan 2024 16:56:49 -0600 Subject: [PATCH 169/536] ci: refresh dev dependencies (#1049) --- tests/static.txt | 2 +- tests/typing.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index 4c7916f08d7..dbff3a076e9 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.13 +ruff==0.1.14 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 850b6cd2275..7019369d5ab 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -32,7 +32,7 @@ idna==3.6 # via requests jinja2==3.1.3 # via -r tests/../hacking/pr_labeler/requirements.txt -markupsafe==2.1.3 +markupsafe==2.1.4 # via jinja2 mypy==1.8.0 # via -r tests/typing.in From d6468625fa21dacf76c65bc875a8c835e665a3b6 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 24 Jan 2024 11:18:20 -0600 Subject: [PATCH 170/536] nox: run clone-core session in a venv as well (#1055) Previously, the clone-core session ran in the global environment (`venv_backend="none"`) and instead of provisioning a venv. I did this to save time, as the clone-core session needs no other dependencies besides a python interpreter. This turned out to be shortsighted. It's better to just create an empty venv that we know we can call `python` in as opposed to relying on whatever `python` may or may not be on `$PATH`. Some systems may only have `python3` or have `python` pointing to the wrong thing. Fixes: https://github.com/ansible/ansible-documentation/issues/1054 --- noxfile.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/noxfile.py b/noxfile.py index 850045dbb9a..ecaebb0f0fd 100644 --- a/noxfile.py +++ b/noxfile.py @@ -110,7 +110,7 @@ def pip_compile(session: nox.Session, req: str): # fmt: on -@nox.session(name="clone-core", venv_backend="none") +@nox.session(name="clone-core") def clone_core(session: nox.Session): """ Clone relevant portions of ansible-core from ansible/ansible into the current From 5ebf9f1686650f90caf2e7b775ed3ad2d876ee9f Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 24 Jan 2024 12:44:01 -0600 Subject: [PATCH 171/536] ci: avoid interpolating inputs into run: scripts (#740) Github Actions makes it easy to inject arbitrary shell code into Github Actions scripts thanks to the way its templating language works. This change mediates that issue by passing action inputs to the `run:` scripts as env vars instead of using `${{ }}` expansions directly in the script bodies. The pr_labeler job is the only one that both runs on pull requests and has access to secrets, but we don't interpolate anything other than `github.event.number`, so that wouldn't allow any malicious person to steal credentials. reusable-pip-compile has access to secrets and accepts user input, but only from trusted sources (i.e., developers who already have write access to this repository) and can manually trigger workflows. Still, it's a good to tighten this up. --- .github/workflows/labeler.yml | 10 ++++--- .github/workflows/reusable-pip-compile.yml | 31 ++++++++++++++-------- 2 files changed, 26 insertions(+), 15 deletions(-) diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml index ad509d96b42..7b69e67a9b2 100644 --- a/.github/workflows/labeler.yml +++ b/.github/workflows/labeler.yml @@ -53,12 +53,14 @@ jobs: env: event_json: "${{ toJSON(github.event) }}" GITHUB_TOKEN: ${{ steps.create_token.outputs.token }} - run: - ./venv/bin/python hacking/pr_labeler/label.py issue ${{ github.event.issue.number || inputs.number }} + number: "${{ github.event.issue.number || inputs.number }}" + run: | + ./venv/bin/python hacking/pr_labeler/label.py issue "${number}" - name: "Run the PR labeler" if: "github.event.pull_request || inputs.type == 'pr'" env: event_json: "${{ toJSON(github.event) }}" GITHUB_TOKEN: ${{ steps.create_token.outputs.token }} - run: - ./venv/bin/python hacking/pr_labeler/label.py pr ${{ github.event.number || inputs.number }} + number: "${{ github.event.number || inputs.number }}" + run: | + ./venv/bin/python hacking/pr_labeler/label.py pr "${number}" diff --git a/.github/workflows/reusable-pip-compile.yml b/.github/workflows/reusable-pip-compile.yml index 1d08d2f725f..802be4e7e26 100644 --- a/.github/workflows/reusable-pip-compile.yml +++ b/.github/workflows/reusable-pip-compile.yml @@ -82,43 +82,52 @@ jobs: run: | hacking/get_bot_user.sh "ansible-documentation-bot" "Ansible Documentation Bot" - name: "Use a branch named ${{ inputs.pr-branch }}" + env: + base_branch: "${{ inputs.base-branch }}" + pr_branch: "${{ inputs.pr-branch }}" id: branch run: | set -x - if git branch -r | grep "origin/${{ inputs.pr-branch }}"; then + if git branch -r | grep "origin/${pr_branch}"; then echo "branch-exists=true" >> "${GITHUB_OUTPUT}" - git switch "${{ inputs.pr-branch }}" + git switch "${pr_branch}" ${{ inputs.reset-branch && 'git reset --hard' || 'git rebase' }} \ - "${{ inputs.base-branch }}" + "${base_branch}" else echo "branch-exists=false" >> "${GITHUB_OUTPUT}" - git switch -c "${{ inputs.pr-branch }}" + git switch -c "${pr_branch}" fi - name: "Run nox ${{ inputs.nox-args }}" env: # Ensure the latest pip version is used VIRTUALENV_DOWNLOAD: '1' + # + nox_args: "${{ inputs.nox-args }}" run: | - nox ${{ inputs.nox-args }} + nox ${nox_args} - name: Push new dependency versions and create a PR env: GITHUB_TOKEN: ${{ steps.create_token.outputs.token }} + base_branch: "${{ inputs.base-branch }}" + pr_branch: "${{ inputs.pr-branch }}" + message: "${{ inputs.message }}" + changed_files: "${{ inputs.changed-files }}" run: | set -x git diff || : - git add ${{ inputs.changed-files }} - if git diff-index --quiet HEAD ${{ inputs.changed-files }}; then + git add ${changed_files} + if git diff-index --quiet HEAD ${changed_files}; then echo "Nothing to do!" exit fi - git commit -m "${{ inputs.message }}" - git push --force origin "${{ inputs.pr-branch }}" + git commit -m "${message}" + git push --force origin "${pr_branch}" if [ "${{ steps.branch.outputs.branch-exists }}" = "false" ] then gh pr create \ - --base "${{ inputs.base-branch }}" \ - --title "${{ inputs.message }}" \ + --base "${base_branch}" \ + --title "${message}" \ --body "" \ --label dependency_update fi From f8a4aeab3f8dde9d1dae6ab123992216bb3b57bd Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 24 Jan 2024 19:43:58 +0000 Subject: [PATCH 172/536] ci pip-compile: disable workflow_dispatch for reusable workflow We don't really need this, and it's a bit of a security hole. The individual pip-compile-dev and pip-compile-docs have workflow_dispatch which can be used instead. --- .github/workflows/reusable-pip-compile.yml | 25 ---------------------- 1 file changed, 25 deletions(-) diff --git a/.github/workflows/reusable-pip-compile.yml b/.github/workflows/reusable-pip-compile.yml index 802be4e7e26..f040aa870e3 100644 --- a/.github/workflows/reusable-pip-compile.yml +++ b/.github/workflows/reusable-pip-compile.yml @@ -3,8 +3,6 @@ name: "Refresh pinned dependencies" "on": workflow_call: - # GHA does not support anchors :( - # inputs: &inputs inputs: # Commit messae and PR title message: @@ -31,29 +29,6 @@ name: "Refresh pinned dependencies" reset-branch: type: boolean default: false - workflow_dispatch: - # inputs: *inputs - inputs: - message: - type: string - required: true - pr-branch: - type: string - required: true - base-branch: - type: string - required: true - nox-args: - type: string - required: true - changed-files: - default: "tests/*.txt" - type: string - required: false - reset-branch: - type: boolean - default: false - jobs: refresh: runs-on: ubuntu-latest From c29f39ed221976c86209f8a778d558a723303f01 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 24 Jan 2024 19:48:43 +0000 Subject: [PATCH 173/536] nox pip-compile: don't use env to pass nox args Using env here messes up the quoting for the args passed from the calling workflows. Now that workflow_dispatch is disabled for the reusable workflow, it should be safe to use GHA workflow templating directly. --- .github/workflows/reusable-pip-compile.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/reusable-pip-compile.yml b/.github/workflows/reusable-pip-compile.yml index f040aa870e3..06e9ee92f45 100644 --- a/.github/workflows/reusable-pip-compile.yml +++ b/.github/workflows/reusable-pip-compile.yml @@ -77,9 +77,8 @@ jobs: # Ensure the latest pip version is used VIRTUALENV_DOWNLOAD: '1' # - nox_args: "${{ inputs.nox-args }}" run: | - nox ${nox_args} + nox ${{ inputs.nox-args }} - name: Push new dependency versions and create a PR env: GITHUB_TOKEN: ${{ steps.create_token.outputs.token }} From b68b03edc3d903fba7a8be519d6d0f64f938fa8d Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 24 Jan 2024 19:00:08 +0000 Subject: [PATCH 174/536] ci pip-compile: allow adding extra labels to PRs --- .github/workflows/reusable-pip-compile.yml | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/.github/workflows/reusable-pip-compile.yml b/.github/workflows/reusable-pip-compile.yml index 06e9ee92f45..dc25afe6d59 100644 --- a/.github/workflows/reusable-pip-compile.yml +++ b/.github/workflows/reusable-pip-compile.yml @@ -29,6 +29,9 @@ name: "Refresh pinned dependencies" reset-branch: type: boolean default: false + labels: + type: string + default: "" jobs: refresh: runs-on: ubuntu-latest @@ -86,6 +89,7 @@ jobs: pr_branch: "${{ inputs.pr-branch }}" message: "${{ inputs.message }}" changed_files: "${{ inputs.changed-files }}" + labels: "${{ inputs.labels }}" run: | set -x git diff || : @@ -99,9 +103,18 @@ jobs: git push --force origin "${pr_branch}" if [ "${{ steps.branch.outputs.branch-exists }}" = "false" ] then - gh pr create \ - --base "${base_branch}" \ - --title "${message}" \ - --body "" \ + command=(gh pr create + --base "${base_branch}" + --title "${message}" + --body "" --label dependency_update + ) + # Add custom labels to the command. + old_ifs="$IFS" + IFS="," + for label in ${labels}; do + command+=("--label" "${label}") + done + IFS="${old_ifs}" fi + "${command[@]}" From 42e07a1d071d41fa4b0cdd0f1510cffb62d07b5d Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 25 Jan 2024 14:05:33 -0500 Subject: [PATCH 175/536] Remove 2.10 from build (#1046) --- docs/docsite/Makefile | 25 ++------ docs/docsite/rst/2.10_index.rst | 106 -------------------------------- docs/docsite/rst/conf.py | 52 ++-------------- 3 files changed, 11 insertions(+), 172 deletions(-) delete mode 100644 docs/docsite/rst/2.10_index.rst diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile index 6c496219479..93e8fba044c 100644 --- a/docs/docsite/Makefile +++ b/docs/docsite/Makefile @@ -79,16 +79,9 @@ gettext_generate_rst: collections_meta config cli keywords # from the same set of rst files (Ansible the package docs, and core docs). # Symlink the relevant index into place for building Ansible docs ansible_structure: - # We must have python and python-packaging for the version_helper - # script so use it for version comparison - if $(PYTHON) -c "import sys, packaging.version as p; sys.exit(not p.Version('$(MAJOR_VERSION)') > p.Version('2.10'))" ; then \ - echo "Creating symlinks in ansible_structure"; \ - ln -sf ../rst/ansible_index.rst rst/index.rst; \ - ln -sf ../dev_guide/ansible_index.rst rst/dev_guide/index.rst; \ - else \ - echo 'Creating symlinks for older ansible in ansible_structure'; \ - ln -sf ../rst/2.10_index.rst rst/index.rst; \ - fi + @echo "Creating symlinks in ansible_structure" + ln -sf ../rst/ansible_index.rst rst/index.rst + ln -sf ../dev_guide/ansible_index.rst rst/dev_guide/index.rst # Symlink the relevant index into place for building core docs core_structure: @@ -123,11 +116,7 @@ else endif htmldocs: ansible_structure generate_rst - if $(PYTHON) -c "import sys, packaging.version as p; sys.exit(not p.Version('$(MAJOR_VERSION)') > p.Version('2.10'))" ; then \ - CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx 'DOCS_VARIANTS=-t ansible' html; \ - else \ - CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx 'DOCS_VARIANTS=-t 2.10' html; \ - fi + CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx 'DOCS_VARIANTS=-t ansible' html core_htmldocs: core_structure core_generate_rst ifdef LANGOPTS @@ -137,11 +126,7 @@ else endif singlehtmldocs: ansible_structure generate_rst - if $(PYTHON) -c "import sys, packaging.version as p; sys.exit(not p.Version('$(MAJOR_VERSION)') > p.Version('2.10'))" ; then \ - CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx 'DOCS_VARIANTS=-t ansible' singlehtml; \ - else \ - CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx 'DOCS_VARIANTS=-t 2.10' singlehtml; \ - fi + CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx 'DOCS_VARIANTS=-t ansible' singlehtml core_singlehtmldocs: core_structure core_generate_rst ifdef LANGOPTS diff --git a/docs/docsite/rst/2.10_index.rst b/docs/docsite/rst/2.10_index.rst deleted file mode 100644 index 1ff97d0bae0..00000000000 --- a/docs/docsite/rst/2.10_index.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. _ansible_documentation: - -Ansible Documentation -===================== - -About Ansible -````````````` - -Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks such as continuous deployments or zero downtime rolling updates. - -Ansible's main goals are simplicity and ease-of-use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with other transports and pull modes as alternatives), and a language that is designed around auditability by humans--even those not familiar with the program. - -We believe simplicity is relevant to all sizes of environments, so we design for busy users of all types: developers, sysadmins, release engineers, IT managers, and everyone in between. Ansible is appropriate for managing all environments, from small setups with a handful of instances to enterprise environments with many thousands of instances. - -You can learn more at `AnsibleFest `_, the annual event for all Ansible contributors, users, and customers hosted by Red Hat. AnsibleFest is the place to connect with others, learn new skills, and find a new friend to automate with. - -Ansible manages machines in an agent-less manner. There is never a question of how to upgrade remote daemons or the problem of not being able to manage systems because daemons are uninstalled. Because OpenSSH is one of the most peer-reviewed open source components, security exposure is greatly reduced. Ansible is decentralized--it relies on your existing OS credentials to control access to remote machines. If needed, Ansible can easily connect with Kerberos, LDAP, and other centralized authentication management systems. - -This documentation covers the version of Ansible noted in the upper left corner of this page. We maintain multiple versions of Ansible and of the documentation, so please be sure you are using the version of the documentation that covers the version of Ansible you're using. For recent features, we note the version of Ansible where the feature was added. - -Ansible releases a new major release approximately twice a year. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. Contributors develop and change modules and plugins, hosted in collections since version 2.10, much more quickly. - -.. toctree:: - :maxdepth: 2 - :caption: Installation, Upgrade & Configuration - - installation_guide/index - porting_guides/porting_guides - -.. toctree:: - :maxdepth: 2 - :caption: Using Ansible - - user_guide/index - -.. toctree:: - :maxdepth: 2 - :caption: Contributing to Ansible - - community/index - -.. toctree:: - :maxdepth: 2 - :caption: Extending Ansible - - dev_guide/index - -.. toctree:: - :glob: - :maxdepth: 1 - :caption: Common Ansible Scenarios - - scenario_guides/cloud_guides - scenario_guides/network_guides - scenario_guides/virt_guides - -.. toctree:: - :maxdepth: 2 - :caption: Network Automation - - network/getting_started/index - network/user_guide/index - network/dev_guide/index - -.. toctree:: - :maxdepth: 2 - :caption: Ansible Galaxy - - galaxy/user_guide.rst - galaxy/dev_guide.rst - - -.. toctree:: - :maxdepth: 1 - :caption: Reference & Appendices - - collections/index - collections/all_plugins - reference_appendices/playbooks_keywords - reference_appendices/common_return_values - reference_appendices/config - reference_appendices/general_precedence - reference_appendices/YAMLSyntax - reference_appendices/python_3_support - reference_appendices/interpreter_discovery - reference_appendices/release_and_maintenance - reference_appendices/test_strategies - dev_guide/testing/sanity/index - reference_appendices/faq - reference_appendices/glossary - reference_appendices/module_utils - reference_appendices/special_variables - reference_appendices/tower - reference_appendices/automationhub - reference_appendices/logging - - -.. toctree:: - :maxdepth: 2 - :caption: Release Notes - -.. toctree:: - :maxdepth: 2 - :caption: Roadmaps - - roadmap/index.rst diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 6947dea822b..7f73069dbad 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -32,7 +32,7 @@ # the repository version needs to be the one that is loaded: sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..', 'lib'))) -KNOWN_TAGS = {'all', 'ansible', 'core', 'core_lang', '2.10'} +KNOWN_TAGS = {'all', 'ansible', 'core', 'core_lang'} applied_tags_count = sum( int(tags.has(known_tag_name)) for known_tag_name in KNOWN_TAGS @@ -46,8 +46,7 @@ # Controls branch version for core releases 'devel' if tags.has('core_lang') or tags.has('core') else # Controls branch version for Ansible package releases - 'devel' if tags.has('ansible') or tags.has('all') else - '2.10' if tags.has('2.10') + 'devel' if tags.has('ansible') or tags.has('all') else '' ) AUTHOR = 'Ansible, Inc' @@ -85,7 +84,7 @@ project = ( 'Ansible Core' if ( tags.has('all') or tags.has('core_lang') or tags.has('core') - ) else 'Ansible' if tags.has('2.10') or tags.has('ansible') + ) else 'Ansible' if tags.has('ansible') else '' ) @@ -115,7 +114,6 @@ # A list of glob-style patterns that should be excluded when looking # for source files. exclude_patterns = [] if tags.has('all') else [ - '2.10_index.rst', 'ansible_index.rst', 'core_index.rst', ] @@ -173,15 +171,7 @@ 'roadmap/COLLECTIONS*' ] if tags.has('core_lang') or tags.has('core') else [ 'porting_guides/core_porting_guides', -] if tags.has('ansible') else [ - 'dev_guide/ansible_index.rst', - 'dev_guide/core_index.rst', - 'dev_guide/core_branches_and_tags.rst', - 'porting_guides/core_porting_guides.rst', - 'porting_guides/porting_guide_base_2.10.rst', - 'porting_guides/porting_guide_core_*', - 'roadmap/index.rst', -] if tags.has('2.10') else '' +] if tags.has('ansible') else '' # The reST default role (used for this markup: `text`) to use for all # documents. @@ -249,7 +239,6 @@ 'latest_version': ( 'devel' if tags.has('all') else '2.16' if tags.has('core_lang') or tags.has('core') else - '2.10' if tags.has('2.10') else '9' if tags.has('ansible') else '' ), @@ -258,7 +247,6 @@ ('devel',) if tags.has('all') else ('2.15_ja', '2.14_ja', '2.13_ja',) if tags.has('core_lang') else ('2.16', '2.15', '2.14', 'devel',) if tags.has('core') else - ('latest', '2.9', '2.9_ja', '2.8', 'devel') if tags.has('2.10') else ('latest', '2.9', 'devel') if tags.has('ansible') else '' ), @@ -275,7 +263,7 @@ html_title = ( 'Ansible Core Documentation' if ( tags.has('all') or tags.has('core_lang') or tags.has('core') - ) else 'Ansible Documentation' if tags.has('2.10') or tags.has('ansible') + ) else 'Ansible Documentation' if tags.has('ansible') else '' ) @@ -390,35 +378,7 @@ 'jinja2': ('http://jinja.palletsprojects.com/', None), 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), 'ansible_9': ('https://docs.ansible.com/ansible/9/', None), -} if tags.has('all') else { - 'python': ('https://docs.python.org/2/', None), - 'python3': ('https://docs.python.org/3/', None), - 'jinja2': ('http://jinja.palletsprojects.com/', None), - 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), - 'ansible_9': ('https://docs.ansible.com/ansible/9/', None), -} if tags.has('core_lang') else { - 'python': ('https://docs.python.org/2/', None), - 'python3': ('https://docs.python.org/3/', None), - 'jinja2': ('http://jinja.palletsprojects.com/', None), - 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), - 'ansible_9': ('https://docs.ansible.com/ansible/9/', None), -} if tags.has('core') else { - 'python': ('https://docs.python.org/2/', None), - 'python3': ('https://docs.python.org/3/', None), - 'jinja2': ('http://jinja.palletsprojects.com/', None), - 'ansible_2_10': ('https://docs.ansible.com/ansible/2.10/', None), - 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), - 'ansible_2_8': ('https://docs.ansible.com/ansible/2.8/', None), - 'ansible_2_7': ('https://docs.ansible.com/ansible/2.7/', None), - 'ansible_2_6': ('https://docs.ansible.com/ansible/2.6/', None), - 'ansible_2_5': ('https://docs.ansible.com/ansible/2.5/', None), -} if tags.has('2.10') else { - 'python': ('https://docs.python.org/2/', None), - 'python3': ('https://docs.python.org/3/', None), - 'jinja2': ('http://jinja.palletsprojects.com/', None), - 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), - 'ansible_9': ('https://docs.ansible.com/ansible/9/', None), -} if tags.has('ansible') else {} +} # linckchecker settings linkcheck_ignore = [ From 19a37c214941096ac33e4a6295bad02c4b52aaf1 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 24 Jan 2024 22:39:52 +0000 Subject: [PATCH 176/536] ci pip-compile: add appropriate labels to dev and docs jobs Dev dependency PRs are usually backported to all stable branches and should be marked with the `tooling` label. Doc build dependency PRs are never backported and should be marked with the `doc builds` label. --- .github/workflows/pip-compile-dev.yml | 4 ++++ .github/workflows/pip-compile-docs.yml | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/.github/workflows/pip-compile-dev.yml b/.github/workflows/pip-compile-dev.yml index 93792aa7a3f..9d356635931 100644 --- a/.github/workflows/pip-compile-dev.yml +++ b/.github/workflows/pip-compile-dev.yml @@ -15,6 +15,9 @@ name: "Refresh dev dependencies" reset-branch: type: boolean default: false + labels: + required: false + type: string push: branches: - devel @@ -37,4 +40,5 @@ jobs: 'pip-compile-3.10(static)' 'pip-compile-3.10(spelling)' reset-branch: "${{ inputs.reset-branch || false }}" + labels: "${{ inputs.labels || 'backport-2.14,backport-2.15,backport-2.16,tooling' }}" secrets: inherit diff --git a/.github/workflows/pip-compile-docs.yml b/.github/workflows/pip-compile-docs.yml index c679f8cd79b..6c90c24e10c 100644 --- a/.github/workflows/pip-compile-docs.yml +++ b/.github/workflows/pip-compile-docs.yml @@ -15,6 +15,9 @@ name: "Refresh docs build dependencies" reset-branch: type: boolean default: false + labels: + required: false + type: string push: branches: - devel @@ -33,4 +36,5 @@ jobs: pr-branch: "${{ inputs.pr-branch || 'pip-compile/devel/docs' }}" nox-args: "-e 'pip-compile-3.10(requirements)' 'pip-compile-3.10(requirements-relaxed)'" reset-branch: "${{ inputs.reset-branch || false }}" + labels: "${{ inputs.labels || 'doc builds,no_backport' }}" secrets: inherit From 1c5251d8d5f02c9535331c5c6a12a02899f4b0cf Mon Sep 17 00:00:00 2001 From: Akira Yokochi Date: Sat, 27 Jan 2024 04:42:30 +0900 Subject: [PATCH 177/536] Add network differences explanation (#1051) * add network differences description * Update docs/docsite/rst/network/getting_started/network_differences.rst Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- .../docsite/rst/network/getting_started/network_differences.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docsite/rst/network/getting_started/network_differences.rst b/docs/docsite/rst/network/getting_started/network_differences.rst index ef9e97c3fa0..b7b3f8acaab 100644 --- a/docs/docsite/rst/network/getting_started/network_differences.rst +++ b/docs/docsite/rst/network/getting_started/network_differences.rst @@ -14,6 +14,8 @@ Unlike most Ansible modules, network modules do not run on the managed nodes. Fr Network modules also use the control node as a destination for backup files, for those modules that offer a ``backup`` option. With Linux/Unix modules, where a configuration file already exists on the managed node(s), the backup file gets written by default in the same directory as the new, changed file. Network modules do not update configuration files on the managed nodes, because network configuration is not written in files. Network modules write backup files on the control node, usually in the `backup` directory under the playbook root directory. +When using the connection plugins (for example, ``ansible.netcommon.network_cli``) for network modules, Unix/Linux modules such as ``ansible.builtin.file`` and ``ansible.builtin.copy`` also run on the control node. + Multiple communication protocols ================================================================================ From 8f2054e7e7b4caceb910a8d9842d37f26b2f964d Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 29 Jan 2024 12:01:24 -0600 Subject: [PATCH 178/536] ci: refresh dev dependencies (#1065) --- tests/formatters.txt | 2 +- tests/typing.txt | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index ebaeeb4b99e..7ef94fe6b95 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==23.12.1 +black==24.1.0 # via -r tests/formatters.in click==8.1.7 # via black diff --git a/tests/typing.txt b/tests/typing.txt index 7019369d5ab..e78cc199603 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/typing.txt --strip-extras tests/typing.in # -argcomplete==3.2.1 +argcomplete==3.2.2 # via nox certifi==2023.11.17 # via requests @@ -18,9 +18,9 @@ click==8.1.7 # via typer codeowners==0.6.0 # via -r tests/../hacking/pr_labeler/requirements.txt -colorlog==6.8.0 +colorlog==6.8.2 # via nox -cryptography==41.0.7 +cryptography==42.0.1 # via pyjwt deprecated==1.2.14 # via pygithub From 5782a34f681d85682370931b2f46cd309af91c5b Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 31 Jan 2024 07:19:46 +0100 Subject: [PATCH 179/536] community_steering_committee.rst: update with respect to forum and collection requirements (#997) * community_steering_committee.rst: update with respect to forum and collection requirements * Update docs/docsite/rst/community/steering/community_steering_committee.rst Co-authored-by: Felix Fontein * Simplify links. Co-authored-by: Maxwell G --------- Co-authored-by: Felix Fontein Co-authored-by: Maxwell G --- .../steering/community_steering_committee.rst | 25 ++++++++----------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index 21d229e13d6..7f20c115152 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -1,7 +1,7 @@ .. THIS DOCUMENT IS OWNED BY THE ANSIBLE COMMUNITY STEERING COMMITTEE. ALL CHANGES MUST BE APPROVED BY THE STEERING COMMITTEE! For small changes (fixing typos, language errors, etc.) create a PR and ping @ansible/steering-committee. - For other changes, create a discussion in https://github.com/ansible-community/community-topics/ to discuss the changes. + For other changes, create a `community topic `_ to discuss them. (Creating a draft PR for this file and mentioning it in the community topic is also OK.) .. _steering_responsibilities: @@ -73,9 +73,9 @@ Committee members are selected based on their active contribution to the Ansible Creating new policy proposals & inclusion requests ---------------------------------------------------- -The Committee uses the `community-topics repository `_ to asynchronously discuss with the Community and vote on Community topics in corresponding issues. +The Committee uses the `Ansible Forum `_ to asynchronously discuss with the Community and vote on the proposals in corresponding `community topics `_. -You can create a new issue in the `community-topics repository `_ as a discussion topic if you want to discuss an idea that impacts any of the following: +You can create a `community topic `_ if you want to discuss an idea that impacts any of the following: * Ansible Community * Community collection best practices and requirements @@ -83,12 +83,10 @@ You can create a new issue in the `community-topics repository `_ repository. - -#. Create a corresponding issue containing the rationale behind these changes in the `community-topics repository `_ repository. +#. Submit a new pull request against the document by clicking the ``Edit`` button on its web page. +#. Create a `community topic `_ containing the rationale for the proposed changes. To submit new collections for inclusion into the Ansible package: @@ -103,7 +101,7 @@ Depending on a topic you want to discuss with the Community and the Committee, a Community topics workflow ^^^^^^^^^^^^^^^^^^^^^^^^^ -The Committee uses the `Community-topics workflow `_ to asynchronously discuss and vote on the `community-topics `_. +The Committee uses the `Community-topics workflow `_ to asynchronously discuss and vote on the `community topics `_. The quorum, the minimum number of Committee members who must vote on a topic in order for a decision to be officially made, is half of the whole number of the Committee members. If the quorum number contains a fractional part, it is rounded up to the next whole number. For example, if there are thirteen members currently in the committee, the quorum will be seven. @@ -116,7 +114,7 @@ For votes with more than two options, one choice must have at least half of the Community topics triage ^^^^^^^^^^^^^^^^^^^^^^^ -The Committee conducts a triage of `community topics `_ periodically (every three to six months). +The Committee conducts a triage of `community topics `_ periodically (every three to six months). The triage goals are: @@ -154,7 +152,7 @@ When reviewing community collection `inclusion requests `_ linked to the corresponding inclusion request. The issue's description says that the collection has been approved by two or more Committee members and establishes a date (a week by default) when the inclusion decision will be considered made. This time period can be used to raise concerns. +#. After the collection gets two or more Committee member approvals, a Committee member creates a `community topic `_ linked to the corresponding inclusion request. The issue's description says that the collection has been approved by two or more Committee members and establishes a date (a week by default) when the inclusion decision will be considered made. This time period can be used to raise concerns. #. If no objections are raised up to the established date, the inclusion request is considered successfully resolved. In this case, a Committee member: @@ -167,10 +165,9 @@ When reviewing community collection `inclusion requests `_. Meeting summaries are posted in the `Community Working Group Meeting Agenda `_ issue. +See the Community Working Group meeting `schedule `_. Meeting summaries are posted on the `Forum `_. .. note:: - Participation in the Community Working Group meetings is optional for Committee members. Decisions on community topics are made asynchronously in the `community-topics `_ repository. + Participation in the Community Working Group meetings is optional for Committee members. Decisions on `community topics `_ are made asynchronously in the topics themselves. -The meeting minutes can be found at the `fedora meetbot site `_ and the same is posted to `Ansible Devel Mailing List `_ after every meeting. From 2dc5ef805c74247c8fa1cd2037e8662915f4d5b4 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 31 Jan 2024 08:03:27 +0100 Subject: [PATCH 180/536] Bump antsibull-docs to 2.7.0. (#1090) --- tests/constraints.in | 2 +- tests/requirements-relaxed.in | 2 +- tests/requirements-relaxed.txt | 2 +- tests/requirements.txt | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/constraints.in b/tests/constraints.in index 28ed46552a4..f5214993ae2 100644 --- a/tests/constraints.in +++ b/tests/constraints.in @@ -2,4 +2,4 @@ # and antsibull-docs that production builds rely upon. sphinx == 7.2.5 -antsibull-docs == 2.6.0 # currently approved version +antsibull-docs == 2.7.0 # currently approved version diff --git a/tests/requirements-relaxed.in b/tests/requirements-relaxed.in index a5792f7af9d..dd452b3ae7b 100644 --- a/tests/requirements-relaxed.in +++ b/tests/requirements-relaxed.in @@ -12,5 +12,5 @@ sphinx-intl # translation utility used by docs/docsite/Makefile sphinx-notfound-page sphinx-ansible-theme rstcheck -antsibull-docs ~= 2.6 # 2.6.0 has a fix for EXAMPLES parsing that previously caused docs builds to fail +antsibull-docs ~= 2.7 # 2.7.0 has a fix for new plugin_name field in ansible-doc output sphinx-copybutton diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 2c6cbeefe56..1a25be0b578 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -20,7 +20,7 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-core==2.2.0 # via antsibull-docs -antsibull-docs==2.6.1 +antsibull-docs==2.7.0 # via -r tests/requirements-relaxed.in antsibull-docs-parser==1.0.0 # via antsibull-docs diff --git a/tests/requirements.txt b/tests/requirements.txt index 96648d0c559..32d5de3717c 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -20,7 +20,7 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-core==2.2.0 # via antsibull-docs -antsibull-docs==2.6.0 +antsibull-docs==2.7.0 # via # -c tests/constraints.in # -r tests/requirements-relaxed.in From 926fd6e83b65e8229cf1ef66ffa773188fc26803 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 29 Jan 2024 22:13:04 +0000 Subject: [PATCH 181/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 2 +- tests/requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 1a25be0b578..d8f46c98755 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -6,7 +6,7 @@ # aiofiles==23.2.1 # via antsibull-core -aiohttp==3.9.1 +aiohttp==3.9.3 # via # antsibull-core # antsibull-docs diff --git a/tests/requirements.txt b/tests/requirements.txt index 32d5de3717c..8d6dc735977 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -6,7 +6,7 @@ # aiofiles==23.2.1 # via antsibull-core -aiohttp==3.9.1 +aiohttp==3.9.3 # via # antsibull-core # antsibull-docs From e867348e348256381d20c194451b799aa7bd9c96 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Wed, 31 Jan 2024 07:04:23 +0000 Subject: [PATCH 182/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 2 +- tests/requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index d8f46c98755..4f55411feea 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -161,7 +161,7 @@ typing-extensions==4.9.0 # via # pydantic # rstcheck -urllib3==2.1.0 +urllib3==2.2.0 # via requests yarl==1.9.4 # via aiohttp diff --git a/tests/requirements.txt b/tests/requirements.txt index 8d6dc735977..b9c4802b97f 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -164,7 +164,7 @@ typing-extensions==4.9.0 # via # pydantic # rstcheck -urllib3==2.1.0 +urllib3==2.2.0 # via requests yarl==1.9.4 # via aiohttp From c26618e03e8e05cd6c7d1a9389d38ef5118f07c9 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 31 Jan 2024 01:12:15 -0600 Subject: [PATCH 183/536] Add Ansible community 9.2.0 porting guide (#1087) --- .../rst/porting_guides/porting_guide_9.rst | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 75d5d80142c..9d9f3292e64 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -88,6 +88,79 @@ Networking ========== +Porting Guide for v9.2.0 +======================== + +Added Collections +----------------- + +- community.library_inventory_filtering_v1 (version 1.0.0) + +Known Issues +------------ + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_network_attributes - Issue(279049) - If unsupported values are provided for the parameter ``ome_network_attributes``, then this module does not provide a correct error message. +- ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the following parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. +- ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` +- ome_device_quick_deploy - Issue(275231) - This module does not deploy a new configuration to a slot that has disabled IPv6. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + +Major Changes +------------- + +community.docker +~~~~~~~~~~~~~~~~ + +- The ``community.docker`` collection now depends on the ``community.library_inventory_filtering_v1`` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with ``ansible-galaxy collection install``, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugins (https://github.com/ansible-collections/community.docker/pull/698). + +community.hashi_vault +~~~~~~~~~~~~~~~~~~~~~ + +- requirements - the ``requests`` package which is required by ``hvac`` now has a more restrictive range for this collection in certain use cases due to breaking security changes in ``ansible-core`` that were backported (https://github.com/ansible-collections/community.hashi_vault/pull/416). + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- All OME modules are enhanced to support the environment variables `OME_USERNAME` and `OME_PASSWORD` as fallback for credentials. +- All iDRAC and Redfish modules are enhanced to support the environment variables `IDRAC_USERNAME` and `IDRAC_PASSWORD` as fallback for credentials. +- idrac_certificates - The module is enhanced to support the import and export of `CUSTOMCERTIFICATE`. +- idrac_gather_facts - This role is enhanced to support secure boot. +- idrac_license - The module is introduced to configure iDRAC licenses. + +infoblox.nios_modules +~~~~~~~~~~~~~~~~~~~~~ + +- Upgrade Ansible version support from 2.13 to 2.16. +- Upgrade Python version support from 3.8 to 3.10. + +Deprecated Features +------------------- + +community.dns +~~~~~~~~~~~~~ + +- hetzner_dns_records and hosttech_dns_records inventory plugins - the ``filters`` option has been renamed to ``simple_filters``. The old name will stop working in community.hrobot 2.0.0 (https://github.com/ansible-collections/community.dns/pull/181). + +community.docker +~~~~~~~~~~~~~~~~ + +- docker_container - the default ``ignore`` for the ``image_name_mismatch`` parameter has been deprecated and will switch to ``recreate`` in community.docker 4.0.0. A deprecation warning will be printed in situations where the default value is used and where a behavior would change once the default changes (https://github.com/ansible-collections/community.docker/pull/703). + +community.general +~~~~~~~~~~~~~~~~~ + +- consul_acl - the module has been deprecated and will be removed in community.general 10.0.0. ``consul_token`` and ``consul_policy`` can be used instead (https://github.com/ansible-collections/community.general/pull/7901). + +community.hrobot +~~~~~~~~~~~~~~~~ + +- robot inventory plugin - the ``filters`` option has been renamed to ``simple_filters``. The old name will stop working in community.hrobot 2.0.0 (https://github.com/ansible-collections/community.hrobot/pull/94). + Porting Guide for v9.1.0 ======================== From 20fc39b366762506209c7c2dc38b7ef999fbecc4 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Wed, 31 Jan 2024 18:13:46 +0100 Subject: [PATCH 184/536] Ansible 10 roadmap (#994) * Ansible 10 roadmap * Update docs/docsite/rst/roadmap/COLLECTIONS_10.rst Co-authored-by: Felix Fontein * Update docs/docsite/rst/roadmap/COLLECTIONS_10.rst Co-authored-by: Felix Fontein * Remove unnecessary space * Update link in footnote 3 Co-authored-by: Felix Fontein * Additional alphas * Add note about bug and security fixes --------- Co-authored-by: Felix Fontein --- docs/docsite/rst/roadmap/COLLECTIONS_10.rst | 92 +++++++++++++++++++ .../rst/roadmap/ansible_roadmap_index.rst | 1 + 2 files changed, 93 insertions(+) create mode 100644 docs/docsite/rst/roadmap/COLLECTIONS_10.rst diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_10.rst b/docs/docsite/rst/roadmap/COLLECTIONS_10.rst new file mode 100644 index 00000000000..283b15b9931 --- /dev/null +++ b/docs/docsite/rst/roadmap/COLLECTIONS_10.rst @@ -0,0 +1,92 @@ +.. + THIS DOCUMENT IS OWNED BY THE ANSIBLE COMMUNITY STEERING COMMITTEE. ALL CHANGES MUST BE APPROVED BY THE STEERING COMMITTEE! + For small changes (fixing typos, language errors, etc.) create a PR and ping @ansible/steering-committee. + For other changes, create a discussion as described in https://github.com/ansible-community/community-topics/blob/main/community_topics_workflow.md#creating-a-topic + to discuss the changes. + (Creating a draft PR for this file and mentioning it in the community topic is also OK.) + +.. _ansible_10_roadmap: + +==================== +Ansible project 10.0 +==================== + +This release schedule includes dates for the `ansible `_ package, with a few dates for the `ansible-core `_ package as well. All dates are subject to change. See the `ansible-core 2.17 Roadmap `_ for the most recent updates on ``ansible-core``. + +.. contents:: + :local: + + +Release schedule +================= + + +:2024-04-01: ansible-core feature freeze, stable-2.17 branch created. +:2024-04-08: Start of ansible-core 2.17 betas +:2024-04-09: Ansible-10.0.0 alpha1 [1]_ +:2024-04-29: First ansible-core 2.17 release candidate. +:2024-04-30: Ansible-10.0.0 alpha2 [1]_ +:2024-05-20: Ansible-core-2.17.0 released. +:2024-05-20: Last day for collections to make backwards incompatible releases that will be accepted into Ansible-10. This includes adding new collections to Ansible 10.0.0; from now on new collections have to wait for 10.1.0 or later. +:2024-05-21: Ansible-10.0.0 beta1 -- feature freeze [2]_ (weekly beta releases; collection owners and interested users should test for bugs). +:2024-05-28: Ansible-10.0.0 rc1 [3]_ [4]_ (weekly release candidates as needed; test and alert us to any blocker bugs). Blocker bugs will slip release. +:2024-05-31: Last day to trigger an Ansible-10.0.0rc2 release because of major defects in Ansible-10.0.0rc1. +:2024-06-04: Ansible-10.0.0rc2 when necessary, otherwise Ansible-10.0.0 release. +:2024-06-11: Ansible-10.0.0 release when Ansible-10.0.0rc2 was necessary. +:2024-06-04 or 2023-06-11: Create the ansible-build-data directory and files for Ansible-11. +:2024-06-17: Release of ansible-core 2.17.1. +:2024-06-18: Release of Ansible-10.1.0 (bugfix + compatible features: every four weeks.) + +.. [1] In case there are any additional ansible-core beta releases or release candidates, we will try to do another Ansible-10.0.0 alpha release. This might mean that we will release Ansible-10.0.0 alpha2 earlier (and release Ansible-10.0.0 alpha3 or later on 2024-04-30) and / or release one or more additional alpha after 2024-04-30. + +.. [2] No new modules or major features accepted after this date. In practice, this means we will freeze the semver collection versions to compatible release versions. For example, if the version of community.crypto on this date was community.crypto 2.3.0; Ansible-10.0.0 could ship with community.crypto 2.3.1. It would not ship with community.crypto 2.4.0. + +.. [3] After this date only changes blocking a release are accepted. Accepted changes require creating a new release candidate and may slip the final release date. + +.. [4] Collections will be updated to a new version only if a blocker is approved. Collection owners should discuss any blockers at a community meeting (before this freeze) to decide whether to bump the version of the collection for a fix. See the `creating an Ansible Community Topic workflow `_. + +.. note:: + + Breaking changes will be introduced in Ansible 10.0.0. We encourage the use of deprecation periods that give advance notice of breaking changes at least one Ansible release before they are introduced. However, deprecation notices are not guaranteed to take place. + +.. note:: + + In general, it is in the discretion of the release manager to delay a release by 1-2 days for reasons such as personal (schedule) problems, technical problems (CI/infrastructure breakdown), and so on. + However, in case two releases are planned for the same day, a release of the latest stable version takes precedence. This means that if a stable Ansible 10 release collides with a pre-release of Ansible 11, the latter will be delayed. + If a Ansible 10 release collides with a stable Ansible 11 release, including 11.0.0, the Ansible 10 release will be delayed. + + +Planned major changes +===================== + +- The netapp.aws collection will be removed as it is unmaintained (https://github.com/ansible-community/ansible-build-data/issues/223). +- The gluster.gluster collection will be removed as it is unmaintained (https://github.com/ansible-community/ansible-build-data/issues/249). +- The community.sap collection will be removed as it is deprecated (https://github.com/ansible-community/ansible-build-data/issues/262). +- The netapp.azure collection will be removed as it is unmaintained (https://github.com/ansible-community/ansible-build-data/issues/272). +- The netapp.elementsw collection will be removed as it is unmaintained (https://github.com/ansible-community/ansible-build-data/issues/276). +- The netapp.um_info collection will be removed as it is unmaintained (https://github.com/ansible-community/ansible-build-data/issues/280). +- The community.azure collection will be removed as it is deprecated (https://github.com/ansible-community/ansible-build-data/issues/283). +- The hpe.nimble collection will be removed as it is unmaintained (https://github.com/ansible-community/ansible-build-data/issues/285). + +You can install removed collections manually with ``ansible-galaxy collection install ``. + + +Ansible minor releases +======================= + +Ansible 10.x follows ansible-core-2.17.x releases, so releases will occur approximately every four weeks. If ansible-core delays a release for whatever reason, the next Ansible 10.x minor release will be delayed accordingly. + +Ansible 10.x minor releases may contain new features (including new collections) but not backwards incompatibilities. In practice, this means we will include new collection versions where either the patch or the minor version number has changed but not when the major number has changed. For example, if Ansible-10.0.0 ships with community.crypto 2.3.0, Ansible-10.1.0 could ship with community.crypto 2.4.0 but not community.crypto 3.0.0. + + +.. note:: + + Minor and patch releases will stop when Ansible-11 is released. See the :ref:`Release and Maintenance Page ` for more information. + +.. note:: + + We will not provide bugfixes or security fixes for collections that do not + provide updates for their major release cycle included in Ansible 10. + + +For more information, reach out on a mailing list or a chat channel - see :ref:`communication` for more details. diff --git a/docs/docsite/rst/roadmap/ansible_roadmap_index.rst b/docs/docsite/rst/roadmap/ansible_roadmap_index.rst index 5b3d72e0566..b09d5babd54 100644 --- a/docs/docsite/rst/roadmap/ansible_roadmap_index.rst +++ b/docs/docsite/rst/roadmap/ansible_roadmap_index.rst @@ -24,6 +24,7 @@ See :ref:`Ansible communication channels ` for details on how to :glob: :caption: Ansible Release Roadmaps + COLLECTIONS_10 COLLECTIONS_9 COLLECTIONS_8 COLLECTIONS_7 From 6c1ec485fd48dfbc05f66d0475a8a27b886283a9 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 31 Jan 2024 11:37:24 -0600 Subject: [PATCH 185/536] Extend Ansible 9 lifecycle to November 2024 (#1023) * Extend Ansible 9 lifecycle to November 2024 Relates: https://forum.ansible.com/t/maintain-ansible-9-for-longer-than-6-months/2574 * Update docs/docsite/rst/roadmap/COLLECTIONS_9.rst Co-authored-by: Felix Fontein * Update docs/docsite/rst/roadmap/COLLECTIONS_9.rst Grammar fix Co-authored-by: Sandra McCann * roadmap COLLECTIONS_9: add note about bug and security fixes Co-authored-by: Felix Fontein Co-authored-by: Sandra McCann --------- Co-authored-by: Felix Fontein Co-authored-by: Sandra McCann --- docs/docsite/rst/roadmap/COLLECTIONS_9.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_9.rst b/docs/docsite/rst/roadmap/COLLECTIONS_9.rst index 941e0909b31..5610a72fc8c 100644 --- a/docs/docsite/rst/roadmap/COLLECTIONS_9.rst +++ b/docs/docsite/rst/roadmap/COLLECTIONS_9.rst @@ -74,7 +74,12 @@ Ansible 9.x minor releases may contain new features (including new collections) .. note:: - Minor and patch releases will stop when Ansible-10 is released. See the :ref:`Release and Maintenance Page ` for more information. + Minor and patch releases will stop in November 2024, at the end of the Ansible Core 2.16 critical bugfix support lifecycle. This is roughly half a year longer than regular Ansible releases. See the :ref:`Release and Maintenance Page ` for more information. + +.. note:: + + We will not provide bugfixes or security fixes for collections that do not + provide updates for their major release cycle included in Ansible 9. For more information, reach out on a mailing list or a chat channel - see :ref:`communication` for more details. From 9aed903be131c4bd6249296ad51bd826c2316157 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 31 Jan 2024 18:56:43 +0100 Subject: [PATCH 186/536] Collection requirements: undocumented-parameter must only be used for deprecated parameters or internal parameters (#989) * undocumented-parameter must only be used for deprecated parameters or internal parameters. * Add newline. --- .../collection_contributors/collection_requirements.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 58bbacb0411..dbff3ca57ce 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -413,7 +413,12 @@ CI Testing * ``validate-modules:nonexistent-parameter-documented`` * ``validate-modules:parameter-list-no-elements`` * ``validate-modules:parameter-type-not-in-doc`` - * ``validate-modules:undocumented-parameter`` + + * The following validations MUST not be ignored except in specific circumstances: + * ``validate-modules:undocumented-parameter``: this MUST only be ignored in one of these two cases: + + 1. A dangerous module parameter has been deprecated or removed, and code is present to inform the user that they should not use this specific parameter anymore or that it stopped working intentionally. + 2. Module parameters are only used to pass in data from an accompanying action plugin. * 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. From 0075db676fcf81c3953d186df8b153bc76da4b7f Mon Sep 17 00:00:00 2001 From: Nilashish Chakraborty Date: Fri, 2 Feb 2024 03:59:06 +0530 Subject: [PATCH 187/536] [network] update note about `gather_network_resources` (#1096) * update note about `gather_network_resources` * Update docs/docsite/rst/network/getting_started/first_playbook.rst Co-authored-by: Sandra McCann --------- Co-authored-by: Sandra McCann --- docs/docsite/rst/network/getting_started/first_playbook.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/network/getting_started/first_playbook.rst b/docs/docsite/rst/network/getting_started/first_playbook.rst index 7d4d9d67ea7..5608c0a85dc 100644 --- a/docs/docsite/rst/network/getting_started/first_playbook.rst +++ b/docs/docsite/rst/network/getting_started/first_playbook.rst @@ -207,6 +207,6 @@ The playbook returns the following interface facts: } -Note that this returns a subset of what is returned by just setting ``gather_subset: interfaces``. +Note that ``gather_network_resources`` renders configuration data as facts for all supported resources (interfaces, bgp, ospf, and so on), whereas, ``gather_subset`` is primarily used to fetch operational data. You can store these facts and use them directly in another task, such as with the :ansplugin:`eos_interfaces ` resource module. From 0e6d9c67d8d4930d2e8e602b988593ad1f3dbe4f Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Fri, 2 Feb 2024 12:41:23 -0500 Subject: [PATCH 188/536] remove outdated ansible/community links (#913) --------- Co-authored-by: Felix Fontein Co-authored-by: Andrew Klychkov --- .../collection_release_with_branches.rst | 8 ++--- .../collection_release_without_branches.rst | 2 +- .../collection_requirements.rst | 4 +-- .../collection_development_process.rst | 2 +- .../contributing_maintained_collections.rst | 32 +++++++++---------- .../rst/community/contributor_path.rst | 2 +- .../community/documentation_contributions.rst | 2 +- .../rst/community/maintainers_guidelines.rst | 14 ++++---- .../rst/community/maintainers_workflow.rst | 2 +- .../steering/community_steering_committee.rst | 2 +- .../steering_committee_membership.rst | 2 +- .../developing_modules_in_groups.rst | 4 +-- docs/docsite/rst/dev_guide/testing.rst | 2 +- .../rst/dev_guide/testing_httptester.rst | 3 +- .../rst/dev_guide/testing_integration.rst | 3 +- docs/docsite/rst/roadmap/COLLECTIONS_9.rst | 2 +- .../roadmap/ansible_core_roadmap_index.rst | 1 - 17 files changed, 44 insertions(+), 43 deletions(-) diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst index 44d6e832b2a..0eae079863c 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst @@ -150,7 +150,7 @@ Publishing the collection 4. Add a GitHub release for the new tag. The title should be the version and content, such as - ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. -5. Announce the release through the `Bullhorn Newsletter `_. +5. Announce the release through the `Bullhorn Newsletter `_. 6. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/Libera.Chat IRC channel `_. @@ -205,7 +205,7 @@ Publishing the collection 3. Add a GitHub release for the new tag. The title should be the version and content, such as - ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. -4. Announce the release through the `Bullhorn Newsletter `_. +4. Announce the release through the `Bullhorn Newsletter `_. 5. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel `_. Additionally, you can announce it using GitHub's Releases system. @@ -289,7 +289,7 @@ Releasing when more minor versions are expected This is deliberate, since the next minor release ``X.(Y+1).0`` already contains the changes for ``X.Y.Z`` as well since these were cherry-picked from ``stable-X``. -4. Announce the release through the `Bullhorn Newsletter `_. +4. Announce the release through the `Bullhorn Newsletter `_. 5. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel `. @@ -336,6 +336,6 @@ Releasing when no more minor versions are expected 3. Add a GitHub release for the new tag. Title should be the version and content, such as: ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. -4. Announce the release through the `Bullhorn Newsletter `_. +4. Announce the release through the `Bullhorn Newsletter `_. 5. Announce the release in the pinned issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel `_. diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst index 74ec9fa58f7..8ece8b50be1 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst @@ -110,6 +110,6 @@ Publish the collection 4. Add a GitHub release for the new tag. Title should be the version and content ``See https://github.com/ansible-collections/community.xxx/blob/main/CHANGELOG.rst for all changes``. -5. Announce the release through the `Bullhorn Newsletter issue `_. +5. Announce the release through the `Bullhorn Newsletter issue `_. 6. Announce the release in the pinned release issue/community pinboard of the collection mentioned in step 3 and in the ``community`` :ref:`Matrix/IRC channel `. diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index dbff3ca57ce..581ae8d60fc 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -31,7 +31,7 @@ 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 `_. +* Discussing in the `Community Working Group meeting `_. * Creating `GitHub Issues `_ in the ``ansible-collections`` repository. Keeping informed @@ -40,7 +40,7 @@ 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. +* The `Bullhorn `_ Ansible contributor newsletter. .. _coll_infrastructure_reqs: diff --git a/docs/docsite/rst/community/collection_development_process.rst b/docs/docsite/rst/community/collection_development_process.rst index c2f3279b87d..e718223ec04 100644 --- a/docs/docsite/rst/community/collection_development_process.rst +++ b/docs/docsite/rst/community/collection_development_process.rst @@ -19,7 +19,7 @@ If you want to follow the conversation about what features will be added to the * the :ref:`roadmaps` * the :ref:`Ansible Release Schedule ` -* the `Ansible Community Working Group `_ . +* the `Ansible Community Working Group `_ . Micro development: the lifecycle of a PR ======================================== diff --git a/docs/docsite/rst/community/contributing_maintained_collections.rst b/docs/docsite/rst/community/contributing_maintained_collections.rst index 3df67f6f5e0..71f7862e1cc 100644 --- a/docs/docsite/rst/community/contributing_maintained_collections.rst +++ b/docs/docsite/rst/community/contributing_maintained_collections.rst @@ -66,7 +66,7 @@ The following table shows: amazon.aws community.aws - AWS + AWS ✓** ** ✓ @@ -77,7 +77,7 @@ The following table shows: ansible.netcommon*** community.network - Network + Network ✓ ✓ ✓ @@ -99,7 +99,7 @@ The following table shows: ansible.windows community.windows - Windows + Windows ✓ ✓**** ✓ @@ -110,7 +110,7 @@ The following table shows: arista.eos community.network - Network + Network ✓ ✓ ✓ @@ -121,7 +121,7 @@ The following table shows: cisco.asa community.asa - Security + Security ✓ ✓ ✓ @@ -132,7 +132,7 @@ The following table shows: cisco.ios community.network - Network + Network ✓ ✓ ✓ @@ -143,7 +143,7 @@ The following table shows: cisco.iosxr community.network - Network + Network ✓ ✓ ✓ @@ -154,7 +154,7 @@ The following table shows: cisco.nxos community.network - Network + Network ✓ ✓ ✓ @@ -165,7 +165,7 @@ The following table shows: ibm.qradar community.qradar - Security + Security ✓ ✓ @@ -176,7 +176,7 @@ The following table shows: junipernetworks.junos community.network - Network + Network ✓ ✓ ✓ @@ -187,7 +187,7 @@ The following table shows: kubernetes.core kubernetes.core - Kubernetes + Kubernetes ✓ ✓ ✓ @@ -198,7 +198,7 @@ The following table shows: redhat.openshift community.okd - Kubernetes + Kubernetes ✓ ✓ ✓ @@ -208,7 +208,7 @@ The following table shows: openvswitch.openvswitch community.network - Network + Network ✓ ✓ ✓ @@ -219,7 +219,7 @@ The following table shows: splunk.es community.es - Security + Security ✓ ✓ @@ -230,7 +230,7 @@ The following table shows: vyos.vyos community.network - Network + Network ✓ ✓ ✓ @@ -241,7 +241,7 @@ The following table shows: vmware.vmware_rest vmware.vmware_rest - VMware + VMware ✓ ✓ ✓ diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst index fb59a302f02..d3a57e54311 100644 --- a/docs/docsite/rst/community/contributor_path.rst +++ b/docs/docsite/rst/community/contributor_path.rst @@ -111,4 +111,4 @@ To reach the status, as the current Committee members did before getting it, alo * Subscribe to, comment on, and vote on the `Community Topics `_. * Propose your topics. -* If time permits, join the `Community meetings `_. Note this is **NOT** a requirement. +* If time permits, join the `Community meetings `_. Note this is **NOT** a requirement. diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 1f88377e47e..05657287b68 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -231,7 +231,7 @@ It is recommended to run tests on a clean copy of the repository, which is the p Joining the documentation working group ======================================= -The Documentation Working Group (DaWGs) meets weekly on Tuesdays in the Docs chat (using `Matrix `_ or using IRC at `irc.libera.chat `_). For more information, including links to our agenda and a calendar invite, please visit the `working group page in the community repo `_. +The Documentation Working Group (DaWGs) meets weekly on Tuesdays in the Docs chat (using `Matrix `_ or using IRC at `irc.libera.chat `_). For more information, including links to our agenda and a calendar invite, visit our `forum group `_. .. seealso:: :ref:`More about testing module documentation ` diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst index 03fa5e8e270..c85f8a21b5e 100644 --- a/docs/docsite/rst/community/maintainers_guidelines.rst +++ b/docs/docsite/rst/community/maintainers_guidelines.rst @@ -23,7 +23,7 @@ In general, collection maintainers: - :ref:`Release collections `. - 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 `_. +- Subscribe and submit news to the `Bullhorn newsletter `_. - :ref:`Build a healthy community ` to increase the number of active contributors and maintainers around collections. - Revise these guidelines to improve the maintainer experience for yourself and others. @@ -34,12 +34,12 @@ How to become a maintainer A person interested in becoming a maintainer and satisfying the :ref:`requirements` may either self-nominate or be nominated by another maintainer. -To nominate a candidate, create a GitHub issue in the relevant collection repository. If there is no response, the repository is not actively maintained, or the current maintainers do not have permissions to add the candidate, please create the issue in the `ansible/community `_ repository. +To nominate a candidate, create a GitHub issue in the relevant collection repository. If there is no response, the repository is not actively maintained, or the current maintainers do not have permissions to add the candidate, Create a topic in the `Ansible community forum `_. Communicating as a collection maintainer ----------------------------------------- - Maintainers are highly encouraged to subscribe to the `"Changes impacting collection contributors and maintainers" GitHub repo `_ and the `Bullhorn newsletter `_. If you have something important to announce through the newsletter (for example, recent releases), see the `Bullhorn's wiki page `_ to learn how. + Maintainers are highly encouraged to subscribe to the `"Changes impacting collection contributors and maintainers" GitHub repo `_ and the `Bullhorn newsletter `_. If you have something important to announce through the newsletter (for example, recent releases), see the Bullhorn to learn how. Collection contributors and maintainers can also communicate through: @@ -61,7 +61,7 @@ Project maintainers can use the following techniques to establish communication * Find an existing `forum group `_ or :ref:`working group` that is similar to your project and join the conversation. * `Request `_ a new working group for your project. -* `Create `_ a public chat for your working group or `ask `_ the community team. +* `Create `_ a public chat for your working group or `ask in the forum for help `_. * Provide working group details and links to chat rooms in the contributor section of your project ``README.md``. * Encourage contributors to join the forum group and chat. @@ -79,12 +79,12 @@ Share your opinion and vote on the topics to help the community make the best de Contributor Summits ------------------- -The quarterly Ansible Contributor Summit is a global event that provides our contributors a great opportunity to meet each other, communicate, share ideas, and see that there are other real people behind the messages on Matrix or Libera Chat IRC, or GitHub. This gives a sense of community. Watch the `Bullhorn newsletter `_ for information when the next contributor summit, invite contributors you know, and take part in the event together. +The quarterly Ansible Contributor Summit is a global event that provides our contributors a great opportunity to meet each other, communicate, share ideas, and see that there are other real people behind the messages on Matrix or Libera Chat IRC, or GitHub. This gives a sense of community. Watch the `Bullhorn newsletter `_ for information when the next contributor summit, invite contributors you know, and take part in the event together. Weekly community Matrix/IRC meetings ------------------------------------ -The Community and the Steering Committee come together at weekly meetings in the ``#ansible-community`` `Libera.Chat IRC `_ channel or in the bridged `#community:ansible.com `_ room on `Matrix `_ to discuss important project questions. Join us! Here is our `schedule `_. +The Community and the Steering Committee come together at weekly meetings in the ``#ansible-community`` `Libera.Chat IRC `_ channel or in the bridged `#community:ansible.com `_ room on `Matrix `_ to discuss important project questions. Join us! Here is our `schedule `_. Expanding the collection community =================================== @@ -125,7 +125,7 @@ Conduct pull request days regularly. You could plan PR days, for example, on the Promote active contributors satisfying :ref:`requirements` to maintainers. Revise contributors' activity regularly. -If your collection found new maintainers, announce that fact in the `Bullhorn newsletter `_ and during the next Contributor Summit congratulating and thanking them for the work done. You can mention all the people promoted since the previous summit. Remember to invite the other maintainers to the Summit in advance. +If your collection found new maintainers, announce that fact in the `Bullhorn newsletter `_ and during the next Contributor Summit congratulating and thanking them for the work done. You can mention all the people promoted since the previous summit. Remember to invite the other maintainers to the Summit in advance. Some other general guidelines to encourage contributors: diff --git a/docs/docsite/rst/community/maintainers_workflow.rst b/docs/docsite/rst/community/maintainers_workflow.rst index e14ce5c025d..09675502e43 100644 --- a/docs/docsite/rst/community/maintainers_workflow.rst +++ b/docs/docsite/rst/community/maintainers_workflow.rst @@ -89,7 +89,7 @@ If you feel you don't have time to maintain your collection anymore, you should: - If the collection is under the ``ansible-collections`` organization, also inform relevant :ref:`communication_irc`, the ``community`` chat channels on IRC or matrix, or by email ``ansible-community@redhat.com``. - Look at active contributors in the collection to find new maintainers among them. Discuss the potential candidates with other maintainers or with the community team. - If you failed to find a replacement, create a pinned issue in the collection, announcing that the collection needs new maintainers. -- Make the same announcement through the `Bullhorn newsletter `_. +- Make the same announcement through the `Bullhorn newsletter `_. - Please be around to discuss potential candidates found by other maintainers or by the community team. Remember, this is a community, so you can come back at any time in the future. diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index 7f20c115152..07235c16892 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -159,7 +159,7 @@ When reviewing community collection `inclusion requests `_. - #. Announces the inclusion through the `Bullhorn newsletter `_. + #. Announces the inclusion through the `Bullhorn newsletter `_. #. Closes the topic. Community Working Group meetings diff --git a/docs/docsite/rst/community/steering/steering_committee_membership.rst b/docs/docsite/rst/community/steering/steering_committee_membership.rst index 16922636a53..a665ff5ff84 100644 --- a/docs/docsite/rst/community/steering/steering_committee_membership.rst +++ b/docs/docsite/rst/community/steering/steering_committee_membership.rst @@ -50,7 +50,7 @@ The process to join the Steering Committee consists of the following steps: #. Any community member may nominate someone or themselves for Committee membership by contacting one of the :ref:`current Committee members `) or by sending an email to ``ansible-community@redhat.com``. #. A Committee member who receives the nomination must inform the Committee about it by forwarding the full message. #. The vote is conducted by email. Nominees must receive a majority of votes from the present Committee members to be added to the Committee. -#. Provided that the vote result is positive, it is announced in the `Bullhorn `_ newsletter and the new member is added to the :ref:`Committee member list `. +#. Provided that the vote result is positive, it is announced in the `Bullhorn `_ newsletter and the new member is added to the :ref:`Committee member list `. Leaving the Steering Committee ------------------------------- diff --git a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst index fc0fecceaf7..0091159cf6c 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst @@ -21,7 +21,7 @@ This list of prerequisites is designed to help ensure that you develop high-qual * We encourage supporting :ref:`Python 2.6+ and Python 3.5+ `. * Look at Ansible Galaxy and review the naming conventions in your functional area (such as cloud, networking, databases). * With great power comes great responsibility: Ansible collection maintainers have a duty to help keep content up to date and release collections they are responsible for regularly. As with all successful community projects, collection maintainers should keep a watchful eye for reported issues and contributions. -* We strongly recommend unit and/or integration tests. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :ref:`developing_testing` and the `Testing Working Group `_. +* We strongly recommend unit and/or integration tests. Unit tests are especially valuable when external resources (such as cloud or network devices) are required. For more information see :ref:`developing_testing`. Naming conventions @@ -56,7 +56,7 @@ In the :ref:`ansible_community_guide` you can find how to: * Subscribe to the Mailing Lists - We suggest "Ansible Development List" and "Ansible Announce list" * ``#ansible-devel`` - We have found that communicating on the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) works best for developers so we can have an interactive dialog. -* Working group and other chat channel meetings - Join the various weekly meetings `meeting schedule and agenda page `_ +* Working group and other chat channel meetings - Join the various weekly meetings `meeting schedule page `_ Required files ============== diff --git a/docs/docsite/rst/dev_guide/testing.rst b/docs/docsite/rst/dev_guide/testing.rst index 86ec4c2ccf0..e7d33db9552 100644 --- a/docs/docsite/rst/dev_guide/testing.rst +++ b/docs/docsite/rst/dev_guide/testing.rst @@ -242,4 +242,4 @@ Want to know more about testing? ================================ If you'd like to know more about the plans for improving testing Ansible then why not join the -`Testing Working Group `_. +`Ansible community forum `_. diff --git a/docs/docsite/rst/dev_guide/testing_httptester.rst b/docs/docsite/rst/dev_guide/testing_httptester.rst index 7c1a9fbbaf7..c9d364cf853 100644 --- a/docs/docsite/rst/dev_guide/testing_httptester.rst +++ b/docs/docsite/rst/dev_guide/testing_httptester.rst @@ -25,4 +25,5 @@ Source files can be found in the `http-test-container `_ to avoid duplicated effort. +If you have sometime to improve ``httptester``, open an issue in the +`http-test-container `_ repository. \ No newline at end of file diff --git a/docs/docsite/rst/dev_guide/testing_integration.rst b/docs/docsite/rst/dev_guide/testing_integration.rst index 7b244d79f5e..3667e8a39b3 100644 --- a/docs/docsite/rst/dev_guide/testing_integration.rst +++ b/docs/docsite/rst/dev_guide/testing_integration.rst @@ -244,4 +244,5 @@ For guidance on writing network test see :ref:`testing_resource_modules`. Where to find out more ====================== -If you'd like to know more about the plans for improving testing Ansible, join the `Testing Working Group `_. +If you'd like to know more about the plans for improving testing Ansible, join the +`Ansible community forum `_ \ No newline at end of file diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_9.rst b/docs/docsite/rst/roadmap/COLLECTIONS_9.rst index 5610a72fc8c..0f3b841fce9 100644 --- a/docs/docsite/rst/roadmap/COLLECTIONS_9.rst +++ b/docs/docsite/rst/roadmap/COLLECTIONS_9.rst @@ -40,7 +40,7 @@ Release schedule .. [2] After this date only changes blocking a release are accepted. Accepted changes require creating a new release candidate and may slip the final release date. -.. [3] Collections will be updated to a new version only if a blocker is approved. Collection owners should discuss any blockers at a community IRC meeting (before this freeze) to decide whether to bump the version of the collection for a fix. See the `Community IRC meeting agenda `_. +.. [3] Collections will be updated to a new version only if a blocker is approved. Collection owners should discuss any blockers with a ``community-wg`` tagged forum topic (before this freeze) to decide whether to bump the version of the collection for a fix. See the `Creating a Community working group topic `_ for details. .. note:: diff --git a/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst b/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst index ee28d8bbd2b..d5a9af200d9 100644 --- a/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst +++ b/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst @@ -14,7 +14,6 @@ Each roadmap is published both as an idea of what is upcoming in ``ansible-core` You can submit feedback on the current roadmap in multiple ways: -- Edit the agenda of an `Core Team Meeting `_ (preferred) - Post on the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) - Email the ansible-devel list From 048e4d468a8391103bbacf5a8028e307d32dbe29 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Fri, 2 Feb 2024 12:43:22 -0600 Subject: [PATCH 189/536] Add documentation for module option context (#1057) * Add documentation for module option context * suggestion Co-authored-by: Don Naro * Expand docs to indicate context is not used by core --------- Co-authored-by: Don Naro --- .../developing_program_flow_modules.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst index 35c01ed8498..9e4cca27124 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -766,6 +766,23 @@ This section will discuss the behavioral attributes for arguments: If ``options`` is specified, ``required_by`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`. +:context: + + .. versionadded:: 2.17 + + You can set the value of the ``context`` key to a dict of custom content. This allows you to provide additional context in the argument spec. The content provided is not validated or utilized by the core engine. + + Example: + + .. code-block:: python + + option = { + 'type': 'str', + 'context': { + 'disposition': '/properties/apiType', + }, + 'choices': ['http', 'soap'], + } .. _argument_spec_dependencies: From 209fd01a5e9425b63e867e4ae8d8c89d5dcaed9c Mon Sep 17 00:00:00 2001 From: Akira Yokochi Date: Sat, 3 Feb 2024 03:45:03 +0900 Subject: [PATCH 190/536] Fix doc prompts (#1074) * add $ prompt * add space --- docs/docsite/rst/network/getting_started/first_inventory.rst | 2 +- .../rst/network/user_guide/network_debug_troubleshooting.rst | 4 ++-- docs/docsite/rst/network/user_guide/validate.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/network/getting_started/first_inventory.rst b/docs/docsite/rst/network/getting_started/first_inventory.rst index 5df08538aa2..48da95b7d6d 100644 --- a/docs/docsite/rst/network/getting_started/first_inventory.rst +++ b/docs/docsite/rst/network/getting_started/first_inventory.rst @@ -412,7 +412,7 @@ To see the original value, you can use the debug module. Please note if your YAM .. code-block:: console - cat vyos.yml | grep -v ansible_connection >> vyos_no_connection.yml + $ cat vyos.yml | grep -v ansible_connection >> vyos_no_connection.yml ansible localhost -m debug -a var="ansible_password" -e "@vyos_no_connection.yml" --ask-vault-pass Vault password: diff --git a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst index 77c5dd66324..30668dff309 100644 --- a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst +++ b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst @@ -578,7 +578,7 @@ Example: Handle single login menu prompts with host variables .. code-block:: console - $cat host_vars/.yaml + $ cat host_vars/.yaml --- ansible_terminal_initial_prompt: - "Connect to a host" @@ -589,7 +589,7 @@ Example: Handle remote host multiple login menu prompts with host variables .. code-block:: console - $cat host_vars/.yaml + $ cat host_vars/.yaml --- ansible_terminal_initial_prompt: - "Press any key to enter main menu" diff --git a/docs/docsite/rst/network/user_guide/validate.rst b/docs/docsite/rst/network/user_guide/validate.rst index 37f79c6ab49..5837a2b85f6 100644 --- a/docs/docsite/rst/network/user_guide/validate.rst +++ b/docs/docsite/rst/network/user_guide/validate.rst @@ -91,7 +91,7 @@ The criteria for ``jsonschema`` in this example is as follows: .. code-block:: text - $cat criteria/nxos_show_interface_admin_criteria.json + $ cat criteria/nxos_show_interface_admin_criteria.json { "type" : "object", "patternProperties": { From f557b292ed2562457de852dfb5b58abc1c3f3b94 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Tue, 6 Feb 2024 10:00:04 -0500 Subject: [PATCH 191/536] Alternatives is plural --- docs/docsite/rst/dev_guide/module_lifecycle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/module_lifecycle.rst b/docs/docsite/rst/dev_guide/module_lifecycle.rst index fe19f82da1e..c3883eafc88 100644 --- a/docs/docsite/rst/dev_guide/module_lifecycle.rst +++ b/docs/docsite/rst/dev_guide/module_lifecycle.rst @@ -32,7 +32,7 @@ To deprecate a module in ansible-core, you must: :removed_in: A ``string``, such as ``"2.10"``; the version of Ansible where the module will be replaced with a docs-only module stub. Usually current release +4. Mutually exclusive with :removed_by_date:. :remove_by_date: (Added in ansible-base 2.10). An ISO 8601 formatted date when the module will be removed. Usually 2 years from the date the module is deprecated. Mutually exclusive with :removed_in:. :why: Optional string that used to detail why this has been removed. - :alternative: Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``. + :alternatives: Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``. * For an example of documenting deprecation, see this `PR that deprecates multiple modules `_. Some of the elements in the PR might now be out of date. From 8a6badcb23127749ed8c6d588e660ab3d5c892b7 Mon Sep 17 00:00:00 2001 From: Akira Yokochi Date: Thu, 8 Feb 2024 21:29:23 +0900 Subject: [PATCH 192/536] comment out ellipsis --- docs/docsite/rst/inventory_guide/intro_inventory.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index fb6d007c326..aeb2428830d 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -185,7 +185,7 @@ In YAML: .. code-block:: yaml - ... + # ... webservers: hosts: www[01:50].example.com: @@ -203,7 +203,7 @@ In YAML: .. code-block:: yaml - ... + # ... webservers: hosts: www[01:50:2].example.com: @@ -349,7 +349,7 @@ In YAML: .. code-block:: yaml - ... + # ... hosts: jumper: ansible_port: 5555 From 2118a47b0b8e618c66c6706509fe0717347b93a5 Mon Sep 17 00:00:00 2001 From: akira6592 Date: Thu, 8 Feb 2024 21:43:27 +0900 Subject: [PATCH 193/536] adjust intents --- docs/docsite/rst/inventory_guide/intro_inventory.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index aeb2428830d..996b43817de 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -185,7 +185,7 @@ In YAML: .. code-block:: yaml - # ... + # ... webservers: hosts: www[01:50].example.com: @@ -203,7 +203,7 @@ In YAML: .. code-block:: yaml - # ... + # ... webservers: hosts: www[01:50:2].example.com: @@ -349,7 +349,7 @@ In YAML: .. code-block:: yaml - # ... + # ... hosts: jumper: ansible_port: 5555 From 90c08ab19ad50bcd760f4542a582a0deae1f9039 Mon Sep 17 00:00:00 2001 From: Dan Church Date: Thu, 8 Feb 2024 10:22:19 -0600 Subject: [PATCH 194/536] Fix syntax error in error condition Seen when running `make -f Makefile.sphinx CPUS=1 PYTHON=python3 man`. Python v3.9.18 --- docs/docsite/rst/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 7f73069dbad..93d8c36255b 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -38,8 +38,8 @@ int(tags.has(known_tag_name)) for known_tag_name in KNOWN_TAGS ) assert applied_tags_count == 1, ( - 'Exactly one of the following tags expected: {", ".join(tags)}'. - format(tags=KNOWN_TAGS) + 'Exactly one of the following tags expected: {tags}'. + format(tags=", ".join(KNOWN_TAGS)) ) VERSION = ( From 4daebffd00bb83d2ea842bde3f29a3c9d2a0bbcb Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 11 Feb 2024 01:09:33 -0600 Subject: [PATCH 195/536] ci: refresh dev dependencies (#1091) --- tests/formatters.txt | 4 ++-- tests/static.txt | 2 +- tests/typing.txt | 16 ++++++---------- 3 files changed, 9 insertions(+), 13 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 7ef94fe6b95..0b862c1d150 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==24.1.0 +black==24.1.1 # via -r tests/formatters.in click==8.1.7 # via black @@ -16,7 +16,7 @@ packaging==23.2 # via black pathspec==0.12.1 # via black -platformdirs==4.1.0 +platformdirs==4.2.0 # via black tomli==2.0.1 # via black diff --git a/tests/static.txt b/tests/static.txt index dbff3a076e9..30235d52149 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.1.14 +ruff==0.2.1 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index e78cc199603..e3e57389140 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -6,7 +6,7 @@ # argcomplete==3.2.2 # via nox -certifi==2023.11.17 +certifi==2024.2.2 # via requests cffi==1.16.0 # via @@ -20,7 +20,7 @@ codeowners==0.6.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 # via nox -cryptography==42.0.1 +cryptography==42.0.2 # via pyjwt deprecated==1.2.14 # via pygithub @@ -32,7 +32,7 @@ idna==3.6 # via requests jinja2==3.1.3 # via -r tests/../hacking/pr_labeler/requirements.txt -markupsafe==2.1.4 +markupsafe==2.1.5 # via jinja2 mypy==1.8.0 # via -r tests/typing.in @@ -42,11 +42,11 @@ nox==2023.4.22 # via -r tests/typing.in packaging==23.2 # via nox -platformdirs==4.1.0 +platformdirs==4.2.0 # via virtualenv pycparser==2.21 # via cffi -pygithub==2.1.1 +pygithub==2.2.0 # via -r tests/../hacking/pr_labeler/requirements.txt pyjwt==2.8.0 # via @@ -54,12 +54,8 @@ pyjwt==2.8.0 # pyjwt pynacl==1.5.0 # via pygithub -python-dateutil==2.8.2 - # via pygithub requests==2.31.0 # via pygithub -six==1.16.0 - # via python-dateutil tomli==2.0.1 # via mypy typer==0.9.0 @@ -70,7 +66,7 @@ typing-extensions==4.9.0 # mypy # pygithub # typer -urllib3==2.1.0 +urllib3==2.2.0 # via # pygithub # requests From 793edf7e0aca63c2b1c14985d84a1c9eab85d241 Mon Sep 17 00:00:00 2001 From: Tom Kivlin Date: Mon, 12 Feb 2024 00:26:55 +0000 Subject: [PATCH 196/536] add note explaining injected task has always tag Signed-off-by: Tom Kivlin --- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 316d164c729..252881a48d0 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -269,6 +269,11 @@ validation, the role will fail execution. then validation on those dependencies will run before the dependent role, even if argument validation fails for the dependent role. +.. note:: + + The inserted role argument validation task is tagged with the :ref:`always ` tag, + so if the role is :ref:`statically imported ` then this task will run unless ``--skip-tags`` is used. + Specification format -------------------- From d38599e35f0de4e345990eef67a22d28b02ccabd Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Mon, 12 Feb 2024 12:38:17 +0000 Subject: [PATCH 197/536] Updated following PR review Co-authored-by: Don Naro --- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 252881a48d0..dbabdde499b 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -271,8 +271,8 @@ validation, the role will fail execution. .. note:: - The inserted role argument validation task is tagged with the :ref:`always ` tag, - so if the role is :ref:`statically imported ` then this task will run unless ``--skip-tags`` is used. + Ansible tags the inserted role argument validation task with :ref:`always `. + If the role is :ref:`statically imported ` this task runs unless you use the ``--skip-tags`` flag. Specification format -------------------- From aa552a0cb4200ed57d715733fb38089e47054dd8 Mon Sep 17 00:00:00 2001 From: akira6592 Date: Tue, 13 Feb 2024 21:05:42 +0900 Subject: [PATCH 198/536] add note for ellipsis --- docs/docsite/rst/inventory_guide/intro_inventory.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index 996b43817de..a7e5156c94a 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -20,6 +20,8 @@ Ansible :ref:`inventory_plugins` supports a range of formats and sources to make .. contents:: :local: +.. note:: The following YAML snippets include an ellipsis to indicate they are part of a larger YAML file. You can find out more about YAML syntax at `YAML Basics `_. + .. _inventoryformat: Inventory basics: formats, hosts, and groups From 8288cbe5fa880a391c2d2dc514f2a432518f306c Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 13 Feb 2024 19:03:05 +0100 Subject: [PATCH 199/536] Update Ansible 9 porting guide. (#1124) --- docs/docsite/rst/porting_guides/porting_guide_9.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 9d9f3292e64..cc544d74e02 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -8,15 +8,12 @@ Ansible 9 Porting Guide ======================= .. contents:: - :local: :depth: 2 Ansible 9 is based on Ansible-core 2.16. - -We suggest you read this page along with the `Ansible 9 Changelog `_ to understand what updates you may need to make. - +We suggest you read this page along with the `Ansible 9 Changelog `_ to understand what updates you may need to make. Playbook ======== @@ -87,7 +84,6 @@ Porting custom scripts Networking ========== - Porting Guide for v9.2.0 ======================== From be66e621614c40de6759095a1a9bb8b37a14fcf1 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 15 Feb 2024 13:14:44 +0100 Subject: [PATCH 200/536] Improve role argspec documentation (#1126) * Extend description for 'author'. * Improve option keyword descriptions. --- .../docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 316d164c729..d33a52e9c78 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -303,7 +303,8 @@ role ``meta/argument_specs.yml`` file. All fields are lowercase. :author: * Name of the entry point authors. - * Use a multi-line list if there is more than one author. + * This can be a single string or a list of strings. Use one list entry per author. + If there is only a single author, use a string or a one-element list. :options: @@ -317,6 +318,8 @@ role ``meta/argument_specs.yml`` file. All fields are lowercase. :description: * Detailed explanation of what this option does. It should be written in full sentences. + * This can be a single string or a list of strings. In case this is a list of strings, every list + element is a new paragraph. :version_added: @@ -336,11 +339,11 @@ role ``meta/argument_specs.yml`` file. All fields are lowercase. :default: - * If ``required`` is false/missing, ``default`` may be specified (assumed 'null' if missing). + * If ``required`` is ``false``/missing, ``default`` may be specified (assumed ``null`` if missing). * Ensure that the default value in the docs matches the default value in the code. The actual default for the role variable will always come from ``defaults/main.yml``. * The default field must not be listed as part of the description unless it requires additional information or conditions. - * If the option is a boolean value, you should use `true/false` if you want to be compatible with `ansible-lint`. + * If the option is a boolean value, you should use ``true``/``false`` if you want to be compatible with ``ansible-lint``. :choices: From 5e29d9aa147e27a729f5579b06dbcbcf76461591 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sat, 17 Feb 2024 21:05:37 -0500 Subject: [PATCH 201/536] ci: refresh dev dependencies (#1131) --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 6 ++---- 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 0b862c1d150..f15f6a601c4 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==24.1.1 +black==24.2.0 # via -r tests/formatters.in click==8.1.7 # via black diff --git a/tests/static.txt b/tests/static.txt index 30235d52149..628384eed9c 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.2.1 +ruff==0.2.2 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index e3e57389140..723fafd36a3 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -20,7 +20,7 @@ codeowners==0.6.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 # via nox -cryptography==42.0.2 +cryptography==42.0.3 # via pyjwt deprecated==1.2.14 # via pygithub @@ -49,9 +49,7 @@ pycparser==2.21 pygithub==2.2.0 # via -r tests/../hacking/pr_labeler/requirements.txt pyjwt==2.8.0 - # via - # pygithub - # pyjwt + # via pygithub pynacl==1.5.0 # via pygithub requests==2.31.0 From 7547d43415743aa25e083947e01490f14a5c9d6e Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 18 Feb 2024 13:47:50 -0500 Subject: [PATCH 202/536] ci: refresh docs build dependencies (#1110) --- tests/requirements-relaxed.txt | 8 ++++---- tests/requirements.txt | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 4f55411feea..2f48fc4f920 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -36,7 +36,7 @@ babel==2.14.0 # sphinx-intl build==1.0.3 # via antsibull-core -certifi==2023.11.17 +certifi==2024.2.2 # via requests charset-normalizer==3.3.2 # via requests @@ -63,9 +63,9 @@ jinja2==3.1.3 # -r tests/requirements-relaxed.in # antsibull-docs # sphinx -markupsafe==2.1.4 +markupsafe==2.1.5 # via jinja2 -multidict==6.0.4 +multidict==6.0.5 # via # aiohttp # yarl @@ -167,5 +167,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==69.0.3 +setuptools==69.1.0 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index b9c4802b97f..4c6a60a86f4 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -38,7 +38,7 @@ babel==2.14.0 # sphinx-intl build==1.0.3 # via antsibull-core -certifi==2023.11.17 +certifi==2024.2.2 # via requests charset-normalizer==3.3.2 # via requests @@ -65,9 +65,9 @@ jinja2==3.1.3 # -r tests/requirements-relaxed.in # antsibull-docs # sphinx -markupsafe==2.1.4 +markupsafe==2.1.5 # via jinja2 -multidict==6.0.4 +multidict==6.0.5 # via # aiohttp # yarl @@ -170,5 +170,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==69.0.3 +setuptools==69.1.0 # via sphinx-intl From 1d8e851c0fa0e44f66085ce679def62e74313add Mon Sep 17 00:00:00 2001 From: Sutapa Bhattacharjee <129940487+BhattacharjeeSutapa@users.noreply.github.com> Date: Mon, 19 Feb 2024 22:16:30 +0530 Subject: [PATCH 203/536] Add example around ansible-galaxy command (#1053) Co-authored-by: Don Naro --- docs/docsite/rst/command_guide/cheatsheet.rst | 43 ++++++++++++++++--- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 9f4f3c395f2..56eef5802e9 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -35,20 +35,49 @@ See :ref:`ansible-playbook` for detailed documentation. ansible-galaxy ============== -Installing a collection: +Installing collections +^^^^^^^^^^^^^^^^^^^^^^ + +* Install a single collection: .. code-block:: bash - ansible-galaxy collection install mynamespace.mycollection + ansible-galaxy collection install mynamespace.mycollection -Downloads ``mynamespace.mycollection`` from the configured Galaxy server (``_ by default). - +Downloads ``mynamespace.mycollection`` from the configured Galaxy server (`galaxy.ansible.com` by default). -Listing all installed collections: +* Install a list of collections: .. code-block:: bash - ansible-galaxy collection list + ansible-galaxy collection install -r requirements.yml -See :ref:`ansible-galaxy` for detailed documentation. +Downloads the list of collections specified in the ``requirements.yml`` file. + +* List all installed collections: + +.. code-block:: bash + + ansible-galaxy collection list + +Installing roles +^^^^^^^^^^^^^^^^ + +* Install a role named `example.role`: + +.. code-block:: bash + + ansible-galaxy role install example.role + + # SNIPPED_OUTPUT + - extracting example.role to /home/user/.ansible/roles/example.role + - example.role was installed successfully + + +* List all installed roles: +.. code-block:: bash + + ansible-galaxy role list + +See :ref:`ansible-galaxy` for detailed documentation. From ab2d9e3d0f5b87d569bbadf420b1f73cc54dd1da Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Mon, 19 Feb 2024 12:50:54 -0600 Subject: [PATCH 204/536] Fix core deprecation cycle example to match reality (#1113) --- .../rst/reference_appendices/release_and_maintenance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 7530cae20cc..8d2434d55cf 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -408,7 +408,7 @@ Since Ansible is a package of individual collections, the deprecation cycle depe ansible-core deprecation cycle ------------------------------- -The deprecation cycle in ``ansible-core`` is normally across 4 feature releases (2.x. where the x marks a feature release). The feature is normally removed in the 4th release after we announce the deprecation. For example, something deprecated in 2.10 will be removed in 2.14. The tracking is tied to the number of releases, not the release numbering itself. +The deprecation cycle in ``ansible-core`` is normally across 4 feature releases (2.x. where the x marks a feature release). The feature is normally removed in the 4th release after we announce the deprecation. For example, something deprecated in 2.10 will be removed in 2.13. The tracking is tied to the number of releases, not the release numbering itself. Although this is the standard, there are times where a deprecation cycle for a feature or behavior may have a longer or shorter deprecation cycle based on use or urgency of removal. .. seealso:: From a4cb511c64f141016f6f217740d37a98894aa576 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 20 Feb 2024 13:46:12 +0100 Subject: [PATCH 205/536] Remove/update incorrect docs building documentation (#1128) * MODULES= and PLUGINS= haven't worked since ansible-base 2.10. * MODULES= no longer exists. * Fix dash. * Remove no longer correct parts. * Mention --docker option. --- docs/docsite/Makefile | 18 ++------------ .../community/documentation_contributions.rst | 16 +++++-------- .../rst/dev_guide/testing_documentation.rst | 24 +++++++------------ 3 files changed, 16 insertions(+), 42 deletions(-) diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile index 93e8fba044c..afcfe4bab7f 100644 --- a/docs/docsite/Makefile +++ b/docs/docsite/Makefile @@ -22,20 +22,6 @@ ifndef POTDIR POTDIR = $(BUILDDIR)/gettext endif -# Backwards compat for separate VARS -PLUGIN_ARGS= -ifdef MODULES -ifndef PLUGINS - PLUGIN_ARGS = -l $(MODULES) -else - PLUGIN_ARGS = -l $(MODULES),$(PLUGINS) -endif -else -ifdef PLUGINS - PLUGIN_ARGS = -l $(PLUGINS) -endif -endif - ANSIBLE_VERSION_ARGS= ifdef ANSIBLE_VERSION ANSIBLE_VERSION_ARGS=--ansible-version=$(ANSIBLE_VERSION) @@ -196,11 +182,11 @@ config: ../templates/config.rst.j2 $(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ $(EXTRA_CONFIG_DUMPER_ARGS) ../../lib/ansible/config/base.yml plugins: - $(PLUGIN_FORMATTER) full -o rst $(ANSIBLE_VERSION_ARGS) $(EXTRA_PLUGIN_FORMATTER_ARGS) $(PLUGIN_ARGS) + $(PLUGIN_FORMATTER) full -o rst $(ANSIBLE_VERSION_ARGS) $(EXTRA_PLUGIN_FORMATTER_ARGS) # This only builds the plugin docs included with ansible-core core_plugins: - $(PLUGIN_FORMATTER) core -o rst $(EXTRA_PLUGIN_FORMATTER_ARGS) $(PLUGIN_ARGS) + $(PLUGIN_FORMATTER) core -o rst $(EXTRA_PLUGIN_FORMATTER_ARGS) epub: (CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx epub) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 05657287b68..a29b8c537f2 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -175,22 +175,18 @@ This process compiles all the links but provides minimal log output. If you're w Building all the rST pages ^^^^^^^^^^^^^^^^^^^^^^^^^^ -To build all the rST files without any module documentation: +To build all the rST files with almost no module documentation: .. code-block:: bash - MODULES=none make webdocs + make coredocs + +This is building effectively the ansible-core documentation, as opposed to the Ansible community package documentation, which includes documentation for many collections. Building module docs and rST pages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To build documentation for a few modules included in ``ansible/ansible`` plus all the rST files, use a comma-separated list: - -.. code-block:: bash - - MODULES=one_module,another_module make webdocs - -To build all the module documentation plus all the rST files: +To build all the module documentation for the Ansible community package plus all the rST files: .. code-block:: bash @@ -207,7 +203,7 @@ Advanced users can build one or more rST files with the sphinx utility directly. sphinx-build [options] sourcedir outdir [filenames...] -You can specify file names, or ``–a`` for all files, or omit both to compile only new/changed files. +You can specify file names, or ``-a`` for all files, or omit both to compile only new/changed files. For example: diff --git a/docs/docsite/rst/dev_guide/testing_documentation.rst b/docs/docsite/rst/dev_guide/testing_documentation.rst index 280e2c03270..65cfc0ce84e 100644 --- a/docs/docsite/rst/dev_guide/testing_documentation.rst +++ b/docs/docsite/rst/dev_guide/testing_documentation.rst @@ -9,23 +9,9 @@ Testing plugin documentation A quick test while developing is to use ``ansible-doc -t `` to see if it renders, you might need to add ``-M /path/to/module`` if the module is not somewhere Ansible expects to find it. -Before you submit a plugin for inclusion in Ansible, you must test your documentation for correct HTML rendering and for modules to ensure that the argspec matches the documentation in your Python file. -The community pages offer more information on :ref:`testing reStructuredText documentation `. +Before you submit a plugin for inclusion in ansible-core, you must run tests to ensure that the argspec matches the documentation in your Python file, and that the argspec's and documentation's structure is correct. -For example, to check the HTML output of your module documentation: - -#. Ensure working :ref:`development environment `. -#. Install required Python packages (drop '--user' in venv/virtualenv): - - .. code-block:: bash - - pip install --user -r requirements.txt - pip install --user -r docs/docsite/requirements.txt - -#. Ensure your module is in the correct directory: ``lib/ansible/modules/mymodule.py`` or in a configured path. -#. Build HTML from your module documentation: ``MODULES=mymodule make webdocs``. -#. To build the HTML documentation for multiple modules, use a comma-separated list of module names: ``MODULES=mymodule,mymodule2 make webdocs``. -#. View the HTML page at ``file:///path/to/docs/docsite/_build/html/modules/mymodule_module.html``. +The community pages offer more information on :ref:`testing reStructuredText documentation ` if you extend the Ansible documentation with additional RST files. To ensure that your module documentation matches your ``argument_spec``: @@ -41,4 +27,10 @@ To ensure that your module documentation matches your ``argument_spec``: ansible-test sanity --test validate-modules mymodule +If you have Docker or Podman installed, you can also use them with the ``--docker`` option, which uses an image that already has all requirements installed: + +.. code-block:: bash + + ansible-test sanity --docker --test validate-modules mymodule + For other plugin types the steps are similar, just adjusting names and paths to the specific type. From e11847995c32edaec5dc0a7646c5fb9daa37446e Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 20 Feb 2024 15:02:45 +0100 Subject: [PATCH 206/536] steering committee: update members / past members lists (#1143) --- .../rst/community/steering/community_steering_committee.rst | 2 -- .../rst/community/steering/steering_committee_past_members.rst | 2 ++ 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index 07235c16892..a848cc0e564 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -44,8 +44,6 @@ The following table lists the current Steering Committee members. See :ref:`stee +------------------+---------------+-------------+ | Andrew Klychkov | Andersson007 | 2021 | +------------------+---------------+-------------+ - | Brad Thornton | cidrblock | 2021 | - +------------------+---------------+-------------+ | Brian Scholer | briantist | 2022 | +------------------+---------------+-------------+ | Dylan Silva | thaumos | 2021 | diff --git a/docs/docsite/rst/community/steering/steering_committee_past_members.rst b/docs/docsite/rst/community/steering/steering_committee_past_members.rst index bc544a888e4..f193c39a230 100644 --- a/docs/docsite/rst/community/steering/steering_committee_past_members.rst +++ b/docs/docsite/rst/community/steering/steering_committee_past_members.rst @@ -18,6 +18,8 @@ people for their great service to the Community and the project! +------------------+-----------+-------------------+ | Name | GitHub | Years of service | +==================+===========+===================+ + | Brad Thornton | cidrblock | 2021-2024 | + +------------------+-----------+-------------------+ | Jill Rouleau | jillr | 2021-2022 | +------------------+-----------+-------------------+ | Tadej Borovšak | tadeboro | 2021-2022 | From 9a5f50d9f83829d6182d9a199c2a3dc02eeaef6a Mon Sep 17 00:00:00 2001 From: rlangus <70724746+rlangus@users.noreply.github.com> Date: Thu, 22 Feb 2024 14:04:21 -0600 Subject: [PATCH 207/536] Update playbooks_templating_now.rst (#1099) Added an example to how to use the function. Co-authored-by: Don Naro --- docs/docsite/rst/playbook_guide/playbooks_templating_now.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_templating_now.rst b/docs/docsite/rst/playbook_guide/playbooks_templating_now.rst index 380995b49b1..f80dab6336d 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_templating_now.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_templating_now.rst @@ -13,4 +13,6 @@ utc Specify ``True`` to get the current time in UTC. Defaults to ``False``. fmt - Accepts a `strftime `_ string that returns a formatted date time string. \ No newline at end of file + Accepts a `strftime `_ string that returns a formatted date time string. + +For example: ``dtg: "Current time (UTC): {{ now(utc=true,fmt='%Y-%m-%d %H:%M:%S') }}"`` From 80af5766b41fcb1ffa207ea4d2c205fe44a03f69 Mon Sep 17 00:00:00 2001 From: John Lamb Date: Thu, 22 Feb 2024 15:05:49 -0500 Subject: [PATCH 208/536] Fix problems with example inventory in the intro_patterns doc (#1138) * invalid inventory format in patterns doc The example inventory placed the host alias directly in the `groups['atlanta']` dictionary, instead of in the `groups['atlanta']['hosts']` dictionary required by the inventory format. * Fix misleading hostvar name in example The documentation implies that ansible uses `hostvars['host1']['host']` to store the address of a target host (as specified in the example inventory), but in fact it would be stored in `hostvars['host1']['ansible_host']`. This is confusing for newcomers. --- docs/docsite/rst/inventory_guide/intro_patterns.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/inventory_guide/intro_patterns.rst b/docs/docsite/rst/inventory_guide/intro_patterns.rst index e3bb607c8eb..039a41b4d90 100644 --- a/docs/docsite/rst/inventory_guide/intro_patterns.rst +++ b/docs/docsite/rst/inventory_guide/intro_patterns.rst @@ -111,10 +111,11 @@ Your pattern must match your inventory syntax. If you define a host as an :ref:` .. code-block:: yaml atlanta: - host1: - http_port: 80 - maxRequestsPerChild: 808 - host: 127.0.0.2 + hosts: + host1: + http_port: 80 + maxRequestsPerChild: 808 + ansible_host: 127.0.0.2 you must use the alias in your pattern. In the example above, you must use ``host1`` in your pattern. If you use the IP address, you will once again get the error: From 83df14a5bc2a3a7a38b9aeb1e8db9e26f4052da5 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 25 Feb 2024 00:10:08 +0000 Subject: [PATCH 209/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 2f48fc4f920..92b893a8944 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -161,11 +161,11 @@ typing-extensions==4.9.0 # via # pydantic # rstcheck -urllib3==2.2.0 +urllib3==2.2.1 # via requests yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==69.1.0 +setuptools==69.1.1 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index 4c6a60a86f4..d37fc895745 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -164,11 +164,11 @@ typing-extensions==4.9.0 # via # pydantic # rstcheck -urllib3==2.2.0 +urllib3==2.2.1 # via requests yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==69.1.0 +setuptools==69.1.1 # via sphinx-intl From 1d6461b335105266c205e496cbf213d00119d072 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sat, 24 Feb 2024 18:52:16 -0600 Subject: [PATCH 210/536] ci: refresh dev dependencies (#1162) --- tests/typing.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/typing.txt b/tests/typing.txt index 723fafd36a3..a61566d96d8 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -20,7 +20,7 @@ codeowners==0.6.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 # via nox -cryptography==42.0.3 +cryptography==42.0.5 # via pyjwt deprecated==1.2.14 # via pygithub @@ -64,11 +64,11 @@ typing-extensions==4.9.0 # mypy # pygithub # typer -urllib3==2.2.0 +urllib3==2.2.1 # via # pygithub # requests -virtualenv==20.25.0 +virtualenv==20.25.1 # via nox wrapt==1.16.0 # via deprecated From 1f8844b20094120e38e1ee219272593face48002 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 28 Feb 2024 00:18:01 -0600 Subject: [PATCH 211/536] Add Ansible community 9.3.0 porting guide (#1168) --- .../rst/porting_guides/porting_guide_9.rst | 34 ++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index cc544d74e02..5d598d03690 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -84,6 +84,38 @@ Porting custom scripts Networking ========== +Porting Guide for v9.3.0 +======================== + +Major Changes +------------- + +community.mysql +~~~~~~~~~~~~~~~ + +- Collection version 2.*.* is EOL, no more bugfixes will be backported. Please consider upgrading to the latest version. + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Update all the boolean values to true/false in the documents and examples. +- Update the document of log_fact. +- Update the mismatched version message with version ranges. +- Update the required ansible version to 2.14. +- Update the supported version ranges instead of concrete version numbers to reduce the collection size. + +Deprecated Features +------------------- + +- The ``inspur.sm`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/2854). +- The ``netapp.storagegrid`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/2811). +- The ``purestorage.fusion`` collection is officially unmaintained and has been archived. Therefore, it will be removed from Ansible 10 (https://forum.ansible.com/t/3712). + +community.crypto +~~~~~~~~~~~~~~~~ + +- openssl_csr_pipe, openssl_privatekey_pipe, x509_certificate_pipe - the current behavior of check mode is deprecated and will change in community.crypto 3.0.0. The current behavior is similar to the modules without ``_pipe``: if the object needs to be (re-)generated, only the ``changed`` status is set, but the object is not updated. From community.crypto 3.0.0 on, the modules will ignore check mode and always act as if check mode is not active. This behavior can already achieved now by adding ``check_mode: false`` to the task. If you think this breaks your use-case of this module, please `create an issue in the community.crypto repository `__ (https://github.com/ansible-collections/community.crypto/issues/712, https://github.com/ansible-collections/community.crypto/pull/714). + Porting Guide for v9.2.0 ======================== @@ -569,7 +601,7 @@ Ansible-core - Old style vars plugins which use the entrypoints `get_host_vars` or `get_group_vars` are deprecated. The plugin should be updated to inherit from `BaseVarsPlugin` and define a `get_vars` method as the entrypoint. - Support for Windows Server 2012 and 2012 R2 has been removed as the support end of life from Microsoft is October 10th 2023. These versions of Windows will no longer be tested in this Ansible release and it cannot be guaranteed that they will continue to work going forward. - ``STRING_CONVERSION_ACTION`` config option is deprecated as it is no longer used in the Ansible Core code base. -- the 'smart' option for setting a connection plugin is being removed as it's main purpose (choosing between ssh and paramiko) is now irrelevant. +- the 'smart' option for setting a connection plugin is being removed as its main purpose (choosing between ssh and paramiko) is now irrelevant. - vault and unfault filters - the undocumented ``vaultid`` parameter is deprecated and will be removed in ansible-core 2.20. Use ``vault_id`` instead. - yum_repository - deprecated parameter 'keepcache' (https://github.com/ansible/ansible/issues/78693). From b69f8c675cb10158ab43a83067359b733e8e0f43 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 28 Feb 2024 21:10:00 +0100 Subject: [PATCH 212/536] [Needs SC vote] Steering Committee: votes on new members to be conducted on the forum; change the chairperson election procedure (#1085) * Steering Committee: votes on new members to be conducted on the forum * Add voting * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: Sandra McCann * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: Sandra McCann * Incorporate feedback * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: Maxwell G * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: Maxwell G * Incorporate feedback * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: John Barker --------- Co-authored-by: Sandra McCann Co-authored-by: Maxwell G Co-authored-by: John Barker --- .../steering/steering_committee_membership.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/docsite/rst/community/steering/steering_committee_membership.rst b/docs/docsite/rst/community/steering/steering_committee_membership.rst index a665ff5ff84..29f34259036 100644 --- a/docs/docsite/rst/community/steering/steering_committee_membership.rst +++ b/docs/docsite/rst/community/steering/steering_committee_membership.rst @@ -45,11 +45,13 @@ A person is eligible to become a Committee member if they have: Process ^^^^^^^^ +Any community member may nominate someone or themselves for Steering Committee membership. + The process to join the Steering Committee consists of the following steps: -#. Any community member may nominate someone or themselves for Committee membership by contacting one of the :ref:`current Committee members `) or by sending an email to ``ansible-community@redhat.com``. -#. A Committee member who receives the nomination must inform the Committee about it by forwarding the full message. -#. The vote is conducted by email. Nominees must receive a majority of votes from the present Committee members to be added to the Committee. +#. The nominator contacts one of the :ref:`current Committee members ` or by sending an email to ``ansible-community@redhat.com``. Existing members nominating would skip to the following step. +#. A Committee member who receives the nomination must inform the Committee about it by forwarding the full nomination message in a private message to the `SteeringCommittee ` group on the forum. +#. The vote is conducted in the forum thread. Nominees must receive a majority of votes from the present Committee members to be added to the Committee. #. Provided that the vote result is positive, it is announced in the `Bullhorn `_ newsletter and the new member is added to the :ref:`Committee member list `. Leaving the Steering Committee @@ -130,14 +132,14 @@ In the case of starting the removal process, the topic's description in the reas Chairperson ------------ -The chairperson election will happen once a year around the time of -Ansible Fest. If the current chairperson has to step down early, the election happens immediately. +The chairperson election happens once a year at the time the Committee agrees on by voting in a dedicated forum thread. +If the current chairperson has to step down early, the election happens immediately. The process of the election consists of the following steps: -#. Members interested in being the chairperson will inform a - person responsible for arranging the election about that. -#. Conduct anonymous voting somewhere. +#. Send a private message to the `Steering Committee `_ forum group. +#. Members interested in being the chairperson nominate themselves in the thread. +#. Conduct anonymous voting in the thread. #. Internally and publicly announce the elected candidate. The chairperson has the following powers unlike regular members: From 2292a057ae1acc1eb5147cfa55da2b148f4d1f8a Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Fri, 1 Mar 2024 10:38:12 +0100 Subject: [PATCH 213/536] [SC vote needed] Steering Committee: simplify member removal policy; update links (#1075) * Steering Committee: simplify member removal policy; update links * The topic must be private * Incorporate feedback * Fix * Fix * Fix * Revert the changes * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: Maxwell G * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: Maxwell G * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: Maxwell G * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: Maxwell G * Remove line * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: Mario Lenz * Update docs/docsite/rst/community/steering/steering_committee_membership.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> --------- Co-authored-by: Maxwell G Co-authored-by: Mario Lenz Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> --- .../steering_committee_membership.rst | 36 +++++++++++-------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/docsite/rst/community/steering/steering_committee_membership.rst b/docs/docsite/rst/community/steering/steering_committee_membership.rst index 29f34259036..36db0ab76e2 100644 --- a/docs/docsite/rst/community/steering/steering_committee_membership.rst +++ b/docs/docsite/rst/community/steering/steering_committee_membership.rst @@ -23,7 +23,7 @@ As a Committee member, you agree to: #. Abide by the :ref:`code_of_conduct` in all your interactions with the Community. #. Be a Community ambassador by representing its needs within the Committee and throughout the decision making process. -#. Asynchronously participate in discussions and voting on the `Community Topics `_. +#. Asynchronously participate in discussions and voting on the `Community Topics `_. #. Review other proposals of importance that need the Committee's attention and provide feedback. #. Act for the sake of the Community by not promoting corporate or individual agenda during the decision making process. #. Engage with the Community in a professional and positive manner, encourage community members to express their opinion. @@ -52,7 +52,7 @@ The process to join the Steering Committee consists of the following steps: #. The nominator contacts one of the :ref:`current Committee members ` or by sending an email to ``ansible-community@redhat.com``. Existing members nominating would skip to the following step. #. A Committee member who receives the nomination must inform the Committee about it by forwarding the full nomination message in a private message to the `SteeringCommittee ` group on the forum. #. The vote is conducted in the forum thread. Nominees must receive a majority of votes from the present Committee members to be added to the Committee. -#. Provided that the vote result is positive, it is announced in the `Bullhorn `_ newsletter and the new member is added to the :ref:`Committee member list `. +#. Provided that the vote result is positive, it is announced in the `Bullhorn `_ newsletter and the new member is added to the :ref:`Committee member list `. Leaving the Steering Committee ------------------------------- @@ -67,7 +67,10 @@ Voluntarily leaving the Steering Committee ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A Committee member can voluntarily leave the Committee. -In this case, they notify the other members, create an issue in the `Community Topics `_ repository announcing the resignation, and after that, they are no longer considered Committee members. +In this case, the member notifies the other members via a private message to the ``SteeringCommittee`` group in the forum. +This change in the steering committee has also to be announced in Bullhorn. +If the member voluntarily leaving does not want to write this announcement, one of the remaining Committee members will write it. +After that, they are no longer considered a Committee member. Committee members who resign and later change their minds can rejoin the Committee by following the :ref:`Process for joining the Steering Committee`. @@ -77,7 +80,7 @@ Involuntarily leaving the Steering Committee A Committee member will be removed from the Committee if they: -#. Do not participate in asynchronous discussions and voting on the `Community Topics `_ for more than 3 months in a row. +#. Do not participate in asynchronous discussions and voting on `Community Topics `_ for more than 3 months in a row. #. Participate unreasonably irregularly (for example, once a month for several months). Unreasonably is defined by other Committee members considering circumstances in each particular case. #. Violate the :ref:`code_of_conduct`. @@ -86,23 +89,26 @@ A Committee member will be removed from the Committee if they: Absence or irregular participation in discussing topics and votes .................................................................. -In case of absence or irregular participation, the involuntarily removal process consists of the following steps: +In case of absence or irregular participation, the removal process consists of the following steps: #. Another Committee member (hereinafter the initiator) contacts the person by email asking if they are still interested in fulfilling their Committee member's duties. -#. If they respond that they are not interested, the initiator asks the person to step down on their own following the :ref:`Voluntarily leaving process`. -#. If there has been no response or stepping down issue created by the person within a reasonable time, the initiator notifies other Committee members about the situation. -#. In case of agreement among the Committee about the need for removal, the initiator provides a draft of a corresponding topic's description to the Committee by email for discussion and approval. - * The topic's title is ``Steering Committee member audit.``. It must not contain the person's name or other identifying information. + * If the answer is negative, the initiator asks the person to :ref:`step down voluntarily`. - * The description must not contain or imply any form of condemnation. +#. In case there is no response from the person within a week after the email was sent or if the person agreed to step down but has no time to do it themselves, the initiator: - * It must mention that the person has been inactive for an unknown reason for the last N months and that, in accordance with the Steering Committee policies, their place should be freed for another person who can continue their great job. + * Sends a private message to the ``SteeringCommittee`` group on the forum. - * The description must mention person's achievements and thanks for their time and effort they spent serving for the Community, Committee, and the Project, and a hope that one day they will come back. + * The message title is ``Steering Committee member audit.``. -#. The initiator creates the topic in the `Community Topics `_ repository containing the description and the title from the draft. -#. The Committee members vote on the topic. + * The message body must not contain or imply any form of condemnation. + + * It must mention that the person has been inactive and, in accordance with the Steering Committee policies, their place should be freed for another person who can continue their great job. + + * The message should thank the Committee member for their time and effort they spent serving the Community during their time on the Committee. + +#. The Committee members vote in the thread. +#. If the Committee votes for removal, a pull request is raised to move the person from the :ref:`steering_members` list to the :ref:`steering_past_members` and merged. Ansible Community Code of Conduct violations ............................................. @@ -144,4 +150,4 @@ The process of the election consists of the following steps: The chairperson has the following powers unlike regular members: -* The chairperson's vote breaks ties to resolve deadlocks when equal numbers of steering committee members vote for and against a `community topic `_. +* The chairperson's vote breaks ties to resolve deadlocks when equal numbers of steering committee members vote for and against a `community topic `_. From 116a73d737481dd40c830c9f8def77767fa61da8 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 4 Mar 2024 06:37:42 +0000 Subject: [PATCH 214/536] Bump wntrblm/nox from 2023.04.22 to 2024.03.02 Bumps [wntrblm/nox](https://github.com/wntrblm/nox) from 2023.04.22 to 2024.03.02. - [Release notes](https://github.com/wntrblm/nox/releases) - [Changelog](https://github.com/wntrblm/nox/blob/main/CHANGELOG.md) - [Commits](https://github.com/wntrblm/nox/compare/2023.04.22...2024.03.02) --- updated-dependencies: - dependency-name: wntrblm/nox dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- .github/workflows/reusable-nox.yml | 2 +- .github/workflows/reusable-pip-compile.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/reusable-nox.yml b/.github/workflows/reusable-nox.yml index a7611e30f32..6a96b993097 100644 --- a/.github/workflows/reusable-nox.yml +++ b/.github/workflows/reusable-nox.yml @@ -28,7 +28,7 @@ jobs: - name: Check out repo uses: actions/checkout@v4 - name: Setup nox - uses: wntrblm/nox@2023.04.22 + uses: wntrblm/nox@2024.03.02 with: python-versions: "${{ matrix.python-versions }}" - name: Graft ansible-core diff --git a/.github/workflows/reusable-pip-compile.yml b/.github/workflows/reusable-pip-compile.yml index dc25afe6d59..6242748cf7b 100644 --- a/.github/workflows/reusable-pip-compile.yml +++ b/.github/workflows/reusable-pip-compile.yml @@ -53,7 +53,7 @@ jobs: run: | python docs/bin/clone-core.py - name: Set up nox - uses: wntrblm/nox@2023.04.22 + uses: wntrblm/nox@2024.03.02 with: python-versions: "3.9" - name: Set up git committer From 075615a0f2067862fb60b2ba33797495556553b9 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Thu, 7 Mar 2024 13:04:57 -0600 Subject: [PATCH 215/536] Data Tagging Delayed to 2.18 (#1182) --- docs/docsite/rst/roadmap/ROADMAP_2_17.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/roadmap/ROADMAP_2_17.rst b/docs/docsite/rst/roadmap/ROADMAP_2_17.rst index d731d5d53fc..c75158b32ef 100644 --- a/docs/docsite/rst/roadmap/ROADMAP_2_17.rst +++ b/docs/docsite/rst/roadmap/ROADMAP_2_17.rst @@ -48,7 +48,6 @@ Release Manager Planned work ============ -* Data Tagging * Drop Python 2.7 and 3.6 support for module execution * Remove deprecated functionality * Decrease incidental integration tests @@ -62,3 +61,4 @@ Delayed work The following work has been delayed and retargeted for a future release: +* Data Tagging From b46a0a0f33e6f18709ccc0bf992bce123129edde Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Thu, 7 Mar 2024 14:09:52 -0500 Subject: [PATCH 216/536] ci: refresh docs build dependencies (#1173) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 92b893a8944..9dd4127d357 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -34,7 +34,7 @@ babel==2.14.0 # via # sphinx # sphinx-intl -build==1.0.3 +build==1.1.1 # via antsibull-core certifi==2024.2.2 # via requests @@ -157,7 +157,7 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.9.0 +typing-extensions==4.10.0 # via # pydantic # rstcheck diff --git a/tests/requirements.txt b/tests/requirements.txt index d37fc895745..02b1a9b5cf0 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -36,7 +36,7 @@ babel==2.14.0 # via # sphinx # sphinx-intl -build==1.0.3 +build==1.1.1 # via antsibull-core certifi==2024.2.2 # via requests @@ -160,7 +160,7 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.9.0 +typing-extensions==4.10.0 # via # pydantic # rstcheck From f570902dea02988de93647e4b1d547773641c260 Mon Sep 17 00:00:00 2001 From: Johnny Lim Date: Fri, 8 Mar 2024 04:22:20 +0900 Subject: [PATCH 217/536] Fix typo (#1175) * Fix typo * Use double quotes Co-authored-by: Don Naro * Update docs/docsite/rst/getting_started/get_started_playbook.rst --------- Co-authored-by: Don Naro Co-authored-by: Sandra McCann --- docs/docsite/rst/getting_started/get_started_playbook.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/getting_started/get_started_playbook.rst b/docs/docsite/rst/getting_started/get_started_playbook.rst index 0aba4392842..26c76917210 100644 --- a/docs/docsite/rst/getting_started/get_started_playbook.rst +++ b/docs/docsite/rst/getting_started/get_started_playbook.rst @@ -42,7 +42,7 @@ In this output you can see: * The names that you give the play and each task. You should always use descriptive names that make it easy to verify and troubleshoot playbooks. -* The ``Gather Facts`` task runs implicitly. +* The ``Gathering Facts`` task runs implicitly. By default, Ansible gathers information about your inventory that it can use in the playbook. * The status of each task. From 39e1e2945366fee17062c26eca15b1bc66b14afe Mon Sep 17 00:00:00 2001 From: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> Date: Thu, 7 Mar 2024 14:36:22 -0500 Subject: [PATCH 218/536] Clarify documentation about empty collections vs collection skeletons (#1180) * Clarify documentation about empty collections vs collection skeletons * Update docs/docsite/rst/dev_guide/developing_collections_creating.rst --- .../developing_collections_creating.rst | 44 ++++++++++++++++--- 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections_creating.rst b/docs/docsite/rst/dev_guide/developing_collections_creating.rst index 8b1a9b1f873..deff8fb1b63 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_creating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_creating.rst @@ -6,7 +6,7 @@ Creating collections To create a collection: -#. Create a :ref:`collection skeleton` with the ``ansible-galaxy collection init`` command. +#. Create a :ref:`new collection`, optionally using a custom :ref:`collection template`, with the ``ansible-galaxy collection init`` command. #. Add modules and other content to the collection. #. Build the collection into a collection artifact with :ref:`ansible-galaxy collection build`. #. Publish the collection artifact to Galaxy with :ref:`ansible-galaxy collection publish`. @@ -44,10 +44,10 @@ There are a few special namespaces: The `local namespace `__ does not contain any collection on Ansible Galaxy, and the intention is that this will never change. You can use the ``local`` namespace for collections that are locally on your machine or locally in your git repositories, without having to fear collisions with actually existing collections on Ansible Galaxy. -.. _creating_collections_skeleton: +.. _creating_new_collections: -Creating a collection skeleton -============================== +Creating a new collection +========================= Create your collection skeleton in a path that includes ``ansible_collections``, for example `collections/ansible_collections/`. @@ -66,19 +66,51 @@ It will create the structure ``[my_namespace]/[my_collection]/[collection skelet .. hint:: If Git is used for version control, the corresponding repository should be initialized in the collection directory. -Once the skeleton exists, you can populate the directories with the content you want inside the collection. See `ansible-collections `_ GitHub Org to get a better idea of what you can place inside a collection. +Once the collection exists, you can populate the directories with the content you want inside the collection. See `ansible-collections `_ GitHub Org to get a better idea of what you can place inside a collection. Reference: the ``ansible-galaxy collection`` command Currently the ``ansible-galaxy collection`` command implements the following sub commands: -* ``init``: Create a basic collection skeleton based on the default template included with Ansible or your own template. +* ``init``: Create a basic collection based on the default template included with Ansible or your own template. * ``build``: Create a collection artifact that can be uploaded to Galaxy or your own repository. * ``publish``: Publish a built collection artifact to Galaxy. * ``install``: Install one or more collections. To learn more about the ``ansible-galaxy`` command-line tool, see the :ref:`ansible-galaxy` man page. +.. _creating_collection_skeletons: + +Creating a collection from a custom template +============================================ + +The built-in collection template is a simple example of a collection that works with ``ansible-core``, but if you want to simplify your development process you may want to create a custom collection template to pass to ``ansible-galaxy collection init``. + +A collection skeleton is a directory that looks like a collection directory but any ``.j2`` files (excluding those in ``templates/`` and ``roles/*/templates/``) will be templated by ``ansible-galaxy collection init``. The skeleton's ``galaxy.yml.j2`` file should use the variables ``namespace`` and ``collection_name`` which are derived from ``ansible-galaxy init namespace.collection_name``, and will populate the metadata in the initialized collection's ``galaxy.yml`` file. There are a few additional variables available by default (for example, ``version`` is ``1.0.0``), and these can be supplemented/overridden using ``--extra-vars``. + +An example ``galaxy.yml.j2`` file that accepts an optional dictionary variable ``dependencies`` could look like this: + +.. code-block:: yaml + + namespace: {{ namespace }} + name: {{ collection_name }} + version: "{{ (version|quote) is version("0.0.0", operator="gt", version_type="semver")|ternary(version, undef("version must be a valid semantic version greater than 0.0.0")) }}" + dependencies: {{ dependencies|default({}, true) }} + +To initialize a collection using the new template, pass the path to the skeleton with ``ansible-galaxy collection init``: + +.. code-block:: bash + + ansible_collections#> ansible-galaxy collection init --collection-skeleton /path/to/my/namespace/skeleton --extra-vars "@my_vars_file.json" my_namespace.my_collection + +.. note:: + + Before ``ansible-core`` 2.17, collection skeleton templating is limited to the few hardcoded variables including ``namespace``, ``collection_name``, and ``version``. + +.. note:: + + The default collection skeleton uses an internal filter ``comment_ify`` that isn't accessibly to ``--collection-skeleton``. Use ``ansible-doc -t filter|test --list`` to see available plugins. + .. seealso:: :ref:`collections` From 05bbf1879330e14e3d11b359184b9ea48b809fd7 Mon Sep 17 00:00:00 2001 From: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> Date: Thu, 7 Mar 2024 14:47:34 -0500 Subject: [PATCH 219/536] Update documentation about vars: in roles: since they're no longer added to the play's variables (#1181) --- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 41dd0ad80dd..990cc990334 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -151,7 +151,9 @@ You can pass other keywords to the ``roles`` option: When you add a tag to the ``role`` option, Ansible applies the tag to ALL tasks within the role. -When using ``vars:`` within the ``roles:`` section of a playbook, the variables are added to the play variables, making them available to all tasks within the play before and after the role. This behavior can be changed by :ref:`DEFAULT_PRIVATE_ROLE_VARS`. +.. note:: + + Prior to ``ansible-core`` 2.15, ``vars:`` within the ``roles:`` section of a playbook are added to the play variables, making them available to all tasks within the play before and after the role. This behavior can be changed by :ref:`DEFAULT_PRIVATE_ROLE_VARS`. On more recent versions, ``vars:`` do not leak into the play's variable scope. Including roles: dynamic reuse ------------------------------ From 7b8500dea137ebd4d7d86ae4c453a9e07be83ebe Mon Sep 17 00:00:00 2001 From: "Eric L." Date: Sat, 9 Mar 2024 17:03:48 +0100 Subject: [PATCH 220/536] The ipaddr/ipv4/ipv6 filters have moved from netcommon to utils --- docs/docsite/rst/playbook_guide/playbooks_filters.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index ac01a6010f3..0e1791980fa 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -1253,24 +1253,24 @@ To test if a string is a valid IP address: .. code-block:: yaml+jinja - {{ myvar | ansible.netcommon.ipaddr }} + {{ myvar | ansible.utils.ipaddr }} You can also require a specific IP protocol version: .. code-block:: yaml+jinja - {{ myvar | ansible.netcommon.ipv4 }} - {{ myvar | ansible.netcommon.ipv6 }} + {{ myvar | ansible.utils.ipv4 }} + {{ myvar | ansible.utils.ipv6 }} IP address filter can also be used to extract specific information from an IP address. For example, to get the IP address itself from a CIDR, you can use: .. code-block:: yaml+jinja - {{ '192.0.2.1/24' | ansible.netcommon.ipaddr('address') }} + {{ '192.0.2.1/24' | ansible.utils.ipaddr('address') }} # => 192.0.2.1 -More information about :ansplugin:`ansible.netcommon.ipaddr#filter` filter and complete usage guide can be found +More information about :ansplugin:`ansible.utils.ipaddr#filter` filter and complete usage guide can be found in :ref:`playbooks_filters_ipaddr`. .. _network_filters: From 8d2e8770734f91d90fb3991edab00dfdd70f9e0d Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 3 Mar 2024 00:05:57 +0000 Subject: [PATCH 221/536] ci: refresh dev dependencies --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index f15f6a601c4..0c7e6dbab96 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -20,5 +20,5 @@ platformdirs==4.2.0 # via black tomli==2.0.1 # via black -typing-extensions==4.9.0 +typing-extensions==4.10.0 # via black diff --git a/tests/static.txt b/tests/static.txt index 628384eed9c..4c2ad93cbe9 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.2.2 +ruff==0.3.0 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index a61566d96d8..2daa9bd3cfc 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -58,7 +58,7 @@ tomli==2.0.1 # via mypy typer==0.9.0 # via -r tests/../hacking/pr_labeler/requirements.txt -typing-extensions==4.9.0 +typing-extensions==4.10.0 # via # codeowners # mypy From 5237dc1b588f870c3b342c5920d4637a9d775646 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Tue, 5 Mar 2024 19:18:26 +0000 Subject: [PATCH 222/536] ci: refresh dev dependencies --- tests/typing.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/typing.txt b/tests/typing.txt index 2daa9bd3cfc..5363784d9aa 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -38,7 +38,7 @@ mypy==1.8.0 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy -nox==2023.4.22 +nox==2024.3.2 # via -r tests/typing.in packaging==23.2 # via nox From 2f6bbe0c5f43f0e2faf0a203ac0b24b477f16a54 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 10 Mar 2024 00:06:19 +0000 Subject: [PATCH 223/536] ci: refresh dev dependencies --- tests/static.txt | 2 +- tests/typing.txt | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index 4c2ad93cbe9..f40fc514a3e 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.3.0 +ruff==0.3.2 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 5363784d9aa..0d1d9c5c37e 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/typing.txt --strip-extras tests/typing.in # -argcomplete==3.2.2 +argcomplete==3.2.3 # via nox certifi==2024.2.2 # via requests @@ -16,7 +16,7 @@ charset-normalizer==3.3.2 # via requests click==8.1.7 # via typer -codeowners==0.6.0 +codeowners==0.7.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 # via nox @@ -34,7 +34,7 @@ jinja2==3.1.3 # via -r tests/../hacking/pr_labeler/requirements.txt markupsafe==2.1.5 # via jinja2 -mypy==1.8.0 +mypy==1.9.0 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy From 4fbf8cc2e36e4356e263ba7440903daebc6c6f8b Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 12 Mar 2024 09:57:16 +0000 Subject: [PATCH 224/536] use ruff check syntax in noxfile --- noxfile.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/noxfile.py b/noxfile.py index ecaebb0f0fd..50f4034d38a 100644 --- a/noxfile.py +++ b/noxfile.py @@ -31,7 +31,7 @@ def static(session: nox.Session): Run static checkers """ install(session, req="static") - session.run("ruff", *session.posargs, *LINT_FILES) + session.run("ruff", "check", *session.posargs, *LINT_FILES) @nox.session From d0ee17ece91c6ecd61f3adfc573e3884e72df5ae Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 13 Mar 2024 13:44:03 -0400 Subject: [PATCH 225/536] add back suggested edit from #1175 --- docs/docsite/rst/getting_started/get_started_playbook.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/getting_started/get_started_playbook.rst b/docs/docsite/rst/getting_started/get_started_playbook.rst index 26c76917210..170b1f2205a 100644 --- a/docs/docsite/rst/getting_started/get_started_playbook.rst +++ b/docs/docsite/rst/getting_started/get_started_playbook.rst @@ -42,7 +42,7 @@ In this output you can see: * The names that you give the play and each task. You should always use descriptive names that make it easy to verify and troubleshoot playbooks. -* The ``Gathering Facts`` task runs implicitly. +* The "Gathering Facts" task runs implicitly. By default, Ansible gathers information about your inventory that it can use in the playbook. * The status of each task. From 6544a5c11199657e4004643b223700d5cf7cf197 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 13 Mar 2024 16:32:22 -0400 Subject: [PATCH 226/536] Trim down the docs banners (#1188) --- docs/docsite/.templates/banner.html | 5 +++-- docs/docsite/rst/conf.py | 4 ++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/docsite/.templates/banner.html b/docs/docsite/.templates/banner.html index f013940f258..7f0dc156f45 100644 --- a/docs/docsite/.templates/banner.html +++ b/docs/docsite/.templates/banner.html @@ -16,12 +16,13 @@ var banner = ''; var extra_banner = ''; /*use extra_banner for when we want something extra, like a survey or Community Day notice */ - var extra_banner = + /* var extra_banner = '

' + '

' + 'Discuss Ansible in the new Ansible Forum!' + '

' + '
'; + */ // Create a banner if we're not on the official docs site if (location.host == "docs.testing.ansible.com") { document.write('
' + @@ -40,7 +41,7 @@ /* temp extra banner to advertise something */ banner += extra_banner; - msg += 'This is the latest (stable) community version of the Ansible documentation. For Red Hat customers, see the difference between Ansible community projects and Red Hat supported products or Ansible Automation Platform Life Cycle for subscriptions.'; + msg += 'This is the latest (stable) Ansible community documentation. For Red Hat Ansible Automation Platform subscriptions, see Life Cycle for version details.'; } else if (startsWith(current_url_path, "/ansible/2.9/")) { msg += 'You are reading the latest Red Hat released version of the Ansible documentation. Community users can use this version, or select latest from the version selector to the left for the most recent community version.'; } else if (startsWith(current_url_path, "/ansible/devel/")) { diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 93d8c36255b..0557e180dc7 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -263,12 +263,12 @@ html_title = ( 'Ansible Core Documentation' if ( tags.has('all') or tags.has('core_lang') or tags.has('core') - ) else 'Ansible Documentation' if tags.has('ansible') + ) else 'Ansible Community Documentation' if tags.has('ansible') else '' ) # A shorter title for the navigation bar. Default is the same as html_title. -html_short_title = 'Documentation' +# html_short_title = 'Community Documentation' # The name of an image file (within the static path) to place at the top of # the sidebar. From 482ed2aea26890e8cf6a4e8b1cc3248721281589 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 13 Mar 2024 16:36:47 -0400 Subject: [PATCH 227/536] Add link to antsibull-docs docsite (#1198) --- .../rst/dev_guide/developing_collections_documenting.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/docsite/rst/dev_guide/developing_collections_documenting.rst b/docs/docsite/rst/dev_guide/developing_collections_documenting.rst index a0d60676544..f80b75e9384 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_documenting.rst @@ -27,4 +27,7 @@ You can use `antsibull-docs `_ to build #. Then run ``./build.sh``. #. Open ``build/html/index.html`` in a browser of your choice. +See `antsibull-docs documentation `_ for complete details. + If you want to add additional documentation to your collection next to the plugin, module, and role documentation, see :ref:`collections_doc_dir`. + From a985c5b375b6495d63d2a6be12038cb76c13ece7 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 17 Mar 2024 21:18:49 -0500 Subject: [PATCH 228/536] ci: refresh dev dependencies (#1214) --- tests/formatters.txt | 4 ++-- tests/static.txt | 2 +- tests/typing.txt | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 0c7e6dbab96..18d9e417dee 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==24.2.0 +black==24.3.0 # via -r tests/formatters.in click==8.1.7 # via black @@ -12,7 +12,7 @@ isort==5.13.2 # via -r tests/formatters.in mypy-extensions==1.0.0 # via black -packaging==23.2 +packaging==24.0 # via black pathspec==0.12.1 # via black diff --git a/tests/static.txt b/tests/static.txt index f40fc514a3e..52f0fdd4873 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.3.2 +ruff==0.3.3 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 0d1d9c5c37e..345d3fc9295 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -40,7 +40,7 @@ mypy-extensions==1.0.0 # via mypy nox==2024.3.2 # via -r tests/typing.in -packaging==23.2 +packaging==24.0 # via nox platformdirs==4.2.0 # via virtualenv From 38c01a20659bfb69abe31f1d99019d8d6b98bbfe Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Sun, 17 Mar 2024 22:50:30 -0500 Subject: [PATCH 229/536] hacking: add script to create git tags for new Core releases (#1084) Relates: https://github.com/ansible/ansible-documentation/issues/66 --- hacking/tagger/requirements.txt | 3 + hacking/tagger/tag.py | 416 ++++++++++++++++++++++++++++++++ noxfile.py | 1 + tests/typing.in | 1 + tests/typing.txt | 14 +- 5 files changed, 433 insertions(+), 2 deletions(-) create mode 100644 hacking/tagger/requirements.txt create mode 100755 hacking/tagger/tag.py diff --git a/hacking/tagger/requirements.txt b/hacking/tagger/requirements.txt new file mode 100644 index 00000000000..220933af86f --- /dev/null +++ b/hacking/tagger/requirements.txt @@ -0,0 +1,3 @@ +gitpython +packaging +typer diff --git a/hacking/tagger/tag.py b/hacking/tagger/tag.py new file mode 100755 index 00000000000..a3e556cb7ec --- /dev/null +++ b/hacking/tagger/tag.py @@ -0,0 +1,416 @@ +#!/usr/bin/env python3 + +# Copyright (C) 2024 Maxwell G +# SPDX-License-Identifier: GPL-3.0-or-later +# GNU General Public License v3.0+ +# (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) + +""" +Script to handle tagging versions in the ansible-documentation repo in sync +with ansible-core. +""" + +from __future__ import annotations + +import datetime +from collections.abc import Iterable +from dataclasses import dataclass +from pathlib import Path +from string import Template +from types import SimpleNamespace +from typing import Any, List, NamedTuple, NoReturn, Optional + +import click +import git +import git.objects.util +import typer + +from packaging.version import Version + +MESSAGE = Template( + """\ +${version_str} + +This tag contains a snapshot of the ansible-documentation ${branch} branch +at the time of the ansible-core ${version_str} release. +""" +) +# hacking/tagger +HERE = Path(__file__).resolve().parent +ROOT = HERE.parent.parent + +DEFAULT_ANSIBLE_CORE_CHECKOUT = ROOT.parent.joinpath("ansible") +DEFAULT_REMOTE = "origin" +DEFAULT_ACTIVE_BRANCHES: tuple[str, ...] = ("stable-2.14", "stable-2.15", "stable-2.16") + + +def get_tags(repo: git.Repo) -> list[str]: + """ + Args: + repo: + A repo object + Returns: + A list of tag names as strings + """ + return [tag.name.removeprefix("refs/tags/") for tag in repo.tags] + + +def filter_tags(tags: Iterable[str], major_minor: str) -> dict[str, Version]: + """ + Args: + tags: + Iterable of tag names as strings + major_minor: + `{version.major}.{version.minor}` of an ansible-core branch + Returns: + Sorted (newest->oldest) dict of tag names that are part of + `major_minor` mapped to parsed `packaging.version.Version`s + """ + tags = { + tag: Version(stripped) + for tag in tags + if (stripped := tag.lstrip("v")).startswith(major_minor) + } + return dict(sorted(tags.items(), reverse=True, key=lambda x: x[1])) + + +def get_tag_datetime(tag: git.TagReference) -> datetime.datetime: + """ + Args: + tag: + Lightweight tag reference + Returns: + A `datetime.datetime` of the tagged date or the committed date for a + non-annotated tag + """ + if tag.tag: + return git.objects.util.from_timestamp( + tag.tag.tagged_date, tag.tag.tagger_tz_offset + ) + return tag.commit.committed_datetime + + +def _get_last_commit_before( + commits: Iterable[git.objects.Commit], before: datetime.datetime +) -> git.objects.Commit: + for commit in commits: + if commit.committed_datetime <= before: + return commit + raise ValueError("No commit found!") + + +def get_last_hash( + docs_repo: git.Repo, core_tag: git.TagReference, branch: str, remote: str +) -> str: + """ + Get the last commit before the datetime of ansible-core's release of TAG. + + Args: + docs_repo: + ansible-documentation `git.Repo` object + core_tag: + `git.TagReference` for the corresponding tag in ansible-core + branch: + Branch name in which to search for the properly timed commit + + Returns: + Commit hash + + Raises: + ValueError: + No commit was found before the datetime of ansible-core's release of TAG + """ + return _get_last_commit_before( + commits=docs_repo.iter_commits(f"{remote}/{branch}", first_parent=True), + before=get_tag_datetime(core_tag), + ) + + +def get_branch(tag_name: str, /) -> str: + """ + Determine a `stable-XX.XX` branch name based on `tag_name` + """ + version = Version(tag_name.lstrip("v")) + major_minor = f"{version.major}.{version.minor}" + return "stable-" + major_minor + + +def v_prefix_tag(name: str, /) -> str: + """ + Ensure a tag/version has a `v` prefix + """ + return "v" + name.lstrip("v") + + +# START: typer CLI code + +app = typer.Typer() + + +def fatal(__msg: object, /, *, returncode: int = 1) -> NoReturn: + typer.secho(f"! {__msg}", err=True, fg="red") + raise typer.Exit(returncode) + + +def msg(__msg: object, not_on_quiet: bool = True, /, **kwargs: Any) -> None: + if not_on_quiet: + try: + quiet = click.get_current_context().ensure_object(Args).quiet + except Exception: + quiet = False + if quiet: + return + kwarg: dict[str, Any] = {"err": True, "fg": "blue"} | kwargs + typer.secho(f"* {__msg}", **kwarg) + + +@dataclass(kw_only=True) +class Args: + """ + Context for global arguments + """ + + docs_repo_path: Path + docs_repo: git.Repo + docs_remote: str + core_repo_path: Path + core_repo: git.Repo + core_remote: str + quiet: bool + + +def ensure_tag(tag: git.TagReference) -> None: + """ + Ensure a `git.TagReference` actually object + """ + try: + _ = tag.object + except ValueError: + name = tag.name.removeprefix("refs/tags/") + fatal(f"Tag {name} does not exist in core!") + + +def get_new_tags(args: Args, branch: str) -> dict[str, Version]: + """ + Returns: + Sorted (newest->oldest) dict of new tag names mapped to parsed + `packaging.version.Version`s + """ + core_tags, our_tags = get_tags(args.core_repo), get_tags(args.docs_repo) + core_filtered_tags = filter_tags(core_tags, branch.removeprefix("stable-")) + our_filtered_tags = filter_tags(our_tags, branch.removeprefix("stable-")) + missing_tags: dict[str, Version] = {} + for tag, version in core_filtered_tags.items(): + if tag in our_filtered_tags: + break + missing_tags[tag] = version + return missing_tags + + +class BranchTagRef(NamedTuple): + branch: str + tag: str + ref: str + + +def branch_tag_ref( + args: Args, branch: str | None, tag: str, ref: str | None +) -> BranchTagRef: + tag = v_prefix_tag(tag) + branch = branch or get_branch(tag) + core_tag = args.core_repo.tag(tag) + ensure_tag(core_tag) + if not ref: + ref = get_last_hash(args.docs_repo, core_tag, branch, args.docs_remote) + return BranchTagRef(branch, tag, ref) + + +def create_tag( + args: Args, branch: str, tag: str, ref: str, *, push: bool +) -> git.TagReference: + """ + Create and push a tag with the proper message + + Args: + args: + CLI context `Args` object + branch: + Branch name + tag: + Tag name + ref: + Reference to tag + """ + message = MESSAGE.substitute(version_str=tag.lstrip("v"), branch=branch) + msg(f"Tagging {ref} as {tag}") + tag_ref = git.TagReference.create(args.docs_repo, tag, ref, message) + if push: + print(f"Pushing {tag} to {args.docs_remote}") + args.docs_repo.remote(args.docs_remote).push(tag) + return tag_ref + + +PARAMS = SimpleNamespace( + branches=typer.Option( + None, + "-b", + "--branch", + help="Branches in which to search for tags." + " Can be specified multiple times." + f" Defaults to {DEFAULT_ACTIVE_BRANCHES}", + ), + branch=typer.Option( + None, + "-b", + "--branch", + help="Branch name. Autodetect based on --tag by deafult.", + ), + tag_required=typer.Option( + ..., + "-t", + "--tag", + help="Tag name", + ), + ref=typer.Option( + ..., + "-r", + "--ref", + help="Tag reference", + ), +) + + +@app.callback(help=__doc__) +def callback( + ctx: typer.Context, + docs_repo_path: Path = typer.Option( + ROOT, + "--docs", + help="Path to ansible-documentation checkout", + dir_okay=True, + file_okay=False, + exists=True, + ), + core_repo_path: Path = typer.Option( + DEFAULT_ANSIBLE_CORE_CHECKOUT, + "--core", + help="Path to core checkout", + dir_okay=True, + file_okay=False, + exists=True, + ), + remote: Optional[str] = typer.Option( + None, + help="Git Remote name for ansible-core and ansible-documentation checkouts." + f" Default: {DEFAULT_REMOTE}", + ), + core_remote: Optional[str] = typer.Option( + None, help="Override remote name for core checkout" + ), + docs_remote: Optional[str] = typer.Option( + None, help="Override remote name for docs checkout" + ), + fetch: bool = typer.Option(True, help="Whether to fetch repos"), + quiet: bool = typer.Option(False, help="Silence logging"), +): + """ + Process global CLI arguments and create a context object to store them + """ + core_remote = core_remote or remote or DEFAULT_REMOTE + docs_remote = docs_remote or remote or DEFAULT_REMOTE + docs_repo = git.Repo(docs_repo_path) + core_repo = git.Repo(core_repo_path) + args = Args( + docs_repo_path=docs_repo_path, + docs_repo=docs_repo, + docs_remote=docs_remote, + core_repo_path=core_repo_path, + core_repo=core_repo, + core_remote=core_remote, + quiet=quiet, + ) + ctx.obj = args + if fetch: + fetch_all(args) + + +def fetch_all(args: Args) -> None: + remotes = { + "docs": (args.docs_repo, args.docs_remote), + "core": (args.core_repo, args.core_remote), + } + for name, (repo, cur_remote) in remotes.items(): + msg(f"Fetching {cur_remote} from {name} repo...") + repo.remote(cur_remote).fetch() + + +@app.command(name="new-tags") +def new_tags_command( + ctx: typer.Context, branches: Optional[List[str]] = PARAMS.branches +) -> None: + """ + List new tags in ansible-core that are not tagged here + """ + args = ctx.ensure_object(Args) + branches = branches or list(DEFAULT_ACTIVE_BRANCHES) + missing_tags = [tag for branch in branches for tag in get_new_tags(args, branch)] + if missing_tags: + print("\n".join(missing_tags)) + ctx.exit(0 if missing_tags else 1) + + +@app.command(name="hash") +def hash_command( + ctx: typer.Context, + tag: str = PARAMS.tag_required, + branch: Optional[str] = PARAMS.branch, +) -> None: + """ + Get the last commit hash before the datetime of ansible-core's release of TAG. + """ + args = ctx.ensure_object(Args) + _, _, ref = branch_tag_ref(args, branch, tag, None) + print(ref) + + +@app.command(name="mantag") +def mantag_command( + ctx: typer.Context, + tag: str = PARAMS.tag_required, + ref: str = PARAMS.ref, + branch: Optional[str] = PARAMS.branch, + push: bool = True, +) -> None: + """ + Manually tag a release + """ + args = ctx.ensure_object(Args) + triplet = branch_tag_ref(args, branch, tag, ref) + create_tag(args, *triplet, push=push) + + +@app.command(name="tag") +def tag_command( + ctx: typer.Context, + branches: Optional[List[str]] = PARAMS.branches, + push: bool = True, +): + """ + Determine the missing ansible-core releases from `--branch`, create + corresponding tags for each release in the ansible-documentation repo, and + push them. + """ + args = ctx.ensure_object(Args) + branches = branches or list(DEFAULT_ACTIVE_BRANCHES) + triplets: list[BranchTagRef] = [ + branch_tag_ref(args, branch, tag, None) + for branch in branches + for tag in get_new_tags(args, branch) + ] + + for triplet in triplets: + create_tag(args, *triplet, push=push) + + +if __name__ == "__main__": + app() diff --git a/noxfile.py b/noxfile.py index 50f4034d38a..fbb0beb757d 100644 --- a/noxfile.py +++ b/noxfile.py @@ -10,6 +10,7 @@ LINT_FILES: tuple[str, ...] = ( "hacking/pr_labeler/label.py", + "hacking/tagger/tag.py", "noxfile.py", *iglob("docs/bin/*.py"), ) diff --git a/tests/typing.in b/tests/typing.in index 63112a0d90a..5eaee63794a 100644 --- a/tests/typing.in +++ b/tests/typing.in @@ -1,3 +1,4 @@ -r ../hacking/pr_labeler/requirements.txt +-r ../hacking/tagger/requirements.txt mypy nox diff --git a/tests/typing.txt b/tests/typing.txt index 345d3fc9295..c6cce4e8805 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -28,6 +28,10 @@ distlib==0.3.8 # via virtualenv filelock==3.13.1 # via virtualenv +gitdb==4.0.11 + # via gitpython +gitpython==3.1.42 + # via -r tests/../hacking/tagger/requirements.txt idna==3.6 # via requests jinja2==3.1.3 @@ -41,7 +45,9 @@ mypy-extensions==1.0.0 nox==2024.3.2 # via -r tests/typing.in packaging==24.0 - # via nox + # via + # -r tests/../hacking/tagger/requirements.txt + # nox platformdirs==4.2.0 # via virtualenv pycparser==2.21 @@ -54,10 +60,14 @@ pynacl==1.5.0 # via pygithub requests==2.31.0 # via pygithub +smmap==5.0.1 + # via gitdb tomli==2.0.1 # via mypy typer==0.9.0 - # via -r tests/../hacking/pr_labeler/requirements.txt + # via + # -r tests/../hacking/pr_labeler/requirements.txt + # -r tests/../hacking/tagger/requirements.txt typing-extensions==4.10.0 # via # codeowners From b6613f659da3a69484e19aa6a57050bdded9662e Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Wed, 20 Mar 2024 15:48:10 -0400 Subject: [PATCH 230/536] ci: refresh docs build dependencies (#1215) * ci: refresh docs build dependencies * ci: refresh docs build dependencies --------- Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 19 +++++++++++-------- tests/requirements.txt | 6 +++--- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 9dd4127d357..1b0207a460e 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -14,15 +14,17 @@ aiosignal==1.3.1 # via aiohttp alabaster==0.7.16 # via sphinx +annotated-types==0.6.0 + # via pydantic ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-core==2.2.0 +antsibull-core==3.0.0 # via antsibull-docs -antsibull-docs==2.7.0 +antsibull-docs==2.9.0 # via -r tests/requirements-relaxed.in -antsibull-docs-parser==1.0.0 +antsibull-docs-parser==1.0.1 # via antsibull-docs async-timeout==4.0.3 # via aiohttp @@ -69,7 +71,7 @@ multidict==6.0.5 # via # aiohttp # yarl -packaging==23.2 +packaging==24.0 # via # antsibull-core # antsibull-docs @@ -77,10 +79,12 @@ packaging==23.2 # sphinx perky==0.9.2 # via antsibull-core -pydantic==1.10.14 +pydantic==2.6.4 # via # antsibull-core # antsibull-docs +pydantic-core==2.16.3 + # via pydantic pygments==2.17.2 # via # ansible-pygments @@ -105,8 +109,6 @@ semantic-version==2.10.0 # via # antsibull-core # antsibull-docs -sh==1.14.3 - # via antsibull-core six==1.16.0 # via twiggy snowballstemmer==2.2.0 @@ -160,6 +162,7 @@ types-docutils==0.18.3 typing-extensions==4.10.0 # via # pydantic + # pydantic-core # rstcheck urllib3==2.2.1 # via requests @@ -167,5 +170,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==69.1.1 +setuptools==69.2.0 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index 02b1a9b5cf0..052a1c8078d 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -24,7 +24,7 @@ antsibull-docs==2.7.0 # via # -c tests/constraints.in # -r tests/requirements-relaxed.in -antsibull-docs-parser==1.0.0 +antsibull-docs-parser==1.0.1 # via antsibull-docs async-timeout==4.0.3 # via aiohttp @@ -71,7 +71,7 @@ multidict==6.0.5 # via # aiohttp # yarl -packaging==23.2 +packaging==24.0 # via # antsibull-core # antsibull-docs @@ -170,5 +170,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==69.1.1 +setuptools==69.2.0 # via sphinx-intl From e5b359c3a1d8e439ec359efb007751746eed5718 Mon Sep 17 00:00:00 2001 From: Aaron R <57102156+aaronr8684@users.noreply.github.com> Date: Wed, 20 Mar 2024 16:37:57 -0400 Subject: [PATCH 231/536] Update testing_units_modules.rst (#1210) Broken link from - https://rbcs-us.com/documents/Why-Most-Unit-Testing-is-Waste.pdf Which redirected to - https://www.rexblack.com/documents/Why-Most-Unit-Testing-is-Waste.pdf New link to - https://drive.google.com/file/d/1BC67QxdwZ9Y48GAsD8xVxkbqu4znCCHq/view Link found on new domain - https://www.rexblack.com/articles --- docs/docsite/rst/dev_guide/testing_units_modules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/testing_units_modules.rst b/docs/docsite/rst/dev_guide/testing_units_modules.rst index d07dcff9448..9296da6b0e6 100644 --- a/docs/docsite/rst/dev_guide/testing_units_modules.rst +++ b/docs/docsite/rst/dev_guide/testing_units_modules.rst @@ -583,7 +583,7 @@ the code in Ansible to trigger that failure. `Uncle Bob's many videos on YouTube `_ Unit testing is a part of the of various philosophies of software development, including Extreme Programming (XP), Clean Coding. Uncle Bob talks through how to benefit from this - `"Why Most Unit Testing is Waste" `_ + `"Why Most Unit Testing is Waste" `_ An article warning against the costs of unit testing `'A Response to "Why Most Unit Testing is Waste"' `_ An response pointing to how to maintain the value of unit tests From 2db3056cdb5816d7c67486e7537c4403067d5288 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Wed, 20 Mar 2024 15:41:32 -0500 Subject: [PATCH 232/536] Unintended or undocumented functionality may be removed without deprecation (#1209) * Unintended or undocumented functionality may be removed without deprecation * Explain unintended functionality --- .../rst/reference_appendices/release_and_maintenance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 8d2434d55cf..03f0583c5e1 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -408,7 +408,7 @@ Since Ansible is a package of individual collections, the deprecation cycle depe ansible-core deprecation cycle ------------------------------- -The deprecation cycle in ``ansible-core`` is normally across 4 feature releases (2.x. where the x marks a feature release). The feature is normally removed in the 4th release after we announce the deprecation. For example, something deprecated in 2.10 will be removed in 2.13. The tracking is tied to the number of releases, not the release numbering itself. Although this is the standard, there are times where a deprecation cycle for a feature or behavior may have a longer or shorter deprecation cycle based on use or urgency of removal. +The deprecation cycle in ``ansible-core`` is normally across 4 feature releases (2.x. where the x marks a feature release). The feature is normally removed in the 4th release after we announce the deprecation. For example, something deprecated in 2.10 will be removed in 2.13. The tracking is tied to the number of releases, not the release numbering itself. Although this is the standard, there are times where a deprecation cycle for a feature or behavior may have a longer or shorter deprecation cycle based on use or urgency of removal. Unintended or undocumented functionality may be removed without a deprecation cycle. In this context, unintended functionality refers specifically to emergent features that occur outside the release roadmap. .. seealso:: From 5d5e7a56ea31e91372cce5d48a6bf04e2641e7a9 Mon Sep 17 00:00:00 2001 From: Spreadcat Date: Wed, 20 Mar 2024 21:42:24 +0100 Subject: [PATCH 233/536] Update playbooks_advanced_syntax.rst (#1208) Adjusting the intendation to consequently use two whitespaces. Sometimes there were foure in one example, then two again and in one example even both mixed. --- .../playbooks_advanced_syntax.rst | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst index f76260e4e3b..a1327c2e051 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst @@ -28,7 +28,7 @@ In a playbook: --- hosts: all vars: - my_unsafe_variable: !unsafe 'unsafe % value' + my_unsafe_variable: !unsafe 'unsafe % value' tasks: ... @@ -38,11 +38,11 @@ For complex variables such as hashes or arrays, use ``!unsafe`` on the individua --- my_unsafe_array: - - !unsafe 'unsafe element' - - 'safe element' + - !unsafe 'unsafe element' + - 'safe element' my_unsafe_hash: - unsafe_key: !unsafe 'unsafe value' + unsafe_key: !unsafe 'unsafe value' .. _anchors_and_aliases: @@ -57,15 +57,15 @@ You define an anchor with ``&``, then refer to it using an alias, denoted with ` --- ... vars: - app1: - jvm: &jvm_opts - opts: '-Xms1G -Xmx2G' - port: 1000 - path: /usr/lib/app1 + app1: + jvm: &jvm_opts + opts: '-Xms1G -Xmx2G' + port: 1000 + path: /usr/lib/app1 app2: - jvm: - <<: *jvm_opts - path: /usr/lib/app2 + jvm: + <<: *jvm_opts + path: /usr/lib/app2 ... Here, ``app1`` and ``app2`` share the values for ``opts`` and ``port`` using the anchor ``&jvm_opts`` and the alias ``*jvm_opts``. @@ -99,14 +99,14 @@ Now, you can reuse the value of ``app_version`` within the value of ``custom_na hosts: localhost vars: webapp: - version: &my_version 1.0 - custom_name: - - "ToDo_App" - - *my_version + version: &my_version 1.0 + custom_name: + - "ToDo_App" + - *my_version tasks: - name: Using Anchor value ansible.builtin.debug: - msg: My app is called "{{ webapp.custom_name | join('-') }}". + msg: My app is called "{{ webapp.custom_name | join('-') }}". You've anchored the value of ``version`` with the ``&my_version`` anchor and reused it with the ``*my_version`` alias. Anchors and aliases let you access nested values inside dictionaries. From f3c43868a1fd0af03e978ce273b3792e8c39dc14 Mon Sep 17 00:00:00 2001 From: Sutapa Bhattacharjee <129940487+BhattacharjeeSutapa@users.noreply.github.com> Date: Thu, 21 Mar 2024 02:21:04 +0530 Subject: [PATCH 234/536] Cheat sheet instructions for ansible ad-hoc commands (#1171) * add ansible ad-hoc command * change * Update docs/docsite/rst/command_guide/cheatsheet.rst Co-authored-by: Don Naro * Update docs/docsite/rst/command_guide/cheatsheet.rst Co-authored-by: Don Naro * Fix trailing whitespace * change * changed * fix * fix * removed } * rectified * Removed become --------- Co-authored-by: Don Naro --- docs/docsite/rst/command_guide/cheatsheet.rst | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 56eef5802e9..3e9402e3da9 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -31,7 +31,6 @@ Loads ``my_playbook.yml`` from the current working directory and: See :ref:`ansible-playbook` for detailed documentation. - ansible-galaxy ============== @@ -73,7 +72,6 @@ Installing roles - extracting example.role to /home/user/.ansible/roles/example.role - example.role was installed successfully - * List all installed roles: .. code-block:: bash @@ -81,3 +79,29 @@ Installing roles ansible-galaxy role list See :ref:`ansible-galaxy` for detailed documentation. + +ansible +======= + +Running ad-hoc commands +^^^^^^^^^^^^^^^^^^^^^^^ + +* Install a package + +.. code-block:: bash + + ansible localhost -m ansible.builtin.apt -a "name=apache2 state=present" -b -K + +Runs ``ansible localhost``- on your local system. +- ``name=apache2 state=present`` - installs the `apache2` package on a Debian-based system. +- ``-b`` - uses :ref:`become ` to execute with elevated privileges. +- ``-m`` - specifies a module name. +- ``-K`` - prompts for the privilege escalation password. + +.. code-block:: bash + + localhost | SUCCESS => { + "cache_update_time": 1709959287, + "cache_updated": false, + "changed": false + #... From 1d0b46bba51b8b2d3d0ded0a4d439b48038c1fef Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 20 Mar 2024 21:53:26 +0100 Subject: [PATCH 235/536] Document attributes (#1130) * Markup fixes. * option-name is not a field. * Document module attributes. --- .../developing_modules_documenting.rst | 52 ++++++++++++++++--- .../playbook_guide/playbooks_reuse_roles.rst | 4 +- 2 files changed, 48 insertions(+), 8 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index 161b84533f7..9f0271afb9e 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -22,7 +22,7 @@ Every Ansible module written in Python must begin with seven standard sections i Some older Ansible modules have ``imports`` at the bottom of the file, ``Copyright`` notices with the full GPL prefix, and/or ``DOCUMENTATION`` fields in the wrong order. These are legacy files that need updating - do not copy them into new modules. Over time we are updating and correcting older modules. Please follow the guidelines on this page! .. note:: For non-Python modules you still create a ``.py`` file for documentation purposes. Starting at ansible-core 2.14 you can instead choose to create a ``.yml`` file that has the same data structure, but in pure YAML. - With YAML files, the examples below are easy to use by removing Python quoting and substituting ``=`` for ``:``, for example ``DOCUMENTATION = r''' ... '''` ` to ``DOCUMENTATION: ...`` and removing closing quotes. :ref:`adjacent_yaml_doc` + With YAML files, the examples below are easy to use by removing Python quoting and substituting ``=`` for ``:``, for example ``DOCUMENTATION = r''' ... '''`` to ``DOCUMENTATION: ...`` and removing closing quotes. :ref:`adjacent_yaml_doc` .. _shebang: @@ -134,15 +134,16 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require :options: - * Options are often called `parameters` or `arguments`. Because the documentation field is called `options`, we will use that term. + * Options are often called "parameters" or "arguments". Because the documentation field is called ``options``, we will use that term. * If the module has no options (for example, it is a ``_facts`` module), all you need is one line: ``options: {}``. * If your module has options (in other words, accepts arguments), each option should be documented thoroughly. For each module option, include: :option-name: - * Declarative operation (not CRUD), to focus on the final state, for example `online:`, rather than `is_online:`. + * Declarative operation (not CRUD), to focus on the final state, for example ``online:``, rather than ``is_online:``. * The name of the option should be consistent with the rest of the module, as well as other modules in the same category. * When in doubt, look for other modules to find option names that are used for the same purpose, we like to offer consistency to our users. + * (There is no explicit field ``option-name``. This entry is about the *key* of the option in the ``options`` dictionary.) :description: @@ -186,7 +187,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require :version_added: - * Only needed if this option was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field. + * Only needed if this option was extended after initial Ansible release, in other words, this is greater than the top level ``version_added`` field. * This is a string, and not a float, for example, ``version_added: '2.3'``. * In collections, this must be the collection version the option was added to, not the Ansible version. For example, ``version_added: 1.0.0``. @@ -244,11 +245,50 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require * If you use ``ref:`` to link to an anchor that is not associated with a title, you must add a title to the ref for the link to work correctly. +:attributes: + + * A dictionary mapping attribute names to dictionaries describing that attribute. + * Usually attributes are provided by documentation fragments, for example ``ansible.builtin.action_common_attributes`` and its sub-fragments. + Modules and plugins use the appropriate docs fragments and fill in the ``support``, ``details``, and potential attribute-specific other fields. + + :description: + + * A string or a list of strings. Each string is one paragraph. The description is required. + * Explanation of what this attribute does. It should be written in full sentences. + + :details: + + * A string or a list of strings. Each string is one paragraph. + * Describes how support might not work as expected by the user. + * The details are optional in general, but must be provided if ``support`` is ``partial``. + + :support: + + * One of ``full``, ``none``, ``partial``, or ``N/A``. This is required. + * Indicates whether this attribute is supported by this module or plugin. + + :membership: + + * A string or a list of strings. + * Must only be used for the attribute ``action_group``, and must always be specified for that attribute. + * Lists the action groups this module or action is part of. + + :platforms: + + * A string or a list of strings. + * Must only be used for the attribute ``platform``, and must always be specified for that attribute. + * Lists the platforms the module or action supports. + + :version_added: + + * Only needed if this attribute's support was extended after the module/plugin was created, in other words, this is greater than the top level ``version_added`` field. + * This is a string, and not a float, for example, ``version_added: '2.3'``. + * In collections, this must be the collection version the attribute's support was added to, not the Ansible version. For example, ``version_added: 1.0.0``. :notes: * Details of any important information that doesn't fit in one of the above sections. - * For example, whether ``check_mode`` is or is not supported. + * Information on ``check_mode`` or ``diff`` should **not** be listed here, but instead be mentioned in the ``attributes``. .. _module_documents_linking: @@ -430,7 +470,7 @@ Otherwise, for each value returned, provide the following fields. All fields are :sample: One or more examples. :version_added: - Only needed if this return was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field. + Only needed if this return was extended after initial Ansible release, in other words, this is greater than the top level ``version_added`` field. This is a string, and not a float, for example, ``version_added: '2.3'``. :contains: Optional. To describe nested return values, set ``type: dict``, or ``type: list``/``elements: dict``, or if you really have to, ``type: complex``, and repeat the elements above for each sub-field. diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 990cc990334..6083dc15455 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -195,7 +195,7 @@ You can pass other keywords, including variables and tags, when including roles: tags: typeA ... -When you add a :ref:`tag ` to an ``include_role`` task, Ansible applies the tag `only` to the include itself. This means you can pass ``--tags`` to run only selected tasks from the role, if those tasks themselves have the same tag as the include statement. See :ref:`selective_reuse` for details. +When you add a :ref:`tag ` to an ``include_role`` task, Ansible applies the tag **only** to the include itself. This means you can pass ``--tags`` to run only selected tasks from the role, if those tasks themselves have the same tag as the include statement. See :ref:`selective_reuse` for details. You can conditionally include a role: @@ -246,7 +246,7 @@ You can pass other keywords, including variables and tags when importing roles: app_port: 5000 ... -When you add a tag to an ``import_role`` statement, Ansible applies the tag to `all` tasks within the role. See :ref:`tag_inheritance` for details. +When you add a tag to an ``import_role`` statement, Ansible applies the tag to **all** tasks within the role. See :ref:`tag_inheritance` for details. .. _role_argument_spec: From f08e36711fb95709dcabc29d4130306323f89780 Mon Sep 17 00:00:00 2001 From: Zhaohui Mei Date: Thu, 21 Mar 2024 23:00:04 +0800 Subject: [PATCH 236/536] Update developing_modules_general.rst Remove extra characters --- docs/docsite/rst/dev_guide/developing_modules_general.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules_general.rst b/docs/docsite/rst/dev_guide/developing_modules_general.rst index abffcf191c8..be0b5030e00 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general.rst @@ -105,7 +105,7 @@ If your module does not need to target a remote host, you can quickly and easily .. code:: console - ``$ python library/my_test.py /tmp/args.json`` + $ python library/my_test.py /tmp/args.json It should return output like this: From 461eff64e7b6fc05d7b6d6babc1a194aad8b0e94 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 21 Mar 2024 15:49:33 +0000 Subject: [PATCH 237/536] update refs --- docs/docsite/rst/playbook_guide/playbooks_filters.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index 0e1791980fa..6c25eabc377 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -1240,7 +1240,7 @@ These filters help you with common network tasks. .. note:: - These filters have migrated to the `ansible.netcommon `_ collection. Follow the installation instructions to install that collection. + These filters have migrated to the `ansible.utils `_ collection. Follow the installation instructions to install that collection. .. _ipaddr_filter: @@ -1271,7 +1271,7 @@ address. For example, to get the IP address itself from a CIDR, you can use: # => 192.0.2.1 More information about :ansplugin:`ansible.utils.ipaddr#filter` filter and complete usage guide can be found -in :ref:`playbooks_filters_ipaddr`. +in :ref:`plugins_in_ansible.utils`. .. _network_filters: From aa36805208bb735332dc3faf4a0d678f02c5b3a3 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 27 Mar 2024 18:02:02 +0100 Subject: [PATCH 238/536] Add Ansible 9.4.0 porting guide. (#1238) --- docs/docsite/rst/porting_guides/porting_guide_9.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 5d598d03690..836c4629eaf 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -84,6 +84,17 @@ Porting custom scripts Networking ========== +Porting Guide for v9.4.0 +======================== + +Deprecated Features +------------------- + +amazon.aws +~~~~~~~~~~ + +- iam_role_info - in a release after 2026-05-01 paths must begin and end with ``/`` (https://github.com/ansible-collections/amazon.aws/pull/1998). + Porting Guide for v9.3.0 ======================== From d5e5d59cfdaa8d23500ee19217584eb8d87a50ec Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 24 Mar 2024 00:06:29 +0000 Subject: [PATCH 239/536] ci: refresh dev dependencies --- tests/static.txt | 2 +- tests/typing.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index 52f0fdd4873..75cad6da34f 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.3.3 +ruff==0.3.4 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index c6cce4e8805..ca980b6d648 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -64,7 +64,7 @@ smmap==5.0.1 # via gitdb tomli==2.0.1 # via mypy -typer==0.9.0 +typer==0.10.0 # via # -r tests/../hacking/pr_labeler/requirements.txt # -r tests/../hacking/tagger/requirements.txt From f7d28bee05b4d501c14b1716ac7ac1d6e8fbb84c Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 31 Mar 2024 00:06:29 +0000 Subject: [PATCH 240/536] ci: refresh dev dependencies --- tests/typing.txt | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/tests/typing.txt b/tests/typing.txt index ca980b6d648..695e86eb647 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -15,7 +15,7 @@ cffi==1.16.0 charset-normalizer==3.3.2 # via requests click==8.1.7 - # via typer + # via typer-slim codeowners==0.7.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 @@ -26,7 +26,7 @@ deprecated==1.2.14 # via pygithub distlib==0.3.8 # via virtualenv -filelock==3.13.1 +filelock==3.13.3 # via virtualenv gitdb==4.0.11 # via gitpython @@ -36,8 +36,12 @@ idna==3.6 # via requests jinja2==3.1.3 # via -r tests/../hacking/pr_labeler/requirements.txt +markdown-it-py==3.0.0 + # via rich markupsafe==2.1.5 # via jinja2 +mdurl==0.1.2 + # via markdown-it-py mypy==1.9.0 # via -r tests/typing.in mypy-extensions==1.0.0 @@ -50,30 +54,42 @@ packaging==24.0 # nox platformdirs==4.2.0 # via virtualenv -pycparser==2.21 +pycparser==2.22 # via cffi -pygithub==2.2.0 +pygithub==2.3.0 # via -r tests/../hacking/pr_labeler/requirements.txt +pygments==2.17.2 + # via rich pyjwt==2.8.0 # via pygithub pynacl==1.5.0 # via pygithub requests==2.31.0 # via pygithub +rich==13.7.1 + # via typer-slim +shellingham==1.5.4 + # via typer-slim smmap==5.0.1 # via gitdb tomli==2.0.1 # via mypy -typer==0.10.0 +typer==0.12.0 # via # -r tests/../hacking/pr_labeler/requirements.txt # -r tests/../hacking/tagger/requirements.txt +typer-cli==0.12.0 + # via typer +typer-slim==0.12.0 + # via + # typer + # typer-cli typing-extensions==4.10.0 # via # codeowners # mypy # pygithub - # typer + # typer-slim urllib3==2.2.1 # via # pygithub From b77e3cf9085710825fa325b2b61ceace4f306bc8 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 31 Mar 2024 00:10:53 +0000 Subject: [PATCH 241/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 2 +- tests/requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 1b0207a460e..daff9407c6e 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -36,7 +36,7 @@ babel==2.14.0 # via # sphinx # sphinx-intl -build==1.1.1 +build==1.2.1 # via antsibull-core certifi==2024.2.2 # via requests diff --git a/tests/requirements.txt b/tests/requirements.txt index 052a1c8078d..579fd4dd71e 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -36,7 +36,7 @@ babel==2.14.0 # via # sphinx # sphinx-intl -build==1.1.1 +build==1.2.1 # via antsibull-core certifi==2024.2.2 # via requests From 5702bd0c8e0ac27b96f796e543599e8017091097 Mon Sep 17 00:00:00 2001 From: sutapa Date: Thu, 4 Apr 2024 20:21:12 +0530 Subject: [PATCH 242/536] ansible doc --- docs/docsite/rst/command_guide/cheatsheet.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 3e9402e3da9..719bb7e1a0c 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -105,3 +105,22 @@ Runs ``ansible localhost``- on your local system. "cache_updated": false, "changed": false #... + +ansible doc +=========== + Show plugin names and their source files: + +ansible-doc -F +add_host /usr/lib/python3/dist-packages/ansible/modules/add_host.py +amazon.aws.aws_az_facts /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_az_f +amazon.aws.aws_az_info /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_az_i +amazon.aws.aws_caller_facts /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_call +..# + + List available plugins: + +ansible-doc -t module -l +amazon.aws.autoscaling_group Create or delete AWS AutoScaling Groups (ASGs) +amazon.aws.autoscaling_group_info Gather information about EC2 Auto Scaling Groups (ASGs) in AWS +amazon.aws.aws_az_info Gather information about availability zones in AWS +..# \ No newline at end of file From 1bbf1575b07b3ea09c75e7e2fbaa7c99ac91438a Mon Sep 17 00:00:00 2001 From: sutapa Date: Thu, 4 Apr 2024 20:24:24 +0530 Subject: [PATCH 243/536] Change --- docs/docsite/rst/command_guide/cheatsheet.rst | 37 +++++++++++-------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 719bb7e1a0c..0c49e77efe5 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -108,19 +108,24 @@ Runs ``ansible localhost``- on your local system. ansible doc =========== - Show plugin names and their source files: - -ansible-doc -F -add_host /usr/lib/python3/dist-packages/ansible/modules/add_host.py -amazon.aws.aws_az_facts /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_az_f -amazon.aws.aws_az_info /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_az_i -amazon.aws.aws_caller_facts /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_call -..# - - List available plugins: - -ansible-doc -t module -l -amazon.aws.autoscaling_group Create or delete AWS AutoScaling Groups (ASGs) -amazon.aws.autoscaling_group_info Gather information about EC2 Auto Scaling Groups (ASGs) in AWS -amazon.aws.aws_az_info Gather information about availability zones in AWS -..# \ No newline at end of file + +* Show plugin names and their source files: + +.. code-block:: bash + + ansible-doc -F + add_host /usr/lib/python3/dist-packages/ansible/modules/add_host.py + amazon.aws.aws_az_facts /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_az_f + amazon.aws.aws_az_info /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_az_i + amazon.aws.aws_caller_facts /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_call + ..# + +* List available plugins: + +.. code-block:: bash + + ansible-doc -t module -l + amazon.aws.autoscaling_group Create or delete AWS AutoScaling Groups (ASGs) + amazon.aws.autoscaling_group_info Gather information about EC2 Auto Scaling Groups (ASGs) in AWS + amazon.aws.aws_az_info Gather information about availability zones in AWS + ..# \ No newline at end of file From 35598f98a026d7829cd59107a2c8cbf9c3a60666 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 4 Apr 2024 19:37:36 +0100 Subject: [PATCH 244/536] update tagger for 2.17 --- hacking/tagger/tag.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hacking/tagger/tag.py b/hacking/tagger/tag.py index a3e556cb7ec..42d1066dee5 100755 --- a/hacking/tagger/tag.py +++ b/hacking/tagger/tag.py @@ -41,7 +41,7 @@ DEFAULT_ANSIBLE_CORE_CHECKOUT = ROOT.parent.joinpath("ansible") DEFAULT_REMOTE = "origin" -DEFAULT_ACTIVE_BRANCHES: tuple[str, ...] = ("stable-2.14", "stable-2.15", "stable-2.16") +DEFAULT_ACTIVE_BRANCHES: tuple[str, ...] = ("stable-2.15", "stable-2.16", "stable-2.17") def get_tags(repo: git.Repo) -> list[str]: From 09b522a890a390488af755eedbdadbc9c92ed47c Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 4 Apr 2024 19:58:40 +0100 Subject: [PATCH 245/536] Update hacking/tagger/tag.py Co-authored-by: Maxwell G --- hacking/tagger/tag.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hacking/tagger/tag.py b/hacking/tagger/tag.py index 42d1066dee5..40931f8b301 100755 --- a/hacking/tagger/tag.py +++ b/hacking/tagger/tag.py @@ -41,7 +41,7 @@ DEFAULT_ANSIBLE_CORE_CHECKOUT = ROOT.parent.joinpath("ansible") DEFAULT_REMOTE = "origin" -DEFAULT_ACTIVE_BRANCHES: tuple[str, ...] = ("stable-2.15", "stable-2.16", "stable-2.17") +DEFAULT_ACTIVE_BRANCHES: tuple[str, ...] = ("stable-2.14", "stable-2.15", "stable-2.16", "stable-2.17") def get_tags(repo: git.Repo) -> list[str]: From b687378a65b65c4e456a479ded07a85d8d0f46fd Mon Sep 17 00:00:00 2001 From: Don Naro Date: Fri, 5 Apr 2024 16:48:30 +0100 Subject: [PATCH 246/536] format tag.py --- hacking/tagger/tag.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/hacking/tagger/tag.py b/hacking/tagger/tag.py index 40931f8b301..d2067583160 100755 --- a/hacking/tagger/tag.py +++ b/hacking/tagger/tag.py @@ -41,7 +41,12 @@ DEFAULT_ANSIBLE_CORE_CHECKOUT = ROOT.parent.joinpath("ansible") DEFAULT_REMOTE = "origin" -DEFAULT_ACTIVE_BRANCHES: tuple[str, ...] = ("stable-2.14", "stable-2.15", "stable-2.16", "stable-2.17") +DEFAULT_ACTIVE_BRANCHES: tuple[str, ...] = ( + "stable-2.14", + "stable-2.15", + "stable-2.16", + "stable-2.17", +) def get_tags(repo: git.Repo) -> list[str]: From a7f384acf63b107d9684154a21323c2f35dce019 Mon Sep 17 00:00:00 2001 From: sutapa Date: Mon, 8 Apr 2024 19:24:09 +0530 Subject: [PATCH 247/536] edited --- docs/docsite/rst/command_guide/cheatsheet.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 0c49e77efe5..28715ac14dc 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -125,7 +125,7 @@ ansible doc .. code-block:: bash ansible-doc -t module -l - amazon.aws.autoscaling_group Create or delete AWS AutoScaling Groups (ASGs) - amazon.aws.autoscaling_group_info Gather information about EC2 Auto Scaling Groups (ASGs) in AWS + amazon.aws.autoscaling_group Create or delete AWS AutoScaling Groups + amazon.aws.autoscaling_group_info Gather information about EC2 Auto Scaling Groups in AWS amazon.aws.aws_az_info Gather information about availability zones in AWS ..# \ No newline at end of file From cd732e6ac1a5a26ea2ef74b4d0701cf26ce06f85 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 23 Jan 2024 15:35:22 +0000 Subject: [PATCH 248/536] build package docs via gh action --- .github/workflows/build-package-docs.yaml | 99 +++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 .github/workflows/build-package-docs.yaml diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml new file mode 100644 index 00000000000..60a1e60bcb4 --- /dev/null +++ b/.github/workflows/build-package-docs.yaml @@ -0,0 +1,99 @@ +name: Ansible package docs build +on: + workflow_dispatch: + inputs: + github_fork: + description: 'GitHub Fork' + required: true + default: 'ansible' + github_branch: + description: 'GitHub Branch' + required: true + default: 'devel' + language: + type: choice + description: 'Language' + required: true + default: 'english' + options: + - 'english' + - 'japanese' + package_version: + type: choice + description: 'Ansible Version' + required: true + default: 'devel' + options: + - 'devel' + - '9' + - '8' + - '7' + - '6' + - '5' + - '4' + - '3' + - '2.10' + latest_symlink: + type: boolean + description: 'Add latest symlink' + required: true + +jobs: + build-package-docs: + runs-on: ubuntu-latest + env: + PACKAGE_VERSION: "${{ github.event.inputs.package_version }}" + LANGUAGE: ${{ github.event.inputs.language}} + steps: + - name: Checkout Ansible documentation + uses: actions/checkout@v4 + with: + repository: ${{ github.event.inputs.github_fork }}/ansible-documentation + ref: ${{ github.event.inputs.github_branch }} + path: build-directory + + - name: Setup nox + uses: wntrblm/nox@2024.03.02 + + - name: Output Python info + run: python --version --version && which python + + - name: Graft ansible-core + run: nox -s clone-core + working-directory: build-directory + + - name: Install project requirements + run: python -m pip install -r tests/requirements.in -c tests/requirements.txt + working-directory: build-directory + + - name: Set the COLLECTION_LIST variable + run: | + if [ ${PACKAGE_VERSION} == "devel" ]; then + echo COLLECTION_LIST="" >> $GITHUB_ENV + else + echo COLLECTION_LIST="${PACKAGE_VERSION}" >> $GITHUB_ENV + fi + + - name: Set the VERSION variable + run: | + if [ ${LANGUAGE} == "english" ]; then + echo VERSION="${PACKAGE_VERSION}" >> $GITHUB_ENV + elif [ ${LANGUAGE} == "japanese" ]; then + echo VERSION="${PACKAGE_VERSION}_ja" >> $GITHUB_ENV + fi + + - name: Build the docs + run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}" + working-directory: build-directory/docs/docsite + + - name: Create latest symlink + if: ${{ github.event.inputs.latest_symlink == 'true' }} + run: ln -s ${VERSION} _build/latest + working-directory: build-directory/docs/docsite + + - name: Create a downloadable archive of the build output + uses: actions/upload-artifact@v4 + with: + name: package-docs-build + path: build-directory/docs/docsite/_build/html/** + retention-days: 7 From 0563496b25f53b9a8b2ebb1c5ddd3c4a0ba820b1 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 6 Mar 2024 13:10:28 +0000 Subject: [PATCH 249/536] update package version options Co-authored-by: Sandra McCann <30267855+samccann@users.noreply.github.com> --- .github/workflows/build-package-docs.yaml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 60a1e60bcb4..72af767e50d 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -25,14 +25,10 @@ on: default: 'devel' options: - 'devel' + - '10' - '9' - '8' - '7' - - '6' - - '5' - - '4' - - '3' - - '2.10' latest_symlink: type: boolean description: 'Add latest symlink' From a8218d24acfff91b65f9666894f5a0435000844c Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 6 Mar 2024 15:38:53 +0000 Subject: [PATCH 250/536] Update .github/workflows/build-package-docs.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 72af767e50d..7c158794667 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -83,7 +83,7 @@ jobs: working-directory: build-directory/docs/docsite - name: Create latest symlink - if: ${{ github.event.inputs.latest_symlink == 'true' }} + if: github.event.inputs.latest_symlink == 'true' run: ln -s ${VERSION} _build/latest working-directory: build-directory/docs/docsite From 458cd3e64c2ecf830a580752f628ce41bffd7851 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 6 Mar 2024 15:39:12 +0000 Subject: [PATCH 251/536] Update .github/workflows/build-package-docs.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/build-package-docs.yaml | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 7c158794667..6dd0d8f05cb 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -63,12 +63,10 @@ jobs: working-directory: build-directory - name: Set the COLLECTION_LIST variable - run: | - if [ ${PACKAGE_VERSION} == "devel" ]; then - echo COLLECTION_LIST="" >> $GITHUB_ENV - else - echo COLLECTION_LIST="${PACKAGE_VERSION}" >> $GITHUB_ENV - fi + if: env.PACKAGE_VERSION != 'devel' + run: >- + echo COLLECTION_LIST='"${PACKAGE_VERSION}"' + >> "${GITHUB_ENV}" - name: Set the VERSION variable run: | From 18fca868765e75b27e2adb06325de8f7c33e4e6a Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 6 Mar 2024 15:40:54 +0000 Subject: [PATCH 252/536] Update .github/workflows/build-package-docs.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 6dd0d8f05cb..9c1825b8612 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -39,7 +39,7 @@ jobs: runs-on: ubuntu-latest env: PACKAGE_VERSION: "${{ github.event.inputs.package_version }}" - LANGUAGE: ${{ github.event.inputs.language}} + LANGUAGE: ${{ github.event.inputs.language }} steps: - name: Checkout Ansible documentation uses: actions/checkout@v4 From 223cac9be61c44cff197bffd9c68ccfdf2584a03 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 6 Mar 2024 16:06:55 +0000 Subject: [PATCH 253/536] rm quotes --- .github/workflows/build-package-docs.yaml | 28 +++++++++++------------ 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 9c1825b8612..838ab5b35ed 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -3,42 +3,42 @@ on: workflow_dispatch: inputs: github_fork: - description: 'GitHub Fork' + description: GitHub Fork required: true - default: 'ansible' + default: ansible github_branch: - description: 'GitHub Branch' + description: GitHub Branch required: true - default: 'devel' + default: devel language: type: choice - description: 'Language' + description: Language required: true - default: 'english' + default: english options: - - 'english' - - 'japanese' + - english + - japanese package_version: type: choice - description: 'Ansible Version' + description: Ansible Version required: true - default: 'devel' + default: devel options: - - 'devel' + - devel - '10' - '9' - '8' - '7' latest_symlink: type: boolean - description: 'Add latest symlink' + description: Add latest symlink required: true jobs: build-package-docs: runs-on: ubuntu-latest env: - PACKAGE_VERSION: "${{ github.event.inputs.package_version }}" + PACKAGE_VERSION: ${{ github.event.inputs.package_version }} LANGUAGE: ${{ github.event.inputs.language }} steps: - name: Checkout Ansible documentation @@ -77,7 +77,7 @@ jobs: fi - name: Build the docs - run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}" + run: make webdocs ANSIBLE_VERSION=${COLLECTION_LIST} working-directory: build-directory/docs/docsite - name: Create latest symlink From 7fd8a9512a1cdefd13573cd0caad51e54d6d3de5 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 6 Mar 2024 16:10:29 +0000 Subject: [PATCH 254/536] add yaml start and fix indentation --- .github/workflows/build-package-docs.yaml | 84 ++++++++++++----------- 1 file changed, 43 insertions(+), 41 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 838ab5b35ed..e061bf0d148 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -1,3 +1,5 @@ +--- + name: Ansible package docs build on: workflow_dispatch: @@ -41,53 +43,53 @@ jobs: PACKAGE_VERSION: ${{ github.event.inputs.package_version }} LANGUAGE: ${{ github.event.inputs.language }} steps: - - name: Checkout Ansible documentation - uses: actions/checkout@v4 - with: - repository: ${{ github.event.inputs.github_fork }}/ansible-documentation - ref: ${{ github.event.inputs.github_branch }} - path: build-directory + - name: Checkout Ansible documentation + uses: actions/checkout@v4 + with: + repository: ${{ github.event.inputs.github_fork }}/ansible-documentation + ref: ${{ github.event.inputs.github_branch }} + path: build-directory - - name: Setup nox - uses: wntrblm/nox@2024.03.02 + - name: Setup nox + uses: wntrblm/nox@2024.03.02 - - name: Output Python info - run: python --version --version && which python + - name: Output Python info + run: python --version --version && which python - - name: Graft ansible-core - run: nox -s clone-core - working-directory: build-directory + - name: Graft ansible-core + run: nox -s clone-core + working-directory: build-directory - - name: Install project requirements - run: python -m pip install -r tests/requirements.in -c tests/requirements.txt - working-directory: build-directory + - name: Install project requirements + run: python -m pip install -r tests/requirements.in -c tests/requirements.txt + working-directory: build-directory - - name: Set the COLLECTION_LIST variable - if: env.PACKAGE_VERSION != 'devel' - run: >- - echo COLLECTION_LIST='"${PACKAGE_VERSION}"' - >> "${GITHUB_ENV}" + - name: Set the COLLECTION_LIST variable + if: env.PACKAGE_VERSION != 'devel' + run: >- + echo COLLECTION_LIST='"${PACKAGE_VERSION}"' + >> "${GITHUB_ENV}" - - name: Set the VERSION variable - run: | - if [ ${LANGUAGE} == "english" ]; then - echo VERSION="${PACKAGE_VERSION}" >> $GITHUB_ENV - elif [ ${LANGUAGE} == "japanese" ]; then - echo VERSION="${PACKAGE_VERSION}_ja" >> $GITHUB_ENV - fi + - name: Set the VERSION variable + run: | + if [ ${LANGUAGE} == "english" ]; then + echo VERSION="${PACKAGE_VERSION}" >> $GITHUB_ENV + elif [ ${LANGUAGE} == "japanese" ]; then + echo VERSION="${PACKAGE_VERSION}_ja" >> $GITHUB_ENV + fi - - name: Build the docs - run: make webdocs ANSIBLE_VERSION=${COLLECTION_LIST} - working-directory: build-directory/docs/docsite + - name: Build the docs + run: make webdocs ANSIBLE_VERSION=${COLLECTION_LIST} + working-directory: build-directory/docs/docsite - - name: Create latest symlink - if: github.event.inputs.latest_symlink == 'true' - run: ln -s ${VERSION} _build/latest - working-directory: build-directory/docs/docsite + - name: Create latest symlink + if: github.event.inputs.latest_symlink == 'true' + run: ln -s ${VERSION} _build/latest + working-directory: build-directory/docs/docsite - - name: Create a downloadable archive of the build output - uses: actions/upload-artifact@v4 - with: - name: package-docs-build - path: build-directory/docs/docsite/_build/html/** - retention-days: 7 + - name: Create a downloadable archive of the build output + uses: actions/upload-artifact@v4 + with: + name: package-docs-build + path: build-directory/docs/docsite/_build/html/** + retention-days: 7 From 3a81d05ad4e27543a9a8ca26e4e6e1d1379bb7c8 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 6 Mar 2024 16:30:58 +0000 Subject: [PATCH 255/536] split cmd over multiple lines --- .github/workflows/build-package-docs.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index e061bf0d148..724c37f2a48 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -61,7 +61,10 @@ jobs: working-directory: build-directory - name: Install project requirements - run: python -m pip install -r tests/requirements.in -c tests/requirements.txt + run: | + python -m pip install \ + -r tests/requirements.in \ + -c tests/requirements.txt working-directory: build-directory - name: Set the COLLECTION_LIST variable From f39e85ae5b3a07f1f5d5bed60f5e2f6aade221fd Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 7 Mar 2024 10:46:39 +0000 Subject: [PATCH 256/536] use kebab-case for inputs --- .github/workflows/build-package-docs.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 724c37f2a48..922c5404f2a 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -4,11 +4,11 @@ name: Ansible package docs build on: workflow_dispatch: inputs: - github_fork: + github-fork: description: GitHub Fork required: true default: ansible - github_branch: + github-branch: description: GitHub Branch required: true default: devel @@ -20,7 +20,7 @@ on: options: - english - japanese - package_version: + package-version: type: choice description: Ansible Version required: true @@ -31,7 +31,7 @@ on: - '9' - '8' - '7' - latest_symlink: + latest-symlink: type: boolean description: Add latest symlink required: true @@ -40,14 +40,14 @@ jobs: build-package-docs: runs-on: ubuntu-latest env: - PACKAGE_VERSION: ${{ github.event.inputs.package_version }} + PACKAGE_VERSION: ${{ github.event.inputs.package-version }} LANGUAGE: ${{ github.event.inputs.language }} steps: - name: Checkout Ansible documentation uses: actions/checkout@v4 with: - repository: ${{ github.event.inputs.github_fork }}/ansible-documentation - ref: ${{ github.event.inputs.github_branch }} + repository: ${{ github.event.inputs.github-fork }}/ansible-documentation + ref: ${{ github.event.inputs.github-branch }} path: build-directory - name: Setup nox @@ -86,7 +86,7 @@ jobs: working-directory: build-directory/docs/docsite - name: Create latest symlink - if: github.event.inputs.latest_symlink == 'true' + if: github.event.inputs.latest-symlink == 'true' run: ln -s ${VERSION} _build/latest working-directory: build-directory/docs/docsite From 5de8e908143263e351f5a6a0e61ef6d767151f60 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 7 Mar 2024 11:04:45 +0000 Subject: [PATCH 257/536] change input to ansible-package-version --- .github/workflows/build-package-docs.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 922c5404f2a..41835ddc241 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -20,9 +20,9 @@ on: options: - english - japanese - package-version: + ansible-package-version: type: choice - description: Ansible Version + description: Version of the Ansible community package to build required: true default: devel options: @@ -40,7 +40,7 @@ jobs: build-package-docs: runs-on: ubuntu-latest env: - PACKAGE_VERSION: ${{ github.event.inputs.package-version }} + PACKAGE_VERSION: ${{ github.event.inputs.ansible-package-version }} LANGUAGE: ${{ github.event.inputs.language }} steps: - name: Checkout Ansible documentation From c5b1afeebbbb20242fd950972dc2e38b8bf23e69 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 7 Mar 2024 11:09:09 +0000 Subject: [PATCH 258/536] move env to top level --- .github/workflows/build-package-docs.yaml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 41835ddc241..6f890158e63 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -36,12 +36,14 @@ on: description: Add latest symlink required: true + +env: + PACKAGE_VERSION: ${{ github.event.inputs.ansible-package-version }} + LANGUAGE: ${{ github.event.inputs.language }} + jobs: build-package-docs: runs-on: ubuntu-latest - env: - PACKAGE_VERSION: ${{ github.event.inputs.ansible-package-version }} - LANGUAGE: ${{ github.event.inputs.language }} steps: - name: Checkout Ansible documentation uses: actions/checkout@v4 From cdaf2385c29724631ad4c4dd63f584ca059c4d77 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 7 Mar 2024 11:18:12 +0000 Subject: [PATCH 259/536] fix up repository inputs --- .github/workflows/build-package-docs.yaml | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 6f890158e63..8bbeae6f7ca 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -4,12 +4,16 @@ name: Ansible package docs build on: workflow_dispatch: inputs: - github-fork: - description: GitHub Fork + repository-owner: + description: GitHub account or org that owns the repository required: true default: ansible - github-branch: - description: GitHub Branch + repository-name: + description: Name of the GitHub repository + required: true + default: ansible-documentation + repository-branch: + description: Branch, tag, or commit SHA required: true default: devel language: @@ -48,8 +52,8 @@ jobs: - name: Checkout Ansible documentation uses: actions/checkout@v4 with: - repository: ${{ github.event.inputs.github-fork }}/ansible-documentation - ref: ${{ github.event.inputs.github-branch }} + repository: ${{ github.event.inputs.repository-owner }}/${{ github.event.inputs.repository-name }} + ref: ${{ github.event.inputs.repository-branch }} path: build-directory - name: Setup nox From 0aa244c28776cf3e9683e735bd3e797942ac305b Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 7 Mar 2024 11:24:46 +0000 Subject: [PATCH 260/536] create latest symlink and include in tarball --- .github/workflows/build-package-docs.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 8bbeae6f7ca..dee467b74b0 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -87,18 +87,22 @@ jobs: echo VERSION="${PACKAGE_VERSION}_ja" >> $GITHUB_ENV fi - - name: Build the docs + - name: Build the Ansible community package docs run: make webdocs ANSIBLE_VERSION=${COLLECTION_LIST} working-directory: build-directory/docs/docsite - name: Create latest symlink if: github.event.inputs.latest-symlink == 'true' - run: ln -s ${VERSION} _build/latest + run: ln -s "${VERSION}" _build/html/latest working-directory: build-directory/docs/docsite - - name: Create a downloadable archive of the build output + - name: Create a tarball with the build contents + run: tar -zcvf build.tar.gz --directory=_build/html/ . + working-directory: build-directory/docs/docsite + + - name: Create a downloadable archive that contains the tarball uses: actions/upload-artifact@v4 with: name: package-docs-build - path: build-directory/docs/docsite/_build/html/** + path: build-directory/docs/docsite/build.tar.gz retention-days: 7 From 4c364171235131953e5e57622fd851d6a27a67ef Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 3 Apr 2024 09:41:11 +0100 Subject: [PATCH 261/536] Update .github/workflows/build-package-docs.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index dee467b74b0..f54ef737be0 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -82,7 +82,7 @@ jobs: - name: Set the VERSION variable run: | if [ ${LANGUAGE} == "english" ]; then - echo VERSION="${PACKAGE_VERSION}" >> $GITHUB_ENV + echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}" elif [ ${LANGUAGE} == "japanese" ]; then echo VERSION="${PACKAGE_VERSION}_ja" >> $GITHUB_ENV fi From 9d2d0952216b2133ecfbd03d4895b47e5a9988c6 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 3 Apr 2024 09:41:20 +0100 Subject: [PATCH 262/536] Update .github/workflows/build-package-docs.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index f54ef737be0..5841b50d39e 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -84,7 +84,7 @@ jobs: if [ ${LANGUAGE} == "english" ]; then echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}" elif [ ${LANGUAGE} == "japanese" ]; then - echo VERSION="${PACKAGE_VERSION}_ja" >> $GITHUB_ENV + echo VERSION="${PACKAGE_VERSION}_ja" >> "${GITHUB_ENV}" fi - name: Build the Ansible community package docs From 68e308ce2a310f57056ee2e2cdc7e3596f411d09 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 3 Apr 2024 09:42:21 +0100 Subject: [PATCH 263/536] Update .github/workflows/build-package-docs.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 5841b50d39e..7e0c24db928 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -88,7 +88,7 @@ jobs: fi - name: Build the Ansible community package docs - run: make webdocs ANSIBLE_VERSION=${COLLECTION_LIST} + run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}" working-directory: build-directory/docs/docsite - name: Create latest symlink From 67062fc50276f7c2fd46b8eab6912442d8af03e1 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 3 Apr 2024 09:45:41 +0100 Subject: [PATCH 264/536] Update .github/workflows/build-package-docs.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 7e0c24db928..dce655bec69 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -92,7 +92,7 @@ jobs: working-directory: build-directory/docs/docsite - name: Create latest symlink - if: github.event.inputs.latest-symlink == 'true' + if: github.event.inputs.latest-symlink run: ln -s "${VERSION}" _build/html/latest working-directory: build-directory/docs/docsite From 28897705500184a06a6106aaa35b193495a1e4e1 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 8 Apr 2024 16:16:38 +0100 Subject: [PATCH 265/536] Update .github/workflows/build-package-docs.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/build-package-docs.yaml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index dce655bec69..e864be82f09 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -97,7 +97,17 @@ jobs: working-directory: build-directory/docs/docsite - name: Create a tarball with the build contents - run: tar -zcvf build.tar.gz --directory=_build/html/ . + run: >- + tar czvf + --directory=_build/html/ + ansible-package-docs-html-"${PACKAGE_VERSION}"-$(date '+%Y-%m-%d')-${{ + github.run_id + }}-${{ + github.run_number + }}-${{ + github.run_attempt + }}.tar.gz + . working-directory: build-directory/docs/docsite - name: Create a downloadable archive that contains the tarball From 60332eb223fa238645044b04fafed27a85071b4a Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 8 Apr 2024 17:28:19 +0100 Subject: [PATCH 266/536] tar cmd update --- .github/workflows/build-package-docs.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index e864be82f09..f2ecf64ffd4 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -98,8 +98,7 @@ jobs: - name: Create a tarball with the build contents run: >- - tar czvf - --directory=_build/html/ + tar -czvf ansible-package-docs-html-"${PACKAGE_VERSION}"-$(date '+%Y-%m-%d')-${{ github.run_id }}-${{ @@ -107,7 +106,7 @@ jobs: }}-${{ github.run_attempt }}.tar.gz - . + --directory=_build/html/ . working-directory: build-directory/docs/docsite - name: Create a downloadable archive that contains the tarball From c4ab7ae8e6975e3521f7f5bc3bba4c5b30b6fa54 Mon Sep 17 00:00:00 2001 From: sutapa Date: Tue, 9 Apr 2024 12:07:36 +0530 Subject: [PATCH 267/536] change --- docs/docsite/rst/command_guide/cheatsheet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 28715ac14dc..041634b596b 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -106,7 +106,7 @@ Runs ``ansible localhost``- on your local system. "changed": false #... -ansible doc +ansible-doc =========== * Show plugin names and their source files: From 8f7c10017e7ae57812f4731863fe42668d46c776 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1vid=20N=C3=A9meth?= Date: Tue, 9 Apr 2024 13:46:58 +0200 Subject: [PATCH 268/536] feat: remove the "smart option and rewrite the default connection type --- docs/docsite/rst/inventory_guide/intro_inventory.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index a7e5156c94a..4f90024380e 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -582,7 +582,7 @@ Host connection: .. include:: shared_snippets/SSH_password_prompt.txt ansible_connection - Connection type to the host. This can be the name of any Ansible connection plugin. SSH protocol types are ``smart``, ``ssh`` or ``paramiko``. The default is smart. Non-SSH based types are described in the next section. + Connection type to the host. This can be the name of any Ansible connection plugin. SSH protocol types are ``ssh`` or ``paramiko``. The default is ssh. Non-SSH based types are described in the next section. General for all connections: From 9e7ec7a21c4a72be7716d171cd0cca269462fed7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1vid=20N=C3=A9meth?= Date: Tue, 9 Apr 2024 13:47:52 +0200 Subject: [PATCH 269/536] feat: remove depricated smart connection description in connection plugins --- docs/docsite/rst/dev_guide/developing_plugins.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index dce4ed934f4..67f9b6da9ac 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -310,9 +310,7 @@ There are also some tasks which are generated internally and implicitly at vario Connection plugins ------------------ -Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. The most commonly used connection plugins are the ``paramiko`` SSH, native ssh (just called ``ssh``), and ``local`` connection types. All of these can be used in playbooks and with ``/usr/bin/ansible`` to connect to remote machines. - -Ansible version 2.1 introduced the ``smart`` connection plugin. The ``smart`` connection type allows Ansible to automatically select either the ``paramiko`` or ``openssh`` connection plugin based on system capabilities, or the ``ssh`` connection plugin if OpenSSH supports ControlPersist. +Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. The most commonly used connection plugins are the ``paramiko`` SSH, native ssh (just called ``ssh``) and ``local`` connection types. All of these can be used in playbooks and with ``/usr/bin/ansible`` to connect to remote machines. To create a new connection plugin (for example, to support SNMP, Message bus, or other transports), copy the format of one of the existing connection plugins and drop it into ``connection`` directory on your :ref:`local plugin path `. From d2eb89453922b46db916cd596f972efd5d9062d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1vid=20N=C3=A9meth?= Date: Tue, 9 Apr 2024 13:48:53 +0200 Subject: [PATCH 270/536] feat: update the paramiko description --- docs/docsite/rst/reference_appendices/glossary.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst index ce35c16e477..8419834ae12 100644 --- a/docs/docsite/rst/reference_appendices/glossary.rst +++ b/docs/docsite/rst/reference_appendices/glossary.rst @@ -354,12 +354,11 @@ when a term comes up on the mailing list. Ansible orchestration is all about modeling that kind of process. paramiko - By default, Ansible manages machines over SSH. The library that - Ansible uses by default to do this is a Python-powered library called - paramiko. The paramiko library is generally fast and easy to manage, - though users who want to use Kerberos or Jump Hosts may wish to switch - to a native SSH binary such as OpenSSH by specifying the connection - type in their :term:`playbooks`, or using the ``-c ssh`` flag. + By default, Ansible uses native OpenSSH, because it supports ControlPersist. + If your control machine uses an older version of OpenSSH that does not support ControlPersist, + Ansible will fall back to a Python implementation of OpenSSH called 'paramiko'. + The paramiko library is generally fast and easy to manage. To use paramiko + you need to specify the connection type in your :term:`playbooks`, or by using the ``-c paramiko`` flag. Playbooks Playbooks are the language by which Ansible orchestrates, configures, From 33ba56d6c83c0f340484da1dd16610d966c00c64 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 9 Apr 2024 17:31:35 +0200 Subject: [PATCH 271/536] Add Ansible 10.0.0a1 porting guide. (#1260) --- .../rst/porting_guides/porting_guide_10.rst | 399 ++++++++++++++++++ .../rst/porting_guides/porting_guides.rst | 1 + 2 files changed, 400 insertions(+) create mode 100644 docs/docsite/rst/porting_guides/porting_guide_10.rst diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst new file mode 100644 index 00000000000..d4cae3313dd --- /dev/null +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -0,0 +1,399 @@ +.. + THIS DOCUMENT IS AUTOMATICALLY GENERATED BY ANTSIBULL! PLEASE DO NOT EDIT MANUALLY! (YOU PROBABLY WANT TO EDIT porting_guide_core_2.17.rst) + +.. _porting_10_guide: + +======================== +Ansible 10 Porting Guide +======================== + +.. contents:: + :depth: 2 + + +Ansible 10 is based on Ansible-core 2.17. + +We suggest you read this page along with the `Ansible 10 Changelog `_ to understand what updates you may need to make. + +Playbook +======== + +No notable changes + + +Command Line +============ + +No notable changes + + +Deprecated +========== + +No notable changes + + +Modules +======= + +No notable changes + + +Modules removed +--------------- + +The following modules no longer exist: + +* No notable changes + + +Deprecation notices +------------------- + +No notable changes + + +Noteworthy module changes +------------------------- + +No notable changes + + +Plugins +======= + +No notable changes + + +Porting custom scripts +====================== + +No notable changes + + +Networking +========== + +No notable changes + +Porting Guide for v10.0.0a1 +=========================== + +Added Collections +----------------- + +- community.library_inventory_filtering_v1 (version 1.0.0) + +Known Issues +------------ + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_network_attributes - Issue(279049) - If unsupported values are provided for the parameter ``ome_network_attributes``, then this module does not provide a correct error message. +- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. +- ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the following parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. +- ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` +- ome_device_quick_deploy - Issue(275231) - This module does not deploy a new configuration to a slot that has disabled IPv6. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + +Breaking Changes +---------------- + +Ansible-core +~~~~~~~~~~~~ + +- assert - Nested templating may result in an inability for the conditional to be evaluated. See the porting guide for more information. + +cloud.common +~~~~~~~~~~~~ + +- Bump minimum Python supported version to 3.9. +- Remove support for ansible-core < 2.14. + +community.ciscosmb +~~~~~~~~~~~~~~~~~~ + +- in facts of interface 'bandwith' changed to 'bandwidth' + +community.okd +~~~~~~~~~~~~~ + +- Bump minimum Python suupported version to 3.9 (https://github.com/openshift/community.okd/pull/202). +- Remove support for ansible-core < 2.14 (https://github.com/openshift/community.okd/pull/202). + +hetzner.hcloud +~~~~~~~~~~~~~~ + +- Drop support for ansible-core 2.13. +- certificate - The `not_valid_before` and `not_valid_after` values are now returned as ISO-8601 formatted strings. +- certificate_info - The `not_valid_before` and `not_valid_after` values are now returned as ISO-8601 formatted strings. +- inventory - Remove the deprecated `api_token_env` option, you may use the `ansible.builtin.env` lookup as alternative. +- iso_info - The `deprecated` value is now returned as ISO-8601 formatted strings. + +kubernetes.core +~~~~~~~~~~~~~~~ + +- Remove support for ansible-core < 2.14 +- Update python kubernetes library to 24.2.0, helm/kind-action to 1.8.0, kubernetes >= 1.24. + +theforeman.foreman +~~~~~~~~~~~~~~~~~~ + +- content_view_filter - stop managing rules from this module, ``content_view_filter_rule`` should be used for that +- inventory plugin - do not default to ``http://localhost:3000`` as the Foreman URL, providing a URL is now mandatory + +vmware.vmware_rest +~~~~~~~~~~~~~~~~~~ + +- Remove support for ansible-core < 2.14 + +Major Changes +------------- + +Ansible-core +~~~~~~~~~~~~ + +- urls.py - Removed support for Python 2 + +ansible.netcommon +~~~~~~~~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. + +ansible.utils +~~~~~~~~~~~~~ + +- Bumping `netaddr` to `>=0.10.1`, means that starting from this release, the minimum `netaddr` version this collection requires is `>=0.10.1`. +- Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. +- This release mainly addresses the breaking changes in the `netaddr` library. +- With the new release of `netaddr` 1.0.0, the `IPAddress.is_private()` method has been removed and instead, the `IPAddress.is_global()` method has been extended to support the same functionality. This change has been reflected in the `ipaddr` filter plugin. + +arista.eos +~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. +- This release removes previously deprecated modules and attributes from this collection. Please refer to the **Removed Features** section for details. + +cisco.asa +~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. + +cisco.ios +~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. +- ios_ntp - Remove deprecated ntp legacy module + +cisco.iosxr +~~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. +- This release removes previously deprecated module and attributes from this collection. Please refer to the **Removed Features** section for details. + +cisco.nxos +~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. +- This release removes four previously deprecated modules from this collection. Please refer to the **Removed Features** section for details. + +community.docker +~~~~~~~~~~~~~~~~ + +- The ``community.docker`` collection now depends on the ``community.library_inventory_filtering_v1`` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with ``ansible-galaxy collection install``, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugins (https://github.com/ansible-collections/community.docker/pull/698). + +community.hashi_vault +~~~~~~~~~~~~~~~~~~~~~ + +- requirements - the ``requests`` package which is required by ``hvac`` now has a more restrictive range for this collection in certain use cases due to breaking security changes in ``ansible-core`` that were backported (https://github.com/ansible-collections/community.hashi_vault/pull/416). + +community.mysql +~~~~~~~~~~~~~~~ + +- Collection version 2.*.* is EOL, no more bugfixes will be backported. Please consider upgrading to the latest version. + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- All OME modules are enhanced to support the environment variables `OME_USERNAME` and `OME_PASSWORD` as fallback for credentials. +- All iDRAC and Redfish modules are enhanced to support the environment variables `IDRAC_USERNAME` and `IDRAC_PASSWORD` as fallback for credentials. +- idrac_certificates - The module is enhanced to support the import and export of `CUSTOMCERTIFICATE`. +- idrac_diagnostics - The module is introduced to run and export diagnostics on iDRAC. +- idrac_gather_facts - This role is enhanced to support secure boot. +- idrac_license - The module is introduced to configure iDRAC licenses. +- idrac_user - This role is introduced to manage local users of iDRAC. + +dellemc.unity +~~~~~~~~~~~~~ + +- Adding support for Unity Puffin v5.4. + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Add notes for backup modules in the documentation in both monitor and monitor_fact modules. +- Supported new FOS versions 7.4.2 and 7.4.3, and support data type mac_address in the collection. +- Update all the boolean values to true/false in the documents and examples. +- Update the document of log_fact. +- Update the documentation for the supported versions from latest to a fix version number. +- Update the mismatched version message with version ranges. +- Update the required ansible version to 2.14. +- Update the required ansible version to 2.15. +- Update the supported version ranges instead of concrete version numbers to reduce the collection size. + +grafana.grafana +~~~~~~~~~~~~~~~ + +- Add an Ansible role for OpenTelemetry Collector by @ishanjainn in https://github.com/grafana/grafana-ansible-collection/pull/138 + +ibm.qradar +~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. + +infoblox.nios_modules +~~~~~~~~~~~~~~~~~~~~~ + +- Upgrade Ansible version support from 2.13 to 2.16. +- Upgrade Python version support from 3.8 to 3.10. + +junipernetworks.junos +~~~~~~~~~~~~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. +- This release removes previously deprecated modules from this collection. Please refer to the **Removed Features** section for details. + +splunk.es +~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. + +Removed Collections +------------------- + +- community.azure (previously included version: 2.0.0) +- community.sap (previously included version: 2.0.0) +- gluster.gluster (previously included version: 1.0.2) +- hpe.nimble (previously included version: 1.1.4) +- netapp.aws (previously included version: 21.7.1) +- netapp.azure (previously included version: 21.10.1) +- netapp.elementsw (previously included version: 21.7.0) +- netapp.um_info (previously included version: 21.8.1) +- purestorage.fusion (previously included version: 1.6.0) + +Removed Features +---------------- + +- The ``gluster.gluster`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/225). Users can still install this collection with ``ansible-galaxy collection install gluster.gluster``. +- The ``hpe.nimble`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/254). Users can still install this collection with ``ansible-galaxy collection install hpe.nimble``. +- The ``netapp.aws`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/223). Users can still install this collection with ``ansible-galaxy collection install netapp.aws``. +- The ``netapp.azure`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/234). Users can still install this collection with ``ansible-galaxy collection install netapp.azure``. +- The ``netapp.elementsw`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/235). Users can still install this collection with ``ansible-galaxy collection install netapp.elementsw``. +- The ``netapp.um_info`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/244). Users can still install this collection with ``ansible-galaxy collection install netapp.um_info``. +- The deprecated ``community.azure`` collection has been removed. There is a successor collection ``azure.azcollection`` in the community package which should cover the same functionality. +- The deprecated ``community.sap`` collection has been removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/247). There is a successor collection ``community.sap_libs`` in the community package which should cover the same functionality. +- The deprecated ``purestorage.fusion`` collection has been removed (https://forum.ansible.com/t/3712). + +Ansible-core +~~~~~~~~~~~~ + +- Remove deprecated APIs from ansible-docs (https://github.com/ansible/ansible/issues/81716). +- Remove deprecated JINJA2_NATIVE_WARNING environment variable (https://github.com/ansible/ansible/issues/81714) +- Remove deprecated ``scp_if_ssh`` from ssh connection plugin (https://github.com/ansible/ansible/issues/81715). +- Remove deprecated crypt support from ansible.utils.encrypt (https://github.com/ansible/ansible/issues/81717) +- With the removal of Python 2 support, the yum module and yum action plugin are removed and redirected to ``dnf``. + +arista.eos +~~~~~~~~~~ + +- Remove depreacted eos_bgp module which is replaced with eos_bgp_global and eos_bgp_address_family. +- Remove deprecated eos_logging module which is replaced with eos_logging_global resource module. +- Remove deprecated timers.throttle attribute. + +cisco.ios +~~~~~~~~~ + +- Deprecated ios_ntp module in favor of ios_ntp_global. +- Removed previously deprecated ios_bgp module in favor of ios_bgp_global and ios_bgp_address_family. + +cisco.iosxr +~~~~~~~~~~~ + +- Remove deprecated iosxr_logging module which is replaced with iosxr_logging_global resource module. + +cisco.nxos +~~~~~~~~~~ + +- The nxos_logging module has been removed with this release. +- The nxos_ntp module has been removed with this release. +- The nxos_ntp_auth module has been removed with this release. +- The nxos_ntp_options module has been removed with this release. + +junipernetworks.junos +~~~~~~~~~~~~~~~~~~~~~ + +- Remove deprected junos_logging module which is replaced by junos_logging_global resource module. + +Deprecated Features +------------------- + +- The ``inspur.sm`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/2854). +- The ``netapp.storagegrid`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/2811). + +Ansible-core +~~~~~~~~~~~~ + +- Old style vars plugins which use the entrypoints `get_host_vars` or `get_group_vars` are deprecated. The plugin should be updated to inherit from `BaseVarsPlugin` and define a `get_vars` method as the entrypoint. +- The 'required' parameter in 'ansible.module_utils.common.process.get_bin_path' API is deprecated (https://github.com/ansible/ansible/issues/82464). +- ``module_utils`` - importing the following convenience helpers from ``ansible.module_utils.basic`` has been deprecated: ``get_exception``, ``literal_eval``, ``_literal_eval``, ``datetime``, ``signal``, ``types``, ``chain``, ``repeat``, ``PY2``, ``PY3``, ``b``, ``binary_type``, ``integer_types``, ``iteritems``, ``string_types``, ``test_type``, ``map`` and ``shlex_quote``. +- ansible-doc - role entrypoint attributes are deprecated and eventually will no longer be shown in ansible-doc from ansible-core 2.20 on (https://github.com/ansible/ansible/issues/82639, https://github.com/ansible/ansible/pull/82678). +- paramiko connection plugin, configuration items in the global scope are being deprecated and will be removed in favor or the existing same options in the plugin itself. Users should not need to change anything (how to configure them are the same) but plugin authors using the global constants should move to using the plugin's get_option(). + +amazon.aws +~~~~~~~~~~ + +- iam_role_info - in a release after 2026-05-01 paths must begin and end with ``/`` (https://github.com/ansible-collections/amazon.aws/pull/1998). + +community.crypto +~~~~~~~~~~~~~~~~ + +- openssl_csr_pipe, openssl_privatekey_pipe, x509_certificate_pipe - the current behavior of check mode is deprecated and will change in community.crypto 3.0.0. The current behavior is similar to the modules without ``_pipe``: if the object needs to be (re-)generated, only the ``changed`` status is set, but the object is not updated. From community.crypto 3.0.0 on, the modules will ignore check mode and always act as if check mode is not active. This behavior can already achieved now by adding ``check_mode: false`` to the task. If you think this breaks your use-case of this module, please `create an issue in the community.crypto repository `__ (https://github.com/ansible-collections/community.crypto/issues/712, https://github.com/ansible-collections/community.crypto/pull/714). + +community.dns +~~~~~~~~~~~~~ + +- hetzner_dns_records and hosttech_dns_records inventory plugins - the ``filters`` option has been renamed to ``simple_filters``. The old name will stop working in community.hrobot 2.0.0 (https://github.com/ansible-collections/community.dns/pull/181). + +community.docker +~~~~~~~~~~~~~~~~ + +- docker_container - the default ``ignore`` for the ``image_name_mismatch`` parameter has been deprecated and will switch to ``recreate`` in community.docker 4.0.0. A deprecation warning will be printed in situations where the default value is used and where a behavior would change once the default changes (https://github.com/ansible-collections/community.docker/pull/703). + +community.general +~~~~~~~~~~~~~~~~~ + +- consul_acl - the module has been deprecated and will be removed in community.general 10.0.0. ``consul_token`` and ``consul_policy`` can be used instead (https://github.com/ansible-collections/community.general/pull/7901). + +community.hrobot +~~~~~~~~~~~~~~~~ + +- robot inventory plugin - the ``filters`` option has been renamed to ``simple_filters``. The old name will stop working in community.hrobot 2.0.0 (https://github.com/ansible-collections/community.hrobot/pull/94). + +community.okd +~~~~~~~~~~~~~ + +- openshift - the ``openshift`` inventory plugin has been deprecated and will be removed in release 4.0.0 (https://github.com/ansible-collections/kubernetes.core/issues/31). + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- The ``dellemc_idrac_storage_volume`` module is deprecated and replaced with ``idrac_storage_volume``. + +kubernetes.core +~~~~~~~~~~~~~~~ + +- k8s - the ``k8s`` inventory plugin has been deprecated and will be removed in release 4.0.0 (https://github.com/ansible-collections/kubernetes.core/issues/31). diff --git a/docs/docsite/rst/porting_guides/porting_guides.rst b/docs/docsite/rst/porting_guides/porting_guides.rst index a3241c147dd..248636a3cee 100644 --- a/docs/docsite/rst/porting_guides/porting_guides.rst +++ b/docs/docsite/rst/porting_guides/porting_guides.rst @@ -10,6 +10,7 @@ This section lists porting guides that can help you in updating playbooks, plugi :maxdepth: 1 :glob: + porting_guide_10 porting_guide_9 porting_guide_8 porting_guide_7 From 815d52b7545be4c2a0ddaaa74360cef7baadc414 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Sat, 13 Apr 2024 13:31:33 +0200 Subject: [PATCH 272/536] [Needs SC vote before merging] Steering Committee: team membership (#1237) * Steering Committee: team membership * Incorporate feedback * Mention recommended minimum term length. Co-authored-by: Sandra McCann * Extend rotation explanation. --------- Co-authored-by: Felix Fontein Co-authored-by: Sandra McCann --- .../steering/community_steering_committee.rst | 2 ++ .../steering/steering_committee_membership.rst | 10 +++++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index a848cc0e564..7686f159746 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -46,6 +46,8 @@ The following table lists the current Steering Committee members. See :ref:`stee +------------------+---------------+-------------+ | Brian Scholer | briantist | 2022 | +------------------+---------------+-------------+ + | Core Team repr. | See Forum | 2024 | + +------------------+---------------+-------------+ | Dylan Silva | thaumos | 2021 | +------------------+---------------+-------------+ | Felix Fontein | felixfontein | 2021 | diff --git a/docs/docsite/rst/community/steering/steering_committee_membership.rst b/docs/docsite/rst/community/steering/steering_committee_membership.rst index 36db0ab76e2..d566ebbd821 100644 --- a/docs/docsite/rst/community/steering/steering_committee_membership.rst +++ b/docs/docsite/rst/community/steering/steering_committee_membership.rst @@ -18,7 +18,6 @@ This document describes the expectations and policies related to membership in t Expectations of a Steering Committee member ------------------------------------------- - As a Committee member, you agree to: #. Abide by the :ref:`code_of_conduct` in all your interactions with the Community. @@ -42,6 +41,15 @@ A person is eligible to become a Committee member if they have: #. Active contributions to Ansible and/or related projects in any form described in the :ref:`collections_contributions`. #. A consent to follow the :ref:`steering_expectations`. +Team membership +^^^^^^^^^^^^^^^ + +The Committee can accept a team to be a member. +In this case, the team chooses its representative and announces the person in a dedicated `Community Topic `_. +After the announcement is made, the new representative is added to the `SteeringCommittee ` group on the forum, and the previous representative is removed from that group. + +The team uses the same Community Topic for announcing subsequent representative changes. Representatives should commit to at least two months of membership. + Process ^^^^^^^^ From c55805df06cff60b044df8064fdd6f02b4bb0606 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 7 Apr 2024 00:05:50 +0000 Subject: [PATCH 273/536] ci: refresh dev dependencies --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 20 +++++++------------- 3 files changed, 9 insertions(+), 15 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 18d9e417dee..a7bb9b971f5 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -20,5 +20,5 @@ platformdirs==4.2.0 # via black tomli==2.0.1 # via black -typing-extensions==4.10.0 +typing-extensions==4.11.0 # via black diff --git a/tests/static.txt b/tests/static.txt index 75cad6da34f..2e9285d9239 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.3.4 +ruff==0.3.5 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 695e86eb647..34e90b68d97 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -15,7 +15,7 @@ cffi==1.16.0 charset-normalizer==3.3.2 # via requests click==8.1.7 - # via typer-slim + # via typer codeowners==0.7.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 @@ -30,7 +30,7 @@ filelock==3.13.3 # via virtualenv gitdb==4.0.11 # via gitpython -gitpython==3.1.42 +gitpython==3.1.43 # via -r tests/../hacking/tagger/requirements.txt idna==3.6 # via requests @@ -67,29 +67,23 @@ pynacl==1.5.0 requests==2.31.0 # via pygithub rich==13.7.1 - # via typer-slim + # via typer shellingham==1.5.4 - # via typer-slim + # via typer smmap==5.0.1 # via gitdb tomli==2.0.1 # via mypy -typer==0.12.0 +typer==0.12.1 # via # -r tests/../hacking/pr_labeler/requirements.txt # -r tests/../hacking/tagger/requirements.txt -typer-cli==0.12.0 - # via typer -typer-slim==0.12.0 - # via - # typer - # typer-cli -typing-extensions==4.10.0 +typing-extensions==4.11.0 # via # codeowners # mypy # pygithub - # typer-slim + # typer urllib3==2.2.1 # via # pygithub From 962a0dab575e350f162837fe25c26c0efbb4082e Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 14 Apr 2024 00:10:21 +0000 Subject: [PATCH 274/536] ci: refresh dev dependencies --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index a7bb9b971f5..5e1efcba758 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==24.3.0 +black==24.4.0 # via -r tests/formatters.in click==8.1.7 # via black diff --git a/tests/static.txt b/tests/static.txt index 2e9285d9239..e41bbb4854c 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.3.5 +ruff==0.3.7 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 34e90b68d97..429be7fe98d 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -26,13 +26,13 @@ deprecated==1.2.14 # via pygithub distlib==0.3.8 # via virtualenv -filelock==3.13.3 +filelock==3.13.4 # via virtualenv gitdb==4.0.11 # via gitpython gitpython==3.1.43 # via -r tests/../hacking/tagger/requirements.txt -idna==3.6 +idna==3.7 # via requests jinja2==3.1.3 # via -r tests/../hacking/pr_labeler/requirements.txt @@ -74,7 +74,7 @@ smmap==5.0.1 # via gitdb tomli==2.0.1 # via mypy -typer==0.12.1 +typer==0.12.3 # via # -r tests/../hacking/pr_labeler/requirements.txt # -r tests/../hacking/tagger/requirements.txt From b6c75792a1e439bff53ab7af384631163b56497d Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 7 Apr 2024 00:11:16 +0000 Subject: [PATCH 275/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 2 +- tests/requirements.txt | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index daff9407c6e..e8ee94d5966 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -159,7 +159,7 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.10.0 +typing-extensions==4.11.0 # via # pydantic # pydantic-core diff --git a/tests/requirements.txt b/tests/requirements.txt index 579fd4dd71e..2b3774de0cc 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -79,7 +79,7 @@ packaging==24.0 # sphinx perky==0.9.2 # via antsibull-core -pydantic==1.10.14 +pydantic==1.10.15 # via # antsibull-core # antsibull-docs @@ -160,7 +160,7 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.10.0 +typing-extensions==4.11.0 # via # pydantic # rstcheck From bf04632ff464a7348e2670a8adf7a4afb65c3c0d Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 14 Apr 2024 00:13:46 +0000 Subject: [PATCH 276/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 10 +++++----- tests/requirements.txt | 6 +++--- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index e8ee94d5966..450d3bd83f5 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -6,7 +6,7 @@ # aiofiles==23.2.1 # via antsibull-core -aiohttp==3.9.3 +aiohttp==3.9.4 # via # antsibull-core # antsibull-docs @@ -54,7 +54,7 @@ frozenlist==1.4.1 # via # aiohttp # aiosignal -idna==3.6 +idna==3.7 # via # requests # yarl @@ -79,11 +79,11 @@ packaging==24.0 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.6.4 +pydantic==2.7.0 # via # antsibull-core # antsibull-docs -pydantic-core==2.16.3 +pydantic-core==2.18.1 # via pydantic pygments==2.17.2 # via @@ -170,5 +170,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==69.2.0 +setuptools==69.5.1 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index 2b3774de0cc..f431085e085 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -6,7 +6,7 @@ # aiofiles==23.2.1 # via antsibull-core -aiohttp==3.9.3 +aiohttp==3.9.4 # via # antsibull-core # antsibull-docs @@ -54,7 +54,7 @@ frozenlist==1.4.1 # via # aiohttp # aiosignal -idna==3.6 +idna==3.7 # via # requests # yarl @@ -170,5 +170,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==69.2.0 +setuptools==69.5.1 # via sphinx-intl From 29d755add580a9822da561010a032d25d08d7de8 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Mon, 15 Apr 2024 14:51:55 +0200 Subject: [PATCH 277/536] SC: move community_topics_workflow.md to docs.ansible.com (#1257) * SC: move community_topics_workflow.md to docs.ansible.com * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- .../steering/community_steering_committee.rst | 2 +- .../steering/community_topics_workflow.rst | 126 ++++++++++++++++++ .../rst/community/steering/steering_index.rst | 1 + docs/docsite/rst/conf.py | 1 + 4 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 docs/docsite/rst/community/steering/community_topics_workflow.rst diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index 7686f159746..b6192360599 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -101,7 +101,7 @@ Depending on a topic you want to discuss with the Community and the Committee, a Community topics workflow ^^^^^^^^^^^^^^^^^^^^^^^^^ -The Committee uses the `Community-topics workflow `_ to asynchronously discuss and vote on the `community topics `_. +The Committee uses the :ref:`community_topics_workflow` to asynchronously discuss and vote on the `community topics `_. The quorum, the minimum number of Committee members who must vote on a topic in order for a decision to be officially made, is half of the whole number of the Committee members. If the quorum number contains a fractional part, it is rounded up to the next whole number. For example, if there are thirteen members currently in the committee, the quorum will be seven. diff --git a/docs/docsite/rst/community/steering/community_topics_workflow.rst b/docs/docsite/rst/community/steering/community_topics_workflow.rst new file mode 100644 index 00000000000..a35b2f23137 --- /dev/null +++ b/docs/docsite/rst/community/steering/community_topics_workflow.rst @@ -0,0 +1,126 @@ +.. + THIS DOCUMENT IS OWNED BY THE ANSIBLE COMMUNITY STEERING COMMITTEE. ALL CHANGES MUST BE APPROVED BY THE STEERING COMMITTEE! + For small changes (fixing typos, language errors, etc.) create a PR and ping @ansible/steering-committee. + For other changes, create a `community topic `_ to discuss them. + (Creating a draft PR for this file and mentioning it in the community topic is also OK.) + +.. _community_topics_workflow: + +Ansible community topics workflow +================================= + +Overview +-------- + +This document describes the Ansible community topics workflow (herein after ``Workflow``) to provide guidance on successful resolving topics in an asynchronous way. + +The Workflow is a set of actions that need to be done successively within the corresponding time frames. + +.. note:: + + If you have any ideas on how the Workflow can be improved, please create an issue in this repository or pull request against this document. + +Creating a topic +---------------- + +Any person can `create a topic `_ tagged with ``community-wg`` under the ``Project Discussions`` category in the `Ansible Forum `_. A :ref:`Steering Committee member` can tag the forum post with `community-wg-nextmtg` to put it on the meeting agenda. + +Workflow +======== + +.. note:: + + This is a rough scenario and it can vary depending on a topic's complexity and other nuances, for example, when there is a mass agreement upfront. + +Preparation stage +----------------- + +A Committee person checks the topic content and asks the author, or other persons, to provide additional information if needed. + +Discussion stage +---------------- + +* If the topic is ready to be discussed, the Committee person: + + * Adds the ``community-wg-nextmtg`` tag if it needs to be discussed in the meeting. + + * Opens the discussion by adding a comment asking the Community and the Committee to take part in it. + +* No synchronous discussion is needed (there are no blockers, complications, confusion, or impasses). + +Voting stage +------------ + +* Depending on the topic complexity, 1-2 weeks after the discussion was opened, the Committee person formulates vote options based on the prior discussion and gives participants a reasonable amount of time to propose changes to the options (no longer than a week). The person summarizes the options in a comment and also establishes a date when the vote begins if there are no objections about the options or vote date. +* In the vote date, the vote starts with a comment from a Committee person who opens the vote and establishes a date when the vote ends ($CURRENT_DATE + no longer than 21 days; Usually it should not exceed 14 days. 21 days should only be used if it is known that a lot of interested persons will likely not have time to vote in a 14 day period). +* The Committee person labels the topic with the ``active-vote`` tag. +* The Committee person adds ``[Vote ends on $YYYY-MM-DD]`` to the beginning of the topic description. +* A vote is actually two polls, one for the Steering Committee, one for everyone else. To create a vote in a topic: + + * Create a new post in the topic. + + * Click the ``gear`` button in the composer and select ``Build Poll``. + + * Click the ``gear`` in the Poll Builder for advanced mode. + + * Set up the options (generally this will be Single Choice but other poll types can be used). + + * Title it "Steering Committee vote" and "Limit voting" to the ``Steering Committee``. + + * Do not set the close date because it cannot be changed later. + + * Results should be "Always Visible" unless there is some good reason for the SC votes not to be public. + + * Submit the poll (the BBcode will appear in the post) and then repeat the above for the second poll. + + * The title should be "Community vote". + + * No group limitation. + +Voting result stage +------------------- + +* The day after the last day of the vote, the Committee person: + + * Closes the polls. + + * Removes the ``active-vote`` tag. + + * Add a comment that the vote ended. + + * Changes the beginning of the topic's description to ``[Vote ended]``. + + * Creates a summary comment declaring the vote result. + +* The vote result and final decision are announced via the `Bullhorn newsletter `_. + + +Implementation stage +-------------------- + +* If the topic implies some actions (if it does not, just mark this as complete), the Committee person: + + * Assigns the topic to the person who is responsible for performing the actions. + + * Add the ``being-implemented`` tag to the topic. + + * After the topic is implemented, the assignee: + + * Comments on the topic that the work is done. + + * Removes the ``being-implemented`` tag. + + * Add the ``implemented`` tag. + +* If the topic implies actions related to the future Ansible Community package releases (for example, a collection exclusion), the Committee person: + + * Adds the ``scheduled-for-future-release`` tag to the topic. + + * Checks if there is a corresponding milestone in the `ansible-build-data `_ repository. If there is no milestone, the person creates it. + + * Creates an issue in ansible-build-data that references the topic in community-topics, and adds it to the milestone. + +Tools +===== + +We have some `scripts `_ that can be used to create Ansible community announcements in the Bullhorn and similar places. diff --git a/docs/docsite/rst/community/steering/steering_index.rst b/docs/docsite/rst/community/steering/steering_index.rst index 2d5f6306401..877324072b7 100644 --- a/docs/docsite/rst/community/steering/steering_index.rst +++ b/docs/docsite/rst/community/steering/steering_index.rst @@ -18,3 +18,4 @@ This section focuses on the guidelines and membership of the Ansible Community S community_steering_committee steering_committee_membership steering_committee_past_members + community_topics_workflow diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 0557e180dc7..339382948c2 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -142,6 +142,7 @@ 'community/maintainers_guidelines.rst', 'community/maintainers_workflow.rst', 'community/steering/community_steering_committee.rst', + 'community/steering/community_topics_workflow.rst', 'community/steering/steering_committee_membership.rst', 'community/steering/steering_committee_past_members.rst', 'community/steering/steering_index.rst', From 87d8d5b5d40788504c254d58eff3d989bd882c0c Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 16 Apr 2024 07:54:03 +0200 Subject: [PATCH 278/536] community_topics_workflow: fix formatting (#1270) --- .../steering/community_topics_workflow.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/docsite/rst/community/steering/community_topics_workflow.rst b/docs/docsite/rst/community/steering/community_topics_workflow.rst index a35b2f23137..5cc0a0ead50 100644 --- a/docs/docsite/rst/community/steering/community_topics_workflow.rst +++ b/docs/docsite/rst/community/steering/community_topics_workflow.rst @@ -26,19 +26,19 @@ Creating a topic Any person can `create a topic `_ tagged with ``community-wg`` under the ``Project Discussions`` category in the `Ansible Forum `_. A :ref:`Steering Committee member` can tag the forum post with `community-wg-nextmtg` to put it on the meeting agenda. Workflow -======== +-------- .. note:: This is a rough scenario and it can vary depending on a topic's complexity and other nuances, for example, when there is a mass agreement upfront. Preparation stage ------------------ +^^^^^^^^^^^^^^^^^ A Committee person checks the topic content and asks the author, or other persons, to provide additional information if needed. Discussion stage ----------------- +^^^^^^^^^^^^^^^^ * If the topic is ready to be discussed, the Committee person: @@ -49,7 +49,7 @@ Discussion stage * No synchronous discussion is needed (there are no blockers, complications, confusion, or impasses). Voting stage ------------- +^^^^^^^^^^^^ * Depending on the topic complexity, 1-2 weeks after the discussion was opened, the Committee person formulates vote options based on the prior discussion and gives participants a reasonable amount of time to propose changes to the options (no longer than a week). The person summarizes the options in a comment and also establishes a date when the vote begins if there are no objections about the options or vote date. * In the vote date, the vote starts with a comment from a Committee person who opens the vote and establishes a date when the vote ends ($CURRENT_DATE + no longer than 21 days; Usually it should not exceed 14 days. 21 days should only be used if it is known that a lot of interested persons will likely not have time to vote in a 14 day period). @@ -78,7 +78,7 @@ Voting stage * No group limitation. Voting result stage -------------------- +^^^^^^^^^^^^^^^^^^^ * The day after the last day of the vote, the Committee person: @@ -96,7 +96,7 @@ Voting result stage Implementation stage --------------------- +^^^^^^^^^^^^^^^^^^^^ * If the topic implies some actions (if it does not, just mark this as complete), the Committee person: @@ -121,6 +121,6 @@ Implementation stage * Creates an issue in ansible-build-data that references the topic in community-topics, and adds it to the milestone. Tools -===== +----- We have some `scripts `_ that can be used to create Ansible community announcements in the Bullhorn and similar places. From 2116dd5d6eda34106597a6fb190050d3e2609f7e Mon Sep 17 00:00:00 2001 From: Martin Krizek Date: Wed, 17 Apr 2024 08:55:48 +0200 Subject: [PATCH 279/536] ansible-core 2.17 porting guide: remote Python version support See #83054 --- docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst index 4294fbe5525..2b4bf724eaf 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst @@ -25,7 +25,7 @@ No notable changes Command Line ============ -No notable changes +* Python 2.7 and Python 3.6 are no longer supported remote versions. Python 3.7+ is now required for target execution. Deprecated From 2243d4c28cd9a041a2f5728d115b6486938d251d Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 17 Apr 2024 11:50:17 -0400 Subject: [PATCH 280/536] Update playbooks_reuse_roles.rst minor fixes --- .../playbook_guide/playbooks_reuse_roles.rst | 39 +++++++++++++------ 1 file changed, 27 insertions(+), 12 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 6083dc15455..00e096bcc33 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -12,7 +12,7 @@ Roles let you automatically load related vars, files, tasks, handlers, and other Role directory structure ======================== -An Ansible role has a defined directory structure with eight main standard directories. You must include at least one of these directories in each role. You can omit any directories the role does not use. For example: +An Ansible role has a defined directory structure with six main standard directories. You must include at least one of these directories in each role. You can omit any directories the role does not use. For example: .. code-block:: text @@ -23,18 +23,23 @@ An Ansible role has a defined directory structure with eight main standard direc .. include:: shared_snippets/role_directory.txt -By default, Ansible will look in each directory within a role for a ``main.yml`` file for relevant content (also ``main.yaml`` and ``main``): +By default, Ansible will look in most role directories for a ``main.yml`` file for relevant content (also ``main.yaml`` and ``main``): - ``tasks/main.yml`` - the main list of tasks that the role executes. -- ``handlers/main.yml`` - handlers, which may be used within or outside this role. -- ``library/my_module.py`` - modules, which may be used within this role (see :ref:`embedding_modules_and_plugins_in_roles` for more information). -- ``defaults/main.yml`` - default variables for the role (see :ref:`playbooks_variables` for more information). These variables have the lowest priority of any variables available and can be easily overridden by any other variable, including inventory variables. -- ``vars/main.yml`` - other variables for the role (see :ref:`playbooks_variables` for more information). -- ``files/main.yml`` - files that the role deploys. -- ``templates/main.yml`` - templates that the role deploys. -- ``meta/main.yml`` - metadata for the role, including role dependencies and optional Galaxy metadata such as platforms supported. +- ``handlers/main.yml`` - handlers, which are imported into the parent play for use by the role or other roles and tasks in the play. +- ``defaults/main.yml`` - very low precedence values for variables provided by the role (see :ref:`playbooks_variables` for more information). A role's own defaults will take priority over other role's defaults, but any/all other varible sources will override this. +- ``vars/main.yml`` - high precedence variables provided by the role to the play (see :ref:`playbooks_variables` for more information). +- ``files/stuff.txt`` - one or more files that are available for the role and it's children. +- ``templates/something.j2`` - templates to use in the role or child roles. +- ``meta/main.yml`` - metadata for the role, including role dependencies and optional Galaxy metadata such as platforms supported. This is required for uploading into galaxy as a standalone role, but not for using the role in your play. -You can add other YAML files in some directories. For example, you can place platform-specific tasks in separate files and refer to them in the ``tasks/main.yml`` file: +.. note:: + - None of the files above are required for a role. For example, you can just provide ``files/something.txt`` or ``vars/for_import.yml`` and it will still be a valid role. + - On stand alone roles you can also include custom modules and/or plugins, for example ``library/my_module.py`, which may be used within this role (see :ref:`embedding_modules_and_plugins_in_roles` for more information). + - A 'stand alone' role reffers to role that is not part of a collection but their own individualy installable content. + +You can add other YAML files in some directories, but they won't be used by deafult. They can be included/imported directly or specified when using ``include_role/import_role``. +For example, you can place platform-specific tasks in separate files and refer to them in the ``tasks/main.yml`` file: .. code-block:: yaml @@ -59,7 +64,16 @@ You can add other YAML files in some directories. For example, you can place pla name: "apache2" state: present -Roles may also include modules and other plugin types in a directory called ``library``. For more information, please refer to :ref:`embedding_modules_and_plugins_in_roles` below. + +Or call them directly when loading the role: + +.. code-block:: yaml + + - name: include apt tasks + include_role: + tasks_from: apt.yml + when: ansible_facts['os_family'] == 'Debian' + .. _role_search_path: @@ -87,11 +101,12 @@ Alternatively, you can call a role with a fully qualified path: Using roles =========== -You can use roles in three ways: +You can use roles in four ways: - at the play level with the ``roles`` option: This is the classic way of using roles in a play. - at the tasks level with ``include_role``: You can reuse roles dynamically anywhere in the ``tasks`` section of a play using ``include_role``. - at the tasks level with ``import_role``: You can reuse roles statically anywhere in the ``tasks`` section of a play using ``import_role``. +- as a dependency of another role (see the ``dependencies`` keyword in ``meta/main.yml`` in this same page). .. _roles_keyword: From d7f93425178f3d1d3e303cebf644a9dcabd17263 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 17 Apr 2024 11:56:47 -0400 Subject: [PATCH 281/536] Update playbooks_reuse_roles.rst --- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 00e096bcc33..f8e1faaa67d 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -12,7 +12,7 @@ Roles let you automatically load related vars, files, tasks, handlers, and other Role directory structure ======================== -An Ansible role has a defined directory structure with six main standard directories. You must include at least one of these directories in each role. You can omit any directories the role does not use. For example: +An Ansible role has a defined directory structure with seven main standard directories. You must include at least one of these directories in each role. You can omit any directories the role does not use. For example: .. code-block:: text @@ -25,7 +25,7 @@ An Ansible role has a defined directory structure with six main standard directo By default, Ansible will look in most role directories for a ``main.yml`` file for relevant content (also ``main.yaml`` and ``main``): -- ``tasks/main.yml`` - the main list of tasks that the role executes. +- ``tasks/main.yml`` - A list of tasks that the role provides to the play for execution. - ``handlers/main.yml`` - handlers, which are imported into the parent play for use by the role or other roles and tasks in the play. - ``defaults/main.yml`` - very low precedence values for variables provided by the role (see :ref:`playbooks_variables` for more information). A role's own defaults will take priority over other role's defaults, but any/all other varible sources will override this. - ``vars/main.yml`` - high precedence variables provided by the role to the play (see :ref:`playbooks_variables` for more information). @@ -37,6 +37,7 @@ By default, Ansible will look in most role directories for a ``main.yml`` file f - None of the files above are required for a role. For example, you can just provide ``files/something.txt`` or ``vars/for_import.yml`` and it will still be a valid role. - On stand alone roles you can also include custom modules and/or plugins, for example ``library/my_module.py`, which may be used within this role (see :ref:`embedding_modules_and_plugins_in_roles` for more information). - A 'stand alone' role reffers to role that is not part of a collection but their own individualy installable content. + - Variables from ``vars/`` and ``defaults/`` are imported into play scope unless you disable it via the ``public`` option in ``import_role``/``include_role``. You can add other YAML files in some directories, but they won't be used by deafult. They can be included/imported directly or specified when using ``include_role/import_role``. For example, you can place platform-specific tasks in separate files and refer to them in the ``tasks/main.yml`` file: @@ -65,7 +66,7 @@ For example, you can place platform-specific tasks in separate files and refer t state: present -Or call them directly when loading the role: +Or call them directly when loading the role (this bypasses the main.yml files): .. code-block:: yaml From f93f9aefc896bcdee71b5b67108d4e6efd6b89fb Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 17 Apr 2024 11:57:55 -0400 Subject: [PATCH 282/536] Update playbooks_reuse_roles.rst --- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index f8e1faaa67d..716e359c68c 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -72,6 +72,7 @@ Or call them directly when loading the role (this bypasses the main.yml files): - name: include apt tasks include_role: + name: package_manager_bootstrap tasks_from: apt.yml when: ansible_facts['os_family'] == 'Debian' From 2ee69db4d73ec751bdbf460f95ce6aa38c1e219b Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 17 Apr 2024 13:32:38 -0400 Subject: [PATCH 283/536] Update playbooks_reuse_roles.rst --- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 716e359c68c..acc0a9bd58c 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -35,7 +35,7 @@ By default, Ansible will look in most role directories for a ``main.yml`` file f .. note:: - None of the files above are required for a role. For example, you can just provide ``files/something.txt`` or ``vars/for_import.yml`` and it will still be a valid role. - - On stand alone roles you can also include custom modules and/or plugins, for example ``library/my_module.py`, which may be used within this role (see :ref:`embedding_modules_and_plugins_in_roles` for more information). + - On stand alone roles you can also include custom modules and/or plugins, for example ``library/my_module.py``, which may be used within this role (see :ref:`embedding_modules_and_plugins_in_roles` for more information). - A 'stand alone' role reffers to role that is not part of a collection but their own individualy installable content. - Variables from ``vars/`` and ``defaults/`` are imported into play scope unless you disable it via the ``public`` option in ``import_role``/``include_role``. From adb97e4daa2b0d1a155b6707dca0f160d2de2993 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 17 Apr 2024 19:39:10 +0200 Subject: [PATCH 284/536] Bump antsibull-docs to 2.10.0 (#1268) * Bump antsibull-docs to 2.10.0. * Replace sh usage with subprocess. --- .../command_plugins/docs_build.py | 8 ++++++-- tests/constraints.in | 2 +- tests/requirements-relaxed.txt | 9 ++++++++- tests/requirements.txt | 20 ++++++++++++++----- 4 files changed, 30 insertions(+), 9 deletions(-) diff --git a/hacking/build_library/build_ansible/command_plugins/docs_build.py b/hacking/build_library/build_ansible/command_plugins/docs_build.py index bb25fbc7bee..e064bfdddad 100644 --- a/hacking/build_library/build_ansible/command_plugins/docs_build.py +++ b/hacking/build_library/build_ansible/command_plugins/docs_build.py @@ -10,6 +10,7 @@ import os.path import pathlib import shutil +import subprocess from tempfile import TemporaryDirectory import yaml @@ -148,11 +149,14 @@ def generate_core_docs(args): def generate_full_docs(args): """Regenerate the documentation for all plugins listed in the plugin_to_collection_file.""" # imports here so that they don't cause unnecessary deps for all of the plugins - import sh from antsibull_docs.cli import antsibull_docs with TemporaryDirectory() as tmp_dir: - sh.git(['clone', 'https://github.com/ansible-community/ansible-build-data'], _cwd=tmp_dir) + subprocess.run( + ['git', 'clone', 'https://github.com/ansible-community/ansible-build-data'], + check=True, + cwd=tmp_dir, + ) # If we want to validate that the ansible version and ansible-core branch version match, # this would be the place to do it. diff --git a/tests/constraints.in b/tests/constraints.in index f5214993ae2..522d65804a4 100644 --- a/tests/constraints.in +++ b/tests/constraints.in @@ -2,4 +2,4 @@ # and antsibull-docs that production builds rely upon. sphinx == 7.2.5 -antsibull-docs == 2.7.0 # currently approved version +antsibull-docs == 2.10.0 # currently approved version diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 450d3bd83f5..a1428bb532d 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -20,9 +20,11 @@ ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme +antsibull-changelog==0.26.0 + # via antsibull-docs antsibull-core==3.0.0 # via antsibull-docs -antsibull-docs==2.9.0 +antsibull-docs==2.10.0 # via -r tests/requirements-relaxed.in antsibull-docs-parser==1.0.1 # via antsibull-docs @@ -46,6 +48,7 @@ click==8.1.7 # via sphinx-intl docutils==0.18.1 # via + # antsibull-changelog # antsibull-docs # rstcheck # sphinx @@ -73,6 +76,7 @@ multidict==6.0.5 # yarl packaging==24.0 # via + # antsibull-changelog # antsibull-core # antsibull-docs # build @@ -94,6 +98,7 @@ pyproject-hooks==1.0.0 pyyaml==6.0.1 # via # -r tests/requirements-relaxed.in + # antsibull-changelog # antsibull-core # antsibull-docs requests==2.31.0 @@ -104,9 +109,11 @@ rstcheck==5.0.0 # via # -c tests/constraints-base.in # -r tests/requirements-relaxed.in + # antsibull-changelog # antsibull-docs semantic-version==2.10.0 # via + # antsibull-changelog # antsibull-core # antsibull-docs six==1.16.0 diff --git a/tests/requirements.txt b/tests/requirements.txt index f431085e085..f8adba5be81 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -14,13 +14,17 @@ aiosignal==1.3.1 # via aiohttp alabaster==0.7.16 # via sphinx +annotated-types==0.6.0 + # via pydantic ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-core==2.2.0 +antsibull-changelog==0.26.0 # via antsibull-docs -antsibull-docs==2.7.0 +antsibull-core==3.0.0 + # via antsibull-docs +antsibull-docs==2.10.0 # via # -c tests/constraints.in # -r tests/requirements-relaxed.in @@ -46,6 +50,7 @@ click==8.1.7 # via sphinx-intl docutils==0.18.1 # via + # antsibull-changelog # antsibull-docs # rstcheck # sphinx @@ -73,16 +78,19 @@ multidict==6.0.5 # yarl packaging==24.0 # via + # antsibull-changelog # antsibull-core # antsibull-docs # build # sphinx perky==0.9.2 # via antsibull-core -pydantic==1.10.15 +pydantic==2.7.0 # via # antsibull-core # antsibull-docs +pydantic-core==2.18.1 + # via pydantic pygments==2.17.2 # via # ansible-pygments @@ -92,6 +100,7 @@ pyproject-hooks==1.0.0 pyyaml==6.0.1 # via # -r tests/requirements-relaxed.in + # antsibull-changelog # antsibull-core # antsibull-docs requests==2.31.0 @@ -102,13 +111,13 @@ rstcheck==5.0.0 # via # -c tests/constraints-base.in # -r tests/requirements-relaxed.in + # antsibull-changelog # antsibull-docs semantic-version==2.10.0 # via + # antsibull-changelog # antsibull-core # antsibull-docs -sh==1.14.3 - # via antsibull-core six==1.16.0 # via twiggy snowballstemmer==2.2.0 @@ -163,6 +172,7 @@ types-docutils==0.18.3 typing-extensions==4.11.0 # via # pydantic + # pydantic-core # rstcheck urllib3==2.2.1 # via requests From 808ae16796d5ae654becd7b48c6548a84d5b30ad Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Wed, 17 Apr 2024 17:40:08 +0000 Subject: [PATCH 285/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 7 ++++--- tests/requirements.txt | 4 ++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index a1428bb532d..b4b059ae539 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -6,7 +6,7 @@ # aiofiles==23.2.1 # via antsibull-core -aiohttp==3.9.4 +aiohttp==3.9.5 # via # antsibull-core # antsibull-docs @@ -22,7 +22,7 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-changelog==0.26.0 # via antsibull-docs -antsibull-core==3.0.0 +antsibull-core==3.0.1 # via antsibull-docs antsibull-docs==2.10.0 # via -r tests/requirements-relaxed.in @@ -120,7 +120,7 @@ six==1.16.0 # via twiggy snowballstemmer==2.2.0 # via sphinx -sphinx==7.2.6 +sphinx==7.3.5 # via # -r tests/requirements-relaxed.in # antsibull-docs @@ -160,6 +160,7 @@ tomli==2.0.1 # via # build # pyproject-hooks + # sphinx twiggy==0.5.1 # via # antsibull-core diff --git a/tests/requirements.txt b/tests/requirements.txt index f8adba5be81..df913499fc0 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -6,7 +6,7 @@ # aiofiles==23.2.1 # via antsibull-core -aiohttp==3.9.4 +aiohttp==3.9.5 # via # antsibull-core # antsibull-docs @@ -22,7 +22,7 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-changelog==0.26.0 # via antsibull-docs -antsibull-core==3.0.0 +antsibull-core==3.0.1 # via antsibull-docs antsibull-docs==2.10.0 # via From 63376bba0b99e2cc49e2391394d960a6472be07c Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Wed, 17 Apr 2024 17:40:12 +0000 Subject: [PATCH 286/536] ci: refresh dev dependencies --- tests/typing.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/tests/typing.txt b/tests/typing.txt index 429be7fe98d..a3ab6d9d7c5 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/typing.txt --strip-extras tests/typing.in # -argcomplete==3.2.3 +argcomplete==3.3.0 # via nox certifi==2024.2.2 # via requests @@ -46,7 +46,7 @@ mypy==1.9.0 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy -nox==2024.3.2 +nox==2024.4.15 # via -r tests/typing.in packaging==24.0 # via @@ -73,7 +73,9 @@ shellingham==1.5.4 smmap==5.0.1 # via gitdb tomli==2.0.1 - # via mypy + # via + # mypy + # nox typer==0.12.3 # via # -r tests/../hacking/pr_labeler/requirements.txt @@ -88,7 +90,7 @@ urllib3==2.2.1 # via # pygithub # requests -virtualenv==20.25.1 +virtualenv==20.25.3 # via nox wrapt==1.16.0 # via deprecated From 730b6902f8396da2200519cc9a1a6c4788aa7c3c Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 17 Apr 2024 14:35:22 -0400 Subject: [PATCH 287/536] izpell --- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index acc0a9bd58c..180e5818f37 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -27,7 +27,7 @@ By default, Ansible will look in most role directories for a ``main.yml`` file f - ``tasks/main.yml`` - A list of tasks that the role provides to the play for execution. - ``handlers/main.yml`` - handlers, which are imported into the parent play for use by the role or other roles and tasks in the play. -- ``defaults/main.yml`` - very low precedence values for variables provided by the role (see :ref:`playbooks_variables` for more information). A role's own defaults will take priority over other role's defaults, but any/all other varible sources will override this. +- ``defaults/main.yml`` - very low precedence values for variables provided by the role (see :ref:`playbooks_variables` for more information). A role's own defaults will take priority over other role's defaults, but any/all other variable sources will override this. - ``vars/main.yml`` - high precedence variables provided by the role to the play (see :ref:`playbooks_variables` for more information). - ``files/stuff.txt`` - one or more files that are available for the role and it's children. - ``templates/something.j2`` - templates to use in the role or child roles. @@ -36,10 +36,10 @@ By default, Ansible will look in most role directories for a ``main.yml`` file f .. note:: - None of the files above are required for a role. For example, you can just provide ``files/something.txt`` or ``vars/for_import.yml`` and it will still be a valid role. - On stand alone roles you can also include custom modules and/or plugins, for example ``library/my_module.py``, which may be used within this role (see :ref:`embedding_modules_and_plugins_in_roles` for more information). - - A 'stand alone' role reffers to role that is not part of a collection but their own individualy installable content. + - A 'stand alone' role refers to role that is not part of a collection but their own individually installable content. - Variables from ``vars/`` and ``defaults/`` are imported into play scope unless you disable it via the ``public`` option in ``import_role``/``include_role``. -You can add other YAML files in some directories, but they won't be used by deafult. They can be included/imported directly or specified when using ``include_role/import_role``. +You can add other YAML files in some directories, but they won't be used by default. They can be included/imported directly or specified when using ``include_role/import_role``. For example, you can place platform-specific tasks in separate files and refer to them in the ``tasks/main.yml`` file: .. code-block:: yaml From 63d711a37a4db596bb697d90d16a6c448ac38e1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1vid=20N=C3=A9meth?= Date: Thu, 18 Apr 2024 17:00:31 +0200 Subject: [PATCH 288/536] fix: mentioned errors in the pull request --- docs/docsite/rst/dev_guide/developing_plugins.rst | 2 +- docs/docsite/rst/reference_appendices/glossary.rst | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 67f9b6da9ac..99ba3706714 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -310,7 +310,7 @@ There are also some tasks which are generated internally and implicitly at vario Connection plugins ------------------ -Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. The most commonly used connection plugins are the ``paramiko`` SSH, native ssh (just called ``ssh``) and ``local`` connection types. All of these can be used in playbooks and with ``/usr/bin/ansible`` to connect to remote machines. +Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. The most commonly used connection plugins are native ``ssh``, ``paramiko``, and ``local``. All of these can be used with the ``ansible`` executable and in playbooks. To create a new connection plugin (for example, to support SNMP, Message bus, or other transports), copy the format of one of the existing connection plugins and drop it into ``connection`` directory on your :ref:`local plugin path `. diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst index 8419834ae12..1e553757008 100644 --- a/docs/docsite/rst/reference_appendices/glossary.rst +++ b/docs/docsite/rst/reference_appendices/glossary.rst @@ -354,9 +354,7 @@ when a term comes up on the mailing list. Ansible orchestration is all about modeling that kind of process. paramiko - By default, Ansible uses native OpenSSH, because it supports ControlPersist. - If your control machine uses an older version of OpenSSH that does not support ControlPersist, - Ansible will fall back to a Python implementation of OpenSSH called 'paramiko'. + Ansible can use Python SSH implementation called 'paramiko'. The paramiko library is generally fast and easy to manage. To use paramiko you need to specify the connection type in your :term:`playbooks`, or by using the ``-c paramiko`` flag. From 4be2502e225b7a664ad3bb3fb5e619cda4685a1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Thu, 18 Apr 2024 17:05:50 +0200 Subject: [PATCH 289/536] fix: typo in url (ansible#1199) --- docs/docsite/rst/roadmap/ROADMAP_2_7.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/roadmap/ROADMAP_2_7.rst b/docs/docsite/rst/roadmap/ROADMAP_2_7.rst index bf65dcf79fd..d69218d1d50 100644 --- a/docs/docsite/rst/roadmap/ROADMAP_2_7.rst +++ b/docs/docsite/rst/roadmap/ROADMAP_2_7.rst @@ -106,4 +106,4 @@ Modules * `Sources `_ `pr #42790 `_ * `Features `_ `pr #42848 `_ - * `Config `_ `pr #42915 `_ + * `Config `_ `pr #42915 `_ From 28fb9a5f30a6aa15e3d5e1f5f8c2f0f6d7714018 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Thu, 18 Apr 2024 17:24:58 +0200 Subject: [PATCH 290/536] feat: mention ANSIBLE_CONNECTION_PATH (ansible#793) --- docs/docsite/rst/plugins/connection.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index 4fc0d9d0dbb..201dd835f11 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -9,7 +9,7 @@ Connection plugins Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. -By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH`, native ssh (just called :ref:`ssh`), and :ref:`local` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins `. +By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH`, native ssh (just called :ref:`ssh`), and :ref:`local` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins `. To configure these plugins, you might use :ref:`ANSIBLE_CONNECTION_PATH` option. The basics of these connection types are covered in the :ref:`getting started` section. From 5b67c4a212dca234495b67ddda81000dbfa1000e Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 18 Apr 2024 11:26:33 -0400 Subject: [PATCH 291/536] Apply suggestions from code review Co-authored-by: Don Naro --- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 180e5818f37..05b86f213c4 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -26,7 +26,7 @@ An Ansible role has a defined directory structure with seven main standard direc By default, Ansible will look in most role directories for a ``main.yml`` file for relevant content (also ``main.yaml`` and ``main``): - ``tasks/main.yml`` - A list of tasks that the role provides to the play for execution. -- ``handlers/main.yml`` - handlers, which are imported into the parent play for use by the role or other roles and tasks in the play. +- ``handlers/main.yml`` - handlers that are imported into the parent play for use by the role or other roles and tasks in the play. - ``defaults/main.yml`` - very low precedence values for variables provided by the role (see :ref:`playbooks_variables` for more information). A role's own defaults will take priority over other role's defaults, but any/all other variable sources will override this. - ``vars/main.yml`` - high precedence variables provided by the role to the play (see :ref:`playbooks_variables` for more information). - ``files/stuff.txt`` - one or more files that are available for the role and it's children. @@ -36,7 +36,7 @@ By default, Ansible will look in most role directories for a ``main.yml`` file f .. note:: - None of the files above are required for a role. For example, you can just provide ``files/something.txt`` or ``vars/for_import.yml`` and it will still be a valid role. - On stand alone roles you can also include custom modules and/or plugins, for example ``library/my_module.py``, which may be used within this role (see :ref:`embedding_modules_and_plugins_in_roles` for more information). - - A 'stand alone' role refers to role that is not part of a collection but their own individually installable content. + - A 'stand alone' role refers to role that is not part of a collection but as individually installable content. - Variables from ``vars/`` and ``defaults/`` are imported into play scope unless you disable it via the ``public`` option in ``import_role``/``include_role``. You can add other YAML files in some directories, but they won't be used by default. They can be included/imported directly or specified when using ``include_role/import_role``. @@ -66,7 +66,7 @@ For example, you can place platform-specific tasks in separate files and refer t state: present -Or call them directly when loading the role (this bypasses the main.yml files): +Or call those tasks directly when loading the role, which bypasses the ``main.yml`` files: .. code-block:: yaml @@ -103,7 +103,7 @@ Alternatively, you can call a role with a fully qualified path: Using roles =========== -You can use roles in four ways: +You can use roles in the following ways: - at the play level with the ``roles`` option: This is the classic way of using roles in a play. - at the tasks level with ``include_role``: You can reuse roles dynamically anywhere in the ``tasks`` section of a play using ``include_role``. From fc2d6dce3853f220d9350cadf1061528384a34d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1vid=20N=C3=A9meth?= Date: Thu, 18 Apr 2024 17:37:26 +0200 Subject: [PATCH 292/536] fix: add new example of the modules to clarify usage --- .../playbooks_module_defaults.rst | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst b/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst index 3a4bdfc31f8..918d34ecd2c 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst @@ -154,22 +154,24 @@ In a playbook, you can set module defaults for whole groups of modules, such as In ansible-core 2.12, collections can define their own groups in the ``meta/runtime.yml`` file. ``module_defaults`` does not take the ``collections`` keyword into account, so the fully qualified group name must be used for new groups in ``module_defaults``. -Here is an example ``runtime.yml`` file for a collection and a sample playbook using the group. +Here is an example ``runtime.yml`` file for the ``ns.coll`` collection defining an action group ``ns.coll.my_group`` and placing the ``sample_module`` from ``ns.coll`` and ``another_module`` from ``another.collection`` into it. .. code-block:: YAML # collections/ansible_collections/ns/coll/meta/runtime.yml action_groups: - groupname: - - module - - another.collection.module + my_group: + - sample_module + - another.collection.another_module + +This group can now be used in a playbook like this: .. code-block:: YAML - - hosts: localhost - module_defaults: - group/ns.coll.groupname: - option_name: option_value - tasks: - - ns.coll.module: - - another.collection.module + - hosts: localhost + module_defaults: + group/ns.coll.my_group: + option_name: option_value + tasks: + - ns.coll.sample_module: + - another.collection.another_module: \ No newline at end of file From d863f587c50b3616c92235ec2aa63fde6f78760e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1vid=20N=C3=A9meth?= Date: Thu, 18 Apr 2024 18:39:10 +0200 Subject: [PATCH 293/536] fix: reformat sentence, check intendations with yamllint --- .../rst/playbook_guide/playbooks_module_defaults.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst b/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst index 918d34ecd2c..abfe61574d0 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_module_defaults.rst @@ -154,12 +154,13 @@ In a playbook, you can set module defaults for whole groups of modules, such as In ansible-core 2.12, collections can define their own groups in the ``meta/runtime.yml`` file. ``module_defaults`` does not take the ``collections`` keyword into account, so the fully qualified group name must be used for new groups in ``module_defaults``. -Here is an example ``runtime.yml`` file for the ``ns.coll`` collection defining an action group ``ns.coll.my_group`` and placing the ``sample_module`` from ``ns.coll`` and ``another_module`` from ``another.collection`` into it. +Here is an example ``runtime.yml`` file for the ``ns.coll`` collection. +This file defines an action group named ``ns.coll.my_group`` and places the ``sample_module`` from ``ns.coll`` and ``another_module`` from ``another.collection`` into the group. .. code-block:: YAML - # collections/ansible_collections/ns/coll/meta/runtime.yml - action_groups: + # collections/ansible_collections/ns/coll/meta/runtime.yml + action_groups: my_group: - sample_module - another.collection.another_module From 5b17f8f3cac6fda7d7a9ef6cf91d957e5b2c9a10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1vid=20N=C3=A9meth?= Date: Thu, 18 Apr 2024 18:50:59 +0200 Subject: [PATCH 294/536] fix: use backticks, all sentences on a new line --- docs/docsite/rst/reference_appendices/glossary.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst index 1e553757008..a2cf6bc559c 100644 --- a/docs/docsite/rst/reference_appendices/glossary.rst +++ b/docs/docsite/rst/reference_appendices/glossary.rst @@ -354,9 +354,9 @@ when a term comes up on the mailing list. Ansible orchestration is all about modeling that kind of process. paramiko - Ansible can use Python SSH implementation called 'paramiko'. - The paramiko library is generally fast and easy to manage. To use paramiko - you need to specify the connection type in your :term:`playbooks`, or by using the ``-c paramiko`` flag. + Ansible can use a Python SSH implementation called ``paramiko``. + The paramiko library is generally fast and easy to manage. + To use paramiko you need to specify the connection type in your :term:`playbooks`, or by using the ``-c paramiko`` flag. Playbooks Playbooks are the language by which Ansible orchestrates, configures, From 1f1f7d314259de844018a8090957dd3210a737f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C3=A1vid=20N=C3=A9meth?= Date: Thu, 18 Apr 2024 18:51:31 +0200 Subject: [PATCH 295/536] fix: highlight ssh, remove unnecessary sentence --- docs/docsite/rst/inventory_guide/intro_inventory.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index 4f90024380e..0a3300f061c 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -582,7 +582,7 @@ Host connection: .. include:: shared_snippets/SSH_password_prompt.txt ansible_connection - Connection type to the host. This can be the name of any Ansible connection plugin. SSH protocol types are ``ssh`` or ``paramiko``. The default is ssh. Non-SSH based types are described in the next section. + Connection type to the host. This can be the name of any Ansible connection plugin. SSH protocol types are ``ssh`` or ``paramiko``. The default is ``ssh``. General for all connections: From ae9cc54e82db48737a0dff8103c922c42b5d00d0 Mon Sep 17 00:00:00 2001 From: montu2606 <110610160+montu2606@users.noreply.github.com> Date: Fri, 19 Apr 2024 21:39:08 +0530 Subject: [PATCH 296/536] Update playbooks_blocks.rst (#1190) In rescue block we are looking for 'Do Something' , but the task name is 'do something' . Due to the case difference, rescue is getting skipped as condition is not getting met --- docs/docsite/rst/playbook_guide/playbooks_blocks.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst index 795c6d9525c..e60d50853ee 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst @@ -192,7 +192,7 @@ These can be inspected in the ``rescue`` section: tasks: - name: Attempt and graceful roll back demo block: - - name: Do something + - name: Do Something ansible.builtin.shell: grep $(whoami) /etc/hosts - name: Force a failure, if previous one succeeds From 7f4079fc1f19cdd87ab48dbe7e2ad408fc7284c2 Mon Sep 17 00:00:00 2001 From: Ondrej Nemec Date: Sat, 20 Apr 2024 18:44:10 +0200 Subject: [PATCH 297/536] docs: example with changed_when: true (#1167) --- .../rst/playbook_guide/playbooks_error_handling.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst index d0a134bf8d9..641da6cb7ed 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst @@ -156,6 +156,15 @@ Ansible lets you define when a particular task has "changed" a remote node using ansible.builtin.shell: wall 'beep' changed_when: False +If you want to report change all the time, use ``changed_when: True``. + +.. code-block:: yaml + + - name: This task will always report 'changed' status + ansible.builtin.command: /path/to/command + changed_when: True + + You can also combine multiple conditions to override "changed" result. .. code-block:: yaml From 0467807e2304a3dcdace4865f5d4c7f8b4d8588c Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 21 Apr 2024 00:06:07 +0000 Subject: [PATCH 298/536] ci: refresh dev dependencies --- tests/static.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/static.txt b/tests/static.txt index e41bbb4854c..9d83c82bd2b 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.3.7 +ruff==0.4.1 # via -r tests/static.in From abcb523b20556790bbdfd726a58fe9cffd595a54 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 21 Apr 2024 00:10:28 +0000 Subject: [PATCH 299/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index b4b059ae539..96fcc7bf6b9 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -120,7 +120,7 @@ six==1.16.0 # via twiggy snowballstemmer==2.2.0 # via sphinx -sphinx==7.3.5 +sphinx==7.3.7 # via # -r tests/requirements-relaxed.in # antsibull-docs @@ -134,7 +134,7 @@ sphinx-ansible-theme==0.10.3 # via -r tests/requirements-relaxed.in sphinx-copybutton==0.5.2 # via -r tests/requirements-relaxed.in -sphinx-intl==2.1.0 +sphinx-intl==2.2.0 # via -r tests/requirements-relaxed.in sphinx-notfound-page==1.0.0 # via -r tests/requirements-relaxed.in diff --git a/tests/requirements.txt b/tests/requirements.txt index df913499fc0..6e7daafc6a9 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -137,7 +137,7 @@ sphinx-ansible-theme==0.10.3 # via -r tests/requirements-relaxed.in sphinx-copybutton==0.5.2 # via -r tests/requirements-relaxed.in -sphinx-intl==2.1.0 +sphinx-intl==2.2.0 # via -r tests/requirements-relaxed.in sphinx-notfound-page==1.0.0 # via -r tests/requirements-relaxed.in From f5b909c854cfc52057566687eac5ec90aa0ef1a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Sun, 21 Apr 2024 19:07:15 +0200 Subject: [PATCH 300/536] ffeat: Relative path tip --- .../rst/tips_tricks/ansible_tips_tricks.rst | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index defa5c194bc..ca283f5a347 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -117,6 +117,31 @@ There is no limit to the number of variable and vault files or their names. Note that using this strategy in your inventory still requires *all vault passwords to be available* (for example for ``ansible-playbook`` or `AWX/Ansible Tower `_) when run with that inventory. +Use relative paths in your playbooks +------------------------------------ + +To make reorganising your files more convenient, you can use relative paths for referenced files in your playbooks. +The global Ansible variables might help determine the relative paths, as the example below demonstrates. + +The example expects the ``ansible.cfg`` file to be in the root of the folder. + +#. Set the following variables for the `all` group: + +.. code-block:: yaml + ansible_repo_path: "{{ ansible_config_file[:-11] }}" + files_path: "{{ ansible_repo_path }}/playbooks/files" + templates_path: "{{ ansible_repo_path }}/playbooks/templates" + tasks_path: "{{ ansible_repo_path }}/playbooks/tasks" + vaults_path: "{{ ansible_repo_path }}/playbooks/vaults" + +#. Use these variables to reference a file (``playbooks/files/foo.conf``) as follows. + +.. code-block:: yaml + - name: File copy + ansible.builtin.copy: + src: {{ files_path }}/foo.conf + dest: /etc/foo.conf + .. _execution_tips: Execution tricks From 8d0968caa903fc544487fda93db6519b9c4f09dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Sun, 21 Apr 2024 19:16:29 +0200 Subject: [PATCH 301/536] typo fix --- docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index ca283f5a347..2c72454ff0f 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -117,11 +117,11 @@ There is no limit to the number of variable and vault files or their names. Note that using this strategy in your inventory still requires *all vault passwords to be available* (for example for ``ansible-playbook`` or `AWX/Ansible Tower `_) when run with that inventory. -Use relative paths in your playbooks +Use absolute paths in your playbooks ------------------------------------ -To make reorganising your files more convenient, you can use relative paths for referenced files in your playbooks. -The global Ansible variables might help determine the relative paths, as the example below demonstrates. +To make reorganising your files more convenient, you can use absolute paths for referenced files in your playbooks. +The global Ansible variables might help determine the absolute paths, as the example below demonstrates. The example expects the ``ansible.cfg`` file to be in the root of the folder. From 7d9a625a5ff716590255f9835a8efabd9a0c12fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Sun, 21 Apr 2024 19:31:31 +0200 Subject: [PATCH 302/536] syntax fix --- docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index 2c72454ff0f..bc2b64cb2ed 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -120,7 +120,7 @@ Note that using this strategy in your inventory still requires *all vault passwo Use absolute paths in your playbooks ------------------------------------ -To make reorganising your files more convenient, you can use absolute paths for referenced files in your playbooks. +To make reorganizing your files more convenient, you can use absolute paths for referenced files in your playbooks. The global Ansible variables might help determine the absolute paths, as the example below demonstrates. The example expects the ``ansible.cfg`` file to be in the root of the folder. @@ -128,6 +128,7 @@ The example expects the ``ansible.cfg`` file to be in the root of the folder. #. Set the following variables for the `all` group: .. code-block:: yaml + ansible_repo_path: "{{ ansible_config_file[:-11] }}" files_path: "{{ ansible_repo_path }}/playbooks/files" templates_path: "{{ ansible_repo_path }}/playbooks/templates" @@ -137,6 +138,7 @@ The example expects the ``ansible.cfg`` file to be in the root of the folder. #. Use these variables to reference a file (``playbooks/files/foo.conf``) as follows. .. code-block:: yaml + - name: File copy ansible.builtin.copy: src: {{ files_path }}/foo.conf From 584ee0ee703156b48c88c8dce0ab4e56d93a0282 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 22 Apr 2024 06:47:22 +0000 Subject: [PATCH 303/536] Bump wntrblm/nox from 2024.03.02 to 2024.04.15 Bumps [wntrblm/nox](https://github.com/wntrblm/nox) from 2024.03.02 to 2024.04.15. - [Release notes](https://github.com/wntrblm/nox/releases) - [Changelog](https://github.com/wntrblm/nox/blob/main/CHANGELOG.md) - [Commits](https://github.com/wntrblm/nox/compare/2024.03.02...2024.04.15) --- updated-dependencies: - dependency-name: wntrblm/nox dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- .github/workflows/build-package-docs.yaml | 2 +- .github/workflows/reusable-nox.yml | 2 +- .github/workflows/reusable-pip-compile.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index f2ecf64ffd4..3282249d9cc 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -57,7 +57,7 @@ jobs: path: build-directory - name: Setup nox - uses: wntrblm/nox@2024.03.02 + uses: wntrblm/nox@2024.04.15 - name: Output Python info run: python --version --version && which python diff --git a/.github/workflows/reusable-nox.yml b/.github/workflows/reusable-nox.yml index 6a96b993097..bf8ac66ab75 100644 --- a/.github/workflows/reusable-nox.yml +++ b/.github/workflows/reusable-nox.yml @@ -28,7 +28,7 @@ jobs: - name: Check out repo uses: actions/checkout@v4 - name: Setup nox - uses: wntrblm/nox@2024.03.02 + uses: wntrblm/nox@2024.04.15 with: python-versions: "${{ matrix.python-versions }}" - name: Graft ansible-core diff --git a/.github/workflows/reusable-pip-compile.yml b/.github/workflows/reusable-pip-compile.yml index 6242748cf7b..0fcae147eec 100644 --- a/.github/workflows/reusable-pip-compile.yml +++ b/.github/workflows/reusable-pip-compile.yml @@ -53,7 +53,7 @@ jobs: run: | python docs/bin/clone-core.py - name: Set up nox - uses: wntrblm/nox@2024.03.02 + uses: wntrblm/nox@2024.04.15 with: python-versions: "3.9" - name: Set up git committer From 9bc241ef4180a93b44ea8bcb6768d649cdc908fc Mon Sep 17 00:00:00 2001 From: Ondrej Nemec Date: Mon, 22 Apr 2024 09:53:41 +0200 Subject: [PATCH 304/536] docs: referencing defining-changed in playbooks_handlers (#1167) --- docs/docsite/rst/playbook_guide/playbooks_handlers.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst index 4d7c2d00a7a..9dc9d9f7d87 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst @@ -5,6 +5,10 @@ Handlers: running operations on change Sometimes you want a task to run only when a change is made on a machine. For example, you may want to restart a service if a task updates the configuration of that service, but not if the configuration is unchanged. Ansible uses handlers to address this use case. Handlers are tasks that only run when notified. +.. note:: + + Ansible sets "changed" status implicitely, but you can also define the rules using ``changed_when``. See :ref:`override_the_changed_result` to determine it explicitely. + .. contents:: :local: From 2700fd0730d34d32bf69f48a44ed6f26c6cd09b5 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 22 Apr 2024 10:11:47 +0100 Subject: [PATCH 305/536] fixes name of the upload artifact --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 3282249d9cc..6690888b52c 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -113,5 +113,5 @@ jobs: uses: actions/upload-artifact@v4 with: name: package-docs-build - path: build-directory/docs/docsite/build.tar.gz + path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz retention-days: 7 From e92e87a0334a27a2f0f7f6dd826b263ce1bd2d94 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 22 Apr 2024 11:49:54 +0100 Subject: [PATCH 306/536] Update docs/docsite/rst/dev_guide/developing_plugins.rst Co-authored-by: Maxwell G --- docs/docsite/rst/dev_guide/developing_plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 99ba3706714..cf29d066be7 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -310,7 +310,7 @@ There are also some tasks which are generated internally and implicitly at vario Connection plugins ------------------ -Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. The most commonly used connection plugins are native ``ssh``, ``paramiko``, and ``local``. All of these can be used with the ``ansible`` executable and in playbooks. +Connection plugins allow Ansible to connect to target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. The most commonly used connection plugins are native ``ssh``, ``paramiko``, and ``local``. All of these can be used with ad-hoc tasks and in playbooks. To create a new connection plugin (for example, to support SNMP, Message bus, or other transports), copy the format of one of the existing connection plugins and drop it into ``connection`` directory on your :ref:`local plugin path `. From edb1a707cb1c7af641c11e608a0c25b448db9798 Mon Sep 17 00:00:00 2001 From: Ondrej Nemec Date: Mon, 22 Apr 2024 14:46:32 +0200 Subject: [PATCH 307/536] docs: wording (#1167) --- docs/docsite/rst/playbook_guide/playbooks_handlers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst index 9dc9d9f7d87..dbb58d3b1d6 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst @@ -7,7 +7,7 @@ Sometimes you want a task to run only when a change is made on a machine. For ex .. note:: - Ansible sets "changed" status implicitely, but you can also define the rules using ``changed_when``. See :ref:`override_the_changed_result` to determine it explicitely. + Ansible sets "changed" status by itself, but you can also define the rules using ``changed_when``. See :ref:`override_the_changed_result` to determine it explicitely. .. contents:: :local: From ebfd9e838f625124ff91a8daf57369fa76e0f33f Mon Sep 17 00:00:00 2001 From: Ondrej Nemec Date: Mon, 22 Apr 2024 15:01:23 +0200 Subject: [PATCH 308/536] fix: spelling (#1167) --- docs/docsite/rst/playbook_guide/playbooks_handlers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst index dbb58d3b1d6..6502036673f 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst @@ -7,7 +7,7 @@ Sometimes you want a task to run only when a change is made on a machine. For ex .. note:: - Ansible sets "changed" status by itself, but you can also define the rules using ``changed_when``. See :ref:`override_the_changed_result` to determine it explicitely. + Ansible sets "changed" status by itself, but you can also define the rules using ``changed_when``. See :ref:`override_the_changed_result` to determine it explicitly. .. contents:: :local: From f2c60083362e9c6c767577129f73086d2b35416e Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 22 Apr 2024 23:59:57 +0100 Subject: [PATCH 309/536] ci pip-compile-dev: add backport-2.17 label to PRs (#1310) --- .github/workflows/pip-compile-dev.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pip-compile-dev.yml b/.github/workflows/pip-compile-dev.yml index 9d356635931..c648cd9dcf9 100644 --- a/.github/workflows/pip-compile-dev.yml +++ b/.github/workflows/pip-compile-dev.yml @@ -40,5 +40,5 @@ jobs: 'pip-compile-3.10(static)' 'pip-compile-3.10(spelling)' reset-branch: "${{ inputs.reset-branch || false }}" - labels: "${{ inputs.labels || 'backport-2.14,backport-2.15,backport-2.16,tooling' }}" + labels: "${{ inputs.labels || 'backport-2.14,backport-2.15,backport-2.16,backport-2.17,tooling' }}" secrets: inherit From 4effdab36bba7283bf51459820e5d762af82837e Mon Sep 17 00:00:00 2001 From: vojtam Date: Tue, 23 Apr 2024 10:38:19 +0200 Subject: [PATCH 310/536] Reworked headings * better subsection heading about how plugins resolve local relative paths * put information about troubleshooting search paths into sub-subsection --- docs/docsite/rst/playbook_guide/playbook_pathing.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index 9fcd0429059..dcc00be49b8 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -21,8 +21,8 @@ Task paths Relative paths used in a task typically refer to remote files and directories on the managed nodes. However, paths passed to lookup plugins and some paths used in action plugins such as the "src" path for the :ansplugin:`template ` and :ansplugin:`copy ` modules refer to local files and directories on the control node. -Resolving local relative paths ------------------------------- +How plugins resolve local relative paths +---------------------------------------- When you specify a relative path for a local file, Ansible will try to find that file first in the current task's role, then in other roles that included or depend on the current role, then relative to the file in which the task is defined, and finally relative to the current play. It will take the first matching file that it finds. This way, if multiple files with the same file name exist, Ansible will find the file that is closest to the current task and that is most likely to be file you wanted. @@ -39,6 +39,9 @@ Specifically, Ansible tries to find the file Ansible does not search the current working directory. (The directory you're in when you execute Ansible.) Also, Ansible will only search within a role if you actually included it with an `include_role` or `import_role` task or a dependency. If you instead use `include`, `include_task` or `import_task` to include just the tasks from a specific file but not the full role, Ansible will not search that role in steps 1 and 2. +Troubleshooting search paths +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + When you execute Ansible, the variable `ansible_search_path` will contain the paths searched, in the order they were searched in but without listing their subdirectories. If you run Ansible in verbosity level 5 by passing the `-vvvvv` argument, Ansible will report each directory as it searches, except when it searches for a tasks file. From 4c596ea1b2333094f39c0080302d477d20aeb11c Mon Sep 17 00:00:00 2001 From: vojtam Date: Tue, 23 Apr 2024 10:58:49 +0200 Subject: [PATCH 311/536] replaced single backticks with double ones in places where syntax should be highlighted --- docs/docsite/rst/playbook_guide/playbook_pathing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index dcc00be49b8..fd9c942dd1d 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -33,16 +33,16 @@ Specifically, Ansible tries to find the file 1. In its appropriate subdirectory—"files", "vars", "templates" or "tasks", depending on the kind of file Ansible is searching for. 2. Directly in its directory. -2. Like 1, in the parent role that called into this current role with `include_role`, `import_role`, or with a role dependency. If the parent role has its own parent role, Ansible will repeat this step with that role. +2. Like 1, in the parent role that called into this current role with ``include_role``, ``import_role``, or with a role dependency. If the parent role has its own parent role, Ansible will repeat this step with that role. 3. Like 1, in the current task file's directory. 4. Like 1, in the current play file's directory. -Ansible does not search the current working directory. (The directory you're in when you execute Ansible.) Also, Ansible will only search within a role if you actually included it with an `include_role` or `import_role` task or a dependency. If you instead use `include`, `include_task` or `import_task` to include just the tasks from a specific file but not the full role, Ansible will not search that role in steps 1 and 2. +Ansible does not search the current working directory. (The directory you're in when you execute Ansible.) Also, Ansible will only search within a role if you actually included it with an ``include_role`` or ``import_role`` task or a dependency. If you instead use ``include``, ``include_task`` or ``import_task`` to include just the tasks from a specific file but not the full role, Ansible will not search that role in steps 1 and 2. Troubleshooting search paths ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When you execute Ansible, the variable `ansible_search_path` will contain the paths searched, in the order they were searched in but without listing their subdirectories. If you run Ansible in verbosity level 5 by passing the `-vvvvv` argument, Ansible will report each directory as it searches, except when it searches for a tasks file. +When you execute Ansible, the variable ``ansible_search_path`` will contain the paths searched, in the order they were searched in but without listing their subdirectories. If you run Ansible in verbosity level 5 by passing the ``-vvvvv`` argument, Ansible will report each directory as it searches, except when it searches for a tasks file. .. note:: The current working directory might vary depending on the connection plugin and if the action is local or remote. For the remote it is normally the directory on which the login shell puts the user. For local it is either the directory you executed ansible from or in some cases the playbook directory. From fdc65aa2a43b27e7677afe2afa7bd0713675390b Mon Sep 17 00:00:00 2001 From: vojtam Date: Tue, 23 Apr 2024 11:17:05 +0200 Subject: [PATCH 312/536] Refactored the line about ansible not searching the current workdir. --- docs/docsite/rst/playbook_guide/playbook_pathing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index fd9c942dd1d..e799f066a88 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -37,7 +37,8 @@ Specifically, Ansible tries to find the file 3. Like 1, in the current task file's directory. 4. Like 1, in the current play file's directory. -Ansible does not search the current working directory. (The directory you're in when you execute Ansible.) Also, Ansible will only search within a role if you actually included it with an ``include_role`` or ``import_role`` task or a dependency. If you instead use ``include``, ``include_task`` or ``import_task`` to include just the tasks from a specific file but not the full role, Ansible will not search that role in steps 1 and 2. +Ansible does not search for local files in the current working directory, in other words, the directory from which you execute Ansible. +Ansible will only search within a role if you actually included it with an ``include_role`` or ``import_role`` task or a dependency. If you instead use ``include``, ``include_task`` or ``import_task`` to include just the tasks from a specific file but not the full role, Ansible will not search that role in steps 1 and 2. Troubleshooting search paths ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 3696321d73072e1bf04882f89e095d0679984aa3 Mon Sep 17 00:00:00 2001 From: Ondrej Nemec Date: Tue, 23 Apr 2024 13:42:13 +0200 Subject: [PATCH 313/536] fix: more consistent displaying of changed_when: True example (#1167) --- .../rst/playbook_guide/playbooks_error_handling.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst index 641da6cb7ed..7a17c33c551 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst @@ -156,13 +156,9 @@ Ansible lets you define when a particular task has "changed" a remote node using ansible.builtin.shell: wall 'beep' changed_when: False -If you want to report change all the time, use ``changed_when: True``. - -.. code-block:: yaml - - - name: This task will always report 'changed' status - ansible.builtin.command: /path/to/command - changed_when: True + - name: This task will always report 'changed' status + ansible.builtin.command: /path/to/command + changed_when: True You can also combine multiple conditions to override "changed" result. From 46dcf79fe89041ce59ba3dd4248056c9cdebc9ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Tue, 23 Apr 2024 21:52:16 +0200 Subject: [PATCH 314/536] fix: connection keyword mentioned --- docs/docsite/rst/plugins/connection.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index 201dd835f11..f0c27d05ff5 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -9,7 +9,7 @@ Connection plugins Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. -By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH`, native ssh (just called :ref:`ssh`), and :ref:`local` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins `. To configure these plugins, you might use :ref:`ANSIBLE_CONNECTION_PATH` option. +By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH`, native ssh (just called :ref:`ssh`), and :ref:`local` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins `. To establish the connection, you can use an ``ansible-connection`` script referenced in :ref:`ANSIBLE_CONNECTION_PATH`. To change the connection plugin used for tasks, you can use the ``connection`` keyword. The basics of these connection types are covered in the :ref:`getting started` section. From 1e7fbb64d7f7d6727a9d13c1e537be83413477ed Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 24 Apr 2024 08:22:07 +0200 Subject: [PATCH 315/536] Add Ansible 9.5.1 porting guide. (#1312) --- .../rst/porting_guides/porting_guide_9.rst | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 836c4629eaf..5cb14161635 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -84,6 +84,43 @@ Porting custom scripts Networking ========== +Porting Guide for v9.5.1 +======================== + +Major Changes +------------- + +containers.podman +~~~~~~~~~~~~~~~~~ + +- Add quadlet support for Podman modules + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Add notes for backup modules in the documentation in both monitor and monitor_fact modules. +- Supported new FOS versions 7.4.2 and 7.4.3, and support data type mac_address in the collection. +- Update the documentation for the supported versions from latest to a fix version number. +- Update the required ansible version to 2.15. + +Deprecated Features +------------------- + +community.crypto +~~~~~~~~~~~~~~~~ + +- acme.backends module utils - from community.crypto on, all implementations of ``CryptoBackend`` must override ``get_ordered_csr_identifiers()``. The current default implementation, which simply sorts the result of ``get_csr_identifiers()``, will then be removed (https://github.com/ansible-collections/community.crypto/pull/725). + +community.general +~~~~~~~~~~~~~~~~~ + +- hipchat callback plugin - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The callback plugin is therefore deprecated and will be removed from community.general 10.0.0 if nobody provides compelling reasons to still keep it (https://github.com/ansible-collections/community.general/issues/8184, https://github.com/ansible-collections/community.general/pull/8189). + +community.vmware +~~~~~~~~~~~~~~~~ + +- vmware_guest_tools_info - `vm_tools_install_status` will be removed from next major version (5.0.0) of the collection since the API call that provides this information has been deprecated by VMware. Use `vm_tools_running_status` / `vm_tools_version_status` instead (https://github.com/ansible-collections/community.vmware/issues/2033). + Porting Guide for v9.4.0 ======================== From 85e80a6f457969c356fcad64191b25c318d0dc61 Mon Sep 17 00:00:00 2001 From: vojtam Date: Wed, 24 Apr 2024 16:01:10 +0200 Subject: [PATCH 316/536] Added a note describing how Ansible deals with relative tasks paths when using include_role vs when using include_taks / import_task --- docs/docsite/rst/playbook_guide/playbook_pathing.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index e799f066a88..22f3da5fa7d 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -26,7 +26,7 @@ How plugins resolve local relative paths When you specify a relative path for a local file, Ansible will try to find that file first in the current task's role, then in other roles that included or depend on the current role, then relative to the file in which the task is defined, and finally relative to the current play. It will take the first matching file that it finds. This way, if multiple files with the same file name exist, Ansible will find the file that is closest to the current task and that is most likely to be file you wanted. -Specifically, Ansible tries to find the file +Specifically, Ansible tries to find the file in the following order: 1. In the current role. @@ -38,7 +38,8 @@ Specifically, Ansible tries to find the file 4. Like 1, in the current play file's directory. Ansible does not search for local files in the current working directory, in other words, the directory from which you execute Ansible. -Ansible will only search within a role if you actually included it with an ``include_role`` or ``import_role`` task or a dependency. If you instead use ``include``, ``include_task`` or ``import_task`` to include just the tasks from a specific file but not the full role, Ansible will not search that role in steps 1 and 2. + +.. note:: When resolving local relative paths for tasks files, Ansible uses the context of the role that includes tasks with an ``include_role`` or ``import_role`` statement. If you import the tasks with ``include_task``, or ``import_task`` statements, Ansible uses the context of the importing file. Troubleshooting search paths ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From bd0157ba6348eaae98886ef1210a118a6762d16d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Wed, 24 Apr 2024 16:24:34 +0200 Subject: [PATCH 317/536] fix: remove mention of 'connection_plugins' --- docs/docsite/rst/plugins/connection.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index f0c27d05ff5..40f6cf172be 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -20,14 +20,6 @@ The basics of these connection types are covered in the :ref:`getting started Date: Wed, 24 Apr 2024 17:22:01 +0200 Subject: [PATCH 318/536] comments integrated --- docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index bc2b64cb2ed..d4b8e233462 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -123,13 +123,13 @@ Use absolute paths in your playbooks To make reorganizing your files more convenient, you can use absolute paths for referenced files in your playbooks. The global Ansible variables might help determine the absolute paths, as the example below demonstrates. -The example expects the ``ansible.cfg`` file to be in the root of the folder. +#. Set an environment variable 'PROJECT_ROOT' to the actual path of the project root. #. Set the following variables for the `all` group: .. code-block:: yaml - ansible_repo_path: "{{ ansible_config_file[:-11] }}" + ansible_repo_path: "{{ lookup('env', 'PROJECT_ROOT') }}" files_path: "{{ ansible_repo_path }}/playbooks/files" templates_path: "{{ ansible_repo_path }}/playbooks/templates" tasks_path: "{{ ansible_repo_path }}/playbooks/tasks" @@ -144,6 +144,8 @@ The example expects the ``ansible.cfg`` file to be in the root of the folder. src: {{ files_path }}/foo.conf dest: /etc/foo.conf +This way, you can change the root of the project without having to change your playbooks. + .. _execution_tips: Execution tricks From 5ec8d489cb260ffd20feca61958769814ba16822 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Wed, 24 Apr 2024 22:44:29 +0200 Subject: [PATCH 319/536] example removed --- .../rst/tips_tricks/ansible_tips_tricks.rst | 30 ++----------------- 1 file changed, 3 insertions(+), 27 deletions(-) diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index d4b8e233462..6a4071ea06e 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -117,34 +117,10 @@ There is no limit to the number of variable and vault files or their names. Note that using this strategy in your inventory still requires *all vault passwords to be available* (for example for ``ansible-playbook`` or `AWX/Ansible Tower `_) when run with that inventory. -Use absolute paths in your playbooks ------------------------------------- - -To make reorganizing your files more convenient, you can use absolute paths for referenced files in your playbooks. -The global Ansible variables might help determine the absolute paths, as the example below demonstrates. - -#. Set an environment variable 'PROJECT_ROOT' to the actual path of the project root. - -#. Set the following variables for the `all` group: - -.. code-block:: yaml - - ansible_repo_path: "{{ lookup('env', 'PROJECT_ROOT') }}" - files_path: "{{ ansible_repo_path }}/playbooks/files" - templates_path: "{{ ansible_repo_path }}/playbooks/templates" - tasks_path: "{{ ansible_repo_path }}/playbooks/tasks" - vaults_path: "{{ ansible_repo_path }}/playbooks/vaults" - -#. Use these variables to reference a file (``playbooks/files/foo.conf``) as follows. - -.. code-block:: yaml - - - name: File copy - ansible.builtin.copy: - src: {{ files_path }}/foo.conf - dest: /etc/foo.conf +Avoid configuration-dependent content +------------------------------------- -This way, you can change the root of the project without having to change your playbooks. +To ensure that your automation project is easy to understand, modify, and share with others, you should avoid configuration-dependent content. For example, rather than referencing an ``ansible.cfg`` as the root of a project, you should use magic variables such as ``playbook_dir`` or ``role_name`` to determine paths relative to known locations within your project directory. This can help to keep automation content flexible, reusable, and easy to maintain. .. _execution_tips: From 5a69a9a86bf936226a39ec0c55fae692afdf68cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Wed, 24 Apr 2024 23:50:02 +0200 Subject: [PATCH 320/536] comments integrated --- docs/docsite/rst/plugins/connection.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index 40f6cf172be..5faad988a7c 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -9,7 +9,7 @@ Connection plugins Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. -By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH`, native ssh (just called :ref:`ssh`), and :ref:`local` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins `. To establish the connection, you can use an ``ansible-connection`` script referenced in :ref:`ANSIBLE_CONNECTION_PATH`. To change the connection plugin used for tasks, you can use the ``connection`` keyword. +By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH`, native ssh (just called :ref:`ssh`), and :ref:`local` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins `. You can use the ``ANSIBLE_CONNECTION_PATH`` environment variable to specify a custom directory for the ``ansible-connection`` script along with other files related to connections during remote execution. To change the connection plugin for your tasks, you can use the ``connection`` keyword. The basics of these connection types are covered in the :ref:`getting started` section. From 97e89fbe9ee383919324de95219f0876ee7d5549 Mon Sep 17 00:00:00 2001 From: Ondrej Nemec Date: Thu, 25 Apr 2024 09:30:28 +0200 Subject: [PATCH 321/536] docs: added section referencing changed_when (#1167) --- .../rst/playbook_guide/playbooks_handlers.rst | 37 +++++++++++++++++-- 1 file changed, 33 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst index 6502036673f..15878c96251 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst @@ -5,10 +5,6 @@ Handlers: running operations on change Sometimes you want a task to run only when a change is made on a machine. For example, you may want to restart a service if a task updates the configuration of that service, but not if the configuration is unchanged. Ansible uses handlers to address this use case. Handlers are tasks that only run when notified. -.. note:: - - Ansible sets "changed" status by itself, but you can also define the rules using ``changed_when``. See :ref:`override_the_changed_result` to determine it explicitly. - .. contents:: :local: @@ -118,6 +114,39 @@ Each handler should have a globally unique name. If multiple handlers are define There is only one global scope for handlers (handler names and listen topics) regardless of where the handlers are defined. This also includes handlers defined in roles. +Controlling the notifing of handlers by defining "changed" +---------------------------------------------------------- + +By using ``changed_when`` keyword, you define when a task has "changed" status. This means you directly determine when ``notify`` is triggered so it executes the handlers. + +In following example it is ensured that the handler restarts the service every time the new configuration gets copied: + +.. code-block:: yaml + + - name: Copy httpd configuration + ansible.builtin.copy: + src: ./new_httpd.conf + dest: /etc/httpd/conf/httpd.conf + # The task is always reported as changed + changed_when: True + notify: Restart apache + +Also you can execute handler for example based on command return value: + +.. code-block:: yaml + + tasks: + - name: Task with handled command result + ansible.builtin.command: /bin/utils/check_command + register: result + changed_when: result.rc == 2 # something is not properly initialized + notify: Initialize files + + handlers: + - name: Initialize files + ... + +See :ref:`override_the_changed_result` for more about ``changed_when``. Controlling when handlers run ----------------------------- From bd321d629b9b165dd27ab3a6d7b5ec40bfb9463c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Thu, 25 Apr 2024 12:25:42 +0200 Subject: [PATCH 322/536] 'for more information' added --- docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index 6a4071ea06e..4edb226af2a 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -120,7 +120,7 @@ Note that using this strategy in your inventory still requires *all vault passwo Avoid configuration-dependent content ------------------------------------- -To ensure that your automation project is easy to understand, modify, and share with others, you should avoid configuration-dependent content. For example, rather than referencing an ``ansible.cfg`` as the root of a project, you should use magic variables such as ``playbook_dir`` or ``role_name`` to determine paths relative to known locations within your project directory. This can help to keep automation content flexible, reusable, and easy to maintain. +To ensure that your automation project is easy to understand, modify, and share with others, you should avoid configuration-dependent content. For example, rather than referencing an ``ansible.cfg`` as the root of a project, you can use magic variables such as ``playbook_dir`` or ``role_name`` to determine paths relative to known locations within your project directory. This can help to keep automation content flexible, reusable, and easy to maintain. For more information, see :ref:`special variables`. .. _execution_tips: From 8073c10c0bcb52b0f3626d25906188bd1319fabd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Thu, 25 Apr 2024 12:48:28 +0200 Subject: [PATCH 323/536] changing location --- docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index 4edb226af2a..54d2ecbd749 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -26,6 +26,11 @@ Customize the CLI output You can change the output from Ansible CLI commands using :ref:`callback_plugins`. +Avoid configuration-dependent content +------------------------------------- + +To ensure that your automation project is easy to understand, modify, and share with others, you should avoid configuration-dependent content. For example, rather than referencing an ``ansible.cfg`` as the root of a project, you can use magic variables such as ``playbook_dir`` or ``role_name`` to determine paths relative to known locations within your project directory. This can help to keep automation content flexible, reusable, and easy to maintain. For more information, see :ref:`special variables`. + .. _playbook_tips: Playbook tips @@ -117,11 +122,6 @@ There is no limit to the number of variable and vault files or their names. Note that using this strategy in your inventory still requires *all vault passwords to be available* (for example for ``ansible-playbook`` or `AWX/Ansible Tower `_) when run with that inventory. -Avoid configuration-dependent content -------------------------------------- - -To ensure that your automation project is easy to understand, modify, and share with others, you should avoid configuration-dependent content. For example, rather than referencing an ``ansible.cfg`` as the root of a project, you can use magic variables such as ``playbook_dir`` or ``role_name`` to determine paths relative to known locations within your project directory. This can help to keep automation content flexible, reusable, and easy to maintain. For more information, see :ref:`special variables`. - .. _execution_tips: Execution tricks From d0722d227afea83033267bd7ae18aa8ec6a00822 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tereza=20Helanov=C3=A1?= Date: Thu, 25 Apr 2024 14:47:26 +0200 Subject: [PATCH 324/536] mention of ANSIBLE_CONNECTION_PATH removed --- docs/docsite/rst/plugins/connection.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index 5faad988a7c..dc0c8753102 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -9,7 +9,7 @@ Connection plugins Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time. -By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH`, native ssh (just called :ref:`ssh`), and :ref:`local` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins `. You can use the ``ANSIBLE_CONNECTION_PATH`` environment variable to specify a custom directory for the ``ansible-connection`` script along with other files related to connections during remote execution. To change the connection plugin for your tasks, you can use the ``connection`` keyword. +By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH`, native ssh (just called :ref:`ssh`), and :ref:`local` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins `. To change the connection plugin for your tasks, you can use the ``connection`` keyword. The basics of these connection types are covered in the :ref:`getting started` section. From a984211d45b3110607fbe4e42d46e36933c2bd16 Mon Sep 17 00:00:00 2001 From: Ondrej Nemec Date: Thu, 25 Apr 2024 17:43:58 +0200 Subject: [PATCH 325/536] fix: wording and structure changes (#1167) --- .../playbooks_error_handling.rst | 1 - .../rst/playbook_guide/playbooks_handlers.rst | 53 +++++++------------ 2 files changed, 19 insertions(+), 35 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst index 7a17c33c551..1d05f204207 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst @@ -160,7 +160,6 @@ Ansible lets you define when a particular task has "changed" a remote node using ansible.builtin.command: /path/to/command changed_when: True - You can also combine multiple conditions to override "changed" result. .. code-block:: yaml diff --git a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst index 15878c96251..1b3c2111859 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst @@ -114,40 +114,6 @@ Each handler should have a globally unique name. If multiple handlers are define There is only one global scope for handlers (handler names and listen topics) regardless of where the handlers are defined. This also includes handlers defined in roles. -Controlling the notifing of handlers by defining "changed" ----------------------------------------------------------- - -By using ``changed_when`` keyword, you define when a task has "changed" status. This means you directly determine when ``notify`` is triggered so it executes the handlers. - -In following example it is ensured that the handler restarts the service every time the new configuration gets copied: - -.. code-block:: yaml - - - name: Copy httpd configuration - ansible.builtin.copy: - src: ./new_httpd.conf - dest: /etc/httpd/conf/httpd.conf - # The task is always reported as changed - changed_when: True - notify: Restart apache - -Also you can execute handler for example based on command return value: - -.. code-block:: yaml - - tasks: - - name: Task with handled command result - ansible.builtin.command: /bin/utils/check_command - register: result - changed_when: result.rc == 2 # something is not properly initialized - notify: Initialize files - - handlers: - - name: Initialize files - ... - -See :ref:`override_the_changed_result` for more about ``changed_when``. - Controlling when handlers run ----------------------------- @@ -171,6 +137,25 @@ The ``meta: flush_handlers`` task triggers any handlers that have been notified Once handlers are executed, either automatically after each mentioned section or manually by the ``flush_handlers`` meta task, they can be notified and run again in later sections of the play. +Defining when tasks change +-------------------------- + +You can control when handlers are notified about task changes using the ``changed_when`` keyword. + +In the following example, the handler restarts the service each time the configuration file is copied: + +.. code-block:: yaml + + tasks: + - name: Copy httpd configuration + ansible.builtin.copy: + src: ./new_httpd.conf + dest: /etc/httpd/conf/httpd.conf + # The task is always reported as changed + changed_when: True + notify: Restart apache + +See :ref:`override_the_changed_result` for more about ``changed_when``. Using variables with handlers ----------------------------- From 36a52b86c7d455bba94b32658f6ec92e69b64bf0 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 25 Apr 2024 17:34:23 +0100 Subject: [PATCH 326/536] update symlink step syntax in docs build workflow this change fixes an issue with the docs build workflow so that the input to create a symlink is applied correctly, otherwise the symlink is always created --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 6690888b52c..04fd308a4b1 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -92,7 +92,7 @@ jobs: working-directory: build-directory/docs/docsite - name: Create latest symlink - if: github.event.inputs.latest-symlink + if: ${{ github.event.inputs.latest-symlink == 'true'}} run: ln -s "${VERSION}" _build/html/latest working-directory: build-directory/docs/docsite From 22bc86912e39051cedceafa91cc749455e7bbf58 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Fri, 26 Apr 2024 10:29:31 +0100 Subject: [PATCH 327/536] improve workflow syntax --- .github/workflows/build-package-docs.yaml | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 6690888b52c..2889afb18f9 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -52,7 +52,12 @@ jobs: - name: Checkout Ansible documentation uses: actions/checkout@v4 with: - repository: ${{ github.event.inputs.repository-owner }}/${{ github.event.inputs.repository-name }} + repository: >- + ${{ + github.event.inputs.repository-owner + }}/${{ + github.event.inputs.repository-name + }} ref: ${{ github.event.inputs.repository-branch }} path: build-directory @@ -67,10 +72,10 @@ jobs: working-directory: build-directory - name: Install project requirements - run: | - python -m pip install \ - -r tests/requirements.in \ - -c tests/requirements.txt + run: >- + python -m pip install + -r tests/requirements.in + -c tests/requirements.txt working-directory: build-directory - name: Set the COLLECTION_LIST variable From d61e53a9d41ba96dbf9c745c983c246aced1488d Mon Sep 17 00:00:00 2001 From: bontreger Date: Fri, 26 Apr 2024 14:12:37 -0400 Subject: [PATCH 328/536] Add examples to clarify inventory plugin usage (#1347) * Add examples to clarify inventory plugin usage * Update docs/docsite/rst/plugins/inventory.rst Co-authored-by: Don Naro * Update docs/docsite/rst/plugins/inventory.rst Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- docs/docsite/rst/plugins/inventory.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst index 5ea035cb42f..63f46608da0 100644 --- a/docs/docsite/rst/plugins/inventory.rst +++ b/docs/docsite/rst/plugins/inventory.rst @@ -52,6 +52,13 @@ To use an inventory plugin, you must provide an inventory source. Most of the ti To start using an inventory plugin with a YAML configuration source, create a file with the accepted file name schema documented for the plugin in question, then add ``plugin: plugin_name``. Use the fully qualified name if the plugin is in a collection. + +.. note:: Inventory plugins have required name patterns to which they must conform, for example: + + An inventory that includes the ``kubevirt.core.kubevirt`` inventory plugin must use the ``*.kubevirt.yml`` filename pattern. + An inventory that includes the ``servicenow.servicenow.now`` inventory plugin must use the ``*.servicenow.yml`` filename pattern. + + .. code-block:: yaml # demo.aws_ec2.yml From 0abae713b9ef4fbe976e2531ea8d19359158720e Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 28 Apr 2024 00:06:34 +0000 Subject: [PATCH 329/536] ci: refresh dev dependencies --- tests/formatters.txt | 4 ++-- tests/static.txt | 2 +- tests/typing.txt | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 5e1efcba758..0111fc98952 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==24.4.0 +black==24.4.2 # via -r tests/formatters.in click==8.1.7 # via black @@ -16,7 +16,7 @@ packaging==24.0 # via black pathspec==0.12.1 # via black -platformdirs==4.2.0 +platformdirs==4.2.1 # via black tomli==2.0.1 # via black diff --git a/tests/static.txt b/tests/static.txt index 9d83c82bd2b..ab6b2988e10 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.4.1 +ruff==0.4.2 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index a3ab6d9d7c5..fad9c16b458 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -42,7 +42,7 @@ markupsafe==2.1.5 # via jinja2 mdurl==0.1.2 # via markdown-it-py -mypy==1.9.0 +mypy==1.10.0 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy @@ -52,7 +52,7 @@ packaging==24.0 # via # -r tests/../hacking/tagger/requirements.txt # nox -platformdirs==4.2.0 +platformdirs==4.2.1 # via virtualenv pycparser==2.22 # via cffi @@ -90,7 +90,7 @@ urllib3==2.2.1 # via # pygithub # requests -virtualenv==20.25.3 +virtualenv==20.26.0 # via nox wrapt==1.16.0 # via deprecated From 024d31c1b739b52859ac74fb6b1c38810535aabd Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 28 Apr 2024 00:11:13 +0000 Subject: [PATCH 330/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 96fcc7bf6b9..6f2f9408869 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -83,11 +83,11 @@ packaging==24.0 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.7.0 +pydantic==2.7.1 # via # antsibull-core # antsibull-docs -pydantic-core==2.18.1 +pydantic-core==2.18.2 # via pydantic pygments==2.17.2 # via diff --git a/tests/requirements.txt b/tests/requirements.txt index 6e7daafc6a9..d59b8eaab9d 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -85,11 +85,11 @@ packaging==24.0 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.7.0 +pydantic==2.7.1 # via # antsibull-core # antsibull-docs -pydantic-core==2.18.1 +pydantic-core==2.18.2 # via pydantic pygments==2.17.2 # via From 4f825d6337c52e870c7e37a3861c5c5b50218480 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 29 Apr 2024 09:45:13 +0100 Subject: [PATCH 331/536] Update .github/workflows/build-package-docs.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 04fd308a4b1..63c97f06b6a 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -92,7 +92,7 @@ jobs: working-directory: build-directory/docs/docsite - name: Create latest symlink - if: ${{ github.event.inputs.latest-symlink == 'true'}} + if: fromJSON(github.event.inputs.latest-symlink) run: ln -s "${VERSION}" _build/html/latest working-directory: build-directory/docs/docsite From 47973316ca82790a618220da1b5a1fc6e63a24c5 Mon Sep 17 00:00:00 2001 From: vojtam Date: Tue, 30 Apr 2024 18:26:08 +0200 Subject: [PATCH 332/536] fix: tiny stylistic changes --- docs/docsite/rst/playbook_guide/playbook_pathing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index 22f3da5fa7d..1baafb9be72 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -37,7 +37,7 @@ Specifically, Ansible tries to find the file in the following order: 3. Like 1, in the current task file's directory. 4. Like 1, in the current play file's directory. -Ansible does not search for local files in the current working directory, in other words, the directory from which you execute Ansible. +Ansible does not search for local files in the current working directory; in other words, the directory from which you execute Ansible. .. note:: When resolving local relative paths for tasks files, Ansible uses the context of the role that includes tasks with an ``include_role`` or ``import_role`` statement. If you import the tasks with ``include_task``, or ``import_task`` statements, Ansible uses the context of the importing file. From cf2b85928b07da262894d30f1d9d2c0a8858c9ed Mon Sep 17 00:00:00 2001 From: vojtam Date: Tue, 30 Apr 2024 18:36:21 +0200 Subject: [PATCH 333/536] moved Troubleshooting search paths subsection to the bottom of the page and moved the note with details about current work dir up, where it fits better --- docs/docsite/rst/playbook_guide/playbook_pathing.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index 1baafb9be72..490ab49f2ac 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -39,12 +39,11 @@ Specifically, Ansible tries to find the file in the following order: Ansible does not search for local files in the current working directory; in other words, the directory from which you execute Ansible. +.. note:: The current working directory might vary depending on the connection plugin and if the action is local or remote. For the remote it is normally the directory on which the login shell puts the user. For local it is either the directory you executed ansible from or in some cases the playbook directory. + .. note:: When resolving local relative paths for tasks files, Ansible uses the context of the role that includes tasks with an ``include_role`` or ``import_role`` statement. If you import the tasks with ``include_task``, or ``import_task`` statements, Ansible uses the context of the importing file. Troubleshooting search paths ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When you execute Ansible, the variable ``ansible_search_path`` will contain the paths searched, in the order they were searched in but without listing their subdirectories. If you run Ansible in verbosity level 5 by passing the ``-vvvvv`` argument, Ansible will report each directory as it searches, except when it searches for a tasks file. - - -.. note:: The current working directory might vary depending on the connection plugin and if the action is local or remote. For the remote it is normally the directory on which the login shell puts the user. For local it is either the directory you executed ansible from or in some cases the playbook directory. From 3ed42f8226e8422092129e44f26be29a805427fa Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 30 Apr 2024 22:15:07 +0200 Subject: [PATCH 334/536] Add Ansible 10.0.0a2 porting guide. (#1378) --- .../rst/porting_guides/porting_guide_10.rst | 93 ++++++++++++++++++- 1 file changed, 92 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst index d4cae3313dd..df3524ddac7 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -24,7 +24,7 @@ No notable changes Command Line ============ -No notable changes +* Python 2.7 and Python 3.6 are no longer supported remote versions. Python 3.7+ is now required for target execution. Deprecated @@ -76,6 +76,97 @@ Networking No notable changes +Porting Guide for v10.0.0a2 +=========================== + +Added Collections +----------------- + +- kaytus.ksmanage (version 1.2.1) + +Known Issues +------------ + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + +Major Changes +------------- + +arista.eos +~~~~~~~~~~ + +- Update the netcommon base version 6.1.0 to support cli_restore plugin. + +cisco.ios +~~~~~~~~~ + +- Update the netcommon base version 6.1.0 to support cli_restore plugin. + +cisco.iosxr +~~~~~~~~~~~ + +- Update the netcommon base version to support cli_restore plugin. + +cisco.nxos +~~~~~~~~~~ + +- Updated the minimum required ansible.netcommon version to 6.1.0 to support the cli_restore module. + +containers.podman +~~~~~~~~~~~~~~~~~ + +- Add quadlet support for Podman modules + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_session - This module allows you to create and delete the sessions on iDRAC. + +grafana.grafana +~~~~~~~~~~~~~~~ + +- Add Grafana Loki role by @voidquark in https://github.com/grafana/grafana-ansible-collection/pull/188 +- Add Grafana Mimir role by @GVengelen in https://github.com/grafana/grafana-ansible-collection/pull/183 +- Add an Ansible role for Grafana Alloy by @ishanjainn in https://github.com/grafana/grafana-ansible-collection/pull/169 + +junipernetworks.junos +~~~~~~~~~~~~~~~~~~~~~ + +- Update the netcommon base version 6.1.0 to support cli_restore plugin. + +Removed Features +---------------- + +Ansible-core +~~~~~~~~~~~~ + +- Removed Python 2.7 and Python 3.6 as a supported remote version. Python 3.7+ is now required for target execution. + +Deprecated Features +------------------- + +community.crypto +~~~~~~~~~~~~~~~~ + +- acme.backends module utils - from community.crypto on, all implementations of ``CryptoBackend`` must override ``get_ordered_csr_identifiers()``. The current default implementation, which simply sorts the result of ``get_csr_identifiers()``, will then be removed (https://github.com/ansible-collections/community.crypto/pull/725). + +community.general +~~~~~~~~~~~~~~~~~ + +- hipchat callback plugin - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The callback plugin is therefore deprecated and will be removed from community.general 10.0.0 if nobody provides compelling reasons to still keep it (https://github.com/ansible-collections/community.general/issues/8184, https://github.com/ansible-collections/community.general/pull/8189). + +community.vmware +~~~~~~~~~~~~~~~~ + +- vmware_guest_tools_info - `vm_tools_install_status` will be removed from next major version (5.0.0) of the collection since the API call that provides this information has been deprecated by VMware. Use `vm_tools_running_status` / `vm_tools_version_status` instead (https://github.com/ansible-collections/community.vmware/issues/2033). + Porting Guide for v10.0.0a1 =========================== From ba04139aaa7a178eed1ccda037f962bea1dd5594 Mon Sep 17 00:00:00 2001 From: Devids10 <129358723+Devids10@users.noreply.github.com> Date: Tue, 30 Apr 2024 23:19:00 +0200 Subject: [PATCH 335/536] MUNI_TECH_WRITERS: Better documented local collections for playbooks #1129 (#1315) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: remove the reused snippet * feat: add new shared_snippet and add description of local installation next to playbooks * feat: add new section for installing collections locally * fix: fix nox check error * fix: remove shared txt files, add them to their included space, add an anchor to the new section * fix: comments from the pull request --------- Co-authored-by: Dávid Németh --- .../collections_installing.rst | 84 ++++++++++++++++++- .../installing_collections.txt | 72 ---------------- 2 files changed, 83 insertions(+), 73 deletions(-) delete mode 100644 docs/docsite/rst/shared_snippets/installing_collections.txt diff --git a/docs/docsite/rst/collections_guide/collections_installing.rst b/docs/docsite/rst/collections_guide/collections_installing.rst index 50366b41928..313f754e5aa 100644 --- a/docs/docsite/rst/collections_guide/collections_installing.rst +++ b/docs/docsite/rst/collections_guide/collections_installing.rst @@ -16,7 +16,62 @@ See `Getting started with Execution Environments ` if you are using any other Galaxy server, such as Red Hat Automation Hub. + +To install a collection hosted in Galaxy: + +.. code-block:: bash + + ansible-galaxy collection install my_namespace.my_collection + +To upgrade a collection to the latest available version from the Galaxy server you can use the ``--upgrade`` option: + +.. code-block:: bash + + ansible-galaxy collection install my_namespace.my_collection --upgrade + +You can also directly use the tarball from your build: + +.. code-block:: bash + + ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections + +You can build and install a collection from a local source directory. The ``ansible-galaxy`` utility builds the collection using the ``MANIFEST.json`` or ``galaxy.yml`` +metadata in the directory. + +.. code-block:: bash + + ansible-galaxy collection install /path/to/collection -p ./collections + +You can also install multiple collections in a namespace directory. + +.. code-block:: text + + ns/ + ├── collection1/ + │ ├── MANIFEST.json + │ └── plugins/ + └── collection2/ + ├── galaxy.yml + └── plugins/ + +.. code-block:: bash + + ansible-galaxy collection install /path/to/ns -p ./collections + +.. note:: + The install command automatically appends the path ``ansible_collections`` to the one specified with the ``-p`` option unless the + parent directory is already in a folder called ``ansible_collections``. + + +When using the ``-p`` option to specify the install path, use one of the values configured in :ref:`COLLECTIONS_PATHS`, as this is +where Ansible itself will expect to find collections. If you don't specify a path, ``ansible-galaxy collection install`` installs +the collection to the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections`` .. _installing_signed_collections: @@ -114,6 +169,33 @@ Downloading a collection for offline use .. include:: ../shared_snippets/download_tarball_collections.txt +.. _collection_local_install: + +Installing collections adjacent to playbooks +-------------------------------------------- + +You can install collections locally next to your playbooks inside your project instead of in a global location on your system or on AWX. + +Using locally installed collections adjacent to playbooks has some benefits, such as: +* Ensuring that all users of the project use the same collection version. +* Using self-contained projects makes it easy to move across different environments. Increased portability also reduces overhead when setting up new environments. This is a benefit when deploying Ansible playbooks in cloud environments. +* Managing collections locally lets you version them along with your playbooks. +* Installing collections locally isolates them from global installations in environments that have multiple projects. + +Here is an example of keeping a collection adjacent to the current playbook, under a ``collections/ansible_collections/`` directory structure. + +.. code-block:: text + + ./ + ├── play.yml + ├── collections/ + │ └── ansible_collections/ + │ └── my_namespace/ + │ └── my_collection/ + + +See :ref:`collection_structure` for details on the collection directory structure. + Installing a collection from source files ----------------------------------------- diff --git a/docs/docsite/rst/shared_snippets/installing_collections.txt b/docs/docsite/rst/shared_snippets/installing_collections.txt deleted file mode 100644 index e408ccf113b..00000000000 --- a/docs/docsite/rst/shared_snippets/installing_collections.txt +++ /dev/null @@ -1,72 +0,0 @@ - - -By default, ``ansible-galaxy collection install`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the -:file:`ansible.cfg` file under :ref:`galaxy_server`). You do not need any further configuration. -By default, Ansible installs the collection in ``~/.ansible/collections`` under the ``ansible_collections`` directory. - -See :ref:`Configuring the ansible-galaxy client ` if you are using any other Galaxy server, such as Red Hat Automation Hub. - -To install a collection hosted in Galaxy: - -.. code-block:: bash - - ansible-galaxy collection install my_namespace.my_collection - -To upgrade a collection to the latest available version from the Galaxy server you can use the ``--upgrade`` option: - -.. code-block:: bash - - ansible-galaxy collection install my_namespace.my_collection --upgrade - -You can also directly use the tarball from your build: - -.. code-block:: bash - - ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections - -You can build and install a collection from a local source directory. The ``ansible-galaxy`` utility builds the collection using the ``MANIFEST.json`` or ``galaxy.yml`` -metadata in the directory. - -.. code-block:: bash - - ansible-galaxy collection install /path/to/collection -p ./collections - -You can also install multiple collections in a namespace directory. - -.. code-block:: text - - ns/ - ├── collection1/ - │ ├── MANIFEST.json - │ └── plugins/ - └── collection2/ - ├── galaxy.yml - └── plugins/ - -.. code-block:: bash - - ansible-galaxy collection install /path/to/ns -p ./collections - -.. note:: - The install command automatically appends the path ``ansible_collections`` to the one specified with the ``-p`` option unless the - parent directory is already in a folder called ``ansible_collections``. - - -When using the ``-p`` option to specify the install path, use one of the values configured in :ref:`COLLECTIONS_PATHS`, as this is -where Ansible itself will expect to find collections. If you don't specify a path, ``ansible-galaxy collection install`` installs -the collection to the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections`` - -You can also keep a collection adjacent to the current playbook, under a ``collections/ansible_collections/`` directory structure. - -.. code-block:: text - - ./ - ├── play.yml - ├── collections/ - │ └── ansible_collections/ - │ └── my_namespace/ - │ └── my_collection/ - - -See :ref:`collection_structure` for details on the collection directory structure. - From 186be843998a0d3436671bff7e1867edaefc5c0f Mon Sep 17 00:00:00 2001 From: xszabo3 <165585659+xszabo3@users.noreply.github.com> Date: Wed, 1 May 2024 21:21:04 +0000 Subject: [PATCH 336/536] Fix typos in style guide (#1368) * doc: fix external link typo in style guide * doc: remove extra colons from style guide --- docs/docsite/rst/dev_guide/style_guide/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst index cb0a1f10c9f..033b70b6ae4 100644 --- a/docs/docsite/rst/dev_guide/style_guide/index.rst +++ b/docs/docsite/rst/dev_guide/style_guide/index.rst @@ -183,7 +183,7 @@ Long pages, or pages with multiple levels of headings, can also include a local .. note:: - Avoid raw URLs. RST and sphinx allow ::code:`https://my.example.com`, but this is unhelpful for those using screen readers. ``:ref:`` links automatically pick up the heading from the anchor, but for external links, always use the ::code:`link title `_` format. + Avoid raw URLs. RST and sphinx allow :code:`https://my.example.com`, but this is unhelpful for those using screen readers. ``:ref:`` links automatically pick up the heading from the anchor, but for external links, always use the :code:`\`link title \`_` format. .. _adding_anchors_rst: From 008acbdfab2ee8d0739563c85606f3387c481ce1 Mon Sep 17 00:00:00 2001 From: klemaszpetra <164990225+klemaszpetra@users.noreply.github.com> Date: Thu, 2 May 2024 21:34:34 +0200 Subject: [PATCH 337/536] New section on combining variables added (#1383) * New section on combining variables added * adapted changes from the review * moving the combining variables section * added subheadings --------- Co-authored-by: Petra Klemaszova --- .../playbook_guide/playbooks_variables.rst | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/docs/docsite/rst/playbook_guide/playbooks_variables.rst b/docs/docsite/rst/playbook_guide/playbooks_variables.rst index 3a4e5fcace5..05e011657b2 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_variables.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_variables.rst @@ -177,6 +177,70 @@ Both of these examples reference the same value ("one"). Bracket notation always ``add``, ``append``, ``as_integer_ratio``, ``bit_length``, ``capitalize``, ``center``, ``clear``, ``conjugate``, ``copy``, ``count``, ``decode``, ``denominator``, ``difference``, ``difference_update``, ``discard``, ``encode``, ``endswith``, ``expandtabs``, ``extend``, ``find``, ``format``, ``fromhex``, ``fromkeys``, ``get``, ``has_key``, ``hex``, ``imag``, ``index``, ``insert``, ``intersection``, ``intersection_update``, ``isalnum``, ``isalpha``, ``isdecimal``, ``isdigit``, ``isdisjoint``, ``is_integer``, ``islower``, ``isnumeric``, ``isspace``, ``issubset``, ``issuperset``, ``istitle``, ``isupper``, ``items``, ``iteritems``, ``iterkeys``, ``itervalues``, ``join``, ``keys``, ``ljust``, ``lower``, ``lstrip``, ``numerator``, ``partition``, ``pop``, ``popitem``, ``real``, ``remove``, ``replace``, ``reverse``, ``rfind``, ``rindex``, ``rjust``, ``rpartition``, ``rsplit``, ``rstrip``, ``setdefault``, ``sort``, ``split``, ``splitlines``, ``startswith``, ``strip``, ``swapcase``, ``symmetric_difference``, ``symmetric_difference_update``, ``title``, ``translate``, ``union``, ``update``, ``upper``, ``values``, ``viewitems``, ``viewkeys``, ``viewvalues``, ``zfill``. +Combining variables +=================== + +To merge variables that contain lists or dictionaries, you can use the following approaches. + +Combining list variables +------------------------ + +You can use the `set_fact` module to combine lists into a new `merged_list` variable as follows: + +.. code-block:: yaml + + vars: + list1: + - apple + - banana + - fig + + list2: + - peach + - plum + - pear + + tasks: + - name: Combine list1 and list2 into a merged_list var + ansible.builtin.set_fact: + merged_list: "{{ list1 + list2 }}" + +Combining dictionary variables +------------------------------ + +To merge dictionaries use the ``combine`` filter, for example: + +.. code-block:: yaml + + vars: + dict1: + name: Leeroy Jenkins + age: 25 + occupation: Astronaut + + dict2: + location: Galway + country: Ireland + postcode: H71 1234 + + tasks: + - name: Combine dict1 and dict2 into a merged_dict var + ansible.builtin.set_fact: + merged_dict: "{{ dict1 | ansible.builtin.combine(dict2) }}" + +For more details, see :ansplugin:`ansible.builtin.combine#filter` . + +Using the merge_variables lookup +-------------------------------- + +To merge variables that match the given prefixes, suffixes, or regular expressions, you can use the ``community.general.merge_variables`` lookup, for example: + +.. code-block:: yaml + + merged_variable: "{{ lookup('community.general.merge_variables', '__my_pattern', pattern_type='suffix') }}" + +For more details and example usage, refer to the `community.general.merge_variables lookup documentation `_. + .. _registered_variables: Registering variables From cbb89d7e68ed640119000e7d6d776ca759aca1b3 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Thu, 2 May 2024 14:38:33 -0500 Subject: [PATCH 338/536] CONTRIBUTING: document backport labels and PR Merging (#1364) This documents the current strategy for using the Patchback bot (at least as I perceive it) and the conclusion from the PR merge strategies discussion in https://github.com/ansible/ansible-documentation/issues/554. I've noticed some confusion about this lately, so I wanted to clear it up. --- CONTRIBUTING.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 713b64960a3..be7da611765 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,3 +9,41 @@ By contributing to ansible-documentation, you agree to the Developer Certificate Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution. See the [DCO](DCO) file for details. + +## Backport labels + +This repository has `stable-.` branches to correspond to each +ansible-core major release. +ansible-documentation commmitters can add `backport-.` labels to +pull requests so the [Patchback bot] will automatically create backport pull +requests after the original PR is merged. +Small fixes or cleanups should at least be backported to the latest +stable branch. +If a PR should stay on the `devel` and not be backported—for example, if the +documentation update addresses an ansible-core change that only occurred on the +ansible-core development branch—maintainers should instead add the +`no_backport` label. + +[Patchback bot]: https://github.com/apps/patchback + +## Merging pull requests + +This repository has two ways to apply pull requests: +`Squash and merge` and `Create a merge commit`. +`Squash and merge` squashes all of the commits from the PR's base branch into a +single commit and then applies that commit on top of the target branch in the +upstream ansible-documentation repository. +`Create a merge commit` uses `git merge` which preserves the entire commit +history from the base branch. +This may not be desired if, for example, there are a lot of fixup commits with +nondescriptive commit messages. +For other more complex changes—especially those that involve the docs build +scripts or other tooling code—it may be desirable to preserve the full commit +history to keep logical changes separated and avoid clobbering useful metadata +so the git history remains useful in the future. The maintainer who merges the +PR can select the merge mode through the dropdown menu next to the green merge +button. +Generally, maintainers should apply PRs using `Squash and merge`. +`Create a merge commit` should be used if the PR author added the +`merge_commit` label or the maintainer otherwise assesses that merge mode makes +sense for the change in question. From e16dbd39a56a837f72f870540af073ca06af71a0 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 2 May 2024 20:42:01 +0100 Subject: [PATCH 339/536] follows up on #1042 to remove smart from uptime script (#1340) --- examples/scripts/uptime.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/scripts/uptime.py b/examples/scripts/uptime.py index d77a5fb5660..38f2be9b1ac 100755 --- a/examples/scripts/uptime.py +++ b/examples/scripts/uptime.py @@ -53,7 +53,7 @@ def v2_runner_on_failed(self, result, *args, **kwargs): def main(): host_list = ['localhost', 'www.example.com', 'www.google.com'] # since the API is constructed for CLI it expects certain options to always be set in the context object - context.CLIARGS = ImmutableDict(connection='smart', module_path=['/to/mymodules', '/usr/share/ansible'], forks=10, become=None, + context.CLIARGS = ImmutableDict(module_path=['/to/mymodules', '/usr/share/ansible'], forks=10, become=None, become_method=None, become_user=None, check=False, diff=False, verbosity=0) # required for # https://github.com/ansible/ansible/blob/devel/lib/ansible/inventory/manager.py#L204 From fd3495af6394922cfc81344c42133a0fb62f98c7 Mon Sep 17 00:00:00 2001 From: xszabo3 <165585659+xszabo3@users.noreply.github.com> Date: Thu, 2 May 2024 19:44:03 +0000 Subject: [PATCH 340/536] Integrate ansible-creator and devtools into the developing collections guide (#1302) * doc: integrate ansible-creator in developing_collections_creating.rst * doc: corrections based on feedback * doc: highlight ansible-creator in note * doc: corrections based on review * doc: move ansible-creator section, rename anchor * doc: rewrite ADT note based on suggestion * doc: change links from github to readthedocs --- .../developing_collections_creating.rst | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections_creating.rst b/docs/docsite/rst/dev_guide/developing_collections_creating.rst index deff8fb1b63..c2a30b4c9a9 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_creating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_creating.rst @@ -6,7 +6,7 @@ Creating collections To create a collection: -#. Create a :ref:`new collection`, optionally using a custom :ref:`collection template`, with the ``ansible-galaxy collection init`` command. +#. Create a :ref:`new collection`, optionally using a custom :ref:`collection template`, with the ``ansible-galaxy collection init`` command. #. Add modules and other content to the collection. #. Build the collection into a collection artifact with :ref:`ansible-galaxy collection build`. #. Publish the collection artifact to Galaxy with :ref:`ansible-galaxy collection publish`. @@ -79,7 +79,7 @@ Currently the ``ansible-galaxy collection`` command implements the following sub To learn more about the ``ansible-galaxy`` command-line tool, see the :ref:`ansible-galaxy` man page. -.. _creating_collection_skeletons: +.. _creating_collection_from_custom_template: Creating a collection from a custom template ============================================ @@ -111,12 +111,30 @@ To initialize a collection using the new template, pass the path to the skeleton The default collection skeleton uses an internal filter ``comment_ify`` that isn't accessibly to ``--collection-skeleton``. Use ``ansible-doc -t filter|test --list`` to see available plugins. +.. _creating_collection_with_ansible-creator: + +Creating collections with ansible-creator +========================================= + +`ansible-creator `_ is designed to quickly scaffold an Ansible collection project. + +.. note:: + + The `Ansible Development Tools `_ package offers a convenient way to install ``ansible-creator`` along with a curated set of tools for developing automation content. + +After `installing `_ ``ansible-creator`` you can initialize a project in one of the following ways: + +* Use the `init `_ subcommand. +* Use ``ansible-creator`` with the `Ansible extension `_ in Visual Studio Code. + .. seealso:: :ref:`collections` Learn how to install and use collections. :ref:`collection_structure` Directories and files included in the collection skeleton + `Ansible Development Tools (ADT) `_ + Python package of tools to create and test Ansible content. `Mailing List `_ The development mailing list :ref:`communication_irc` From 79d7670f352eaad2d793806c622341532a80441b Mon Sep 17 00:00:00 2001 From: Don Naro Date: Fri, 3 May 2024 16:28:54 +0100 Subject: [PATCH 341/536] update codespell ignore lines (#1366) This change ignores spelling issues in two lines from the generated docs/docssite/rst/reference_appendices/config.rst file. --- .codespellignorelines | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.codespellignorelines b/.codespellignorelines index 59936541356..2eed9ae6cc1 100644 --- a/.codespellignorelines +++ b/.codespellignorelines @@ -13,3 +13,6 @@ see the `Active Directory Certificate Services documentation "$6$43927$lQxPKz2M2X.NWO.gK.t7phLwOKQMcSq72XxDZQ0XzYV6DlL1OD72h417aj16OnHTGxNzhftXJQBcjbunLEepM0" table#network-platform-table thead tr th.head { +# Following lines from the generated file docs/docsite/rst/reference_appendices/config.rst +:Description: This setting changes the behaviour of mismatched host patterns, it allows you to force a fatal error, a warning or just ignore it. + This setting changes the behaviour of mismatched host patterns, it allows you to force a fatal error, a warning or just ignore it. From d8005fcb21715631df9d2d1b88790f5b66e5397d Mon Sep 17 00:00:00 2001 From: SimonC <2318325+Simon-cto@users.noreply.github.com> Date: Mon, 6 May 2024 17:44:56 +0200 Subject: [PATCH 342/536] Adding explanation for combining until with loop (#1367) * Adding explanation for combining until with loop * Update docs/docsite/rst/playbook_guide/playbooks_loops.rst Co-authored-by: Don Naro * Update docs/docsite/rst/playbook_guide/playbooks_loops.rst Co-authored-by: Don Naro * Update docs/docsite/rst/playbook_guide/playbooks_loops.rst Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- .../rst/playbook_guide/playbooks_loops.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index 93fd27d94eb..afd73abca7c 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -256,6 +256,24 @@ When you run a task with ``until`` and register the result as a variable, the re If ``until`` is not specified, the task will retry until the task succeeds but at most ``retries`` times. +You can combine the ``until`` keyword with ``loop`` or ``with_``. The result of the task for each element of the loop is registered in the variable and can be used in the ``until`` condition. Here is an example: + +.. code-block:: yaml + + - name: Retry combined with a loop + uri: + url: "https://{{ item }}.ansible.com" + method: GET + register: uri_output + with_items: + - "galaxy" + - "docs" + - "forum" + - "www" + retries: 2 + delay: 1 + until: "uri_output.status == 200" + .. _loop_over_inventory: Looping over inventory From 70a04825eb4838fcd8c7ec0dcfd57d382225e489 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niko=20Mlynar=C4=8Dik?= <536617@mail.muni.cz> Date: Wed, 17 Apr 2024 22:09:16 +0200 Subject: [PATCH 343/536] Added a section on retrying tasks with timeout. --- .../rst/playbook_guide/playbooks_loops.rst | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index afd73abca7c..6c02966def1 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -274,6 +274,39 @@ You can combine the ``until`` keyword with ``loop`` or ``with_``. The re delay: 1 until: "uri_output.status == 200" +.. _retry_with_timeout: + +Retrying a task with timeout +---------------------------- + +You can use the ``timeout`` keyword to set a time limit for the execution of the task code. + +When you retry a task, ``timeout`` applies per each attempt and remains consistent -- it is not affected by the total time spent on a task. + +For example + +.. code-block:: yaml + - name: Retry a task with timeout + ansible.builtin.shell: sleep 10; /usr/bin/foo + register: result + until: result != -1 + retries: 3 + timeout: 15 + +This task runs up to 3 times with the ``timeout`` set to 15 seconds. During each retry, the execution time does not exceed the timeout limit and the task is retried until a condition is met. + +When the task code exceeds the ``timeout``, the retry process is stopped and the whole task fails. + +.. code-block:: yaml + - name: Retry a task with timeout + ansible.builtin.shell: sleep 10; /usr/bin/foo + register: result + until: result != -1 + retries: 3 + timeout: 5 + +In this task, code execution exceeds ``timeout`` and the task fails after the first attempt. + .. _loop_over_inventory: Looping over inventory From f03798954b042a07bde70ed0441f997fb2e70c8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niko=20Mlynar=C4=8Dik?= <536617@mail.muni.cz> Date: Thu, 18 Apr 2024 17:45:24 +0200 Subject: [PATCH 344/536] Code block edit. --- .../rst/playbook_guide/playbooks_loops.rst | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index 6c02966def1..eeae6b9a7b1 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -286,24 +286,26 @@ When you retry a task, ``timeout`` applies per each attempt and remains consiste For example .. code-block:: yaml - - name: Retry a task with timeout - ansible.builtin.shell: sleep 10; /usr/bin/foo - register: result - until: result != -1 - retries: 3 - timeout: 15 + + - name: Retry a task with timeout + ansible.builtin.shell: sleep 10; /usr/bin/foo + register: result + until: result != -1 + retries: 3 + timeout: 15 This task runs up to 3 times with the ``timeout`` set to 15 seconds. During each retry, the execution time does not exceed the timeout limit and the task is retried until a condition is met. When the task code exceeds the ``timeout``, the retry process is stopped and the whole task fails. .. code-block:: yaml - - name: Retry a task with timeout - ansible.builtin.shell: sleep 10; /usr/bin/foo - register: result - until: result != -1 - retries: 3 - timeout: 5 + + - name: Retry a task with timeout + ansible.builtin.shell: sleep 10; /usr/bin/foo + register: result + until: result != -1 + retries: 3 + timeout: 5 In this task, code execution exceeds ``timeout`` and the task fails after the first attempt. From c9b4d3d92ff809714bf8bca1be8791ffe7e5e07d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niko=20Mlynar=C4=8Dik?= <536617@mail.muni.cz> Date: Mon, 6 May 2024 21:24:39 +0200 Subject: [PATCH 345/536] Section on retrying with timeout pass 2 --- .../rst/playbook_guide/playbooks_loops.rst | 38 +++++++------------ 1 file changed, 13 insertions(+), 25 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index eeae6b9a7b1..a1a2f2439f6 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -274,40 +274,28 @@ You can combine the ``until`` keyword with ``loop`` or ``with_``. The re delay: 1 until: "uri_output.status == 200" -.. _retry_with_timeout: - Retrying a task with timeout ----------------------------- - -You can use the ``timeout`` keyword to set a time limit for the execution of the task code. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When you retry a task, ``timeout`` applies per each attempt and remains consistent -- it is not affected by the total time spent on a task. +When you use ``timeout`` in a loop, it applies per retry attempt. See :ref:`TASK_TIMEOUT ` for more details. For example .. code-block:: yaml - - name: Retry a task with timeout - ansible.builtin.shell: sleep 10; /usr/bin/foo - register: result - until: result != -1 - retries: 3 - timeout: 15 - -This task runs up to 3 times with the ``timeout`` set to 15 seconds. During each retry, the execution time does not exceed the timeout limit and the task is retried until a condition is met. - -When the task code exceeds the ``timeout``, the retry process is stopped and the whole task fails. - -.. code-block:: yaml + - name: Ensure the service is running + ansible.builtin.service: + name: my_service + state: startedgit + register: service_status + until: service_status is succeeded + retries: 5 + delay: 10 + timeout: 30 - - name: Retry a task with timeout - ansible.builtin.shell: sleep 10; /usr/bin/foo - register: result - until: result != -1 - retries: 3 - timeout: 5 +This task tries to start a service and retries the operation up to 5 times, with a 10 second delay between retries. Each attempt has a ``timeout`` limit of 30 seconds. -In this task, code execution exceeds ``timeout`` and the task fails after the first attempt. +When the task code exceeds the ``timeout``, the retry process is stopped. .. _loop_over_inventory: From e275a58f2aed7d04e505489ecc90d6d2effa1d71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niko=20Mlynar=C4=8Dik?= <536617@mail.muni.cz> Date: Fri, 3 May 2024 19:08:38 +0200 Subject: [PATCH 346/536] removed example --- .../rst/playbook_guide/playbooks_loops.rst | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index a1a2f2439f6..e7f9bc0285e 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -279,22 +279,6 @@ Retrying a task with timeout When you use ``timeout`` in a loop, it applies per retry attempt. See :ref:`TASK_TIMEOUT ` for more details. -For example - -.. code-block:: yaml - - - name: Ensure the service is running - ansible.builtin.service: - name: my_service - state: startedgit - register: service_status - until: service_status is succeeded - retries: 5 - delay: 10 - timeout: 30 - -This task tries to start a service and retries the operation up to 5 times, with a 10 second delay between retries. Each attempt has a ``timeout`` limit of 30 seconds. - When the task code exceeds the ``timeout``, the retry process is stopped. .. _loop_over_inventory: From 4e4ee1aef0892ca6a3f2acf9a92dc3b9c00e192b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niko=20Mlynar=C4=8Dik?= <536617@mail.muni.cz> Date: Mon, 6 May 2024 12:21:22 +0200 Subject: [PATCH 347/536] Minor rewording changes --- docs/docsite/rst/playbook_guide/playbooks_loops.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index e7f9bc0285e..c183d19f20f 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -279,7 +279,7 @@ Retrying a task with timeout When you use ``timeout`` in a loop, it applies per retry attempt. See :ref:`TASK_TIMEOUT ` for more details. -When the task code exceeds the ``timeout``, the retry process is stopped. +If the task action execution exceeds the ``timeout``, the retry process is stopped. .. _loop_over_inventory: From 43d8a1fcde94240a5884ec509443a6bff9721f4d Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 6 May 2024 22:50:22 +0200 Subject: [PATCH 348/536] Bump antsibull-docs to 2.11.0. (#1417) --- tests/constraints.in | 2 +- tests/requirements-relaxed.txt | 2 +- tests/requirements.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/constraints.in b/tests/constraints.in index 522d65804a4..8758dbd321d 100644 --- a/tests/constraints.in +++ b/tests/constraints.in @@ -2,4 +2,4 @@ # and antsibull-docs that production builds rely upon. sphinx == 7.2.5 -antsibull-docs == 2.10.0 # currently approved version +antsibull-docs == 2.11.0 # currently approved version diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 6f2f9408869..a1ff29f86c8 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -24,7 +24,7 @@ antsibull-changelog==0.26.0 # via antsibull-docs antsibull-core==3.0.1 # via antsibull-docs -antsibull-docs==2.10.0 +antsibull-docs==2.11.0 # via -r tests/requirements-relaxed.in antsibull-docs-parser==1.0.1 # via antsibull-docs diff --git a/tests/requirements.txt b/tests/requirements.txt index d59b8eaab9d..3f179eae98f 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -24,7 +24,7 @@ antsibull-changelog==0.26.0 # via antsibull-docs antsibull-core==3.0.1 # via antsibull-docs -antsibull-docs==2.10.0 +antsibull-docs==2.11.0 # via # -c tests/constraints.in # -r tests/requirements-relaxed.in From 5cd197944465e5d01be3ecbf7aa27140e245c295 Mon Sep 17 00:00:00 2001 From: Andrew Zipperer <47086307+zipperer@users.noreply.github.com> Date: Tue, 7 May 2024 11:31:24 -0500 Subject: [PATCH 349/536] intro_installation.rst: shells -> shell's to make possessive (#1420) --- docs/docsite/rst/installation_guide/intro_installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 51e63165e25..0526359984c 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -346,7 +346,7 @@ If you do not have bash 4.2, you must register each script independently. $ eval $(register-python-argcomplete ansible-pull) $ eval $(register-python-argcomplete ansible-vault) -You should place the above commands into your shells profile file such as ``~/.profile`` or ``~/.bash_profile``. +You should place the above commands into your shell's profile file such as ``~/.profile`` or ``~/.bash_profile``. Using ``argcomplete`` with zsh or tcsh ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 38e099ea47809ddbc53d06d126a10bf94b8c7db1 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 9 May 2024 10:31:02 -0400 Subject: [PATCH 350/536] Add changelog link and update powershell range --- .../rst/reference_appendices/release_and_maintenance.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 03f0583c5e1..ab583979b7e 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -155,14 +155,14 @@ Dates listed indicate the start date of the maintenance cycle. - End Of Life - Control Node Python - Target Python / PowerShell - * - 2.17 + * - `2.17`_ - | GA: 20 May 2024 | Critical: 04 Nov 2024 | Security: 19 May 2025 - Nov 2025 - | Python 3.10 - 3.12 - | Python 3.7 - 3.12 - | PowerShell TBD + | PowerShell 3 - 5.1 * - `2.16`_ - | GA: 06 Nov 2023 | Critical: 20 May 2024 @@ -317,6 +317,7 @@ Dates listed indicate the start date of the maintenance cycle. .. _2.14: https://github.com/ansible/ansible/blob/stable-2.14/changelogs/CHANGELOG-v2.14.rst .. _2.15: https://github.com/ansible/ansible/blob/stable-2.15/changelogs/CHANGELOG-v2.15.rst .. _2.16: https://github.com/ansible/ansible/blob/stable-2.16/changelogs/CHANGELOG-v2.16.rst +.. _2.17: https://github.com/ansible/ansible/blob/stable-2.17/changelogs/CHANGELOG-v2.17.rst From 6e2bf9688ca8a326471580190c0bbc554c631018 Mon Sep 17 00:00:00 2001 From: Chyna Sanders Date: Thu, 9 May 2024 14:42:08 -0500 Subject: [PATCH 351/536] Update playbooks_reuse_roles.rst (#1415) Updated the link for the Ansible Galaxy documentation to reflect the galaxy-ng documentation. Decided to remove the line completely ('A page that refers back to this one frequently is the...' ) which referred to a documentation page that no longer exists, as it seemed superfluous and slightly confusing. --- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 05b86f213c4..838fc7edd11 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -714,7 +714,7 @@ Sharing roles: Ansible Galaxy The client ``ansible-galaxy`` is included in Ansible. The Galaxy client allows you to download roles from Ansible Galaxy and provides an excellent default framework for creating your own roles. -Read the `Ansible Galaxy documentation `_ page for more information. A page that refers back to this one frequently is the Galaxy Roles document which explains the required metadata your role needs for use in Galaxy . +Read the `Ansible Galaxy documentation `_ page for more information. .. seealso:: From 3db7927a878a29527515c596805c8aefc1a57a48 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 9 May 2024 21:43:59 +0200 Subject: [PATCH 352/536] how_can_i_help page: rephrase the paragraph mentioning forums (#1410) --- docs/docsite/rst/community/how_can_I_help.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/how_can_I_help.rst b/docs/docsite/rst/community/how_can_I_help.rst index 8dfd0757885..0b0bd89bdc0 100644 --- a/docs/docsite/rst/community/how_can_I_help.rst +++ b/docs/docsite/rst/community/how_can_I_help.rst @@ -27,7 +27,8 @@ When you become a power user, your ability and opportunities to help the Ansible Ask and answer questions online =============================== -There are many forums online where Ansible users ask and answer questions. Reach out and communicate with your fellow Ansible users. +There are many online platforms where Ansible users and contributors ask and answer questions including the :ref:`ansible_forum`. +Reach out and communicate with your fellow Ansible enthusiasts. You can find the official :ref:`Ansible communication channels `. From 757b8943fc6a801ffa449a9a3bea0b687290bce8 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Thu, 9 May 2024 12:45:57 -0700 Subject: [PATCH 353/536] Restore the umask note for building docs (#1400) Signed-off-by: Abhijeet Kasurde --- docs/docsite/rst/community/documentation_contributions.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index a29b8c537f2..c10c0a10843 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -114,6 +114,11 @@ For more information on minimum Python versions, see the :ref:`support matrix Date: Thu, 9 May 2024 15:48:38 -0400 Subject: [PATCH 354/536] clarify backup_file (#1391) * add conditional Also backup_file would not be present if updated is not changed * clarify docs too * better desc --- .../rst/reference_appendices/common_return_values.rst | 2 +- docs/docsite/rst/reference_appendices/faq.rst | 11 +++++++---- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/common_return_values.rst b/docs/docsite/rst/reference_appendices/common_return_values.rst index 04f57ac3d6c..7ef8c69e951 100644 --- a/docs/docsite/rst/reference_appendices/common_return_values.rst +++ b/docs/docsite/rst/reference_appendices/common_return_values.rst @@ -18,7 +18,7 @@ Common backup_file ``````````` -For those modules that implement `backup=no|yes` when manipulating files, a path to the backup file created. +For those modules that implement `backup=no|yes` when manipulating files, a path to the backup file created if original file was changed. .. code-block:: console diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index b0aaec7f243..b34b177a1b2 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -845,11 +845,11 @@ and backups, which most file based modules also support: .. code-block:: yaml - - name: update config and backout if validation fails + - name: maintain config and backout if validation after change fails block: - - name: do the actual update, works with copy, lineinfile and any action that allows for `backup`. - template: src=template.j2 dest=/x/y/z backup=yes moreoptions=stuff - register: updated + - name: do the actual update, works with copy, lineinfile and any action that allows for `backup`. + template: src=template.j2 dest=/x/y/z backup=yes moreoptions=stuff + register: updated - name: run validation, this will change a lot as needed. We assume it returns an error when not passing, use `failed_when` if otherwise. shell: run_validation_commmand @@ -857,17 +857,20 @@ and backups, which most file based modules also support: become_user: requiredbyapp environment: WEIRD_REQUIREMENT: 1 + when: updated is changed rescue: - name: restore backup file to original, in the hope the previous configuration was working. copy: remote_src: true dest: /x/y/z src: "{{ updated['backup_file'] }}" + when: updated is changed always: - name: We choose to always delete backup, but could copy or move, or only delete in rescue. file: path: "{{ updated['backup_file'] }}" state: absent + when: updated is changed .. _jinja2_faqs: From 34bf3a4fc521568b3faf65b9926c54c3b5a8a7cb Mon Sep 17 00:00:00 2001 From: radvalach <134097304+radvalach@users.noreply.github.com> Date: Thu, 9 May 2024 21:50:09 +0200 Subject: [PATCH 355/536] Document the possibility of vars/main and defaults/main being directories (#1320) * feat: document the possibility of vars/main and defaults/main being directories * fix: add backslashes before "*" symbols to override their special meaning * fix: implement review feedback * fix: change documented possible main file extensions * fix: update feature to accommodate for recently merged documentation of custom main files * fix: move defaults/vars main directories explanation * fix: grammar and style changes * fix: replace "lexicographical" with "alphabetical" * fix: clarify the possibility of specifying custom file name * fix: replace spelling out options with ref to an explanation * fix: fix typo --------- Co-authored-by: Radim Valach --- .../rst/playbook_guide/playbooks_filters.rst | 2 +- .../playbook_guide/playbooks_reuse_roles.rst | 36 +++++++++++++++---- .../playbook_guide/playbooks_variables.rst | 6 ++-- 3 files changed, 33 insertions(+), 11 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index 6c25eabc377..c7ce2190a39 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -27,7 +27,7 @@ You can provide default values for variables directly in your templates using th {{ some_variable | default(5) }} -In the above example, if the variable 'some_variable' is not defined, Ansible uses the default value 5, rather than raising an "undefined variable" error and failing. If you are working within a role, you can also add a ``defaults/main.yml`` to define the default values for variables in your role. +In the above example, if the variable 'some_variable' is not defined, Ansible uses the default value 5, rather than raising an "undefined variable" error and failing. If you are working within a role, you can also add role defaults to define the default values for variables in your role. To learn more about role defaults see :ref:`Role directory structure `. Beginning in version 2.8, attempting to access an attribute of an Undefined value in Jinja will return another Undefined value, rather than throwing an error immediately. This means that you can now simply use a default with a value in a nested data structure (in other words, :code:`{{ foo.bar.baz | default('DEFAULT') }}`) when you do not know if the intermediate values are defined. diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 838fc7edd11..3404263392f 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -9,6 +9,8 @@ Roles let you automatically load related vars, files, tasks, handlers, and other .. contents:: :local: +.. _role_directory_structure: + Role directory structure ======================== @@ -77,6 +79,20 @@ Or call those tasks directly when loading the role, which bypasses the ``main.ym when: ansible_facts['os_family'] == 'Debian' +Directories ``defaults`` and ``vars`` may also include *nested directories*. If your variables file is a directory, Ansible reads all variables files and directories inside in alphabetical order. If a nested directory contains variables files as well as directories, Ansible reads the directories first. Below is an example of a ``vars/main`` directory: + +.. code-block:: text + + roles/ + common/ # this hierarchy represents a "role" + vars/ + main/ # <-- variables associated with this role + first_nested_directory/ + first_variables_file.yml + second_nested_directory/ + second_variables_file.yml + third_variables_file.yml + .. _role_search_path: Storing and finding roles @@ -125,15 +141,21 @@ The classic (original) way to use roles is with the ``roles`` option for a given - common - webservers -When you use the ``roles`` option at the play level, for each role 'x': +When you use the ``roles`` option at the play level, each role 'x' looks for a ``main.yml`` (also ``main.yaml`` and ``main``) in the following directories: -- If roles/x/tasks/main.yml exists, Ansible adds the tasks in that file to the play. -- If roles/x/handlers/main.yml exists, Ansible adds the handlers in that file to the play. -- If roles/x/vars/main.yml exists, Ansible adds the variables in that file to the play. -- If roles/x/defaults/main.yml exists, Ansible adds the variables in that file to the play. -- If roles/x/meta/main.yml exists, Ansible adds any role dependencies in that file to the list of roles. +- ``roles/x/tasks/`` +- ``roles/x/handlers/`` +- ``roles/x/vars/`` +- ``roles/x/defaults/`` +- ``roles/x/meta/`` - Any copy, script, template or include tasks (in the role) can reference files in roles/x/{files,templates,tasks}/ (dir depends on task) without having to path them relatively or absolutely. +.. note:: + ``vars`` and ``defaults`` can also match to a directory of the same name and Ansible will process all the files contained in that directory. See :ref:`Role directory structure ` for more details. + +.. note:: + If you use ``include_role/import_role``, you can specify a custom file name instead of ``main``. The ``meta`` directory is an exception because it does not allow for customization. + When you use the ``roles`` option at the play level, Ansible treats the roles as static imports and processes them during playbook parsing. Ansible executes each play in this order: - Any ``pre_tasks`` defined in the play. @@ -365,7 +387,7 @@ role ``meta/argument_specs.yml`` file. All fields are lowercase. * If ``required`` is ``false``/missing, ``default`` may be specified (assumed ``null`` if missing). * Ensure that the default value in the docs matches the default value in the code. The actual - default for the role variable will always come from ``defaults/main.yml``. + default for the role variable will always come from the role defaults (as defined in :ref:`Role directory structure `). * The default field must not be listed as part of the description unless it requires additional information or conditions. * If the option is a boolean value, you should use ``true``/``false`` if you want to be compatible with ``ansible-lint``. diff --git a/docs/docsite/rst/playbook_guide/playbooks_variables.rst b/docs/docsite/rst/playbook_guide/playbooks_variables.rst index 05e011657b2..d4dd5765905 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_variables.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_variables.rst @@ -424,7 +424,7 @@ Understanding variable precedence Ansible does apply variable precedence, and you might have a use for it. Here is the order of precedence from least to greatest (the last listed variables override all other variables): #. command line values (for example, ``-u my_user``, these are not variables) - #. role defaults (defined in role/defaults/main.yml) [1]_ + #. role defaults (as defined in :ref:`Role directory structure `) [1]_ #. inventory file or script group vars [2]_ #. inventory group_vars/all [3]_ #. playbook group_vars/all [3]_ @@ -437,7 +437,7 @@ Ansible does apply variable precedence, and you might have a use for it. Here is #. play vars #. play vars_prompt #. play vars_files - #. role vars (defined in role/vars/main.yml) + #. role vars (as defined in :ref:`Role directory structure `) #. block vars (only for tasks in block) #. task vars (only for the task) #. include_vars @@ -555,7 +555,7 @@ When you read this playbook it is clear that you have chosen to set a variable o vars: myname: John -Variables set in one role are available to later roles. You can set variables in a ``roles/common_settings/vars/main.yml`` file and use them in other roles and elsewhere in your playbook: +Variables set in one role are available to later roles. You can set variables in the role's ``vars`` directory (as defined in :ref:`Role directory structure `) and use them in other roles and elsewhere in your playbook: .. code-block:: yaml From e97f5f8c2b1a7f0ac33d18d2824e2043ab6c864a Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Thu, 9 May 2024 15:55:20 -0400 Subject: [PATCH 356/536] ci: refresh docs build dependencies (#1409) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 5 ++--- tests/requirements.txt | 8 +++----- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index a1ff29f86c8..8ede56975a3 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -89,11 +89,11 @@ pydantic==2.7.1 # antsibull-docs pydantic-core==2.18.2 # via pydantic -pygments==2.17.2 +pygments==2.18.0 # via # ansible-pygments # sphinx -pyproject-hooks==1.0.0 +pyproject-hooks==1.1.0 # via build pyyaml==6.0.1 # via @@ -159,7 +159,6 @@ sphinxcontrib-serializinghtml==1.1.10 tomli==2.0.1 # via # build - # pyproject-hooks # sphinx twiggy==0.5.1 # via diff --git a/tests/requirements.txt b/tests/requirements.txt index 3f179eae98f..632e72fcd42 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -91,11 +91,11 @@ pydantic==2.7.1 # antsibull-docs pydantic-core==2.18.2 # via pydantic -pygments==2.17.2 +pygments==2.18.0 # via # ansible-pygments # sphinx -pyproject-hooks==1.0.0 +pyproject-hooks==1.1.0 # via build pyyaml==6.0.1 # via @@ -160,9 +160,7 @@ sphinxcontrib-qthelp==1.0.7 sphinxcontrib-serializinghtml==1.1.10 # via sphinx tomli==2.0.1 - # via - # build - # pyproject-hooks + # via build twiggy==0.5.1 # via # antsibull-core From 60234ba8ced9ed80d27d2bda1eee8ec72a3db34d Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 5 May 2024 00:05:53 +0000 Subject: [PATCH 357/536] ci: refresh dev dependencies --- tests/static.txt | 2 +- tests/typing.txt | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index ab6b2988e10..41e86f28ba1 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.4.2 +ruff==0.4.3 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index fad9c16b458..6e07ae22784 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -20,13 +20,13 @@ codeowners==0.7.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 # via nox -cryptography==42.0.5 +cryptography==42.0.6 # via pyjwt deprecated==1.2.14 # via pygithub distlib==0.3.8 # via virtualenv -filelock==3.13.4 +filelock==3.14.0 # via virtualenv gitdb==4.0.11 # via gitpython @@ -58,7 +58,7 @@ pycparser==2.22 # via cffi pygithub==2.3.0 # via -r tests/../hacking/pr_labeler/requirements.txt -pygments==2.17.2 +pygments==2.18.0 # via rich pyjwt==2.8.0 # via pygithub @@ -90,7 +90,7 @@ urllib3==2.2.1 # via # pygithub # requests -virtualenv==20.26.0 +virtualenv==20.26.1 # via nox wrapt==1.16.0 # via deprecated From 77746fad9830facee60c47cf7e62b14ea82d1bf1 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 12 May 2024 00:06:10 +0000 Subject: [PATCH 358/536] ci: refresh dev dependencies --- tests/static.txt | 2 +- tests/typing.txt | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index 41e86f28ba1..8ad4c2d34b9 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.4.3 +ruff==0.4.4 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 6e07ae22784..66a772aedf0 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -20,7 +20,7 @@ codeowners==0.7.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 # via nox -cryptography==42.0.6 +cryptography==42.0.7 # via pyjwt deprecated==1.2.14 # via pygithub @@ -34,7 +34,7 @@ gitpython==3.1.43 # via -r tests/../hacking/tagger/requirements.txt idna==3.7 # via requests -jinja2==3.1.3 +jinja2==3.1.4 # via -r tests/../hacking/pr_labeler/requirements.txt markdown-it-py==3.0.0 # via rich From 0b2d757c120e0f9ac6171598cd6888da8f38c98c Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 12 May 2024 00:10:47 +0000 Subject: [PATCH 359/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 8ede56975a3..db45d3f18c1 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -34,7 +34,7 @@ asyncio-pool==0.6.0 # via antsibull-docs attrs==23.2.0 # via aiohttp -babel==2.14.0 +babel==2.15.0 # via # sphinx # sphinx-intl @@ -63,7 +63,7 @@ idna==3.7 # yarl imagesize==1.4.1 # via sphinx -jinja2==3.1.3 +jinja2==3.1.4 # via # -r tests/requirements-relaxed.in # antsibull-docs diff --git a/tests/requirements.txt b/tests/requirements.txt index 632e72fcd42..e04de540bff 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -36,7 +36,7 @@ asyncio-pool==0.6.0 # via antsibull-docs attrs==23.2.0 # via aiohttp -babel==2.14.0 +babel==2.15.0 # via # sphinx # sphinx-intl @@ -65,7 +65,7 @@ idna==3.7 # yarl imagesize==1.4.1 # via sphinx -jinja2==3.1.3 +jinja2==3.1.4 # via # -r tests/requirements-relaxed.in # antsibull-docs From ba860d238108616a6870249045570dda382f577d Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 14 May 2024 07:46:28 +0200 Subject: [PATCH 360/536] [Needs SC vote before merging] SC: update collection inclusion procedure (#1256) * SC: update collection inclusion procedure * Change as requested --- .../steering/community_steering_committee.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index b6192360599..8869c297365 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -148,13 +148,19 @@ When reviewing community collection `inclusion requests `_ linked to the corresponding inclusion request. The issue's description says that the collection has been approved by two or more Committee members and establishes a date (a week by default) when the inclusion decision will be considered made. This time period can be used to raise concerns. + * At least one of the reviews checks compliance with the entire checklist. + * All subsequent reviews can focus only on compliance with documentation and development conventions. -#. If no objections are raised up to the established date, the inclusion request is considered successfully resolved. In this case, a Committee member: + * Reviewers must not be involved significantly in development of the collection. They MUST declare any potential conflict of interest (for example, being friends/relatives/coworkers of the maintainers/authors, being users of the collection, or having contributed to that collection recently or in the past). + +#. After the collection gets two Committee member approvals, a Committee member creates a `community topic `_ linked to the corresponding inclusion request. The issue's description says that the collection has been approved by the Committee and establishes a date (a week by default) when the inclusion decision will be considered made. + + * The inclusion automatically gets suspended if the Committee members raise concerns or start another inclusion review within this time period. + * When there are no more objections or ongoing inclusion reviews, the inclusion date gets prolonged for another week. + +#. If the inclusion has not been suspended by the established date, the inclusion request is considered successfully resolved. In this case, a Committee member: #. Declares the decision in the topic and in the inclusion request. #. Moves the request to the ``Resolved reviews`` category. From 8ac53f3cd3ee1a4971311e9578bc2fe1f7de6313 Mon Sep 17 00:00:00 2001 From: sutapa Date: Tue, 14 May 2024 15:13:18 +0530 Subject: [PATCH 361/536] Remove output --- docs/docsite/rst/command_guide/cheatsheet.rst | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 041634b596b..7dcd2b21ade 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -114,18 +114,11 @@ ansible-doc .. code-block:: bash ansible-doc -F - add_host /usr/lib/python3/dist-packages/ansible/modules/add_host.py - amazon.aws.aws_az_facts /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_az_f - amazon.aws.aws_az_info /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_az_i - amazon.aws.aws_caller_facts /usr/lib/python3/dist-packages/ansible_collections/amazon/aws/plugins/modules/aws_call ..# -* List available plugins: +* Show available plugins: .. code-block:: bash ansible-doc -t module -l - amazon.aws.autoscaling_group Create or delete AWS AutoScaling Groups - amazon.aws.autoscaling_group_info Gather information about EC2 Auto Scaling Groups in AWS - amazon.aws.aws_az_info Gather information about availability zones in AWS ..# \ No newline at end of file From b18d7a3643deda19519a113cc07873c9fcfba4e0 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 14 May 2024 15:42:27 +0200 Subject: [PATCH 362/536] Add Ansible 10.0.0a3 porting guide. (#1452) --- .../rst/porting_guides/porting_guide_10.rst | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst index df3524ddac7..1cfe8804c39 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -76,6 +76,56 @@ Networking No notable changes +Porting Guide for v10.0.0a3 +=========================== + +Breaking Changes +---------------- + +community.hrobot +~~~~~~~~~~~~~~~~ + +- robot inventory plugin - ``filters`` is now no longer an alias of ``simple_filters``, but a new, different option (https://github.com/ansible-collections/community.hrobot/pull/101). + +Major Changes +------------- + +community.hrobot +~~~~~~~~~~~~~~~~ + +- The ``community.hrobot`` collection now depends on the ``community.library_inventory_filtering_v1`` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with ``ansible-galaxy collection install``, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugin (https://github.com/ansible-collections/community.hrobot/pull/101). + +grafana.grafana +~~~~~~~~~~~~~~~ + +- Add a new config part to configure KeyCloak based auth by @he0s in https://github.com/grafana/grafana-ansible-collection/pull/191 +- Add promtail role by @voidquark in https://github.com/grafana/grafana-ansible-collection/pull/197 +- Bump ansible-lint from 24.2.2 to 24.2.3 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/195 + +Removed Features +---------------- + +community.grafana +~~~~~~~~~~~~~~~~~ + +- removed deprecated `message` argument in `grafana_dashboard` + +community.hrobot +~~~~~~~~~~~~~~~~ + +- The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 2.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug (https://github.com/ansible-collections/community.hrobot/pull/101). + +Deprecated Features +------------------- + +amazon.aws +~~~~~~~~~~ + +- cloudformation - the ``template`` parameter has been deprecated and will be removed in a release after 2026-05-01. The ``template_body`` parameter can be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). + Porting Guide for v10.0.0a2 =========================== From 5ad52c1eae875a1dc6f256afb75480cfa223c7e9 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 14 May 2024 17:24:36 +0100 Subject: [PATCH 363/536] edits and suggestions --- .../rst/playbook_guide/playbook_pathing.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index 490ab49f2ac..2d351b7a011 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -30,20 +30,26 @@ Specifically, Ansible tries to find the file in the following order: 1. In the current role. - 1. In its appropriate subdirectory—"files", "vars", "templates" or "tasks", depending on the kind of file Ansible is searching for. + 1. In its appropriate subdirectory: "files", "vars", "templates", or "tasks"; depending on the kind of file Ansible is searching for. 2. Directly in its directory. - + 2. Like 1, in the parent role that called into this current role with ``include_role``, ``import_role``, or with a role dependency. If the parent role has its own parent role, Ansible will repeat this step with that role. 3. Like 1, in the current task file's directory. 4. Like 1, in the current play file's directory. Ansible does not search for local files in the current working directory; in other words, the directory from which you execute Ansible. -.. note:: The current working directory might vary depending on the connection plugin and if the action is local or remote. For the remote it is normally the directory on which the login shell puts the user. For local it is either the directory you executed ansible from or in some cases the playbook directory. +.. note:: -.. note:: When resolving local relative paths for tasks files, Ansible uses the context of the role that includes tasks with an ``include_role`` or ``import_role`` statement. If you import the tasks with ``include_task``, or ``import_task`` statements, Ansible uses the context of the importing file. + * The current working directory might vary depending on the connection plugin and if the action is local or remote. + For the remote it is normally the directory on which the login shell puts the user. + For local it is either the directory you executed ansible from or in some cases the playbook directory. + * Search path context is additive, meaning that Ansible uses a "stack" of contexts when resolving file paths. + When resolving local relative paths for files in tasks, the context of the role that includes tasks with an ``include_role`` or ``import_role`` statement gets highest precedence in the stack. + If you import the tasks with ``include_task``, or ``import_task`` statements, Ansible uses the context of the importing file. Troubleshooting search paths ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When you execute Ansible, the variable ``ansible_search_path`` will contain the paths searched, in the order they were searched in but without listing their subdirectories. If you run Ansible in verbosity level 5 by passing the ``-vvvvv`` argument, Ansible will report each directory as it searches, except when it searches for a tasks file. +When you execute Ansible, the variable ``ansible_search_path`` will contain the paths searched, in the order they were searched in but without listing their subdirectories. +If you run Ansible in verbosity level 5 by passing the ``-vvvvv`` argument, Ansible will report each directory as it searches, except when it searches for a tasks file. From 48cf2aed6d20634f2cc8507140cfb87a9207bc63 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 14 May 2024 18:29:45 +0100 Subject: [PATCH 364/536] revert subheading --- docs/docsite/rst/playbook_guide/playbook_pathing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index 2d351b7a011..4073ed0743d 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -21,8 +21,8 @@ Task paths Relative paths used in a task typically refer to remote files and directories on the managed nodes. However, paths passed to lookup plugins and some paths used in action plugins such as the "src" path for the :ansplugin:`template ` and :ansplugin:`copy ` modules refer to local files and directories on the control node. -How plugins resolve local relative paths ----------------------------------------- +Resolving local relative paths +------------------------------ When you specify a relative path for a local file, Ansible will try to find that file first in the current task's role, then in other roles that included or depend on the current role, then relative to the file in which the task is defined, and finally relative to the current play. It will take the first matching file that it finds. This way, if multiple files with the same file name exist, Ansible will find the file that is closest to the current task and that is most likely to be file you wanted. From 83b7c122ed48ae2844eea867650b7d880ef026ab Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 16 May 2024 07:42:11 +0200 Subject: [PATCH 365/536] Update community topics links (#1451) * Update community topics links * fix * fix * fix * Update docs/docsite/rst/community/contributor_path.rst Co-authored-by: Don Naro * Fix --------- Co-authored-by: Don Naro --- .../collection_requirements.rst | 4 ++-- docs/docsite/rst/community/communication.rst | 12 +++++++----- docs/docsite/rst/community/contributor_path.rst | 6 +++--- .../docsite/rst/community/maintainers_guidelines.rst | 2 +- .../steering/community_steering_committee.rst | 6 +++++- .../community/steering/community_topics_workflow.rst | 4 +--- .../steering/steering_committee_membership.rst | 2 +- .../steering/steering_committee_past_members.rst | 2 +- .../rst/community/steering/steering_index.rst | 2 +- 9 files changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 581ae8d60fc..f682894f100 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -1,7 +1,7 @@ .. THIS DOCUMENT IS OWNED BY THE ANSIBLE COMMUNITY STEERING COMMITTEE. ALL CHANGES MUST BE APPROVED BY THE STEERING COMMITTEE! For small changes (fixing typos, language errors, etc.) create a PR and ping @ansible/steering-committee. - For other changes, create a discussion in https://github.com/ansible-community/community-topics/ to discuss the changes. + For other changes, create a :ref:`topic` on the Forum to discuss the changes. (Creating a draft PR for this file and mentioning it in the community topic is also OK.) .. _collections_requirements: @@ -23,7 +23,7 @@ This section provides help, advice, and guidance on making sure your collections .. 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. + `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 :ref:`community topic` for discussion and a final vote. Feedback and communications ============================== diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 0a47bc5b582..079b296a2f4 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -194,16 +194,18 @@ If you also need a real-time chat channel, you can `request one `_ uses the `community-topics repository `_ to asynchronously discuss with the Community and vote on Community topics in corresponding issues. +The :ref:`Ansible Community Steering Committee` uses the :ref:`ansible_forum` to asynchronously discuss with the Community and vote on Community topics. -Create a new issue in the `repository `_ if you want to discuss an idea that impacts any of the following: +Create a `new topic `_ if you want to discuss an idea that impacts any of the following: * Ansible Community -* Community collection best practices and `requirements `_ -* `Community collection inclusion policy `_ -* `The Community governance `_ +* Community collection best practices and :ref:`requirements` +* :ref:`Community collection inclusion policy` +* :ref:`The Community governance` * Other proposals of importance that need the Committee or overall Ansible community attention +See the `Community topics workflow `_ to learn more. + Ansible Automation Platform support questions ============================================= diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst index d3a57e54311..a5171c0af04 100644 --- a/docs/docsite/rst/community/contributor_path.rst +++ b/docs/docsite/rst/community/contributor_path.rst @@ -82,7 +82,7 @@ See :ref:`communication` for ways to communicate and engage with the Ansible com Teach others ============ -Share your experience with other contributors through :ref:`improving documentation`, answering questions from other contributors and users on :ref:`Matrix/Libera.Chat IRC`, giving advice on issues and pull requests, and discussing `Community Topics `_. +Share your experience with other contributors through :ref:`improving documentation`, answering questions from other contributors and users on :ref:`Matrix/Libera.Chat IRC`, giving advice on issues and pull requests, and discussing topics on the :ref:`ansible_forum`. Become a collection maintainer =============================== @@ -105,10 +105,10 @@ Become a steering committee member You do NOT have to be a programmer to become a steering committee member. -The :ref:`Steering Committee ` member status reflects the highest level of trust which allows contributors to lead the project by making very important `decisions `_ for the Ansible project. The Committee members are the community leaders who shape the project's future and the future of automation in the IT world in general. +The :ref:`Steering Committee ` member status reflects the highest level of trust and allows contributors to lead the project by making important decisions for the Ansible project. The Committee members are community leaders who shape the project's future and the future of automation in the IT world in general. To reach the status, as the current Committee members did before getting it, along with the things mentioned in this document, you should: -* Subscribe to, comment on, and vote on the `Community Topics `_. +* Subscribe to, comment on, and vote on the `community topics`. * Propose your topics. * If time permits, join the `Community meetings `_. Note this is **NOT** a requirement. diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst index c85f8a21b5e..af4912b57da 100644 --- a/docs/docsite/rst/community/maintainers_guidelines.rst +++ b/docs/docsite/rst/community/maintainers_guidelines.rst @@ -70,7 +70,7 @@ See the :ref:`Communication guide ` to learn more about real- Community Topics ---------------- -The Community and the `Steering Committee `_ asynchronously discuss and vote on the `Community Topics `_ which impact the whole project or its parts including collections and packaging. +The Community and the :ref:`Steering Committee ` asynchronously discuss and vote on the :ref:`community topics` which impact the whole project or its parts including collections and packaging. Share your opinion and vote on the topics to help the community make the best decisions. diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index 8869c297365..3bdbfba2b20 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -70,12 +70,14 @@ John Barker (`gundalow `_) has been elected by the Committee members are selected based on their active contribution to the Ansible Project and its community. See :ref:`community_steering_guidelines` to learn details. +.. _creating_community_topic: + Creating new policy proposals & inclusion requests ---------------------------------------------------- The Committee uses the `Ansible Forum `_ to asynchronously discuss with the Community and vote on the proposals in corresponding `community topics `_. -You can create a `community topic `_ if you want to discuss an idea that impacts any of the following: +You can `create a community topic `_ (make sure you use the ``Project Discussions`` category and the ``community-wg`` tag) if you want to discuss an idea that impacts any of the following: * Ansible Community * Community collection best practices and requirements @@ -98,6 +100,8 @@ Depending on a topic you want to discuss with the Community and the Committee, a * :ref:`collections_requirements`. * `Ansible Collection Inclusion Checklist `_. +.. _community_topics_workflow: + Community topics workflow ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/docsite/rst/community/steering/community_topics_workflow.rst b/docs/docsite/rst/community/steering/community_topics_workflow.rst index 5cc0a0ead50..dd2f1b2024e 100644 --- a/docs/docsite/rst/community/steering/community_topics_workflow.rst +++ b/docs/docsite/rst/community/steering/community_topics_workflow.rst @@ -4,8 +4,6 @@ For other changes, create a `community topic `_ to discuss them. (Creating a draft PR for this file and mentioning it in the community topic is also OK.) -.. _community_topics_workflow: - Ansible community topics workflow ================================= @@ -118,7 +116,7 @@ Implementation stage * Checks if there is a corresponding milestone in the `ansible-build-data `_ repository. If there is no milestone, the person creates it. - * Creates an issue in ansible-build-data that references the topic in community-topics, and adds it to the milestone. + * Creates an issue in ansible-build-data that references the :ref:`community topic`, and adds it to the milestone. Tools ----- diff --git a/docs/docsite/rst/community/steering/steering_committee_membership.rst b/docs/docsite/rst/community/steering/steering_committee_membership.rst index d566ebbd821..0825a728dda 100644 --- a/docs/docsite/rst/community/steering/steering_committee_membership.rst +++ b/docs/docsite/rst/community/steering/steering_committee_membership.rst @@ -1,7 +1,7 @@ .. THIS DOCUMENT IS OWNED BY THE ANSIBLE COMMUNITY STEERING COMMITTEE. ALL CHANGES MUST BE APPROVED BY THE STEERING COMMITTEE! For small changes (fixing typos, language errors, etc.) create a PR and ping @ansible/steering-committee. - For other changes, create a discussion in https://github.com/ansible-community/community-topics/ to discuss the changes. + For other changes, create a :ref:`community topic` to discuss the changes. (Creating a draft PR for this file and mentioning it in the community topic is also OK.) .. _community_steering_guidelines: diff --git a/docs/docsite/rst/community/steering/steering_committee_past_members.rst b/docs/docsite/rst/community/steering/steering_committee_past_members.rst index f193c39a230..e1960857483 100644 --- a/docs/docsite/rst/community/steering/steering_committee_past_members.rst +++ b/docs/docsite/rst/community/steering/steering_committee_past_members.rst @@ -1,7 +1,7 @@ .. THIS DOCUMENT IS OWNED BY THE ANSIBLE COMMUNITY STEERING COMMITTEE. ALL CHANGES MUST BE APPROVED BY THE STEERING COMMITTEE! For small changes (fixing typos, language errors, etc.) create a PR and ping @ansible/steering-committee. - For other changes, create a discussion in https://github.com/ansible-community/community-topics/ to discuss the changes. + For other changes, create a :ref:`community topic` to discuss the changes. (Creating a draft PR for this file and mentioning it in the community topic is also OK.) .. _steering_past_members: diff --git a/docs/docsite/rst/community/steering/steering_index.rst b/docs/docsite/rst/community/steering/steering_index.rst index 877324072b7..0a0f04c183f 100644 --- a/docs/docsite/rst/community/steering/steering_index.rst +++ b/docs/docsite/rst/community/steering/steering_index.rst @@ -1,7 +1,7 @@ .. THIS DOCUMENT IS OWNED BY THE ANSIBLE COMMUNITY STEERING COMMITTEE. ALL CHANGES MUST BE APPROVED BY THE STEERING COMMITTEE! For small changes (fixing typos, language errors, etc.) create a PR and ping @ansible/steering-committee. - For other changes, create a discussion in https://github.com/ansible-community/community-topics/ to discuss the changes. + For other changes, create a :ref:`community topic` to discuss the changes. (Creating a draft PR for this file and mentioning it in the community topic is also OK.) .. _community_steering_committee: From 9156c9d863a8235dd95a7cb6b9fa0eaed041d87e Mon Sep 17 00:00:00 2001 From: simeononsecurity <4913771+simeononsecurity@users.noreply.github.com> Date: Thu, 16 May 2024 12:56:29 -0500 Subject: [PATCH 366/536] Remove depreciated platforms reference (#1458) Per https://github.com/ansible/ansible/issues/82453 --- docs/docsite/rst/galaxy/user_guide.rst | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/docsite/rst/galaxy/user_guide.rst b/docs/docsite/rst/galaxy/user_guide.rst index aaa400334c2..1caaef4f1cf 100644 --- a/docs/docsite/rst/galaxy/user_guide.rst +++ b/docs/docsite/rst/galaxy/user_guide.rst @@ -347,16 +347,6 @@ The following shows an example ``meta/main.yml`` file with dependent roles: company: "Midwestern Mac, LLC" license: "license (BSD, MIT)" min_ansible_version: 2.4 - platforms: - - name: EL - versions: - - all - - name: Debian - versions: - - all - - name: Ubuntu - versions: - - all galaxy_tags: - web - system From 9f8a12814d8d97b4bad8b1e954e52fcf9cd989ba Mon Sep 17 00:00:00 2001 From: Don Naro Date: Fri, 17 May 2024 10:25:56 +0100 Subject: [PATCH 367/536] Update docs/docsite/rst/playbook_guide/playbook_pathing.rst Co-authored-by: Sandra McCann --- docs/docsite/rst/playbook_guide/playbook_pathing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbook_pathing.rst b/docs/docsite/rst/playbook_guide/playbook_pathing.rst index 4073ed0743d..efc226df507 100644 --- a/docs/docsite/rst/playbook_guide/playbook_pathing.rst +++ b/docs/docsite/rst/playbook_guide/playbook_pathing.rst @@ -43,7 +43,7 @@ Ansible does not search for local files in the current working directory; in oth * The current working directory might vary depending on the connection plugin and if the action is local or remote. For the remote it is normally the directory on which the login shell puts the user. - For local it is either the directory you executed ansible from or in some cases the playbook directory. + For local it is either the directory you executed Ansible from or in some cases the playbook directory. * Search path context is additive, meaning that Ansible uses a "stack" of contexts when resolving file paths. When resolving local relative paths for files in tasks, the context of the role that includes tasks with an ``include_role`` or ``import_role`` statement gets highest precedence in the stack. If you import the tasks with ``include_task``, or ``import_task`` statements, Ansible uses the context of the importing file. From bfbea11f84e436809b741e326681ab4dab7db55f Mon Sep 17 00:00:00 2001 From: Don Naro Date: Fri, 17 May 2024 10:27:52 +0100 Subject: [PATCH 368/536] Update docs/docsite/rst/playbook_guide/playbooks_loops.rst --- docs/docsite/rst/playbook_guide/playbooks_loops.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index c183d19f20f..10f7a83601c 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -277,7 +277,7 @@ You can combine the ``until`` keyword with ``loop`` or ``with_``. The re Retrying a task with timeout ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When you use ``timeout`` in a loop, it applies per retry attempt. See :ref:`TASK_TIMEOUT ` for more details. +When you use the ``timeout`` keyword in a loop, it applies to each attempt of the task action. See :ref:`TASK_TIMEOUT ` for more details. If the task action execution exceeds the ``timeout``, the retry process is stopped. From 0bedcea8aa56a7b17b1233669e99e7cdef5c46eb Mon Sep 17 00:00:00 2001 From: Don Naro Date: Fri, 17 May 2024 10:36:04 +0100 Subject: [PATCH 369/536] make it a note --- docs/docsite/rst/playbook_guide/playbooks_loops.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index 10f7a83601c..95e9e3167d2 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -274,12 +274,9 @@ You can combine the ``until`` keyword with ``loop`` or ``with_``. The re delay: 1 until: "uri_output.status == 200" -Retrying a task with timeout -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When you use the ``timeout`` keyword in a loop, it applies to each attempt of the task action. See :ref:`TASK_TIMEOUT ` for more details. +.. note:: -If the task action execution exceeds the ``timeout``, the retry process is stopped. + When you use the ``timeout`` keyword in a loop, it applies to each attempt of the task action. See :ref:`TASK_TIMEOUT ` for more details. .. _loop_over_inventory: From b64c0de0ad97b303b1747ae389caed3c12b876ea Mon Sep 17 00:00:00 2001 From: Don Naro Date: Fri, 17 May 2024 10:59:07 +0100 Subject: [PATCH 370/536] Update docs/docsite/rst/command_guide/cheatsheet.rst --- docs/docsite/rst/command_guide/cheatsheet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 7dcd2b21ade..59ddaf5dc9d 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -114,7 +114,7 @@ ansible-doc .. code-block:: bash ansible-doc -F - ..# + #... * Show available plugins: From 41f3bbfcc40f794be2965c080d96fe33f69dd5ae Mon Sep 17 00:00:00 2001 From: Don Naro Date: Fri, 17 May 2024 10:59:14 +0100 Subject: [PATCH 371/536] Update docs/docsite/rst/command_guide/cheatsheet.rst --- docs/docsite/rst/command_guide/cheatsheet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/command_guide/cheatsheet.rst b/docs/docsite/rst/command_guide/cheatsheet.rst index 59ddaf5dc9d..cb55b5366e7 100644 --- a/docs/docsite/rst/command_guide/cheatsheet.rst +++ b/docs/docsite/rst/command_guide/cheatsheet.rst @@ -121,4 +121,4 @@ ansible-doc .. code-block:: bash ansible-doc -t module -l - ..# \ No newline at end of file + #... \ No newline at end of file From b628f3825bf36b5a53aaabe349d1925e94486421 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 19 May 2024 00:06:04 +0000 Subject: [PATCH 372/536] ci: refresh dev dependencies --- tests/formatters.txt | 2 +- tests/typing.txt | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 0111fc98952..92c8b534a5e 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -16,7 +16,7 @@ packaging==24.0 # via black pathspec==0.12.1 # via black -platformdirs==4.2.1 +platformdirs==4.2.2 # via black tomli==2.0.1 # via black diff --git a/tests/typing.txt b/tests/typing.txt index 66a772aedf0..2430cd37863 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -52,7 +52,7 @@ packaging==24.0 # via # -r tests/../hacking/tagger/requirements.txt # nox -platformdirs==4.2.1 +platformdirs==4.2.2 # via virtualenv pycparser==2.22 # via cffi @@ -90,7 +90,7 @@ urllib3==2.2.1 # via # pygithub # requests -virtualenv==20.26.1 +virtualenv==20.26.2 # via nox wrapt==1.16.0 # via deprecated From 85eb8610ca6c2ad85b02418aa747452a2bfac312 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 20 May 2024 15:24:03 +0200 Subject: [PATCH 373/536] Fix list. --- .../rst/dev_guide/developing_modules_documenting.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index 9f0271afb9e..ed07df827bd 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -336,11 +336,12 @@ The parameters for these formatting functions can use escaping with backslashes: Rules for using ``O()`` and ``RV()`` are very strict. You must follow syntax rules so that documentation renderers can create hyperlinks for the options and return values, respectively. The allowed syntaxes are as follows: -- To reference an option for the current plugin/module, or the entrypoint of the current role (inside role entrypoint documentation), use ``O(option)`` and ``O(option=name)``. -- To reference an option for another entrypoint ``entrypoint`` from inside role documentation, use ``O(entrypoint:option)`` and ``O(entrypoint:option=name)``. The entrypoint information can be ignored by the documentation renderer, turned into a link to that entrypoint, or even directly to the option of that entrypoint. -- To reference an option for *another* plugin/module ``plugin.fqcn.name`` of type ``type``, use ``O(plugin.fqcn.name#type:option)`` and ``O(plugin.fqcn.name#type:option=name)``. For modules, use ``type=module``. The FQCN and plugin type can be ignored by the documentation renderer, turned into a link to that plugin, or even directly to the option of that plugin. -- To reference an option for entrypoint ``entrypoint`` of *another* role ``role.fqcn.name``, use ``O(role.fqcn.name#role:entrypoint:option)`` and ``O(role.fqcn.name#role:entrypoint:option=name)``. The FQCN and entrypoint information can be ignored by the documentation renderer, turned into a link to that entrypoint, or even directly to the option of that entrypoint. -- To reference options that do not exist (for example, options that were removed in an earlier version), use ``O(ignore:option)`` and ``O(ignore:option=name)``. The ``ignore:`` part will not be shown to the user by documentation rendering. + +* To reference an option for the current plugin/module, or the entrypoint of the current role (inside role entrypoint documentation), use ``O(option)`` and ``O(option=name)``. +* To reference an option for another entrypoint ``entrypoint`` from inside role documentation, use ``O(entrypoint:option)`` and ``O(entrypoint:option=name)``. The entrypoint information can be ignored by the documentation renderer, turned into a link to that entrypoint, or even directly to the option of that entrypoint. +* To reference an option for *another* plugin/module ``plugin.fqcn.name`` of type ``type``, use ``O(plugin.fqcn.name#type:option)`` and ``O(plugin.fqcn.name#type:option=name)``. For modules, use ``type=module``. The FQCN and plugin type can be ignored by the documentation renderer, turned into a link to that plugin, or even directly to the option of that plugin. +* To reference an option for entrypoint ``entrypoint`` of *another* role ``role.fqcn.name``, use ``O(role.fqcn.name#role:entrypoint:option)`` and ``O(role.fqcn.name#role:entrypoint:option=name)``. The FQCN and entrypoint information can be ignored by the documentation renderer, turned into a link to that entrypoint, or even directly to the option of that entrypoint. +* To reference options that do not exist (for example, options that were removed in an earlier version), use ``O(ignore:option)`` and ``O(ignore:option=name)``. The ``ignore:`` part will not be shown to the user by documentation rendering. Option names can refer to suboptions by listing the path to the option separated by dots. For example, if you have an option ``foo`` with suboption ``bar``, then you must use ``O(foo.bar)`` to reference that suboption. You can add array indications like ``O(foo[].bar)`` or even ``O(foo[-1].bar)`` to indicate specific list elements. Everything between ``[`` and ``]`` pairs will be ignored to determine the real name of the option. For example, ``O(foo[foo | length - 1].bar[])`` results in the same link as ``O(foo.bar)``, but the text ``foo[foo | length - 1].bar[]`` displays instead of ``foo.bar``. From b82d2109a9d12756d16eabe918ee893908914eb1 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Mon, 20 May 2024 19:11:17 +0200 Subject: [PATCH 374/536] collection_requirements: update community topic links (#1421) * collection_requirements: update community topic links * Add forum * Update --- .../collection_requirements.rst | 10 ++++------ docs/docsite/rst/community/communication.rst | 1 + 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index f682894f100..664b7ba607b 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -15,7 +15,6 @@ This section describes the requirements for maintainers of Ansible community col .. contents:: :local: - Overview ======== @@ -37,17 +36,16 @@ As with any project it is very important that we get feedback from users, contri Keeping informed ================ -You should subscribe to: +To track changes that affect collections: -* 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. +* Join the `Collection Maintainers & Contributors forum group `_. +* Subscribe to 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. @@ -213,7 +211,7 @@ When using ``version_added`` in the documentation: 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 requests) reports must always be accepted. -* Collections are encouraged to use z:ref:`links and formatting macros ` +* Collections are encouraged to use :ref:`links and formatting macros ` * Including a :ref:`RETURN ` block for modules is strongly encouraged but not required. .. _coll_workflow: diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 079b296a2f4..ffb6f3d1ed2 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -190,6 +190,7 @@ request it in the `forum topic `_. +.. _community_topics: Ansible Community Topics ======================== From b737e3007cf76a8c98b77954d415cad529a59b5f Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Mon, 20 May 2024 15:11:20 -0400 Subject: [PATCH 375/536] update version switcher to suppor 2.17 (#1464) --- docs/docsite/rst/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 339382948c2..b3a7a5db17d 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -239,7 +239,7 @@ 'current_version': version, 'latest_version': ( 'devel' if tags.has('all') else - '2.16' if tags.has('core_lang') or tags.has('core') else + '2.17' if tags.has('core_lang') or tags.has('core') else '9' if tags.has('ansible') else '' ), @@ -247,7 +247,7 @@ 'available_versions': ( ('devel',) if tags.has('all') else ('2.15_ja', '2.14_ja', '2.13_ja',) if tags.has('core_lang') else - ('2.16', '2.15', '2.14', 'devel',) if tags.has('core') else + ('2.17', '2.16', '2.15', 'devel',) if tags.has('core') else ('latest', '2.9', 'devel') if tags.has('ansible') else '' ), From ce3ae496d94a21ee1a8133e699658f53b409d301 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Tue, 21 May 2024 12:03:55 +0200 Subject: [PATCH 376/536] Add Ansible community 9.6.0 porting guide (#1493) --- .../rst/porting_guides/porting_guide_9.rst | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 5cb14161635..7feefabb34c 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -84,6 +84,60 @@ Porting custom scripts Networking ========== +Porting Guide for v9.6.0 +======================== + +Added Collections +----------------- + +- kaytus.ksmanage (version 1.2.1) + +Known Issues +------------ + +community.docker +~~~~~~~~~~~~~~~~ + +- Please note that the fix for requests 2.32.0 included in community.docker 3.10.1 only + fixes problems with the *vendored* Docker SDK for Python code. Modules and plugins that + use Docker SDK for Python can still fail due to the SDK currently being incompatible + with requests 2.32.0. + + If you still experience problems with requests 2.32.0, such as error messages like + ``Not supported URL scheme http+docker``, please restrict requests to ``<2.32.0``. + +Breaking Changes +---------------- + +community.ciscosmb +~~~~~~~~~~~~~~~~~~ + +- in facts of interface 'bandwith' changed to 'bandwidth' + +Deprecated Features +------------------- + +amazon.aws +~~~~~~~~~~ + +- cloudformation - the ``template`` parameter has been deprecated and will be removed in a release after 2026-05-01. The ``template_body`` parameter can be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). + +community.crypto +~~~~~~~~~~~~~~~~ + +- acme documentation fragment - the default ``community.crypto.acme[.documentation]`` docs fragment is deprecated and will be removed from community.crypto 3.0.0. Replace it with both the new ``community.crypto.acme.basic`` and ``community.crypto.acme.account`` fragments (https://github.com/ansible-collections/community.crypto/pull/735). +- acme.backends module utils - the ``get_cert_information()`` method for a ACME crypto backend must be implemented from community.crypto 3.0.0 on (https://github.com/ansible-collections/community.crypto/pull/736). +- crypto.module_backends.common module utils - the ``crypto.module_backends.common`` module utils is deprecated and will be removed from community.crypto 3.0.0. Use the improved ``argspec`` module util instead (https://github.com/ansible-collections/community.crypto/pull/749). + +community.docker +~~~~~~~~~~~~~~~~ + +- docker_compose - the Docker Compose v1 module is deprecated and will be removed from community.docker 4.0.0. Please migrate to the ``community.docker.docker_compose_v2`` module, which works with Docker Compose v2 (https://github.com/ansible-collections/community.docker/issues/823, https://github.com/ansible-collections/community.docker/pull/833). +- various modules and plugins - the ``ssl_version`` option has been deprecated and will be removed from community.docker 4.0.0. It has already been removed from Docker SDK for Python 7.0.0, and was only necessary in the past to work around SSL/TLS issues (https://github.com/ansible-collections/community.docker/pull/853). + Porting Guide for v9.5.1 ======================== From dac4787e114a1e6dbf9f778f8cfbd57ccca5afee Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Tue, 21 May 2024 12:04:17 +0200 Subject: [PATCH 377/536] Add Ansible community 10.0.0b1 porting guide (#1494) --- .../rst/porting_guides/porting_guide_10.rst | 165 +++++++++++++++++- 1 file changed, 160 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst index 1cfe8804c39..6a58fcd2d38 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -76,6 +76,166 @@ Networking No notable changes +Porting Guide for v10.0.0b1 +=========================== + +Known Issues +------------ + +community.docker +~~~~~~~~~~~~~~~~ + +- Please note that the fix for requests 2.32.0 included in community.docker 3.10.1 only + fixes problems with the *vendored* Docker SDK for Python code. Modules and plugins that + use Docker SDK for Python can still fail due to the SDK currently being incompatible + with requests 2.32.0. + + If you still experience problems with requests 2.32.0, such as error messages like + ``Not supported URL scheme http+docker``, please restrict requests to ``<2.32.0``. + +Breaking Changes +---------------- + +amazon.aws +~~~~~~~~~~ + +- amazon.aws collection - Support for ansible-core < 2.15 has been dropped (https://github.com/ansible-collections/amazon.aws/pull/2093). +- iam_role - ``iam_role.assume_role_policy_document`` is no longer converted from CamelCase to snake_case (https://github.com/ansible-collections/amazon.aws/pull/2040). +- iam_role_info - ``iam_role.assume_role_policy_document`` is no longer converted from CamelCase to snake_case (https://github.com/ansible-collections/amazon.aws/pull/2040). +- kms_key - the ``policies`` return value has been renamed to ``key_policies`` the contents has not been changed (https://github.com/ansible-collections/amazon.aws/pull/2040). +- kms_key_info - the ``policies`` return value has been renamed to ``key_policies`` the contents has not been changed (https://github.com/ansible-collections/amazon.aws/pull/2040). +- lambda_event - | ``batch_size`` no longer defaults to 100. According to the boto3 API (https://boto3.amazonaws.com/v1/documentation/api/1.26.78/reference/services/lambda.html#Lambda.Client.create_event_source_mapping), ``batch_size`` defaults to 10 for sqs sources and to 100 for stream sources (https://github.com/ansible-collections/amazon.aws/pull/2025). + +community.aws +~~~~~~~~~~~~~ + +- The community.aws collection has dropped support for ``botocore<1.29.0`` and ``boto3<1.26.0``. Most modules will continue to work with older versions of the AWS SDK, however compatability with older versions of the SDK is not guaranteed and will not be tested. When using older versions of the SDK a warning will be emitted by Ansible (https://github.com/ansible-collections/amazon.aws/pull/1763). +- aws_region_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.aws_region_info``. +- aws_s3_bucket_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.aws_s3_bucket_info``. +- community.aws collection - Support for ansible-core < 2.15 has been dropped (https://github.com/ansible-collections/community.aws/pull/2074). +- community.aws collection - due to the AWS SDKs announcing the end of support for Python less than 3.7 (https://aws.amazon.com/blogs/developer/python-support-policy-updates-for-aws-sdks-and-tools/) support for Python less than 3.7 by this collection wss been deprecated in release 6.0.0 and removed in release 7.0.0. (https://github.com/ansible-collections/amazon.aws/pull/1763). +- iam_access_key - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_access_key``. +- iam_access_key_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_access_key_info``. +- iam_group - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_group`` (https://github.com/ansible-collections/community.aws/pull/1945). +- iam_managed_policy - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_managed_policy`` (https://github.com/ansible-collections/community.aws/pull/1954). +- iam_mfa_device_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_mfa_device_info`` (https://github.com/ansible-collections/community.aws/pull/1953). +- iam_password_policy - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_password_policy``. +- iam_role - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_role`` (https://github.com/ansible-collections/community.aws/pull/1948). +- iam_role_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.iam_role_info`` (https://github.com/ansible-collections/community.aws/pull/1948). +- s3_bucket_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.s3_bucket_info``. +- sts_assume_role - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.sts_assume_role``. + +community.dns +~~~~~~~~~~~~~ + +- The default for the ``txt_character_encoding`` options in various modules and plugins changed from ``octal`` to ``decimal`` (https://github.com/ansible-collections/community.dns/pull/196). +- inventory plugins - ``filters`` is now no longer an alias of ``simple_filters``, but a new, different option (https://github.com/ansible-collections/community.dns/pull/196). +- inventory plugins - the ``plugin`` option is now required (https://github.com/ansible-collections/community.dns/pull/196). +- lookup, lookup_as_dict - the default for ``search`` changed from ``false`` (implicit default for community.dns 2.x.y) to ``true`` (https://github.com/ansible-collections/community.dns/issues/200, https://github.com/ansible-collections/community.dns/pull/201). + +community.general +~~~~~~~~~~~~~~~~~ + +- cpanm - the default of the ``mode`` option changed from ``compatibility`` to ``new`` (https://github.com/ansible-collections/community.general/pull/8198). +- django_manage - the module now requires Django >= 4.1 (https://github.com/ansible-collections/community.general/pull/8198). +- django_manage - the module will now fail if ``virtualenv`` is specified but no virtual environment exists at that location (https://github.com/ansible-collections/community.general/pull/8198). +- redfish_command, redfish_config, redfish_info - change the default for ``timeout`` from 10 to 60 (https://github.com/ansible-collections/community.general/pull/8198). + +Major Changes +------------- + +community.dns +~~~~~~~~~~~~~ + +- The ``community.dns`` collection now depends on the ``community.library_inventory_filtering_v1`` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with ``ansible-galaxy collection install``, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugins (https://github.com/ansible-collections/community.dns/pull/196). + +Removed Features +---------------- + +amazon.aws +~~~~~~~~~~ + +- iam_role - the ``iam_role.assume_role_policy_document_raw`` return value has been deprecated. ``iam_role.assume_role_policy_document`` now returns the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). +- iam_role_info - the ``iam_role.assume_role_policy_document_raw`` return value has been deprecated. ``iam_role.assume_role_policy_document`` now returns the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). +- module_utils.policy - the previously deprecated ``sort_json_policy_dict()`` function has been removed, consider using ``compare_policies()`` instead (https://github.com/ansible-collections/amazon.aws/pull/2052). + +community.dns +~~~~~~~~~~~~~ + +- The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 3.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug (https://github.com/ansible-collections/community.dns/pull/196). +- hetzner_dns_record_set, hetzner_dns_record - the deprecated alias ``name`` of the prefix option was removed (https://github.com/ansible-collections/community.dns/pull/196). +- hosttech_dns_records - the redirect to the ``hosttech_dns_record_sets`` module has been removed (https://github.com/ansible-collections/community.dns/pull/196). + +community.general +~~~~~~~~~~~~~~~~~ + +- The deprecated redirects for internal module names have been removed. These internal redirects were extra-long FQCNs like ``community.general.packaging.os.apt_rpm`` that redirect to the short FQCN ``community.general.apt_rpm``. They were originally needed to implement flatmapping; as various tooling started to recommend users to use the long names flatmapping was removed from the collection and redirects were added for users who already followed these incorrect recommendations (https://github.com/ansible-collections/community.general/pull/7835). +- ansible_galaxy_install - the ``ack_ansible29`` and ``ack_min_ansiblecore211`` options have been removed. They no longer had any effect (https://github.com/ansible-collections/community.general/pull/8198). +- cloudflare_dns - remove support for SPF records. These are no longer supported by CloudFlare (https://github.com/ansible-collections/community.general/pull/7782). +- django_manage - support for the ``command`` values ``cleanup``, ``syncdb``, and ``validate`` were removed. Use ``clearsessions``, ``migrate``, and ``check`` instead, respectively (https://github.com/ansible-collections/community.general/pull/8198). +- flowdock - this module relied on HTTPS APIs that do not exist anymore and was thus removed (https://github.com/ansible-collections/community.general/pull/8198). +- mh.mixins.deps module utils - the ``DependencyMixin`` has been removed. Use the ``deps`` module utils instead (https://github.com/ansible-collections/community.general/pull/8198). +- proxmox - the ``proxmox_default_behavior`` option has been removed (https://github.com/ansible-collections/community.general/pull/8198). +- rax* modules, rax module utils, rax docs fragment - the Rackspace modules relied on the deprecated package ``pyrax`` and were thus removed (https://github.com/ansible-collections/community.general/pull/8198). +- redhat module utils - the classes ``Rhsm``, ``RhsmPool``, and ``RhsmPools`` have been removed (https://github.com/ansible-collections/community.general/pull/8198). +- redhat_subscription - the alias ``autosubscribe`` of the ``auto_attach`` option was removed (https://github.com/ansible-collections/community.general/pull/8198). +- stackdriver - this module relied on HTTPS APIs that do not exist anymore and was thus removed (https://github.com/ansible-collections/community.general/pull/8198). +- webfaction_* modules - these modules relied on HTTPS APIs that do not exist anymore and were thus removed (https://github.com/ansible-collections/community.general/pull/8198). + +Deprecated Features +------------------- + +amazon.aws +~~~~~~~~~~ + +- aws_ec2 inventory plugin - removal of the previously deprecated ``include_extra_api_calls`` option has been assigned to release 9.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2040). +- cloudformation - the ``template`` parameter has been deprecated and will be removed in a release after 2026-05-01. The ``template_body`` parameter can be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). +- iam_policy - removal of the previously deprecated ``policies`` return key has been assigned to release 9.0.0. Use the ``policy_names`` return key instead (https://github.com/ansible-collections/amazon.aws/pull/2040). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- rds_param_group - the ``rds_param_group`` module has been renamed to ``rds_instance_param_group``. The usage of the module has not changed. The rds_param_group alias will be removed in version 10.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2058). + +community.aws +~~~~~~~~~~~~~ + +- aws_glue_connection - updated the deprecation for removal of the ``connection_parameters`` return key from ``after 2024-06-01`` to release version ``9.0.0``, it is being replaced by the ``raw_connection_parameters`` key (https://github.com/ansible-collections/community.aws/pull/518). +- ecs_cluster - updated the deprecation for updated default of ``purge_capacity_providers``, the current default of ``False`` will be changed to ``True`` in release ``9.0.0``. To maintain the current behaviour explicitly set ``purge_capacity_providers=False`` (https://github.com/ansible-collections/community.aws/pull/1640). +- ecs_service - updated the deprecation for updated default of ``purge_placement_constraints``, the current default of ``False`` will be changed to ``True`` in release ``9.0.0``. To maintain the current behaviour explicitly set ``purge_placement_constraints=False`` (https://github.com/ansible-collections/community.aws/pull/1716). +- ecs_service - updated the deprecation for updated default of ``purge_placement_strategy``, the current default of ``False`` will be changed to ``True`` in release ``9.0.0``. To maintain the current behaviour explicitly set ``purge_placement_strategy=False`` (https://github.com/ansible-collections/community.aws/pull/1716). + +community.crypto +~~~~~~~~~~~~~~~~ + +- acme documentation fragment - the default ``community.crypto.acme[.documentation]`` docs fragment is deprecated and will be removed from community.crypto 3.0.0. Replace it with both the new ``community.crypto.acme.basic`` and ``community.crypto.acme.account`` fragments (https://github.com/ansible-collections/community.crypto/pull/735). +- acme.backends module utils - the ``get_cert_information()`` method for a ACME crypto backend must be implemented from community.crypto 3.0.0 on (https://github.com/ansible-collections/community.crypto/pull/736). +- crypto.module_backends.common module utils - the ``crypto.module_backends.common`` module utils is deprecated and will be removed from community.crypto 3.0.0. Use the improved ``argspec`` module util instead (https://github.com/ansible-collections/community.crypto/pull/749). + +community.docker +~~~~~~~~~~~~~~~~ + +- docker_compose - the Docker Compose v1 module is deprecated and will be removed from community.docker 4.0.0. Please migrate to the ``community.docker.docker_compose_v2`` module, which works with Docker Compose v2 (https://github.com/ansible-collections/community.docker/issues/823, https://github.com/ansible-collections/community.docker/pull/833). +- various modules and plugins - the ``ssl_version`` option has been deprecated and will be removed from community.docker 4.0.0. It has already been removed from Docker SDK for Python 7.0.0, and was only necessary in the past to work around SSL/TLS issues (https://github.com/ansible-collections/community.docker/pull/853). + +community.general +~~~~~~~~~~~~~~~~~ + +- MH DependencyCtxMgr module_utils - deprecate ``module_utils.mh.mixin.deps.DependencyCtxMgr`` in favour of ``module_utils.deps`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.AnsibleModule`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.DependencyCtxMgr`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.StateMixin`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.VarDict,`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.VarMeta`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.VarsMixin`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate use of ``VarsMixin`` in favor of using the ``VardDict`` module_utils (https://github.com/ansible-collections/community.general/pull/8226). +- ModuleHelper vars module_utils - bump deprecation of ``VarMeta``, ``VarDict`` and ``VarsMixin`` to version 11.0.0 (https://github.com/ansible-collections/community.general/pull/8226). +- apt_rpm - the behavior of ``state=present`` and ``state=installed`` is deprecated and will change in community.general 11.0.0. Right now the module will upgrade a package to the latest version if one of these two states is used. You should explicitly use ``state=latest`` if you want this behavior, and switch to ``state=present_not_latest`` if you do not want to upgrade the package if it is already installed. In community.general 11.0.0 the behavior of ``state=present`` and ``state=installed`` will change to that of ``state=present_not_latest`` (https://github.com/ansible-collections/community.general/issues/8217, https://github.com/ansible-collections/community.general/pull/8285). +- consul_acl - the module has been deprecated and will be removed in community.general 10.0.0. ``consul_token`` and ``consul_policy`` can be used instead (https://github.com/ansible-collections/community.general/pull/7901). +- django_manage - the ``ack_venv_creation_deprecation`` option has no more effect and will be removed from community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/8198). +- gitlab modules - the basic auth method on GitLab API have been deprecated and will be removed in community.general 10.0.0 (https://github.com/ansible-collections/community.general/pull/8383). +- hipchat callback plugin - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The callback plugin is therefore deprecated and will be removed from community.general 10.0.0 if nobody provides compelling reasons to still keep it (https://github.com/ansible-collections/community.general/issues/8184, https://github.com/ansible-collections/community.general/pull/8189). +- irc - the defaults ``false`` for ``use_tls`` and ``validate_certs`` have been deprecated and will change to ``true`` in community.general 10.0.0 to improve security. You can already improve security now by explicitly setting them to ``true``. Specifying values now disables the deprecation warning (https://github.com/ansible-collections/community.general/pull/7578). + Porting Guide for v10.0.0a3 =========================== @@ -514,11 +674,6 @@ community.docker - docker_container - the default ``ignore`` for the ``image_name_mismatch`` parameter has been deprecated and will switch to ``recreate`` in community.docker 4.0.0. A deprecation warning will be printed in situations where the default value is used and where a behavior would change once the default changes (https://github.com/ansible-collections/community.docker/pull/703). -community.general -~~~~~~~~~~~~~~~~~ - -- consul_acl - the module has been deprecated and will be removed in community.general 10.0.0. ``consul_token`` and ``consul_policy`` can be used instead (https://github.com/ansible-collections/community.general/pull/7901). - community.hrobot ~~~~~~~~~~~~~~~~ From 44e7c7adedf0da3c6bce13ab96aebcb6132324f8 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 22 May 2024 09:28:09 +0200 Subject: [PATCH 378/536] Update collection_checklist.md links to point to new location (#1505) --- .../collection_contributors/collection_requirements.rst | 2 +- .../rst/community/steering/community_steering_committee.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 664b7ba607b..41bbb035b5e 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -529,7 +529,7 @@ To be included in the `ansible` package, collections must meet the following cri * :ref:`Development conventions `. * `Collection requirements `_ (this document). - * The `Collection Inclusion Criteria Checklist `_ covers most of the criteria from 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. diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index 3bdbfba2b20..2c09cb48ab0 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -98,7 +98,7 @@ Depending on a topic you want to discuss with the Community and the Committee, a * :ref:`code_of_conduct`. * :ref:`collections_requirements`. -* `Ansible Collection Inclusion Checklist `_. +* `Ansible Collection Inclusion Checklist `_. .. _community_topics_workflow: @@ -146,7 +146,7 @@ When reviewing community collection `inclusion requests `_ into a corresponding `discussion `_. +#. A Committee member who conducts the inclusion review copies the `Ansible community collection checklist `_ into a corresponding `discussion `_. #. In the course of the review, the Committee member marks items as completed or leaves a comment saying whether the reviewer expects an issue to be addressed or whether it is optional (for example, it could be **MUST FIX:** or **SHOULD FIX:** under an item). From a16d58566dee7340ae510aa200392916112e7e01 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 22 May 2024 11:02:00 +0200 Subject: [PATCH 379/536] Move Ansible package collection removal process to docs.ansible.com (#1492) * Move Ansible package collection removal process to docs.ansible.com * Fix * Fix * Fix --- .../collection_package_removal.rst | 245 ++++++++++++++++++ .../steering/community_steering_committee.rst | 8 +- docs/docsite/rst/conf.py | 1 + 3 files changed, 253 insertions(+), 1 deletion(-) create mode 100644 docs/docsite/rst/community/collection_contributors/collection_package_removal.rst diff --git a/docs/docsite/rst/community/collection_contributors/collection_package_removal.rst b/docs/docsite/rst/community/collection_contributors/collection_package_removal.rst new file mode 100644 index 00000000000..01e9da48a9e --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_package_removal.rst @@ -0,0 +1,245 @@ +.. + THIS DOCUMENT IS OWNED BY THE ANSIBLE COMMUNITY STEERING COMMITTEE. ALL CHANGES MUST BE APPROVED BY THE STEERING COMMITTEE! + For small changes (fixing typos, language errors, etc.) create a PR and ping @ansible/steering-committee. + For other changes, create a :ref:`topic` on the Forum to discuss the changes. + (Creating a draft PR for this file and mentioning it in the community topic is also OK.) + +.. _removal_from_ansible: + +***************************************************** +Ansible Community Package Collections Removal Process +***************************************************** + +.. contents:: + :local: + +Overview +======== + +Sometimes the Ansible community removes a collection from the Ansible package for stability, legal, or security reasons. This document describes why we might remove a collection from the `Ansible community package `_ (`build data `_). + +In cases of emergency (for example, a serious security vulnerability that is not fixed in a collection) the :ref:`Ansible Community Engineering Steering Committee` can vote on emergency exceptions. In most cases, we follow the rules listed on this page. + +General processes +================= + +The general process of removing a collection follows these steps: + +#. Announcing an upcoming removal of a collection. +#. Removing the collection. +#. When appropriate, re-adding the collection. + + +.. _announce_removal: + +Announcing upcoming removal +--------------------------- + +#. Announce upcoming removal in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). + See the following link for an `example on how to add changelog entries to the Ansible changelog `__. +#. Announce upcoming removal in the collection's issue tracker if possible. +#. Announce upcoming removal in The Bullhorn. + +.. _remove_collection: + +Removing a collection +--------------------- + +To remove a collection from Ansible version X.0.0: + +#. Remove from ``ansible.in`` (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). +#. Remove from ``collection-meta.yaml`` (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). +#. Document actual removal for the first/next alpha of Ansible X.0.0 in the Ansible changelog (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``). + See the following link for an `example on how to add changelog entries to the Ansible changelog `__. + +.. _readd_collection: + +Re-adding a collection +---------------------- + +Re-adding a collection to Ansible works the same as adding it in the first place. See the `process of adding a new collection to Ansible `_ for reference. + +#. Re-add collection to ``ansible.in`` (``https://github.com/ansible-community/ansible-build-data/blob/main//ansible.in``). +#. Re-add collection to ``collection-meta.yaml`` (``https://github.com/ansible-community/ansible-build-data/blob/main//collection-meta.yaml``). +#. If the removal was announced in the Ansible changelog for a version that has not yet been released (``https://github.com/ansible-community/ansible-build-data/blob/main//changelog.yaml``), remove the announcement. + +Broken collections +================== + +The community can remove a collection from the Ansible community package if the collection is broken. + +Identifying and removing a broken collection +-------------------------------------------- + +Conditions for removal +~~~~~~~~~~~~~~~~~~~~~~ + +A collection is considered broken if one of the following conditions is true: + +#. It depends on another collection included in X.0.0 but does not work with the actual version of it that is included, and there is no content in the collection that still works. + +We remove broken collections from Ansible (X+1).0.0 under the following conditions: + +#. The collection seems to be unmaintained and nobody fixes the problems. +#. The plan to remove the collection in the next major Ansible release is publicized at least two months before the (X+1).0.0 release, and at least one month before the first (X+1).0.0 beta release (feature freeze). + +Process +~~~~~~~ + +The announcement mentioned below must state the reasons for the proposed removal and alert maintainers and the Ansible community that, to prevent the removal, the collection urgently needs new maintainers who can fix the problems. + +#. `Announce upcoming removal in Ansible X+1 `_. +#. `Remove collection from Ansible X+1 `_. + +Canceling removal of a broken collection +----------------------------------------- + +Conditions +~~~~~~~~~~ + +#. The issues have to be fixed and a new release (bugfix, minor or major) has to be made before the Ansible X+1 feature freeze. +#. Someone has to promise to maintain the collection and prevent a similar situation at least for some time. + +Process +~~~~~~~ + +#. Update the removal issue in the collection's issue tracker and close the issue. +#. Announce canceled removal in The Bullhorn. +#. `Re-add collection to Ansible X+1 `_. + +Re-adding collection to Ansible +------------------------------- + +Conditions +~~~~~~~~~~ + +Conditions under which the collections can be re-included in the Ansible package without going through the `full inclusion process `_: + +#. The issues have to be fixed and a new release has to be made before the Ansible X+2 feature freeze. +#. Someone has to promise to maintain the collection and prevent a similar situation at least for some time. + +Process +~~~~~~~ + +#. Follow `regular process of adding a new collection to Ansible `_. + +Unmaintained collections +======================== + +Removing a collection that has been explicitly deprecated or abandoned by its (former) maintainers +-------------------------------------------------------------------------------------------------- + +Process +~~~~~~~ + +If the current major release is X and there hasn't been a feature freeze release of the next major version X+1, remove the collection from Y=(X+1).0.0. +If there already has been a feature freeze release of the next major version X+1, remove the collection from Y=(X+2).0.0. + +#. `Announce upcoming removal from the Y Ansible release `_. +#. `Remove collection from the Y Ansible release `_. + +See `the example pull request `_ in the ``ansible-build-data`` repository to learn how to remove the collection. + +Identifying and removing an unmaintained collection that has not been deprecated by its maintainers +--------------------------------------------------------------------------------------------------- + +Conditions for removal +~~~~~~~~~~~~~~~~~~~~~~ + +A collection is considered unmaintained if multiple of the following conditions are satisfied: + +#. There has been no maintainer's activity in the collection repository for several months (for example, pull request merges and releases). +#. CI has stopped passing (or even has not been running) for several months. +#. Bug reports and bugfix PRs start piling up without being reviewed. + +There is no complete formal definition of an unmaintained collection. + +Process +~~~~~~~ + +#. The appearance that the collection is no longer maintained and might be removed from the Ansible package has to be announced both in The Bullhorn and in the collection's issue tracker. +#. At least four weeks after the notice appeared in The Bullhorn and the collection's issue tracker, the Ansible Community Engineering Steering Committee (SC) must look at the collection and vote that it considers it unmaintained. The vote must be open for at least one week. +#. If the SC does not vote that the collection seems to be unmaintained, the process is stopped. The issue needs to be updated accordingly. +#. If X.0.0 will be released next, set Y=X+1. If X.0.0 has already been released, but (X+1).0.0 has not yet been released, set Y=X+2. +#. `Announce upcoming removal from Ansible Y `_. +#. `Remove collection from Ansible Y `_. + +Canceling removal of an unmaintained collection +------------------------------------------------ + +Conditions +~~~~~~~~~~ + +#. Ansible Y has not yet been released. +#. One or multiple maintainers step up, or return, to clean up the collection's state. +#. There have been concrete results made by new maintainers (for example, CI has been fixed, the collection has been released, pull request authors have got meaningful feedback). + +Process +~~~~~~~ + +#. The Steering Committee votes on whether the result is acceptable. +#. A negative vote must come with a good explanation why the clean up work has not been sufficient. In that case, this process stops. +#. If the Steering Committee does not vote against still removing the collection (this includes the case that the vote did not reach quorum), proceed as follows. +#. `Re-add collection to Ansible Y `_. + +Re-adding collection to Ansible +------------------------------- + +There is no simplified process. Once the collection has been removed from Ansible Y.0.0, it needs to go through the full inclusion process to be re-added to the Ansible package. Exceptions are only possible if the Steering Committee votes on them. The Steering Committee can approve or deny a fast re-entry without going through the full review process. + +Collections not satisfying the Collection requirements +====================================================== + +A collection can be removed from the package if it violates one or more of the :ref:`Collection requirements` without resolving the violations within the time allowed. + +This section is not applicable to cases of broken or unmaintained collections. Instead, see the corresponding paragraphs of this document. + +Identifying and removing a collection +------------------------------------- + +Conditions for removal +~~~~~~~~~~~~~~~~~~~~~~ + +#. A collection violates one or more of the :ref:`Collection requirements`. +#. Collection maintainers have not fixed the violations and have not released a fixed version of the collection within the time period established by this document. + +Process +~~~~~~~ + +#. Any community member who finds a collection that violates one or more of the :ref:`Collection requirements` may file an issue against said collection's repository. If the reporter is unsure whether something constitutes a violation or believes that the apparently violated guideline is unclear, they should consult with the steering committee by filing a :ref:`community topic` before proceeding. +#. The issue filed against the collection's repository should include the following information: + + * References to the corresponding :ref:`Collection requirements` the collection violates. + * Actions collection maintainers need to do to make the collection comply with the requirements. + +#. A default term for the collection to solve the issue is four weeks since the issue was created. It can vary depending on a requirement violated, SC opinions or other circumstances. +#. If the violation is not fixed or there is a disagreement between the reporter and the maintainers, the reporter or another person creates a :ref:`community topic`. +#. Two SC members check the reported circumstances and confirm in the topic that the violation is present from their point of view, and is one that must be fixed. +#. The Community and SC vote on considering the collection violating the requirements and removing it from the package. The vote must be open for at least one week. +#. If SC votes that the collection does NOT violate the requirements, the process is stopped. The issue needs to be updated accordingly. +#. If X.0.0 will be released next, set Y=X+1. If X.0.0 has already been released, but (X+1).0.0 has not yet been released, set Y=X+2. +#. Announce upcoming removal from Ansible Y in the original issue in the collection's repository. +#. `Announce upcoming removal from Ansible Y `_. +#. `Remove collection from Ansible Y `_. + +Canceling removal +------------------ + +Conditions +~~~~~~~~~~ + +#. Ansible Y has not yet been released. +#. All the requirements violations have been fixed. + +Process +~~~~~~~ + +#. SC votes on whether the result is acceptable. +#. A negative vote must come with a good explanation why the actions done by collection maintainers have not been sufficient. +#. If SC does not vote against the removal of the collection (this includes the case that the vote did not reach quorum), the removal will continue. +#. If SC votes to cancel the removal, `re-add collection to Ansible Y `_. + +Re-adding collection to Ansible +------------------------------- + +There is no simplified process. Once the collection has been removed from Ansible Y.0.0, it needs to go through the full inclusion process to be re-added to the Ansible package. Exceptions are only possible if SC votes on them. SC can approve or deny a fast re-entry without going through the full review process. diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index 2c09cb48ab0..be470618878 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -81,7 +81,7 @@ You can `create a community topic `_. +* :ref:`removal_from_ansible`. .. _community_topics_workflow: @@ -172,6 +173,11 @@ When reviewing community collection `inclusion requests `_. #. Closes the topic. +Collection exclusion workflow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Committee uses the :ref:`removal_from_ansible` to remove collections not satisfying the :ref:`collection_requirements` from the Ansible package. + Community Working Group meetings --------------------------------- diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index b3a7a5db17d..3a7d03d75ae 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -127,6 +127,7 @@ 'community/collection_contributors/collection_test_pr_locally.rst', 'community/collection_contributors/collection_integration_tests.rst', 'community/collection_contributors/collection_integration_running.rst', + 'community/collection_contributors/collection_package_removal.rst', 'community/collection_contributors/collection_reviewing.rst', 'community/collection_contributors/collection_requirements.rst', 'community/collection_contributors/collection_unit_tests.rst', From b1c8ee6518b1b27dc51c243c2e692baab7302f7f Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 22 May 2024 14:42:00 -0400 Subject: [PATCH 380/536] update backport instructions for 2.17 (#1504) --- docs/docsite/rst/community/development_process.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 91847e89421..53e3db1f756 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -206,7 +206,7 @@ Here are some examples: remote_src=True even if mode was not set as a parameter. This failed on filesystems which do not have permission bits (https://github.com/ansible/ansible/issues/29444). -You can find more example changelog fragments in the `changelog directory `_ for the 2.16 release. +You can find more example changelog fragments in the `changelog directory `_ for the 2.17 release. After you have written the changelog fragment for your PR, commit the file and include it with the pull request. @@ -241,7 +241,7 @@ We do **not** backport features. These instructions assume that: - * ``stable-2.16`` is the targeted release branch for the backport + * ``stable-2.17`` is the targeted release branch for the backport * ``https://github.com/ansible/ansible.git`` is configured as a ``git remote`` named ``upstream``. If you do not use a ``git remote`` named ``upstream``, adjust the instructions accordingly. * ``https://github.com//ansible.git`` is configured as a ``git remote`` named ``origin``. If you do not use a ``git remote`` named ``origin``, adjust the instructions accordingly. @@ -250,7 +250,7 @@ We do **not** backport features. .. code-block:: shell git fetch upstream - git checkout -b backport/2.16/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.16 + git checkout -b backport/2.17/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.17 #. Cherry pick the relevant commit SHA from the devel branch into your feature branch, handling merge conflicts as necessary: @@ -264,15 +264,15 @@ We do **not** backport features. .. code-block:: shell - git push origin backport/2.16/[PR_NUMBER_FROM_DEVEL] + git push origin backport/2.17/[PR_NUMBER_FROM_DEVEL] -#. Submit the pull request for ``backport/2.16/[PR_NUMBER_FROM_DEVEL]`` against the ``stable-2.16`` branch +#. Submit the pull request for ``backport/2.17/[PR_NUMBER_FROM_DEVEL]`` against the ``stable-2.17`` branch #. The Release Manager will decide whether to merge the backport PR before the next minor release. There isn't any need to follow up. Just ensure that the automated tests (CI) are green. .. note:: - The branch name ``backport/2.16/[PR_NUMBER_FROM_DEVEL]`` is somewhat arbitrary but conveys meaning about the purpose of the branch. This branch name format is not required, but it can be helpful, especially when making multiple backport PRs for multiple stable branches. + The branch name ``backport/2.17/[PR_NUMBER_FROM_DEVEL]`` is somewhat arbitrary but conveys meaning about the purpose of the branch. This branch name format is not required, but it can be helpful, especially when making multiple backport PRs for multiple stable branches. .. note:: From 19ce4c9e580861272be897a59c2052a303c58995 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 22 May 2024 14:42:39 -0400 Subject: [PATCH 381/536] mark 2.14 EOL in the release table (#1502) --- .../rst/reference_appendices/release_and_maintenance.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index ab583979b7e..3c541d7b3a0 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -185,7 +185,8 @@ Dates listed indicate the start date of the maintenance cycle. - | GA: 07 Nov 2022 | Critical: 22 May 2023 | Security: 06 Nov 2023 - - 20 May 2024 + - | **EOL** + | 20 May 2024 - | Python 3.9 - 3.11 - | Python 2.7 | Python 3.5 - 3.11 From 19119d022b3e3605c50898e6b0d0e003701f10ea Mon Sep 17 00:00:00 2001 From: Lyle McKarns Date: Wed, 22 May 2024 15:46:51 -0400 Subject: [PATCH 382/536] Add tagger section to README per 1272 (#1460) * First pass at adding tagging doc * Further Doc Cleanup * Add Details * Update README.md Markdown standards fixup Co-authored-by: Don Naro * Update README.md wording fixup Co-authored-by: Don Naro * Update README.md Clearer description for why/when to tag Co-authored-by: Don Naro * Update README.md language clarity fixup Co-authored-by: Don Naro * Update README.md Co-authored-by: Don Naro * Update README.md Co-authored-by: Don Naro * Update README.md silly typo fixup Co-authored-by: Don Naro * Update README.md clarity fixup Co-authored-by: Don Naro * For clarity on venv, and reqs * clarity on remotes for tagger * Markdown quality fixup * clarify checkout instructions for tagging * Update README.md Co-authored-by: Don Naro * Update README.md typo Co-authored-by: Don Naro * Fixups * Update README.md Co-authored-by: Don Naro * Update README.md Co-authored-by: Don Naro * Update README.md Co-authored-by: Don Naro * Update README.md Co-authored-by: Don Naro * Update README.md Co-authored-by: Don Naro * Update README.md Co-authored-by: Don Naro * Update README.md Co-authored-by: Sandra McCann * Update README.md Co-authored-by: Sandra McCann * Cleanup of checkout directory description for clarity * Update README.md Co-authored-by: Maxwell G * Update README.md Co-authored-by: Maxwell G * Update README.md Co-authored-by: Maxwell G * Updates for clarity around use of the tagger script (fewer steps needed) --------- Co-authored-by: Don Naro Co-authored-by: Sandra McCann Co-authored-by: Maxwell G --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index e9392b53ba5..2c729580b0d 100644 --- a/README.md +++ b/README.md @@ -136,3 +136,35 @@ If you do not have Python 3.10 installed, you can use root-less podman with a Py ```bash podman run --rm --tty --volume "$(pwd):/mnt:z" --workdir /mnt docker.io/library/python:3.10 bash -c 'pip install nox ; nox -s pip-compile' ``` + +## Creating release tags + +When a tag is created in the [`ansible/ansible`](https://github.com/ansible/ansible) repository for a release or release candidate, a corresponding tag should be created in this `ansible-documentation` repository. + +First, install the additional tagging dependencies from this repository as follows, creating or activating a `venv` as needed: + +``` bash +python3 -m venv ./venv +source ./venv/bin/activate +pip install -r hacking/tagger/requirements.txt +``` + +Next, ensure that you have the [`ansible/ansible`](https://github.com/ansible/ansible) and [`ansible/ansible-documentation`](https://github.com/ansible/ansible-documentation) repositories checked out. +The tool assumes that both checkouts have the same parent directory. You can set different paths to your checkouts with the `--docs` and `--core` options if you have them set up another way. + +Lastly, run the tagger script. + +This will determine any missing `ansible-core` tags and create them in `ansible-documentation` if needed, exiting normally otherwise: + +``` bash +# The tagger scripts assumes "origin" as the upstream remote. +./hacking/tagger/tag.py tag + +# If you use a different upstream remote, specify the name. +./hacking/tagger/tag.py --remote tag + +# If your core repo is not in the same filesystem location, specify the path. +./hacking/tagger/tag.py --core tag +``` + +See `--help` for extended options. From b0b3ba38c92e525bb15c9ec1c1725db0e3de44ca Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 23 May 2024 09:25:08 +0100 Subject: [PATCH 383/536] resolves #1491 adding assert details This change brings details into the 2.17.0 porting guide that were mentioned in the changelog. --- .../porting_guide_core_2.17.rst | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst index 2b4bf724eaf..e44496a0c2c 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst @@ -19,7 +19,30 @@ This document is part of a collection on porting. The complete list of porting g Playbook ======== -No notable changes +* Conditionals - due to mitigation of security issue CVE-2023-5764 in ansible-core 2.16.1, + conditional expressions with embedded template blocks can fail with the message + "``Conditional is marked as unsafe, and cannot be evaluated.``" when an embedded template + consults data from untrusted sources like module results or vars marked ``!unsafe``. + Conditionals with embedded templates can be a source of malicious template injection when + referencing untrusted data, and can nearly always be rewritten without embedded + templates. Playbook task conditional keywords such as ``when`` and ``until`` have long + displayed warnings discouraging use of embedded templates in conditionals; this warning + has been expanded to non-task conditionals as well, such as the ``assert`` action. + + .. code-block:: yaml + + - name: task with a module result (always untrusted by Ansible) + shell: echo "hi mom" + register: untrusted_result + + # don't do it this way... + # - name: insecure conditional with embedded template consulting untrusted data + # assert: + # that: '"hi mom" is in {{ untrusted_result.stdout }}' + + - name: securely access untrusted values directly as Jinja variables instead + assert: + that: '"hi mom" is in untrusted_result.stdout' Command Line From 35cd44b33f2d095154e0982b12b9cb112a4d31a4 Mon Sep 17 00:00:00 2001 From: Rui Chen Date: Thu, 23 May 2024 13:32:20 -0400 Subject: [PATCH 384/536] release_and_maintenance: mark 8.x unmaintained as 8.7.0 released (#1522) --- .../rst/reference_appendices/release_and_maintenance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 3c541d7b3a0..8f68e1b2f70 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -83,7 +83,7 @@ Ansible Community Package Release Status ================================== ============================================== ========================= 10.0.0 In development (unreleased) 2.17 `9.x Changelogs`_ Current 2.16 -`8.x Changelogs`_ Unmaintained (end of life) after Ansible 8.7.0 2.15 +`8.x Changelogs`_ Unmaintained (end of life) 2.15 `7.x Changelogs`_ Unmaintained (end of life) 2.14 `6.x Changelogs`_ Unmaintained (end of life) 2.13 `5.x Changelogs`_ Unmaintained (end of life) 2.12 From 701b1c52ee111b0e181635f709cc42e2ac89bbc5 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 26 May 2024 00:10:41 +0000 Subject: [PATCH 385/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 12 ++++++------ tests/requirements.txt | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index db45d3f18c1..c9f181a4b86 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -14,13 +14,13 @@ aiosignal==1.3.1 # via aiohttp alabaster==0.7.16 # via sphinx -annotated-types==0.6.0 +annotated-types==0.7.0 # via pydantic ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-changelog==0.26.0 +antsibull-changelog==0.27.0 # via antsibull-docs antsibull-core==3.0.1 # via antsibull-docs @@ -101,7 +101,7 @@ pyyaml==6.0.1 # antsibull-changelog # antsibull-core # antsibull-docs -requests==2.31.0 +requests==2.32.2 # via sphinx resolvelib==1.0.1 # via -r tests/requirements-relaxed.in @@ -136,7 +136,7 @@ sphinx-copybutton==0.5.2 # via -r tests/requirements-relaxed.in sphinx-intl==2.2.0 # via -r tests/requirements-relaxed.in -sphinx-notfound-page==1.0.0 +sphinx-notfound-page==1.0.2 # via -r tests/requirements-relaxed.in sphinx-rtd-theme==2.0.0 # via @@ -166,7 +166,7 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.11.0 +typing-extensions==4.12.0 # via # pydantic # pydantic-core @@ -177,5 +177,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==69.5.1 +setuptools==70.0.0 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index e04de540bff..ce036fffc0f 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -14,13 +14,13 @@ aiosignal==1.3.1 # via aiohttp alabaster==0.7.16 # via sphinx -annotated-types==0.6.0 +annotated-types==0.7.0 # via pydantic ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-changelog==0.26.0 +antsibull-changelog==0.27.0 # via antsibull-docs antsibull-core==3.0.1 # via antsibull-docs @@ -103,7 +103,7 @@ pyyaml==6.0.1 # antsibull-changelog # antsibull-core # antsibull-docs -requests==2.31.0 +requests==2.32.2 # via sphinx resolvelib==1.0.1 # via -r tests/requirements-relaxed.in @@ -139,7 +139,7 @@ sphinx-copybutton==0.5.2 # via -r tests/requirements-relaxed.in sphinx-intl==2.2.0 # via -r tests/requirements-relaxed.in -sphinx-notfound-page==1.0.0 +sphinx-notfound-page==1.0.2 # via -r tests/requirements-relaxed.in sphinx-rtd-theme==2.0.0 # via @@ -167,7 +167,7 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.11.0 +typing-extensions==4.12.0 # via # pydantic # pydantic-core @@ -178,5 +178,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==69.5.1 +setuptools==70.0.0 # via sphinx-intl From 738f805044ae386c4174d6a9907851bafaad4a47 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 28 May 2024 09:13:02 +0200 Subject: [PATCH 386/536] Requesting a collection: replace overview links --- docs/docsite/rst/community/communication.rst | 8 +++++++- docs/docsite/rst/dev_guide/developing_collections.rst | 2 -- .../rst/dev_guide/developing_collections_creating.rst | 2 +- .../docsite/rst/dev_guide/developing_collections_path.rst | 2 +- 4 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index ffb6f3d1ed2..1a0deaf5fe8 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -187,9 +187,15 @@ Anyone can request to start a Working Group, for any reason. If you need only a `Forum group `_, request it in the `forum topic `_. - If you also need a real-time chat channel, you can `request one `_. +.. _request_coll_repo: + +Requesting a community collection repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Working groups are often built around Ansible community collections. You can use a repository under your organization or request one under `ansible-collections `_ on the forum by creating a topic in the `Project Discussions category and the coll-repo-request tag `_. + .. _community_topics: Ansible Community Topics diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index b507cd3ef1b..ae8efa7e5ea 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -43,8 +43,6 @@ For instructions on developing modules, see :ref:`developing_modules_general`. Learn how to install and use collections in playbooks and roles :ref:`contributing_maintained_collections` Guidelines for contributing to selected collections - `Ansible Collections Overview and FAQ `_ - Current development status of community collections and FAQ `Mailing List `_ The development mailing list :ref:`communication_irc` diff --git a/docs/docsite/rst/dev_guide/developing_collections_creating.rst b/docs/docsite/rst/dev_guide/developing_collections_creating.rst index c2a30b4c9a9..9ffeee7f126 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_creating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_creating.rst @@ -38,7 +38,7 @@ There are a few special namespaces: :community: - The `community namespace `__ is owned by the Ansible community. Collections from this namespace generally live in the `GitHub ansible-collection organization `__. If you want to create a collection in this namespace, it is best to `create an issue in github.com/ansible-collections/overview `__. + The `community namespace `__ is owned by the Ansible community. Collections from this namespace generally live in the `GitHub ansible-collection organization `__. If you want to create a collection in this namespace, :ref:`request` it on the forum. :local: diff --git a/docs/docsite/rst/dev_guide/developing_collections_path.rst b/docs/docsite/rst/dev_guide/developing_collections_path.rst index 2c4d108e070..9f28a639941 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_path.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_path.rst @@ -79,7 +79,7 @@ Publish your collection source code Publish your collection on a platform for software development and version control such as `GitHub `_. It can be your personal repository or your organization's one. -You can also `request `_ a repository under the `ansible-collections `_ organization. +You can also :ref:`request` a repository under the `ansible-collections `_ organization. Make sure your collection contains exhaustive license information. Ansible is an open source project, so we encourage you to license it under one of open source licenses. From bd24f0cb29fcdc194d6aa0240264e799fcfa0fce Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 28 May 2024 10:24:29 +0200 Subject: [PATCH 387/536] Fix --- .../rst/dev_guide/developing_collections_creating.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections_creating.rst b/docs/docsite/rst/dev_guide/developing_collections_creating.rst index 9ffeee7f126..32adfc0765b 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_creating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_creating.rst @@ -26,23 +26,23 @@ Collection names consist of a namespace and a name, separated by a period (``.`` Usually namespaces and names use lower-case letters, digits, and underscores, but no upper-case letters. -You should make sure that the namespace you use is not registered by someone else by checking on `Ansible Galaxy's namespace list `__. If you chose a namespace or even a full collection name that collides with another collection on Galaxy, it can happen that if you or someone else runs ``ansible-galaxy collection install`` with your collection name, you end up with another collection. Even if the namespace currently does not exist, it could be created later by someone else. +You should make sure that the namespace you use is not registered by someone else by checking on `Ansible Galaxy's namespace list `_. If you chose a namespace or even a full collection name that collides with another collection on Galaxy, it can happen that if you or someone else runs ``ansible-galaxy collection install`` with your collection name, you end up with another collection. Even if the namespace currently does not exist, it could be created later by someone else. -If you want to request a new namespace on Ansible Galaxy, `create an issue on github.com/ansible/galaxy `__. +If you want to request a new namespace on Ansible Galaxy, `create an issue on github.com/ansible/galaxy `_. There are a few special namespaces: :ansible: - The `ansible namespace `__ is owned by Red Hat and reserved for official Ansible collections. Two special members are the synthetic ``ansible.builtin`` and ``ansible.legacy`` collections. These cannot be found on Ansible Galaxy, but are built-in into ansible-core. + The `ansible namespace `_ is owned by Red Hat and reserved for official Ansible collections. Two special members are the synthetic ``ansible.builtin`` and ``ansible.legacy`` collections. These cannot be found on Ansible Galaxy, but are built-in into ansible-core. :community: - The `community namespace `__ is owned by the Ansible community. Collections from this namespace generally live in the `GitHub ansible-collection organization `__. If you want to create a collection in this namespace, :ref:`request` it on the forum. + The `community namespace `_ is owned by the Ansible community. Collections from this namespace generally live in the `GitHub ansible-collection organization `_. If you want to create a collection in this namespace, :ref:`request` it on the forum. :local: - The `local namespace `__ does not contain any collection on Ansible Galaxy, and the intention is that this will never change. You can use the ``local`` namespace for collections that are locally on your machine or locally in your git repositories, without having to fear collisions with actually existing collections on Ansible Galaxy. + The `local namespace `_ does not contain any collection on Ansible Galaxy, and the intention is that this will never change. You can use the ``local`` namespace for collections that are locally on your machine or locally in your git repositories, without having to fear collisions with actually existing collections on Ansible Galaxy. .. _creating_new_collections: From 58f733fd8cfd462124f6ddd9087fa24ee707bc07 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 28 May 2024 09:25:49 +0100 Subject: [PATCH 388/536] fix minor typo in Makefile --- docs/docsite/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/Makefile b/docs/docsite/Makefile index afcfe4bab7f..8fa6373fca5 100644 --- a/docs/docsite/Makefile +++ b/docs/docsite/Makefile @@ -89,14 +89,14 @@ gettext: gettext_structure gettext_generate_rst generate-po: ifeq ($(LANGUAGES),) - @echo 'LANGUAGES is not defined. It is mandatory. LANGUAGES should be a comma separated list of languages to support. (Exampe: fr,es)' + @echo 'LANGUAGES is not defined. It is mandatory. LANGUAGES should be a comma separated list of languages to support. (Example: fr,es)' else (cd docs/docsite/; sphinx-intl update -w 0 -d rst/locales -p "$(POTDIR)" -l $(LANGUAGES)) endif needs-translation: ifeq ($(LANGUAGES),) - @echo 'LANGUAGES is not defined. It is mandatory. LANGUAGES should be a comma separated list of languages to support. (Exampe: fr,es)' + @echo 'LANGUAGES is not defined. It is mandatory. LANGUAGES should be a comma separated list of languages to support. (Example: fr,es)' else (cd docs/docsite/; sphinx-intl stat -d rst/locales -l $(LANGUAGES) | grep -E ' [1-9][0-9]* (fuzzy|untranslated)' | sort) endif From 8a77a2312a7ef8de22b5204ef848b243b068a2b7 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 30 May 2024 13:57:20 +0200 Subject: [PATCH 389/536] Python collection requirements: restructure (#1459) * Python collection requirements: restructure * simplify * Fix * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- .../collection_requirements.rst | 40 +++++++++---------- 1 file changed, 18 insertions(+), 22 deletions(-) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 41bbb035b5e..0cd776aee5c 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -67,57 +67,53 @@ The following guidelines describe the required structure for your collection: 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`. +In addition to the Python requirements specified in this section, collections 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. - -An **eligible controller Python version** for a collection is a Python version that is supported on the controller side by at least one ansible-core version that the collection supports. Similarly, an **eligible target Python version** for a collection is a Python version that is supported on the target side by at least one ansible-core version that the collection supports. The eligible controller and target Python versions can be determined from the :ref:`ansible_core_support_matrix` and from the ``requires_ansible`` value in ``meta/runtime.yml`` in the collection. +Python requirements for a collection vary between **controller environment** and **other environment**. .. _coll_controller_req: Controller environment ~~~~~~~~~~~~~~~~~~~~~~ -Collections MUST support all eligible controller Python versions in the controller environment, unless required libraries do not support these Python versions. The :ref:`Steering Committee ` can grant other exceptions on a case-by-case basis. +* Collections MUST support all eligible controller Python versions in the controller environment, unless required libraries do not support these Python versions. The :ref:`Steering Committee ` can grant other exceptions on a case-by-case basis. -The collection MUST document all eligible controller Python versions that are not supported in the controller environment. See :ref:`coll_python_docs_req` for details. + * controller environment: the plugins/modules always run in the same environment (Python interpreter, venv, host, and so on) as ansible-core itself. + * eligible controller Python version: a Python version that is supported on the controller side by at least one ansible-core version that the collection supports. The eligible versions can be determined from the :ref:`ansible_core_support_matrix` and from the ``requires_ansible`` value in ``meta/runtime.yml`` in the collection. + +* The collection MUST document all eligible controller Python versions that are **not** supported in the controller environment. See :ref:`coll_python_docs_req` for details. Other environment ~~~~~~~~~~~~~~~~~ -Collections MUST support all eligible controller Python versions in the other environment, unless required libraries do not support these Python versions. The :ref:`Steering Committee ` can grant other exceptions on a case-by-case basis. +* Collections MUST support all eligible controller Python versions in the other environment, unless required libraries do not support these Python versions. The :ref:`Steering Committee ` can grant other exceptions on a case-by-case basis. -Collections SHOULD support all eligible target Python versions in the other environment. + * other environment: the plugins/modules run not in a controller environment. + * eligible target Python version: a Python version that is supported on the target side by at least one ansible-core version that the collection supports. The eligible versions can be determined from the :ref:`ansible_core_support_matrix` and from the ``requires_ansible`` value in ``meta/runtime.yml`` in the collection. -The collection MUST document all eligible target Python versions that are not supported in the other environment. See :ref:`coll_python_docs_req` for details. +* The collection MUST document all eligible target Python versions that are not supported in the other environment. See :ref:`coll_python_docs_req` for details. -.. note:: +Dropping Python versions support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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). +Because dropping support for a Python version for an existing module/plugin is a breaking change, the collection: + +* SHOULD announce it under the deprecated features section in its changelog in previous versions before the support is dropped. +* MUST release a major version that actually drops the support. .. _coll_python_docs_req: Python documentation requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* If everything in your collection supports all eligible controller/target Python versions, you do not need to document supported Python versions. -* If your collection does not support those Python versions, you MUST document which versions it supports in the README. +* If your collection does not support all eligible controller/target 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 From b64297c274b1491118c461ff2d8184ad4b2ce254 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 26 May 2024 00:06:21 +0000 Subject: [PATCH 390/536] ci: refresh dev dependencies --- tests/formatters.txt | 2 +- tests/spelling.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 92c8b534a5e..e174f6638e4 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -20,5 +20,5 @@ platformdirs==4.2.2 # via black tomli==2.0.1 # via black -typing-extensions==4.11.0 +typing-extensions==4.12.0 # via black diff --git a/tests/spelling.txt b/tests/spelling.txt index 1b5e6127689..f68489fd312 100644 --- a/tests/spelling.txt +++ b/tests/spelling.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/spelling.txt --strip-extras tests/spelling.in # -codespell==2.2.6 +codespell==2.3.0 # via -r tests/spelling.in diff --git a/tests/static.txt b/tests/static.txt index 8ad4c2d34b9..9f031c5e7a7 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.4.4 +ruff==0.4.5 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 2430cd37863..27cb8f5c406 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -64,7 +64,7 @@ pyjwt==2.8.0 # via pygithub pynacl==1.5.0 # via pygithub -requests==2.31.0 +requests==2.32.2 # via pygithub rich==13.7.1 # via typer @@ -80,7 +80,7 @@ typer==0.12.3 # via # -r tests/../hacking/pr_labeler/requirements.txt # -r tests/../hacking/tagger/requirements.txt -typing-extensions==4.11.0 +typing-extensions==4.12.0 # via # codeowners # mypy From c2e85b1f610c699860d2b78c7b93b866f4ff0be5 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 2 Jun 2024 00:06:29 +0000 Subject: [PATCH 391/536] ci: refresh dev dependencies --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index e174f6638e4..26d65805f0d 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -20,5 +20,5 @@ platformdirs==4.2.2 # via black tomli==2.0.1 # via black -typing-extensions==4.12.0 +typing-extensions==4.12.1 # via black diff --git a/tests/static.txt b/tests/static.txt index 9f031c5e7a7..890cc866d7f 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.4.5 +ruff==0.4.7 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 27cb8f5c406..347cb87c8a8 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -64,7 +64,7 @@ pyjwt==2.8.0 # via pygithub pynacl==1.5.0 # via pygithub -requests==2.32.2 +requests==2.32.3 # via pygithub rich==13.7.1 # via typer @@ -80,7 +80,7 @@ typer==0.12.3 # via # -r tests/../hacking/pr_labeler/requirements.txt # -r tests/../hacking/tagger/requirements.txt -typing-extensions==4.12.0 +typing-extensions==4.12.1 # via # codeowners # mypy From 1aeabbd27e2d9d089753b1c076d306db14a94020 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 2 Jun 2024 00:10:38 +0000 Subject: [PATCH 392/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 10 +++++----- tests/requirements.txt | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index c9f181a4b86..45ae64e323a 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -20,7 +20,7 @@ ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-changelog==0.27.0 +antsibull-changelog==0.28.0 # via antsibull-docs antsibull-core==3.0.1 # via antsibull-docs @@ -83,11 +83,11 @@ packaging==24.0 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.7.1 +pydantic==2.7.2 # via # antsibull-core # antsibull-docs -pydantic-core==2.18.2 +pydantic-core==2.18.3 # via pydantic pygments==2.18.0 # via @@ -101,7 +101,7 @@ pyyaml==6.0.1 # antsibull-changelog # antsibull-core # antsibull-docs -requests==2.32.2 +requests==2.32.3 # via sphinx resolvelib==1.0.1 # via -r tests/requirements-relaxed.in @@ -166,7 +166,7 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.12.0 +typing-extensions==4.12.1 # via # pydantic # pydantic-core diff --git a/tests/requirements.txt b/tests/requirements.txt index ce036fffc0f..07f3561016a 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -20,7 +20,7 @@ ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-changelog==0.27.0 +antsibull-changelog==0.28.0 # via antsibull-docs antsibull-core==3.0.1 # via antsibull-docs @@ -85,11 +85,11 @@ packaging==24.0 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.7.1 +pydantic==2.7.2 # via # antsibull-core # antsibull-docs -pydantic-core==2.18.2 +pydantic-core==2.18.3 # via pydantic pygments==2.18.0 # via @@ -103,7 +103,7 @@ pyyaml==6.0.1 # antsibull-changelog # antsibull-core # antsibull-docs -requests==2.32.2 +requests==2.32.3 # via sphinx resolvelib==1.0.1 # via -r tests/requirements-relaxed.in @@ -167,7 +167,7 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.12.0 +typing-extensions==4.12.1 # via # pydantic # pydantic-core From 21daa167d910695e831aa7556042ea64042aa2eb Mon Sep 17 00:00:00 2001 From: "Brian R. Becker" Date: Tue, 4 Jun 2024 07:44:55 -0700 Subject: [PATCH 393/536] Update playbooks_blocks.rst (#1546) Fix name of second rescue task in the example to make clear it applies to the second task in the block. --- docs/docsite/rst/playbook_guide/playbooks_blocks.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst index e60d50853ee..dac527894b9 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst @@ -203,7 +203,7 @@ These can be inspected in the ``rescue`` section: ansible.builtin.debug: msg: All is good, ignore error as grep could not find 'me' in hosts - - name: All is good if the first task failed + - name: All is good if the second task failed when: "'/bin/false' in ansible_failed_result.cmd | d([])" ansible.builtin.fail: msg: It is still false!!! From 3312052df9ef0b432a36026f9e790a45bc66e5b0 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Tue, 4 Jun 2024 17:30:19 +0200 Subject: [PATCH 394/536] Add Ansible community 10.0.0 porting guide (#1555) --- .../rst/porting_guides/porting_guide_10.rst | 426 ++++++------------ 1 file changed, 150 insertions(+), 276 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst index 6a58fcd2d38..b485ddaae0c 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -76,8 +76,14 @@ Networking No notable changes -Porting Guide for v10.0.0b1 -=========================== +Porting Guide for v10.0.0 +========================= + +Added Collections +----------------- + +- community.library_inventory_filtering_v1 (version 1.0.1) +- kaytus.ksmanage (version 1.2.1) Known Issues ------------ @@ -93,9 +99,27 @@ community.docker If you still experience problems with requests 2.32.0, such as error messages like ``Not supported URL scheme http+docker``, please restrict requests to ``<2.32.0``. +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_network_attributes - Issue(279049) - If unsupported values are provided for the parameter ``ome_network_attributes``, then this module does not provide a correct error message. +- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. +- ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the following parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. +- ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` +- ome_device_quick_deploy - Issue(275231) - This module does not deploy a new configuration to a slot that has disabled IPv6. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + Breaking Changes ---------------- +Ansible-core +~~~~~~~~~~~~ + +- assert - Nested templating may result in an inability for the conditional to be evaluated. See the porting guide for more information. + amazon.aws ~~~~~~~~~~ @@ -106,6 +130,12 @@ amazon.aws - kms_key_info - the ``policies`` return value has been renamed to ``key_policies`` the contents has not been changed (https://github.com/ansible-collections/amazon.aws/pull/2040). - lambda_event - | ``batch_size`` no longer defaults to 100. According to the boto3 API (https://boto3.amazonaws.com/v1/documentation/api/1.26.78/reference/services/lambda.html#Lambda.Client.create_event_source_mapping), ``batch_size`` defaults to 10 for sqs sources and to 100 for stream sources (https://github.com/ansible-collections/amazon.aws/pull/2025). +cloud.common +~~~~~~~~~~~~ + +- Bump minimum Python supported version to 3.9. +- Remove support for ansible-core < 2.14. + community.aws ~~~~~~~~~~~~~ @@ -125,6 +155,11 @@ community.aws - s3_bucket_info - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.s3_bucket_info``. - sts_assume_role - The module has been migrated from the ``community.aws`` collection. Playbooks using the Fully Qualified Collection Name for this module should be updated to use ``amazon.aws.sts_assume_role``. +community.ciscosmb +~~~~~~~~~~~~~~~~~~ + +- in facts of interface 'bandwith' changed to 'bandwidth' + community.dns ~~~~~~~~~~~~~ @@ -141,285 +176,11 @@ community.general - django_manage - the module will now fail if ``virtualenv`` is specified but no virtual environment exists at that location (https://github.com/ansible-collections/community.general/pull/8198). - redfish_command, redfish_config, redfish_info - change the default for ``timeout`` from 10 to 60 (https://github.com/ansible-collections/community.general/pull/8198). -Major Changes -------------- - -community.dns -~~~~~~~~~~~~~ - -- The ``community.dns`` collection now depends on the ``community.library_inventory_filtering_v1`` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with ``ansible-galaxy collection install``, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugins (https://github.com/ansible-collections/community.dns/pull/196). - -Removed Features ----------------- - -amazon.aws -~~~~~~~~~~ - -- iam_role - the ``iam_role.assume_role_policy_document_raw`` return value has been deprecated. ``iam_role.assume_role_policy_document`` now returns the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). -- iam_role_info - the ``iam_role.assume_role_policy_document_raw`` return value has been deprecated. ``iam_role.assume_role_policy_document`` now returns the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). -- module_utils.policy - the previously deprecated ``sort_json_policy_dict()`` function has been removed, consider using ``compare_policies()`` instead (https://github.com/ansible-collections/amazon.aws/pull/2052). - -community.dns -~~~~~~~~~~~~~ - -- The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 3.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug (https://github.com/ansible-collections/community.dns/pull/196). -- hetzner_dns_record_set, hetzner_dns_record - the deprecated alias ``name`` of the prefix option was removed (https://github.com/ansible-collections/community.dns/pull/196). -- hosttech_dns_records - the redirect to the ``hosttech_dns_record_sets`` module has been removed (https://github.com/ansible-collections/community.dns/pull/196). - -community.general -~~~~~~~~~~~~~~~~~ - -- The deprecated redirects for internal module names have been removed. These internal redirects were extra-long FQCNs like ``community.general.packaging.os.apt_rpm`` that redirect to the short FQCN ``community.general.apt_rpm``. They were originally needed to implement flatmapping; as various tooling started to recommend users to use the long names flatmapping was removed from the collection and redirects were added for users who already followed these incorrect recommendations (https://github.com/ansible-collections/community.general/pull/7835). -- ansible_galaxy_install - the ``ack_ansible29`` and ``ack_min_ansiblecore211`` options have been removed. They no longer had any effect (https://github.com/ansible-collections/community.general/pull/8198). -- cloudflare_dns - remove support for SPF records. These are no longer supported by CloudFlare (https://github.com/ansible-collections/community.general/pull/7782). -- django_manage - support for the ``command`` values ``cleanup``, ``syncdb``, and ``validate`` were removed. Use ``clearsessions``, ``migrate``, and ``check`` instead, respectively (https://github.com/ansible-collections/community.general/pull/8198). -- flowdock - this module relied on HTTPS APIs that do not exist anymore and was thus removed (https://github.com/ansible-collections/community.general/pull/8198). -- mh.mixins.deps module utils - the ``DependencyMixin`` has been removed. Use the ``deps`` module utils instead (https://github.com/ansible-collections/community.general/pull/8198). -- proxmox - the ``proxmox_default_behavior`` option has been removed (https://github.com/ansible-collections/community.general/pull/8198). -- rax* modules, rax module utils, rax docs fragment - the Rackspace modules relied on the deprecated package ``pyrax`` and were thus removed (https://github.com/ansible-collections/community.general/pull/8198). -- redhat module utils - the classes ``Rhsm``, ``RhsmPool``, and ``RhsmPools`` have been removed (https://github.com/ansible-collections/community.general/pull/8198). -- redhat_subscription - the alias ``autosubscribe`` of the ``auto_attach`` option was removed (https://github.com/ansible-collections/community.general/pull/8198). -- stackdriver - this module relied on HTTPS APIs that do not exist anymore and was thus removed (https://github.com/ansible-collections/community.general/pull/8198). -- webfaction_* modules - these modules relied on HTTPS APIs that do not exist anymore and were thus removed (https://github.com/ansible-collections/community.general/pull/8198). - -Deprecated Features -------------------- - -amazon.aws -~~~~~~~~~~ - -- aws_ec2 inventory plugin - removal of the previously deprecated ``include_extra_api_calls`` option has been assigned to release 9.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2040). -- cloudformation - the ``template`` parameter has been deprecated and will be removed in a release after 2026-05-01. The ``template_body`` parameter can be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). -- iam_policy - removal of the previously deprecated ``policies`` return key has been assigned to release 9.0.0. Use the ``policy_names`` return key instead (https://github.com/ansible-collections/amazon.aws/pull/2040). -- module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). -- module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). -- module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). -- rds_param_group - the ``rds_param_group`` module has been renamed to ``rds_instance_param_group``. The usage of the module has not changed. The rds_param_group alias will be removed in version 10.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2058). - -community.aws -~~~~~~~~~~~~~ - -- aws_glue_connection - updated the deprecation for removal of the ``connection_parameters`` return key from ``after 2024-06-01`` to release version ``9.0.0``, it is being replaced by the ``raw_connection_parameters`` key (https://github.com/ansible-collections/community.aws/pull/518). -- ecs_cluster - updated the deprecation for updated default of ``purge_capacity_providers``, the current default of ``False`` will be changed to ``True`` in release ``9.0.0``. To maintain the current behaviour explicitly set ``purge_capacity_providers=False`` (https://github.com/ansible-collections/community.aws/pull/1640). -- ecs_service - updated the deprecation for updated default of ``purge_placement_constraints``, the current default of ``False`` will be changed to ``True`` in release ``9.0.0``. To maintain the current behaviour explicitly set ``purge_placement_constraints=False`` (https://github.com/ansible-collections/community.aws/pull/1716). -- ecs_service - updated the deprecation for updated default of ``purge_placement_strategy``, the current default of ``False`` will be changed to ``True`` in release ``9.0.0``. To maintain the current behaviour explicitly set ``purge_placement_strategy=False`` (https://github.com/ansible-collections/community.aws/pull/1716). - -community.crypto -~~~~~~~~~~~~~~~~ - -- acme documentation fragment - the default ``community.crypto.acme[.documentation]`` docs fragment is deprecated and will be removed from community.crypto 3.0.0. Replace it with both the new ``community.crypto.acme.basic`` and ``community.crypto.acme.account`` fragments (https://github.com/ansible-collections/community.crypto/pull/735). -- acme.backends module utils - the ``get_cert_information()`` method for a ACME crypto backend must be implemented from community.crypto 3.0.0 on (https://github.com/ansible-collections/community.crypto/pull/736). -- crypto.module_backends.common module utils - the ``crypto.module_backends.common`` module utils is deprecated and will be removed from community.crypto 3.0.0. Use the improved ``argspec`` module util instead (https://github.com/ansible-collections/community.crypto/pull/749). - -community.docker -~~~~~~~~~~~~~~~~ - -- docker_compose - the Docker Compose v1 module is deprecated and will be removed from community.docker 4.0.0. Please migrate to the ``community.docker.docker_compose_v2`` module, which works with Docker Compose v2 (https://github.com/ansible-collections/community.docker/issues/823, https://github.com/ansible-collections/community.docker/pull/833). -- various modules and plugins - the ``ssl_version`` option has been deprecated and will be removed from community.docker 4.0.0. It has already been removed from Docker SDK for Python 7.0.0, and was only necessary in the past to work around SSL/TLS issues (https://github.com/ansible-collections/community.docker/pull/853). - -community.general -~~~~~~~~~~~~~~~~~ - -- MH DependencyCtxMgr module_utils - deprecate ``module_utils.mh.mixin.deps.DependencyCtxMgr`` in favour of ``module_utils.deps`` (https://github.com/ansible-collections/community.general/pull/8280). -- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.AnsibleModule`` (https://github.com/ansible-collections/community.general/pull/8280). -- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.DependencyCtxMgr`` (https://github.com/ansible-collections/community.general/pull/8280). -- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.StateMixin`` (https://github.com/ansible-collections/community.general/pull/8280). -- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.VarDict,`` (https://github.com/ansible-collections/community.general/pull/8280). -- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.VarMeta`` (https://github.com/ansible-collections/community.general/pull/8280). -- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.VarsMixin`` (https://github.com/ansible-collections/community.general/pull/8280). -- ModuleHelper module_utils - deprecate use of ``VarsMixin`` in favor of using the ``VardDict`` module_utils (https://github.com/ansible-collections/community.general/pull/8226). -- ModuleHelper vars module_utils - bump deprecation of ``VarMeta``, ``VarDict`` and ``VarsMixin`` to version 11.0.0 (https://github.com/ansible-collections/community.general/pull/8226). -- apt_rpm - the behavior of ``state=present`` and ``state=installed`` is deprecated and will change in community.general 11.0.0. Right now the module will upgrade a package to the latest version if one of these two states is used. You should explicitly use ``state=latest`` if you want this behavior, and switch to ``state=present_not_latest`` if you do not want to upgrade the package if it is already installed. In community.general 11.0.0 the behavior of ``state=present`` and ``state=installed`` will change to that of ``state=present_not_latest`` (https://github.com/ansible-collections/community.general/issues/8217, https://github.com/ansible-collections/community.general/pull/8285). -- consul_acl - the module has been deprecated and will be removed in community.general 10.0.0. ``consul_token`` and ``consul_policy`` can be used instead (https://github.com/ansible-collections/community.general/pull/7901). -- django_manage - the ``ack_venv_creation_deprecation`` option has no more effect and will be removed from community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/8198). -- gitlab modules - the basic auth method on GitLab API have been deprecated and will be removed in community.general 10.0.0 (https://github.com/ansible-collections/community.general/pull/8383). -- hipchat callback plugin - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The callback plugin is therefore deprecated and will be removed from community.general 10.0.0 if nobody provides compelling reasons to still keep it (https://github.com/ansible-collections/community.general/issues/8184, https://github.com/ansible-collections/community.general/pull/8189). -- irc - the defaults ``false`` for ``use_tls`` and ``validate_certs`` have been deprecated and will change to ``true`` in community.general 10.0.0 to improve security. You can already improve security now by explicitly setting them to ``true``. Specifying values now disables the deprecation warning (https://github.com/ansible-collections/community.general/pull/7578). - -Porting Guide for v10.0.0a3 -=========================== - -Breaking Changes ----------------- - community.hrobot ~~~~~~~~~~~~~~~~ - robot inventory plugin - ``filters`` is now no longer an alias of ``simple_filters``, but a new, different option (https://github.com/ansible-collections/community.hrobot/pull/101). -Major Changes -------------- - -community.hrobot -~~~~~~~~~~~~~~~~ - -- The ``community.hrobot`` collection now depends on the ``community.library_inventory_filtering_v1`` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with ``ansible-galaxy collection install``, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugin (https://github.com/ansible-collections/community.hrobot/pull/101). - -grafana.grafana -~~~~~~~~~~~~~~~ - -- Add a new config part to configure KeyCloak based auth by @he0s in https://github.com/grafana/grafana-ansible-collection/pull/191 -- Add promtail role by @voidquark in https://github.com/grafana/grafana-ansible-collection/pull/197 -- Bump ansible-lint from 24.2.2 to 24.2.3 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/195 - -Removed Features ----------------- - -community.grafana -~~~~~~~~~~~~~~~~~ - -- removed deprecated `message` argument in `grafana_dashboard` - -community.hrobot -~~~~~~~~~~~~~~~~ - -- The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 2.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug (https://github.com/ansible-collections/community.hrobot/pull/101). - -Deprecated Features -------------------- - -amazon.aws -~~~~~~~~~~ - -- cloudformation - the ``template`` parameter has been deprecated and will be removed in a release after 2026-05-01. The ``template_body`` parameter can be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). -- module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). -- module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). -- module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). - -Porting Guide for v10.0.0a2 -=========================== - -Added Collections ------------------ - -- kaytus.ksmanage (version 1.2.1) - -Known Issues ------------- - -dellemc.openmanage -~~~~~~~~~~~~~~~~~~ - -- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. -- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. -- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. -- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. -- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. - -Major Changes -------------- - -arista.eos -~~~~~~~~~~ - -- Update the netcommon base version 6.1.0 to support cli_restore plugin. - -cisco.ios -~~~~~~~~~ - -- Update the netcommon base version 6.1.0 to support cli_restore plugin. - -cisco.iosxr -~~~~~~~~~~~ - -- Update the netcommon base version to support cli_restore plugin. - -cisco.nxos -~~~~~~~~~~ - -- Updated the minimum required ansible.netcommon version to 6.1.0 to support the cli_restore module. - -containers.podman -~~~~~~~~~~~~~~~~~ - -- Add quadlet support for Podman modules - -dellemc.openmanage -~~~~~~~~~~~~~~~~~~ - -- idrac_session - This module allows you to create and delete the sessions on iDRAC. - -grafana.grafana -~~~~~~~~~~~~~~~ - -- Add Grafana Loki role by @voidquark in https://github.com/grafana/grafana-ansible-collection/pull/188 -- Add Grafana Mimir role by @GVengelen in https://github.com/grafana/grafana-ansible-collection/pull/183 -- Add an Ansible role for Grafana Alloy by @ishanjainn in https://github.com/grafana/grafana-ansible-collection/pull/169 - -junipernetworks.junos -~~~~~~~~~~~~~~~~~~~~~ - -- Update the netcommon base version 6.1.0 to support cli_restore plugin. - -Removed Features ----------------- - -Ansible-core -~~~~~~~~~~~~ - -- Removed Python 2.7 and Python 3.6 as a supported remote version. Python 3.7+ is now required for target execution. - -Deprecated Features -------------------- - -community.crypto -~~~~~~~~~~~~~~~~ - -- acme.backends module utils - from community.crypto on, all implementations of ``CryptoBackend`` must override ``get_ordered_csr_identifiers()``. The current default implementation, which simply sorts the result of ``get_csr_identifiers()``, will then be removed (https://github.com/ansible-collections/community.crypto/pull/725). - -community.general -~~~~~~~~~~~~~~~~~ - -- hipchat callback plugin - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The callback plugin is therefore deprecated and will be removed from community.general 10.0.0 if nobody provides compelling reasons to still keep it (https://github.com/ansible-collections/community.general/issues/8184, https://github.com/ansible-collections/community.general/pull/8189). - -community.vmware -~~~~~~~~~~~~~~~~ - -- vmware_guest_tools_info - `vm_tools_install_status` will be removed from next major version (5.0.0) of the collection since the API call that provides this information has been deprecated by VMware. Use `vm_tools_running_status` / `vm_tools_version_status` instead (https://github.com/ansible-collections/community.vmware/issues/2033). - -Porting Guide for v10.0.0a1 -=========================== - -Added Collections ------------------ - -- community.library_inventory_filtering_v1 (version 1.0.0) - -Known Issues ------------- - -dellemc.openmanage -~~~~~~~~~~~~~~~~~~ - -- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. -- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. -- idrac_network_attributes - Issue(279049) - If unsupported values are provided for the parameter ``ome_network_attributes``, then this module does not provide a correct error message. -- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. -- ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the following parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. -- ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` -- ome_device_quick_deploy - Issue(275231) - This module does not deploy a new configuration to a slot that has disabled IPv6. -- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. -- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. - -Breaking Changes ----------------- - -Ansible-core -~~~~~~~~~~~~ - -- assert - Nested templating may result in an inability for the conditional to be evaluated. See the porting guide for more information. - -cloud.common -~~~~~~~~~~~~ - -- Bump minimum Python supported version to 3.9. -- Remove support for ansible-core < 2.14. - -community.ciscosmb -~~~~~~~~~~~~~~~~~~ - -- in facts of interface 'bandwith' changed to 'bandwidth' - community.okd ~~~~~~~~~~~~~ @@ -478,6 +239,7 @@ arista.eos - Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. - This release removes previously deprecated modules and attributes from this collection. Please refer to the **Removed Features** section for details. +- Update the netcommon base version 6.1.0 to support cli_restore plugin. cisco.asa ~~~~~~~~~ @@ -488,6 +250,7 @@ cisco.ios ~~~~~~~~~ - Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. +- Update the netcommon base version 6.1.0 to support cli_restore plugin. - ios_ntp - Remove deprecated ntp legacy module cisco.iosxr @@ -495,12 +258,19 @@ cisco.iosxr - Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. - This release removes previously deprecated module and attributes from this collection. Please refer to the **Removed Features** section for details. +- Update the netcommon base version to support cli_restore plugin. cisco.nxos ~~~~~~~~~~ - Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. - This release removes four previously deprecated modules from this collection. Please refer to the **Removed Features** section for details. +- Updated the minimum required ansible.netcommon version to 6.1.0 to support the cli_restore module. + +community.dns +~~~~~~~~~~~~~ + +- The ``community.dns`` collection now depends on the ``community.library_inventory_filtering_v1`` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with ``ansible-galaxy collection install``, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugins (https://github.com/ansible-collections/community.dns/pull/196). community.docker ~~~~~~~~~~~~~~~~ @@ -512,11 +282,21 @@ community.hashi_vault - requirements - the ``requests`` package which is required by ``hvac`` now has a more restrictive range for this collection in certain use cases due to breaking security changes in ``ansible-core`` that were backported (https://github.com/ansible-collections/community.hashi_vault/pull/416). +community.hrobot +~~~~~~~~~~~~~~~~ + +- The ``community.hrobot`` collection now depends on the ``community.library_inventory_filtering_v1`` collection. This utility collection provides host filtering functionality for inventory plugins. If you use the Ansible community package, both collections are included and you do not have to do anything special. If you install the collection with ``ansible-galaxy collection install``, it will be installed automatically. If you install the collection by copying the files of the collection to a place where ansible-core can find it, for example by cloning the git repository, you need to make sure that you also have to install the dependency if you are using the inventory plugin (https://github.com/ansible-collections/community.hrobot/pull/101). + community.mysql ~~~~~~~~~~~~~~~ - Collection version 2.*.* is EOL, no more bugfixes will be backported. Please consider upgrading to the latest version. +containers.podman +~~~~~~~~~~~~~~~~~ + +- Add quadlet support for Podman modules + dellemc.openmanage ~~~~~~~~~~~~~~~~~~ @@ -526,6 +306,7 @@ dellemc.openmanage - idrac_diagnostics - The module is introduced to run and export diagnostics on iDRAC. - idrac_gather_facts - This role is enhanced to support secure boot. - idrac_license - The module is introduced to configure iDRAC licenses. +- idrac_session - This module allows you to create and delete the sessions on iDRAC. - idrac_user - This role is introduced to manage local users of iDRAC. dellemc.unity @@ -549,7 +330,13 @@ fortinet.fortios grafana.grafana ~~~~~~~~~~~~~~~ +- Add Grafana Loki role by @voidquark in https://github.com/grafana/grafana-ansible-collection/pull/188 +- Add Grafana Mimir role by @GVengelen in https://github.com/grafana/grafana-ansible-collection/pull/183 +- Add a new config part to configure KeyCloak based auth by @he0s in https://github.com/grafana/grafana-ansible-collection/pull/191 +- Add an Ansible role for Grafana Alloy by @ishanjainn in https://github.com/grafana/grafana-ansible-collection/pull/169 - Add an Ansible role for OpenTelemetry Collector by @ishanjainn in https://github.com/grafana/grafana-ansible-collection/pull/138 +- Add promtail role by @voidquark in https://github.com/grafana/grafana-ansible-collection/pull/197 +- Bump ansible-lint from 24.2.2 to 24.2.3 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/195 ibm.qradar ~~~~~~~~~~ @@ -567,6 +354,7 @@ junipernetworks.junos - Bumping `requires_ansible` to `>=2.14.0`, since previous ansible-core versions are EoL now. - This release removes previously deprecated modules from this collection. Please refer to the **Removed Features** section for details. +- Update the netcommon base version 6.1.0 to support cli_restore plugin. splunk.es ~~~~~~~~~ @@ -606,8 +394,16 @@ Ansible-core - Remove deprecated JINJA2_NATIVE_WARNING environment variable (https://github.com/ansible/ansible/issues/81714) - Remove deprecated ``scp_if_ssh`` from ssh connection plugin (https://github.com/ansible/ansible/issues/81715). - Remove deprecated crypt support from ansible.utils.encrypt (https://github.com/ansible/ansible/issues/81717) +- Removed Python 2.7 and Python 3.6 as a supported remote version. Python 3.7+ is now required for target execution. - With the removal of Python 2 support, the yum module and yum action plugin are removed and redirected to ``dnf``. +amazon.aws +~~~~~~~~~~ + +- iam_role - the ``iam_role.assume_role_policy_document_raw`` return value has been deprecated. ``iam_role.assume_role_policy_document`` now returns the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). +- iam_role_info - the ``iam_role.assume_role_policy_document_raw`` return value has been deprecated. ``iam_role.assume_role_policy_document`` now returns the same format as ``iam_role.assume_role_policy_document_raw`` (https://github.com/ansible-collections/amazon.aws/pull/2040). +- module_utils.policy - the previously deprecated ``sort_json_policy_dict()`` function has been removed, consider using ``compare_policies()`` instead (https://github.com/ansible-collections/amazon.aws/pull/2052). + arista.eos ~~~~~~~~~~ @@ -634,6 +430,39 @@ cisco.nxos - The nxos_ntp_auth module has been removed with this release. - The nxos_ntp_options module has been removed with this release. +community.dns +~~~~~~~~~~~~~ + +- The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 3.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug (https://github.com/ansible-collections/community.dns/pull/196). +- hetzner_dns_record_set, hetzner_dns_record - the deprecated alias ``name`` of the prefix option was removed (https://github.com/ansible-collections/community.dns/pull/196). +- hosttech_dns_records - the redirect to the ``hosttech_dns_record_sets`` module has been removed (https://github.com/ansible-collections/community.dns/pull/196). + +community.general +~~~~~~~~~~~~~~~~~ + +- The deprecated redirects for internal module names have been removed. These internal redirects were extra-long FQCNs like ``community.general.packaging.os.apt_rpm`` that redirect to the short FQCN ``community.general.apt_rpm``. They were originally needed to implement flatmapping; as various tooling started to recommend users to use the long names flatmapping was removed from the collection and redirects were added for users who already followed these incorrect recommendations (https://github.com/ansible-collections/community.general/pull/7835). +- ansible_galaxy_install - the ``ack_ansible29`` and ``ack_min_ansiblecore211`` options have been removed. They no longer had any effect (https://github.com/ansible-collections/community.general/pull/8198). +- cloudflare_dns - remove support for SPF records. These are no longer supported by CloudFlare (https://github.com/ansible-collections/community.general/pull/7782). +- django_manage - support for the ``command`` values ``cleanup``, ``syncdb``, and ``validate`` were removed. Use ``clearsessions``, ``migrate``, and ``check`` instead, respectively (https://github.com/ansible-collections/community.general/pull/8198). +- flowdock - this module relied on HTTPS APIs that do not exist anymore and was thus removed (https://github.com/ansible-collections/community.general/pull/8198). +- mh.mixins.deps module utils - the ``DependencyMixin`` has been removed. Use the ``deps`` module utils instead (https://github.com/ansible-collections/community.general/pull/8198). +- proxmox - the ``proxmox_default_behavior`` option has been removed (https://github.com/ansible-collections/community.general/pull/8198). +- rax* modules, rax module utils, rax docs fragment - the Rackspace modules relied on the deprecated package ``pyrax`` and were thus removed (https://github.com/ansible-collections/community.general/pull/8198). +- redhat module utils - the classes ``Rhsm``, ``RhsmPool``, and ``RhsmPools`` have been removed (https://github.com/ansible-collections/community.general/pull/8198). +- redhat_subscription - the alias ``autosubscribe`` of the ``auto_attach`` option was removed (https://github.com/ansible-collections/community.general/pull/8198). +- stackdriver - this module relied on HTTPS APIs that do not exist anymore and was thus removed (https://github.com/ansible-collections/community.general/pull/8198). +- webfaction_* modules - these modules relied on HTTPS APIs that do not exist anymore and were thus removed (https://github.com/ansible-collections/community.general/pull/8198). + +community.grafana +~~~~~~~~~~~~~~~~~ + +- removed deprecated `message` argument in `grafana_dashboard` + +community.hrobot +~~~~~~~~~~~~~~~~ + +- The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 2.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug (https://github.com/ansible-collections/community.hrobot/pull/101). + junipernetworks.junos ~~~~~~~~~~~~~~~~~~~~~ @@ -657,11 +486,30 @@ Ansible-core amazon.aws ~~~~~~~~~~ +- aws_ec2 inventory plugin - removal of the previously deprecated ``include_extra_api_calls`` option has been assigned to release 9.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2040). +- cloudformation - the ``template`` parameter has been deprecated and will be removed in a release after 2026-05-01. The ``template_body`` parameter can be used in conjungtion with the lookup plugin (https://github.com/ansible-collections/amazon.aws/pull/2048). +- iam_policy - removal of the previously deprecated ``policies`` return key has been assigned to release 9.0.0. Use the ``policy_names`` return key instead (https://github.com/ansible-collections/amazon.aws/pull/2040). - iam_role_info - in a release after 2026-05-01 paths must begin and end with ``/`` (https://github.com/ansible-collections/amazon.aws/pull/1998). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_connection_info()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.botocore - the ``boto3`` parameter for ``get_aws_region()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- module_utils.ec2 - the ``boto3`` parameter for ``get_ec2_security_group_ids_from_names()`` will be removed in a release after 2025-05-01. The ``boto3`` parameter has been ignored since release 4.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2047). +- rds_param_group - the ``rds_param_group`` module has been renamed to ``rds_instance_param_group``. The usage of the module has not changed. The rds_param_group alias will be removed in version 10.0.0 (https://github.com/ansible-collections/amazon.aws/pull/2058). + +community.aws +~~~~~~~~~~~~~ + +- aws_glue_connection - updated the deprecation for removal of the ``connection_parameters`` return key from ``after 2024-06-01`` to release version ``9.0.0``, it is being replaced by the ``raw_connection_parameters`` key (https://github.com/ansible-collections/community.aws/pull/518). +- ecs_cluster - updated the deprecation for updated default of ``purge_capacity_providers``, the current default of ``False`` will be changed to ``True`` in release ``9.0.0``. To maintain the current behaviour explicitly set ``purge_capacity_providers=False`` (https://github.com/ansible-collections/community.aws/pull/1640). +- ecs_service - updated the deprecation for updated default of ``purge_placement_constraints``, the current default of ``False`` will be changed to ``True`` in release ``9.0.0``. To maintain the current behaviour explicitly set ``purge_placement_constraints=False`` (https://github.com/ansible-collections/community.aws/pull/1716). +- ecs_service - updated the deprecation for updated default of ``purge_placement_strategy``, the current default of ``False`` will be changed to ``True`` in release ``9.0.0``. To maintain the current behaviour explicitly set ``purge_placement_strategy=False`` (https://github.com/ansible-collections/community.aws/pull/1716). community.crypto ~~~~~~~~~~~~~~~~ +- acme documentation fragment - the default ``community.crypto.acme[.documentation]`` docs fragment is deprecated and will be removed from community.crypto 3.0.0. Replace it with both the new ``community.crypto.acme.basic`` and ``community.crypto.acme.account`` fragments (https://github.com/ansible-collections/community.crypto/pull/735). +- acme.backends module utils - from community.crypto on, all implementations of ``CryptoBackend`` must override ``get_ordered_csr_identifiers()``. The current default implementation, which simply sorts the result of ``get_csr_identifiers()``, will then be removed (https://github.com/ansible-collections/community.crypto/pull/725). +- acme.backends module utils - the ``get_cert_information()`` method for a ACME crypto backend must be implemented from community.crypto 3.0.0 on (https://github.com/ansible-collections/community.crypto/pull/736). +- crypto.module_backends.common module utils - the ``crypto.module_backends.common`` module utils is deprecated and will be removed from community.crypto 3.0.0. Use the improved ``argspec`` module util instead (https://github.com/ansible-collections/community.crypto/pull/749). - openssl_csr_pipe, openssl_privatekey_pipe, x509_certificate_pipe - the current behavior of check mode is deprecated and will change in community.crypto 3.0.0. The current behavior is similar to the modules without ``_pipe``: if the object needs to be (re-)generated, only the ``changed`` status is set, but the object is not updated. From community.crypto 3.0.0 on, the modules will ignore check mode and always act as if check mode is not active. This behavior can already achieved now by adding ``check_mode: false`` to the task. If you think this breaks your use-case of this module, please `create an issue in the community.crypto repository `__ (https://github.com/ansible-collections/community.crypto/issues/712, https://github.com/ansible-collections/community.crypto/pull/714). community.dns @@ -672,7 +520,28 @@ community.dns community.docker ~~~~~~~~~~~~~~~~ +- docker_compose - the Docker Compose v1 module is deprecated and will be removed from community.docker 4.0.0. Please migrate to the ``community.docker.docker_compose_v2`` module, which works with Docker Compose v2 (https://github.com/ansible-collections/community.docker/issues/823, https://github.com/ansible-collections/community.docker/pull/833). - docker_container - the default ``ignore`` for the ``image_name_mismatch`` parameter has been deprecated and will switch to ``recreate`` in community.docker 4.0.0. A deprecation warning will be printed in situations where the default value is used and where a behavior would change once the default changes (https://github.com/ansible-collections/community.docker/pull/703). +- various modules and plugins - the ``ssl_version`` option has been deprecated and will be removed from community.docker 4.0.0. It has already been removed from Docker SDK for Python 7.0.0, and was only necessary in the past to work around SSL/TLS issues (https://github.com/ansible-collections/community.docker/pull/853). + +community.general +~~~~~~~~~~~~~~~~~ + +- MH DependencyCtxMgr module_utils - deprecate ``module_utils.mh.mixin.deps.DependencyCtxMgr`` in favour of ``module_utils.deps`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.AnsibleModule`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.DependencyCtxMgr`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.StateMixin`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.VarDict,`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.VarMeta`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate ``plugins.module_utils.module_helper.VarsMixin`` (https://github.com/ansible-collections/community.general/pull/8280). +- ModuleHelper module_utils - deprecate use of ``VarsMixin`` in favor of using the ``VardDict`` module_utils (https://github.com/ansible-collections/community.general/pull/8226). +- ModuleHelper vars module_utils - bump deprecation of ``VarMeta``, ``VarDict`` and ``VarsMixin`` to version 11.0.0 (https://github.com/ansible-collections/community.general/pull/8226). +- apt_rpm - the behavior of ``state=present`` and ``state=installed`` is deprecated and will change in community.general 11.0.0. Right now the module will upgrade a package to the latest version if one of these two states is used. You should explicitly use ``state=latest`` if you want this behavior, and switch to ``state=present_not_latest`` if you do not want to upgrade the package if it is already installed. In community.general 11.0.0 the behavior of ``state=present`` and ``state=installed`` will change to that of ``state=present_not_latest`` (https://github.com/ansible-collections/community.general/issues/8217, https://github.com/ansible-collections/community.general/pull/8285). +- consul_acl - the module has been deprecated and will be removed in community.general 10.0.0. ``consul_token`` and ``consul_policy`` can be used instead (https://github.com/ansible-collections/community.general/pull/7901). +- django_manage - the ``ack_venv_creation_deprecation`` option has no more effect and will be removed from community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/8198). +- gitlab modules - the basic auth method on GitLab API have been deprecated and will be removed in community.general 10.0.0 (https://github.com/ansible-collections/community.general/pull/8383). +- hipchat callback plugin - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The callback plugin is therefore deprecated and will be removed from community.general 10.0.0 if nobody provides compelling reasons to still keep it (https://github.com/ansible-collections/community.general/issues/8184, https://github.com/ansible-collections/community.general/pull/8189). +- irc - the defaults ``false`` for ``use_tls`` and ``validate_certs`` have been deprecated and will change to ``true`` in community.general 10.0.0 to improve security. You can already improve security now by explicitly setting them to ``true``. Specifying values now disables the deprecation warning (https://github.com/ansible-collections/community.general/pull/7578). community.hrobot ~~~~~~~~~~~~~~~~ @@ -684,6 +553,11 @@ community.okd - openshift - the ``openshift`` inventory plugin has been deprecated and will be removed in release 4.0.0 (https://github.com/ansible-collections/kubernetes.core/issues/31). +community.vmware +~~~~~~~~~~~~~~~~ + +- vmware_guest_tools_info - `vm_tools_install_status` will be removed from next major version (5.0.0) of the collection since the API call that provides this information has been deprecated by VMware. Use `vm_tools_running_status` / `vm_tools_version_status` instead (https://github.com/ansible-collections/community.vmware/issues/2033). + dellemc.openmanage ~~~~~~~~~~~~~~~~~~ From 427a9f132c21e3dde3490139eaf55e207e72fe02 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 4 Jun 2024 11:45:18 -0400 Subject: [PATCH 395/536] update conf.py for Ansible 10 (#1544) --- docs/docsite/rst/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 3a7d03d75ae..8b105a5fb4b 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -241,7 +241,7 @@ 'latest_version': ( 'devel' if tags.has('all') else '2.17' if tags.has('core_lang') or tags.has('core') else - '9' if tags.has('ansible') + '10' if tags.has('ansible') else '' ), # list specifically out of order to make latest work @@ -249,7 +249,7 @@ ('devel',) if tags.has('all') else ('2.15_ja', '2.14_ja', '2.13_ja',) if tags.has('core_lang') else ('2.17', '2.16', '2.15', 'devel',) if tags.has('core') else - ('latest', '2.9', 'devel') if tags.has('ansible') + ('latest', '9', '2.9', 'devel') if tags.has('ansible') else '' ), } From 4ef8336020683cc288decfa962cb91887cdb55e6 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 4 Jun 2024 11:45:40 -0400 Subject: [PATCH 396/536] Update release table for Ansible 10 and 9 (#1543) --- .../rst/reference_appendices/release_and_maintenance.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 8f68e1b2f70..c8833863b20 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -81,8 +81,9 @@ This table links to the changelogs for each major Ansible release. These changel ================================== ============================================== ========================= Ansible Community Package Release Status Core version dependency ================================== ============================================== ========================= -10.0.0 In development (unreleased) 2.17 -`9.x Changelogs`_ Current 2.16 +11.0.0 In development (unreleased) 2.18 +`10.x Changelogs`_ Current 2.17 +`9.x Changelogs`_ Minor/patch releases (EOL Nov 2024) 2.16 `8.x Changelogs`_ Unmaintained (end of life) 2.15 `7.x Changelogs`_ Unmaintained (end of life) 2.14 `6.x Changelogs`_ Unmaintained (end of life) 2.13 @@ -92,6 +93,7 @@ Ansible Community Package Release Status `2.10 Changelogs`_ Unmaintained (end of life) 2.10 ================================== ============================================== ========================= +.. _10.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/10/CHANGELOG-v10.md .. _9.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/9/CHANGELOG-v9.rst .. _8.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/8/CHANGELOG-v8.rst .. _7.x Changelogs: https://github.com/ansible-community/ansible-build-data/blob/main/7/CHANGELOG-v7.rst From e1a64d7705ec7cf2717f60f998f5f98993a1eed2 Mon Sep 17 00:00:00 2001 From: M15terHyde <59905806+M15terHyde@users.noreply.github.com> Date: Tue, 4 Jun 2024 20:17:35 -0500 Subject: [PATCH 397/536] Update playbooks_advanced_syntax.rst fixed YAML indentation --- .../rst/playbook_guide/playbooks_advanced_syntax.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst index a1327c2e051..c23dc5a7e17 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst @@ -62,10 +62,10 @@ You define an anchor with ``&``, then refer to it using an alias, denoted with ` opts: '-Xms1G -Xmx2G' port: 1000 path: /usr/lib/app1 - app2: - jvm: - <<: *jvm_opts - path: /usr/lib/app2 + app2: + jvm: + <<: *jvm_opts + path: /usr/lib/app2 ... Here, ``app1`` and ``app2`` share the values for ``opts`` and ``port`` using the anchor ``&jvm_opts`` and the alias ``*jvm_opts``. From 036ef725b477113d03fac24f6fa99e1923524d2d Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 5 Jun 2024 15:18:43 -0400 Subject: [PATCH 398/536] Add Ansible 10 to intersphinx links --- docs/docsite/rst/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 8b105a5fb4b..3f66caaa887 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -380,6 +380,7 @@ 'jinja2': ('http://jinja.palletsprojects.com/', None), 'ansible_2_9': ('https://docs.ansible.com/ansible/2.9/', None), 'ansible_9': ('https://docs.ansible.com/ansible/9/', None), + 'ansible_10': ('https://docs.ansible.com/ansible/10/', None), } # linckchecker settings From f35694520d18c36078f961334811a260a1ff0a40 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 5 Jun 2024 17:01:46 -0400 Subject: [PATCH 399/536] remove mailchimp subscribe from docs --- docs/docsite/rst/community/communication.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 1a0deaf5fe8..2cfa2de5297 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -224,7 +224,7 @@ The Bullhorn ============ **The Bullhorn** is our newsletter for the Ansible contributor community. You can get Bullhorn updates -from the :ref:`ansible_forum` or `subscribe `_ to receive it. +from the :ref:`ansible_forum`. If you have any questions or content you would like to share, you are welcome to chat with us in the `Ansible Social room on Matrix, and mention From 296ca61f0cf1627148e190e355337ffb297c30e6 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 6 Jun 2024 07:08:32 +0200 Subject: [PATCH 400/536] Update the Ansible 10 porting guide. (#1570) --- .../rst/porting_guides/porting_guide_10.rst | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst index b485ddaae0c..536ff920af0 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -18,7 +18,30 @@ We suggest you read this page along with the `Ansible 10 Changelog Date: Fri, 7 Jun 2024 01:55:01 +0800 Subject: [PATCH 401/536] Update playbooks_loops.rst (#1569) Document version requirement for retries without `until` keyword. --- docs/docsite/rst/playbook_guide/playbooks_loops.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index 95e9e3167d2..c8f808422e2 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -254,7 +254,7 @@ To see the results of individual retries, run the play with ``-vv``. When you run a task with ``until`` and register the result as a variable, the registered variable will include a key called "attempts", which records the number of retries for the task. -If ``until`` is not specified, the task will retry until the task succeeds but at most ``retries`` times. +If ``until`` is not specified, the task will retry until the task succeeds but at most ``retries`` times (New in version 2.16). You can combine the ``until`` keyword with ``loop`` or ``with_``. The result of the task for each element of the loop is registered in the variable and can be used in the ``until`` condition. Here is an example: From 952d5f6614f4abf2ef8afbca87e786eb1cdd1e58 Mon Sep 17 00:00:00 2001 From: Alexander Date: Thu, 6 Jun 2024 19:56:02 +0200 Subject: [PATCH 402/536] Update uptime.py (#1524) With one of the recent ansible upgrade (2.14 to 2.15) there is an error: No module named \ "Ansible_collections. Ansible. builtin " when executing the script. The added code initializes the plugin loader to solve this issue --- examples/scripts/uptime.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/examples/scripts/uptime.py b/examples/scripts/uptime.py index 38f2be9b1ac..cdb1f6653a3 100755 --- a/examples/scripts/uptime.py +++ b/examples/scripts/uptime.py @@ -13,6 +13,7 @@ from ansible.parsing.dataloader import DataLoader from ansible.playbook.play import Play from ansible.plugins.callback import CallbackBase +from ansible.plugins.loader import init_plugin_loader from ansible.vars.manager import VariableManager from ansible import context @@ -51,6 +52,7 @@ def v2_runner_on_failed(self, result, *args, **kwargs): def main(): + init_plugin_loader() host_list = ['localhost', 'www.example.com', 'www.google.com'] # since the API is constructed for CLI it expects certain options to always be set in the context object context.CLIARGS = ImmutableDict(module_path=['/to/mymodules', '/usr/share/ansible'], forks=10, become=None, From 430b3ea15f7df838229ebcf5205978c78a93a34c Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 6 Jun 2024 13:57:07 -0400 Subject: [PATCH 403/536] cause people keep doing this (#1567) * cause people keep doing this * Update docs/docsite/rst/inventory_guide/intro_inventory.rst Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- docs/docsite/rst/inventory_guide/intro_inventory.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index 0a3300f061c..fb6c1f68023 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -587,7 +587,7 @@ ansible_connection General for all connections: ansible_host - The name of the host to connect to, if different from the alias you wish to give to it. + The name of the host to connect to, if different from the alias you wish to give to it. Never set it to depend on ``inventory_hostname`` if you use delegation. ansible_port The connection port number, if not the default (22 for ssh) ansible_user From 7cdb75e8b90d864f248d3be3ba5689e95a2e7e7d Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 9 Jun 2024 00:11:41 +0000 Subject: [PATCH 404/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 8 ++++---- tests/requirements.txt | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 45ae64e323a..210fa91aa39 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -40,7 +40,7 @@ babel==2.15.0 # sphinx-intl build==1.2.1 # via antsibull-core -certifi==2024.2.2 +certifi==2024.6.2 # via requests charset-normalizer==3.3.2 # via requests @@ -83,11 +83,11 @@ packaging==24.0 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.7.2 +pydantic==2.7.3 # via # antsibull-core # antsibull-docs -pydantic-core==2.18.3 +pydantic-core==2.18.4 # via pydantic pygments==2.18.0 # via @@ -166,7 +166,7 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.12.1 +typing-extensions==4.12.2 # via # pydantic # pydantic-core diff --git a/tests/requirements.txt b/tests/requirements.txt index 07f3561016a..fc1ce137ee7 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -42,7 +42,7 @@ babel==2.15.0 # sphinx-intl build==1.2.1 # via antsibull-core -certifi==2024.2.2 +certifi==2024.6.2 # via requests charset-normalizer==3.3.2 # via requests @@ -85,11 +85,11 @@ packaging==24.0 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.7.2 +pydantic==2.7.3 # via # antsibull-core # antsibull-docs -pydantic-core==2.18.3 +pydantic-core==2.18.4 # via pydantic pygments==2.18.0 # via @@ -167,7 +167,7 @@ twiggy==0.5.1 # antsibull-docs types-docutils==0.18.3 # via rstcheck -typing-extensions==4.12.1 +typing-extensions==4.12.2 # via # pydantic # pydantic-core From 0ee91b1f5e255088777fa20f9659067396648a4d Mon Sep 17 00:00:00 2001 From: Jordan Borean Date: Wed, 12 Jun 2024 07:21:33 +1000 Subject: [PATCH 405/536] Fix up PowerShell and Windows support lifecycle (#1587) * Fix up PowerShell and Windows support lifecycle * Update docs/docsite/rst/reference_appendices/release_and_maintenance.rst Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- .../release_and_maintenance.rst | 35 +++++++++++-------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index c8833863b20..3b0d7aba8e9 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -54,9 +54,9 @@ The Ansible community team typically releases two major versions of the communit Starting with version 2.10, the Ansible community team guarantees maintenance for only one major community package release at a time. For example, when Ansible 4.0.0 gets released, the team will stop making new 3.x releases. Community members may maintain older versions if desired. -.. note:: - - Each Ansible EOL version may issue one final maintenance release at or shortly after the first release of the next version. When this happens, the final maintenance release is EOL at the date it releases. +.. note:: + + Each Ansible EOL version may issue one final maintenance release at or shortly after the first release of the next version. When this happens, the final maintenance release is EOL at the date it releases. .. note:: @@ -141,6 +141,13 @@ Starting with ``ansible-core`` version 2.16, each release includes target node s Support for Python 2.7 is included in ``ansible-core`` version 2.16 and earlier. +.. _target_node_windows_support: + +``ansible-core`` target node PowerShell and Windows support +----------------------------------------------------------- + +``ansible-core`` on Windows supports the baseline version of PowerShell that each Windows version ships with. For example, Windows Server 2016 shipped with PowerShell 5.1 so Ansible will support PowerShell 5.1 for the life of Windows Server 2016 support. Support for each Windows version is determined by the Windows lifecycle policy and when each version reaches the extended end date. For example Windows Server 2012 and 2012 R2 extended end date was for October 10th 2023 while Windows Server 2016 is January 12th 2027. Windows support does not align with the 3 year Extended Security Updates (``ESU``) support from Microsoft which is a paid support option for products that are past the normal end of support date from Microsoft. + .. _ansible_core_support_matrix: ``ansible-core`` support matrix @@ -151,7 +158,7 @@ Dates listed indicate the start date of the maintenance cycle. .. list-table:: :header-rows: 1 - + * - Version - Support - End Of Life @@ -164,7 +171,7 @@ Dates listed indicate the start date of the maintenance cycle. - Nov 2025 - | Python 3.10 - 3.12 - | Python 3.7 - 3.12 - | PowerShell 3 - 5.1 + | PowerShell 5.1 * - `2.16`_ - | GA: 06 Nov 2023 | Critical: 20 May 2024 @@ -173,7 +180,7 @@ Dates listed indicate the start date of the maintenance cycle. - | Python 3.10 - 3.12 - | Python 2.7 | Python 3.6 - 3.12 - | Powershell 3 - 5.1 + | Powershell 5.1 * - `2.15`_ - | GA: 22 May 2023 | Critical: 06 Nov 2023 @@ -253,7 +260,7 @@ Dates listed indicate the start date of the maintenance cycle. .. - May 2026 .. - | Python 3.11 - 3.13 .. - | Python 3.8 - 3.13 -.. | PowerShell TBD +.. | PowerShell 5.1 .. * - 2.19 .. - May 2025 .. - Nov 2025 @@ -261,7 +268,7 @@ Dates listed indicate the start date of the maintenance cycle. .. - Nov 2026 .. - | Python 3.11 - 3.13 .. - | Python 3.8 - 3.13 -.. | PowerShell TBD +.. | PowerShell 5.1 .. * - 2.20 .. - Nov 2025 .. - May 2026 @@ -269,7 +276,7 @@ Dates listed indicate the start date of the maintenance cycle. .. - May 2027 .. - | Python 3.12 - 3.14 .. - | Python 3.9 - 3.14 -.. | PowerShell TBD +.. | PowerShell 5.1 .. * - 2.21 .. - May 2026 .. - Nov 2026 @@ -277,7 +284,7 @@ Dates listed indicate the start date of the maintenance cycle. .. - Nov 2027 .. - | Python 3.12 - 3.14 .. - | Python 3.9 - 3.14 -.. | PowerShell TBD +.. | PowerShell 5.1 .. * - 2.22 .. - Nov 2026 .. - May 2027 @@ -285,7 +292,7 @@ Dates listed indicate the start date of the maintenance cycle. .. - May 2028 .. - | Python 3.13 - 3.15 .. - | Python 3.9 - 3.15 -.. | PowerShell TBD +.. | PowerShell 5.1 .. * - 2.23 .. - May 2027 .. - Nov 2027 @@ -293,7 +300,7 @@ Dates listed indicate the start date of the maintenance cycle. .. - Nov 2028 .. - | Python 3.13 - 3.15 .. - | Python 3.10 - 3.15 -.. | PowerShell TBD +.. | PowerShell 5.1 .. * - 2.24 .. - Nov 2027 .. - May 2028 @@ -301,7 +308,7 @@ Dates listed indicate the start date of the maintenance cycle. .. - May 2029 .. - | Python 3.14 - 3.16 .. - | Python 3.11 - 3.16 -.. | PowerShell TBD +.. | PowerShell 5.1 .. * - 2.25 .. - May 2028 .. - Nov 2028 @@ -309,7 +316,7 @@ Dates listed indicate the start date of the maintenance cycle. .. - Nov 2029 .. - | Python 3.14 - 3.16 .. - | Python 3.11 - 3.16 -.. | PowerShell TBD +.. | PowerShell 5.1 .. _2.9: https://github.com/ansible/ansible/blob/stable-2.9/changelogs/CHANGELOG-v2.9.rst From 3a1de281ccea0965eb63e9654169a2e9d46bda66 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Wed, 12 Jun 2024 16:28:01 -0500 Subject: [PATCH 406/536] Add 2.18 roadmap (#1590) --- docs/docsite/rst/roadmap/ROADMAP_2_18.rst | 73 +++++++++++++++++++ .../roadmap/ansible_core_roadmap_index.rst | 1 + 2 files changed, 74 insertions(+) create mode 100644 docs/docsite/rst/roadmap/ROADMAP_2_18.rst diff --git a/docs/docsite/rst/roadmap/ROADMAP_2_18.rst b/docs/docsite/rst/roadmap/ROADMAP_2_18.rst new file mode 100644 index 00000000000..93e218bca8a --- /dev/null +++ b/docs/docsite/rst/roadmap/ROADMAP_2_18.rst @@ -0,0 +1,73 @@ +.. _core_roadmap_2.18: + +***************** +Ansible-core 2.18 +***************** + +.. contents:: + :local: + +Release Schedule +================ + +Expected +-------- + +PRs must be raised well in advance of the dates below to have a chance of being included in this ansible-core release. + +.. note:: Dates subject to change. + +Development Phase +^^^^^^^^^^^^^^^^^ + +The ``milestone`` branch will be advanced at the start date of each development phase, and the beta 1 release. + +- 2024-04-29 Development Phase 1 +- 2024-06-24 Development Phase 2 +- 2024-08-05 Development Phase 3 +- 2024-09-23 Beta 1 + +Release Phase +^^^^^^^^^^^^^ + +- 2024-09-16 Feature Freeze (and ``stable-2.18`` branching from ``devel``) + No new functionality (including modules/plugins) to any code + +- 2024-09-23 Beta 1 + +- 2024-10-14 Release Candidate 1 + +- 2024-11-04 Release + +.. note:: The beta and release candidate schedules allow for up to 3 releases on a weekly schedule depending on the necessity of creating a release. + +Release Manager +=============== + + Ansible Core Team + +Planned work +============ + +* Drop Python 3.10, and add Python 3.13 for controller code +* Drop Python 3.7, and add Python 3.13 for target code +* Data Tagging +* Add support to ansible-galaxy for new console.redhat.com service account auth +* Finalize task object connection attribute for connection reporting in callbacks +* Add break functionality for task loops +* Add new non-local mount facts +* Evaluate changes to strategy plugins to use the core strategy result processing for meta task results +* Remove deprecated functionality +* Decrease incidental integration tests +* Add controller type hinting for discrete areas of the code +* Decrease testing sanity ignores +* Update ansible-test container images and VMs +* Update ansible-test dependencies + + +Delayed work +============ + +The following work has been delayed and retargeted for a future release: + +* TBD diff --git a/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst b/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst index d5a9af200d9..02e964e406d 100644 --- a/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst +++ b/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst @@ -24,6 +24,7 @@ See :ref:`Ansible communication channels ` for details on how to :glob: :caption: ansible-core Roadmaps + ROADMAP_2_18 ROADMAP_2_17 ROADMAP_2_16 ROADMAP_2_15 From e7ebe3d2388212cb2794dc44d16e21d2c4294bfa Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 13 Jun 2024 19:05:36 +0100 Subject: [PATCH 407/536] add steps to deploy doc build assets (#1353) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * add steps to deploy doc build assets to prod Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) * Update .github/workflows/build-package-docs.yaml Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) * use GH actions bot * environment name and url * add input for deploy job and target * add git diff-index quiet head * use deploy key and git push * add steps to deploy to gh-pages as a test site * update branch name input for prod * make envs more consistent * use same branch name for destination * rm extra empty line * Update .github/workflows/build-package-docs.yaml Co-authored-by: Felix Fontein * github env consistency * simplify tar extract step to use one-top-level * Update .github/workflows/build-package-docs.yaml Co-authored-by: Felix Fontein * set environment url --------- Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) Co-authored-by: Felix Fontein --- .github/workflows/build-package-docs.yaml | 104 +++++++++++++++++++++- 1 file changed, 103 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index aa00854f026..cc12254e610 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -39,7 +39,18 @@ on: type: boolean description: Add latest symlink required: true - + deploy: + type: boolean + description: Deploy the build + required: true + deployment-environment: + type: choice + description: Deployment environment + required: true + default: test + options: + - production + - test env: PACKAGE_VERSION: ${{ github.event.inputs.ansible-package-version }} @@ -120,3 +131,94 @@ jobs: name: package-docs-build path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz retention-days: 7 + + deploy-package-docs: + if: fromJSON(github.event.inputs.deploy) + needs: build-package-docs + runs-on: ubuntu-latest + environment: + name: deploy-package-docs + url: ${{ env.ENV_URL }} + env: + TARGET: ${{ github.event.inputs.deployment-environment }} + DEST_REPO: ansible-community/package-doc-builds + USER_EMAIL: "41898282+github-actions[bot]@users.noreply.github.com" + USER_NAME: "github-actions[bot]" + steps: + - name: Download the build archive + uses: actions/download-artifact@v4 + with: + name: package-docs-build + + - name: Extract the tarball + run: >- + tar -xvzf + ansible-package-docs-html-*.tar.gz + --one-top-level + + - name: Set the production branch and url + if: env.TARGET == 'production' + env: + BRANCH_NAME: ${{ github.event.inputs.repository-branch }} + PROD_URL: https://ansible.readthedocs.io/projects/ansible/en + run: | + echo "BRANCH=${BRANCH_NAME}" >> "${GITHUB_ENV}" + echo "ENV_URL=${PROD_URL}/${BRANCH_NAME}" >> "${GITHUB_ENV}" + + - name: Set the test branch and url + if: env.TARGET == 'test' + env: + TEST_URL: https://ansible-community.github.io/package-doc-builds + run: | + echo "BRANCH=gh-pages" >> "${GITHUB_ENV}" + echo "ENV_URL=${TEST_URL}" >> "${GITHUB_ENV}" + + - name: Checkout the deploy directory + uses: actions/checkout@v4 + with: + repository: ${{ env.DEST_REPO }} + ref: ${{ env.BRANCH }} + path: deploy-directory + fetch-depth: 0 + ssh-key: ${{ secrets.DEPLOY_DOC_BUILD }} + persist-credentials: true + + - name: Copy the generated HTML and assets for production + run: >- + rsync -av --delete --mkpath + ansible-package-docs-html-*/ + deploy-directory/docs + + - name: Create a norobots.txt file for the test site + if: env.TARGET == 'test' + run: | + touch norobots.txt + echo "User-agent: *" > norobots.txt + echo "Disallow: /" >> norobots.txt + working-directory: deploy-directory/docs + + - name: Configure the git user + run: | + git config --local user.email "${USER_EMAIL}" + git config --local user.name "${USER_NAME}" + working-directory: deploy-directory + + - name: Git add the generated HTML and assets + run: git add ./docs --all --force + working-directory: deploy-directory + + - name: Commit generated HTML and assets + run: >- + git diff-index --quiet HEAD || + git commit -m "Push docs build $(date '+%Y-%m-%d')-${{ + github.run_id + }}-${{ + github.run_number + }}-${{ + github.run_attempt + }}" + working-directory: deploy-directory + + - name: Push build to deploy repository + run: git push origin + working-directory: deploy-directory From 4fd8c58945291cdf3c6a896f9cb18b11a0da10b3 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 13 Jun 2024 14:23:03 -0400 Subject: [PATCH 408/536] clarify how to verify collection-level docs (#1589) * clarify how to verify collection-level docs * Update docs/docsite/rst/community/documentation_contributions.rst --- .../rst/community/documentation_contributions.rst | 5 +++-- .../dev_guide/developing_collections_documenting.rst | 10 ++++++++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index c10c0a10843..b701eed95ec 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -74,7 +74,7 @@ A great documentation GitHub issue or PR includes: Verifying your documentation PR ================================ -If you make multiple changes to the documentation, or add more than a line to it, before you open a pull request, please: +If you make multiple changes to the Ansible documentation, or add more than a line to it, before you open a pull request, please: #. Check that your text follows our :ref:`style_guide`. #. Test your changes for rST errors. @@ -82,7 +82,8 @@ If you make multiple changes to the documentation, or add more than a line to it .. note:: - The following sections apply to documentation sourced from the ``ansible/ansible-documentation`` repo and does not apply to documentation from an individual collection. See the collection README file for details on how to contribute to that collection. + The following sections apply to documentation sourced from the ``ansible/ansible-documentation`` repo and does not apply to documentation from an individual collection. See the collection README file for details on how to contribute to that collection. Collection developers can also lint their collection-level documentation. See :ref:`verify_collection_docs` for details. + Setting up your environment to build documentation locally ---------------------------------------------------------- diff --git a/docs/docsite/rst/dev_guide/developing_collections_documenting.rst b/docs/docsite/rst/dev_guide/developing_collections_documenting.rst index f80b75e9384..456fc5c7593 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_documenting.rst @@ -14,6 +14,16 @@ Documenting roles To document a role, you have to add a role argument spec by creating a file ``meta/argument_specs.yml`` in your role. See :ref:`role_argument_spec` for details. As an example, you can look at `the argument specs file `_ of the :ansplugin:`sensu.sensu_go.install role ` on GitHub. + +.. _verify_collection_docs: + +Verifying your collection documentation +======================================= + +You can use ``antsibull-docs`` to lint your collection documentation. +See `Linting collection documentation `_. +for details. + .. _build_collection_docsite: Build a docsite with antsibull-docs From 7a60bbac069dd9aa8749dae06aca34b2f20b6679 Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 9 Jun 2024 00:06:45 +0000 Subject: [PATCH 409/536] ci: refresh dev dependencies --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 26d65805f0d..30bb9812364 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -20,5 +20,5 @@ platformdirs==4.2.2 # via black tomli==2.0.1 # via black -typing-extensions==4.12.1 +typing-extensions==4.12.2 # via black diff --git a/tests/static.txt b/tests/static.txt index 890cc866d7f..d5107968a24 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.4.7 +ruff==0.4.8 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 347cb87c8a8..c2ea7be79ee 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -6,7 +6,7 @@ # argcomplete==3.3.0 # via nox -certifi==2024.2.2 +certifi==2024.6.2 # via requests cffi==1.16.0 # via @@ -20,7 +20,7 @@ codeowners==0.7.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 # via nox -cryptography==42.0.7 +cryptography==42.0.8 # via pyjwt deprecated==1.2.14 # via pygithub @@ -80,7 +80,7 @@ typer==0.12.3 # via # -r tests/../hacking/pr_labeler/requirements.txt # -r tests/../hacking/tagger/requirements.txt -typing-extensions==4.12.1 +typing-extensions==4.12.2 # via # codeowners # mypy From a7812fd0f3df70765c649b350152092a497909df Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 16 Jun 2024 00:06:21 +0000 Subject: [PATCH 410/536] ci: refresh dev dependencies --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 30bb9812364..fb3fda3d9f7 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -12,7 +12,7 @@ isort==5.13.2 # via -r tests/formatters.in mypy-extensions==1.0.0 # via black -packaging==24.0 +packaging==24.1 # via black pathspec==0.12.1 # via black diff --git a/tests/static.txt b/tests/static.txt index d5107968a24..e206a188061 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.4.8 +ruff==0.4.9 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index c2ea7be79ee..2a77c16edf9 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -26,7 +26,7 @@ deprecated==1.2.14 # via pygithub distlib==0.3.8 # via virtualenv -filelock==3.14.0 +filelock==3.15.1 # via virtualenv gitdb==4.0.11 # via gitpython @@ -48,7 +48,7 @@ mypy-extensions==1.0.0 # via mypy nox==2024.4.15 # via -r tests/typing.in -packaging==24.0 +packaging==24.1 # via # -r tests/../hacking/tagger/requirements.txt # nox From 8683009cb83e75ccec83422f94c91c4f7bac225d Mon Sep 17 00:00:00 2001 From: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 16 Jun 2024 00:11:08 +0000 Subject: [PATCH 411/536] ci: refresh docs build dependencies --- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 210fa91aa39..b85be64334f 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -74,7 +74,7 @@ multidict==6.0.5 # via # aiohttp # yarl -packaging==24.0 +packaging==24.1 # via # antsibull-changelog # antsibull-core @@ -83,7 +83,7 @@ packaging==24.0 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.7.3 +pydantic==2.7.4 # via # antsibull-core # antsibull-docs diff --git a/tests/requirements.txt b/tests/requirements.txt index fc1ce137ee7..cdf4f635e44 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -76,7 +76,7 @@ multidict==6.0.5 # via # aiohttp # yarl -packaging==24.0 +packaging==24.1 # via # antsibull-changelog # antsibull-core @@ -85,7 +85,7 @@ packaging==24.0 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.7.3 +pydantic==2.7.4 # via # antsibull-core # antsibull-docs From ea82742348946bcb08820197ea69ddbef2a4dbfb Mon Sep 17 00:00:00 2001 From: jeremy-bryant <71235811+jeremy-bryant@users.noreply.github.com> Date: Tue, 18 Jun 2024 11:07:47 +0100 Subject: [PATCH 412/536] Fix typo in communication.rst (#1598) * Fix typo in communication.rst Fix typo in /msg alias This should be /msg alis as described in the link https://libera.chat/guides/findingchannels * ignore alis spell check --------- Co-authored-by: Don Naro --- .codespellignorelines | 1 + docs/docsite/rst/community/communication.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.codespellignorelines b/.codespellignorelines index 2eed9ae6cc1..6768407657e 100644 --- a/.codespellignorelines +++ b/.codespellignorelines @@ -16,3 +16,4 @@ see the `Active Directory Certificate Services documentation `_. From 4c4afe3663c1ab78cb29ef9f84b9011b18118c3d Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 18 Jun 2024 11:11:45 +0100 Subject: [PATCH 413/536] use the package version as the branch name (#1600) This change configures the publishing workflow to use the package version as the branch name in the destination repository. For example the branch name should be "10" for the Ansible 10 package. This ensures that the resulting url for the published docs uses the version and not the branch name. --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index cc12254e610..6956e93a5a3 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -159,7 +159,7 @@ jobs: - name: Set the production branch and url if: env.TARGET == 'production' env: - BRANCH_NAME: ${{ github.event.inputs.repository-branch }} + BRANCH_NAME: ${{ github.event.inputs.ansible-package-version }} PROD_URL: https://ansible.readthedocs.io/projects/ansible/en run: | echo "BRANCH=${BRANCH_NAME}" >> "${GITHUB_ENV}" From c3cd7bd7e0f699126a67aa567909572b81ce83d0 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 18 Jun 2024 11:22:32 +0100 Subject: [PATCH 414/536] rm translation from rtd url The Read The Docs project for the package docs builds use the "Multiple versions without translations" versioning scheme. The resulting url has the `/` format. --- .github/workflows/build-package-docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 6956e93a5a3..94e78beede6 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -160,7 +160,7 @@ jobs: if: env.TARGET == 'production' env: BRANCH_NAME: ${{ github.event.inputs.ansible-package-version }} - PROD_URL: https://ansible.readthedocs.io/projects/ansible/en + PROD_URL: https://ansible.readthedocs.io/projects/ansible/ run: | echo "BRANCH=${BRANCH_NAME}" >> "${GITHUB_ENV}" echo "ENV_URL=${PROD_URL}/${BRANCH_NAME}" >> "${GITHUB_ENV}" From 0a8816e1a04f33a21712dc2ebba7589266d52445 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 18 Jun 2024 13:29:00 +0200 Subject: [PATCH 415/536] Add porting guide for 9.7.0. (#1609) --- .../rst/porting_guides/porting_guide_9.rst | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 7feefabb34c..6b514011724 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -84,6 +84,40 @@ Porting custom scripts Networking ========== +Porting Guide for v9.7.0 +======================== + +Known Issues +------------ + +community.general +~~~~~~~~~~~~~~~~~ + +- homectl - the module does not work under Python 3.13 or newer, since it relies on the removed ``crypt`` standard library module (https://github.com/ansible-collections/community.general/issues/4691, https://github.com/ansible-collections/community.general/pull/8497). +- udm_user - the module does not work under Python 3.13 or newer, since it relies on the removed ``crypt`` standard library module (https://github.com/ansible-collections/community.general/issues/4690, https://github.com/ansible-collections/community.general/pull/8497). + +Major Changes +------------- + +containers.podman +~~~~~~~~~~~~~~~~~ + +- Add mount and unmount for volumes +- Add multiple subnets for networks +- Add new options for podman_container +- Add new options to pod module +- Add podman search +- Improve idempotency for networking in podman_container +- Redesign idempotency for Podman Pod module + +Removed Features +---------------- + +community.grafana +~~~~~~~~~~~~~~~~~ + +- removed deprecated `message` argument in `grafana_dashboard` + Porting Guide for v9.6.0 ======================== From deaf1fd6567b14477aa59fc5682d79577c72cede Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 18 Jun 2024 13:29:13 +0200 Subject: [PATCH 416/536] Add porting guide for Ansible 10.1.0. (#1610) --- .../rst/porting_guides/porting_guide_10.rst | 60 ++++++++++++++++++- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst index 536ff920af0..cd8261f3dea 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -99,6 +99,62 @@ Networking No notable changes +Porting Guide for v10.1.0 +========================= + +Added Collections +----------------- + +- ieisystem.inmanage (version 2.0.0) + +Known Issues +------------ + +community.general +~~~~~~~~~~~~~~~~~ + +- homectl - the module does not work under Python 3.13 or newer, since it relies on the removed ``crypt`` standard library module (https://github.com/ansible-collections/community.general/issues/4691, https://github.com/ansible-collections/community.general/pull/8497). +- udm_user - the module does not work under Python 3.13 or newer, since it relies on the removed ``crypt`` standard library module (https://github.com/ansible-collections/community.general/issues/4690, https://github.com/ansible-collections/community.general/pull/8497). + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + +Major Changes +------------- + +containers.podman +~~~~~~~~~~~~~~~~~ + +- Add mount and unmount for volumes +- Add multiple subnets for networks +- Add new options for podman_container +- Add new options to pod module +- Add podman search +- Improve idempotency for networking in podman_container +- Redesign idempotency for Podman Pod module + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- Added support to use session ID for authentication of iDRAC, OpenManage Enterprise and OpenManage Enterprise Modular. +- ome_session - This module allows you to create and delete the sessions on OpenManage Enterprise and OpenManage Enterprise Modular. + +Deprecated Features +------------------- + +community.general +~~~~~~~~~~~~~~~~~ + +- CmdRunner module util - setting the value of the ``ignore_none`` parameter within a ``CmdRunner`` context is deprecated and that feature should be removed in community.general 12.0.0 (https://github.com/ansible-collections/community.general/pull/8479). +- git_config - the ``list_all`` option has been deprecated and will be removed in community.general 11.0.0. Use the ``community.general.git_config_info`` module instead (https://github.com/ansible-collections/community.general/pull/8453). +- git_config - using ``state=present`` without providing ``value`` is deprecated and will be disallowed in community.general 11.0.0. Use the ``community.general.git_config_info`` module instead to read a value (https://github.com/ansible-collections/community.general/pull/8453). + Porting Guide for v10.0.0 ========================= @@ -456,7 +512,7 @@ cisco.nxos community.dns ~~~~~~~~~~~~~ -- The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 3.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug (https://github.com/ansible-collections/community.dns/pull/196). +- The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 3.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, and ansible-core 2.13 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug (https://github.com/ansible-collections/community.dns/pull/196). - hetzner_dns_record_set, hetzner_dns_record - the deprecated alias ``name`` of the prefix option was removed (https://github.com/ansible-collections/community.dns/pull/196). - hosttech_dns_records - the redirect to the ``hosttech_dns_record_sets`` module has been removed (https://github.com/ansible-collections/community.dns/pull/196). @@ -484,7 +540,7 @@ community.grafana community.hrobot ~~~~~~~~~~~~~~~~ -- The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 2.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug (https://github.com/ansible-collections/community.hrobot/pull/101). +- The collection no longer supports Ansible, ansible-base, and ansible-core releases that are currently End of Life at the time of the 2.0.0 release. This means that Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, and ansible-core 2.13 are no longer supported. The collection might still work with these versions, but it can stop working at any moment without advance notice, and this will not be considered a bug (https://github.com/ansible-collections/community.hrobot/pull/101). junipernetworks.junos ~~~~~~~~~~~~~~~~~~~~~ From 24bded91f9879ddc5d7dcc817b04d7e7b756f07f Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Thu, 20 Jun 2024 15:24:41 -0500 Subject: [PATCH 417/536] Add 2.18 support matrix entry (#1618) * Add 2.18 support matrix entry * fix indentation --- .../release_and_maintenance.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 3b0d7aba8e9..3275814d471 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -164,6 +164,14 @@ Dates listed indicate the start date of the maintenance cycle. - End Of Life - Control Node Python - Target Python / PowerShell + * - `2.18`_ + - | GA: 04 Nov 2024 + | Critical: 19 May 2025 + | Security: 03 Nov 2025 + - May 2026 + - | Python 3.10 - 3.13 + - | Python 3.8 - 3.13 + | PowerShell 5.1 * - `2.17`_ - | GA: 20 May 2024 | Critical: 04 Nov 2024 @@ -253,14 +261,6 @@ Dates listed indicate the start date of the maintenance cycle. - | Python 2.6 - 2.7 | Python 3.5 - 3.8 | PowerShell 3 - 5.1 -.. * - 2.18 -.. - Nov 2024 -.. - May 2025 -.. - Nov 2025 -.. - May 2026 -.. - | Python 3.11 - 3.13 -.. - | Python 3.8 - 3.13 -.. | PowerShell 5.1 .. * - 2.19 .. - May 2025 .. - Nov 2025 @@ -328,6 +328,7 @@ Dates listed indicate the start date of the maintenance cycle. .. _2.15: https://github.com/ansible/ansible/blob/stable-2.15/changelogs/CHANGELOG-v2.15.rst .. _2.16: https://github.com/ansible/ansible/blob/stable-2.16/changelogs/CHANGELOG-v2.16.rst .. _2.17: https://github.com/ansible/ansible/blob/stable-2.17/changelogs/CHANGELOG-v2.17.rst +.. _2.18: https://github.com/ansible/ansible/blob/stable-2.18/changelogs/CHANGELOG-v2.18.rst From 6f223211643283594f87010f20678a7736e62239 Mon Sep 17 00:00:00 2001 From: Japje Date: Thu, 20 Jun 2024 22:25:35 +0200 Subject: [PATCH 418/536] Update playbooks_loops.rst (#1617) update example to correct typo --- docs/docsite/rst/playbook_guide/playbooks_loops.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index c8f808422e2..27f1d120fea 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -493,7 +493,7 @@ To avoid this, you can specify the name of the variable for each loop using ``lo .. code-block:: yaml+jinja # main.yml - - include_task: inner.yml + - include_tasks: inner.yml loop: - 1 - 2 From 678e113aa77e3e21382c4b066ca56ca009a37b38 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Thu, 20 Jun 2024 13:40:10 -0700 Subject: [PATCH 419/536] Update unit test document (#1597) * Update unit test document Fixes: ansible/ansible#83034 Signed-off-by: Abhijeet Kasurde * Apply suggestions from code review Co-authored-by: Don Naro --------- Signed-off-by: Abhijeet Kasurde Co-authored-by: Don Naro --- docs/docsite/rst/dev_guide/testing.rst | 35 +++++++++++++++----------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/docs/docsite/rst/dev_guide/testing.rst b/docs/docsite/rst/dev_guide/testing.rst index e7d33db9552..aef6edfa314 100644 --- a/docs/docsite/rst/dev_guide/testing.rst +++ b/docs/docsite/rst/dev_guide/testing.rst @@ -11,9 +11,9 @@ Testing Ansible Why test your Ansible contributions? ==================================== -If you're a developer, one of the most valuable things you can do is to look at GitHub issues and help fix bugs, since bug-fixing is almost always prioritized over feature development. Even for non-developers, helping to test pull requests for bug fixes and features is still immensely valuable. +If you're a developer, one of the most valuable things you can do is to look at GitHub issues and help fix bugs, since bug-fixing is almost always prioritized over feature development. Even for non-developers, helping to test pull requests for bug fixes and features is still immensely valuable. -Ansible users who understand how to write playbooks and roles should be able to test their work. GitHub pull requests will automatically run a variety of tests (for example, Azure Pipelines) that show bugs in action. However, contributors must also test their work outside of the automated GitHub checks and show evidence of these tests in the PR to ensure that their work will be more likely to be reviewed and merged. +Ansible users who understand how to write playbooks and roles should be able to test their work. GitHub pull requests will automatically run a variety of tests (for example, Azure Pipelines) that show bugs in action. However, contributors must also test their work outside of the automated GitHub checks and show evidence of these tests in the pull request to ensure that their work will be more likely to be reviewed and merged. Read on to learn how Ansible is tested, how to test your contributions locally, and how to extend testing capabilities. @@ -24,7 +24,7 @@ If you want to learn about testing collections, read :ref:`testing_collections` Types of tests ============== -At a high level we have the following classifications of tests: +At a high level, we have the following classifications of tests: :sanity: * :ref:`testing_sanity` @@ -83,22 +83,29 @@ Occasionally you may find your PR fails due to a reason unrelated to your change * a temporary issue accessing an external resource, such as a yum or git repo * a timeout creating a virtual machine to run the tests on -If either of these issues appear to be the case, you can rerun the Azure Pipelines test by: +If either issue appears to be the case, you can rerun the Azure Pipelines test by: -* adding a comment with ``/rebuild`` (full rebuild) or ``/rebuild_failed`` (rebuild only failed CI nodes) to the PR -* closing and re-opening the PR (full rebuild) -* making another change to the PR and pushing to GitHub +* adding a comment with ``/rebuild`` (full rebuild) or ``/rebuild_failed`` (rebuild only failed CI nodes) to the pull request +* closing and re-opening the pull request (full rebuild) +* making another change to the branch and pushing to GitHub -If the issue persists, please contact us in the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_). +If the issue persists, please contact us in the ``#ansible-devel`` chat channel (using `Matrix `_ or using IRC at `irc.libera.chat `_). How to test a PR ================ -Ideally, code should add tests that prove that the code works. That's not always possible and tests are not always comprehensive, especially when a user doesn't have access to a wide variety of platforms, or is using an API or web service. In these cases, live testing against real equipment can be more valuable than automation that runs against simulated interfaces. In any case, things should always be tested manually the first time as well. +Ideally, the code should add tests that prove that the code works. That's not always possible and tests are not always comprehensive, especially when a user doesn't have access to a wide variety of platforms, or is using an API or web service. In these cases, live testing against real equipment can be more valuable than automation that runs against simulated interfaces. In any case, things should always be tested manually the first time as well. Thankfully, helping to test Ansible is pretty straightforward, assuming you are familiar with how Ansible works. +Setup: Installing Pytest and required Pytest libraries +------------------------------------------------------ + +Ansible's unit testing framework leverages the pytest library. Before diving into testing, ensure you have ``pytest`` installed alongside any additional pytest libraries such as ``pytest-mock`` and ``pytest-xdist``. + +Refer to the documentation for more information: :ref:`testing_units`. + Setup: Checking out a Pull Request ---------------------------------- @@ -126,7 +133,7 @@ Create a fresh area to work: git clone https://github.com/ansible/ansible.git ansible-pr-testing cd ansible-pr-testing -Next, find the pull request you'd like to test and make note of its number. It will look something like this: +Next, find the pull request you'd like to test and make a note of its number. It will look something like this: .. code-block:: text @@ -224,11 +231,11 @@ If the PR does not resolve the issue, or if you see any failures from the unit/i Code Coverage Online ^^^^^^^^^^^^^^^^^^^^ -`The online code coverage reports `_ are a good way +`The online code coverage reports `_ is a good way to identify areas for testing improvement in Ansible. By following red colors you can -drill down through the reports to find files which have no tests at all. Adding both -integration and unit tests which show clearly how code should work, verify important -Ansible functions and increase testing coverage in areas where there is none is a valuable +drill down through the reports to find files that have no tests at all. Adding both +integration and unit tests that show clearly how code should work, verify important +Ansible functions and increases testing coverage in areas where there is none is a valuable way to help improve Ansible. The code coverage reports only cover the ``devel`` branch of Ansible where new feature From bacf38f2464949f58cf37ebdeb10936b86d16e12 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 20 Jun 2024 16:40:42 -0400 Subject: [PATCH 420/536] Replace WG list with a pointer to the forum groups . (#1596) * Replace WG list with a pointer to the forum groups for single source of truth * add matrix link --- docs/docsite/rst/community/communication.rst | 28 ++------------------ 1 file changed, 2 insertions(+), 26 deletions(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 46723df3214..5d8dfbc42f5 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -130,35 +130,11 @@ Working groups Working Groups are a way for Ansible community members to self-organize around particular topics of interest. -Our community working groups are represented in Matrix rooms and `Forum groups `_. +Our community working groups are represented in `Matrix rooms `_ and `Forum groups `_. +See those links for a complete list of communications channels. Many of them meet in chat. If you want to get involved in a working group, join the Matrix room or IRC channel where it meets or comment on the agenda. -- `AAP Configuration as Code `_ - Matrix: `#aap_config_as_code:ansible.com `_ -- `Amazon (AWS) Working Group `_ - Matrix: `#aws:ansible.com `_ | IRC: ``#ansible-aws`` -- `AWX Working Group `_ - Matrix: `#awx:ansible.com `_ | IRC: ``#ansible-awx`` -- Azure Working Group - Matrix: `#azure:ansible.com `_ | IRC: ``#ansible-azure`` -- `Community Working Group `_ (including Meetups) - Matrix: `#community:ansible.com `_ | IRC: ``#ansible-community`` -- Container Working Group - Matrix: `#container:ansible.com `_ | IRC: ``#ansible-container`` -- DigitalOcean Working Group - Matrix: `#digitalocean:ansible.im `_ | IRC: ``#ansible-digitalocean`` -- Diversity Working Group - Matrix: `#diversity:ansible.com `_ | IRC: ``#ansible-diversity`` -- Docker Working Group - Matrix: `#devel:ansible.com `_ | IRC: ``#ansible-devel`` -- `Documentation Working Group `_ - Matrix: `#docs:ansible.com `_ | IRC: ``#ansible-docs`` -- `Execution Environments Group `_ -- `Galaxy Working Group `_ - Matrix: `#galaxy:ansible.com `_ | IRC: ``#ansible-galaxy`` -- JBoss Working Group - Matrix: `#jboss:ansible.com `_ | IRC: ``#ansible-jboss`` -- Kubernetes Working Group - Matrix: `#kubernetes:ansible.com `_ | IRC: ``#ansible-kubernetes`` -- Linode Working Group - Matrix: `#linode:ansible.com `_ | IRC: ``#ansible-linode`` -- Molecule Working Group (`testing platform for Ansible playbooks and roles `_) - Matrix: `#molecule:ansible.im `_ | IRC: ``#ansible-molecule`` -- MySQL Working Group - Matrix: `#mysql:ansible.com `_ -- `Network Working Group `_ - Matrix: `#network:ansible.com `_ | IRC: ``#ansible-network`` -- `PostgreSQL Working Group `_ - Matrix: `#postgresql:ansible.com `_ -- `Release Management Working Group `_ - Matrix: `#release-management:ansible.com `_ -- Remote Management Working Group - Matrix: `#devel:ansible.com `_ | IRC: ``#ansible-devel`` -- Storage Working Group - Matrix: `#storage:ansible.com `_ | IRC: ``#ansible-storage`` -- VMware Working Group - Matrix: `#vmware:ansible.com `_ | IRC: ``#ansible-vmware`` -- Windows Working Group - Matrix: `#windows:ansible.com `_ | IRC: ``#ansible-windows`` -- Ansible developer tools Group - Matrix: `#devtools:ansible.com `_ | IRC: ``#ansible-devtools`` Forming a new working group ---------------------------- From 91a9b483c50fcda42d636ec9e54c5d787072e2b5 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Fri, 21 Jun 2024 17:24:47 +0200 Subject: [PATCH 421/536] developing_collections_migrating.rst: update (#1605) * developing_collections_migrating.rst: update * Update docs/docsite/rst/dev_guide/developing_collections_migrating.rst Co-authored-by: Don Naro * Update docs/docsite/rst/dev_guide/developing_collections_migrating.rst Co-authored-by: Don Naro * Update docs/docsite/rst/dev_guide/developing_collections_migrating.rst Co-authored-by: Don Naro * Update docs/docsite/rst/dev_guide/developing_collections_migrating.rst Co-authored-by: Don Naro * Update docs/docsite/rst/dev_guide/developing_collections_migrating.rst Co-authored-by: Don Naro * Update docs/docsite/rst/dev_guide/developing_collections_migrating.rst Co-authored-by: Sandra McCann * Update docs/docsite/rst/dev_guide/developing_collections_migrating.rst Co-authored-by: Sandra McCann * Mention old collection to update FQCN --------- Co-authored-by: Don Naro Co-authored-by: Sandra McCann --- .../dev_guide/developing_collections_migrating.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections_migrating.rst b/docs/docsite/rst/dev_guide/developing_collections_migrating.rst index 5cfa51ae2af..99cd846feef 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_migrating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_migrating.rst @@ -4,7 +4,8 @@ Migrating Ansible content to a different collection *************************************************** -When you move content from one collection to another, for example to extract a set of related modules out of ``community.general`` to create a more focused collection, you must make sure the transition is easy for users to follow. +You might decide to move content from one collection to another; for example, to extract a set of related modules out of ``community.general`` or ``community.network`` to create a more focused collection. +When you migrate content between collections, you must take certain steps to ensure users can follow the transition. .. contents:: :local: @@ -13,18 +14,19 @@ When you move content from one collection to another, for example to extract a s Migrating content ================= -Before you start migrating content from one collection to another, look at `Ansible Collection Requirements `_. - -To migrate content from one collection to another, if the collections are parts of `Ansible distribution `_: +If the collection from which you are going to migrate content is included in the `Ansible community package `_, ensure the target collection satisfies the :ref:`collections_requirements`. After you satisfy the requirements, you can migrate the content as follows: #. Copy content from the source (old) collection to the target (new) collection. +#. Change ``M()``, examples, ``seealso``, ``extended_documentation_fragments`` to use actual FQCNs in moved content, old collection, and in other collections that have references to the content. +#. Move all related issues, pull requests, and wiki pages. +#. Look through the ``docs/docsite`` directory of the `ansible-documentation GitHub repository `_ (for example, using the ``grep`` command-line utility) to check if there are examples using the moved modules and plugins so that you can update those FQCNs. #. Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the old collection. The deprecation must be released after the copied content has been included in a release of the new collection. #. When the next major release of the old collection is prepared: * remove the module/plugin from the old collection * remove the symlink stored in ``plugin/modules`` directory if appropriate (mainly when removing from ``community.general`` and ``community.network``) * remove related unit and integration tests - * remove specific module utils + * remove specific module utils (if they are NOT used by other modules/plugins or ``module_utils``) * remove specific documentation fragments if there are any in the old collection * add a changelog fragment containing entries for ``removed_features`` and ``breaking_changes``; you can see an example of a changelog fragment in this `pull request `_ * change ``meta/runtime.yml`` in the old collection: From c8403c74c48ba8119ec62090a6b5a2281d9fd0dd Mon Sep 17 00:00:00 2001 From: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> Date: Fri, 21 Jun 2024 14:16:23 -0400 Subject: [PATCH 422/536] Revert "Add example /usr/bin/env python as Python interpreter (#280)" (#1629) This reverts commit 07c50093a2a599d2a413b8c28872887e5f07995f. --- .../rst/reference_appendices/interpreter_discovery.rst | 2 -- .../docsite/rst/reference_appendices/python_3_support.rst | 8 -------- 2 files changed, 10 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/interpreter_discovery.rst b/docs/docsite/rst/reference_appendices/interpreter_discovery.rst index 740891ea783..23d1d970929 100644 --- a/docs/docsite/rst/reference_appendices/interpreter_discovery.rst +++ b/docs/docsite/rst/reference_appendices/interpreter_discovery.rst @@ -49,5 +49,3 @@ auto_silent You can still set ``ansible_python_interpreter`` to a specific path at any variable level (for example, in host_vars, in vars files, in playbooks, and so on). Setting a specific path completely disables automatic interpreter discovery; Ansible always uses the path specified. - -.. seealso:: :ref:`python_3_support` for ``ansible_python_interpreter`` usage examples. diff --git a/docs/docsite/rst/reference_appendices/python_3_support.rst b/docs/docsite/rst/reference_appendices/python_3_support.rst index 61239b748c4..5c60a4ea85e 100644 --- a/docs/docsite/rst/reference_appendices/python_3_support.rst +++ b/docs/docsite/rst/reference_appendices/python_3_support.rst @@ -1,5 +1,3 @@ -.. _python_3_support: - ================ Python 3 Support ================ @@ -70,12 +68,6 @@ Using Python 3 on the managed machines with commands and playbooks $ ansible localhost-py3 -m ping $ ansible-playbook sample-playbook.yml -* To use the first Python found on ``PATH`` or if the Python interpreter path is not known in advance, you can use ``/usr/bin/env python`` such as: - -.. code-block:: shell - - ansible_python_interpreter="/usr/bin/env python" - Note that you can also use the `-e` command line option to manually set the python interpreter when you run a command. This can be useful if you want to test whether From d11dc991ed559b6ef52da658ba2eccf0506777d0 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 24 Jun 2024 15:32:52 -0500 Subject: [PATCH 423/536] ci: refresh dev dependencies (#1634) --- tests/static.txt | 2 +- tests/typing.txt | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index e206a188061..ef29ac150ad 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.4.9 +ruff==0.4.10 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 2a77c16edf9..e4c859c017c 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/typing.txt --strip-extras tests/typing.in # -argcomplete==3.3.0 +argcomplete==3.4.0 # via nox certifi==2024.6.2 # via requests @@ -26,7 +26,7 @@ deprecated==1.2.14 # via pygithub distlib==0.3.8 # via virtualenv -filelock==3.15.1 +filelock==3.15.4 # via virtualenv gitdb==4.0.11 # via gitpython @@ -86,11 +86,11 @@ typing-extensions==4.12.2 # mypy # pygithub # typer -urllib3==2.2.1 +urllib3==2.2.2 # via # pygithub # requests -virtualenv==20.26.2 +virtualenv==20.26.3 # via nox wrapt==1.16.0 # via deprecated From fa772df74f3deafbeb4a23649db87b94191de55b Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 25 Jun 2024 09:43:10 +0100 Subject: [PATCH 424/536] Remove latest symlink from publishing workflow (#1615) * remove latest symlink Read The Docs allows you to configure which version corresponds to "latest" which means the symlink is no longer necessary. * add 11 to version list Co-authored-by: Sandra McCann <30267855+samccann@users.noreply.github.com> --- .github/workflows/build-package-docs.yaml | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 94e78beede6..f0f84937025 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -26,19 +26,14 @@ on: - japanese ansible-package-version: type: choice - description: Version of the Ansible community package to build + description: Ansible community package version required: true default: devel options: - devel + - '11' - '10' - '9' - - '8' - - '7' - latest-symlink: - type: boolean - description: Add latest symlink - required: true deploy: type: boolean description: Deploy the build @@ -107,11 +102,6 @@ jobs: run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}" working-directory: build-directory/docs/docsite - - name: Create latest symlink - if: fromJSON(github.event.inputs.latest-symlink) - run: ln -s "${VERSION}" _build/html/latest - working-directory: build-directory/docs/docsite - - name: Create a tarball with the build contents run: >- tar -czvf @@ -160,7 +150,7 @@ jobs: if: env.TARGET == 'production' env: BRANCH_NAME: ${{ github.event.inputs.ansible-package-version }} - PROD_URL: https://ansible.readthedocs.io/projects/ansible/ + PROD_URL: https://ansible.readthedocs.io/projects/ansible run: | echo "BRANCH=${BRANCH_NAME}" >> "${GITHUB_ENV}" echo "ENV_URL=${PROD_URL}/${BRANCH_NAME}" >> "${GITHUB_ENV}" From f1d07132f61cd50e1facfbb684595476411bd1c2 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Tue, 25 Jun 2024 09:44:53 +0100 Subject: [PATCH 425/536] ci: refresh docs build dependencies (#1635) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 6 +++--- tests/requirements.txt | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index b85be64334f..cee52724a15 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -20,7 +20,7 @@ ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-changelog==0.28.0 +antsibull-changelog==0.29.0 # via antsibull-docs antsibull-core==3.0.1 # via antsibull-docs @@ -171,11 +171,11 @@ typing-extensions==4.12.2 # pydantic # pydantic-core # rstcheck -urllib3==2.2.1 +urllib3==2.2.2 # via requests yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==70.0.0 +setuptools==70.1.0 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index cdf4f635e44..743b84b3bb0 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -20,7 +20,7 @@ ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-changelog==0.28.0 +antsibull-changelog==0.29.0 # via antsibull-docs antsibull-core==3.0.1 # via antsibull-docs @@ -172,11 +172,11 @@ typing-extensions==4.12.2 # pydantic # pydantic-core # rstcheck -urllib3==2.2.1 +urllib3==2.2.2 # via requests yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==70.0.0 +setuptools==70.1.0 # via sphinx-intl From c55e71d53aa2d5c5a62b7bfb88147a0534710a5a Mon Sep 17 00:00:00 2001 From: taso <74918216+tasoint@users.noreply.github.com> Date: Tue, 25 Jun 2024 17:45:42 +0900 Subject: [PATCH 426/536] fix Validate data against set criteria with Ansible doc (#1636) fixed following example playbook --- docs/docsite/rst/network/user_guide/validate.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docsite/rst/network/user_guide/validate.rst b/docs/docsite/rst/network/user_guide/validate.rst index 5837a2b85f6..3d91bf3a695 100644 --- a/docs/docsite/rst/network/user_guide/validate.rst +++ b/docs/docsite/rst/network/user_guide/validate.rst @@ -52,7 +52,6 @@ The following example fetches the operational state of some network (Cisco NXOS) - name: print structured interface state data ansible.builtin.debug: msg: "{{ nxos_pyats_show_interface['parsed'] }}" - ---- This results in the following structured data. From 5f172fdbd9a518486cc5135775a2c5fb9e5bf79b Mon Sep 17 00:00:00 2001 From: taso <74918216+tasoint@users.noreply.github.com> Date: Tue, 25 Jun 2024 18:02:05 +0900 Subject: [PATCH 427/536] fix Ansible architecture docs (#1637) I fixed example Inventory ini format file contains '---' used in Yaml --- docs/docsite/rst/dev_guide/overview_architecture.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/overview_architecture.rst b/docs/docsite/rst/dev_guide/overview_architecture.rst index fb78da60512..66568364929 100644 --- a/docs/docsite/rst/dev_guide/overview_architecture.rst +++ b/docs/docsite/rst/dev_guide/overview_architecture.rst @@ -44,7 +44,6 @@ Here's what a plain text inventory file looks like: .. code-block:: text - --- [webservers] www1.example.com www2.example.com From a732a1ee7cabf5971c1933d9ad6e2e691aa2455f Mon Sep 17 00:00:00 2001 From: Lyle McKarns Date: Tue, 25 Jun 2024 06:45:14 -0400 Subject: [PATCH 428/536] Integrate the `alls-green` action into the main GHA CI workflow (#1639) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Integrating all-greens into ci.yml * removing non-existing references When rebuilding this work after repo cleanup, I missed removing these. Thanks for catching that. Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) * Update .github/workflows/ci.yaml --------- Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) Co-authored-by: Don Naro --- .github/workflows/ci.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 3d92f5c4ede..cc46b3f4d81 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -11,3 +11,17 @@ on: jobs: nox: uses: ./.github/workflows/reusable-nox.yml + + check: + if: always() + + needs: + - nox + + runs-on: ubuntu-latest + + steps: + - name: Decide whether the needed jobs succeeded or failed + uses: re-actors/alls-green@release/v1 + with: + jobs: ${{ toJSON(needs) }} From aab570123955229d8bc2fd66e7a73c5812f02044 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Tue, 25 Jun 2024 13:40:43 -0700 Subject: [PATCH 429/536] Remove reference of scp_if_ssh option (#1346) * Remove reference of scp_if_ssh option * scp_if_ssh is removed in Ansible 2.17, remove the references Fixes: #1341 Signed-off-by: Abhijeet Kasurde * review changes Co-authored-by: Maxwell G * details about the smart setting --------- Signed-off-by: Abhijeet Kasurde Co-authored-by: Maxwell G Co-authored-by: Don Naro --- docs/docsite/rst/reference_appendices/faq.rst | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index b34b177a1b2..e0531da6c14 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -26,7 +26,7 @@ IF you are searching for a specific module, you can check the `runtime.yml `_ for hints on how to improve this. @@ -35,7 +35,7 @@ Ansible may feel sluggish on systems with slow disks, such as Raspberry PI. See .. _set_environment: How can I set the PATH or any other environment variable for a task or entire play? -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Setting environment variables can be done with the `environment` keyword. It can be used at the task or other levels in the play. @@ -154,7 +154,7 @@ Rather connect to a management node inside this cloud provider first and run Ans .. _python_interpreters: How do I handle not having a Python interpreter at /usr/bin/python on a remote machine? -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ While you can write Ansible modules in any language, most Ansible modules are written in Python, including the ones central to letting Ansible work. @@ -803,12 +803,14 @@ In these releases, SCP tries to validate that the path of the file to fetch matc The validation fails if the remote file name requires quotes to escape spaces or non-ascii characters in its path. To avoid this error: -* Use SFTP instead of SCP by setting ``scp_if_ssh`` to ``smart`` (which tries SFTP first) or to ``False``. You can do this in one of four ways: - * Rely on the default setting, which is ``smart`` - this works if ``scp_if_ssh`` is not explicitly set anywhere - * Set a :ref:`host variable ` or :ref:`group variable ` in inventory: ``ansible_scp_if_ssh: False`` - * Set an environment variable on your control node: ``export ANSIBLE_SCP_IF_SSH=False`` - * Pass an environment variable when you run Ansible: ``ANSIBLE_SCP_IF_SSH=smart ansible-playbook`` - * Modify your ``ansible.cfg`` file: add ``scp_if_ssh=False`` to the ``[ssh_connection]`` section +* Ensure you are using SFTP, which is the optimal transfer method for security, speed and reliability. Check that you are doing one of the following: + * Rely on the default setting, which is ``smart`` — this works if ``ssh_transfer_method`` is not explicitly set anywhere + * Set a :ref:`host variable ` or :ref:`group variable ` in inventory: ``ansible_ssh_transfer_method: smart`` + * Set an environment variable on your control node: ``export ANSIBLE_SSH_TRANSFER_METHOD=smart`` + * Pass an environment variable when you run Ansible: ``ANSIBLE_SSH_TRANSFER_METHOD=smart ansible-playbook`` + * Modify your ``ansible.cfg`` file: add ``ssh_transfer_method=smart`` to the ``[ssh_connection]`` section. + The ``smart`` setting attempts to use ``sftp`` for the transfer, then falls back to ``scp`` and then ``dd``. + If you want the transfer to fail if SFTP is not available, add ``ssh_transfer_method=sftp`` to the ``[ssh_connection]`` section. * If you must use SCP, set the ``-T`` arg to tell the SCP client to ignore path validation. You can do this in one of three ways: * Set a :ref:`host variable ` or :ref:`group variable `: ``ansible_scp_extra_args=-T``, * Export or pass an environment variable: ``ANSIBLE_SCP_EXTRA_ARGS=-T`` @@ -819,7 +821,7 @@ fails if the remote file name requires quotes to escape spaces or non-ascii char .. _mfa_support: Does Ansible support multiple factor authentication 2FA/MFA/biometrics/finterprint/usbkey/OTP/... -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ No, Ansible is designed to execute multiple tasks against multiple targets, minimizing user interaction. As with most automation tools, it is not compatible with interactive security systems designed to handle human interaction. @@ -910,7 +912,7 @@ for contributing can be found in the docs README `viewable on GitHub Date: Wed, 26 Jun 2024 17:13:54 -0300 Subject: [PATCH 430/536] Remove references to archived ansible/ansible-examples repository (#1653) --- docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst | 7 ------- docs/docsite/rst/playbook_guide/playbooks.rst | 3 --- docs/docsite/rst/playbook_guide/playbooks_delegation.rst | 2 -- docs/docsite/rst/playbook_guide/playbooks_intro.rst | 6 +----- docs/docsite/rst/playbook_guide/playbooks_reuse.rst | 2 -- docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst | 2 -- docs/docsite/rst/playbook_guide/playbooks_variables.rst | 2 +- docs/docsite/rst/reference_appendices/YAMLSyntax.rst | 2 -- docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst | 2 -- docs/docsite/rst/tips_tricks/sample_setup.rst | 4 +--- 10 files changed, 3 insertions(+), 29 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst b/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst index 9ab80ec679d..805ad81bbf5 100644 --- a/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst +++ b/docs/docsite/rst/playbook_guide/guide_rolling_upgrade.rst @@ -23,11 +23,6 @@ playbooks as a template: lamp_haproxy. This example uses a lot of Ansible featur and group variables, and it also comes with an orchestration playbook that can do zero-downtime rolling upgrades of the web application stack. -.. note:: - - `Click here for the latest playbooks for this example - `_. - The playbooks deploy Apache, PHP, MySQL, Nagios, and HAProxy to a CentOS-based set of servers. We're not going to cover how to run these playbooks here. Read the included README in the GitHub project along with the @@ -312,8 +307,6 @@ This should give you a good idea of how to structure a multi-tier application wi .. seealso:: - `lamp_haproxy example `_ - The lamp_haproxy example discussed here. :ref:`working_with_playbooks` An introduction to playbooks :ref:`playbooks_reuse_roles` diff --git a/docs/docsite/rst/playbook_guide/playbooks.rst b/docs/docsite/rst/playbook_guide/playbooks.rst index 7f6659238dd..6d22d79a464 100644 --- a/docs/docsite/rst/playbook_guide/playbooks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks.rst @@ -14,9 +14,6 @@ At a more advanced level, they can sequence multi-tier rollouts involving rollin Playbooks are designed to be human-readable and are developed in a basic text language. There are multiple ways to organize playbooks and the files they include, and we'll offer up some suggestions on that and making the most out of Ansible. -You should look at `Example Playbooks `_ while reading along with the playbook documentation. -These illustrate best practices as well as how to put many of the various concepts together. - .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/playbook_guide/playbooks_delegation.rst b/docs/docsite/rst/playbook_guide/playbooks_delegation.rst index f4bae2d2e24..bdf3649911d 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_delegation.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_delegation.rst @@ -177,8 +177,6 @@ use the default remote connection type: An introduction to playbooks :ref:`playbooks_strategies` More ways to control how and where Ansible executes - `Ansible Examples on GitHub `_ - Many examples of full-stack deployments `User Mailing List `_ Have a question? Stop by the Google group! :ref:`communication_irc` diff --git a/docs/docsite/rst/playbook_guide/playbooks_intro.rst b/docs/docsite/rst/playbook_guide/playbooks_intro.rst index 280097a359e..469a8006f8d 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_intro.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_intro.rst @@ -5,7 +5,7 @@ Ansible playbooks ***************** -Ansible Playbooks offer a repeatable, reusable, simple configuration management and multi-machine deployment system, one that is well suited to deploying complex applications. If you need to execute a task with Ansible more than once, write a playbook and put it under source control. Then you can use the playbook to push out new configuration or confirm the configuration of remote systems. The playbooks in the `ansible-examples repository `_ illustrate many useful techniques. You may want to look at these in another tab as you read the documentation. +Ansible Playbooks offer a repeatable, reusable, simple configuration management and multi-machine deployment system, one that is well suited to deploying complex applications. If you need to execute a task with Ansible more than once, write a playbook and put it under source control. Then you can use the playbook to push out new configuration or confirm the configuration of remote systems. Playbooks can: @@ -136,8 +136,6 @@ Assuming you load balance your checkout location, ``ansible-pull`` scales essent Run ``ansible-pull --help`` for details. -There's also a `clever playbook `_ available to configure ``ansible-pull`` through a crontab from push mode. - Verifying playbooks =================== @@ -173,7 +171,5 @@ The `ansible-lint default rules `_ - Complete end-to-end playbook examples `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse.rst index 4e42fc8d28a..e2306110f2a 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse.rst @@ -220,7 +220,5 @@ Imports are processed before the play begins, so the name of the import no longe Tips and tricks for playbooks :ref:`ansible_galaxy` How to share roles on galaxy, role management - `GitHub Ansible examples `_ - Complete playbook files from the GitHub project source `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index 3404263392f..ea9c39f73c0 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -760,7 +760,5 @@ Read the `Ansible Galaxy documentation `_ - Complete playbook files from the GitHub project source `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/playbook_guide/playbooks_variables.rst b/docs/docsite/rst/playbook_guide/playbooks_variables.rst index d4dd5765905..54492a96aef 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_variables.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_variables.rst @@ -6,7 +6,7 @@ Using Variables Ansible uses variables to manage differences between systems. With Ansible, you can execute tasks and playbooks on multiple different systems with a single command. To represent the variations among those different systems, you can create variables with standard YAML syntax, including lists and dictionaries. You can define these variables in your playbooks, in your :ref:`inventory `, in reusable :ref:`files ` or :ref:`roles `, or at the command line. You can also create variables during a playbook run by registering the return value or values of a task as a new variable. -After you create variables, either by defining them in a file, passing them at the command line, or registering the return value or values of a task as a new variable, you can use those variables in module arguments, in :ref:`conditional "when" statements `, in :ref:`templates `, and in :ref:`loops `. The `ansible-examples GitHub repository `_ contains many examples of using variables in Ansible. +After you create variables, either by defining them in a file, passing them at the command line, or registering the return value or values of a task as a new variable, you can use those variables in module arguments, in :ref:`conditional "when" statements `, in :ref:`templates `, and in :ref:`loops `. Once you understand the concepts and examples on this page, read about :ref:`Ansible facts `, which are variables you retrieve from remote systems. diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index d74f6dc8fdf..b8262c98cd9 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -270,8 +270,6 @@ value: Learn what playbooks can do and how to write/run them. `YAMLLint `_ YAML Lint (online) helps you debug YAML syntax if you are having problems - `GitHub examples directory `_ - Complete playbook files from the GitHub project source `Wikipedia YAML syntax reference `_ A good guide to YAML syntax `Mailing List `_ diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index 54d2ecbd749..32102873c46 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -206,7 +206,5 @@ This pulls in variables from the `group_vars/os_CentOS.yml` file. Learn how to extend Ansible by writing your own modules :ref:`intro_patterns` Learn about how to select hosts - `GitHub examples directory `_ - Complete playbook files from the GitHub project source `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/tips_tricks/sample_setup.rst b/docs/docsite/rst/tips_tricks/sample_setup.rst index 60386cc8807..87215d0a889 100644 --- a/docs/docsite/rst/tips_tricks/sample_setup.rst +++ b/docs/docsite/rst/tips_tricks/sample_setup.rst @@ -4,7 +4,7 @@ Sample Ansible setup ******************** -You have learned about playbooks, inventory, roles, and variables. This section combines all those elements and outlines a sample setup for automating a web service. You can find more example playbooks that illustrate these patterns in our `ansible-examples repository `_. (NOTE: These examples do not use all of the latest features, but are still an excellent reference.). +You have learned about playbooks, inventory, roles, and variables. This section combines all those elements and outlines a sample setup for automating a web service. The sample setup organizes playbooks, roles, inventory, and files with variables by function. Tags at the play and task level provide greater granularity and control. This is a powerful and flexible approach, but there are other ways to organize Ansible content. Your usage of Ansible should fit your needs, so feel free to modify this approach and organize your content accordingly. @@ -289,7 +289,5 @@ If a playbook has a :file:`./library` directory relative to its YAML file, you c Learn how to extend Ansible by writing your own modules :ref:`intro_patterns` Learn about how to select hosts - `GitHub examples directory `_ - Complete playbook files from the GitHub project source `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups From 3551f1999bb18fdfcd5ff2cbf85c33f42000be21 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 2 Jul 2024 12:28:02 +0200 Subject: [PATCH 431/536] docs/docsite/rst/dev_guide/developing_program_flow_modules.rst: avoid using aliases (#1539) * docs/docsite/rst/dev_guide/developing_program_flow_modules.rst: don't use aliases * Update docs/docsite/rst/dev_guide/developing_program_flow_modules.rst Co-authored-by: Sandra McCann * Update docs/docsite/rst/dev_guide/developing_program_flow_modules.rst Co-authored-by: flowerysong --------- Co-authored-by: Sandra McCann Co-authored-by: flowerysong --- docs/docsite/rst/dev_guide/developing_program_flow_modules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst index 9e4cca27124..bb76a79b4d4 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -660,7 +660,7 @@ This section will discuss the behavioral attributes for arguments: :aliases: - ``aliases`` accepts a list of alternative argument names for the argument, such as the case where the argument is ``name`` but the module accepts ``aliases=['pkg']`` to allow ``pkg`` to be interchangeably with ``name`` + ``aliases`` accepts a list of alternative argument names for the argument, such as the case where the argument is ``name`` but the module accepts ``aliases=['pkg']`` to allow ``pkg`` to be interchangeably with ``name``. Use of aliases can make module interfaces confusing, so we recommend adding them only when necessary. If you are updating argument names to fix a typo or improve the interface, consider moving the old names to ``deprecated_aliases`` rather than keeping them around indefinitely. :options: From 7a744a1094c4b1103d457d0f33765a2d2173ca92 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 3 Jul 2024 09:12:32 +0200 Subject: [PATCH 432/536] [WIP, needs vote before merging] collection_requirements.rst: update (#1422) * collection_requirements.rst: update * general updates * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com> * releasing policy MUST -> SHOULD * Remove setting upper bound warning * fix formatting * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Sandra McCann * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Sandra McCann * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Remove the Requirements for collections to be included in the Ansible Package section * Update galaxy section * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Remove extra line * Update Documentation requirements section * CoC feedback incorporate * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein * Fix unnoticed conflict * Reformulate changelog section * Restructure Contributor Workflow section * Fix typo * Add sentence back * Restructure section * Handle Naming section * Handle Licensing section * Restructure Licensing section * Fix typo * Update repo management section * Update branch name and protection section * Undate CI testing section * Update When moving modules between collections section * Update Development conventions section * Update Collection dependencies section * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Restructure backwards compatibility section * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Fix formatting| * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein --------- Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com> Co-authored-by: Sandra McCann Co-authored-by: Don Naro Co-authored-by: Felix Fontein Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> --- .../collection_requirements.rst | 313 ++++++++---------- .../steering/community_steering_committee.rst | 2 + 2 files changed, 139 insertions(+), 176 deletions(-) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 0cd776aee5c..c2ae4bc2b25 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -10,28 +10,22 @@ 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. +This document describes the requirements for maintainers of Ansible community collections included in the Ansible community package. All inclusion candidates and already included collections must meet the criteria marked with ``MUST`` in this document. -.. note:: +You can also find these requirements on the `Collection inclusion criteria checklist `_. - `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 :ref:`community topic` for discussion and a final vote. +Every rejected candidate will get feedback from the :ref:`community_steering_committee` based on a decision made in a dedicated :ref:`community topic`. 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. +Any feedback and help is very welcome. Please create a :ref:`community topic` or bring your questions to the :ref:`community meeting`. Keeping informed ================ @@ -46,21 +40,20 @@ To track changes that affect collections: Collection infrastructure ========================= -The following guidelines describe the required structure for your collection: +The following guidelines describe the required infrastructure 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). +* MUST have a publicly available issue tracker that does not require a paid level of service to create an account and to create and view issues. +* MUST have the issue feature enabled in its repository and accept issue reports from anyone. +* MUST have a Code of Conduct (CoC) compatible with the :ref:`code_of_conduct`. - * 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. + * The recommended approach is have a link to the Ansible :ref:`code_of_conduct`. + * If the collection has its own CoC, it MUST be evaluated by the :ref:`Diversity and Inclusion working group ` and confirmed as compatible with the :ref:`code_of_conduct`. -* MUST be published to `Ansible Galaxy `_. +* MUST be published to `Ansible Galaxy `_ with version 1.0.0 or later. +* MUST contain only objects that follow the :ref:`Licensing rules `. * 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: @@ -120,7 +113,9 @@ 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 file names. -* It is a breaking change when you make an existing ``module_utils`` private and in that case the collection requires a major version bump. + + * If you change a utility in ``module_utils`` from public to private, you are making a breaking change. If you do this, you must release a new major version of your collection. + * Below are some recommendations for ``module_utils`` documentation: * No docstring: everything we recommend for ``other-environment`` is supported. @@ -136,8 +131,7 @@ 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. +* Collection dependencies MUST meet a set of rules. See the section on `Collection Dependencies ` for details. * 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. @@ -153,10 +147,7 @@ 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) +* The ``meta/runtime.yml`` MUST define the minimum version of ansible-core which this collection works with using the ``requires_ansible`` field. For example, if the collection works with ansible-core 2.16 and later, set ``requires_ansible: '>=2.16'`` in the ``meta/runtime.yml`` file. .. _coll_module-reqs: @@ -183,32 +174,33 @@ Modules & Plugins 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. +* 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. -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. + * 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: +Collections: -* 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: +* ``MUST`` use :ref:`links and formatting macros `. +* ``SHOULD`` have contributor guidelines in the ``CONTRIBUTING.md`` or ``README.md`` file. -* 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. +All modules and plugins: -Other items: +* ``MUST`` include a :ref:`DOCUMENTATION ` block. +* ``MUST`` include an :ref:`EXAMPLES ` block (except where not relevant for the plugin type). +* ``MUST`` use FQCNs when referring to modules, plugins and documentation fragments inside and outside the collection including ``ansible.builtin.`` for ansible-core. +* ``MUST`` include a :ref:`RETURN ` block for modules and other plugins that return data. +* ``MUST`` include the ``version_added`` field when adding new content to an existing collection for entities that support it, for example, for modules, plugins, options, return values, and attributes. -* 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 requests) reports must always be accepted. -* Collections are encouraged to use :ref:`links and formatting macros ` -* Including a :ref:`RETURN ` block for modules is strongly encouraged but not required. + * You do not have to add ``version_added`` when creating a new collection before its first release. + * The ``version_added`` field for objects in a collection MUST refer to the version of the collection in which the options were added -- ``NOT`` the version of Ansible or ansible-core. + + * If, for some reason, you need to specify version numbers of Ansible or another collection, you ``MUST`` also provide ``version_added_collection: collection_name``. We strongly recommend to ``NOT`` do this. .. _coll_workflow: @@ -220,30 +212,39 @@ Contributor Workflow 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): +* Collections MUST include a changelog in the `correct format `_. -#. 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. + #. You can generate or check changelogs using `antsibull-changelog `_ (`documentation `_), which provides consistency for changelogs across collections included in the ``ansible`` package. .. _coll_versioning_req: Versioning and deprecation -~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------- + +* Collections MUST adhere to the `Semantic versioning conventions `_: + + * MUST have this information in its ``README.md`` file in the collection root directory. + * SHOULD have this information in its contributor and maintainer documentation. + * MUST have changelog entries under correct categories (``Major changes``, ``Minor changes``, ``Bugfixes``, and so on). -* 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 backward compatibility! (See `semantic versioning `_.) This means in particular: +* Collections MUST preserve backward compatibility: - * 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 the 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. + * To preserve backward compatibility for users, every Ansible minor version series (x.Y.z) will keep the major version of a collection constant. + + * For example, 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 backward compatibility! This means in particular: + + * You can fix bugs in ``patch releases``, but you MUST NOT add new features or deprecate things. + * You can add new features and deprecate things in ``minor releases`` but you MUST NOT remove things or change the behavior of existing features. + * You can only remove things or make breaking changes in ``major releases``. + * See `semantic versioning `_ for more information. + + * We recommend that you ensure 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. + +* The collection SHOULD make its policy of releasing and deprecation available to contributors and users in some way, for example, in its README or pinned issue. See `the announcement in community.general `_ as an example. .. _ coll_naming_req: @@ -253,29 +254,33 @@ 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 `_. +When choosing a name for a brand new namespace: -`Namespace limitations `_ lists requirements for namespaces in Galaxy. +* Take into consideration the `Namespace limitations `_ which list requirements for namespaces in Galaxy. +* If the namespace does not exit yet and is not occupied by anybody else, submit a `namespace request `_ to have it created for you. -For collections created for working with a particular entity, they should contain the entity name, for example ``community.mysql``. +Naming recommendations: -For corporate maintained collections, the repository can be named ``COMPANY_NAME.PRODUCT_NAME``, for example ``ibm.db2``. +* For collections under the ``ansible-collections`` GitHub organization the repository SHOULD be named ``NAMESPACE.COLLECTION``. +* 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``. +* Avoid FQCN/repository names: -We should avoid FQCN / repository names: + * which are unnecessarily long: try to make it compact but clear. + * contain the same words / collocations in ``NAMESPACE`` and ``COLLECTION`` parts, for example ``my_system.my_system``. -* 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``. +.. note:: -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**. + If you plan to get your collection 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** and the certified collection. .. _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. +* Modules that only gather and return information MUST be named ``_info``. +* Modules that gather and return ``ansible_facts`` MUST be named ``_facts`` and MUST NOT return anything but facts. + For more information, refer to the :ref:`Developing modules guidelines `. .. _coll_licensing_req: @@ -283,44 +288,29 @@ For more information, refer to the :ref:`Developing modules guidelines `_ -: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 `the list of licenses from gnu.org -`_ to find which licenses are -compatible with the GPLv3+. The license must be considered open source and compatible with GPLv3+ on both the gnu.org license -list 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. +There are several types of content in collections which licensing has to address in different ways. + +* The content that MUST be licensed with a free software license that is **compatible with** the `GPL-3.0-or-later `_: + + * The ``modules/`` directory content. + * The ``module_utils/`` directory content: ansible-core 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``. + * Code outside ``plugins/``: if it DOES NOT import code licensed under ``GPL-3.0-or-later`` it may be licensed under another license compatible with ``GPL-3.0-or-later``. + * Non-code content. + * To be allowed, the license MUST be considered open source and compatible with ``GPL-3.0-or-later`` on **both**: + + * The `gnu.org license list `_. + * The `Debian Free Software Guidelines `_. + +* The content that MUST be licensed with the `GPL-3.0-or-later `_: + + * All other code in the ``plugins/`` directory except code under the ``modules/`` and ``module_utils/`` directories (see above): 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. + * Code outside ``plugins/``: if it imports any other code that is licensed under ``GPL-3.0-or-later``. Note that this applies in particular to unit tests that often import code from ansible-core, ``plugins/``, ``module_utils/``, or ``modules/``, and such code is often licensed under ``GPL-3.0-or-later``. Contributor License Agreements @@ -340,31 +330,33 @@ and lower barriers to contribution. 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. +* Every collection MUST have a public git repository. +* Releases of the collection MUST be tagged in its repository. + + * The ``git`` utility with the ``tag`` argument MUST be used to tag the releases. + * The tag name MUST exactly match the Galaxy version number. + * Tag names MAY have a ``v`` prefix. + * 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. +* Collection artifacts released to Galaxy MUST be built from the sources that are tagged in the collection's git repository as that release. -We are open to allowing other SCM software once our tooling supports them. + * Any changes made during the build process MUST be clearly documented so the collection artifact can be reproduced. .. _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: +.. note:: -* Allow merge commits: disallowed + This subsection is **only** for repositories under `ansible-collections `_! Other collection repositories can also follow these guidelines, but do not have to. -Branch protections MUST be enforced: +* All new repositories MUST have ``main`` as the default branch. +* Pull Requests settings MUST disallow ``merge commits``. +* The following branch protection rules that MUST be enabled for all release branches: -* Require linear history -* Include administrators + * ``Require linear history`` + * ``Do not allow bypassing the above settings`` .. _coll_ci_tests: @@ -373,31 +365,29 @@ 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 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. -.. note:: - - Subscribe to the `news-for-maintainers repository `_ - and keep your matrix up to date in accordance to related announcements. Add new `ansible-core` versions in a timely manner and consider dropping support and testing against its EOL versions and versions your collection does not support. - If your collection repository is under the ``ansible-collections`` GitHub organization, please keep in mind that the number of testing jobs is limited - and shared across all the collections in the organization. So, focusing on good test coverage of your collection, - please avoid testing against unnecessary entities such as ``ansible-core`` EOL versions your collection does not support. + If your collection repository is under the ``ansible-collections`` GitHub organization, please keep in mind that the number of testing jobs is limited and shared across all the collections in the organization. Therefore, focusing on good test coverage of your collection, please avoid testing against unnecessary entities such as ``ansible-core`` EOL versions that your collection does not support. + +To receive important announcements that can affect the collections (for example, testing), collection maintainers SHOULD: + +* Subscribe to the `news-for-maintainers `_ repository. +* Join the `Collection Maintainers & Contributors `_ forum group. * 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. + * 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. - * 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 SHOULD *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. - * You MUST not ignore the following validations. They must be fixed before approval: + * You SHOULD avoid adding entries to the ``test/sanity/ignore*.txt`` files to get your tests to pass but it is allowed except in cases listed below. + * You MUST NOT ignore the following validations. They MUST be fixed and removed from the files before approval: * ``validate-modules:doc-choices-do-not-match-spec`` * ``validate-modules:doc-default-does-not-match-spec`` * ``validate-modules:doc-missing-type`` @@ -414,15 +404,14 @@ CI Testing 1. A dangerous module parameter has been deprecated or removed, and code is present to inform the user that they should not use this specific parameter anymore or that it stopped working intentionally. 2. Module parameters are only used to pass in data from an accompanying action plugin. - * 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. + * All entries in ``ignore-*.txt`` files MUST have a justification in a comment in the files for each entry. For example ``plugins/modules/docker_container.py use-argspec-type-path # uses colon-separated paths, can't use type=path``. -* 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.) +* You MUST run CI against each of the "major versions" (2.14, 2.16, 2.17, etc) of ``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 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-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 `_. @@ -437,41 +426,27 @@ To learn how to add tests to your collection, see: 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 no regular meetings) as a pinned issue in the repository. +The collections are encouraged to request a working group on the :ref:`ansible_forum`. .. _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. +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: +All modules in your collection: -* 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`` - +* MUST satisfy all the requirements listed in the :ref:`module_dev_conventions`. +* MUST 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. +* MUST 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>`). +* ``check_mode`` MUST be supported by all ``*_info`` and ``*_facts`` modules (for more information, refer to the :ref:`Development conventions <#following-ansible-conventions>`). .. _coll_dependencies: @@ -480,7 +455,9 @@ 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. +* The collection MUST NOT depend on collections not included in the ``ansible`` package. +* Collection dependencies MUST be published on Galaxy. +* 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: @@ -490,13 +467,13 @@ Collection Dependencies #. 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. +* 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: +* 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 a collection depends on releases of 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. @@ -515,22 +492,6 @@ Examples * ``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 =================== diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index be470618878..b84572386f6 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -178,6 +178,8 @@ Collection exclusion workflow The Committee uses the :ref:`removal_from_ansible` to remove collections not satisfying the :ref:`collection_requirements` from the Ansible package. +.. _community_wg_meetings: + Community Working Group meetings --------------------------------- From b519a730cecdb7f24c9edc34736e584add4d7e31 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 4 Jul 2024 11:04:57 +0200 Subject: [PATCH 433/536] communication guide: overhaul (#1667) communication guide: overhaul * Forum as default * Reorder so important information is at the top * remove old information --------- Co-authored-by: Don Naro Co-authored-by: John Barker Co-authored-by: Sandra McCann --- docs/docsite/rst/community/communication.rst | 179 +++++-------------- 1 file changed, 42 insertions(+), 137 deletions(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 5d8dfbc42f5..a8d4e4ba5be 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -17,111 +17,73 @@ All communication and interactions in the Ansible Community are governed by our Forum ===== -The `Ansible Community Forum `_ is a single starting point for questions and help, development discussions, events, and much more. `Register `_ to join the community. Search by categories and tags to find interesting topics or start a new one; subscribe only to topics you need! +The `Ansible Forum `_ is a single starting point and our default communication platform for questions and help, development discussions, events, and much more. `Register `_ to join the community. Search by categories and tags to find interesting topics or start a new one; subscribe only to topics you need! Take a look at the `forum groups `_ and join ones that match your interests. In most cases, joining a forum group automatically subscribes you to related posts. -Want to create a group? -Request it in the `forum topic `_. +The Bullhorn +------------ + +**The Bullhorn** is our newsletter for the Ansible contributor community published in the Forum: + +* To subscribe, click the ``bell`` button under the `Bullhorn category `_ description and then ``Watching``. +* To publish your news item, see the `About the Newsletter category post `_. +* Questions about the newsletter? Ask us in the `Ansible Social room on Matrix `_. + +Regional and Language-specific channels +--------------------------------------- + +If you feel more comfortable communicating in another language other than English, see the `International Communities forum category `_. Currently there are subcategories for Español (Spanish), Português (Portuguese), and Norsk (Norwegian). + +For more information including how to request a subcategory for a language, see the `About the International Communities category post `_. .. _communication_irc: Real-time chat ============== -For real-time interactions, conversations in the Ansible community happen over two chat protocols: Matrix (recommended) and IRC. -The main Matrix and IRC channels exchange messages. -This means you can choose whichever protocol you prefer for the main channels. +For real-time interactions, conversations in the Ansible community happen over the Matrix protocol. .. note:: - Although you can choose either Matrix or IRC, please take into account that many Ansible communities use only Matrix. - -Join a channel any time to ask questions, participate in a Working Group meeting, or just say hello. - -Ansible community on Matrix ---------------------------- + The :ref:`ansible_forum` is our default communication platform. Join the forum and get in touch with the community there before considering other options like Matrix. -To join the community using Matrix, you need two things: +Join a channel any time to chat with fellow enthusiasts, participate in a Working Group meeting, or just say hello. To chat on Matrix, you need: * a Matrix account (from `Matrix.org `_ or any other Matrix homeserver) * a `Matrix client `_ (we recommend `Element Webchat `_) -The Ansible community maintains its own Matrix homeserver at ``ansible.im``, however, public registration is currently unavailable. - -Matrix chat supports: - -* persistence (when you log on, you see all messages since you last logged off) -* edits (Let you fix typos and so on. **NOTE** Each edit you make on Matrix re-sends the message to IRC. Please try to avoid multiple edits!) -* replies to individual users -* reactions/emojis -* bridging to IRC -* no line limits -* images - The room links in the :ref:`general_channels` or the :ref:`working_group_list` list will take you directly to the relevant rooms. -If there is no appropriate room for your community, please create it. - For more information, see the community-hosted `Matrix FAQ `_. You can add Matrix shields to your repository's ``README.md`` using the shield in the `community-topics `_ repository as a template. -Ansible community on IRC ------------------------- - -The Ansible community maintains several IRC channels on `irc.libera.chat `_. To join the community using IRC, you need one thing: - -* an IRC client - -IRC chat supports: - -* no persistence (you only see messages when you are logged on unless you add a bouncer) -* simple text interface -* bridging from Matrix - -Our IRC channels may require you to register your IRC nickname. If you receive an error when you connect or when posting a message, see `libera.chat's Nickname Registration guide `_ for instructions. To find all ``ansible`` specific channels on the libera.chat network, use the following command in your IRC client: - -.. code-block:: text - - /msg alis LIST #ansible* -min 5 - -as described in the `libera.chat docs `_. - -Our channels record history on the Matrix side. The channel history can be viewed in a browser - all channels will report an appropriate link to ``chat.ansible.im`` in their Chanserv entrymsg upon joining the room. Alternatively, a URL of the form ``https://chat.ansible.im/#/room/# {IRC channel name}:libera.chat`` will also work, for example - for the #ansible-docs channel it would be `https://app.element.io/#/room/#ansible-docs:libera.chat`. +.. note:: -.. _general_channels: + IRC channels are no longer considered official communication channels. Please use the Forum and Matrix instead. General channels ---------------- The clickable links will take you directly to the relevant Matrix room in your browser; room/channel information is also given for use in other clients: -- `Community social room and posting news for the Bullhorn newsletter `_ - ``Matrix: #social:ansible.com | IRC: #ansible-social`` -- `General usage and support questions `_ - ``Matrix: #users:ansible.com | IRC: #ansible`` -- `Discussions on developer topics and code related to features or bugs `_ - ``Matrix: #devel:ansible.com | IRC: #ansible-devel`` -- `Discussions on community and collections related topics `_ - ``Matrix: #community:ansible.com | IRC: #ansible-community`` -- `For public community meetings `_ - ``Matrix: #meeting:ansible.im | IRC: #ansible-meeting`` - - We will generally announce these on one or more of the above mailing lists. See the `meeting schedule `_ +- `Community social room and posting news for the Bullhorn newsletter `_ +- `General usage and support questions `_ +- `Discussions on developer topics and code related to features or bugs `_ +- `Discussions on community and collections related topics `_ Working group-specific channels ------------------------------- Many of the working groups have dedicated chat channels. See the :ref:`working_group_list` for more information. -Regional and Language-specific channels ---------------------------------------- +Meetings on Matrix +------------------ -- Comunidad Ansible en español - Matrix: `#espanol:ansible.im `_ | IRC: ``#ansible-es`` -- Communauté française d'Ansible - Matrix: `#francais:ansible.im `_ | IRC: ``#ansible-fr`` -- Communauté suisse d'Ansible - Matrix: `#suisse:ansible.im `_ | IRC: ``#ansible-zh`` -- European Ansible Community - Matrix: `#europe:ansible.im `_ | IRC: ``#ansible-eu`` - -Meetings on chat ----------------- - -The Ansible community holds regular meetings on various topics on Matrix/IRC, and anyone who is interested is invited to participate. For more information about Ansible meetings, consult the `meeting schedule and agenda page `_. +The Ansible community holds regular meetings on various topics on Matrix, and anyone who is interested is invited to participate. +For more information about Ansible meetings, consult the `meeting schedule and agenda page `_. .. _working_group_list: @@ -130,45 +92,23 @@ Working groups Working Groups are a way for Ansible community members to self-organize around particular topics of interest. -Our community working groups are represented in `Matrix rooms `_ and `Forum groups `_. +Our community working groups are represented in `Forum groups `_. See those links for a complete list of communications channels. -Many of them meet in chat. If you want to get involved in a working group, join the Matrix room or IRC channel where it meets or comment on the agenda. - - -Forming a new working group ----------------------------- - -The basic components of a working group are: - -* Group name and charter (why the group exists). -* Registered :ref:`real-time chat channel`. -* Group of users (at least two!) who will be driving the agenda of the working group. -* Dedicated `forum group `_. +Requesting a forum group +-------------------------- -The basic responsibilities of a working group are: +To request a new working group: -* Follow the :ref:`code_of_conduct`. -* Be responsive on your real-time chat channel. -* Be responsive on the `forum `_ in related topics. -* Report semi-regularly on the cool stuff that your working group is working on. -* Keep your forum group information updated. - - -Requesting a working group -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Anyone can request to start a Working Group, for any reason. - -If you need only a `Forum group `_, -request it in the `forum topic `_. - -If you also need a real-time chat channel, you can `request one `_. +* Check if there is no appropriate `Forum group `_ you can join instead of starting a new one. +* See the `things you can ask for `_ with respect to working groups. +* Request a group in the `forum topic `_. +* If you also need a Matrix chat channel, see the `Ansible Community Matrix FAQ `_. .. _request_coll_repo: Requesting a community collection repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------------------- Working groups are often built around Ansible community collections. You can use a repository under your organization or request one under `ansible-collections `_ on the forum by creating a topic in the `Project Discussions category and the coll-repo-request tag `_. @@ -179,15 +119,11 @@ Ansible Community Topics The :ref:`Ansible Community Steering Committee` uses the :ref:`ansible_forum` to asynchronously discuss with the Community and vote on Community topics. -Create a `new topic `_ if you want to discuss an idea that impacts any of the following: - -* Ansible Community -* Community collection best practices and :ref:`requirements` -* :ref:`Community collection inclusion policy` -* :ref:`The Community governance` -* Other proposals of importance that need the Committee or overall Ansible community attention +For more information, see: -See the `Community topics workflow `_ to learn more. +* :ref:`creating_community_topic` +* :ref:`community_topics_workflow` +* `Community topics on the Forum `_ Ansible Automation Platform support questions ============================================= @@ -195,34 +131,3 @@ Ansible Automation Platform support questions Red Hat Ansible `Automation Platform `_ is a subscription that contains support, certified content, and tooling for Ansible including content management, a controller, UI and REST API. If you have a question about Ansible Automation Platform, visit `Red Hat support `_ rather than using a chat channel or the general project mailing list. - -The Bullhorn -============ - -**The Bullhorn** is our newsletter for the Ansible contributor community. You can get Bullhorn updates -from the :ref:`ansible_forum`. - -If you have any questions or content you would like to share, you are welcome to chat with us -in the `Ansible Social room on Matrix, and mention -`newsbot `_ to have your news item tagged for review for -the next weekly issue. - -Read past issues of `the Bullhorn `_. - -Asking questions over email -=========================== - -.. note:: - - This form of communication is deprecated. Consider using the :ref:`ansible_forum` instead. - -Your first post to the mailing list will be moderated (to reduce spam), so please allow up to a day or so for your first post to appear. - -* `Ansible Announce list `_ is a read-only list that shares information about new releases of Ansible, and also rare infrequent event information, such as announcements about an upcoming AnsibleFest, which is our official conference series. Worth subscribing to! -* `Ansible AWX List `_ is for `Ansible AWX `_ -* `Ansible Development List `_ is for questions about developing Ansible modules (mostly in Python), fixing bugs in the Ansible Core code, asking about prospective feature design, or discussions about extending Ansible or features in progress. -* `Ansible Outreach List `_ help with promoting Ansible and `Ansible Meetups `_ -* `Ansible Project List `_ is for sharing Ansible tips, answering questions about playbooks and roles, and general user discussion. -* `Molecule Discussions `_ is designed to aid with the development and testing of Ansible roles with Molecule. - -The Ansible mailing lists are hosted on Google, but you do not need a Google account to subscribe. To subscribe to a group from a non-Google account, send an email to the subscription address requesting the subscription. For example: ``ansible-devel+subscribe@googlegroups.com``. From 6844870ed800f5696c776180b7470eaa0ae2dd42 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Thu, 4 Jul 2024 10:11:27 +0100 Subject: [PATCH 434/536] ci: refresh dev dependencies (#1657) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/static.txt | 2 +- tests/typing.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index ef29ac150ad..55587f89d20 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.4.10 +ruff==0.5.0 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index e4c859c017c..866a4f736cd 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -42,7 +42,7 @@ markupsafe==2.1.5 # via jinja2 mdurl==0.1.2 # via markdown-it-py -mypy==1.10.0 +mypy==1.10.1 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy From f7f76ae6d639546d3697f544cc034c8dd7b75308 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Thu, 4 Jul 2024 10:12:03 +0100 Subject: [PATCH 435/536] ci: refresh docs build dependencies (#1658) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index cee52724a15..dc88ab9ebdf 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/requirements-relaxed.txt --strip-extras tests/requirements-relaxed.in # -aiofiles==23.2.1 +aiofiles==24.1.0 # via antsibull-core aiohttp==3.9.5 # via @@ -177,5 +177,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==70.1.0 +setuptools==70.1.1 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index 743b84b3bb0..7450e89f481 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/requirements.txt --strip-extras tests/requirements.in # -aiofiles==23.2.1 +aiofiles==24.1.0 # via antsibull-core aiohttp==3.9.5 # via @@ -178,5 +178,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==70.1.0 +setuptools==70.1.1 # via sphinx-intl From 09b49cadf85ff0591b573ba5febb15658dd51f87 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 4 Jul 2024 05:13:09 -0400 Subject: [PATCH 436/536] Output workflow parameters for approval details (#1650) * Output workflow parameters for approval details --------- Co-authored-by: Don Naro --- .github/workflows/build-package-docs.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index f0f84937025..88050aeab27 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -122,6 +122,15 @@ jobs: path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz retention-days: 7 + - name: Log the workflow inputs if deploy checked + if: fromJSON(github.event.inputs.deploy) + run: | + echo "## Deployment details :rocket:" >> "${GITHUB_STEP_SUMMARY}" + echo "Publish to: ${{ github.event.inputs.deployment-environment }}" >> "${GITHUB_STEP_SUMMARY}" + echo "Package version: ${{ github.event.inputs.ansible-package-version }}" >> "${GITHUB_STEP_SUMMARY}" + echo "Owner: ${{ github.event.inputs.repository-owner }}" >> "${GITHUB_STEP_SUMMARY}" + echo "Branch: ${{ github.event.inputs.repository-branch }}" >> "${GITHUB_STEP_SUMMARY}" + deploy-package-docs: if: fromJSON(github.event.inputs.deploy) needs: build-package-docs From 47e25cdb73a420d7abbc2fb6a6d364d345ec6af3 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:47:13 +0100 Subject: [PATCH 437/536] ci: refresh dev dependencies (#1675) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/static.txt | 2 +- tests/typing.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index 55587f89d20..aca335586ef 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.5.0 +ruff==0.5.1 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index 866a4f736cd..c2f8cfe95fb 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -6,7 +6,7 @@ # argcomplete==3.4.0 # via nox -certifi==2024.6.2 +certifi==2024.7.4 # via requests cffi==1.16.0 # via From 65bd12bdb94f5445c05b200bbdb4f122b425dd9a Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:48:13 +0100 Subject: [PATCH 438/536] ci: refresh docs build dependencies (#1676) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 12 ++++++------ tests/requirements.txt | 10 +++++----- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index dc88ab9ebdf..b4bbb7a37a5 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -24,9 +24,9 @@ antsibull-changelog==0.29.0 # via antsibull-docs antsibull-core==3.0.1 # via antsibull-docs -antsibull-docs==2.11.0 +antsibull-docs==2.12.0 # via -r tests/requirements-relaxed.in -antsibull-docs-parser==1.0.1 +antsibull-docs-parser==1.0.2 # via antsibull-docs async-timeout==4.0.3 # via aiohttp @@ -40,7 +40,7 @@ babel==2.15.0 # sphinx-intl build==1.2.1 # via antsibull-core -certifi==2024.6.2 +certifi==2024.7.4 # via requests charset-normalizer==3.3.2 # via requests @@ -83,11 +83,11 @@ packaging==24.1 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.7.4 +pydantic==2.8.2 # via # antsibull-core # antsibull-docs -pydantic-core==2.18.4 +pydantic-core==2.20.1 # via pydantic pygments==2.18.0 # via @@ -177,5 +177,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==70.1.1 +setuptools==70.2.0 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index 7450e89f481..b1d306c03a8 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -28,7 +28,7 @@ antsibull-docs==2.11.0 # via # -c tests/constraints.in # -r tests/requirements-relaxed.in -antsibull-docs-parser==1.0.1 +antsibull-docs-parser==1.0.2 # via antsibull-docs async-timeout==4.0.3 # via aiohttp @@ -42,7 +42,7 @@ babel==2.15.0 # sphinx-intl build==1.2.1 # via antsibull-core -certifi==2024.6.2 +certifi==2024.7.4 # via requests charset-normalizer==3.3.2 # via requests @@ -85,11 +85,11 @@ packaging==24.1 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.7.4 +pydantic==2.8.2 # via # antsibull-core # antsibull-docs -pydantic-core==2.18.4 +pydantic-core==2.20.1 # via pydantic pygments==2.18.0 # via @@ -178,5 +178,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==70.1.1 +setuptools==70.2.0 # via sphinx-intl From ed3c4fe85045d466476e7433b68be260ece6f316 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 8 Jul 2024 10:13:27 +0100 Subject: [PATCH 439/536] Nightly builds for package docs publishing workflow (#1663) --- .github/workflows/build-package-docs.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 88050aeab27..7f72a5dd656 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -2,6 +2,8 @@ name: Ansible package docs build on: + schedule: + - cron: '17 5 * * *' workflow_dispatch: inputs: repository-owner: From 7085c949b870ccdde36f90638b6e6738f424f621 Mon Sep 17 00:00:00 2001 From: Lyle McKarns Date: Tue, 9 Jul 2024 09:07:44 -0400 Subject: [PATCH 440/536] Adding daily schedule to CI build (#1659) * Adding daily schedule to CI build * Change from 0 minute to 23, per discussion and referenced suggestion. --- .github/workflows/ci.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index cc46b3f4d81..c52912470b2 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -1,6 +1,9 @@ name: Ansible Docsite CI on: + schedule: + # Daily + - cron: "23 7 * * *" push: branches-ignore: - 'patchback/**' From b7f528e0632edd1a2756b583aae4d52738bbbe4b Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 10 Jul 2024 17:06:04 +0100 Subject: [PATCH 441/536] remove the schedule from the workflow dispatch job (#1683) Relates to issue #1682. This change removes the schedule to stop the workflow from failing due to null input values. We can either add this back with some expressions to set defaults for scheduled runs or create a simplified build workflow that runs on a schedule. --- .github/workflows/build-package-docs.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 7f72a5dd656..88050aeab27 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -2,8 +2,6 @@ name: Ansible package docs build on: - schedule: - - cron: '17 5 * * *' workflow_dispatch: inputs: repository-owner: From db0560c93cfce1db113927463655b4b299966dad Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 11 Jul 2024 10:06:29 +0100 Subject: [PATCH 442/536] notify docs matrix channel on docs build failures (#1651) * notify docs matrix channel on docs build failures * add url with run id --- .github/workflows/build-package-docs.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 88050aeab27..e79db6f9787 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -131,6 +131,28 @@ jobs: echo "Owner: ${{ github.event.inputs.repository-owner }}" >> "${GITHUB_STEP_SUMMARY}" echo "Branch: ${{ github.event.inputs.repository-branch }}" >> "${GITHUB_STEP_SUMMARY}" + notify-build-failures: + if: failure() + needs: build-package-docs + runs-on: ubuntu-latest + env: + ROOM_URL: https://ansible-accounts.ems.host/_matrix/client/v3/rooms/!HJtetIFWYEIDBOXxFE:libera.chat/send/m.room.message + FAIL_MESSAGE: >- + Oh no! A community package docs build has failed. + Check this workflow run to see what went wrong: + https://github.com/ansible/ansible-documentation/actions/runs/${{ github.run_id }} + @orandon @samccann + steps: + - name: Set a transaction ID + run: echo "TX_ID=$(date +%s)" >> "${GITHUB_ENV}" + + - name: Notify the DaWGs in Matrix + run: | + curl -X PUT "${{ env.ROOM_URL }}/${TX_ID}" \ + -H "Authorization: Bearer ${{ secrets.DOCS_BOT_TOKEN }}" \ + -H "Content-Type: application/json" \ + -d '{"msgtype": "m.text", "body": "${{ env.FAIL_MESSAGE }}"}' + deploy-package-docs: if: fromJSON(github.event.inputs.deploy) needs: build-package-docs From 0b1fa3f8ebd0872035a7076e747d4ec7eef47370 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 11 Jul 2024 05:07:56 -0400 Subject: [PATCH 443/536] Remove language option from workflow (#1681) * Remove deprecated language input from the publishing workflow --- .github/workflows/build-package-docs.yaml | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index e79db6f9787..0543abe548f 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -16,14 +16,6 @@ on: description: Branch, tag, or commit SHA required: true default: devel - language: - type: choice - description: Language - required: true - default: english - options: - - english - - japanese ansible-package-version: type: choice description: Ansible community package version @@ -91,13 +83,8 @@ jobs: >> "${GITHUB_ENV}" - name: Set the VERSION variable - run: | - if [ ${LANGUAGE} == "english" ]; then - echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}" - elif [ ${LANGUAGE} == "japanese" ]; then - echo VERSION="${PACKAGE_VERSION}_ja" >> "${GITHUB_ENV}" - fi - + run: echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}" + - name: Build the Ansible community package docs run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}" working-directory: build-directory/docs/docsite From 6c7f7b53430b64e8224f20d5c42c972bce48621d Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 11 Jul 2024 12:46:31 +0200 Subject: [PATCH 444/536] collection_requirements: fix typo (#1684) * collection_requirements: fix typo * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- .../collection_contributors/collection_requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index c2ae4bc2b25..6931ddb0d23 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -299,7 +299,7 @@ There are several types of content in collections which licensing has to address * The content that MUST be licensed with a free software license that is **compatible with** the `GPL-3.0-or-later `_: * The ``modules/`` directory content. - * The ``module_utils/`` directory content: ansible-core 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``. + * The ``module_utils/`` directory content: ansible-core typically uses the `BSD-2-clause `_ license to allow third-party modules to use the ``module_utils`` in cases when those third-party modules have licenses that are incompatible with the GPLv3. Please consider this use case when licensing your own ``module_utils``. * Code outside ``plugins/``: if it DOES NOT import code licensed under ``GPL-3.0-or-later`` it may be licensed under another license compatible with ``GPL-3.0-or-later``. * Non-code content. * To be allowed, the license MUST be considered open source and compatible with ``GPL-3.0-or-later`` on **both**: From e9bedf70369a7949afa89208b15a01d9f8c84327 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 15 Jul 2024 11:07:59 +0100 Subject: [PATCH 445/536] restore anchor in communication guide (#1692) --- docs/docsite/rst/community/communication.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index a8d4e4ba5be..54fa46e350d 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -64,6 +64,8 @@ You can add Matrix shields to your repository's ``README.md`` using the shield i IRC channels are no longer considered official communication channels. Please use the Forum and Matrix instead. +.. _general_channels: + General channels ---------------- @@ -71,7 +73,7 @@ The clickable links will take you directly to the relevant Matrix room in your b - `Community social room and posting news for the Bullhorn newsletter `_ - `General usage and support questions `_ -- `Discussions on developer topics and code related to features or bugs `_ +- `Discussions on developer topics and code related to features or bugs `_ - `Discussions on community and collections related topics `_ Working group-specific channels From 7afbad9dd83a98ef017e688c9e868fa02db6e3c8 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 16 Jul 2024 20:17:03 +0200 Subject: [PATCH 446/536] Add porting guide for Ansible 10.2.0. (#1697) --- .../rst/porting_guides/porting_guide_10.rst | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst index cd8261f3dea..3dd8a539b02 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -99,6 +99,67 @@ Networking No notable changes +Porting Guide for v10.2.0 +========================= + +Added Collections +----------------- + +- kubevirt.core (version 1.5.0) +- vmware.vmware (version 1.3.0) + +Known Issues +------------ + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + +Major Changes +------------- + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_server_config_profile - This module is enhanced to allow you to export and import custom defaults on iDRAC. +- ome_configuration_compliance_baseline - This module is enhanced to schedule the remediation job and stage the reboot. + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Add a sanity_test.yaml file to trigger CI tests in GitHub. +- Support Ansible-core 2.17. +- Support new FOS versions 7.4.4. + +grafana.grafana +~~~~~~~~~~~~~~~ + +- Add a config check before restarting mimir by @panfantastic in https://github.com/grafana/grafana-ansible-collection/pull/198 +- Add support for configuring feature_toggles in grafana role by @LexVar in https://github.com/grafana/grafana-ansible-collection/pull/173 +- Backport post-setup healthcheck from agent to alloy by @v-zhuravlev in https://github.com/grafana/grafana-ansible-collection/pull/213 +- Bump ansible-lint from 24.2.3 to 24.5.0 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/207 +- Bump ansible-lint from 24.5.0 to 24.6.0 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/216 +- Bump braces from 3.0.2 to 3.0.3 in the npm_and_yarn group across 1 directory by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/218 +- Bump pylint from 3.1.0 to 3.1.1 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/200 +- Bump pylint from 3.1.1 to 3.2.2 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/208 +- Bump pylint from 3.2.2 to 3.2.3 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/217 +- Bump pylint from 3.2.3 to 3.2.5 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/234 +- Change from config.river to config.alloy by @cardasac in https://github.com/grafana/grafana-ansible-collection/pull/225 +- Fix Grafana Configuration for Unified and Legacy Alerting Based on Version by @voidquark in https://github.com/grafana/grafana-ansible-collection/pull/215 +- Support adding alloy user to extra groups by @v-zhuravlev in https://github.com/grafana/grafana-ansible-collection/pull/212 +- Updated result.json['message'] to result.json()['message'] by @CPreun in https://github.com/grafana/grafana-ansible-collection/pull/223 + +Deprecated Features +------------------- + +- The ``frr.frr`` collection has been deprecated by the maintainers. Since they've also announced to not support ansible-core 2.18, it will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/6243). +- The ``openvswitch.openvswitch`` collection has been deprecated by the maintainers. Since they've also announced to not support ansible-core 2.18, it will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/6245). + Porting Guide for v10.1.0 ========================= From 780b4d9bbe57770191c84060b624a0ab0c9afd37 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 16 Jul 2024 20:17:16 +0200 Subject: [PATCH 447/536] Add porting guide for Ansible 9.8.0. (#1698) --- .../rst/porting_guides/porting_guide_9.rst | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 6b514011724..0f715944f78 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -84,6 +84,31 @@ Porting custom scripts Networking ========== +Porting Guide for v9.8.0 +======================== + +Added Collections +----------------- + +- ieisystem.inmanage (version 2.0.0) +- vmware.vmware (version 1.3.0) + +Major Changes +------------- + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Add a sanity_test.yaml file to trigger CI tests in GitHub. +- Support Ansible-core 2.17. +- Support new FOS versions 7.4.4. + +Deprecated Features +------------------- + +- The ``frr.frr`` collection has been deprecated by the maintainers. Since they've also announced to not support ansible-core 2.18, it will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/6243). +- The ``openvswitch.openvswitch`` collection has been deprecated by the maintainers. Since they've also announced to not support ansible-core 2.18, it will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/6245). + Porting Guide for v9.7.0 ======================== From 5c49902b7031aa9814771939fe2ff7dabdc2716a Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 18 Jul 2024 07:12:11 +0200 Subject: [PATCH 448/536] Move community_topics_workflow to docs.ansible.com (#1028) * Move community_topics_workflow to docs.ansible.com * Simplify * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Mario Lenz * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Mario Lenz * Improve * Replacing Creating a topic section content * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Clarify * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro --------- Co-authored-by: Mario Lenz Co-authored-by: Don Naro --- docs/docsite/rst/community/communication.rst | 2 + .../steering/community_topics_workflow.rst | 144 +++++++++--------- 2 files changed, 76 insertions(+), 70 deletions(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 54fa46e350d..d929a4b0a82 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -22,6 +22,8 @@ The `Ansible Forum `_ is a single starting point and Take a look at the `forum groups `_ and join ones that match your interests. In most cases, joining a forum group automatically subscribes you to related posts. +.. _bullhorn: + The Bullhorn ------------ diff --git a/docs/docsite/rst/community/steering/community_topics_workflow.rst b/docs/docsite/rst/community/steering/community_topics_workflow.rst index dd2f1b2024e..0e32d516d37 100644 --- a/docs/docsite/rst/community/steering/community_topics_workflow.rst +++ b/docs/docsite/rst/community/steering/community_topics_workflow.rst @@ -4,121 +4,125 @@ For other changes, create a `community topic `_ to discuss them. (Creating a draft PR for this file and mentioning it in the community topic is also OK.) -Ansible community topics workflow -================================= +.. _community_topics_workflow: + +Community topics workflow +========================= Overview -------- -This document describes the Ansible community topics workflow (herein after ``Workflow``) to provide guidance on successful resolving topics in an asynchronous way. +This document describes the Ansible community topics workflow to provide guidance on successful resolving topics in the asynchronous way. -The Workflow is a set of actions that need to be done successively within the corresponding time frames. +The workflow is a set of actions that need to be completed in order within the corresponding time frames. .. note:: - If you have any ideas on how the Workflow can be improved, please create an issue in this repository or pull request against this document. + The following section outlines a generic scenario for a workflow. + Workflows can vary depending on a topic's complexity and other nuances; for example, when there is a mass agreement from the beginning. Creating a topic ---------------- -Any person can `create a topic `_ tagged with ``community-wg`` under the ``Project Discussions`` category in the `Ansible Forum `_. A :ref:`Steering Committee member` can tag the forum post with `community-wg-nextmtg` to put it on the meeting agenda. - -Workflow --------- - -.. note:: - - This is a rough scenario and it can vary depending on a topic's complexity and other nuances, for example, when there is a mass agreement upfront. +Any person can :ref:`create a community topic`. Preparation stage -^^^^^^^^^^^^^^^^^ +----------------- -A Committee person checks the topic content and asks the author, or other persons, to provide additional information if needed. +* A Committee person checks the topic's content and asks the author/other persons to provide additional information as needed. Discussion stage -^^^^^^^^^^^^^^^^ - -* If the topic is ready to be discussed, the Committee person: - - * Adds the ``community-wg-nextmtg`` tag if it needs to be discussed in the meeting. +---------------- - * Opens the discussion by adding a comment asking the Community and the Committee to take part in it. +* By default, the discussion happens asynchronously in the topic. -* No synchronous discussion is needed (there are no blockers, complications, confusion, or impasses). + * A :ref:`steering committee ` member can tag the forum post with ``community-wg-nextmtg`` to put it on the synchronous meeting agenda. Voting stage -^^^^^^^^^^^^ - -* Depending on the topic complexity, 1-2 weeks after the discussion was opened, the Committee person formulates vote options based on the prior discussion and gives participants a reasonable amount of time to propose changes to the options (no longer than a week). The person summarizes the options in a comment and also establishes a date when the vote begins if there are no objections about the options or vote date. -* In the vote date, the vote starts with a comment from a Committee person who opens the vote and establishes a date when the vote ends ($CURRENT_DATE + no longer than 21 days; Usually it should not exceed 14 days. 21 days should only be used if it is known that a lot of interested persons will likely not have time to vote in a 14 day period). -* The Committee person labels the topic with the ``active-vote`` tag. -* The Committee person adds ``[Vote ends on $YYYY-MM-DD]`` to the beginning of the topic description. -* A vote is actually two polls, one for the Steering Committee, one for everyone else. To create a vote in a topic: - - * Create a new post in the topic. - - * Click the ``gear`` button in the composer and select ``Build Poll``. +------------ - * Click the ``gear`` in the Poll Builder for advanced mode. +The Committee person: - * Set up the options (generally this will be Single Choice but other poll types can be used). +* Formulates vote options based on the prior discussion and gives participants up to one week to propose changes to the options. This step takes place one to two weeks after the discussion was opened, depending on the complexity of the topic. +* Summarizes the options in a comment and establishes a date for the vote to begin if there are no objections to the options. +* Starts the vote on the beginning date and establishes an end date, which is $CURRENT_DATE plus: - * Title it "Steering Committee vote" and "Limit voting" to the ``Steering Committee``. + * 7 days: simple cases + * 14 days: maximum vote length + * 21 days: only used in exceptional cases such as holiday seasons when the majority of the Committee are not able to participate in the vote +* Labels the topic with the ``active-vote`` tag. +* Adds ``[Vote ends on $YYYY-MM-DD]`` to the beginning of the topic's description. - * Do not set the close date because it cannot be changed later. - - * Results should be "Always Visible" unless there is some good reason for the SC votes not to be public. - - * Submit the poll (the BBcode will appear in the post) and then repeat the above for the second poll. - - * The title should be "Community vote". +The vote always consists of two polls: one for the Steering Committee, one for everyone else. To create a vote in a topic: + * Create a new post in the topic. + * Click the ``gear`` button in the composer and select ``Build Poll``. + * Click the ``gear`` in the ``Poll Builder`` for advanced mode. + * Set up the options (generally this will be ``Single Choice`` but other poll types can be used). + * Title it "Steering Committee vote" and ``Limit voting`` to the ``@SteeringCommittee``. + * Do NOT set the close date because this cannot be changed later. + * Results should be ``Always Visible`` unless there is a good reason for the SC votes not to be public. + * Submit the poll (the BBcode will appear in the post): + * Repeat the above steps for the second poll: + + * Title should be "Community vote". * No group limitation. Voting result stage -^^^^^^^^^^^^^^^^^^^ - -* The day after the last day of the vote, the Committee person: - - * Closes the polls. +------------------- - * Removes the ``active-vote`` tag. - - * Add a comment that the vote ended. - - * Changes the beginning of the topic's description to ``[Vote ended]``. - - * Creates a summary comment declaring the vote result. - -* The vote result and final decision are announced via the `Bullhorn newsletter `_. +On the vote end date, the Committee person: +* Closes the polls if the :ref:`quorum` is reached, otherwise prolongs the polls. +* Removes the ``active-vote`` tag. +* Adds a comment that the vote has ended. +* Changes the beginning of the topic's description to ``[Vote ended]``. +* Creates a summary comment declaring the vote result. +* Announces the vote result and the final decision in the :ref:`Bullhorn `. Implementation stage -^^^^^^^^^^^^^^^^^^^^ +-------------------- -* If the topic implies some actions (if it does not, just mark this as complete), the Committee person: +No further action required +~~~~~~~~~~~~~~~~~~~~~~~~~~ - * Assigns the topic to the person who is responsible for performing the actions. +The Committee person: - * Add the ``being-implemented`` tag to the topic. +* Merges an associated pull request if exists. +* Adds the ``resolved`` tag. - * After the topic is implemented, the assignee: +Further actions required +~~~~~~~~~~~~~~~~~~~~~~~~ - * Comments on the topic that the work is done. +The Committee person: - * Removes the ``being-implemented`` tag. +* Assigns a person responsible for performing the actions by mentioning them in a comment. +* Adds the ``being-implemented`` tag to the topic. - * Add the ``implemented`` tag. +After the actions are done, the assignee: -* If the topic implies actions related to the future Ansible Community package releases (for example, a collection exclusion), the Committee person: +* Comments on the topic that the work is done. +* Removes the ``being-implemented`` tag. +* Adds the ``implemented`` and ``resolved`` tags. - * Adds the ``scheduled-for-future-release`` tag to the topic. +Package-release related actions required +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - * Checks if there is a corresponding milestone in the `ansible-build-data `_ repository. If there is no milestone, the person creates it. +If the topic implies actions related to the future Ansible community package releases (for example, a collection exclusion), the Committee person/assignee: - * Creates an issue in ansible-build-data that references the :ref:`community topic`, and adds it to the milestone. +* Adds the ``scheduled-for-future-release`` tag to the topic. +* Checks if there is a corresponding milestone in the `ansible-build-data `_ repository. + + * If there is no milestone, the person creates it. +* Creates an issue in ``ansible-build-data`` that references the topic and adds it to the milestone. +* After it is implemented, adds the ``implemented`` and ``resolved`` tags. Tools ----- -We have some `scripts `_ that can be used to create Ansible community announcements in the Bullhorn and similar places. +There are a few `scripts `_ that can be used to create Ansible community announcements on the Bullhorn and similar locations. + +.. seealso:: + + :ref:`steering committee ` + Ansible Community Steering Committee From be8bc9fcf572eb4933e2df8c6f411bc0abdfbdbb Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Fri, 19 Jul 2024 16:44:07 +0100 Subject: [PATCH 449/536] ci: refresh docs build dependencies (#1691) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 2 +- tests/requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index b4bbb7a37a5..ddc2e5f9528 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -177,5 +177,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==70.2.0 +setuptools==70.3.0 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index b1d306c03a8..21b3f754fb0 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -178,5 +178,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==70.2.0 +setuptools==70.3.0 # via sphinx-intl From be4c7259aab72981813aac2cce6bf33bace77b65 Mon Sep 17 00:00:00 2001 From: Lyle McKarns Date: Tue, 23 Jul 2024 16:15:34 -0400 Subject: [PATCH 450/536] Issue #1633 nox session for tagging (#1649) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * WIP tagger session for nox * First pass tagging nox session * Formatting fixup * Adding removal of tmpdir as per discussion * tag session checks for, and uses, existing ansible checkout if it exists, removes tmpdir if it created one. * isort fixup * Working out suggested changes. * Linting cleanup on changes * Different approach to noted chagnes * Reducing tagging session to a bare bones wrapper around the script, leaving all repo management alone * Staging deletion per discussion * Adding tag session to dependency update job * after removing hacking/tagger/requirements.txt moved "gitpython" here for the typing test session requiremnts. * Adding that here didd not accomplish what I'd expected. Removing it and revisiting how to do that. * I think this is where the call needed added to get the tags dependencies automatically updated * remove gitpython, add tag.txt, add blank line * Comment cleanup per OraNod * doc README: document nox tag session instead of manual mode * Update tests/typing.in Per suggestion from @webnjaz Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --------- Co-authored-by: Maxwell G Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/pip-compile-dev.yml | 1 + README.md | 20 ++++--------- noxfile.py | 15 ++++++++++ .../tagger/requirements.txt => tests/tag.in | 0 tests/tag.txt | 30 +++++++++++++++++++ tests/typing.in | 2 +- 6 files changed, 53 insertions(+), 15 deletions(-) rename hacking/tagger/requirements.txt => tests/tag.in (100%) create mode 100644 tests/tag.txt diff --git a/.github/workflows/pip-compile-dev.yml b/.github/workflows/pip-compile-dev.yml index c648cd9dcf9..89ae8e77184 100644 --- a/.github/workflows/pip-compile-dev.yml +++ b/.github/workflows/pip-compile-dev.yml @@ -39,6 +39,7 @@ jobs: 'pip-compile-3.10(typing)' 'pip-compile-3.10(static)' 'pip-compile-3.10(spelling)' + 'pip-compile-3.10(tag)' reset-branch: "${{ inputs.reset-branch || false }}" labels: "${{ inputs.labels || 'backport-2.14,backport-2.15,backport-2.16,backport-2.17,tooling' }}" secrets: inherit diff --git a/README.md b/README.md index 2c729580b0d..9ec6cd5a5be 100644 --- a/README.md +++ b/README.md @@ -141,30 +141,22 @@ podman run --rm --tty --volume "$(pwd):/mnt:z" --workdir /mnt docker.io/library/ When a tag is created in the [`ansible/ansible`](https://github.com/ansible/ansible) repository for a release or release candidate, a corresponding tag should be created in this `ansible-documentation` repository. -First, install the additional tagging dependencies from this repository as follows, creating or activating a `venv` as needed: - -``` bash -python3 -m venv ./venv -source ./venv/bin/activate -pip install -r hacking/tagger/requirements.txt -``` - -Next, ensure that you have the [`ansible/ansible`](https://github.com/ansible/ansible) and [`ansible/ansible-documentation`](https://github.com/ansible/ansible-documentation) repositories checked out. +First, ensure that you have the [`ansible/ansible`](https://github.com/ansible/ansible) and [`ansible/ansible-documentation`](https://github.com/ansible/ansible-documentation) repositories checked out. The tool assumes that both checkouts have the same parent directory. You can set different paths to your checkouts with the `--docs` and `--core` options if you have them set up another way. -Lastly, run the tagger script. +Next, run the `tag` `nox` session. This will determine any missing `ansible-core` tags and create them in `ansible-documentation` if needed, exiting normally otherwise: ``` bash # The tagger scripts assumes "origin" as the upstream remote. -./hacking/tagger/tag.py tag +nox -s tag # If you use a different upstream remote, specify the name. -./hacking/tagger/tag.py --remote tag +nox -s tag -- --remote tag # If your core repo is not in the same filesystem location, specify the path. -./hacking/tagger/tag.py --core tag +nox -s tag -- --core tag ``` -See `--help` for extended options. +See `nox -s tag -- --help` for extended options. diff --git a/noxfile.py b/noxfile.py index fbb0beb757d..e685f9349e7 100644 --- a/noxfile.py +++ b/noxfile.py @@ -180,3 +180,18 @@ def make(session: nox.Session): *(args.make_args or ("clean", "coredocs")), ] session.run("make", "-C", "docs/docsite", *make_args, external=True) + + +@nox.session +def tag(session: nox.Session): + """ + Check the core repo for new releases and create tags in ansible-documentation + """ + install(session, req="tag") + args = list(session.posargs) + + # If run without any arguments, default to "tag" + if not any(arg.startswith(("hash", "mantag", "new-tags", "tag")) for arg in args): + args.append("tag") + + session.run("python", "hacking/tagger/tag.py", *args) diff --git a/hacking/tagger/requirements.txt b/tests/tag.in similarity index 100% rename from hacking/tagger/requirements.txt rename to tests/tag.in diff --git a/tests/tag.txt b/tests/tag.txt new file mode 100644 index 00000000000..faa6f01587c --- /dev/null +++ b/tests/tag.txt @@ -0,0 +1,30 @@ +# +# This file is autogenerated by pip-compile with Python 3.10 +# by the following command: +# +# pip-compile --allow-unsafe --output-file=tests/tag.txt --strip-extras tests/tag.in +# +click==8.1.7 + # via typer +gitdb==4.0.11 + # via gitpython +gitpython==3.1.43 + # via -r tests/tag.in +markdown-it-py==3.0.0 + # via rich +mdurl==0.1.2 + # via markdown-it-py +packaging==24.1 + # via -r tests/tag.in +pygments==2.18.0 + # via rich +rich==13.7.1 + # via typer +shellingham==1.5.4 + # via typer +smmap==5.0.1 + # via gitdb +typer==0.12.3 + # via -r tests/tag.in +typing-extensions==4.12.2 + # via typer diff --git a/tests/typing.in b/tests/typing.in index 5eaee63794a..9701e2c5780 100644 --- a/tests/typing.in +++ b/tests/typing.in @@ -1,4 +1,4 @@ -r ../hacking/pr_labeler/requirements.txt --r ../hacking/tagger/requirements.txt +-r tag.in mypy nox From 141ca118dc7fbe17cccc4c9ba0c42645028c6766 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Wed, 24 Jul 2024 11:21:02 +0100 Subject: [PATCH 451/536] ci: refresh dev dependencies (#1707) * ci: refresh dev dependencies * ci: refresh dev dependencies --------- Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/static.txt | 2 +- tests/typing.txt | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index aca335586ef..3c54c1fafc1 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.5.1 +ruff==0.5.4 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index c2f8cfe95fb..ce1a5713f27 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -20,7 +20,7 @@ codeowners==0.7.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 # via nox -cryptography==42.0.8 +cryptography==43.0.0 # via pyjwt deprecated==1.2.14 # via pygithub @@ -31,7 +31,7 @@ filelock==3.15.4 gitdb==4.0.11 # via gitpython gitpython==3.1.43 - # via -r tests/../hacking/tagger/requirements.txt + # via -r tests/tag.in idna==3.7 # via requests jinja2==3.1.4 @@ -42,7 +42,7 @@ markupsafe==2.1.5 # via jinja2 mdurl==0.1.2 # via markdown-it-py -mypy==1.10.1 +mypy==1.11.0 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy @@ -50,7 +50,7 @@ nox==2024.4.15 # via -r tests/typing.in packaging==24.1 # via - # -r tests/../hacking/tagger/requirements.txt + # -r tests/tag.in # nox platformdirs==4.2.2 # via virtualenv @@ -79,7 +79,7 @@ tomli==2.0.1 typer==0.12.3 # via # -r tests/../hacking/pr_labeler/requirements.txt - # -r tests/../hacking/tagger/requirements.txt + # -r tests/tag.in typing-extensions==4.12.2 # via # codeowners From 79ae2075bf950a768ed5aaea2cdf28b6dd2436ed Mon Sep 17 00:00:00 2001 From: Sebi Date: Wed, 24 Jul 2024 17:23:55 +0200 Subject: [PATCH 452/536] Be more explicit about registering with a loop (#1709) --- docs/docsite/rst/playbook_guide/playbooks_loops.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index 27f1d120fea..7c6fb9dac6f 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -167,7 +167,7 @@ You can register the output of a loop as a variable. For example - "two" register: echo -When you use ``register`` with a loop, the data structure placed in the variable will contain a ``results`` attribute that is a list of all responses from the module. This differs from the data structure returned when using ``register`` without a loop. +When you use ``register`` with a loop, the data structure placed in the variable will contain a ``results`` attribute that is a list of all responses from the module. This differs from the data structure returned when using ``register`` without a loop. The ``changed``/``failed``/``skipped`` attribute that's beside the ``results`` will represent the overall state. ``changed``/``failed`` will be `true` if at least one of the iterations triggered a change/failed, while ``skipped`` will be `true` only if all iterations were skipped. .. code-block:: json From 9dfa018075c7fde2d78cdf2cd496931c1a365ada Mon Sep 17 00:00:00 2001 From: ignyx Date: Thu, 25 Jul 2024 23:18:41 +0200 Subject: [PATCH 453/536] add vault password file example (#1696) * add vault password file example * remove duplicate word in vault password file example Co-authored-by: Sandra McCann --------- Co-authored-by: Sandra McCann --- docs/docsite/rst/vault_guide/vault_managing_passwords.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/docsite/rst/vault_guide/vault_managing_passwords.rst b/docs/docsite/rst/vault_guide/vault_managing_passwords.rst index e83eecf1c29..4a685f54639 100644 --- a/docs/docsite/rst/vault_guide/vault_managing_passwords.rst +++ b/docs/docsite/rst/vault_guide/vault_managing_passwords.rst @@ -73,6 +73,12 @@ Storing passwords in files To store a vault password in a file, enter the password as a string on a single line in the file. Make sure the permissions on the file are appropriate. Do not add password files to source control. +When you run a playbook that uses a vault password stored in a file, specify the file within the ``--vault-password-file`` flag. For example: + +.. code-block:: bash + + ansible-playbook --extra-vars @secrets.enc --vault-password-file secrets.pass + .. _vault_password_client_scripts: Storing passwords in third-party tools with vault password client scripts From dc4f370b00c648b74937abca134e6c5f6e9e4b04 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 29 Jul 2024 09:40:20 +0100 Subject: [PATCH 454/536] ci: refresh dev dependencies (#1722) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/static.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/static.txt b/tests/static.txt index 3c54c1fafc1..1d46f32a5c6 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.5.4 +ruff==0.5.5 # via -r tests/static.in From a8036fa565a9c7884bd91629d4cca8d8a11b0a13 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Tue, 6 Aug 2024 10:46:55 +0100 Subject: [PATCH 455/536] ci: refresh dev dependencies (#1730) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index fb3fda3d9f7..35c12bae48f 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -4,7 +4,7 @@ # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in # -black==24.4.2 +black==24.8.0 # via -r tests/formatters.in click==8.1.7 # via black diff --git a/tests/static.txt b/tests/static.txt index 1d46f32a5c6..2572ccd15da 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.5.5 +ruff==0.5.6 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index ce1a5713f27..d082e99e928 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -42,7 +42,7 @@ markupsafe==2.1.5 # via jinja2 mdurl==0.1.2 # via markdown-it-py -mypy==1.11.0 +mypy==1.11.1 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy @@ -60,7 +60,7 @@ pygithub==2.3.0 # via -r tests/../hacking/pr_labeler/requirements.txt pygments==2.18.0 # via rich -pyjwt==2.8.0 +pyjwt==2.9.0 # via pygithub pynacl==1.5.0 # via pygithub From e2137b19a5bbc9cc7406fb5f45af4b3f1a75b421 Mon Sep 17 00:00:00 2001 From: Matthias Kunnen Date: Wed, 7 Aug 2024 10:11:35 +0200 Subject: [PATCH 456/536] Update integration test guide docker flag usage (#1731) * Update integration test guide docker flag usage The integration guide linked to a file in the devel branch that gets out-of-sync with the actual supported images on the user's system. Instead, we now instruct the user to run the help flag to get the list of supported images that are actually present on their system. * Point users to the right section in ansible-test integration --help --- docs/docsite/rst/dev_guide/testing_integration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/dev_guide/testing_integration.rst b/docs/docsite/rst/dev_guide/testing_integration.rst index 3667e8a39b3..e830ba032b1 100644 --- a/docs/docsite/rst/dev_guide/testing_integration.rst +++ b/docs/docsite/rst/dev_guide/testing_integration.rst @@ -72,7 +72,7 @@ outside of those test subdirectories. They will also not reconfigure or bounce .. note:: Running integration tests within containers - To protect your system from any potential changes caused by integration tests, and to ensure a sensible set of dependencies are available we recommend that you always run integration tests with the ``--docker`` option, for example ``--docker ubuntu2004``. See the `list of supported container images `_ for options (the ``default`` image is used for sanity and unit tests, as well as for platform independent integration tests such as those for cloud modules). + To protect your system from any potential changes caused by integration tests, and to ensure a sensible set of dependencies are available we recommend that you always run integration tests with the ``--docker`` option, for example ``--docker ubuntu2204``. Get the list of supported container images by running ``ansible-test integration --help``. You can find them in the *target docker images* section of the output. The ``default`` image is used for sanity and unit tests, as well as for platform independent integration tests such as those for cloud modules. Run as follows for all POSIX platform tests executed by our CI system in a Fedora 34 container: @@ -245,4 +245,4 @@ Where to find out more ====================== If you'd like to know more about the plans for improving testing Ansible, join the -`Ansible community forum `_ \ No newline at end of file +`Ansible community forum `_ From d29db92914255a6733d22348a9577239a9dfa9c6 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Fri, 9 Aug 2024 15:49:58 -0400 Subject: [PATCH 457/536] Added 'direct' to general precedence (#1740) * added 'direct' to general precedence * other minor fixes * fix code lbock * Apply suggestions from code review Co-authored-by: Sandra McCann * clarificlearing * Update docs/docsite/rst/reference_appendices/general_precedence.rst --------- Co-authored-by: Sandra McCann --- .../general_precedence.rst | 36 +++++++++++++++++-- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/general_precedence.rst b/docs/docsite/rst/reference_appendices/general_precedence.rst index a94f4a64f15..7beb76b1c73 100644 --- a/docs/docsite/rst/reference_appendices/general_precedence.rst +++ b/docs/docsite/rst/reference_appendices/general_precedence.rst @@ -21,6 +21,7 @@ Ansible offers four sources for controlling its behavior. In order of precedence * Command-line options * Playbook keywords * Variables + * Direct Assignment Each category overrides any information from all lower-precedence categories. For example, a playbook keyword will override any configuration setting. @@ -97,7 +98,7 @@ Playbooks are the command or 'state description' structure for Ansible, variable Variables ^^^^^^^^^ -Any variable will override any playbook keyword, any command-line option, and any configuration setting. +Ansible variables are very high on the precedence stack. They will override any playbook keyword, any command-line option, environment variable and any configuration file setting. Variables that have equivalent playbook keywords, command-line options, and configuration settings are known as :ref:`connection_variables`. Originally designed for connection parameters, this category has expanded to include other core variables like the temporary directory and the python interpreter. @@ -136,15 +137,44 @@ Variable values set in a playbook exist only within the playbook object that def Variable values associated directly with a host or group, including variables defined in inventory, by vars plugins, or using modules like :ref:`set_fact` and :ref:`include_vars`, are available to all plays. These 'host scope' variables are also available through the ``hostvars[]`` dictionary. +Variables set through ``extra vars`` have a global scope for the current run and will be present both as 'playbook object vars' and 'hostvars'. + .. _general_precedence_extra_vars: Using ``-e`` extra variables at the command line -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""""""""""" -To override all other settings in all other categories, you can use extra variables: ``--extra-vars`` or ``-e`` at the command line. Values passed with ``-e`` are variables, not command-line options, and they will override configuration settings, command-line options, and playbook keywords as well as variables set elsewhere. For example, this task will connect as ``brian`` not as ``carol``: +To override all other variables, you can use extra variables: ``--extra-vars`` or ``-e`` at the command line. Values passed with ``-e``, while still a command-line option itself, have the highest precedence among variables and will, a bit counter intuitively, be of the higher precedence among most configuration sources, since variables themselves have high precedence. For example, this task will connect as ``brian`` not as ``carol``: .. code:: shell ansible -u carol -e 'ansible_user=brian' -a whoami all You must specify both the variable name and the value with ``--extra-vars``. + + +Direct Assignment +^^^^^^^^^^^^^^^^^ + +This category only applies to things that take direct options, generally modules and some plugin types. Most modules and action plugins do not have any other way to assign settings so precedence rarely comes up in that context, but it still possible for some of them to do so and should be reflected in the documentation. + +.. code:: yaml + + - debug: msg='this is a direct assignment option to an action plugin' + + - ping: + data: also a direct assignment + +Outside of task actions, the most recognizable 'direct assignments' are with lookup, filter and test plugins: + +.. code:: + + lookup('plugin', direct1='value', direct2='value2') + + 'value_directly_assigned'|filter('another directly assigned') + + 'direct value' is testplugin + +Though most of these are not configured in other ways, specially tests, it is possible for plugins and filters to use input from other configuration sources if specified in their documentation. + +Inventory plugins are a bit tricky as they use 'inventory sources' and these sometimes can look like a configuration file and are passed in as a command line option, yet it is still considered 'direct assignment'. It is a bit clearer when using an inline source ``-i host1, host2, host3`` than when using a file source ``-i /path/to/inventory_source``, but they both have the same precedence. From f617a1ec8f7a50344b934e98c116944860b9b245 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 13 Aug 2024 16:08:41 +0200 Subject: [PATCH 458/536] setup.cfg and setup.py are gone since https://github.com/ansible/ansible/commit/68515abf97dfc769c9aed2ba457ed7b8b2580a5c (#1747) --- docs/bin/clone-core.py | 2 -- tests/checkers/docs-build.py | 2 -- 2 files changed, 4 deletions(-) diff --git a/docs/bin/clone-core.py b/docs/bin/clone-core.py index 4ef29087948..e0ea91f6eab 100755 --- a/docs/bin/clone-core.py +++ b/docs/bin/clone-core.py @@ -62,8 +62,6 @@ def main(args: Args) -> None: "MANIFEST.in", "pyproject.toml", "requirements.txt", - "setup.cfg", - "setup.py", ] with tempfile.TemporaryDirectory() as temp_dir: diff --git a/tests/checkers/docs-build.py b/tests/checkers/docs-build.py index 433d00e6cf1..14e579b3ae2 100644 --- a/tests/checkers/docs-build.py +++ b/tests/checkers/docs-build.py @@ -25,8 +25,6 @@ def main(): 'MANIFEST.in', 'pyproject.toml', 'requirements.txt', - 'setup.cfg', - 'setup.py', ] # The tests write to the source tree, which isn't permitted for sanity tests. From 2e04b7d34430d2b05e1cb1808f91e5ea77bdf2f4 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 13 Aug 2024 16:52:48 +0200 Subject: [PATCH 459/536] Add porting guide for Ansible 9.9.0. (#1745) --- .../rst/porting_guides/porting_guide_9.rst | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 0f715944f78..bc677c5e4f1 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -84,6 +84,35 @@ Porting custom scripts Networking ========== +Porting Guide for v9.9.0 +======================== + +Known Issues +------------ + +community.docker +~~~~~~~~~~~~~~~~ + +- docker_container - when specifying a MAC address for a container's network, and the network is attached after container creation (for example, due to idempotency checks), the MAC address is at least in some cases ignored by the Docker Daemon (https://github.com/ansible-collections/community.docker/pull/933). + +Deprecated Features +------------------- + +community.docker +~~~~~~~~~~~~~~~~ + +- The collection deprecates support for all ansible-core versions that are currently End of Life, `according to the ansible-core support matrix `__. This means that the next major release of the collection will no longer support ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. + +community.routeros +~~~~~~~~~~~~~~~~~~ + +- The collection deprecates support for all Ansible/ansible-base/ansible-core versions that are currently End of Life, `according to the ansible-core support matrix `__. This means that the next major release of the collection will no longer support Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. + +community.sops +~~~~~~~~~~~~~~ + +- The collection deprecates support for all Ansible/ansible-base/ansible-core versions that are currently End of Life, `according to the ansible-core support matrix `__. This means that the next major release of the collection will no longer support Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. + Porting Guide for v9.8.0 ======================== From 8da189f416ca159c69ecc1a206cce0dad8168bb9 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 13 Aug 2024 16:53:17 +0200 Subject: [PATCH 460/536] Add porting guide for Ansible 10.3.0. (#1746) --- .../rst/porting_guides/porting_guide_10.rst | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst index 3dd8a539b02..2c88d7e6a8e 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -99,6 +99,44 @@ Networking No notable changes +Porting Guide for v10.3.0 +========================= + +Known Issues +------------ + +community.docker +~~~~~~~~~~~~~~~~ + +- docker_container - when specifying a MAC address for a container's network, and the network is attached after container creation (for example, due to idempotency checks), the MAC address is at least in some cases ignored by the Docker Daemon (https://github.com/ansible-collections/community.docker/pull/933). + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + +Deprecated Features +------------------- + +community.docker +~~~~~~~~~~~~~~~~ + +- The collection deprecates support for all ansible-core versions that are currently End of Life, `according to the ansible-core support matrix `__. This means that the next major release of the collection will no longer support ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. + +community.routeros +~~~~~~~~~~~~~~~~~~ + +- The collection deprecates support for all Ansible/ansible-base/ansible-core versions that are currently End of Life, `according to the ansible-core support matrix `__. This means that the next major release of the collection will no longer support Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. + +community.sops +~~~~~~~~~~~~~~ + +- The collection deprecates support for all Ansible/ansible-base/ansible-core versions that are currently End of Life, `according to the ansible-core support matrix `__. This means that the next major release of the collection will no longer support Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. + Porting Guide for v10.2.0 ========================= From e8102e8f25d78fc76b2fc9cd886636496497b6bf Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Mon, 19 Aug 2024 09:23:24 +0200 Subject: [PATCH 461/536] [Needs SC vote before merging] Collection requirements: add Forum-related reqs (#1703) * Collection requirements: add Forum-related reqs * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Generalize welcoming sentence * Replace links with anchors * Discussions must be disabled if not used * Improve wrt notions * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: John Barker * Fix rst * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: flowerysong * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: flowerysong * Maintainers MUST -> SHOULD be subscribed to tags * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein * Fix a typo * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Maxwell G * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein --------- Co-authored-by: Don Naro Co-authored-by: John Barker Co-authored-by: flowerysong Co-authored-by: Felix Fontein Co-authored-by: Maxwell G --- .../collection_requirements.rst | 55 ++++++++++++++++--- docs/docsite/rst/community/communication.rst | 4 +- 2 files changed, 49 insertions(+), 10 deletions(-) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 6931ddb0d23..41b70ee0362 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -33,7 +33,52 @@ Keeping informed To track changes that affect collections: * Join the `Collection Maintainers & Contributors forum group `_. -* Subscribe to the `Bullhorn `_ Ansible contributor newsletter. +* Subscribe to the :ref:`bullhorn` Ansible contributor newsletter. + +.. _coll_wg_reqs: + +Communication and Working Groups +================================ + +Forum overview +-------------- + +The :ref:`ansible_forum` is our asynchronous default communication platform. + +In the context of organizing communication around Ansible collections, you need to understand the following notions: + +* `Tags `_: together with categories, tags are the main feature used in the Forum to organize conversations around specific topics. Most Ansible projects have one or more associated tags. For Ansible collections the main tag name is usually the technology the collection targets: examples include `kubernetes `_ for ``kubernetes.core``, `windows `_ for ``ansible.windows``, and `postgresql `_ for ``community.postgresql``. +* `Forum groups `_: groups allow you to organize users, manage permissions, have a working group page that provides related information, automatically subscribe members to tags, mention or message the whole group, and more. An example collection working group is the `PostgreSQL Ansible Collection Working Group `_. + +See the `Working Groups - things you can ask for! `_ forum topic for more details. + +Communication requirements +-------------------------- + +Your collection: + +* MUST have a corresponding public tag in the :ref:`ansible_forum` or reuse at least one of the `existing tags `_. + + * Multiple collections can share a tag if they cover similar topics; for example, ``amazon.aws`` and ``community.aws`` could both use the tag ``aws``. + + * In addition, the collection can :ref:`request a forum group`. If the collection requests or already has a group: + + * All related tags MUST be associated with the group. Everyone who joins the group is automatically subscribed to the tags. + * The group MUST be public and free to join by any forum user. + + * Use the `Requesting a tag/forum group `_ topic to request a tag and a forum group. + +* MUST have a communication section in its README with references to the :ref:`ansible_forum` similar to the `collection_template README.md `_. + + * The section MUST contain at least a reference to the `Get Help `_ forum category, potentially including a tag in the URL. + * The section MUST contain information on which tags participants should use for collection-related topics. + * If the collection has a forum group, the section MUST contain a reference to the group. + * Descriptions of the references MUST welcome readers to join and participate. + * Maintainers of the collection SHOULD be subscribed to all associated tags and be members of all associated groups. + +* SHOULD have the ``Discussions`` GitHub feature disabled in favor of the Forum. + + * Unless GitHub discussions are currently used, this feature MUST be `disabled on the repo `_. .. _coll_infrastructure_reqs: @@ -420,14 +465,6 @@ 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 are encouraged to request a working group on the :ref:`ansible_forum`. - .. _coll_migrating_reqs: When moving modules between collections diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index d929a4b0a82..6f1453b4708 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -99,8 +99,10 @@ Working Groups are a way for Ansible community members to self-organize around p Our community working groups are represented in `Forum groups `_. See those links for a complete list of communications channels. +.. _requesting_forum_group: + Requesting a forum group --------------------------- +------------------------ To request a new working group: From 091e4437c1ec07568fd229575b8ebd558c2163e0 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 19 Aug 2024 15:24:51 +0100 Subject: [PATCH 462/536] ci: refresh dev dependencies (#1744) * ci: refresh dev dependencies * ci: refresh dev dependencies --------- Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/static.txt | 2 +- tests/tag.txt | 2 +- tests/typing.txt | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index 2572ccd15da..727fbea66e8 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.5.6 +ruff==0.6.1 # via -r tests/static.in diff --git a/tests/tag.txt b/tests/tag.txt index faa6f01587c..523be2703c9 100644 --- a/tests/tag.txt +++ b/tests/tag.txt @@ -24,7 +24,7 @@ shellingham==1.5.4 # via typer smmap==5.0.1 # via gitdb -typer==0.12.3 +typer==0.12.4 # via -r tests/tag.in typing-extensions==4.12.2 # via typer diff --git a/tests/typing.txt b/tests/typing.txt index d082e99e928..01c550b5f73 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -4,11 +4,11 @@ # # pip-compile --allow-unsafe --output-file=tests/typing.txt --strip-extras tests/typing.in # -argcomplete==3.4.0 +argcomplete==3.5.0 # via nox certifi==2024.7.4 # via requests -cffi==1.16.0 +cffi==1.17.0 # via # cryptography # pynacl @@ -76,7 +76,7 @@ tomli==2.0.1 # via # mypy # nox -typer==0.12.3 +typer==0.12.4 # via # -r tests/../hacking/pr_labeler/requirements.txt # -r tests/tag.in From b56cea37cfb78c4340b79a8d65bd0de56a1eb483 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Tue, 20 Aug 2024 11:03:15 +0100 Subject: [PATCH 463/536] ci: refresh docs build dependencies (#1708) * ci: refresh docs build dependencies * ci: refresh docs build dependencies * ci: refresh docs build dependencies * ci: refresh docs build dependencies * ci: refresh docs build dependencies --------- Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 35 +++++++++++++++++----------------- tests/requirements.txt | 26 +++++++++++++------------ 2 files changed, 31 insertions(+), 30 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index ddc2e5f9528..765abaa067a 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -6,7 +6,9 @@ # aiofiles==24.1.0 # via antsibull-core -aiohttp==3.9.5 +aiohappyeyeballs==2.3.7 + # via aiohttp +aiohttp==3.10.4 # via # antsibull-core # antsibull-docs @@ -22,7 +24,7 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-changelog==0.29.0 # via antsibull-docs -antsibull-core==3.0.1 +antsibull-core==3.0.2 # via antsibull-docs antsibull-docs==2.12.0 # via -r tests/requirements-relaxed.in @@ -32,9 +34,9 @@ async-timeout==4.0.3 # via aiohttp asyncio-pool==0.6.0 # via antsibull-docs -attrs==23.2.0 +attrs==24.2.0 # via aiohttp -babel==2.15.0 +babel==2.16.0 # via # sphinx # sphinx-intl @@ -46,7 +48,7 @@ charset-normalizer==3.3.2 # via requests click==8.1.7 # via sphinx-intl -docutils==0.18.1 +docutils==0.20.1 # via # antsibull-changelog # antsibull-docs @@ -95,7 +97,7 @@ pygments==2.18.0 # sphinx pyproject-hooks==1.1.0 # via build -pyyaml==6.0.1 +pyyaml==6.0.2 # via # -r tests/requirements-relaxed.in # antsibull-changelog @@ -105,7 +107,7 @@ requests==2.32.3 # via sphinx resolvelib==1.0.1 # via -r tests/requirements-relaxed.in -rstcheck==5.0.0 +rstcheck==3.5.0 # via # -c tests/constraints-base.in # -r tests/requirements-relaxed.in @@ -120,7 +122,7 @@ six==1.16.0 # via twiggy snowballstemmer==2.2.0 # via sphinx -sphinx==7.3.7 +sphinx==7.4.7 # via # -r tests/requirements-relaxed.in # antsibull-docs @@ -136,25 +138,25 @@ sphinx-copybutton==0.5.2 # via -r tests/requirements-relaxed.in sphinx-intl==2.2.0 # via -r tests/requirements-relaxed.in -sphinx-notfound-page==1.0.2 +sphinx-notfound-page==1.0.4 # via -r tests/requirements-relaxed.in sphinx-rtd-theme==2.0.0 # via # -c tests/constraints-base.in # sphinx-ansible-theme -sphinxcontrib-applehelp==1.0.8 +sphinxcontrib-applehelp==2.0.0 # via sphinx -sphinxcontrib-devhelp==1.0.6 +sphinxcontrib-devhelp==2.0.0 # via sphinx -sphinxcontrib-htmlhelp==2.0.5 +sphinxcontrib-htmlhelp==2.1.0 # via sphinx sphinxcontrib-jquery==4.1 # via sphinx-rtd-theme sphinxcontrib-jsmath==1.0.1 # via sphinx -sphinxcontrib-qthelp==1.0.7 +sphinxcontrib-qthelp==2.0.0 # via sphinx -sphinxcontrib-serializinghtml==1.1.10 +sphinxcontrib-serializinghtml==2.0.0 # via sphinx tomli==2.0.1 # via @@ -164,18 +166,15 @@ twiggy==0.5.1 # via # antsibull-core # antsibull-docs -types-docutils==0.18.3 - # via rstcheck typing-extensions==4.12.2 # via # pydantic # pydantic-core - # rstcheck urllib3==2.2.2 # via requests yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==70.3.0 +setuptools==72.2.0 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index 21b3f754fb0..582a2d8c3cf 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -6,7 +6,9 @@ # aiofiles==24.1.0 # via antsibull-core -aiohttp==3.9.5 +aiohappyeyeballs==2.3.7 + # via aiohttp +aiohttp==3.10.4 # via # antsibull-core # antsibull-docs @@ -22,7 +24,7 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-changelog==0.29.0 # via antsibull-docs -antsibull-core==3.0.1 +antsibull-core==3.0.2 # via antsibull-docs antsibull-docs==2.11.0 # via @@ -34,9 +36,9 @@ async-timeout==4.0.3 # via aiohttp asyncio-pool==0.6.0 # via antsibull-docs -attrs==23.2.0 +attrs==24.2.0 # via aiohttp -babel==2.15.0 +babel==2.16.0 # via # sphinx # sphinx-intl @@ -97,7 +99,7 @@ pygments==2.18.0 # sphinx pyproject-hooks==1.1.0 # via build -pyyaml==6.0.1 +pyyaml==6.0.2 # via # -r tests/requirements-relaxed.in # antsibull-changelog @@ -139,25 +141,25 @@ sphinx-copybutton==0.5.2 # via -r tests/requirements-relaxed.in sphinx-intl==2.2.0 # via -r tests/requirements-relaxed.in -sphinx-notfound-page==1.0.2 +sphinx-notfound-page==1.0.4 # via -r tests/requirements-relaxed.in sphinx-rtd-theme==2.0.0 # via # -c tests/constraints-base.in # sphinx-ansible-theme -sphinxcontrib-applehelp==1.0.8 +sphinxcontrib-applehelp==2.0.0 # via sphinx -sphinxcontrib-devhelp==1.0.6 +sphinxcontrib-devhelp==2.0.0 # via sphinx -sphinxcontrib-htmlhelp==2.0.5 +sphinxcontrib-htmlhelp==2.1.0 # via sphinx sphinxcontrib-jquery==4.1 # via sphinx-rtd-theme sphinxcontrib-jsmath==1.0.1 # via sphinx -sphinxcontrib-qthelp==1.0.7 +sphinxcontrib-qthelp==2.0.0 # via sphinx -sphinxcontrib-serializinghtml==1.1.10 +sphinxcontrib-serializinghtml==2.0.0 # via sphinx tomli==2.0.1 # via build @@ -178,5 +180,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==70.3.0 +setuptools==72.2.0 # via sphinx-intl From e38e2c5cd47d0a2481a95846862a4a318d5cd2b2 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 20 Aug 2024 17:45:51 -0500 Subject: [PATCH 464/536] dev pip-compile: switch devel branch pip-compile to 3.11 (#1616) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * dev pip-compile: switch devel branch pip-compile to 3.11 This adjusts the devel branch to use Python 3.11 to generate dependencies with pip-compile. This also adjusts the pip-compile-dev workflow to run separate jobs for the stable branches, which will still use Python 3.10 for requirements files. Fixes: https://github.com/ansible/ansible-documentation/issues/1614 Fixes: https://github.com/ansible/ansible-documentation/issues/1450 * ci pip-compile-docs.yml: wrap line with `>-` Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --------- Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- .github/workflows/pip-compile-dev.yml | 59 ++++++++++++++++------ .github/workflows/pip-compile-docs.yml | 5 +- .github/workflows/reusable-pip-compile.yml | 3 +- noxfile.py | 2 +- 4 files changed, 51 insertions(+), 18 deletions(-) diff --git a/.github/workflows/pip-compile-dev.yml b/.github/workflows/pip-compile-dev.yml index 89ae8e77184..86564df9635 100644 --- a/.github/workflows/pip-compile-dev.yml +++ b/.github/workflows/pip-compile-dev.yml @@ -6,12 +6,6 @@ name: "Refresh dev dependencies" - cron: "0 0 * * 0" workflow_dispatch: inputs: - base-branch: - required: false - type: string - pr-branch: - required: false - type: string reset-branch: type: boolean default: false @@ -28,18 +22,53 @@ name: "Refresh dev dependencies" jobs: refresh: + strategy: + fail-fast: false + matrix: + include: + - base-branch: devel + pr-branch: pip-compile/devel/dev + nox-args: >- + -e 'pip-compile-3.11(formatters)' + 'pip-compile-3.11(typing)' + 'pip-compile-3.11(static)' + 'pip-compile-3.11(spelling)' + 'pip-compile-3.11(tag)' + - base-branch: stable-2.17 + pr-branch: pip-compile/stable-2.17/dev + nox-args: >- + -e 'pip-compile-3.10(formatters)' + 'pip-compile-3.10(typing)' + 'pip-compile-3.10(static)' + 'pip-compile-3.10(spelling)' + - base-branch: stable-2.16 + pr-branch: pip-compile/stable-2.16/dev + nox-args: >- + -e 'pip-compile-3.10(formatters)' + 'pip-compile-3.10(typing)' + 'pip-compile-3.10(static)' + 'pip-compile-3.10(spelling)' + - base-branch: stable-2.15 + pr-branch: pip-compile/stable-2.15/dev + nox-args: >- + -e 'pip-compile-3.10(formatters)' + 'pip-compile-3.10(typing)' + 'pip-compile-3.10(static)' + 'pip-compile-3.10(spelling)' + - base-branch: stable-2.14 + pr-branch: pip-compile/stable-2.14/dev + nox-args: >- + -e 'pip-compile-3.10(formatters)' + 'pip-compile-3.10(typing)' + 'pip-compile-3.10(static)' + 'pip-compile-3.10(spelling)' name: "Refresh dev dependencies" uses: ./.github/workflows/reusable-pip-compile.yml with: message: "ci: refresh dev dependencies" - base-branch: "${{ inputs.base-branch || 'devel' }}" - pr-branch: "${{ inputs.pr-branch || 'pip-compile/devel/dev' }}" - nox-args: >- - -e 'pip-compile-3.10(formatters)' - 'pip-compile-3.10(typing)' - 'pip-compile-3.10(static)' - 'pip-compile-3.10(spelling)' - 'pip-compile-3.10(tag)' + base-branch: "${{ matrix.base-branch }}" + pr-branch: "${{ matrix.pr-branch }}" + nox-args: "${{ matrix.nox-args }}" reset-branch: "${{ inputs.reset-branch || false }}" - labels: "${{ inputs.labels || 'backport-2.14,backport-2.15,backport-2.16,backport-2.17,tooling' }}" + labels: "${{ inputs.labels || 'no_backport,tooling' }}" secrets: inherit diff --git a/.github/workflows/pip-compile-docs.yml b/.github/workflows/pip-compile-docs.yml index 6c90c24e10c..0e183ab6615 100644 --- a/.github/workflows/pip-compile-docs.yml +++ b/.github/workflows/pip-compile-docs.yml @@ -34,7 +34,10 @@ jobs: message: "ci: refresh docs build dependencies" base-branch: "${{ inputs.base-branch || 'devel' }}" pr-branch: "${{ inputs.pr-branch || 'pip-compile/devel/docs' }}" - nox-args: "-e 'pip-compile-3.10(requirements)' 'pip-compile-3.10(requirements-relaxed)'" + nox-args: >- + -e + 'pip-compile-3.11(requirements)' + 'pip-compile-3.11(requirements-relaxed)' reset-branch: "${{ inputs.reset-branch || false }}" labels: "${{ inputs.labels || 'doc builds,no_backport' }}" secrets: inherit diff --git a/.github/workflows/reusable-pip-compile.yml b/.github/workflows/reusable-pip-compile.yml index 0fcae147eec..b96bd0353a0 100644 --- a/.github/workflows/reusable-pip-compile.yml +++ b/.github/workflows/reusable-pip-compile.yml @@ -88,6 +88,7 @@ jobs: base_branch: "${{ inputs.base-branch }}" pr_branch: "${{ inputs.pr-branch }}" message: "${{ inputs.message }}" + pr_title: "[${{ inputs.base-branch }}] ${{ inputs.message }}" changed_files: "${{ inputs.changed-files }}" labels: "${{ inputs.labels }}" run: | @@ -105,7 +106,7 @@ jobs: then command=(gh pr create --base "${base_branch}" - --title "${message}" + --title "${pr_title}" --body "" --label dependency_update ) diff --git a/noxfile.py b/noxfile.py index e685f9349e7..e04088cf694 100644 --- a/noxfile.py +++ b/noxfile.py @@ -88,7 +88,7 @@ def lint(session: nox.Session): ) -@nox.session(name="pip-compile", python=["3.10"]) +@nox.session(name="pip-compile", python=["3.11"]) @nox.parametrize(["req"], requirements_files, requirements_files) def pip_compile(session: nox.Session, req: str): # .pip-tools.toml was introduced in v7 From 84e7bb4f42289b84e2350d6fb4607f2ee100ff0c Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Tue, 20 Aug 2024 19:44:27 -0500 Subject: [PATCH 465/536] ci: refresh dev dependencies (#1770) --- tests/formatters.txt | 6 +----- tests/spelling.txt | 2 +- tests/static.txt | 2 +- tests/tag.txt | 2 +- tests/typing.txt | 6 +----- 5 files changed, 5 insertions(+), 13 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 35c12bae48f..e5214ad1e17 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.11 # by the following command: # # pip-compile --allow-unsafe --output-file=tests/formatters.txt --strip-extras tests/formatters.in @@ -18,7 +18,3 @@ pathspec==0.12.1 # via black platformdirs==4.2.2 # via black -tomli==2.0.1 - # via black -typing-extensions==4.12.2 - # via black diff --git a/tests/spelling.txt b/tests/spelling.txt index f68489fd312..9a0eb44df31 100644 --- a/tests/spelling.txt +++ b/tests/spelling.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.11 # by the following command: # # pip-compile --allow-unsafe --output-file=tests/spelling.txt --strip-extras tests/spelling.in diff --git a/tests/static.txt b/tests/static.txt index 727fbea66e8..43a8f9357c7 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.11 # by the following command: # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in diff --git a/tests/tag.txt b/tests/tag.txt index 523be2703c9..b5ce460e173 100644 --- a/tests/tag.txt +++ b/tests/tag.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.11 # by the following command: # # pip-compile --allow-unsafe --output-file=tests/tag.txt --strip-extras tests/tag.in diff --git a/tests/typing.txt b/tests/typing.txt index 01c550b5f73..6a77e36a5c2 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -1,5 +1,5 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.11 # by the following command: # # pip-compile --allow-unsafe --output-file=tests/typing.txt --strip-extras tests/typing.in @@ -72,10 +72,6 @@ shellingham==1.5.4 # via typer smmap==5.0.1 # via gitdb -tomli==2.0.1 - # via - # mypy - # nox typer==0.12.4 # via # -r tests/../hacking/pr_labeler/requirements.txt From 90766243510da5f78cb8fbf69ff409a6748e327d Mon Sep 17 00:00:00 2001 From: mabezi <92539850+mabezi@users.noreply.github.com> Date: Wed, 21 Aug 2024 11:19:46 +0200 Subject: [PATCH 466/536] add note about arguments in shebang in modules (#1718) * add note about arguments in shebang in modules * update note about arguments in shebang in modules * move notes about shebang in one warning --- docs/docsite/rst/dev_guide/developing_modules_documenting.rst | 4 +++- docs/docsite/rst/reference_appendices/faq.rst | 3 ++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index ed07df827bd..c0494161831 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -32,7 +32,9 @@ Python shebang & UTF-8 coding Begin your Ansible module with ``#!/usr/bin/python`` - this "shebang" allows ``ansible_python_interpreter`` to work. Follow the shebang immediately with ``# -*- coding: utf-8 -*-`` to clarify that the file is UTF-8 encoded. -.. note:: Using ``#!/usr/bin/env``, makes ``env`` the interpreter and bypasses ``ansible__interpreter`` logic. +.. warning:: + - Using ``#!/usr/bin/env`` makes ``env`` the interpreter and bypasses ``ansible__interpreter`` logic. + - Passing arguments to the interpreter in the shebang does not work (for example, ``#!/usr/bin/env python``) . .. note:: If you develop the module using a different scripting language, adjust the interpreter accordingly (``#!/usr/bin/``) so ``ansible__interpreter`` can work for that specific language. .. note:: Binary modules do not require a shebang or an interpreter. diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index e0531da6c14..2e36ea8a012 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -182,7 +182,8 @@ Also, this works for ANY interpreter, for example ruby: ``ansible_ruby_interpret so you can use this for custom modules written in any scripting language and control the interpreter location. Keep in mind that if you put ``env`` in your module shebang line (``#!/usr/bin/env ``), -this facility will be ignored so you will be at the mercy of the remote `$PATH`. +this won't work and will be evaluated as one string (including the space between ``env`` and ```` space). +Arguments are neither intended nor supported. .. _installation_faqs: From 398ec70fa1d5ef61f0ff0766bb79319fb140a527 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Wed, 21 Aug 2024 10:21:18 +0100 Subject: [PATCH 467/536] ci: refresh docs build dependencies (#1771) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 14 ++++---------- tests/requirements.txt | 12 ++++-------- 2 files changed, 8 insertions(+), 18 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 765abaa067a..53f02460a5a 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -1,14 +1,14 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.11 # by the following command: # # pip-compile --allow-unsafe --output-file=tests/requirements-relaxed.txt --strip-extras tests/requirements-relaxed.in # aiofiles==24.1.0 # via antsibull-core -aiohappyeyeballs==2.3.7 +aiohappyeyeballs==2.4.0 # via aiohttp -aiohttp==3.10.4 +aiohttp==3.10.5 # via # antsibull-core # antsibull-docs @@ -30,8 +30,6 @@ antsibull-docs==2.12.0 # via -r tests/requirements-relaxed.in antsibull-docs-parser==1.0.2 # via antsibull-docs -async-timeout==4.0.3 - # via aiohttp asyncio-pool==0.6.0 # via antsibull-docs attrs==24.2.0 @@ -158,10 +156,6 @@ sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 # via sphinx -tomli==2.0.1 - # via - # build - # sphinx twiggy==0.5.1 # via # antsibull-core @@ -176,5 +170,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==72.2.0 +setuptools==73.0.1 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index 582a2d8c3cf..43d2b048076 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -1,14 +1,14 @@ # -# This file is autogenerated by pip-compile with Python 3.10 +# This file is autogenerated by pip-compile with Python 3.11 # by the following command: # # pip-compile --allow-unsafe --output-file=tests/requirements.txt --strip-extras tests/requirements.in # aiofiles==24.1.0 # via antsibull-core -aiohappyeyeballs==2.3.7 +aiohappyeyeballs==2.4.0 # via aiohttp -aiohttp==3.10.4 +aiohttp==3.10.5 # via # antsibull-core # antsibull-docs @@ -32,8 +32,6 @@ antsibull-docs==2.11.0 # -r tests/requirements-relaxed.in antsibull-docs-parser==1.0.2 # via antsibull-docs -async-timeout==4.0.3 - # via aiohttp asyncio-pool==0.6.0 # via antsibull-docs attrs==24.2.0 @@ -161,8 +159,6 @@ sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 # via sphinx -tomli==2.0.1 - # via build twiggy==0.5.1 # via # antsibull-core @@ -180,5 +176,5 @@ yarl==1.9.4 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==72.2.0 +setuptools==73.0.1 # via sphinx-intl From 0d35022030782009ec24228cf3124f049776e80e Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 21 Aug 2024 04:32:05 -0500 Subject: [PATCH 468/536] ci: ensure ansible-core files exist before running docs build (#1756) Also, make KEEP_DIRS and KEEP_FILES constants to make the main function cleaner. Fixes: https://github.com/ansible/ansible-documentation/issues/1056 --- docs/bin/clone-core.py | 45 +++++++++++++++++++++++++++++------------- noxfile.py | 9 +++++++++ 2 files changed, 40 insertions(+), 14 deletions(-) diff --git a/docs/bin/clone-core.py b/docs/bin/clone-core.py index e0ea91f6eab..9df817f8929 100755 --- a/docs/bin/clone-core.py +++ b/docs/bin/clone-core.py @@ -18,11 +18,25 @@ DEFAULT_BRANCH = (ROOT / "docs" / "ansible-core-branch.txt").read_text().strip() DEFAULT_ANSIBLE_CORE_REPO = "https://github.com/ansible/ansible" +KEEP_DIRS = ( + "bin", + "lib", + "packaging", + "test/lib", +) + +KEEP_FILES = ( + "MANIFEST.in", + "pyproject.toml", + "requirements.txt", +) + @dataclasses.dataclass() class Args: branch: str | None repo: str + check: bool def parse_args(args: list[str] | None = None) -> Args: @@ -47,22 +61,25 @@ def parse_args(args: list[str] | None = None) -> Args: help="ansible-core repository to check out. Default: %(default)s", default=DEFAULT_ANSIBLE_CORE_REPO, ) + parser.add_argument( + "--check", + action=argparse.BooleanOptionalAction, + help="Ensure that the necessary files exist." + " If they don't clone new ones from ansible-core." + " Otherwise, leave the existing versions alone.", + ) return Args(**vars(parser.parse_args(args))) def main(args: Args) -> None: - keep_dirs = [ - "bin", - "lib", - "packaging", - "test/lib", - ] - - keep_files = [ - "MANIFEST.in", - "pyproject.toml", - "requirements.txt", - ] + if ( + args.check + and all(pathlib.Path(file).is_file() for file in KEEP_FILES) + and all(pathlib.Path(directory).is_dir() for directory in KEEP_DIRS) + ): + print("The necessary core files already exist.") + print("Run 'nox -e clone-core' without --check to update the core files.") + return with tempfile.TemporaryDirectory() as temp_dir: cmd: list[str] = ["git", "clone", args.repo, "--depth=1"] @@ -71,7 +88,7 @@ def main(args: Args) -> None: cmd.append(temp_dir) subprocess.run(cmd, check=True) - for keep_dir in keep_dirs: + for keep_dir in KEEP_DIRS: src = pathlib.Path(temp_dir, keep_dir) dst = pathlib.Path.cwd() / keep_dir @@ -84,7 +101,7 @@ def main(args: Args) -> None: (dst / ".gitignore").write_text("*") - for keep_file in keep_files: + for keep_file in KEEP_FILES: src = pathlib.Path(temp_dir, keep_file) dst = pathlib.Path.cwd() / keep_file diff --git a/noxfile.py b/noxfile.py index e04088cf694..b40bebb6047 100644 --- a/noxfile.py +++ b/noxfile.py @@ -125,6 +125,13 @@ def clone_core(session: nox.Session): ] +def _clone_core_check(session: nox.Session) -> None: + """ + Helper function to run the clone-core script with "--check" + """ + session.run("python", "docs/bin/clone-core.py", "--check") + + def _relaxed_parser(session: nox.Session) -> ArgumentParser: """ Generate an argument parser with a --relaxed option. @@ -159,6 +166,7 @@ def checkers(session: nox.Session, test: str): args = _relaxed_parser(session).parse_args(session.posargs) install(session, req="requirements-relaxed" if args.relaxed else "requirements") + _clone_core_check(session) session.run("make", "-C", "docs/docsite", "clean", external=True) session.run("python", "tests/checkers.py", test) @@ -175,6 +183,7 @@ def make(session: nox.Session): args = parser.parse_args(session.posargs) install(session, req="requirements-relaxed" if args.relaxed else "requirements") + _clone_core_check(session) make_args: list[str] = [ f"PYTHON={_env_python(session)}", *(args.make_args or ("clean", "coredocs")), From 66e5ebeb7eb900f0d8dd7df1e93eef9ab24b2fe3 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Wed, 21 Aug 2024 17:13:18 +0200 Subject: [PATCH 469/536] Ansible 11 roadmap (#1729) * Ansible 11 roadmap * Fix 11.1.0 release date Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- docs/docsite/rst/roadmap/COLLECTIONS_11.rst | 88 +++++++++++++++++++ .../rst/roadmap/ansible_roadmap_index.rst | 1 + 2 files changed, 89 insertions(+) create mode 100644 docs/docsite/rst/roadmap/COLLECTIONS_11.rst diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_11.rst b/docs/docsite/rst/roadmap/COLLECTIONS_11.rst new file mode 100644 index 00000000000..809454bd721 --- /dev/null +++ b/docs/docsite/rst/roadmap/COLLECTIONS_11.rst @@ -0,0 +1,88 @@ +.. + THIS DOCUMENT IS OWNED BY THE ANSIBLE COMMUNITY STEERING COMMITTEE. ALL CHANGES MUST BE APPROVED BY THE STEERING COMMITTEE! + For small changes (fixing typos, language errors, etc.) create a PR and ping @ansible/steering-committee. + For other changes, create a discussion as described in https://github.com/ansible-community/community-topics/blob/main/community_topics_workflow.md#creating-a-topic + to discuss the changes. + (Creating a draft PR for this file and mentioning it in the community topic is also OK.) + +.. _ansible_11_roadmap: + +==================== +Ansible project 11.0 +==================== + +This release schedule includes dates for the `ansible `_ package, with a few dates for the `ansible-core `_ package as well. All dates are subject to change. See the `ansible-core 2.18 Roadmap `_ for the most recent updates on ``ansible-core``. + +.. contents:: + :local: + + +Release schedule +================= + + +:2024-09-16: ansible-core feature freeze, stable-2.18 branch created. +:2024-09-23: Start of ansible-core 2.18 betas +:2024-09-24: Ansible-11.0.0 alpha1 [1]_ +:2024-10-14: First ansible-core 2.18 release candidate. +:2024-10-15: Ansible-11.0.0 alpha2 [1]_ +:2024-11-04: Ansible-core-2.18.0 released. +:2024-11-04: Last day for collections to make backwards incompatible releases that will be accepted into Ansible-11. This includes adding new collections to Ansible 11.0.0; from now on new collections have to wait for 11.1.0 or later. +:2024-11-05: Ansible-11.0.0 beta1 -- feature freeze [2]_ (weekly beta releases; collection owners and interested users should test for bugs). +:2024-11-12: Ansible-11.0.0 rc1 [3]_ [4]_ (weekly release candidates as needed; test and alert us to any blocker bugs). Blocker bugs will slip release. +:2024-11-15: Last day to trigger an Ansible-11.0.0rc2 release because of major defects in Ansible-11.0.0rc1. +:2024-11-19: Ansible-11.0.0rc2 when necessary, otherwise Ansible-11.0.0 release. +:2024-11-26: Ansible-11.0.0 release when Ansible-11.0.0rc2 was necessary. +:2024-11-19 or 2023-11-26: Create the ansible-build-data directory and files for Ansible-11. +:2024-12-02: Release of ansible-core 2.18.1. +:2024-12-03: Release of Ansible-11.1.0 (bugfix + compatible features: every four weeks.) + +.. [1] In case there are any additional ansible-core beta releases or release candidates, we will try to do another Ansible-11.0.0 alpha release. This might mean that we will release Ansible-11.0.0 alpha2 earlier (and release Ansible-11.0.0 alpha3 or later on 2024-10-15) and / or release one or more additional alpha after 2024-10-15. + +.. [2] No new modules or major features accepted after this date. In practice, this means we will freeze the semver collection versions to compatible release versions. For example, if the version of community.crypto on this date was community.crypto 2.3.0; Ansible-11.0.0 could ship with community.crypto 2.3.1. It would not ship with community.crypto 2.4.0. + +.. [3] After this date only changes blocking a release are accepted. Accepted changes require creating a new release candidate and may slip the final release date. + +.. [4] Collections will be updated to a new version only if a blocker is approved. Collection owners should discuss any blockers at a community meeting (before this freeze) to decide whether to bump the version of the collection for a fix. See the `creating an Ansible Community Topic workflow `_. + +.. note:: + + Breaking changes will be introduced in Ansible 11.0.0. We encourage the use of deprecation periods that give advance notice of breaking changes at least one Ansible release before they are introduced. However, deprecation notices are not guaranteed to take place. + +.. note:: + + In general, it is in the discretion of the release manager to delay a release by 1-2 days for reasons such as personal (schedule) problems, technical problems (CI/infrastructure breakdown), and so on. + However, in case two releases are planned for the same day, a release of the latest stable version takes precedence. This means that if a stable Ansible 11 release collides with a pre-release of Ansible 12, the latter will be delayed. + If a Ansible 11 release collides with a stable Ansible 12 release, including 12.0.0, the Ansible 11 release will be delayed. + + +Planned major changes +===================== + +- The inspur.sm collection will be removed as it is unmaintained (https://github.com/ansible-community/ansible-build-data/issues/424). +- The netapp.storagegrid collection will be removed as it is unmaintained (https://github.com/ansible-community/ansible-build-data/issues/434). +- The frr.frr collection will be removed as it is unmaintained (https://github.com/ansible-community/ansible-build-data/issues/437). +- The openvswitch.openvswitch collection will be removed as it is unmaintained (https://github.com/ansible-community/ansible-build-data/issues/437). + +You can install removed collections manually with ``ansible-galaxy collection install ``. + + +Ansible minor releases +======================= + +Ansible 11.x follows ansible-core-2.18.x releases, so releases will occur approximately every four weeks. If ansible-core delays a release for whatever reason, the next Ansible 11.x minor release will be delayed accordingly. + +Ansible 11.x minor releases may contain new features (including new collections) but not backwards incompatibilities. In practice, this means we will include new collection versions where either the patch or the minor version number has changed but not when the major number has changed. For example, if Ansible-11.0.0 ships with community.crypto 2.3.0, Ansible-11.1.0 could ship with community.crypto 2.4.0 but not community.crypto 3.0.0. + + +.. note:: + + Minor and patch releases will stop when Ansible-12 is released. See the :ref:`Release and Maintenance Page ` for more information. + +.. note:: + + We will not provide bugfixes or security fixes for collections that do not + provide updates for their major release cycle included in Ansible 11. + + +For more information, reach out on a mailing list or a chat channel - see :ref:`communication` for more details. diff --git a/docs/docsite/rst/roadmap/ansible_roadmap_index.rst b/docs/docsite/rst/roadmap/ansible_roadmap_index.rst index b09d5babd54..060fc4b1175 100644 --- a/docs/docsite/rst/roadmap/ansible_roadmap_index.rst +++ b/docs/docsite/rst/roadmap/ansible_roadmap_index.rst @@ -24,6 +24,7 @@ See :ref:`Ansible communication channels ` for details on how to :glob: :caption: Ansible Release Roadmaps + COLLECTIONS_11 COLLECTIONS_10 COLLECTIONS_9 COLLECTIONS_8 From 6f8f25f7d12d03ebd477beb87c014b491029541a Mon Sep 17 00:00:00 2001 From: Akira Yokochi Date: Thu, 22 Aug 2024 00:48:51 +0900 Subject: [PATCH 470/536] fix indents network documents (#1776) --- .../getting_started/network_connection_options.rst | 4 ++-- docs/docsite/rst/network/user_guide/platform_nxos.rst | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/network/getting_started/network_connection_options.rst b/docs/docsite/rst/network/getting_started/network_connection_options.rst index bdfb93cb97b..a7aba656373 100644 --- a/docs/docsite/rst/network/getting_started/network_connection_options.rst +++ b/docs/docsite/rst/network/getting_started/network_connection_options.rst @@ -29,8 +29,8 @@ Using vars (per task): - name: save running-config cisco.ios.ios_command: commands: copy running-config startup-config - vars: - ansible_command_timeout: 30 + vars: + ansible_command_timeout: 30 Using the environment variable: diff --git a/docs/docsite/rst/network/user_guide/platform_nxos.rst b/docs/docsite/rst/network/user_guide/platform_nxos.rst index de461aea300..78cee682768 100644 --- a/docs/docsite/rst/network/user_guide/platform_nxos.rst +++ b/docs/docsite/rst/network/user_guide/platform_nxos.rst @@ -87,10 +87,10 @@ Before you can use NX-API to connect to a switch, you must enable NX-API. To ena .. code-block:: yaml - name: Enable NX-API - cisco.nxos.nxos_nxapi: - enable_http: yes - enable_https: yes - when: ansible_network_os == 'cisco.nxos.nxos' + cisco.nxos.nxos_nxapi: + enable_http: yes + enable_https: yes + when: ansible_network_os == 'cisco.nxos.nxos' To find out more about the options for enabling HTTP/HTTPS and local http see the :ref:`nxos_nxapi ` module documentation. From bb6f114d086cb2221e4599a509193154a7165e88 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 22 Aug 2024 10:09:25 +0200 Subject: [PATCH 471/536] Fix links in collection requirements. (#1785) --- .../collection_contributors/collection_requirements.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 41b70ee0362..92e140a19a0 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -176,7 +176,7 @@ galaxy.yml ---------- * The ``tags`` field MUST be set. -* Collection dependencies MUST meet a set of rules. See the section on `Collection Dependencies ` for details. +* Collection dependencies MUST meet a set of rules. See the section on :ref:`Collection Dependencies ` for details. * 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. @@ -201,7 +201,7 @@ meta/execution-environment.yml If a collection has controller-side Python package and/or system package requirements, to allow easy `execution environment `_ building, they SHOULD be listed in corresponding files under the ``meta`` directory, specified in ``meta/execution-environment.yml``, and `verified `_. -See the `Collection-level dependencies guide `_ for more information and `collection_template/meta ` directory content as an example. +See the `Collection-level dependencies guide `_ for more information and `collection_template/meta `_ directory content as an example. Modules & Plugins ------------------ From a8226b1bddfc7b50a78d9d33158dac0da7848ae6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9E=97=E5=8D=9A=E4=BB=81=20Buo-ren=20Lin?= Date: Sun, 25 Aug 2024 23:55:39 +0800 Subject: [PATCH 472/536] Fix broken list markup in the "Installing collections" documentation. (#1798) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 林博仁(Buo-ren Lin) --- docs/docsite/rst/collections_guide/collections_installing.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docsite/rst/collections_guide/collections_installing.rst b/docs/docsite/rst/collections_guide/collections_installing.rst index 313f754e5aa..12f6e67f4b8 100644 --- a/docs/docsite/rst/collections_guide/collections_installing.rst +++ b/docs/docsite/rst/collections_guide/collections_installing.rst @@ -177,6 +177,7 @@ Installing collections adjacent to playbooks You can install collections locally next to your playbooks inside your project instead of in a global location on your system or on AWX. Using locally installed collections adjacent to playbooks has some benefits, such as: + * Ensuring that all users of the project use the same collection version. * Using self-contained projects makes it easy to move across different environments. Increased portability also reduces overhead when setting up new environments. This is a benefit when deploying Ansible playbooks in cloud environments. * Managing collections locally lets you version them along with your playbooks. From b0315c3637cc7b97ad93a2a51c237a0f1ad91d7b Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 26 Aug 2024 12:04:00 +0200 Subject: [PATCH 473/536] Bump antsibull-docs and antsibull-docs-parser versions (#1799) * Bump antsibull-docs and antsibull-docs-parser versions. * Bump to 2.13.1. --- tests/constraints.in | 2 +- tests/requirements-relaxed.txt | 6 +++--- tests/requirements.txt | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/tests/constraints.in b/tests/constraints.in index 8758dbd321d..ae6a6e8107c 100644 --- a/tests/constraints.in +++ b/tests/constraints.in @@ -2,4 +2,4 @@ # and antsibull-docs that production builds rely upon. sphinx == 7.2.5 -antsibull-docs == 2.11.0 # currently approved version +antsibull-docs == 2.13.1 # currently approved version diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 53f02460a5a..34f05885479 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -26,9 +26,9 @@ antsibull-changelog==0.29.0 # via antsibull-docs antsibull-core==3.0.2 # via antsibull-docs -antsibull-docs==2.12.0 +antsibull-docs==2.13.1 # via -r tests/requirements-relaxed.in -antsibull-docs-parser==1.0.2 +antsibull-docs-parser==1.1.0 # via antsibull-docs asyncio-pool==0.6.0 # via antsibull-docs @@ -57,7 +57,7 @@ frozenlist==1.4.1 # via # aiohttp # aiosignal -idna==3.7 +idna==3.8 # via # requests # yarl diff --git a/tests/requirements.txt b/tests/requirements.txt index 43d2b048076..618b25bf35c 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -26,11 +26,11 @@ antsibull-changelog==0.29.0 # via antsibull-docs antsibull-core==3.0.2 # via antsibull-docs -antsibull-docs==2.11.0 +antsibull-docs==2.13.1 # via # -c tests/constraints.in # -r tests/requirements-relaxed.in -antsibull-docs-parser==1.0.2 +antsibull-docs-parser==1.1.0 # via antsibull-docs asyncio-pool==0.6.0 # via antsibull-docs @@ -59,7 +59,7 @@ frozenlist==1.4.1 # via # aiohttp # aiosignal -idna==3.7 +idna==3.8 # via # requests # yarl From 653d2b601a058afaba0f7ef7ee60ebc4ab3e8854 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 26 Aug 2024 11:18:33 +0100 Subject: [PATCH 474/536] [devel] ci: refresh dev dependencies (#1794) * ci: refresh dev dependencies * ci: refresh dev dependencies --------- Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/static.txt | 2 +- tests/tag.txt | 2 +- tests/typing.txt | 8 ++++---- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index 43a8f9357c7..ae11c97abf2 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.6.1 +ruff==0.6.2 # via -r tests/static.in diff --git a/tests/tag.txt b/tests/tag.txt index b5ce460e173..c15394ae390 100644 --- a/tests/tag.txt +++ b/tests/tag.txt @@ -24,7 +24,7 @@ shellingham==1.5.4 # via typer smmap==5.0.1 # via gitdb -typer==0.12.4 +typer==0.12.5 # via -r tests/tag.in typing-extensions==4.12.2 # via typer diff --git a/tests/typing.txt b/tests/typing.txt index 6a77e36a5c2..8c018c8c706 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -32,7 +32,7 @@ gitdb==4.0.11 # via gitpython gitpython==3.1.43 # via -r tests/tag.in -idna==3.7 +idna==3.8 # via requests jinja2==3.1.4 # via -r tests/../hacking/pr_labeler/requirements.txt @@ -42,7 +42,7 @@ markupsafe==2.1.5 # via jinja2 mdurl==0.1.2 # via markdown-it-py -mypy==1.11.1 +mypy==1.11.2 # via -r tests/typing.in mypy-extensions==1.0.0 # via mypy @@ -56,7 +56,7 @@ platformdirs==4.2.2 # via virtualenv pycparser==2.22 # via cffi -pygithub==2.3.0 +pygithub==2.4.0 # via -r tests/../hacking/pr_labeler/requirements.txt pygments==2.18.0 # via rich @@ -72,7 +72,7 @@ shellingham==1.5.4 # via typer smmap==5.0.1 # via gitdb -typer==0.12.4 +typer==0.12.5 # via # -r tests/../hacking/pr_labeler/requirements.txt # -r tests/tag.in From 4efd295360d20c21f942029123c94b8d09377b9f Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 26 Aug 2024 11:20:16 +0100 Subject: [PATCH 475/536] ci: refresh docs build dependencies (#1797) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> From 6c48f78850de8dd8ad956a70cb601940e304e13e Mon Sep 17 00:00:00 2001 From: Lyle McKarns Date: Mon, 26 Aug 2024 09:30:34 -0400 Subject: [PATCH 476/536] Issue1682_nightly_build_default_values (#1727) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * WIP * setting in-line defaults for running on a schedule * ci: refresh dev dependencies (#1634) Remove latest symlink from publishing workflow (#1615) * remove latest symlink Read The Docs allows you to configure which version corresponds to "latest" which means the symlink is no longer necessary. * add 11 to version list Co-authored-by: Sandra McCann <30267855+samccann@users.noreply.github.com> ci: refresh docs build dependencies (#1635) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> fix Validate data against set criteria with Ansible doc (#1636) fixed following example playbook fix Ansible architecture docs (#1637) I fixed example Inventory ini format file contains '---' used in Yaml Integrate the `alls-green` action into the main GHA CI workflow (#1639) * Integrating all-greens into ci.yml * removing non-existing references When rebuilding this work after repo cleanup, I missed removing these. Thanks for catching that. Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) * Update .github/workflows/ci.yaml --------- Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) Co-authored-by: Don Naro Remove reference of scp_if_ssh option (#1346) * Remove reference of scp_if_ssh option * scp_if_ssh is removed in Ansible 2.17, remove the references Fixes: #1341 Signed-off-by: Abhijeet Kasurde * review changes Co-authored-by: Maxwell G * details about the smart setting --------- Signed-off-by: Abhijeet Kasurde Co-authored-by: Maxwell G Co-authored-by: Don Naro Remove references to archived ansible/ansible-examples repository (#1653) docs/docsite/rst/dev_guide/developing_program_flow_modules.rst: avoid using aliases (#1539) * docs/docsite/rst/dev_guide/developing_program_flow_modules.rst: don't use aliases * Update docs/docsite/rst/dev_guide/developing_program_flow_modules.rst Co-authored-by: Sandra McCann * Update docs/docsite/rst/dev_guide/developing_program_flow_modules.rst Co-authored-by: flowerysong --------- Co-authored-by: Sandra McCann Co-authored-by: flowerysong [WIP, needs vote before merging] collection_requirements.rst: update (#1422) * collection_requirements.rst: update * general updates * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com> * releasing policy MUST -> SHOULD * Remove setting upper bound warning * fix formatting * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Sandra McCann * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Sandra McCann * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Remove the Requirements for collections to be included in the Ansible Package section * Update galaxy section * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Remove extra line * Update Documentation requirements section * CoC feedback incorporate * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein * Fix unnoticed conflict * Reformulate changelog section * Restructure Contributor Workflow section * Fix typo * Add sentence back * Restructure section * Handle Naming section * Handle Licensing section * Restructure Licensing section * Fix typo * Update repo management section * Update branch name and protection section * Undate CI testing section * Update When moving modules between collections section * Update Development conventions section * Update Collection dependencies section * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Restructure backwards compatibility section * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> * Fix formatting| * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Felix Fontein --------- Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com> Co-authored-by: Sandra McCann Co-authored-by: Don Naro Co-authored-by: Felix Fontein Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> communication guide: overhaul (#1667) communication guide: overhaul * Forum as default * Reorder so important information is at the top * remove old information --------- Co-authored-by: Don Naro Co-authored-by: John Barker Co-authored-by: Sandra McCann ci: refresh dev dependencies (#1657) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> ci: refresh docs build dependencies (#1658) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Output workflow parameters for approval details (#1650) * Output workflow parameters for approval details --------- Co-authored-by: Don Naro ci: refresh dev dependencies (#1675) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> ci: refresh docs build dependencies (#1676) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Nightly builds for package docs publishing workflow (#1663) Adding daily schedule to CI build (#1659) * Adding daily schedule to CI build * Change from 0 minute to 23, per discussion and referenced suggestion. remove the schedule from the workflow dispatch job (#1683) Relates to issue #1682. This change removes the schedule to stop the workflow from failing due to null input values. We can either add this back with some expressions to set defaults for scheduled runs or create a simplified build workflow that runs on a schedule. notify docs matrix channel on docs build failures (#1651) * notify docs matrix channel on docs build failures * add url with run id Remove language option from workflow (#1681) * Remove deprecated language input from the publishing workflow collection_requirements: fix typo (#1684) * collection_requirements: fix typo * Update docs/docsite/rst/community/collection_contributors/collection_requirements.rst Co-authored-by: Don Naro --------- Co-authored-by: Don Naro WIP restore anchor in communication guide (#1692) Add porting guide for Ansible 10.2.0. (#1697) Add porting guide for Ansible 9.8.0. (#1698) Move community_topics_workflow to docs.ansible.com (#1028) * Move community_topics_workflow to docs.ansible.com * Simplify * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Mario Lenz * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Mario Lenz * Improve * Replacing Creating a topic section content * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro * Clarify * Update docs/docsite/rst/community/steering/community_topics_workflow.rst Co-authored-by: Don Naro --------- Co-authored-by: Mario Lenz Co-authored-by: Don Naro ci: refresh docs build dependencies (#1691) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Issue #1633 nox session for tagging (#1649) * WIP tagger session for nox * First pass tagging nox session * Formatting fixup * Adding removal of tmpdir as per discussion * tag session checks for, and uses, existing ansible checkout if it exists, removes tmpdir if it created one. * isort fixup * Working out suggested changes. * Linting cleanup on changes * Different approach to noted chagnes * Reducing tagging session to a bare bones wrapper around the script, leaving all repo management alone * Staging deletion per discussion * Adding tag session to dependency update job * after removing hacking/tagger/requirements.txt moved "gitpython" here for the typing test session requiremnts. * Adding that here didd not accomplish what I'd expected. Removing it and revisiting how to do that. * I think this is where the call needed added to get the tags dependencies automatically updated * remove gitpython, add tag.txt, add blank line * Comment cleanup per OraNod * doc README: document nox tag session instead of manual mode * Update tests/typing.in Per suggestion from @webnjaz Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --------- Co-authored-by: Maxwell G Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) ci: refresh dev dependencies (#1707) * ci: refresh dev dependencies * ci: refresh dev dependencies --------- Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Be more explicit about registering with a loop (#1709) add vault password file example (#1696) * add vault password file example * remove duplicate word in vault password file example Co-authored-by: Sandra McCann --------- Co-authored-by: Sandra McCann ci: refresh dev dependencies (#1722) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> setting in-line defaults for running on a schedule * Implementing comments --------- Co-authored-by: ansible-documentation-bot[bot] <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- .github/workflows/build-package-docs.yaml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 0543abe548f..0298b878161 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -40,8 +40,7 @@ on: - test env: - PACKAGE_VERSION: ${{ github.event.inputs.ansible-package-version }} - LANGUAGE: ${{ github.event.inputs.language }} + PACKAGE_VERSION: ${{ github.event.inputs.ansible-package-version || 'devel' }} jobs: build-package-docs: @@ -52,11 +51,11 @@ jobs: with: repository: >- ${{ - github.event.inputs.repository-owner + github.event.inputs.repository-owner || 'ansible' }}/${{ - github.event.inputs.repository-name + github.event.inputs.repository-name || 'ansible-documentation' }} - ref: ${{ github.event.inputs.repository-branch }} + ref: ${{ github.event.inputs.repository-branch || 'devel' }} path: build-directory - name: Setup nox From a74da7db4154a5c5fe815702c9caa2ab3594b911 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Mon, 26 Aug 2024 10:48:45 -0500 Subject: [PATCH 477/536] nox: support nox uv backend (#1757) Nox now has a separate venv backend that uses the Rust-based pip replacement, uv. Let's add support for this to our install function so that the constraints are respected when using the uv backend. --- noxfile.py | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/noxfile.py b/noxfile.py index b40bebb6047..2f1bc3e5a5c 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1,6 +1,7 @@ from __future__ import annotations import os +import shlex from argparse import ArgumentParser, BooleanOptionalAction from glob import iglob from pathlib import Path @@ -18,11 +19,29 @@ nox.options.sessions = ("clone-core", "lint", "checkers", "make") +def _set_env_verbose(session: nox.Session, **env: str) -> dict[str, str]: + """ + Helper function to verbosely set environment variables + """ + final_env: dict[str, str] = {} + for key, value in env.items(): + final_env[key] = value + session.log(f"export {key}={shlex.quote(value)}") + return final_env + + def install(session: nox.Session, *args, req: str, **kwargs): if PINNED: pip_constraint = f"tests/{req}.txt" - kwargs.setdefault("env", {})["PIP_CONSTRAINT"] = pip_constraint - session.log(f"export PIP_CONSTRAINT={pip_constraint!r}") + # Set constraint environment variables for both pip and uv to support + # the nox uv backend + env = _set_env_verbose( + session, + PIP_CONSTRAINT=pip_constraint, + UV_CONSTRAINT=pip_constraint, + UV_BUILD_CONSTRAINT=pip_constraint, + ) + kwargs.setdefault("env", {}).update(env) session.install("-r", f"tests/{req}.in", *args, **kwargs) From 1e16923a7eef5cb9756151fa3715f54fd3a3cedd Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Mon, 26 Aug 2024 11:16:29 -0500 Subject: [PATCH 478/536] steering_committee_membership: fix rst link syntax error (#1805) --- .../rst/community/steering/steering_committee_membership.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/steering/steering_committee_membership.rst b/docs/docsite/rst/community/steering/steering_committee_membership.rst index 0825a728dda..511dcc869df 100644 --- a/docs/docsite/rst/community/steering/steering_committee_membership.rst +++ b/docs/docsite/rst/community/steering/steering_committee_membership.rst @@ -46,7 +46,7 @@ Team membership The Committee can accept a team to be a member. In this case, the team chooses its representative and announces the person in a dedicated `Community Topic `_. -After the announcement is made, the new representative is added to the `SteeringCommittee ` group on the forum, and the previous representative is removed from that group. +After the announcement is made, the new representative is added to the `SteeringCommittee `_ group on the forum, and the previous representative is removed from that group. The team uses the same Community Topic for announcing subsequent representative changes. Representatives should commit to at least two months of membership. From 646f35e3dc61281d71b2b735c373eb155e13a0f2 Mon Sep 17 00:00:00 2001 From: Martin Krizek Date: Wed, 28 Aug 2024 17:44:34 +0200 Subject: [PATCH 479/536] Clarify any_errors_fatal behavior change in 2.17 porting guide (#1815) * Clarify any_errors_fatal behavior change in 2.17 porting guide * Update docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst b/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst index e44496a0c2c..c7550d0372d 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_core_2.17.rst @@ -44,6 +44,10 @@ Playbook assert: that: '"hi mom" is in untrusted_result.stdout' +* ``any_errors_fatal`` - when a task in a block with a ``rescue`` section + fails on a host, the ``rescue`` section is executed on all hosts. This + occurs because ``any_errors_fatal`` automatically fails all hosts. + Command Line ============ From 5adb400dc2bad809f70fe1c1764b8665280c7faa Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Thu, 29 Aug 2024 02:38:42 -0500 Subject: [PATCH 480/536] steering_committee_membership: clarify guidelines about team representatives (#1806) Based on general discussions we've been having over the past year about inactive steering committee members, I figured we should clarify the team representative section that we recently added (for Core and potentially other teams in the future). --- .../rst/community/steering/steering_committee_membership.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/docsite/rst/community/steering/steering_committee_membership.rst b/docs/docsite/rst/community/steering/steering_committee_membership.rst index 511dcc869df..9c648cc85ab 100644 --- a/docs/docsite/rst/community/steering/steering_committee_membership.rst +++ b/docs/docsite/rst/community/steering/steering_committee_membership.rst @@ -50,6 +50,10 @@ After the announcement is made, the new representative is added to the `Steering The team uses the same Community Topic for announcing subsequent representative changes. Representatives should commit to at least two months of membership. +The team representative must still abide by all expectations listed in :ref:`steering_expectations`, including those surrounding participation. +Steering Committee members are generally expected to participate in discussions — asynchronously on the forum and/or synchronously in meetings — and votes, +even if the issue in question does not entirely pertain to the team they represent. + Process ^^^^^^^^ From b2d68c9c951a8a4672e75c32c22d7f77bc0fca6b Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 2 Sep 2024 16:36:05 +0100 Subject: [PATCH 481/536] ci: refresh docs build dependencies (#1827) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 6 +++--- tests/requirements.txt | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 34f05885479..97c262ad240 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -40,7 +40,7 @@ babel==2.16.0 # sphinx-intl build==1.2.1 # via antsibull-core -certifi==2024.7.4 +certifi==2024.8.30 # via requests charset-normalizer==3.3.2 # via requests @@ -166,9 +166,9 @@ typing-extensions==4.12.2 # pydantic-core urllib3==2.2.2 # via requests -yarl==1.9.4 +yarl==1.9.6 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==73.0.1 +setuptools==74.0.0 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index 618b25bf35c..fdb45ed55c6 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -42,7 +42,7 @@ babel==2.16.0 # sphinx-intl build==1.2.1 # via antsibull-core -certifi==2024.7.4 +certifi==2024.8.30 # via requests charset-normalizer==3.3.2 # via requests @@ -172,9 +172,9 @@ typing-extensions==4.12.2 # rstcheck urllib3==2.2.2 # via requests -yarl==1.9.4 +yarl==1.9.6 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==73.0.1 +setuptools==74.0.0 # via sphinx-intl From d38b6000c7bed9d8f429898439a50f6f5001352d Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 2 Sep 2024 16:37:05 +0100 Subject: [PATCH 482/536] ci: refresh dev dependencies (#1826) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/static.txt | 2 +- tests/tag.txt | 2 +- tests/typing.txt | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/static.txt b/tests/static.txt index ae11c97abf2..fe84e6a4983 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.6.2 +ruff==0.6.3 # via -r tests/static.in diff --git a/tests/tag.txt b/tests/tag.txt index c15394ae390..e57ef431d82 100644 --- a/tests/tag.txt +++ b/tests/tag.txt @@ -18,7 +18,7 @@ packaging==24.1 # via -r tests/tag.in pygments==2.18.0 # via rich -rich==13.7.1 +rich==13.8.0 # via typer shellingham==1.5.4 # via typer diff --git a/tests/typing.txt b/tests/typing.txt index 8c018c8c706..d28bba5f5ae 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -6,7 +6,7 @@ # argcomplete==3.5.0 # via nox -certifi==2024.7.4 +certifi==2024.8.30 # via requests cffi==1.17.0 # via @@ -66,7 +66,7 @@ pynacl==1.5.0 # via pygithub requests==2.32.3 # via pygithub -rich==13.7.1 +rich==13.8.0 # via typer shellingham==1.5.4 # via typer From d4e77888a45cde3745e7edd7ad9039fffef8ea2b Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 5 Sep 2024 17:16:01 +0100 Subject: [PATCH 483/536] add check-deploy job to publish workflow (#1814) * add check-deploy job to publish workflow --------- Co-authored-by: Maxwell G <9920591+gotmax23@users.noreply.github.com> Co-authored-by: Maxwell G --- .github/workflows/build-package-docs.yaml | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 0298b878161..e3773486a90 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -83,7 +83,7 @@ jobs: - name: Set the VERSION variable run: echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}" - + - name: Build the Ansible community package docs run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}" working-directory: build-directory/docs/docsite @@ -108,10 +108,14 @@ jobs: path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz retention-days: 7 - - name: Log the workflow inputs if deploy checked - if: fromJSON(github.event.inputs.deploy) + check-deploy: + if: github.event_name == 'workflow_dispatch' && github.event.inputs.deploy == 'true' + needs: build-package-docs + runs-on: ubuntu-latest + steps: + - name: Log the workflow inputs if deployed run: | - echo "## Deployment details :rocket:" >> "${GITHUB_STEP_SUMMARY}" + echo "## Deployment details :shipit:" >> "${GITHUB_STEP_SUMMARY}" echo "Publish to: ${{ github.event.inputs.deployment-environment }}" >> "${GITHUB_STEP_SUMMARY}" echo "Package version: ${{ github.event.inputs.ansible-package-version }}" >> "${GITHUB_STEP_SUMMARY}" echo "Owner: ${{ github.event.inputs.repository-owner }}" >> "${GITHUB_STEP_SUMMARY}" @@ -140,8 +144,8 @@ jobs: -d '{"msgtype": "m.text", "body": "${{ env.FAIL_MESSAGE }}"}' deploy-package-docs: - if: fromJSON(github.event.inputs.deploy) - needs: build-package-docs + needs: + - check-deploy runs-on: ubuntu-latest environment: name: deploy-package-docs From f23ba65472845e004f504c212e4f94a1bfbe047f Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sun, 8 Sep 2024 14:11:39 -0500 Subject: [PATCH 484/536] ci: refresh dev dependencies (#1834) --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/typing.txt | 10 +++++----- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index e5214ad1e17..7a14929978d 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -16,5 +16,5 @@ packaging==24.1 # via black pathspec==0.12.1 # via black -platformdirs==4.2.2 +platformdirs==4.3.1 # via black diff --git a/tests/static.txt b/tests/static.txt index fe84e6a4983..6c5de9e1de0 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.6.3 +ruff==0.6.4 # via -r tests/static.in diff --git a/tests/typing.txt b/tests/typing.txt index d28bba5f5ae..56948d21f68 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -8,7 +8,7 @@ argcomplete==3.5.0 # via nox certifi==2024.8.30 # via requests -cffi==1.17.0 +cffi==1.17.1 # via # cryptography # pynacl @@ -20,13 +20,13 @@ codeowners==0.7.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 # via nox -cryptography==43.0.0 +cryptography==43.0.1 # via pyjwt deprecated==1.2.14 # via pygithub distlib==0.3.8 # via virtualenv -filelock==3.15.4 +filelock==3.16.0 # via virtualenv gitdb==4.0.11 # via gitpython @@ -52,7 +52,7 @@ packaging==24.1 # via # -r tests/tag.in # nox -platformdirs==4.2.2 +platformdirs==4.3.1 # via virtualenv pycparser==2.22 # via cffi @@ -86,7 +86,7 @@ urllib3==2.2.2 # via # pygithub # requests -virtualenv==20.26.3 +virtualenv==20.26.4 # via nox wrapt==1.16.0 # via deprecated From 81bcc2fccd3b8f8e89fe3d091bc9908237887abb Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Mon, 9 Sep 2024 15:24:36 +0200 Subject: [PATCH 485/536] community_steering_committee.rst: fix collection requirements link (#1828) --- .../rst/community/steering/community_steering_committee.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index b84572386f6..e87687280c9 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -176,7 +176,7 @@ When reviewing community collection `inclusion requests Date: Mon, 9 Sep 2024 18:55:23 +0200 Subject: [PATCH 486/536] Bump antsibull-docs to 2.14.0; add antsibull-docutils and antsibull-fileutils. (#1837) --- tests/constraints.in | 2 +- tests/requirements-relaxed.txt | 17 +++++++++++++---- tests/requirements.txt | 17 +++++++++++++---- 3 files changed, 27 insertions(+), 9 deletions(-) diff --git a/tests/constraints.in b/tests/constraints.in index ae6a6e8107c..2d0442acf47 100644 --- a/tests/constraints.in +++ b/tests/constraints.in @@ -2,4 +2,4 @@ # and antsibull-docs that production builds rely upon. sphinx == 7.2.5 -antsibull-docs == 2.13.1 # currently approved version +antsibull-docs == 2.14.0 # currently approved version diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 97c262ad240..56cc31de0ef 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -5,7 +5,9 @@ # pip-compile --allow-unsafe --output-file=tests/requirements-relaxed.txt --strip-extras tests/requirements-relaxed.in # aiofiles==24.1.0 - # via antsibull-core + # via + # antsibull-core + # antsibull-fileutils aiohappyeyeballs==2.4.0 # via aiohttp aiohttp==3.10.5 @@ -22,14 +24,20 @@ ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-changelog==0.29.0 +antsibull-changelog==0.30.0 # via antsibull-docs antsibull-core==3.0.2 # via antsibull-docs -antsibull-docs==2.13.1 +antsibull-docs==2.14.0 # via -r tests/requirements-relaxed.in antsibull-docs-parser==1.1.0 # via antsibull-docs +antsibull-docutils==1.0.0 + # via antsibull-changelog +antsibull-fileutils==1.0.0 + # via + # antsibull-changelog + # antsibull-docs asyncio-pool==0.6.0 # via antsibull-docs attrs==24.2.0 @@ -50,6 +58,7 @@ docutils==0.20.1 # via # antsibull-changelog # antsibull-docs + # antsibull-docutils # rstcheck # sphinx # sphinx-rtd-theme @@ -98,9 +107,9 @@ pyproject-hooks==1.1.0 pyyaml==6.0.2 # via # -r tests/requirements-relaxed.in - # antsibull-changelog # antsibull-core # antsibull-docs + # antsibull-fileutils requests==2.32.3 # via sphinx resolvelib==1.0.1 diff --git a/tests/requirements.txt b/tests/requirements.txt index fdb45ed55c6..d645fa31c4f 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -5,7 +5,9 @@ # pip-compile --allow-unsafe --output-file=tests/requirements.txt --strip-extras tests/requirements.in # aiofiles==24.1.0 - # via antsibull-core + # via + # antsibull-core + # antsibull-fileutils aiohappyeyeballs==2.4.0 # via aiohttp aiohttp==3.10.5 @@ -22,16 +24,22 @@ ansible-pygments==0.1.1 # via # antsibull-docs # sphinx-ansible-theme -antsibull-changelog==0.29.0 +antsibull-changelog==0.30.0 # via antsibull-docs antsibull-core==3.0.2 # via antsibull-docs -antsibull-docs==2.13.1 +antsibull-docs==2.14.0 # via # -c tests/constraints.in # -r tests/requirements-relaxed.in antsibull-docs-parser==1.1.0 # via antsibull-docs +antsibull-docutils==1.0.0 + # via antsibull-changelog +antsibull-fileutils==1.0.0 + # via + # antsibull-changelog + # antsibull-docs asyncio-pool==0.6.0 # via antsibull-docs attrs==24.2.0 @@ -52,6 +60,7 @@ docutils==0.18.1 # via # antsibull-changelog # antsibull-docs + # antsibull-docutils # rstcheck # sphinx # sphinx-rtd-theme @@ -100,9 +109,9 @@ pyproject-hooks==1.1.0 pyyaml==6.0.2 # via # -r tests/requirements-relaxed.in - # antsibull-changelog # antsibull-core # antsibull-docs + # antsibull-fileutils requests==2.32.3 # via sphinx resolvelib==1.0.1 From 5b96636eeda8af668bace39d38264e8b93774411 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 9 Sep 2024 17:12:19 -0400 Subject: [PATCH 487/536] [devel] ci: refresh docs build dependencies (#1835) * ci: refresh docs build dependencies * ci: refresh docs build dependencies --------- Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 10 +++++----- tests/requirements.txt | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 56cc31de0ef..e76e462a707 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -46,7 +46,7 @@ babel==2.16.0 # via # sphinx # sphinx-intl -build==1.2.1 +build==1.2.2 # via antsibull-core certifi==2024.8.30 # via requests @@ -92,11 +92,11 @@ packaging==24.1 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.8.2 +pydantic==2.9.1 # via # antsibull-core # antsibull-docs -pydantic-core==2.20.1 +pydantic-core==2.23.3 # via pydantic pygments==2.18.0 # via @@ -175,9 +175,9 @@ typing-extensions==4.12.2 # pydantic-core urllib3==2.2.2 # via requests -yarl==1.9.6 +yarl==1.11.0 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==74.0.0 +setuptools==74.1.2 # via sphinx-intl diff --git a/tests/requirements.txt b/tests/requirements.txt index d645fa31c4f..88821dec103 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -48,7 +48,7 @@ babel==2.16.0 # via # sphinx # sphinx-intl -build==1.2.1 +build==1.2.2 # via antsibull-core certifi==2024.8.30 # via requests @@ -94,11 +94,11 @@ packaging==24.1 # sphinx perky==0.9.2 # via antsibull-core -pydantic==2.8.2 +pydantic==2.9.1 # via # antsibull-core # antsibull-docs -pydantic-core==2.20.1 +pydantic-core==2.23.3 # via pydantic pygments==2.18.0 # via @@ -181,9 +181,9 @@ typing-extensions==4.12.2 # rstcheck urllib3==2.2.2 # via requests -yarl==1.9.6 +yarl==1.11.0 # via aiohttp # The following packages are considered to be unsafe in a requirements file: -setuptools==74.0.0 +setuptools==74.1.2 # via sphinx-intl From 2d2f89b878130b86e2efcb74d76a736d8deac827 Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 9 Sep 2024 23:44:46 +0200 Subject: [PATCH 488/536] ci: refresh dev dependencies (#1845) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/formatters.txt | 2 +- tests/typing.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index 7a14929978d..d4f150de305 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -16,5 +16,5 @@ packaging==24.1 # via black pathspec==0.12.1 # via black -platformdirs==4.3.1 +platformdirs==4.3.2 # via black diff --git a/tests/typing.txt b/tests/typing.txt index 56948d21f68..30f74ad60dc 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -52,7 +52,7 @@ packaging==24.1 # via # -r tests/tag.in # nox -platformdirs==4.3.1 +platformdirs==4.3.2 # via virtualenv pycparser==2.22 # via cffi From 875f6200ec48d1ed81a248736e6ca33ec95a670c Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Tue, 10 Sep 2024 21:09:03 +0200 Subject: [PATCH 489/536] Add porting guide for Ansible 10.4.0 (#1853) --- .../rst/porting_guides/porting_guide_10.rst | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst index 2c88d7e6a8e..a91df8d7746 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -43,6 +43,10 @@ Playbook assert: that: '"hi mom" is in untrusted_result.stdout' +* ``any_errors_fatal`` - when a task in a block with a ``rescue`` section + fails on a host, the ``rescue`` section is executed on all hosts. This + occurs because ``any_errors_fatal`` automatically fails all hosts. + Command Line ============ @@ -99,6 +103,68 @@ Networking No notable changes +Porting Guide for v10.4.0 +========================= + +Known Issues +------------ + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. +- idrac_support_assist - Issue(308550) - This module fails when the NFS share path contains sub directory. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + +Breaking Changes +---------------- + +community.mysql +~~~~~~~~~~~~~~~ + +- collection - support of mysqlclient connector is deprecated - use PyMySQL connector instead! We will stop testing against it in collection version 4.0.0 and remove the related code in 5.0.0 (https://github.com/ansible-collections/community.mysql/issues/654). +- mysql_info - The ``users_info`` filter returned variable ``plugin_auth_string`` contains the hashed password and it's misleading, it will be removed from community.mysql 4.0.0. Use the `plugin_hash_string` return value instead (https://github.com/ansible-collections/community.mysql/pull/629). +- mysql_user - the ``user`` alias of the ``name`` argument has been deprecated and will be removed in collection version 5.0.0. Use the ``name`` argument instead. + +Major Changes +------------- + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_secure_boot - This module allows to import the secure boot certificate. +- idrac_support_assist - This module allows to run and export SupportAssist collection logs on iDRAC. + +grafana.grafana +~~~~~~~~~~~~~~~ + +- fix:mimir molecule should use ansible core 2.16 by @GVengelen in https://github.com/grafana/grafana-ansible-collection/pull/254 + +Deprecated Features +------------------- + +amazon.aws +~~~~~~~~~~ + +- iam_role - support for creating and deleting IAM instance profiles using the ``create_instance_profile`` and ``delete_instance_profile`` options has been deprecated and will be removed in a release after 2026-05-01. To manage IAM instance profiles the ``amazon.aws.iam_instance_profile`` module can be used instead (https://github.com/ansible-collections/amazon.aws/pull/2221). + +community.general +~~~~~~~~~~~~~~~~~ + +- MH decorator cause_changes module utils - deprecate parameters ``on_success`` and ``on_failure`` (https://github.com/ansible-collections/community.general/pull/8791). +- pipx - support for versions of the command line tool ``pipx`` older than ``1.7.0`` is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/8793). +- pipx_info - support for versions of the command line tool ``pipx`` older than ``1.7.0`` is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/8793). + +community.vmware +~~~~~~~~~~~~~~~~ + +- vmware_cluster - the module has been deprecated and will be removed in community.vmware 6.0.0 (https://github.com/ansible-collections/community.vmware/pull/2143). +- vmware_cluster_drs - the module has been deprecated and will be removed in community.vmware 6.0.0 (https://github.com/ansible-collections/community.vmware/pull/2136). +- vmware_cluster_vcls - the module has been deprecated and will be removed in community.vmware 6.0.0 (https://github.com/ansible-collections/community.vmware/pull/2156). + Porting Guide for v10.3.0 ========================= From 36271b4d8ef280fcb005ea002b95312d95417812 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Tue, 10 Sep 2024 21:09:48 +0200 Subject: [PATCH 490/536] Add porting guide for Ansible 9.10.0 (#1854) --- .../rst/porting_guides/porting_guide_9.rst | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index bc677c5e4f1..9d651d89f8f 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -84,6 +84,29 @@ Porting custom scripts Networking ========== +Porting Guide for v9.10.0 +========================= + +Breaking Changes +---------------- + +community.mysql +~~~~~~~~~~~~~~~ + +- collection - support of mysqlclient connector is deprecated - use PyMySQL connector instead! We will stop testing against it in collection version 4.0.0 and remove the related code in 5.0.0 (https://github.com/ansible-collections/community.mysql/issues/654). +- mysql_info - The ``users_info`` filter returned variable ``plugin_auth_string`` contains the hashed password and it's misleading, it will be removed from community.mysql 4.0.0. Use the `plugin_hash_string` return value instead (https://github.com/ansible-collections/community.mysql/pull/629). +- mysql_user - the ``user`` alias of the ``name`` argument has been deprecated and will be removed in collection version 5.0.0. Use the ``name`` argument instead. + +Deprecated Features +------------------- + +community.vmware +~~~~~~~~~~~~~~~~ + +- vmware_cluster - the module has been deprecated and will be removed in community.vmware 6.0.0 (https://github.com/ansible-collections/community.vmware/pull/2143). +- vmware_cluster_drs - the module has been deprecated and will be removed in community.vmware 6.0.0 (https://github.com/ansible-collections/community.vmware/pull/2136). +- vmware_cluster_vcls - the module has been deprecated and will be removed in community.vmware 6.0.0 (https://github.com/ansible-collections/community.vmware/pull/2156). + Porting Guide for v9.9.0 ======================== From 2043e2efa0de69f39edee2829934ca141fd1f254 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Wed, 11 Sep 2024 06:23:48 +0100 Subject: [PATCH 491/536] Restore community ee content (#1852) * restore community ee content This PR restores the docs about community execution environments from the ecosystem docsite. Please see the forum post for more info about this change: https://forum.ansible.com/t/moving-the-community-ee-content-to-package-docs/8239 * Update docs/docsite/rst/getting_started_ee/introduction.rst Co-authored-by: Andrew Klychkov * Update docs/docsite/rst/getting_started_ee/introduction.rst Co-authored-by: Andrew Klychkov * Update docs/docsite/rst/getting_started_ee/run_community_ee_image.rst Co-authored-by: Andrew Klychkov * formatting nits --------- Co-authored-by: Andrew Klychkov --- .../build_execution_environment.rst | 57 +++++++++++++++ docs/docsite/rst/getting_started_ee/index.rst | 39 +++++----- .../rst/getting_started_ee/introduction.rst | 65 +++++++++++++++++ .../run_community_ee_image.rst | 35 +++++++++ .../run_execution_environment.rst | 73 +++++++++++++++++++ .../getting_started_ee/setup_environment.rst | 44 +++++++++++ .../yaml/execution-environment.yml | 17 +++++ .../rst/getting_started_ee/yaml/hosts.yml | 3 + .../yaml/test_localhost.yml | 9 +++ .../getting_started_ee/yaml/test_remote.yml | 9 +++ 10 files changed, 334 insertions(+), 17 deletions(-) create mode 100644 docs/docsite/rst/getting_started_ee/build_execution_environment.rst create mode 100644 docs/docsite/rst/getting_started_ee/introduction.rst create mode 100644 docs/docsite/rst/getting_started_ee/run_community_ee_image.rst create mode 100644 docs/docsite/rst/getting_started_ee/run_execution_environment.rst create mode 100644 docs/docsite/rst/getting_started_ee/setup_environment.rst create mode 100644 docs/docsite/rst/getting_started_ee/yaml/execution-environment.yml create mode 100644 docs/docsite/rst/getting_started_ee/yaml/hosts.yml create mode 100644 docs/docsite/rst/getting_started_ee/yaml/test_localhost.yml create mode 100644 docs/docsite/rst/getting_started_ee/yaml/test_remote.yml diff --git a/docs/docsite/rst/getting_started_ee/build_execution_environment.rst b/docs/docsite/rst/getting_started_ee/build_execution_environment.rst new file mode 100644 index 00000000000..fb9adbea972 --- /dev/null +++ b/docs/docsite/rst/getting_started_ee/build_execution_environment.rst @@ -0,0 +1,57 @@ +.. _building_execution_environment: + +***************************************** +Building your first Execution Environment +***************************************** + +We are going to build an EE that represents an Ansible control node containing standard packages such as ``ansible-core`` and Python in addition to an Ansible collection (``community.postgresql``) and its dependency (the ``psycopg2-binary`` Python connector). + +To build your first EE: + +#. Create a project folder on your filesystem. + + .. code-block:: bash + + mkdir my_first_ee && cd my_first_ee + +#. Create a ``execution-environment.yml`` file that specifies dependencies to include in the image. + + .. literalinclude:: yaml/execution-environment.yml + :language: yaml + + > The `psycopg2-binary` Python package is included in the `requirements.txt` file for the collection. + > For collections that do not include `requirements.txt` files, you need to specify Python dependencies explicitly. + > See the `Ansible Builder documentation `_ for details. + +#. Build a EE container image called ``postgresql_ee``. + + If you use docker, add the ``--container-runtime docker`` argument. + + .. code-block:: bash + + ansible-builder build --tag postgresql_ee + +#. List container images to verify that you built it successfully. + + .. code-block:: bash + + podman image list + + localhost/postgresql_ee latest 2e866777269b 6 minutes ago 1.11 GB + +You can verify the image you created by inspecting the ``Containerfile`` or ``Dockerfile`` in the ``context`` directory to view its configuration. + +.. code-block:: bash + + less context/Containerfile + +You can also use Ansible Navigator to view detailed information about the image. + +Run the `ansible-navigator` command, type ``:images`` in the TUI, and then choose ``postgresql_ee``. + +Proceed to :ref:`running_custom_execution_environment` and test the EE you just built. + +.. seealso:: + + `Running a local container registry for Execution Environments `_ + This guide in the Ansible community forum explains how to set up a local registry for your Execution Environment images. diff --git a/docs/docsite/rst/getting_started_ee/index.rst b/docs/docsite/rst/getting_started_ee/index.rst index 3e3d38edcb8..02c5c384dad 100644 --- a/docs/docsite/rst/getting_started_ee/index.rst +++ b/docs/docsite/rst/getting_started_ee/index.rst @@ -4,29 +4,34 @@ Getting started with Execution Environments ******************************************* -Execution Environments (EEs) are Ansible control nodes packaged as container images. +You can run Ansible automation in containers, like any other modern software application. +Ansible uses container images known as Execution Environments (EE) that act as control nodes. EEs remove complexity to scale out automation projects and make things like deployment operations much more straightforward. -EEs provide you with: +An Execution Environment image contains the following packages as standard: -* Software dependency isolation -* Portability across teams and environments -* Separation from other automation content and tooling +* ``ansible-core`` +* ``ansible-runner`` +* Python +* Ansible content dependencies -You can use Ansible community EEs to get up and running. -Or you can easily build and deploy custom EEs with whatever packages and Ansible community collections you need for your project. +In addition to the standard packages, an EE can also contain: -Visit `Getting started with Execution Environments `_ in the Ansible ecosystem documentation. +* one or more Ansible collections and their dependencies +* other custom components -Ansible ecosystem ------------------ +This getting started guide shows you how to build and test a simple Execution Environment. +The resulting container image represents an Ansible control node that contains: -Using EEs with projects in the Ansible ecosystem lets you expand automation to lots of use cases: +* standard EE packages +* ``community.postgresql`` collection +* ``psycopg2-binary`` Python package -* `Ansible Builder `_ -* `Ansible Navigator `_ -* `Ansible AWX `_ -* `Ansible Runner `_ -* VS Code `Ansible `_ and `Dev Containers `_ extensions +.. toctree:: + :maxdepth: 1 -Visit the `Ansible ecosystem documentation `_ to find How Tos and tutorials for using EEs with Ansible projects. + introduction + setup_environment + build_execution_environment + run_execution_environment + run_community_ee_image diff --git a/docs/docsite/rst/getting_started_ee/introduction.rst b/docs/docsite/rst/getting_started_ee/introduction.rst new file mode 100644 index 00000000000..34e73728655 --- /dev/null +++ b/docs/docsite/rst/getting_started_ee/introduction.rst @@ -0,0 +1,65 @@ +.. _introduction_execution_environment: + +************************************** +Introduction to Execution Environments +************************************** + +Ansible Execution Environments aim to resolve complexity issues and provide all the benefits you can get from containerization. + +Reducing complexity +=================== + +There are three main areas where EEs can reduce complexity: + +* software dependencies +* portability +* content separation + +Dependencies +------------ + +Software applications typically have dependencies, and Ansible is no exception. +These dependencies can include software libraries, configuration files or other services, to name a few. + +Traditionally, administrators install application dependencies on top of an operating system using packaging management tools such as RPM or Python-pip. +The major drawback of such an approach is that an application might require versions of dependencies different from those provided by default. +For Ansible, a typical installation consists of `ansible-core` and a set of Ansible collections. +Many of them have dependencies for the plugins, modules, roles and playbooks they provide. + +The Ansible collections can depend on the following pieces of software and their versions: + +* ``ansible-core`` +* Python +* Python packages +* System packages +* Other Ansible collections + +The dependencies have to be installed and sometimes can conflict with each other. + +One way to **partially** resolve the dependency issue is to use Python virtual environments on Ansible control nodes. +However, applied to Ansible, virtual environments have drawbacks and natural limitations. + +Portability +----------- + +An Ansible user writes content for Ansible locally and wants to leverage the container technology to make their automation runtimes portable, shareable and easily deployable to testing and production environments. + +Content separation +------------------ + +In situations when there is an Ansible control node or a tool such as Ansible AWX/Controller used by several users, they might want separate +their content to avoid configuration and dependency conflicts. + +Ansible tooling for EEs +======================= + +Projects in the Ansible ecosystem also provide several tools that you can use with EEs, such as: + +* `Ansible Builder `_ +* `Ansible Navigator `_ +* `Ansible AWX `_ +* `Ansible Runner `_ +* `VS Code Ansible `_ +* `Dev Containers extensions `_ + +Ready to get started with EEs? Proceed to :ref:`setting_up_ee_environment`. diff --git a/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst b/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst new file mode 100644 index 00000000000..806272fe59b --- /dev/null +++ b/docs/docsite/rst/getting_started_ee/run_community_ee_image.rst @@ -0,0 +1,35 @@ +.. _running_community_execution_environment: + +******************************************* +Running Ansible with the community EE image +******************************************* + +You can run ansible without the need to build a custom EE using community images. + +Use the ``community-ee-minimal`` image that includes only ``ansible-core`` or the ``community-ee-base`` image that also includes several base collections. +Run the following command to see the collections included in the ``community-ee-base`` image: + +.. code-block:: bash + + ansible-navigator collections --execution-environment-image ghcr.io/ansible-community/community-ee-base:latest + +Run the following Ansible ad-hoc command against localhost inside the ``community-ee-minimal`` container: + +.. code-block:: bash + + ansible-navigator exec "ansible localhost -m setup" --execution-environment-image ghcr.io/ansible-community/community-ee-minimal:latest --mode stdout + +Now, create a simple test playbook and run it against ``localhost`` inside the container: + +.. literalinclude:: yaml/test_localhost.yml + :language: yaml + +.. code-block:: bash + + ansible-navigator run test_localhost.yml --execution-environment-image ghcr.io/ansible-community/community-ee-minimal:latest --mode stdout + +.. seealso:: + + * :ref:`building_execution_environment` + * :ref:`running_custom_execution_environment` + * `Ansible Navigator documentation `_ diff --git a/docs/docsite/rst/getting_started_ee/run_execution_environment.rst b/docs/docsite/rst/getting_started_ee/run_execution_environment.rst new file mode 100644 index 00000000000..5021c74cec9 --- /dev/null +++ b/docs/docsite/rst/getting_started_ee/run_execution_environment.rst @@ -0,0 +1,73 @@ +.. _running_custom_execution_environment: + +*************** +Running your EE +*************** + +You can run your EE on the command line against ``localhost`` or a remote target using ``ansible-navigator``. + +> There are other tools besides ``ansible-navigator`` you can run EEs with. + +Run against localhost +===================== + +#. Create a ``test_localhost.yml`` playbook. + + .. literalinclude:: yaml/test_localhost.yml + :language: yaml + +#. Run the playbook inside the ``postgresql_ee`` EE. + + .. code-block:: bash + + ansible-navigator run test_localhost.yml --execution-environment-image postgresql_ee --mode stdout --pull-policy missing --container-options='--user=0' + +You may notice the facts being gathered are about the container and not the developer machine. +This is because the ansible playbook was run inside the container. + +Run against a remote target +=========================== + +Before you start, ensure you have the following: + + * At least one IP address or resolvable hostname for a remote target. + * Valid credentials for the remote host. + * A user with `sudo` permissions on the remote host. + +Execute a playbook inside the ``postgresql_ee`` EE against a remote host machine as in the following example: + +#. Create a directory for inventory files. + + .. code-block:: bash + + mkdir inventory + +#. Create the ``hosts.yml`` inventory file in the ``inventory`` directory. + + .. literalinclude:: yaml/hosts.yml + :language: yaml + +#. Create a ``test_remote.yml`` playbook. + + .. literalinclude:: yaml/test_remote.yml + :language: yaml + +#. Run the playbook inside the ``postgresql_ee`` EE. + + Replace ``student`` with the appropriate username. + Some arguments in the command can be optional depending on your target host authentication method. + + .. code-block:: bash + + ansible-navigator run test_remote.yml -i inventory --execution-environment-image postgresql_ee:latest --mode stdout --pull-policy missing --enable-prompts -u student -k -K + +.. seealso:: + + `Execution Environment Definition `_ + Provides information about the about Execution Environment definition file and available options. + `Ansible Builder CLI usage `_ + Provides details about using Ansible Builder. + `Ansible Navigator documentation `_ + Provides details about using Ansible Navigator. + `Running a local container registry for EEs `_ + This guide in the Ansible community forum explains how to set up a local registry for your Execution Environment images. diff --git a/docs/docsite/rst/getting_started_ee/setup_environment.rst b/docs/docsite/rst/getting_started_ee/setup_environment.rst new file mode 100644 index 00000000000..5b18e42a020 --- /dev/null +++ b/docs/docsite/rst/getting_started_ee/setup_environment.rst @@ -0,0 +1,44 @@ +.. _setting_up_ee_environment: + +*************************** +Setting up your environment +*************************** + +Complete the following steps to set up a local environment for your first Execution Environment: + +#. Ensure the following packages are installed on your system: + + * ``podman`` or ``docker`` + * ``python3`` + + If you use the DNF package manager, install these prerequisites as follows: + + .. code-block:: bash + + sudo dnf install -y podman python3 + +#. Install ``ansible-navigator``: + + .. code-block:: bash + + pip3 install ansible-navigator + + Installing ``ansible-navigator`` lets you run EEs on the command line. + It includes the ``ansible-builder`` package to build EEs. + + If you want to build EEs without testing, install only ``ansible-builder``: + + .. code-block:: bash + + pip3 install ansible-builder + +#. Verify your environment with the following commands: + + .. code-block:: bash + + ansible-navigator --version + ansible-builder --version + +Ready to build an EE in a few easy steps? Proceed to :ref:`building_execution_environment`. + +Want to try an EE without having to build one? Proceed to :ref:`running_community_execution_environment`. diff --git a/docs/docsite/rst/getting_started_ee/yaml/execution-environment.yml b/docs/docsite/rst/getting_started_ee/yaml/execution-environment.yml new file mode 100644 index 00000000000..35668c4bd8e --- /dev/null +++ b/docs/docsite/rst/getting_started_ee/yaml/execution-environment.yml @@ -0,0 +1,17 @@ +version: 3 + +images: + base_image: + name: quay.io/fedora/fedora:latest + +dependencies: + ansible_core: + package_pip: ansible-core + ansible_runner: + package_pip: ansible-runner + system: + - openssh-clients + - sshpass + galaxy: + collections: + - name: community.postgresql diff --git a/docs/docsite/rst/getting_started_ee/yaml/hosts.yml b/docs/docsite/rst/getting_started_ee/yaml/hosts.yml new file mode 100644 index 00000000000..3fb711e9c71 --- /dev/null +++ b/docs/docsite/rst/getting_started_ee/yaml/hosts.yml @@ -0,0 +1,3 @@ +all: + hosts: + 192.168.0.2 # Replace with the IP of your target host \ No newline at end of file diff --git a/docs/docsite/rst/getting_started_ee/yaml/test_localhost.yml b/docs/docsite/rst/getting_started_ee/yaml/test_localhost.yml new file mode 100644 index 00000000000..9be3ab10425 --- /dev/null +++ b/docs/docsite/rst/getting_started_ee/yaml/test_localhost.yml @@ -0,0 +1,9 @@ +- name: Gather and print local facts + hosts: localhost + become: true + gather_facts: true + tasks: + + - name: Print facts + ansible.builtin.debug: + var: ansible_facts diff --git a/docs/docsite/rst/getting_started_ee/yaml/test_remote.yml b/docs/docsite/rst/getting_started_ee/yaml/test_remote.yml new file mode 100644 index 00000000000..08b5517db02 --- /dev/null +++ b/docs/docsite/rst/getting_started_ee/yaml/test_remote.yml @@ -0,0 +1,9 @@ +- name: Gather and print facts + hosts: all + become: true + gather_facts: true + tasks: + + - name: Print facts + ansible.builtin.debug: + var: ansible_facts From ae59246f0bfaf33a5a48bf873b6afe633b032520 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 11 Sep 2024 07:39:39 +0200 Subject: [PATCH 492/536] Replace communication links with a link to communication guide, part 1 (#1851) * Replace communication links with a link to communication guide * Update docs/docsite/rst/command_guide/intro_adhoc.rst Co-authored-by: Don Naro * Update docs/docsite/rst/plugins/become.rst Co-authored-by: Don Naro * Update docs/docsite/rst/plugins/cache.rst Co-authored-by: Don Naro * Update docs/docsite/rst/plugins/callback.rst Co-authored-by: Don Naro * Update docs/docsite/rst/plugins/cliconf.rst Co-authored-by: Don Naro * fix --------- Co-authored-by: Don Naro --- docs/docsite/rst/command_guide/intro_adhoc.rst | 6 ++---- docs/docsite/rst/community/getting_started.rst | 5 ++--- docs/docsite/rst/plugins/become.rst | 6 ++---- docs/docsite/rst/plugins/cache.rst | 6 ++---- docs/docsite/rst/plugins/callback.rst | 6 ++---- docs/docsite/rst/plugins/cliconf.rst | 6 ++---- 6 files changed, 12 insertions(+), 23 deletions(-) diff --git a/docs/docsite/rst/command_guide/intro_adhoc.rst b/docs/docsite/rst/command_guide/intro_adhoc.rst index 6e1810fa197..91b2bc286ef 100644 --- a/docs/docsite/rst/command_guide/intro_adhoc.rst +++ b/docs/docsite/rst/command_guide/intro_adhoc.rst @@ -224,7 +224,5 @@ Now that you understand the basic elements of Ansible execution, you are ready t Browse existing collections, modules, and plugins :ref:`working_with_playbooks` Using Ansible for configuration management & deployment - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/community/getting_started.rst b/docs/docsite/rst/community/getting_started.rst index 5eb4c4689da..94dcf8ef057 100644 --- a/docs/docsite/rst/community/getting_started.rst +++ b/docs/docsite/rst/community/getting_started.rst @@ -21,8 +21,8 @@ Other ways to get involved Here are some other ways to connect with the Ansible community: -* Find an `Ansible Meetup near me `_ - communication +* Visit the :ref:`Ansible communication guide`. +* Find an `Ansible Meetup near you `_. * Learn more about Ansible: * `Read books `_. @@ -30,4 +30,3 @@ Here are some other ways to connect with the Ansible community: * `Attend events `_. * `Review getting started guides `_. * `Watch videos `_ - includes Ansible Automates, AnsibleFest & webinar recordings. -* See where `new releases are announced `_ diff --git a/docs/docsite/rst/plugins/become.rst b/docs/docsite/rst/plugins/become.rst index 6cd7d402a1f..44ea6b2ca96 100644 --- a/docs/docsite/rst/plugins/become.rst +++ b/docs/docsite/rst/plugins/become.rst @@ -61,7 +61,5 @@ Use ``ansible-doc -t become `` to see plugin-specific documentation Test plugins :ref:`lookup_plugins` Lookup plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst index c9ca686ef69..76e24a4cfd6 100644 --- a/docs/docsite/rst/plugins/cache.rst +++ b/docs/docsite/rst/plugins/cache.rst @@ -133,7 +133,5 @@ Use ``ansible-doc -t cache `` to see plugin-specific documentation Strategy plugins :ref:`vars_plugins` Vars plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst index 76172fc2d3e..2d6b50d3c32 100644 --- a/docs/docsite/rst/plugins/callback.rst +++ b/docs/docsite/rst/plugins/callback.rst @@ -110,7 +110,5 @@ Use ``ansible-doc -t callback `` to see plugin-specific documentati Strategy plugins :ref:`vars_plugins` Vars plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/cliconf.rst b/docs/docsite/rst/plugins/cliconf.rst index e175e9a3e99..0d43ff9d4d5 100644 --- a/docs/docsite/rst/plugins/cliconf.rst +++ b/docs/docsite/rst/plugins/cliconf.rst @@ -43,7 +43,5 @@ Use ``ansible-doc -t cliconf `` to see plugin-specific documentatio :ref:`Ansible for Network Automation` An overview of using Ansible to automate networking devices. - `User Mailing List `_ - Have a question? Stop by the Google group! - `irc.libera.chat `_ - #ansible-network IRC chat channel + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide From d06c4b152423a426074ac9040ae75c3287efcf52 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 11 Sep 2024 06:33:07 -0500 Subject: [PATCH 493/536] ci: add workflow to create core tags automatically (#1863) Fixes: https://github.com/ansible/ansible-documentation/issues/66 --- .github/workflows/tag.yml | 48 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 .github/workflows/tag.yml diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml new file mode 100644 index 00000000000..b61f5ba83a6 --- /dev/null +++ b/.github/workflows/tag.yml @@ -0,0 +1,48 @@ +--- +name: Sync tags with ansible-core releases + +"on": + workflow_dispatch: + inputs: + dry-run: + type: boolean + default: false + description: "Select to run the tag script in dry-run mode" + schedule: + - cron: "0 * * * *" # Hourly + +jobs: + tag: + runs-on: "ubuntu-latest" + permissions: + contents: write + steps: + - name: Generate temp GITHUB_TOKEN + id: create_token + uses: tibdex/github-app-token@v2 + with: + app_id: ${{ secrets.BOT_APP_ID }} + private_key: ${{ secrets.BOT_APP_KEY }} + - name: Check out us + uses: actions/checkout@v4 + with: + path: ansible-documentation + fetch-depth: 0 + token: "${{ steps.create_token.outputs.token }}" + - name: Check out core + uses: actions/checkout@v4 + with: + repository: ansible/ansible + path: ansible + fetch-depth: 0 + - name: Setup nox + uses: wntrblm/nox@2024.04.15 + with: + python-versions: "3.12" + - name: Set up git committer + run: | + ./hacking/get_bot_user.sh "ansible-documentation-bot" "Ansible Documentation Bot" + working-directory: ansible-documentation + - name: Run tag script + run: nox -s tag -- tag ${{ inputs.dry-run && '--no-push' || '' }} + working-directory: ansible-documentation From 08e87b5cdb1a5e6b3f5e3122d93c31e8195472bc Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 11 Sep 2024 13:43:48 +0200 Subject: [PATCH 494/536] Give tag workflow access to github-bot environment. (#1866) --- .github/workflows/tag.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml index b61f5ba83a6..5bad5a6c6c2 100644 --- a/.github/workflows/tag.yml +++ b/.github/workflows/tag.yml @@ -14,6 +14,7 @@ name: Sync tags with ansible-core releases jobs: tag: runs-on: "ubuntu-latest" + environment: github-bot permissions: contents: write steps: From 1500fc2790078bf7dd9dd160de02349212636503 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 11 Sep 2024 13:10:34 -0400 Subject: [PATCH 495/536] Correct information about plugin enabling (#1760) * Correct information about plugin enabling * Apply suggestions from code review Co-authored-by: Don Naro --------- Co-authored-by: Don Naro --- docs/docsite/rst/dev_guide/developing_locally.rst | 4 ++++ docs/docsite/rst/plugins/cache.rst | 2 +- docs/docsite/rst/plugins/callback.rst | 2 +- docs/docsite/rst/plugins/inventory.rst | 3 ++- docs/docsite/rst/plugins/vars.rst | 2 +- 5 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_locally.rst b/docs/docsite/rst/dev_guide/developing_locally.rst index e39ff154008..73cc7138151 100644 --- a/docs/docsite/rst/dev_guide/developing_locally.rst +++ b/docs/docsite/rst/dev_guide/developing_locally.rst @@ -137,6 +137,10 @@ Ansible automatically loads all plugins from certain directories adjacent to you Roles contained in collections cannot contain any plugins. All plugins in a collection must live in the collection ``plugins`` directory tree. All plugins in that tree are accessible to all roles in the collection. If you are developing new plugins, we recommend distributing them in :ref:`collections `, not in roles. +.. warning:: + + Some plugin types are needed early during Ansible execution, such as callbacks, inventory, and cache. These plugin types cannot be loaded dynamically and must exist in configured paths or be referenced by FQCN in configuration. + .. _ansible.legacy.custom: Using ``ansible.legacy`` to access custom versions of an ``ansible.builtin`` module diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst index 76e24a4cfd6..5e877a7670e 100644 --- a/docs/docsite/rst/plugins/cache.rst +++ b/docs/docsite/rst/plugins/cache.rst @@ -38,7 +38,7 @@ If the cache plugin is in a collection use the fully qualified name: [defaults] fact_caching = namespace.collection_name.cache_plugin_name -To enable a custom cache plugin, save it in a ``cache_plugins`` directory adjacent to your play, inside a role, or in one of the directory sources configured in :ref:`ansible.cfg `. +To enable a custom cache plugin, save it in one of the directory sources configured in :ref:`ansible.cfg ` or in a collection and then reference it by FQCN. You also need to configure other settings specific to each plugin. Consult the individual plugin documentation or the Ansible :ref:`configuration ` for more details. diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst index 2d6b50d3c32..41f04ddc873 100644 --- a/docs/docsite/rst/plugins/callback.rst +++ b/docs/docsite/rst/plugins/callback.rst @@ -23,7 +23,7 @@ The :ref:`say ` callback responds with a computer-synthesized spee Enabling callback plugins ------------------------- -You can activate a custom callback by either dropping it into a ``callback_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the callback directory sources configured in :ref:`ansible.cfg `. +You can activate a custom callback, depending on it's ``NEEDS_ENABLED`` property, by either dropping it into one of the callback directory sources configured in :ref:`ansible.cfg ` or in a collection and referencing it in configuration by FQCN. Plugins are loaded in alphanumeric order. For example, a plugin implemented in a file named `1_first.py` would run before a plugin file named `2_second.py`. diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst index 63f46608da0..9a9ff627a32 100644 --- a/docs/docsite/rst/plugins/inventory.rst +++ b/docs/docsite/rst/plugins/inventory.rst @@ -36,8 +36,9 @@ Or, if it is a local plugin, perhaps stored in the path set by :ref:`DEFAULT_INV [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. +For other plugins you must either save it in one of the directory sources configured in :ref:`ansible.cfg ` and enable it or add to a collection and then reference it by FQCN. .. _using_inventory: diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst index e9bd42c3064..c4117b58034 100644 --- a/docs/docsite/rst/plugins/vars.rst +++ b/docs/docsite/rst/plugins/vars.rst @@ -18,7 +18,7 @@ The :ref:`host_group_vars ` plugin shipped with Ansible en Enabling vars plugins --------------------- -You can activate a custom vars plugin by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :ref:`ansible.cfg `. +You can activate a custom vars plugin by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :ref:`ansible.cfg `. For a vars plugin to run during inventory build you cannot enable it in a play or role as these are not loaded until later. If they are only going to run at task execution, there are no limitations on where they are provided. Most vars plugins are disabled by default. To enable a vars plugin, set ``vars_plugins_enabled`` in the ``defaults`` section of :ref:`ansible.cfg ` or set the ``ANSIBLE_VARS_ENABLED`` environment variable to the list of vars plugins you want to execute. By default, the :ref:`host_group_vars ` plugin shipped with Ansible is enabled. From bf86a30bef06b22bf87eb54e4b9d028608876fd4 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 12 Sep 2024 09:41:36 +0200 Subject: [PATCH 496/536] Replace communication links with a link to communication guide, part 2 (#1864) * Replace old communication refs with Communication guide ref or forum * Update docs/docsite/rst/community/documentation_contributions.rst Co-authored-by: Felix Fontein --------- Co-authored-by: Felix Fontein --- docs/docsite/rst/community/communication.rst | 2 +- .../rst/community/documentation_contributions.rst | 2 +- .../rst/community/reporting_bugs_and_features.rst | 4 ++-- .../rst/community/reporting_collections.rst | 2 +- docs/docsite/rst/dev_guide/developing_api.rst | 6 ++---- .../rst/dev_guide/developing_collections.rst | 6 ++---- .../developing_collections_changelogs.rst | 6 ++---- .../developing_collections_contributing.rst | 6 ++---- .../dev_guide/developing_collections_creating.rst | 6 ++---- .../developing_collections_distributing.rst | 6 ++---- .../dev_guide/developing_collections_migrating.rst | 6 ++---- .../dev_guide/developing_collections_shared.rst | 6 ++---- .../dev_guide/developing_collections_structure.rst | 6 ++---- .../dev_guide/developing_collections_testing.rst | 6 ++---- docs/docsite/rst/dev_guide/developing_core.rst | 6 ++---- .../docsite/rst/dev_guide/developing_inventory.rst | 6 ++---- docs/docsite/rst/dev_guide/developing_modules.rst | 6 ++---- .../rst/dev_guide/developing_modules_checklist.rst | 2 +- .../rst/dev_guide/developing_modules_general.rst | 6 +----- .../developing_modules_general_windows.rst | 5 +---- .../rst/dev_guide/developing_modules_in_groups.rst | 12 ++---------- docs/docsite/rst/dev_guide/developing_plugins.rst | 6 ++---- docs/docsite/rst/dev_guide/developing_rebasing.rst | 2 +- docs/docsite/rst/dev_guide/sidecar.rst | 6 ++---- docs/docsite/rst/dev_guide/style_guide/index.rst | 4 ++-- .../rst/dev_guide/style_guide/resources.rst | 2 +- docs/docsite/rst/dev_guide/testing.rst | 3 +-- .../testing/sanity/integration-aliases.rst | 2 +- .../rst/dev_guide/testing_units_modules.rst | 9 ++++----- docs/docsite/rst/galaxy/dev_guide.rst | 14 ++++++-------- .../inventory_guide/intro_dynamic_inventory.rst | 6 ++---- .../rst/inventory_guide/intro_inventory.rst | 6 ++---- .../docsite/rst/inventory_guide/intro_patterns.rst | 6 ++---- .../rst/module_plugin_guide/modules_intro.rst | 7 ++----- .../rst/module_plugin_guide/modules_support.rst | 8 +++----- .../developing_resource_modules_network.rst | 2 +- .../network/getting_started/network_resources.rst | 13 ++++++------- docs/docsite/rst/os_guide/intro_bsd.rst | 6 ++---- docs/docsite/rst/os_guide/windows_dsc.rst | 6 ++---- docs/docsite/rst/os_guide/windows_faq.rst | 6 ++---- docs/docsite/rst/os_guide/windows_setup.rst | 6 ++---- docs/docsite/rst/os_guide/windows_usage.rst | 6 ++---- docs/docsite/rst/os_guide/windows_winrm.rst | 6 ++---- .../playbook_guide/playbooks_advanced_syntax.rst | 6 ++---- .../docsite/rst/playbook_guide/playbooks_async.rst | 6 ++---- .../rst/playbook_guide/playbooks_blocks.rst | 6 ++---- .../rst/playbook_guide/playbooks_conditionals.rst | 6 ++---- .../rst/playbook_guide/playbooks_debugger.rst | 6 ++---- .../rst/playbook_guide/playbooks_delegation.rst | 6 ++---- .../rst/playbook_guide/playbooks_environment.rst | 6 ++---- .../playbook_guide/playbooks_error_handling.rst | 6 ++---- .../rst/playbook_guide/playbooks_filters.rst | 6 ++---- .../docsite/rst/playbook_guide/playbooks_intro.rst | 4 ++-- .../rst/playbook_guide/playbooks_lookups.rst | 6 ++---- .../docsite/rst/playbook_guide/playbooks_loops.rst | 6 ++---- .../playbooks_privilege_escalation.rst | 6 ++---- .../rst/playbook_guide/playbooks_prompts.rst | 6 ++---- .../docsite/rst/playbook_guide/playbooks_reuse.rst | 4 ++-- .../rst/playbook_guide/playbooks_reuse_roles.rst | 4 ++-- .../rst/playbook_guide/playbooks_strategies.rst | 6 ++---- docs/docsite/rst/playbook_guide/playbooks_tags.rst | 6 ++---- .../rst/playbook_guide/playbooks_templating.rst | 6 ++---- .../docsite/rst/playbook_guide/playbooks_tests.rst | 6 ++---- .../rst/playbook_guide/playbooks_variables.rst | 6 ++---- docs/docsite/rst/plugins/action.rst | 6 ++---- docs/docsite/rst/plugins/connection.rst | 6 ++---- docs/docsite/rst/plugins/docs_fragment.rst | 6 ++---- docs/docsite/rst/plugins/filter.rst | 6 ++---- docs/docsite/rst/plugins/httpapi.rst | 6 ++---- docs/docsite/rst/plugins/inventory.rst | 6 ++---- docs/docsite/rst/plugins/lookup.rst | 6 ++---- docs/docsite/rst/plugins/module.rst | 6 ++---- docs/docsite/rst/plugins/module_util.rst | 6 ++---- docs/docsite/rst/plugins/netconf.rst | 6 ++---- docs/docsite/rst/plugins/plugins.rst | 6 ++---- docs/docsite/rst/plugins/shell.rst | 6 ++---- docs/docsite/rst/plugins/strategy.rst | 6 ++---- docs/docsite/rst/plugins/terminal.rst | 6 ++---- docs/docsite/rst/plugins/test.rst | 6 ++---- docs/docsite/rst/plugins/vars.rst | 6 ++---- .../rst/reference_appendices/YAMLSyntax.rst | 6 ++---- .../reference_appendices/common_return_values.rst | 6 ++---- docs/docsite/rst/reference_appendices/faq.rst | 6 +++--- docs/docsite/rst/reference_appendices/glossary.rst | 8 +++----- .../release_and_maintenance.rst | 6 ++---- .../rst/reference_appendices/test_strategies.rst | 6 ++---- docs/docsite/rst/roadmap/COLLECTIONS_11.rst | 6 +++++- .../rst/roadmap/ansible_core_roadmap_index.rst | 7 +------ docs/docsite/rst/roadmap/ansible_roadmap_index.rst | 7 ++----- .../rst/tips_tricks/ansible_tips_tricks.rst | 4 ++-- docs/docsite/rst/tips_tricks/sample_setup.rst | 4 ++-- 91 files changed, 186 insertions(+), 341 deletions(-) diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index 6f1453b4708..4ffef1749b9 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -136,4 +136,4 @@ Ansible Automation Platform support questions Red Hat Ansible `Automation Platform `_ is a subscription that contains support, certified content, and tooling for Ansible including content management, a controller, UI and REST API. -If you have a question about Ansible Automation Platform, visit `Red Hat support `_ rather than using a chat channel or the general project mailing list. +If you have a question about Ansible Automation Platform, visit `Red Hat support `_ rather than using community communication platforms. diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index b701eed95ec..aad80389ad2 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -233,7 +233,7 @@ It is recommended to run tests on a clean copy of the repository, which is the p Joining the documentation working group ======================================= -The Documentation Working Group (DaWGs) meets weekly on Tuesdays in the Docs chat (using `Matrix `_ or using IRC at `irc.libera.chat `_). For more information, including links to our agenda and a calendar invite, visit our `forum group `_. +The Documentation Working Group (DaWGs) meets weekly on Tuesdays in the `docs:ansible.im chat room `_ on :ref:`Matrix`. For more information, including links to our agenda, visit our `forum group `_. .. seealso:: :ref:`More about testing module documentation ` diff --git a/docs/docsite/rst/community/reporting_bugs_and_features.rst b/docs/docsite/rst/community/reporting_bugs_and_features.rst index a972603af36..dd950bcd7e4 100644 --- a/docs/docsite/rst/community/reporting_bugs_and_features.rst +++ b/docs/docsite/rst/community/reporting_bugs_and_features.rst @@ -21,9 +21,9 @@ Ansible practices responsible disclosure. To report security-related bugs, send Bugs in ansible-core -------------------- -Before reporting a bug, search in GitHub for `already reported issues `_ and `open pull requests `_ to see if someone has already addressed your issue. Unsure if you found a bug? Report the behavior on the :ref:`mailing list or community chat first `. +Before reporting a bug, search in GitHub for `already reported issues `_ and `open pull requests `_ to see if someone has already addressed your issue. Unsure if you found a bug? Discuss the behavior with the community on the :ref:`Ansible Forum`. -Also, use the mailing list or chat to discuss whether the problem is in ``ansible-core`` or a collection, and for "how do I do this" type questions. +Also, use the :ref:`Ansible Forum` to discuss whether the problem is in ``ansible-core`` or a collection, and for "how do I do this" type questions. You need a free GitHub account to `report bugs `_ that affect: diff --git a/docs/docsite/rst/community/reporting_collections.rst b/docs/docsite/rst/community/reporting_collections.rst index fbcd6ca732e..2b4b211a087 100644 --- a/docs/docsite/rst/community/reporting_collections.rst +++ b/docs/docsite/rst/community/reporting_collections.rst @@ -25,7 +25,7 @@ Many bugs only affect a single module or plugin. If you find a bug that affects #. Click on the Issue Tracker link for that collection. #. Follow the contributor guidelines or instructions in the collection repo. -If you are not sure whether a bug is in ansible-core or a collection, you can report the behavior on the :ref:`mailing list or community chat channel first `. +If you are not sure whether a bug is in ansible-core or a collection, you can report the behavior on the :ref:`Ansible Forum`. Requesting a feature ==================== diff --git a/docs/docsite/rst/dev_guide/developing_api.rst b/docs/docsite/rst/dev_guide/developing_api.rst index 3ea552a2132..4f6d5890b2c 100644 --- a/docs/docsite/rst/dev_guide/developing_api.rst +++ b/docs/docsite/rst/dev_guide/developing_api.rst @@ -41,7 +41,5 @@ command line tools (``lib/ansible/cli/``) is `available on GitHub `_ - Mailing list for development topics - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index ae8efa7e5ea..6bfbfbb9fb3 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -43,7 +43,5 @@ For instructions on developing modules, see :ref:`developing_modules_general`. Learn how to install and use collections in playbooks and roles :ref:`contributing_maintained_collections` Guidelines for contributing to selected collections - `Mailing List `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_collections_changelogs.rst b/docs/docsite/rst/dev_guide/developing_collections_changelogs.rst index 3e164090d2b..334bfd87753 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_changelogs.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_changelogs.rst @@ -76,7 +76,5 @@ If your collection is part of Ansible, use one of the following three options t Learn how to install and use collections. :ref:`contributing_maintained_collections` Guidelines for contributing to selected collections - `Mailing List `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_collections_contributing.rst b/docs/docsite/rst/dev_guide/developing_collections_contributing.rst index d1751723eb8..5fc71fee8e1 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_contributing.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_contributing.rst @@ -60,7 +60,5 @@ You can test your changes by using this checkout of ``community.general`` in pla Learn how to install and use collections. :ref:`contributing_maintained_collections` Guidelines for contributing to selected collections - `Mailing List `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_collections_creating.rst b/docs/docsite/rst/dev_guide/developing_collections_creating.rst index 32adfc0765b..ee70217730c 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_creating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_creating.rst @@ -135,7 +135,5 @@ After `installing `_ Python package of tools to create and test Ansible content. - `Mailing List `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst index 59c08a6d60f..167726dc481 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst @@ -400,7 +400,5 @@ After Galaxy uploads and accepts a collection, the website shows you the **My Im Learn how to install and use collections. :ref:`collections_galaxy_meta` Table of fields used in the :file:`galaxy.yml` file - `Mailing List `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_collections_migrating.rst b/docs/docsite/rst/dev_guide/developing_collections_migrating.rst index 99cd846feef..6cd63d84ba2 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_migrating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_migrating.rst @@ -132,7 +132,5 @@ Ansibulbot will know how to redirect existing issues and PRs to the new repo. Th Learn how to install and use collections. :ref:`contributing_maintained_collections` Guidelines for contributing to selected collections - `Mailing List `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_collections_shared.rst b/docs/docsite/rst/dev_guide/developing_collections_shared.rst index 34db6aea696..baba9422766 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_shared.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_shared.rst @@ -88,7 +88,5 @@ You can use git repositories for collection dependencies during local developmen Learn how to install and use collections. :ref:`contributing_maintained_collections` Guidelines for contributing to selected collections - `Mailing List `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index 4b2139adc75..6a82af60b69 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -299,7 +299,5 @@ See the `collection-level metadata guide `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_collections_testing.rst b/docs/docsite/rst/dev_guide/developing_collections_testing.rst index e24495e3d08..f89f5d83234 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_testing.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_testing.rst @@ -102,7 +102,5 @@ You can specify multiple target names. Each target name is the name of a directo More resources on testing Ansible :ref:`contributing_maintained_collections` Guidelines for contributing to selected collections - `Mailing List `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_core.rst b/docs/docsite/rst/dev_guide/developing_core.rst index ce8b95ece4a..42cb35a8d16 100644 --- a/docs/docsite/rst/dev_guide/developing_core.rst +++ b/docs/docsite/rst/dev_guide/developing_core.rst @@ -16,7 +16,5 @@ Although ``ansible-core`` (the code hosted in the `ansible/ansible repository `_ - The development mailing list - `irc.libera.chat `_ - #ansible-devel IRC chat channel + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_inventory.rst b/docs/docsite/rst/dev_guide/developing_inventory.rst index 3558e1326c4..dfef1c3b260 100644 --- a/docs/docsite/rst/dev_guide/developing_inventory.rst +++ b/docs/docsite/rst/dev_guide/developing_inventory.rst @@ -508,7 +508,5 @@ An easy way to see how this should look is using :ref:`ansible-inventory`, which How to develop plugins `AWX `_ REST API endpoint and GUI for Ansible, syncs with dynamic inventory - `Development Mailing List `_ - Mailing list for development topics - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_modules.rst b/docs/docsite/rst/dev_guide/developing_modules.rst index d8eb2a56189..42d6d6fa3cd 100644 --- a/docs/docsite/rst/dev_guide/developing_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_modules.rst @@ -45,7 +45,5 @@ If your use case isn't covered by an existing module, an action plugin, or a rol :ref:`list_of_collections` Browse existing collections, modules, and plugins - `Mailing List `_ - Development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst index c64f3f4170d..405389750e6 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst @@ -31,7 +31,7 @@ To contribute a module to most Ansible collections, you must: Additional requirements may apply for certain collections. Review the individual collection repositories for more information. -Please make sure your module meets these requirements before you submit your PR/proposal. If you have questions, reach out by using the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) or the `Ansible development mailing list `_. +Please make sure your module meets these requirements before you submit your PR/proposal. If you have questions, visit the :ref:`Ansible communication guide` for information on how to reach out to the community. Contributing to Ansible: subjective requirements ================================================ diff --git a/docs/docsite/rst/dev_guide/developing_modules_general.rst b/docs/docsite/rst/dev_guide/developing_modules_general.rst index be0b5030e00..44db07f92b4 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general.rst @@ -173,11 +173,7 @@ The :ref:`Community Guide ` covers how to open a pull r Communication and development support ===================================== -Join the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) for discussions surrounding Ansible development. - -For questions and discussions pertaining to using the Ansible product, join the ``#ansible`` channel. - -To find other topic-specific chat channels, look at :ref:`Community Guide, Communicating `. +Visit the :ref:`Ansible communication guide` for information on how to join the conversation. Credit ====== diff --git a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst index 1ad3365e1ab..6c74ffc44d3 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst @@ -738,7 +738,4 @@ idempotent and does not report changes. For example: Windows communication and development support ============================================= -Join the ``#ansible-devel`` or ``#ansible-windows`` chat channels (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) for discussions about Ansible development for Windows. - -For questions and discussions pertaining to using the Ansible product, -use the ``#ansible`` channel. +Join the :ref:`Ansible Forum` and use the `windows` tag for discussions about Ansible development for Windows. diff --git a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst index 0091159cf6c..8298f6c0d8b 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst @@ -43,20 +43,14 @@ It is convenient if the organization and repository names on GitHub (or elsewher Speak to us =========== -Circulating your ideas before coding helps you adopt good practices and avoid common mistakes. After reading the "Before you start coding" section you should have a reasonable idea of the structure of your modules. Write a list of your proposed plugin and/or module names, with a short description of what each one does. Circulate that list on IRC or a mailing list so the Ansible community can review your ideas for consistency and familiarity. Names and functionality that are consistent, predictable, and familiar make your collection easier to use. +Circulating your ideas before coding helps you adopt good practices and avoid common mistakes. After reading the "Before you start coding" section you should have a reasonable idea of the structure of your modules. Write a list of your proposed plugin and/or module names, with a short description of what each one does. Circulate that list on the :ref:`Ansible Forum` so the Ansible community can review your ideas for consistency and familiarity. Names and functionality that are consistent, predictable, and familiar make your collection easier to use. .. _developing_in_groups_support: Where to get support ==================== -Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered. - -In the :ref:`ansible_community_guide` you can find how to: - -* Subscribe to the Mailing Lists - We suggest "Ansible Development List" and "Ansible Announce list" -* ``#ansible-devel`` - We have found that communicating on the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) works best for developers so we can have an interactive dialog. -* Working group and other chat channel meetings - Join the various weekly meetings `meeting schedule page `_ +Ansible has a thriving and knowledgeable community of module developers that is a great resource for getting your questions answered. Visit the :ref:`Ansible communication guide` for details. Required files ============== @@ -70,8 +64,6 @@ Your collection should include the following files to be usable: When you have these files ready, review the :ref:`developing_modules_checklist` again. If you are creating a new collection, you are responsible for all procedures related to your repository, including setting rules for contributions, finding reviewers, and testing and maintaining the code in your collection. -If you need help or advice, consider joining the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_). For more information, see :ref:`developing_in_groups_support` and :ref:`communication`. - New to git or GitHub ==================== diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index cf29d066be7..d45ac41a397 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -568,9 +568,7 @@ For example vars plugins, see the source code for the `vars plugins included wit Learn about how to develop dynamic inventory sources :ref:`developing_modules_general` Learn about how to write Ansible modules - `Mailing List `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide :ref:`adjacent_yaml_doc` Alternate YAML files as documentation diff --git a/docs/docsite/rst/dev_guide/developing_rebasing.rst b/docs/docsite/rst/dev_guide/developing_rebasing.rst index dcd1fb07c43..e08ac451db4 100644 --- a/docs/docsite/rst/dev_guide/developing_rebasing.rst +++ b/docs/docsite/rst/dev_guide/developing_rebasing.rst @@ -89,7 +89,7 @@ You should check in on the status of your PR after tests have completed to see i Getting help rebasing ===================== -For help with rebasing your PR, or other development related questions, join us on the #ansible-devel chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_). +If you need any help with rebasing your PR, or you have other development related questions, visit the :ref:`Ansible communication guide` for information on how to reach out to the community. .. seealso:: diff --git a/docs/docsite/rst/dev_guide/sidecar.rst b/docs/docsite/rst/dev_guide/sidecar.rst index ccf3aa75efa..3b1621f29c4 100644 --- a/docs/docsite/rst/dev_guide/sidecar.rst +++ b/docs/docsite/rst/dev_guide/sidecar.rst @@ -94,7 +94,5 @@ YAML documentation is mainly intended for filters, tests and modules. While it i Learn about how to develop dynamic inventory sources :ref:`developing_modules_general` Learn about how to write Ansible modules - `Mailing List `_ - The development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst index 033b70b6ae4..59fdb400caf 100644 --- a/docs/docsite/rst/dev_guide/style_guide/index.rst +++ b/docs/docsite/rst/dev_guide/style_guide/index.rst @@ -481,5 +481,5 @@ These pages offer more help with grammatical, stylistic, and technical rules for How to contribute to the Ansible documentation :ref:`testing_documentation_locally` How to build the Ansible documentation - `irc.libera.chat `_ - #ansible-docs IRC chat channel + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/dev_guide/style_guide/resources.rst b/docs/docsite/rst/dev_guide/style_guide/resources.rst index 64dc0c1dd57..c5b94ac5b18 100644 --- a/docs/docsite/rst/dev_guide/style_guide/resources.rst +++ b/docs/docsite/rst/dev_guide/style_guide/resources.rst @@ -1,7 +1,7 @@ Resources ^^^^^^^^^ * Follow the style of the :ref:`Ansible Documentation` -* Ask for advice on the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) +* Ask the community for advice. Visit the :ref:`Ansible communication guide` for details. * Review these online style guides: * `AP Stylebook `_ diff --git a/docs/docsite/rst/dev_guide/testing.rst b/docs/docsite/rst/dev_guide/testing.rst index aef6edfa314..51a37524fa2 100644 --- a/docs/docsite/rst/dev_guide/testing.rst +++ b/docs/docsite/rst/dev_guide/testing.rst @@ -89,8 +89,7 @@ If either issue appears to be the case, you can rerun the Azure Pipelines test b * closing and re-opening the pull request (full rebuild) * making another change to the branch and pushing to GitHub -If the issue persists, please contact us in the ``#ansible-devel`` chat channel (using `Matrix `_ or using IRC at `irc.libera.chat `_). - +If the issue persists, please contact the community. Visit the :ref:`Ansible communication guide` for details. How to test a PR ================ diff --git a/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst b/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst index 08e6e65c3e0..bc97b2e3cd5 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst @@ -182,4 +182,4 @@ Each issue will be assigned to one of the following projects: Questions --------- -For questions about integration tests reach out to @mattclay or @gundalow on GitHub or the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_). +For questions about integration tests reach out to the community on the :ref:`Ansible Forum` by creating a topic tagged with ``ansible-test``, ``testing`` and other appropriate tags. diff --git a/docs/docsite/rst/dev_guide/testing_units_modules.rst b/docs/docsite/rst/dev_guide/testing_units_modules.rst index 9296da6b0e6..520d2981c1d 100644 --- a/docs/docsite/rst/dev_guide/testing_units_modules.rst +++ b/docs/docsite/rst/dev_guide/testing_units_modules.rst @@ -18,7 +18,7 @@ The document doesn't apply to other parts of Ansible for which the recommendatio normally closer to the Python standard. There is basic documentation for Ansible unit tests in the developer guide :ref:`testing_units`. This document should be readable for a new Ansible module author. If you find it incomplete or confusing, -please open a bug or ask for help on the #ansible-devel chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_). +please open a bug or ask for help on the :ref:`Ansible Forum`. What Are Unit Tests? ==================== @@ -279,8 +279,7 @@ Ansible special cases for unit testing There are a number of special cases for unit testing the environment of an Ansible module. The most common are documented below, and suggestions for others can be found by looking -at the source code of the existing unit tests or asking on the Ansible chat channel or mailing -lists. For more information on joining chat channels and subscribing to mailing lists, see :ref:`communication`. +at the source code of the existing unit tests or :ref:`asking the community`. Module argument processing -------------------------- @@ -564,6 +563,8 @@ the code in Ansible to trigger that failure. .. seealso:: + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide :ref:`testing_units` Ansible unit tests documentation :ref:`testing_running_locally` @@ -576,8 +577,6 @@ the code in Ansible to trigger that failure. The documentation of the earliest supported unittest framework - from Python 2.6 `pytest: helps you write better programs `_ The documentation of pytest - the framework actually used to run Ansible unit tests - `Development Mailing List `_ - Mailing list for development topics `Testing Your Code (from The Hitchhiker's Guide to Python!) `_ General advice on testing Python code `Uncle Bob's many videos on YouTube `_ diff --git a/docs/docsite/rst/galaxy/dev_guide.rst b/docs/docsite/rst/galaxy/dev_guide.rst index 2ff284160e7..43193a0dd61 100644 --- a/docs/docsite/rst/galaxy/dev_guide.rst +++ b/docs/docsite/rst/galaxy/dev_guide.rst @@ -206,11 +206,9 @@ Provide the ID of the integration to be disabled. You can find the ID by using t .. seealso:: - :ref:`collections` - Shareable collections of modules, playbooks and roles - :ref:`playbooks_reuse_roles` - All about ansible roles - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`collections` + Shareable collections of modules, playbooks and roles + :ref:`playbooks_reuse_roles` + All about ansible roles + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/inventory_guide/intro_dynamic_inventory.rst b/docs/docsite/rst/inventory_guide/intro_dynamic_inventory.rst index a9583dfffab..cd8ee99b180 100644 --- a/docs/docsite/rst/inventory_guide/intro_dynamic_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_dynamic_inventory.rst @@ -164,7 +164,5 @@ the dynamic groups as empty in the static inventory file. For example: :ref:`intro_inventory` All about static inventory files - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index fb6c1f68023..1e7286c6033 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -789,7 +789,5 @@ their location. Examples of basic commands :ref:`working_with_playbooks` Learning Ansible's configuration, deployment, and orchestration language. - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/inventory_guide/intro_patterns.rst b/docs/docsite/rst/inventory_guide/intro_patterns.rst index 039a41b4d90..ac75090a33f 100644 --- a/docs/docsite/rst/inventory_guide/intro_patterns.rst +++ b/docs/docsite/rst/inventory_guide/intro_patterns.rst @@ -276,7 +276,5 @@ To apply your knowledge of patterns with Ansible commands and playbooks, read :r Examples of basic commands :ref:`working_with_playbooks` Learning the Ansible configuration management language - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/module_plugin_guide/modules_intro.rst b/docs/docsite/rst/module_plugin_guide/modules_intro.rst index 486202cb37b..3a6411715fd 100644 --- a/docs/docsite/rst/module_plugin_guide/modules_intro.rst +++ b/docs/docsite/rst/module_plugin_guide/modules_intro.rst @@ -56,10 +56,7 @@ For a list of all available modules, see the :ref:`Collection docs `_ - Questions? Help? Ideas? Stop by the list on Google Groups - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide :ref:`all_modules_and_plugins` All modules and plugins available - diff --git a/docs/docsite/rst/module_plugin_guide/modules_support.rst b/docs/docsite/rst/module_plugin_guide/modules_support.rst index 566ae438834..fdb1c210699 100644 --- a/docs/docsite/rst/module_plugin_guide/modules_support.rst +++ b/docs/docsite/rst/module_plugin_guide/modules_support.rst @@ -47,7 +47,7 @@ If you find a bug that affects a plugin in a Galaxy collection: Some partner collections may be hosted in private repositories. -If you are not sure whether the behavior you see is a bug, if you have questions, if you want to discuss development-oriented topics, or if you just want to get in touch, use one of our Google mailing lists or chat channels (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) to :ref:`communicate with Ansiblers `. +If you are not sure whether the behavior you see is a bug, if you have questions, if you want to discuss development-oriented topics, or if you just want to get in touch, visit the :ref:`Ansible communication guide` for information on how to join the community. If you find a bug that affects a module in an Automation Hub collection: @@ -64,7 +64,5 @@ All plugins that remain in ``ansible-core`` and all collections hosted in Automa Examples of using modules in /usr/bin/ansible :ref:`working_with_playbooks` Examples of using modules with /usr/bin/ansible-playbook - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst index 7ed80ce1d51..3df7870ac9f 100644 --- a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst +++ b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst @@ -718,7 +718,7 @@ For more options: ansible-test network-integration --help -If you need additional help or feedback, reach out in the ``#ansible-network`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_). +If you need additional help or feedback, reach out to the community. Visit the :ref:`Ansible communication guide` for details. Unit test requirements ----------------------- diff --git a/docs/docsite/rst/network/getting_started/network_resources.rst b/docs/docsite/rst/network/getting_started/network_resources.rst index a69aba905d7..fd636506175 100644 --- a/docs/docsite/rst/network/getting_started/network_resources.rst +++ b/docs/docsite/rst/network/getting_started/network_resources.rst @@ -8,6 +8,11 @@ Resources and next steps .. contents:: :local: +Community +========= + +Visit the :ref:`Ansible communication guide` for information on how to join the community. + Documents ========= @@ -35,13 +40,7 @@ Ansible hosts module code, examples, demonstrations, and other content on GitHub - `Ansible collections `_ is the main repository for Ansible-maintained and community collections, including collections for network devices. - - Chat channels ============= -Got questions? Chat with us on: - -* the ``#ansible-network`` channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) - -* `Ansible Network Slack `_ - Network & Security Automation Slack community. Check out the #devel channel for discussions on module and plugin development. +Visit the :ref:`Ansible communication guide` for information on how to join the conversation including available chat options. diff --git a/docs/docsite/rst/os_guide/intro_bsd.rst b/docs/docsite/rst/os_guide/intro_bsd.rst index 36ae0c9876b..18a3eb3ddc4 100644 --- a/docs/docsite/rst/os_guide/intro_bsd.rst +++ b/docs/docsite/rst/os_guide/intro_bsd.rst @@ -272,7 +272,5 @@ Please feel free to report any issues or incompatibilities you discover with BSD Learning Ansible's configuration management language :ref:`developing_modules` How to write modules - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/os_guide/windows_dsc.rst b/docs/docsite/rst/os_guide/windows_dsc.rst index f140bf43f35..5b75e00eb70 100644 --- a/docs/docsite/rst/os_guide/windows_dsc.rst +++ b/docs/docsite/rst/os_guide/windows_dsc.rst @@ -502,7 +502,5 @@ Setup IIS Website Tips and tricks for playbooks :ref:`List of Windows Modules ` Windows-specific module list, all implemented in PowerShell - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/os_guide/windows_faq.rst b/docs/docsite/rst/os_guide/windows_faq.rst index 231b5c661ed..08b962b893f 100644 --- a/docs/docsite/rst/os_guide/windows_faq.rst +++ b/docs/docsite/rst/os_guide/windows_faq.rst @@ -243,7 +243,5 @@ host. An introduction to playbooks :ref:`playbooks_best_practices` Tips and tricks for playbooks - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/os_guide/windows_setup.rst b/docs/docsite/rst/os_guide/windows_setup.rst index c31d20138f4..7010ce5e609 100644 --- a/docs/docsite/rst/os_guide/windows_setup.rst +++ b/docs/docsite/rst/os_guide/windows_setup.rst @@ -501,7 +501,5 @@ Using SSH with Windows is experimental. Currently, existing issues are: Tips and tricks for playbooks :ref:`List of Windows Modules ` Windows-specific module list, all implemented in PowerShell - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/os_guide/windows_usage.rst b/docs/docsite/rst/os_guide/windows_usage.rst index c37fcb218d9..10b6db9ca19 100644 --- a/docs/docsite/rst/os_guide/windows_usage.rst +++ b/docs/docsite/rst/os_guide/windows_usage.rst @@ -513,7 +513,5 @@ guides for Windows modules differ substantially from those for standard standard Tips and tricks for playbooks :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/os_guide/windows_winrm.rst b/docs/docsite/rst/os_guide/windows_winrm.rst index 909955679fd..dbf0fd27b85 100644 --- a/docs/docsite/rst/os_guide/windows_winrm.rst +++ b/docs/docsite/rst/os_guide/windows_winrm.rst @@ -1030,7 +1030,5 @@ Some of these limitations can be mitigated by doing one of the following: Tips and tricks for playbooks :ref:`List of Windows Modules ` Windows-specific module list, all implemented in PowerShell - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst index c23dc5a7e17..e542f1164bc 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst @@ -116,7 +116,5 @@ You've anchored the value of ``version`` with the ``&my_version`` anchor and reu All about variables :ref:`complex_data_manipulation` Doing complex data manipulation in Ansible - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_async.rst b/docs/docsite/rst/playbook_guide/playbooks_async.rst index 7ce38faf979..17349feeb58 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_async.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_async.rst @@ -183,7 +183,5 @@ To run multiple asynchronous tasks while limiting the number of tasks running co Options for controlling playbook execution :ref:`playbooks_intro` An introduction to playbooks - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst index dac527894b9..c521ff7e3b6 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst @@ -218,7 +218,5 @@ These can be inspected in the ``rescue`` section: An introduction to playbooks :ref:`playbooks_reuse_roles` Playbook organization by roles - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst index 19a36be16f8..bfd8fd09c4a 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst @@ -600,7 +600,5 @@ Possible values (sample, not complete list): Tips and tricks for playbooks :ref:`playbooks_variables` All about variables - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst index 4f32c04a2d0..1c4fc845d8c 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst @@ -336,7 +336,5 @@ With the default ``linear`` strategy enabled, Ansible halts execution while the Running playbooks while debugging or testing :ref:`playbooks_intro` An introduction to playbooks - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_delegation.rst b/docs/docsite/rst/playbook_guide/playbooks_delegation.rst index bdf3649911d..3a4e9bb4c40 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_delegation.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_delegation.rst @@ -177,7 +177,5 @@ use the default remote connection type: An introduction to playbooks :ref:`playbooks_strategies` More ways to control how and where Ansible executes - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_environment.rst b/docs/docsite/rst/playbook_guide/playbooks_environment.rst index d4fe6094f51..e948dc941c7 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_environment.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_environment.rst @@ -147,7 +147,5 @@ You can also specify the environment at the task level. :ref:`playbooks_intro` An introduction to playbooks - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst index 1d05f204207..8e2a3cb4b97 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst @@ -277,7 +277,5 @@ You can also use blocks to define responses to task errors. This approach is sim Conditional statements in playbooks :ref:`playbooks_variables` All about variables - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index c7ce2190a39..b9f475a4cd8 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -2216,9 +2216,7 @@ This can then be used to reference hashes in Pod specifications: Playbook organization by roles :ref:`tips_and_tricks` Tips and tricks for playbooks - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide `Python 3 Regular expression operations `_ How to use inline regular expression flags diff --git a/docs/docsite/rst/playbook_guide/playbooks_intro.rst b/docs/docsite/rst/playbook_guide/playbooks_intro.rst index 469a8006f8d..dcf2966bd74 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_intro.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_intro.rst @@ -171,5 +171,5 @@ The `ansible-lint default rules `_ - Questions? Help? Ideas? Stop by the list on Google Groups + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_lookups.rst b/docs/docsite/rst/playbook_guide/playbooks_lookups.rst index ee49513ac7f..5ab335ae061 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_lookups.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_lookups.rst @@ -33,7 +33,5 @@ For more details and a list of lookup plugins in ansible-core, see :ref:`plugins All about variables :ref:`playbooks_loops` Looping in playbooks - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index 7c6fb9dac6f..d61e857cfa2 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -588,7 +588,5 @@ Migrating from with_X to loop Conditional statements in playbooks :ref:`playbooks_variables` All about variables - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst b/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst index 56169edc36e..1166a174498 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_privilege_escalation.rst @@ -769,7 +769,5 @@ Limitations of become on Windows .. seealso:: - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_prompts.rst b/docs/docsite/rst/playbook_guide/playbooks_prompts.rst index d962352cb2c..50e90231ab2 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_prompts.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_prompts.rst @@ -118,7 +118,5 @@ Some special characters, such as ``{`` and ``%`` can create templating errors. I Conditional statements in playbooks :ref:`playbooks_variables` All about variables - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse.rst index e2306110f2a..c4c5966d54c 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse.rst @@ -220,5 +220,5 @@ Imports are processed before the play begins, so the name of the import no longe Tips and tricks for playbooks :ref:`ansible_galaxy` How to share roles on galaxy, role management - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst index ea9c39f73c0..386869059e3 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_reuse_roles.rst @@ -760,5 +760,5 @@ Read the `Ansible Galaxy documentation `_ - Questions? Help? Ideas? Stop by the list on Google Groups + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_strategies.rst b/docs/docsite/rst/playbook_guide/playbooks_strategies.rst index 97b620a4898..83d75751574 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_strategies.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_strategies.rst @@ -248,7 +248,5 @@ As always with :ref:`delegation `, the action will be exec Running tasks on or assigning facts to specific machines :ref:`playbooks_reuse_roles` Playbook organization by roles - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst index 5069e09fdfb..98d782c0d2e 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst @@ -479,7 +479,5 @@ If you run or skip certain tags by default, you can use the :ref:`TAGS_RUN` and An introduction to playbooks :ref:`playbooks_reuse_roles` Playbook organization by roles - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_templating.rst b/docs/docsite/rst/playbook_guide/playbooks_templating.rst index 9cc971ea28c..506a17dab3e 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_templating.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_templating.rst @@ -61,7 +61,5 @@ Our test.j2: Tips and tricks for playbooks `Jinja2 Docs `_ Jinja2 documentation, includes the syntax and semantics of the templates - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_tests.rst b/docs/docsite/rst/playbook_guide/playbooks_tests.rst index 4a298ef8099..15905a06218 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tests.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tests.rst @@ -536,7 +536,5 @@ When looking to determine types, it may be tempting to use the ``type_debug`` fi Playbook organization by roles :ref:`tips_and_tricks` Tips and tricks for playbooks - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/playbook_guide/playbooks_variables.rst b/docs/docsite/rst/playbook_guide/playbooks_variables.rst index 54492a96aef..940c96b5dd2 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_variables.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_variables.rst @@ -592,7 +592,5 @@ For information about advanced YAML syntax used to declare variables and have mo Tips and tricks for playbooks :ref:`special_variables` List of special variables - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/action.rst b/docs/docsite/rst/plugins/action.rst index e61ded2dc52..862786cec94 100644 --- a/docs/docsite/rst/plugins/action.rst +++ b/docs/docsite/rst/plugins/action.rst @@ -49,7 +49,5 @@ Use ``ansible-doc `` to see plugin-specific documentation and examples. Th Strategy plugins :ref:`vars_plugins` Vars plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst index dc0c8753102..d7030adbdd6 100644 --- a/docs/docsite/rst/plugins/connection.rst +++ b/docs/docsite/rst/plugins/connection.rst @@ -64,7 +64,5 @@ Use ``ansible-doc -t connection `` to see plugin-specific documenta Lookup plugins :ref:`vars_plugins` Vars plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/docs_fragment.rst b/docs/docsite/rst/plugins/docs_fragment.rst index fc0d923b545..a134780da9b 100644 --- a/docs/docsite/rst/plugins/docs_fragment.rst +++ b/docs/docsite/rst/plugins/docs_fragment.rst @@ -29,7 +29,5 @@ Only collection developers and maintainers use docs fragments. For more informat An introduction to creating Ansible modules :ref:`developing_collections` A guide to creating Ansible collections - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/filter.rst b/docs/docsite/rst/plugins/filter.rst index 2923ce5e6f6..4ec98d33270 100644 --- a/docs/docsite/rst/plugins/filter.rst +++ b/docs/docsite/rst/plugins/filter.rst @@ -57,7 +57,5 @@ You can use ``ansible-doc -t filter -l`` to see the list of available plugins. U Test plugins :ref:`lookup_plugins` Lookup plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/httpapi.rst b/docs/docsite/rst/plugins/httpapi.rst index 09e07677517..4b9657b1bc0 100644 --- a/docs/docsite/rst/plugins/httpapi.rst +++ b/docs/docsite/rst/plugins/httpapi.rst @@ -68,7 +68,5 @@ Use ``ansible-doc -t httpapi `` to see plugin-specific documentatio An overview of using Ansible to automate networking devices. :ref:`Developing network modules` How to develop network modules. - `User Mailing List `_ - Have a question? Stop by the Google group! - `irc.libera.chat `_ - #ansible-network IRC chat channel + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst index 9a9ff627a32..d01ebc0c279 100644 --- a/docs/docsite/rst/plugins/inventory.rst +++ b/docs/docsite/rst/plugins/inventory.rst @@ -185,7 +185,5 @@ Use ``ansible-doc -t inventory `` to see plugin-specific documentat Lookup plugins :ref:`vars_plugins` Vars plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/lookup.rst b/docs/docsite/rst/plugins/lookup.rst index 4f9cd860953..1bda2954e6b 100644 --- a/docs/docsite/rst/plugins/lookup.rst +++ b/docs/docsite/rst/plugins/lookup.rst @@ -161,7 +161,5 @@ You can use ``ansible-doc -t lookup -l`` to see the list of available plugins. U Jinja2 filter plugins :ref:`test_plugins` Jinja2 test plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/module.rst b/docs/docsite/rst/plugins/module.rst index a2083bc09d1..64f2f60de77 100644 --- a/docs/docsite/rst/plugins/module.rst +++ b/docs/docsite/rst/plugins/module.rst @@ -37,7 +37,5 @@ For information on using modules in ad hoc tasks, see :ref:`intro_adhoc`. For in An introduction to creating Ansible modules :ref:`developing_collections` A guide to creating Ansible collections - `User Mailing List `_ - Have a question? Stop by the Google group! - `irc.libera.chat `_ - #ansible-devel IRC chat channel + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/module_util.rst b/docs/docsite/rst/plugins/module_util.rst index c9dc7747e2f..3e5d03cce7c 100644 --- a/docs/docsite/rst/plugins/module_util.rst +++ b/docs/docsite/rst/plugins/module_util.rst @@ -29,7 +29,5 @@ For information on using module utilities, see :ref:`developing_module_utilities An introduction to creating Ansible modules :ref:`developing_collections` A guide to creating Ansible collections - `User Mailing List `_ - Have a question? Stop by the Google group! - `irc.libera.chat `_ - #ansible-devel IRC chat channel + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/netconf.rst b/docs/docsite/rst/plugins/netconf.rst index eeba1061faa..7f7581c9591 100644 --- a/docs/docsite/rst/plugins/netconf.rst +++ b/docs/docsite/rst/plugins/netconf.rst @@ -43,7 +43,5 @@ Use ``ansible-doc -t netconf `` to see plugin-specific documentatio :ref:`Ansible for Network Automation` An overview of using Ansible to automate networking devices. - `User Mailing List `_ - Have a question? Stop by the Google group! - `irc.libera.chat `_ - #ansible-network IRC chat channel + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/plugins.rst b/docs/docsite/rst/plugins/plugins.rst index 1c1355e081b..317c4aeae01 100644 --- a/docs/docsite/rst/plugins/plugins.rst +++ b/docs/docsite/rst/plugins/plugins.rst @@ -42,7 +42,5 @@ This section covers the various types of plugins that are included with Ansible: Ansible configuration documentation and settings :ref:`command_line_tools` Ansible tools, description and options - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/shell.rst b/docs/docsite/rst/plugins/shell.rst index 96597e76262..97fa6407888 100644 --- a/docs/docsite/rst/plugins/shell.rst +++ b/docs/docsite/rst/plugins/shell.rst @@ -52,7 +52,5 @@ You can use ``ansible-doc -t shell -l`` to see the list of available plugins. Us Test plugins :ref:`lookup_plugins` Lookup plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/strategy.rst b/docs/docsite/rst/plugins/strategy.rst index 3a3ea8a95e6..4c0d6cb9f50 100644 --- a/docs/docsite/rst/plugins/strategy.rst +++ b/docs/docsite/rst/plugins/strategy.rst @@ -80,7 +80,5 @@ Use ``ansible-doc -t strategy `` to see plugin-specific documentati Test plugins :ref:`lookup_plugins` Lookup plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/terminal.rst b/docs/docsite/rst/plugins/terminal.rst index 7bc4c39aa3b..c399c97ca4f 100644 --- a/docs/docsite/rst/plugins/terminal.rst +++ b/docs/docsite/rst/plugins/terminal.rst @@ -36,7 +36,5 @@ Plugins are self-documenting. Each plugin should document its configuration opti An overview of using Ansible to automate networking devices. :ref:`connection_plugins` Connection plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - `irc.libera.chat `_ - #ansible-network IRC chat channel + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/test.rst b/docs/docsite/rst/plugins/test.rst index ee81bdd32ae..49378b3273c 100644 --- a/docs/docsite/rst/plugins/test.rst +++ b/docs/docsite/rst/plugins/test.rst @@ -94,7 +94,5 @@ You can use ``ansible-doc -t test -l`` to see the list of available plugins. Use Using tests :ref:`lookup_plugins` Lookup plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst index c4117b58034..1793ba68050 100644 --- a/docs/docsite/rst/plugins/vars.rst +++ b/docs/docsite/rst/plugins/vars.rst @@ -61,7 +61,5 @@ You can use ``ansible-doc -t vars -l`` to see the list of available vars plugins Cache plugins :ref:`lookup_plugins` Lookup plugins - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index b8262c98cd9..b445dfe3da1 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -272,12 +272,10 @@ value: YAML Lint (online) helps you debug YAML syntax if you are having problems `Wikipedia YAML syntax reference `_ A good guide to YAML syntax - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups - :ref:`communication_irc` - How to join Ansible chat channels (join #yaml for yaml-specific questions) `YAML 1.1 Specification `_ The Specification for YAML 1.1, which PyYAML and libyaml are currently implementing `YAML 1.2 Specification `_ For completeness, YAML 1.2 is the successor of 1.1 + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/reference_appendices/common_return_values.rst b/docs/docsite/rst/reference_appendices/common_return_values.rst index 7ef8c69e951..561a05ad3b5 100644 --- a/docs/docsite/rst/reference_appendices/common_return_values.rst +++ b/docs/docsite/rst/reference_appendices/common_return_values.rst @@ -245,7 +245,5 @@ This key contains a list of dictionaries that will be presented to the user. Key Browse existing collections, modules, and plugins `GitHub modules directory `_ Browse source of core and extras modules - `Mailing List `_ - Development mailing list - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 2e36ea8a012..eb985bd21fd 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -943,7 +943,7 @@ Though, if you do not override the ``shell`` module, you can also just write it I don't see my question here ++++++++++++++++++++++++++++ -If you have not found an answer to your questions, you can ask on one of our mailing lists or chat channels. For instructions on subscribing to a list or joining a chat channel, see :ref:`communication`. +If you have not found an answer to your questions, ask the community! Visit the :ref:`Ansible communication guide` for details. .. seealso:: @@ -951,5 +951,5 @@ If you have not found an answer to your questions, you can ask on one of our mai An introduction to playbooks :ref:`playbooks_best_practices` Tips and tricks for playbooks - `User Mailing List `_ - Have a question? Stop by the Google group! + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst index a2cf6bc559c..dbe442a8ef3 100644 --- a/docs/docsite/rst/reference_appendices/glossary.rst +++ b/docs/docsite/rst/reference_appendices/glossary.rst @@ -5,7 +5,7 @@ The following is a list (and re-explanation) of term definitions used elsewhere Consult the documentation home page for the full documentation and to see the terms in context, but this should be a good resource to check your knowledge of Ansible's components and understand how they fit together. It is something you might wish to read for review or -when a term comes up on the mailing list. +when a term comes up on the :ref:`Ansible Forum`. .. glossary:: @@ -534,7 +534,5 @@ when a term comes up on the mailing list. An introduction to playbooks :ref:`playbooks_best_practices` Tips and tricks for playbooks - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 3275814d471..3a114c1d276 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -430,7 +430,5 @@ The deprecation cycle in ``ansible-core`` is normally across 4 feature releases Testing strategies :ref:`ansible_community_guide` Community information and contributing - `Development Mailing List `_ - Mailing list for development topics - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/reference_appendices/test_strategies.rst b/docs/docsite/rst/reference_appendices/test_strategies.rst index 2cef3139f34..0d05ffa1ecb 100644 --- a/docs/docsite/rst/reference_appendices/test_strategies.rst +++ b/docs/docsite/rst/reference_appendices/test_strategies.rst @@ -297,7 +297,5 @@ system. An introduction to playbooks :ref:`playbooks_delegation` Delegation, useful for working with load balancers, clouds, and locally executed steps. - `User Mailing List `_ - Have a question? Stop by the Google group! - :ref:`communication_irc` - How to join Ansible chat channels + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_11.rst b/docs/docsite/rst/roadmap/COLLECTIONS_11.rst index 809454bd721..7d8a333c335 100644 --- a/docs/docsite/rst/roadmap/COLLECTIONS_11.rst +++ b/docs/docsite/rst/roadmap/COLLECTIONS_11.rst @@ -84,5 +84,9 @@ Ansible 11.x minor releases may contain new features (including new collections) We will not provide bugfixes or security fixes for collections that do not provide updates for their major release cycle included in Ansible 11. +Communication +============= -For more information, reach out on a mailing list or a chat channel - see :ref:`communication` for more details. +You can submit feedback on the current roadmap by creating a :ref:`community topic`. + +Visit the :ref:`Ansible communication guide` for details on how to join and use Ansible communication platforms. diff --git a/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst b/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst index 02e964e406d..17b565a77ac 100644 --- a/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst +++ b/docs/docsite/rst/roadmap/ansible_core_roadmap_index.rst @@ -12,12 +12,7 @@ Each roadmap offers a *best guess*, based on the ``ansible-core`` team's experie Each roadmap is published both as an idea of what is upcoming in ``ansible-core``, and as a medium for seeking further feedback from the community. -You can submit feedback on the current roadmap in multiple ways: - -- Post on the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) -- Email the ansible-devel list - -See :ref:`Ansible communication channels ` for details on how to join and use the email lists and chat channels. +You can submit feedback on the current roadmap by creating a topic on the :ref:`Ansible Forum` tagged with ``ansible-core``. .. toctree:: :maxdepth: 1 diff --git a/docs/docsite/rst/roadmap/ansible_roadmap_index.rst b/docs/docsite/rst/roadmap/ansible_roadmap_index.rst index 060fc4b1175..410fc3fbc38 100644 --- a/docs/docsite/rst/roadmap/ansible_roadmap_index.rst +++ b/docs/docsite/rst/roadmap/ansible_roadmap_index.rst @@ -12,12 +12,9 @@ Each roadmap offers a *best guess*, based on the Ansible team's experience and o Each roadmap is published both as an idea of what is upcoming in Ansible, and as a medium for seeking further feedback from the community. -You can submit feedback on the current roadmap in multiple ways: +You can submit feedback on the current roadmap by creating a :ref:`community topic`. -- Edit the agenda of an `Ansible Community Meeting `_ (preferred) -- Post on the ``#ansible-community`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat `_) - -See :ref:`Ansible communication channels ` for details on how to join and use our chat channels. +Visit the :ref:`Ansible communication guide` for details on how to join and use Ansible communication platforms. .. toctree:: :maxdepth: 1 diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index 32102873c46..ac8a370ff2c 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -206,5 +206,5 @@ This pulls in variables from the `group_vars/os_CentOS.yml` file. Learn how to extend Ansible by writing your own modules :ref:`intro_patterns` Learn about how to select hosts - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide diff --git a/docs/docsite/rst/tips_tricks/sample_setup.rst b/docs/docsite/rst/tips_tricks/sample_setup.rst index 87215d0a889..351095e8fdb 100644 --- a/docs/docsite/rst/tips_tricks/sample_setup.rst +++ b/docs/docsite/rst/tips_tricks/sample_setup.rst @@ -289,5 +289,5 @@ If a playbook has a :file:`./library` directory relative to its YAML file, you c Learn how to extend Ansible by writing your own modules :ref:`intro_patterns` Learn about how to select hosts - `Mailing List `_ - Questions? Help? Ideas? Stop by the list on Google Groups + :ref:`Communication` + Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide From 7761910e47c1d4a558143c87111ee113a5e48935 Mon Sep 17 00:00:00 2001 From: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> Date: Thu, 12 Sep 2024 07:05:01 -0400 Subject: [PATCH 497/536] Add documentation for loop_control option to stop a loop early (#1764) * Add documentation for loop_control.break_when option * Add a more practical example --- .../rst/playbook_guide/playbooks_loops.rst | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/docsite/rst/playbook_guide/playbooks_loops.rst b/docs/docsite/rst/playbook_guide/playbooks_loops.rst index d61e857cfa2..ff862a02dea 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_loops.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_loops.rst @@ -387,6 +387,33 @@ To control the time (in seconds) between the execution of each item in a task lo loop_control: pause: 3 +Breaking out of a loop +---------------------- +.. versionadded:: 2.18 + +Use the ``break_when`` directive with ``loop_control`` to exit a loop after any item, based on Jinja2 expressions. + +.. code-block:: yaml+jinja + + # main.yml + - name: Use set_fact in a loop until a condition is met + vars: + special_characters: "!@#$%^&*(),.?:{}|<>" + character_set: "digits,ascii_letters,{{ special_characters }}" + password_policy: '^(?=.*\d)(?=.*[A-Z])(?=.*[{{ special_characters | regex_escape }}]).{12,}$' + block: + - name: Generate a password until it contains a digit, uppercase letter, and special character (10 attempts) + set_fact: + password: "{{ lookup('password', '/dev/null', chars=character_set, length=12) }}" + loop: "{{ range(0, 10) }}" + loop_control: + break_when: + - password is match(password_policy) + + - fail: + msg: "Maximum attempts to generate a valid password exceeded" + when: password is not match(password_policy) + Tracking progress through a loop with ``index_var`` --------------------------------------------------- .. versionadded:: 2.5 From 9f3e3f4b7c3b9335f5488bb6150c7397ba18e039 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Thu, 12 Sep 2024 14:10:58 +0200 Subject: [PATCH 498/536] Change Getting started EE guide reference to point to the relevant location (#1877) --- docs/docsite/rst/collections_guide/collections_installing.rst | 2 +- docs/docsite/rst/command_guide/index.rst | 2 +- .../collection_contributors/collection_requirements.rst | 2 +- docs/docsite/rst/dev_guide/developing_collections_structure.rst | 2 +- docs/docsite/rst/installation_guide/intro_installation.rst | 2 +- docs/docsite/rst/shared_snippets/basic_concepts.txt | 2 +- docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/docsite/rst/collections_guide/collections_installing.rst b/docs/docsite/rst/collections_guide/collections_installing.rst index 12f6e67f4b8..880f78de4a7 100644 --- a/docs/docsite/rst/collections_guide/collections_installing.rst +++ b/docs/docsite/rst/collections_guide/collections_installing.rst @@ -11,7 +11,7 @@ Installing collections in containers ------------------------------------ You can install collections with their dependencies in containers known as Execution Environments. -See `Getting started with Execution Environments `_ for details. +See :ref:`getting_started_ee_index` for details. Installing collections with ``ansible-galaxy`` ---------------------------------------------- diff --git a/docs/docsite/rst/command_guide/index.rst b/docs/docsite/rst/command_guide/index.rst index 4027e3493d7..ca5b41d0e88 100644 --- a/docs/docsite/rst/command_guide/index.rst +++ b/docs/docsite/rst/command_guide/index.rst @@ -25,5 +25,5 @@ Ansible provides ad hoc commands and several utilities for performing various op `Ansible Navigator `_ A command-line tool and a TUI that provides a convenient user interface for most of the native Ansible command-line utilities and allows to run Ansible automation content - inside containers (`Execution Environments `_) + inside containers (:ref:`Execution Environments`) diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index 92e140a19a0..acd549632bb 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -199,7 +199,7 @@ Example: `meta/runtime.yml `_ building, they SHOULD be listed in corresponding files under the ``meta`` directory, specified in ``meta/execution-environment.yml``, and `verified `_. +If a collection has controller-side Python package and/or system package requirements, to allow easy :ref:`execution environment` building, they SHOULD be listed in corresponding files under the ``meta`` directory, specified in ``meta/execution-environment.yml``, and `verified `_. See the `Collection-level dependencies guide `_ for more information and `collection_template/meta `_ directory content as an example. diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index 6a82af60b69..6c15c31973e 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -290,7 +290,7 @@ execution_environments.yml ^^^^^^^^^^^^^^^^^^^^^^^^^^ If your collection has requirements, you can specify them in the ``execution-environment.yml`` file in the ``meta`` directory. -This ensures users do not need to add these requirements manually when building `Execution Environments `_ containing your collection. +This ensures users do not need to add these requirements manually when building :ref:`Execution Environments` containing your collection. See the `collection-level metadata guide `_ for details. .. seealso:: diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 0526359984c..87d77a87967 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -194,7 +194,7 @@ Installing Ansible to containers ================================ Instead of installing Ansible content manually, you can simply build an execution environment container image or use one of the available community images as your control node. -See the `Getting started with Execution Environments guide `_ for details. +See :ref:`getting_started_ee_index` for details. .. _development_install: diff --git a/docs/docsite/rst/shared_snippets/basic_concepts.txt b/docs/docsite/rst/shared_snippets/basic_concepts.txt index a4f7ce06130..2b2c3efeeb6 100644 --- a/docs/docsite/rst/shared_snippets/basic_concepts.txt +++ b/docs/docsite/rst/shared_snippets/basic_concepts.txt @@ -2,7 +2,7 @@ Control node ============ The machine from which you run the Ansible CLI tools (``ansible-playbook`` , ``ansible``, ``ansible-vault`` and others). You can use any computer that meets the software requirements as a control node - laptops, shared desktops, and servers can all run Ansible. -You can also run Ansible in containers known as `Execution Environments `_. +You can also run Ansible in containers known as :ref:`Execution Environments`. Multiple control nodes are possible, but Ansible itself does not coordinate across them, see ``AAP`` for such features. diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index ac8a370ff2c..88746d3d8be 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -132,7 +132,7 @@ These tips apply to using Ansible, rather than to Ansible artifacts. Use Execution Environments -------------------------- -Reduce complexity with portable container images known as `Execution Environments `_. +Reduce complexity with portable container images known as :ref:`Execution Environments`. Try it in staging first ----------------------- From de21da12e12e5cda21c6c82bf6ae5442cf429b77 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 11 Sep 2024 17:55:55 -0500 Subject: [PATCH 499/536] nox clone-core: allow passing extra args to script --- noxfile.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/noxfile.py b/noxfile.py index 2f1bc3e5a5c..66f328eb954 100644 --- a/noxfile.py +++ b/noxfile.py @@ -136,7 +136,7 @@ def clone_core(session: nox.Session): Clone relevant portions of ansible-core from ansible/ansible into the current source tree to facilitate building docs. """ - session.run_always("python", "docs/bin/clone-core.py") + session.run_always("python", "docs/bin/clone-core.py", *session.posargs) checker_tests = [ From b09a2009ba2a58d7a660f8ea694a2ac6063177c1 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Wed, 11 Sep 2024 17:57:44 -0500 Subject: [PATCH 500/536] clone-core: update clone core script to remove old files See the linked issue. The lingering setup.py and setup.cfg files from older versions of ansible-core were breaking a local user's doc build. The clone-core script should automatically remove these. Relates: https://github.com/ansible/ansible/issues/83937 --- docs/bin/clone-core.py | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/bin/clone-core.py b/docs/bin/clone-core.py index 9df817f8929..5412aca15b6 100755 --- a/docs/bin/clone-core.py +++ b/docs/bin/clone-core.py @@ -18,6 +18,7 @@ DEFAULT_BRANCH = (ROOT / "docs" / "ansible-core-branch.txt").read_text().strip() DEFAULT_ANSIBLE_CORE_REPO = "https://github.com/ansible/ansible" +"""Directories to copy from ansible-core into the ansible-documentation tree""" KEEP_DIRS = ( "bin", "lib", @@ -25,12 +26,22 @@ "test/lib", ) +"""Files to copy from ansible-core into the ansible-documentation tree""" KEEP_FILES = ( "MANIFEST.in", "pyproject.toml", "requirements.txt", ) +"""Files to remove after cloning ansible-core""" +REMOVE_FILES = ( + # See https://github.com/ansible/ansible/commit/68515abf97dfc769c9aed2ba457ed7b8b2580a5c + # ansible-core removed setup.py and setup.cfg so we need to make sure to + # remove those when syncing the new version. + "setup.py", + "setup.cfg", +) + @dataclasses.dataclass() class Args: @@ -71,11 +82,31 @@ def parse_args(args: list[str] | None = None) -> Args: return Args(**vars(parser.parse_args(args))) +def remove_files(directory: pathlib.Path = pathlib.Path.cwd()) -> list[pathlib.Path]: + removed: list[pathlib.Path] = [] + for file in REMOVE_FILES: + path = directory / file + if path.is_file(): + print(f"Removing {file!r} ...") + path.unlink() + removed.append(path) + return removed + + def main(args: Args) -> None: + # Start by removing extra files + removed_files = remove_files() + if ( + # Check is enabled args.check + # All core files exist and all(pathlib.Path(file).is_file() for file in KEEP_FILES) + # All core directories exist and all(pathlib.Path(directory).is_dir() for directory in KEEP_DIRS) + # If any extra files are still around, that means our checkout is out + # of date and needs to be refreshed. + and not removed_files ): print("The necessary core files already exist.") print("Run 'nox -e clone-core' without --check to update the core files.") From 8ed3fc754ae1684fe4f40460cf43035efa514b2f Mon Sep 17 00:00:00 2001 From: Jordan Borean Date: Fri, 13 Sep 2024 23:52:35 +1000 Subject: [PATCH 501/536] Revamp Windows docs (#1820) * Revamp Windows docs Rearranges the docs for Windows to expand on the different connection types outside of winrm. Also removes a lot of the old and outdated information that is no longer needed as the affected OS versions are end of life and no longer supported by Ansible. * Apply suggestions from code review Co-authored-by: Don Naro * Fix orphaned links and other changes * Update after rebase and fix some links and indentation --------- Co-authored-by: Don Naro --- .../installation_distros.rst | 4 +- docs/docsite/rst/os_guide/index.rst | 9 +- docs/docsite/rst/os_guide/intro_windows.rst | 173 +++ docs/docsite/rst/os_guide/windows_dsc.rst | 8 +- docs/docsite/rst/os_guide/windows_faq.rst | 245 +--- docs/docsite/rst/os_guide/windows_setup.rst | 505 +------- docs/docsite/rst/os_guide/windows_ssh.rst | 198 ++++ docs/docsite/rst/os_guide/windows_winrm.rst | 1056 +++++------------ .../os_guide/windows_winrm_certificate.rst | 212 ++++ .../rst/os_guide/windows_winrm_kerberos.rst | 298 +++++ .../os_guide/yaml/winrm_cert_auth_setup.yaml | 118 ++ docs/docsite/rst/user_guide/windows_faq.rst | 2 +- docs/docsite/rst/user_guide/windows_setup.rst | 2 +- 13 files changed, 1341 insertions(+), 1489 deletions(-) create mode 100644 docs/docsite/rst/os_guide/intro_windows.rst create mode 100644 docs/docsite/rst/os_guide/windows_ssh.rst create mode 100644 docs/docsite/rst/os_guide/windows_winrm_certificate.rst create mode 100644 docs/docsite/rst/os_guide/windows_winrm_kerberos.rst create mode 100644 docs/docsite/rst/os_guide/yaml/winrm_cert_auth_setup.yaml diff --git a/docs/docsite/rst/installation_guide/installation_distros.rst b/docs/docsite/rst/installation_guide/installation_distros.rst index 26a69f5fc7f..da4b4b94a9b 100644 --- a/docs/docsite/rst/installation_guide/installation_distros.rst +++ b/docs/docsite/rst/installation_guide/installation_distros.rst @@ -68,7 +68,7 @@ Installing Ansible on OpenSUSE Tumbleweed/Leap .. code-block:: bash $ sudo zypper install ansible - + See `OpenSUSE Support Portal `_ for additional help with Ansible on OpenSUSE. .. _from_apt: @@ -170,7 +170,7 @@ Please `open an issue ` +* SSH - :ref:`ssh ` +* Windows Remote Management - :ref:`winrm ` + +PSRP and WinRM +"""""""""""""" + +Historically Ansible used Windows Remote Management (``WinRM``) as the connection protocol to manage Windows nodes. The ``psrp`` and ``winrm`` connection plugins both operate over WinRM and can be used as the connection plugin for Windows nodes. The ``psrp`` connection plugin is a newer connection plugin that offers a few benefits over the ``winrm`` connection plugin, for example: + +* Can be slightly faster +* Less susceptible to timeout issues when the Windows node is under load +* Better support for proxy servers + +See :ref:`windows_winrm` for more information on how WinRM is configured and how to use the ``psrp`` and ``winrm`` connection plugins in Ansible. + +SSH +""" + +SSH is the traditional connection plugin used with POSIX nodes but it can also be used to manage Windows nodes instead of the traditional ``psrp`` or ``winrm`` connection plugins. + +.. note:: + While Ansible has supported using the SSH connection plugin with Windows nodes since Ansible 2.8, official support was only added in version 2.18. + +Some of the benefits of using SSH over the WinRM based transports are: + +* SSH can be easier to configure in non-domain environments +* SSH supports key based authentication which is simpler to manage than certificates +* SSH file transfers are faster than WinRM + +See :ref:`windows_ssh` for more information on how to configure SSH for Windows nodes. + +Which modules are available? +---------------------------- + +The majority of the core Ansible modules are written for a combination of Unix-like machines and other generic services. As these modules are written in Python and use APIs not present on Windows they will not work. + +There are dedicated Windows modules that are written in PowerShell and are meant to be run on Windows hosts. A list of these modules can be in the :ref:`plugins_in_ansible.windows`, :ref:`plugins_in_community.windows`, :ref:`plugins_in_microsoft.ad`, :ref:`plugins_in_chocolatey.chocolatey`, and other collections. + +In addition, the following Ansible Core modules/action-plugins work with Windows: + +* add_host +* assert +* async_status +* debug +* fail +* fetch +* group_by +* include +* include_role +* include_vars +* meta +* pause +* raw +* script +* set_fact +* set_stats +* setup +* slurp +* template (also: win_template) +* wait_for_connection + +.. _windows_control_node: + +Using Windows as the control node +--------------------------------- + +Ansible cannot run on Windows as the control node due to API limitations on the platform. However, you can run Ansible on Windows using the Windows Subsystem for Linux (``WSL``) or in a container. + +.. note:: + The Windows Subsystem for Linux is not supported by Ansible and should not be used for production systems. + +Windows facts +------------- + +Ansible gathers facts from Windows in a similar manner to other POSIX hosts but with some differences. Some facts may be in a different format for backwards compatibility or may not be available at all. + +To see the facts that Ansible gathers from Windows hosts, run the ``setup`` module. + +.. code-block:: bash + + ansible windows -m setup + +Common Windows problems +----------------------- + +Command works locally but not under Ansible +""""""""""""""""""""""""""""""""""""""""""" + +Ansible executes commands through a network logon which can change how Windows authorizes actions. This can cause commands that work locally to fail under Ansible. Some examples of these failures are: + +* the process cannot delegate the user's credentials to a network resource, causing ``Access is Denied`` or ``Resource Unavailable`` errors +* applications that require an interactive session will not work +* some Windows APIs are restricted when running through a network logon +* some tasks require access to the ``DPAPI`` secrets store which is typically not available on a network logon + +The common way is to use :ref:`become` to run a command with explicit credentials. Using ``become`` on Windows will change the network logon to an interactive one and, if explicit credentials are provided to the become identity, the command will be able to access network resources and unlock the ``DPAPI`` store. + +Another option is to use an authentication option on the connection plugin that allows for credential delegation. For SSH this can be done with an explicit username and password or through a Kerberos/GSSAPI logon with delegation enabled. For WinRM based connections, the CredSSP or Kerberos with delegation can be used. See the connection specific documentation for more information. + +Credentials are rejected +"""""""""""""""""""""""" + +There are a few reasons why credentials might be rejected when connecting to the Windows host. Some common reasons are: + +* the username or password is incorrect +* the user account is locked out, disabled, not allowed to log onto that server +* the user account is not allowed to log on through the network +* the user account is not a member of the local Administrators group +* the user account is a local user and the ``LocalAccountTokenFilterPolicy`` is not set + +To verify whether the credentials are correct or the user is allowed to log onto the host you can run the below PowerShell command on the Windows host to see the last failed logon attempt. This will output event details including the ``Status`` and ``Sub Status`` error code indicating why the logon failed. + +.. code-block:: powershell + + Get-WinEvent -FilterHashtable @{LogName = 'Security'; Id = 4625} | + Select-Object -First 1 -ExpandProperty Message + +While not all connection plugins require the connection user to be a member of the local Administrators group, this is typically the default configuration. If the user is not a member of the local Administrators group or is a local user without ``LocalAccountTokenFilterPolicy`` set, the authentication will fail. + +.. seealso:: + + :ref:`intro_adhoc` + Examples of basic commands + :ref:`working_with_playbooks` + Learning Ansible's configuration management language + :ref:`developing_modules` + How to write modules + :ref:`windows_dsc` + Using Ansible with Windows Desired State Configuration + :ref:`windows_performance` + Performance considerations for managing Windows hosts + :ref:`windows_usage` + Windows usage guide + `Mailing List `_ + Questions? Help? Ideas? Stop by the list on Google Groups + :ref:`communication_irc` + How to join Ansible chat channels diff --git a/docs/docsite/rst/os_guide/windows_dsc.rst b/docs/docsite/rst/os_guide/windows_dsc.rst index 5b75e00eb70..59b05f55313 100644 --- a/docs/docsite/rst/os_guide/windows_dsc.rst +++ b/docs/docsite/rst/os_guide/windows_dsc.rst @@ -203,7 +203,7 @@ For example, to define a ``[CimInstance]`` value in Ansible: .. code-block:: yaml+jinja - # [CimInstance]AuthenticationInfo == MSFT_xWebAuthenticationInformation + # [CimInstance]AuthenticationInfo == DSC_WebAuthenticationInformation AuthenticationInfo: Anonymous: false Basic: true @@ -211,7 +211,7 @@ For example, to define a ``[CimInstance]`` value in Ansible: Windows: true In the above example, the CIM instance is a representation of the class -`MSFT_xWebAuthenticationInformation `_. +`DSC_WebAuthenticationInformation `_. This class accepts four boolean variables, ``Anonymous``, ``Basic``, ``Digest``, and ``Windows``. The keys to use in a ``[CimInstance]`` depend on the class it represents. Please read through the documentation of the resource @@ -253,7 +253,7 @@ like this example: .. code-block:: yaml+jinja - # [CimInstance[]]BindingInfo == MSFT_xWebBindingInformation + # [CimInstance[]]BindingInfo == DSC_WebBindingInformation BindingInfo: - Protocol: https Port: 443 @@ -266,7 +266,7 @@ like this example: Port: 80 IPAddress: '*' -The above example is an array with two values of the class `MSFT_xWebBindingInformation `_. +The above example is an array with two values of the class `DSC_WebBindingInformation `_. When defining a ``[CimInstance[]]``, be sure to read the resource documentation to find out what keys to use in the definition. diff --git a/docs/docsite/rst/os_guide/windows_faq.rst b/docs/docsite/rst/os_guide/windows_faq.rst index 08b962b893f..ec937f8d13b 100644 --- a/docs/docsite/rst/os_guide/windows_faq.rst +++ b/docs/docsite/rst/os_guide/windows_faq.rst @@ -1,247 +1,6 @@ -.. _windows_faq: +:orphan: Windows Frequently Asked Questions ================================== -Here are some commonly asked questions in regard to Ansible and Windows and -their answers. - -.. note:: This document covers questions about managing Microsoft Windows servers with Ansible. - For questions about Ansible Core, please see the - :ref:`general FAQ page `. - -Does Ansible work with Windows XP or Server 2003? -`````````````````````````````````````````````````` -Ansible does not work with Windows XP or Server 2003 hosts. Ansible does work with these Windows operating system versions: - -* Windows Server 2016 -* Windows Server 2019 -* Windows Server 2022 -* Windows 10 -* Windows 11 - -Support for Windows Server 2008, 2008 R2, and Windows 7 ended in the 2.10 -release. Support for Windows Server 2012, 2012 R2, Windows 8, and 8.1 ended in -the 2.16 release. - -Ansible also has minimum PowerShell version requirements - please see -:ref:`windows_setup` for the latest information. - -Can I manage Windows Nano Server with Ansible? -`````````````````````````````````````````````` -Ansible does not currently work with Windows Nano Server, since it does -not have access to the full .NET Framework that is used by the majority of the -modules and internal components. - -.. _windows_faq_ansible: - -Can Ansible run on Windows? -``````````````````````````` -No, Ansible can only manage Windows hosts. Ansible cannot run on a Windows host -natively, though it can run under the Windows Subsystem for Linux (WSL). - -.. note:: The Windows Subsystem for Linux is not supported by Ansible and - should not be used for production systems. - -To install Ansible on WSL, the following commands -can be run in the bash terminal: - -.. code-block:: shell - - sudo apt-get update - sudo apt-get install python3-pip git libffi-dev libssl-dev -y - pip install --user ansible pywinrm - -To run Ansible from source instead of a release on the WSL, simply uninstall the pip -installed version and then clone the git repo. - -.. code-block:: shell - - pip uninstall ansible -y - git clone https://github.com/ansible/ansible.git - source ansible/hacking/env-setup - - # To enable Ansible on login, run the following - echo ". ~/ansible/hacking/env-setup -q' >> ~/.bashrc - -If you encounter timeout errors when running Ansible on the WSL, this may be due to an issue -with ``sleep`` not returning correctly. The following workaround may resolve the issue: - -.. code-block:: shell - - mv /usr/bin/sleep /usr/bin/sleep.orig - ln -s /bin/true /usr/bin/sleep - -Another option is to use WSL 2 if running Windows 10 later than build 2004. - -.. code-block:: shell - - wsl --set-default-version 2 - - -Can I use SSH keys to authenticate to Windows hosts? -```````````````````````````````````````````````````` -You cannot use SSH keys with the WinRM or PSRP connection plugins. -These connection plugins use X509 certificates for authentication instead -of the SSH key pairs that SSH uses. - -The way X509 certificates are generated and mapped to a user is different -from the SSH implementation; consult the :ref:`windows_winrm` documentation for -more information. - -Ansible 2.8 has added an experimental option to use the SSH connection plugin, -which uses SSH keys for authentication, for Windows servers. See :ref:`this question ` -for more information. - -.. _windows_faq_winrm: - -Why can I run a command locally that does not work under Ansible? -````````````````````````````````````````````````````````````````` -Ansible executes commands through WinRM. These processes are different from -running a command locally in these ways: - -* Unless using an authentication option like CredSSP or Kerberos with - credential delegation, the WinRM process cannot - delegate the user's credentials to a network resource, causing ``Access is - Denied`` errors. - -* All processes run under WinRM are in a non-interactive session. Applications - that require an interactive session will not work. - -* When running through WinRM, Windows restricts access to internal Windows - APIs like the Windows Update API and DPAPI, which some installers and - programs rely on. - -Some ways to bypass these restrictions are to: - -* Use ``become``, which runs a command as it would when run locally. This will - bypass most WinRM restrictions, as Windows is unaware the process is running - under WinRM when ``become`` is used. See the :ref:`become` documentation for more - information. - -* Use a scheduled task, which can be created with ``win_scheduled_task``. Like - ``become``, it will bypass all WinRM restrictions, but it can only be used to run - commands, not modules. - -* Use ``win_psexec`` to run a command on the host. PSExec does not use WinRM - and so will bypass any of the restrictions. - -* To access network resources without any of these workarounds, you can use - CredSSP or Kerberos with credential delegation enabled. - -See :ref:`become` more info on how to use become. The limitations section at -:ref:`windows_winrm` has more details about WinRM limitations. - -This program won't install on Windows with Ansible -`````````````````````````````````````````````````` -See :ref:`this question ` for more information about WinRM limitations. - -What Windows modules are available? -``````````````````````````````````` -Most of the Ansible modules in Ansible Core are written for a combination of -Linux/Unix machines and arbitrary web services. These modules are written in -Python and most of them do not work on Windows. - -Because of this, there are dedicated Windows modules that are written in -PowerShell and are meant to be run on Windows hosts. A list of these modules -can be found :ref:`here `. - -In addition, the following Ansible Core modules/action-plugins work with Windows: - -* add_host -* assert -* async_status -* debug -* fail -* fetch -* group_by -* include -* include_role -* include_vars -* meta -* pause -* raw -* script -* set_fact -* set_stats -* setup -* slurp -* template (also: win_template) -* wait_for_connection - -Ansible Windows modules exist in the :ref:`plugins_in_ansible.windows`, :ref:`plugins_in_community.windows`, and :ref:`plugins_in_chocolatey.chocolatey` collections. - -Can I run Python modules on Windows hosts? -`````````````````````````````````````````` -No, the WinRM connection protocol is set to use PowerShell modules, so Python -modules will not work. A way to bypass this issue is to use -``delegate_to: localhost`` to run a Python module on the Ansible control node. -This is useful if during a playbook, an external service needs to be contacted -and there is no equivalent Windows module available. - -.. _windows_faq_ssh: - -Can I connect to Windows hosts over SSH? -```````````````````````````````````````` -Ansible 2.8 has added an experimental option to use the SSH connection plugin -to manage Windows hosts. To connect to Windows hosts over SSH, you must install and configure the `Win32-OpenSSH `_ -fork that is in development with Microsoft on -the Windows host(s). While most of the basics should work with SSH, -``Win32-OpenSSH`` is rapidly changing, with new features added and bugs -fixed in every release. It is highly recommend you `install `_ the latest release -of ``Win32-OpenSSH`` from the GitHub Releases page when using it with Ansible -on Windows hosts. - -To use SSH as the connection to a Windows host, set the following variables in -the inventory: - -.. code-block:: shell - - ansible_connection=ssh - - # Set either cmd or powershell not both - ansible_shell_type=cmd - # ansible_shell_type=powershell - -The value for ``ansible_shell_type`` should either be ``cmd`` or ``powershell``. -Use ``cmd`` if the ``DefaultShell`` has not been configured on the SSH service -and ``powershell`` if that has been set as the ``DefaultShell``. - -Why is connecting to a Windows host through SSH failing? -```````````````````````````````````````````````````````` -Unless you are using ``Win32-OpenSSH`` as described above, you must connect to -Windows hosts using :ref:`windows_winrm`. If your Ansible output indicates that -SSH was used, either you did not set the connection vars properly or the host is not inheriting them correctly. - -Make sure ``ansible_connection: winrm`` is set in the inventory for the Windows -host(s). - -Why are my credentials being rejected? -`````````````````````````````````````` -This can be due to a myriad of reasons unrelated to incorrect credentials. - -See HTTP 401/Credentials Rejected at :ref:`windows_setup` for a more detailed -guide of this could mean. - -Why am I getting an error SSL CERTIFICATE_VERIFY_FAILED? -```````````````````````````````````````````````````````` -When the Ansible control node is running on Python 2.7.9+ or an older version of Python that -has backported SSLContext (like Python 2.7.5 on RHEL 7), the control node will attempt to -validate the certificate WinRM is using for an HTTPS connection. If the -certificate cannot be validated (such as in the case of a self-signed cert), it will -fail the verification process. - -To ignore certificate validation, add -``ansible_winrm_server_cert_validation: ignore`` to inventory for the Windows -host. - -.. seealso:: - - :ref:`windows` - The Windows documentation index - :ref:`about_playbooks` - An introduction to playbooks - :ref:`playbooks_best_practices` - Tips and tricks for playbooks - :ref:`Communication` - Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide +This page has moved to :ref:`working_with_windows`. \ No newline at end of file diff --git a/docs/docsite/rst/os_guide/windows_setup.rst b/docs/docsite/rst/os_guide/windows_setup.rst index 7010ce5e609..2ae30b78b25 100644 --- a/docs/docsite/rst/os_guide/windows_setup.rst +++ b/docs/docsite/rst/os_guide/windows_setup.rst @@ -1,505 +1,6 @@ -.. _windows_setup: +:orphan: -Setting up a Windows Host +Setting up a windows Host ========================= -This document discusses the setup that is required before Ansible can communicate with a Microsoft Windows host. -.. contents:: - :local: - -Host Requirements -````````````````` -For Ansible to communicate with a Windows host and use Windows modules, the -Windows host must meet these base requirements for connectivity: - -* With Ansible you can generally manage Windows versions under the current and extended support from Microsoft. You can also manage desktop OSs including Windows 10 and 11, and server OSs including Windows Server 2016, 2019, and 2022. - -* You need to install PowerShell 5.1 or newer and at least .NET 4.0 on the Windows host. - -* You need to create and activate a WinRM listener. More details, see :ref:`winrm_listener`. - -.. Note:: Some Ansible modules have additional requirements, such as a newer OS or PowerShell version. Consult the module documentation page to determine whether a host meets those requirements. - -Upgrading PowerShell and .NET Framework ---------------------------------------- -Ansible requires PowerShell version 5.1 and .NET Framework 4.6 or newer to function. The base image for older unsupported OS' does not meet these -requirements. You can use the `Upgrade-PowerShell.ps1 `_ script to update these. - -This is an example of how to run this script from PowerShell: - -.. code-block:: powershell - - [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 - $url = "https://raw.githubusercontent.com/jborean93/ansible-windows/master/scripts/Upgrade-PowerShell.ps1" - $file = "$env:temp\Upgrade-PowerShell.ps1" - $username = "Administrator" - $password = "Password" - - (New-Object -TypeName System.Net.WebClient).DownloadFile($url, $file) - Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Force - - &$file -Version 5.1 -Username $username -Password $password -Verbose - -In the script, the ``file`` value can be the PowerShell version 3.0, 4.0, or 5.1. - -Once completed, you need to run the following PowerShell commands: - -1. As an optional but good security practice, you can set the execution policy back to the default. - -.. code-block:: powershell - - Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Force - -Use the ``RemoteSigned`` value for Windows servers, or ``Restricted`` for Windows clients. - -2. Remove the auto logon. - -.. code-block:: powershell - - $reg_winlogon_path = "HKLM:\Software\Microsoft\Windows NT\CurrentVersion\Winlogon" - Set-ItemProperty -Path $reg_winlogon_path -Name AutoAdminLogon -Value 0 - Remove-ItemProperty -Path $reg_winlogon_path -Name DefaultUserName -ErrorAction SilentlyContinue - Remove-ItemProperty -Path $reg_winlogon_path -Name DefaultPassword -ErrorAction SilentlyContinue - -The script determines what programs you need to install (such as .NET Framework 4.5.2) and what PowerShell version needs to be present. If a reboot is needed and the ``username`` and ``password`` parameters are set, the script will automatically reboot the machine and then logon. If the ``username`` and ``password`` parameters are not set, the script will prompt the user to manually reboot and logon when required. When the user is next logged in, the script will continue where it left off and the process continues until no more -actions are required. - -.. Note:: If you run the script on Server 2008, then you need to install SP2. For Server 2008 R2 or Windows 7, you need SP1. - - On Windows Server 2008, you can install only PowerShell 3.0. A newer version will result in the script failure. - - The ``username`` and ``password`` parameters are stored in plain text in the registry. Run the cleanup commands after the script finishes to ensure no credentials are stored on the host. - - -WinRM Memory Hotfix -------------------- -On PowerShell v3.0, there is a bug that limits the amount of memory available to the WinRM service. Use the `Install-WMF3Hotfix.ps1 `_ script to install a hotfix on affected hosts as part of the system bootstrapping or imaging process. Without this hotfix, Ansible fails to execute certain commands on the Windows host. - -To install the hotfix: - -.. code-block:: powershell - - [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 - $url = "https://raw.githubusercontent.com/jborean93/ansible-windows/master/scripts/Install-WMF3Hotfix.ps1" - $file = "$env:temp\Install-WMF3Hotfix.ps1" - - (New-Object -TypeName System.Net.WebClient).DownloadFile($url, $file) - powershell.exe -ExecutionPolicy ByPass -File $file -Verbose - -For more details, refer to the `"Out of memory" error on a computer that has a customized MaxMemoryPerShellMB quota set and has WMF 3.0 installed `_ article. - -WinRM Setup -``````````` -You need to configure the WinRM service so that Ansible can connect to it. There are two main components of the WinRM service that govern how Ansible can interface with the Windows host: the ``listener`` and the ``service`` configuration settings. - -.. Note:: - The script for setting up this service is `available to download on GitHub `_. - Reason being that using it can cause several issues for the user. Chances are it will be completely taken down in the future. - - - -.. _winrm_listener: - -WinRM Listener --------------- -The WinRM services listen for requests on one or more ports. Each of these ports must have a listener created and configured. - -To view the current listeners that are running on the WinRM service: - -.. code-block:: powershell - - winrm enumerate winrm/config/Listener - -This will output something like: - -.. code-block:: powershell - - Listener - Address = * - Transport = HTTP - Port = 5985 - Hostname - Enabled = true - URLPrefix = wsman - CertificateThumbprint - ListeningOn = 10.0.2.15, 127.0.0.1, 192.168.56.155, ::1, fe80::5efe:10.0.2.15%6, fe80::5efe:192.168.56.155%8, fe80:: - ffff:ffff:fffe%2, fe80::203d:7d97:c2ed:ec78%3, fe80::e8ea:d765:2c69:7756%7 - - Listener - Address = * - Transport = HTTPS - Port = 5986 - Hostname = SERVER2016 - Enabled = true - URLPrefix = wsman - CertificateThumbprint = E6CDAA82EEAF2ECE8546E05DB7F3E01AA47D76CE - ListeningOn = 10.0.2.15, 127.0.0.1, 192.168.56.155, ::1, fe80::5efe:10.0.2.15%6, fe80::5efe:192.168.56.155%8, fe80:: - ffff:ffff:fffe%2, fe80::203d:7d97:c2ed:ec78%3, fe80::e8ea:d765:2c69:7756%7 - -In the example above there are two listeners activated. One is listening on port 5985 over HTTP and the other is listening on port 5986 over HTTPS. Some of the key options that are useful to understand are: - -* ``Transport``: Whether the listener is run over HTTP or HTTPS. We recommend you use a listener over HTTPS because the data is encrypted without any further changes required. - -* ``Port``: The port the listener runs on. By default, it is ``5985`` for HTTP and ``5986`` for HTTPS. This port can be changed to whatever is required and corresponds to the host var ``ansible_port``. - -* ``URLPrefix``: The URL prefix to listen on. By default, it is ``wsman``. If you change this option, you need to set the host var ``ansible_winrm_path`` to the same value. - -* ``CertificateThumbprint``: If you use an HTTPS listener, this is the thumbprint of the certificate in the Windows Certificate Store that is used in the connection. To get the details of the certificate itself, run this command with the relevant certificate thumbprint in PowerShell: - -.. code-block:: powershell - - $thumbprint = "E6CDAA82EEAF2ECE8546E05DB7F3E01AA47D76CE" - Get-ChildItem -Path cert:\LocalMachine\My -Recurse | Where-Object { $_.Thumbprint -eq $thumbprint } | Select-Object * - -Setup WinRM Listener -++++++++++++++++++++ -There are three ways to set up a WinRM listener: - -* Using ``winrm quickconfig`` for HTTP or ``winrm quickconfig -transport:https`` for HTTPS. This is the easiest option to use when running outside of a domain environment and a simple listener is required. Unlike the other options, this process also has the added benefit of opening up the firewall for the ports required and starting the WinRM service. - -* Using Group Policy Objects (GPO). This is the best way to create a listener when the host is a member of a domain because the configuration is done automatically without any user input. For more information on group policy objects, see the `Group Policy Objects documentation `_. - -* Using PowerShell to create a listener with a specific configuration. This can be done by running the following PowerShell commands: - - .. code-block:: powershell - - $selector_set = @{ - Address = "*" - Transport = "HTTPS" - } - $value_set = @{ - CertificateThumbprint = "E6CDAA82EEAF2ECE8546E05DB7F3E01AA47D76CE" - } - - New-WSManInstance -ResourceURI "winrm/config/Listener" -SelectorSet $selector_set -ValueSet $value_set - - To see the other options with this PowerShell command, refer to the - `New-WSManInstance `_ documentation. - -.. Note:: When creating an HTTPS listener, you must create and store a certificate in the ``LocalMachine\My`` certificate store. - -Delete WinRM Listener -+++++++++++++++++++++ -* To remove all WinRM listeners: - -.. code-block:: powershell - - Remove-Item -Path WSMan:\localhost\Listener\* -Recurse -Force - -* To remove only those listeners that run over HTTPS: - -.. code-block:: powershell - - Get-ChildItem -Path WSMan:\localhost\Listener | Where-Object { $_.Keys -contains "Transport=HTTPS" } | Remove-Item -Recurse -Force - -.. Note:: The ``Keys`` object is an array of strings, so it can contain different values. By default, it contains a key for ``Transport=`` and ``Address=`` which correspond to the values from the ``winrm enumerate winrm/config/Listeners`` command. - -WinRM Service Options ---------------------- -You can control the behavior of the WinRM service component, including authentication options and memory settings. - -To get an output of the current service configuration options, run the following command: - -.. code-block:: powershell - - winrm get winrm/config/Service - winrm get winrm/config/Winrs - -This will output something like: - -.. code-block:: powershell - - Service - RootSDDL = O:NSG:BAD:P(A;;GA;;;BA)(A;;GR;;;IU)S:P(AU;FA;GA;;;WD)(AU;SA;GXGW;;;WD) - MaxConcurrentOperations = 4294967295 - MaxConcurrentOperationsPerUser = 1500 - EnumerationTimeoutms = 240000 - MaxConnections = 300 - MaxPacketRetrievalTimeSeconds = 120 - AllowUnencrypted = false - Auth - Basic = true - Kerberos = true - Negotiate = true - Certificate = true - CredSSP = true - CbtHardeningLevel = Relaxed - DefaultPorts - HTTP = 5985 - HTTPS = 5986 - IPv4Filter = * - IPv6Filter = * - EnableCompatibilityHttpListener = false - EnableCompatibilityHttpsListener = false - CertificateThumbprint - AllowRemoteAccess = true - - Winrs - AllowRemoteShellAccess = true - IdleTimeout = 7200000 - MaxConcurrentUsers = 2147483647 - MaxShellRunTime = 2147483647 - MaxProcessesPerShell = 2147483647 - MaxMemoryPerShellMB = 2147483647 - MaxShellsPerUser = 2147483647 - -You do not need to change the majority of these options. However, some of the important ones to know about are: - -* ``Service\AllowUnencrypted`` - specifies whether WinRM will allow HTTP traffic without message encryption. Message level encryption is only possible when the ``ansible_winrm_transport`` variable is ``ntlm``, ``kerberos`` or ``credssp``. By default, this is ``false`` and you should only set it to ``true`` when debugging WinRM messages. - -* ``Service\Auth\*`` - defines what authentication options you can use with the WinRM service. By default, ``Negotiate (NTLM)`` and ``Kerberos`` are enabled. - -* ``Service\Auth\CbtHardeningLevel`` - specifies whether channel binding tokens are not verified (None), verified but not required (Relaxed), or verified and required (Strict). CBT is only used when connecting with NT LAN Manager (NTLM) or Kerberos over HTTPS. - -* ``Service\CertificateThumbprint`` - thumbprint of the certificate for encrypting the TLS channel used with CredSSP authentication. By default, this is empty. A self-signed certificate is generated when the WinRM service starts and is used in the TLS process. - -* ``Winrs\MaxShellRunTime`` - maximum time, in milliseconds, that a remote command is allowed to execute. - -* ``Winrs\MaxMemoryPerShellMB`` - maximum amount of memory allocated per shell, including its child processes. - -To modify a setting under the ``Service`` key in PowerShell, you need to provide a path to the option after ``winrm/config/Service``: - -.. code-block:: powershell - - Set-Item -Path WSMan:\localhost\Service\{path} -Value {some_value} - -For example, to change ``Service\Auth\CbtHardeningLevel``: - -.. code-block:: powershell - - Set-Item -Path WSMan:\localhost\Service\Auth\CbtHardeningLevel -Value Strict - -To modify a setting under the ``Winrs`` key in PowerShell, you need to provide a path to the option after ``winrm/config/Winrs``: - -.. code-block:: powershell - - Set-Item -Path WSMan:\localhost\Shell\{path} -Value {some_value} - -For example, to change ``Winrs\MaxShellRunTime``: - -.. code-block:: powershell - - Set-Item -Path WSMan:\localhost\Shell\MaxShellRunTime -Value 2147483647 - -.. Note:: If you run the command in a domain environment, some of these options are set by - GPO and cannot be changed on the host itself. When you configure a key with GPO, it contains the text ``[Source="GPO"]`` next to the value. - -Common WinRM Issues -------------------- -WinRM has a wide range of configuration options, which makes its configuration complex. As a result, errors that Ansible displays could in fact be problems with the host setup instead. - -To identify a host issue, run the following command from another Windows host to connect to the target Windows host. - -* To test HTTP: - -.. code-block:: powershell - - winrs -r:http://server:5985/wsman -u:Username -p:Password ipconfig - -* To test HTTPS: - -.. code-block:: powershell - - winrs -r:https://server:5986/wsman -u:Username -p:Password -ssl ipconfig - -The command will fail if the certificate is not verifiable. - -* To test HTTPS ignoring certificate verification: - -.. code-block:: powershell - - $username = "Username" - $password = ConvertTo-SecureString -String "Password" -AsPlainText -Force - $cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $username, $password - - $session_option = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck - Invoke-Command -ComputerName server -UseSSL -ScriptBlock { ipconfig } -Credential $cred -SessionOption $session_option - -If any of the above commands fail, the issue is probably related to the WinRM setup. - -HTTP 401/Credentials Rejected -+++++++++++++++++++++++++++++ -An HTTP 401 error indicates the authentication process failed during the initial -connection. You can check the following to troubleshoot: - -* The credentials are correct and set properly in your inventory with the ``ansible_user`` and ``ansible_password`` variables. - -* The user is a member of the local Administrators group or has been explicitly granted access. You can perform a connection test with the ``winrs`` command to rule this out. - -* The authentication option set by the ``ansible_winrm_transport`` variable is enabled under ``Service\Auth\*``. - -* If running over HTTP and not HTTPS, use ``ntlm``, ``kerberos`` or ``credssp`` with the ``ansible_winrm_message_encryption: auto`` custom inventory variable to enable message encryption. If you use another authentication option, or if it is not possible to upgrade the installed ``pywinrm`` package, you can set ``Service\AllowUnencrypted`` to ``true``. This is recommended only for troubleshooting. - -* The downstream packages ``pywinrm``, ``requests-ntlm``, ``requests-kerberos``, and/or ``requests-credssp`` are up to date using ``pip``. - -* For Kerberos authentication, ensure that ``Service\Auth\CbtHardeningLevel`` is not set to ``Strict``. - -* For Basic or Certificate authentication, make sure that the user is a local account. Domain accounts do not work with Basic and Certificate authentication. - -HTTP 500 Error -++++++++++++++ -An HTTP 500 error indicates a problem with the WinRM service. You can check the following to troubleshoot: - -* The number of your currently open shells has not exceeded either ``WinRsMaxShellsPerUser``. Alternatively, you did not exceed any of the other Winrs quotas. - -Timeout Errors -+++++++++++++++ -Sometimes Ansible is unable to reach the host. These instances usually indicate a problem with the network connection. You can check the following to troubleshoot: - -* The firewall is not set to block the configured WinRM listener ports. -* A WinRM listener is enabled on the port and path set by the host vars. -* The ``winrm`` service is running on the Windows host and is configured for the automatic start. - -Connection Refused Errors -+++++++++++++++++++++++++ -When you communicate with the WinRM service on the host you may encounter some problems. Check the following to help with the troubleshooting: - -* The WinRM service is up and running on the host. Use the ``(Get-Service -Name winrm).Status`` command to get the status of the service. -* The host firewall is allowing traffic over the WinRM port. By default, this is ``5985`` for HTTP and ``5986`` for HTTPS. - -Sometimes an installer may restart the WinRM or HTTP service and cause this error. The best way to deal with this is to use the ``win_psexec`` module from another Windows host. - -Failure to Load Builtin Modules -+++++++++++++++++++++++++++++++ -Sometimes PowerShell fails with an error message similar to: - -.. code-block:: powershell - - The 'Out-String' command was found in the module 'Microsoft.PowerShell.Utility', but the module could not be loaded. - -In that case, there could be a problem when trying to access all the paths specified by the ``PSModulePath`` environment variable. - -A common cause of this issue is that ``PSModulePath`` contains a Universal Naming Convention (UNC) path to a file share. Additionally, the double hop/credential delegation issue causes that the Ansible process cannot access these folders. To work around this problem is to either: - -* Remove the UNC path from ``PSModulePath``. - -or - -* Use an authentication option that supports credential delegation like ``credssp`` or ``kerberos``. You need to have the credential delegation enabled. - -See `KB4076842 `_ for more information on this problem. - -Windows SSH Setup -````````````````` -Ansible 2.8 has added an experimental SSH connection for Windows-managed nodes. - -.. warning:: - Use this feature at your own risk! Using SSH with Windows is experimental. This implementation may make - backwards incompatible changes in future releases. The server-side components can be unreliable depending on your installed version. - -Installing OpenSSH using Windows Settings ------------------------------------------ -You can use OpenSSH to connect Windows 10 clients to Windows Server 2019. OpenSSH Client is available to install on Windows 10 build 1809 and later. OpenSSH Server is available to install on Windows Server 2019 and later. - -For more information, refer to `Get started with OpenSSH for Windows `_. - -Installing Win32-OpenSSH ------------------------- -To install the `Win32-OpenSSH `_ service for use with -Ansible, select one of these installation options: - -* Manually install ``Win32-OpenSSH``, following the `install instructions `_ from Microsoft. - -* Use Chocolatey: - -.. code-block:: powershell - - choco install --package-parameters=/SSHServerFeature openssh - -* Use the ``win_chocolatey`` Ansible module: - -.. code-block:: yaml - - - name: install the Win32-OpenSSH service - win_chocolatey: - name: openssh - package_params: /SSHServerFeature - state: present - -* Install an Ansible Galaxy role for example `jborean93.win_openssh `_: - -.. code-block:: powershell - - ansible-galaxy install jborean93.win_openssh - -* Use the role in your playbook: - -.. code-block:: yaml - - - name: install Win32-OpenSSH service - hosts: windows - gather_facts: false - roles: - - role: jborean93.win_openssh - opt_openssh_setup_service: True - -.. note:: ``Win32-OpenSSH`` is still a beta product and is constantly being updated to include new features and bug fixes. If you use SSH as a connection option for Windows, we highly recommend you install the latest version. - -Configuring the Win32-OpenSSH shell ------------------------------------ - -By default, ``Win32-OpenSSH`` uses ``cmd.exe`` as a shell. - -* To configure a different shell, use an Ansible playbook with a task to define the registry setting: - -.. code-block:: yaml - - - name: set the default shell to PowerShell - win_regedit: - path: HKLM:\SOFTWARE\OpenSSH - name: DefaultShell - data: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe - type: string - state: present - -* To revert the settings to the default shell: - -.. code-block:: yaml - - - name: set the default shell to cmd - win_regedit: - path: HKLM:\SOFTWARE\OpenSSH - name: DefaultShell - state: absent - -Win32-OpenSSH Authentication ----------------------------- -Win32-OpenSSH authentication with Windows is similar to SSH authentication on Unix/Linux hosts. You can use a plaintext password or SSH public key authentication. - -For the key-based authentication: - -* Add your public keys to an ``authorized_key`` file in the ``.ssh`` folder of the user's profile directory. - -* Configure the SSH service using the ``sshd_config`` file. - -When using SSH key authentication with Ansible, the remote session will not have access to user credentials and will fail when attempting to access a network resource. This is also known as the double-hop or credential delegation issue. To work around this problem: - -* Use plaintext password authentication by setting the ``ansible_password`` variable. -* Use the ``become`` directive on the task with the credentials of the user that needs access to the remote resource. - -Configuring Ansible for SSH on Windows --------------------------------------- -To configure Ansible to use SSH for Windows hosts, you must set two connection variables: - -* set ``ansible_connection`` to ``ssh`` -* set ``ansible_shell_type`` to ``cmd`` or ``powershell`` - -The ``ansible_shell_type`` variable should reflect the ``DefaultShell`` configured on the Windows host. Set ``ansible_shell_type`` to ``cmd`` for the default shell. Alternatively, set ``ansible_shell_type`` to ``powershell`` if you changed ``DefaultShell`` to PowerShell. - -Known issues with SSH on Windows --------------------------------- -Using SSH with Windows is experimental. Currently, existing issues are: - -* Win32-OpenSSH versions older than ``v7.9.0.0p1-Beta`` do not work when ``powershell`` is the shell type. -* While Secure Copy Protocol (SCP) should work, SSH File Transfer Protocol (SFTP) is the recommended mechanism to use when copying or fetching a file. - -.. seealso:: - - :ref:`about_playbooks` - An introduction to playbooks - :ref:`playbooks_best_practices` - Tips and tricks for playbooks - :ref:`List of Windows Modules ` - Windows-specific module list, all implemented in PowerShell - :ref:`Communication` - Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide +This page has moved to :ref:`windows_winrm`. \ No newline at end of file diff --git a/docs/docsite/rst/os_guide/windows_ssh.rst b/docs/docsite/rst/os_guide/windows_ssh.rst new file mode 100644 index 00000000000..e55b9049b00 --- /dev/null +++ b/docs/docsite/rst/os_guide/windows_ssh.rst @@ -0,0 +1,198 @@ +.. _windows_ssh: + +Windows SSH +=========== + +On newer Windows versions, you can use SSH to connect to a Windows host. This is an alternative connection option to :ref:`WinRM `. + +.. note:: + While Ansible could use the SSH connection plugin with Windows nodes since Ansible 2.8, official support was only added in version 2.18. + +.. contents:: + :local: + + +SSH Setup +--------- + +Microsoft provides an OpenSSH implementation with Windows since Windows Server 2019 as a Windows capability. It can also be installed through an upstream package under `Win32-OpenSSH `_. Ansible officially only supports the OpenSSH implementation shipped with Windows, not the upstream package. The OpenSSH version must be version ``7.9.0.0`` at a minimum. This effectively means official support starts with Windows Server 2022 because Server 2019 ships with version ``7.7.2.1``. Using older Windows versions or the upstream package might work but is not supported. + +To install the OpenSSH feature on Windows Server 2022 and later, use the following PowerShell command: + +.. code-block:: powershell + + Get-WindowsCapability -Name OpenSSH.Server* -Online | + Add-WindowsCapability -Online + Set-Service -Name sshd -StartupType Automatic -Status Running + + $firewallParams = @{ + Name = 'sshd-Server-In-TCP' + DisplayName = 'Inbound rule for OpenSSH Server (sshd) on TCP port 22' + Action = 'Allow' + Direction = 'Inbound' + Enabled = 'True' # This is not a boolean but an enum + Profile = 'Any' + Protocol = 'TCP' + LocalPort = 22 + } + New-NetFirewallRule @firewallParams + + $shellParams = @{ + Path = 'HKLM:\SOFTWARE\OpenSSH' + Name = 'DefaultShell' + Value = 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' + PropertyType = 'String' + Force = $true + } + New-ItemProperty @shellParams + + +Default Shell Configuration +""""""""""""""""""""""""""" + +By default, OpenSSH on Windows uses ``cmd.exe`` as the default shell. While Ansible can work with this default shell it is recommended to change this to ``powershell.exe`` as it is better tested and should be faster than having ``cmd.exe`` as the default. To change the default shell you can use the following PowerShell script: + +.. code-block:: powershell + + # Set default to powershell.exe + $shellParams = @{ + Path = 'HKLM:\SOFTWARE\OpenSSH' + Name = 'DefaultShell' + Value = 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe' + PropertyType = 'String' + Force = $true + } + New-ItemProperty @shellParams + + # Set default back to cmd.exe + Remove-ItemProperty -Path HKLM:\SOFTWARE\OpenSSH -Name DefaultShell + +The new default shell setting will apply to the next SSH connection, there is no need to restart the ``sshd`` service. You can also use Ansible to configure the default shell: + +.. code-block:: yaml + + - name: set the default shell to PowerShell + ansible.windows.win_regedit: + path: HKLM:\SOFTWARE\OpenSSH + name: DefaultShell + data: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe + type: string + state: present + + - name: reset SSH connection after shell change + ansible.builtin.meta: reset_connection + + - name: set the default shell to cmd + ansible.windows.win_regedit: + path: HKLM:\SOFTWARE\OpenSSH + name: DefaultShell + state: absent + + - name: reset SSH connection after shell change + ansible.builtin.meta: reset_connection + +The ``meta: reset_connection`` is important to ensure the subsequent tasks will use the new default shell. + + +Ansible Configuration +--------------------- + +To configure Ansible to use SSH for Windows hosts, you must set two connection variables: + +* set ``ansible_connection`` to ``ssh`` +* set ``ansible_shell_type`` to ``powershell`` or ``cmd`` + +The ``ansible_shell_type`` variable should reflect the ``DefaultShell`` configured on the Windows host. Other SSH options as documented under the :ref:`ssh ` can also be set for the Windows host. + + +SSH Authentication +------------------ +Win32-OpenSSH authentication with Windows is similar to SSH authentication on Unix/Linux hosts. While there are many authentication methods that can be used there are typically three used on Windows: + ++----------+----------------+---------------------------+-----------------------+ +| Option | Local Accounts | Active Directory Accounts | Credential Delegation | ++==========+================+===========================+=======================+ +| Key | Yes | Yes | No | ++----------+----------------+---------------------------+-----------------------+ +| GSSAPI | No | Yes | Yes | ++----------+----------------+---------------------------+-----------------------+ +| Password | Yes | Yes | Yes | ++----------+----------------+---------------------------+-----------------------+ + +In most cases it is recommended to use key or GSSAPI authentication over password authentication. + +Key Authentication +"""""""""""""""""" + +SSH key authentication on Windows works in the same way as SSH key authentication for POSIX nodes. You can generate a key pair using the ``ssh-keygen`` command and add the public key to the ``authorized_keys`` file in the user's profile directory. The private key should be kept secure and not shared. + +One difference is that the ``authorized_keys`` file for admin users is not located in the ``.ssh`` folder in the user's profile directory but in ``C:\ProgramData\ssh\administrators_authorized_keys``. It is possible to change the location of the ``authorized_keys`` file for admin users back to the user profile directory by removing, or commenting, the lines in ``C:\ProgramData\ssh\sshd_config`` and restarting the ``sshd`` service. + +.. code-block:: + + Match Group administrators + AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys + +SSH keys work with both local and domain accounts but suffer from the double-hop issue. This means that when using SSH key authentication with Ansible, the remote session will not have access to user credentials and will fail when attempting to access a network resource. To work around this problem, you can use :ref:`become ` on the task with the credentials of the user that needs access to the remote resource. + + +GSSAPI Authentication +""""""""""""""""""""" + +GSSAPI authentication will use Kerberos to authenticate the user with the Windows host. To use GSSAPI authentication with Ansible, the Windows server must be configured to allow GSSAPI authentication by editing the ``C:\ProgramData\ssh\sshd_config`` file. Either add in the following line or edit the existing line: + +.. code-block:: text + + GSSAPIAuthentication yes + +Once edited restart the ``sshd`` service with ``Restart-Service -Name sshd``. + +On the Ansible control node, you need to have Kerberos installed and configured with the domain the Windows host is a member of. How to set this up and configure is outside the scope of this document. Once the Kerberos realm is configured you can use the ``kinit`` command to get a ticket for the user you are connecting with and ``klist`` to verify what tickets are available: + +.. code-block:: bash + + > kinit username@REALM.COM + Password for username@REALM.COM + + > klist + Ticket cache: KCM:1000 + Default principal: username@REALM.COM + + Valid starting Expires Service principal + 29/08/24 13:54:51 29/08/24 23:54:51 krbtgt/REALM.COM@REALM.COM + renew until 05/09/24 13:54:48 + +Once you have a valid ticket you can use the ``ansible_user`` hostvar to specify the UPN username and Ansible will automatically use the Kerberos ticket for that user when using SSH. + +It is also possible to enable unconstrained delegation through GSSAPI authentication to have the Windows node access network resources. For GSSAPI delegation to work the ticket retrieved by ``kinit`` must be forwardable and ``ssh`` must be called with the ``-o GSSAPIDelegateCredentials=yes`` option. To retrieve a forwardable ticket either use the ``-f`` flag with ``kinit`` or add ``forwardable = true`` under ``[libdefaults]`` in the ``/etc/krb5.conf`` file. + +.. code-block:: bash + + > kinit -f username@REALM.COM + Password for username@REALM.COM + + # -f will show the ticket flags, we want to see F + > klist -f + Ticket cache: KCM:1000 + Default principal: username@REALM.COM + + Valid starting Expires Service principal + 29/08/24 13:54:51 29/08/24 23:54:51 krbtgt/REALM.COM@REALM.COM + renew until 05/09/24 13:54:48, Flags: FRIA + +The ``GSSAPIDelegateCredentials=yes`` option can either be set in the ``~/.ssh/config`` file or as a hostvar variable in the inventory: + +.. code-block:: yaml+jinja + + ansible_ssh_common_args: -o GSSAPIDelegateCredentials=yes + +Unlike the ``psrp`` or ``winrm`` connection plugins, the SSH connection plugin cannot get a Kerberos TGT ticket when provided with an explicit username and password. This means that the user must have a valid Kerberos ticket before running the playbook. + +See :ref:`windows_winrm_kerberos` for more information on how to configure, use, and troubleshoot Kerberos authentication. + +Password Authentication +""""""""""""""""""""""" + +Password authentication is the least secure method of authentication and is not recommended. However, it is possible to use password authentication with Windows SSH. To use password authentication with Ansible, set the ``ansible_password`` variable in the inventory file or in the playbook. Using password authentication requires the ``sshpass`` package to be installed on the Ansible control node. + +Password authentication works like WinRM CredSSP authentication where the username and password is given to the Windows host and it will perform unconstrained delegation to access network resources. diff --git a/docs/docsite/rst/os_guide/windows_winrm.rst b/docs/docsite/rst/os_guide/windows_winrm.rst index dbf0fd27b85..11d20be3f32 100644 --- a/docs/docsite/rst/os_guide/windows_winrm.rst +++ b/docs/docsite/rst/os_guide/windows_winrm.rst @@ -2,12 +2,12 @@ Windows Remote Management ========================= + Unlike Linux/Unix hosts, which use SSH by default, Windows hosts are configured with WinRM. This topic covers how to configure and use WinRM with Ansible. .. contents:: :local: - :depth: 2 What is WinRM? @@ -16,270 +16,300 @@ What is WinRM? WinRM is a management protocol used by Windows to remotely communicate with another server. It is a SOAP-based protocol that communicates over HTTP/HTTPS and is included in all recent Windows operating systems. Since Windows -Server 2012, WinRM has been enabled by default, but in most cases, extra +Server 2012, WinRM has been enabled by default, but in some cases, extra configuration is required to use WinRM with Ansible. -Ansible uses the `pywinrm `_ package to -communicate with Windows servers over WinRM. It is not installed by default -with the Ansible package. +Ansible can use WinRM through the :ref:`psrp ` or :ref:`winrm ` connection plugins. These plugins have their own Python requirements that are not included in the Ansible package and must be installed separately. -If you chose the ``pipx`` install instructions, you can install it by running the -following: +If you chose the ``pipx`` install instructions, you can install those requirements by running the following: .. code-block:: shell - pipx inject ansible pywinrm # if you installed ansible with pipx - pipx inject ansible-core pywinrm # if you installed ansible-core with pipx + pipx inject "pypsrp<=1.0.0" # for psrp + pipx inject "pywinrm>=0.4.0" # for winrm Or, if you chose the ``pip`` install instructions: .. code-block:: shell - pip install "pywinrm>=0.3.0" - -.. Note:: on distributions with multiple Python versions, use pip2 or pip2.x, - where x matches the Python minor version Ansible is running under. + pip3 install "pypsrp<=1.0.0" # for psrp + pip3 install "pywinrm>=0.4.0" # for winrm .. Warning:: - Using the ``winrm`` or ``psrp`` connection plugins in Ansible on MacOS in - the latest releases typically fails. This is a known problem that occurs - deep within the Python stack and cannot be changed by Ansible. The only - workaround today is to set the environment variable ``no_proxy=*`` and - avoid using Kerberos auth. + Using the ``winrm`` or ``psrp`` connection plugins in Ansible on MacOS in the latest releases typically fails. This is a known problem that occurs deep within the Python stack and cannot be changed by Ansible. The only workaround today is to set the environment variable ``OBJC_DISABLE_INITIALIZE_FORK_SAFETY=yes``, ``no_proxy=*`` and avoid using Kerberos auth. -.. _winrm_auth: +WinRM Setup +----------- -WinRM authentication options ------------------------------ +Before Ansible can connect using WinRM, the Windows host must have a WinRM listener configured. This listener will listen on the configured port and accept incoming WinRM requests. -When connecting to a Windows host, several different options can be used -when authenticating with an account. The authentication type may be set on inventory -hosts or groups with the ``ansible_winrm_transport`` variable. +While this guide covers more details on how to enumerate, add, and remove listeners, you can run the following PowerShell snippet to setup the HTTP listener with the defaults: -The following matrix is a high-level overview of the options: +.. code-block:: powershell -+-------------+----------------+---------------------------+-----------------------+-----------------+ -| Option | Local Accounts | Active Directory Accounts | Credential Delegation | HTTP Encryption | -+=============+================+===========================+=======================+=================+ -| Basic | Yes | No | No | No | -+-------------+----------------+---------------------------+-----------------------+-----------------+ -| Certificate | Yes | No | No | No | -+-------------+----------------+---------------------------+-----------------------+-----------------+ -| Kerberos | No | Yes | Yes | Yes | -+-------------+----------------+---------------------------+-----------------------+-----------------+ -| NTLM | Yes | Yes | No | Yes | -+-------------+----------------+---------------------------+-----------------------+-----------------+ -| CredSSP | Yes | Yes | Yes | Yes | -+-------------+----------------+---------------------------+-----------------------+-----------------+ + # Enables the WinRM service and sets up the HTTP listener + Enable-PSRemoting -Force + + # Opens port 5985 for all profiles + $firewallParams = @{ + Action = 'Allow' + Description = 'Inbound rule for Windows Remote Management via WS-Management. [TCP 5985]' + Direction = 'Inbound' + DisplayName = 'Windows Remote Management (HTTP-In)' + LocalPort = 5985 + Profile = 'Any' + Protocol = 'TCP' + } + New-NetFirewallRule @firewallParams + + # Allows local user accounts to be used with WinRM + # This can be ignored if using domain accounts + $tokenFilterParams = @{ + Path = 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System' + Name = 'LocalAccountTokenFilterPolicy' + Value = 1 + PropertyType = 'DWORD' + Force = $true + } + New-ItemProperty @tokenFilterParams -.. _winrm_basic: +To also add a HTTPS listener with a self signed certificate we can run the following: -Basic -^^^^^^ +.. code-block:: powershell -Basic authentication is one of the simplest authentication options to use but is -also the most insecure. This is because the username and password are simply -base64 encoded, and if a secure channel is not in use (eg, HTTPS) then it can be -decoded by anyone. Basic authentication can only be used for local accounts (not domain accounts). + # Create self signed certificate + $certParams = @{ + CertStoreLocation = 'Cert:\LocalMachine\My' + DnsName = $env:COMPUTERNAME + NotAfter = (Get-Date).AddYears(1) + Provider = 'Microsoft Software Key Storage Provider' + Subject = "CN=$env:COMPUTERNAME" + } + $cert = New-SelfSignedCertificate @certParams + + # Create HTTPS listener + $httpsParams = @{ + ResourceURI = 'winrm/config/listener' + SelectorSet = @{ + Transport = "HTTPS" + Address = "*" + } + ValueSet = @{ + CertificateThumbprint = $cert.Thumbprint + Enabled = $true + } + } + New-WSManInstance @httpsParams + + # Opens port 5986 for all profiles + $firewallParams = @{ + Action = 'Allow' + Description = 'Inbound rule for Windows Remote Management via WS-Management. [TCP 5986]' + Direction = 'Inbound' + DisplayName = 'Windows Remote Management (HTTPS-In)' + LocalPort = 5986 + Profile = 'Any' + Protocol = 'TCP' + } + New-NetFirewallRule @firewallParams -The following example shows host vars configured for basic authentication: +.. warning:: + The above scripts are for demonstration purposes only and should be reviewed before running in a production environment. Some changes, like opening the firewall port for all incoming connections, allowing local accounts to be used with WinRM, self signed certificates, may not be suitable for all environments. -.. code-block:: yaml+jinja - ansible_user: LocalUsername - ansible_password: Password - ansible_connection: winrm - ansible_winrm_transport: basic +Enumerate Listeners +""""""""""""""""""" -Basic authentication is not enabled by default on a Windows host but can be -enabled by running the following in PowerShell: +To view the current listeners that are running on the WinRM service: .. code-block:: powershell - Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true - - -.. _winrm_certificate: - -Certificate -^^^^^^^^^^^^ - -Certificate authentication uses certificates as keys similar to SSH key -pairs, but the file format and key generation process is different. - -The following example shows host vars configured for certificate authentication: + winrm enumerate winrm/config/Listener -.. code-block:: yaml+jinja +This will output something like: - ansible_connection: winrm - ansible_winrm_cert_pem: /path/to/certificate/public/key.pem - ansible_winrm_cert_key_pem: /path/to/certificate/private/key.pem - ansible_winrm_transport: certificate +.. code-block:: powershell -Certificate authentication is not enabled by default on a Windows host but can -be enabled by running the following in PowerShell: + Listener + Address = * + Transport = HTTP + Port = 5985 + Hostname + Enabled = true + URLPrefix = wsman + CertificateThumbprint + ListeningOn = 10.0.2.15, 127.0.0.1, 192.168.56.155, ::1, fe80::5efe:10.0.2.15%6, fe80::5efe:192.168.56.155%8, fe80:: + ffff:ffff:fffe%2, fe80::203d:7d97:c2ed:ec78%3, fe80::e8ea:d765:2c69:7756%7 + + Listener + Address = * + Transport = HTTPS + Port = 5986 + Hostname = SERVER2016 + Enabled = true + URLPrefix = wsman + CertificateThumbprint = E6CDAA82EEAF2ECE8546E05DB7F3E01AA47D76CE + ListeningOn = 10.0.2.15, 127.0.0.1, 192.168.56.155, ::1, fe80::5efe:10.0.2.15%6, fe80::5efe:192.168.56.155%8, fe80:: + ffff:ffff:fffe%2, fe80::203d:7d97:c2ed:ec78%3, fe80::e8ea:d765:2c69:7756%7 + +In the example above there are two WinRM listeners configured. One is listening on port 5985 over HTTP and the other is listening on port 5986 over HTTPS. Some of the key options that are useful to understand are: + +* ``Transport``: Whether the listener is run over HTTP or HTTPS +* ``Port``: The port the to listen on, default for HTTP is ``5985`` and HTTPS is ``5986`` +* ``CertificateThumbprint``: For HTTPS, this is the thumbprint of the certificate used for the TLS connection + +To view the certificate details that is specified by the ``CertificateThumbprint`` you can run the following PowerShell command: .. code-block:: powershell - Set-Item -Path WSMan:\localhost\Service\Auth\Certificate -Value $true - -.. Note:: Encrypted private keys cannot be used as the urllib3 library that - is used by Ansible for WinRM does not support this functionality. + $thumbprint = "E6CDAA82EEAF2ECE8546E05DB7F3E01AA47D76CE" + Get-Item -Path "Cert:\LocalMachine\My\$thumbprint" | Select-Object * -.. Note:: For enabling certificate authentication with a TLS 1.3 connection, Python 3.8+, 3.7.1, or 3.6.7 and Python packages urllib3==2.0.7 or newer are required. -.._winrm_certificate_generate: +Create Listener +""""""""""""""" -Generate a Certificate -++++++++++++++++++++++ +Creating a HTTP listener can be done through the ``Enable-PSRemoting`` cmdlet but you can also use the following PowerShell code to manually create the HTTP listener. -A certificate must be generated before it can be mapped to a local user. -This can be done using one of the following methods: +.. code-block:: powershell -* OpenSSL -* PowerShell, using the ``New-SelfSignedCertificate`` cmdlet -* Active Directory Certificate Services + $listenerParams = @{ + ResourceURI = 'winrm/config/listener' + SelectorSet = @{ + Transport = "HTTP" + Address = "*" + } + ValueSet = @{ + Enabled = $true + Port = 5985 + } + } + New-WSManInstance @listenerParams -Active Directory Certificate Services is beyond of scope in this documentation but may be -the best option to use when running in a domain environment. For more information, -see the `Active Directory Certificate Services documentation `_. +Creating a HTTPS listener is similar but the ``Port`` is now ``5985`` and the ``CertificateThumbprint`` value must be set. The certificate can either be a self signed certificate or a certificate from a certificate authority. How to generate a certificate is outside the scope of this section. -.. Note:: Using the PowerShell cmdlet ``New-SelfSignedCertificate`` to generate - a certificate for authentication only works when being generated from a - Windows 10 or Windows Server 2012 R2 host or later. OpenSSL is still required to - extract the private key from the PFX certificate to a PEM file for Ansible - to use. +.. code-block:: powershell -To generate a certificate with ``OpenSSL``: + $listenerParams = @{ + ResourceURI = 'winrm/config/listener' + SelectorSet = @{ + Transport = "HTTP" + Address = "*" + } + ValueSet = @{ + CertificateThumbprint = 'E6CDAA82EEAF2ECE8546E05DB7F3E01AA47D76CE' + Enabled = $true + Port = 5985 + } + } + New-WSManInstance @listenerParams -.. code-block:: shell +The ``CertificateThumbprint`` value must be set to the thumbprint of a certificate that is installed in the ``LocalMachine\My`` certificate store. - # Set the name of the local user that will have the key mapped to - USERNAME="username" +The ``Address`` selector value can be set to one of three values: - cat > openssl.conf << EOL - distinguished_name = req_distinguished_name - [req_distinguished_name] - [v3_req_client] - extendedKeyUsage = clientAuth - subjectAltName = otherName:1.3.6.1.4.1.311.20.2.3;UTF8:$USERNAME@localhost - EOL +* ``*`` - binds to all addresses +* ``IP:...`` - binds to the IPv4 or IPv6 address specified by ``...`` +* ``MAC:32-a3-58-90-be-cc`` - binds to the adapter with the MAC address specified - export OPENSSL_CONF=openssl.conf - openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -out cert.pem -outform PEM -keyout cert_key.pem -subj "/CN=$USERNAME" -extensions v3_req_client - rm openssl.conf +Remove Listener +""""""""""""""" -To generate a certificate with ``New-SelfSignedCertificate``: +The following code can remove all listeners or a specific one: .. code-block:: powershell - # Set the name of the local user that will have the key mapped - $username = "username" - $output_path = "C:\temp" + # Removes all listeners + Remove-Item -Path WSMan:\localhost\Listener\* -Recurse -Force - # Instead of generating a file, the cert will be added to the personal - # LocalComputer folder in the certificate store - $cert = New-SelfSignedCertificate -Type Custom ` - -Subject "CN=$username" ` - -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.2","2.5.29.17={text}upn=$username@localhost") ` - -KeyUsage DigitalSignature,KeyEncipherment ` - -KeyAlgorithm RSA ` - -KeyLength 2048 + # Removes only HTTP listeners + Get-ChildItem -Path WSMan:\localhost\Listener | + Where-Object Keys -contains "Transport=HTTP" | + Remove-Item -Recurse -Force - # Export the public key - $pem_output = @() - $pem_output += "-----BEGIN CERTIFICATE-----" - $pem_output += [System.Convert]::ToBase64String($cert.RawData) -replace ".{64}", "$&`n" - $pem_output += "-----END CERTIFICATE-----" - [System.IO.File]::WriteAllLines("$output_path\cert.pem", $pem_output) + # Removes only HTTPS listeners + Get-ChildItem -Path WSMan:\localhost\Listener | + Where-Object Keys -contains "Transport=HTTPS" | + Remove-Item -Recurse -Force - # Export the private key in a PFX file - [System.IO.File]::WriteAllBytes("$output_path\cert.pfx", $cert.Export("Pfx")) +WinRM Authentication +-------------------- -.. Note:: To convert the PFX file to a private key that pywinrm can use, run - the following command with OpenSSL - ``openssl pkcs12 -in cert.pfx -nocerts -nodes -out cert_key.pem -passin pass: -passout pass:`` +WinRM has several different authentication options that can be used to authenticate a user with a Windows host. Each option has their own advantages and disadvantages so it is important to understand when to use each one and when to not. -.. _winrm_certificate_import: +The following matrix is a high-level overview of the options: -Import a Certificate to the Certificate Store -+++++++++++++++++++++++++++++++++++++++++++++ ++-------------+----------------+---------------------------+-----------------------+-----------------+ +| Option | Local Accounts | Active Directory Accounts | Credential Delegation | HTTP Encryption | ++=============+================+===========================+=======================+=================+ +| Basic | Yes | No | No | No | ++-------------+----------------+---------------------------+-----------------------+-----------------+ +| Certificate | Yes | No | No | No | ++-------------+----------------+---------------------------+-----------------------+-----------------+ +| Kerberos | No | Yes | Yes | Yes | ++-------------+----------------+---------------------------+-----------------------+-----------------+ +| NTLM | Yes | Yes | No | Yes | ++-------------+----------------+---------------------------+-----------------------+-----------------+ +| CredSSP | Yes | Yes | Yes | Yes | ++-------------+----------------+---------------------------+-----------------------+-----------------+ -Once a certificate has been generated, the issuing certificate needs to be -imported into the ``Trusted Root Certificate Authorities`` of the -``LocalMachine`` store, and the client certificate public key must be present -in the ``Trusted People`` folder of the ``LocalMachine`` store. For this example, -both the issuing certificate and public key are the same. +The ``Basic`` and ``NTLM`` authentication options should not be used over a HTTP listener as they either offer no encryption or very weak encryption. The ``psrp`` connection plugin also offers the ``Negotiate`` authentication option which will attempt to use ``Kerberos`` before falling back to ``NTLM``. The ``winrm`` connection plugin must either specify ``kerberos`` or ``ntlm``. -Following example shows how to import the issuing certificate: +To specify the authentication protocol you can use the following variables: -.. code-block:: powershell +.. code-block:: yaml+jinja - $cert = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2 "cert.pem" + # For psrp + ansible_psrp_auth: basic|certificate|negotiate|kerberos|ntlm|credssp - $store_name = [System.Security.Cryptography.X509Certificates.StoreName]::Root - $store_location = [System.Security.Cryptography.X509Certificates.StoreLocation]::LocalMachine - $store = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Store -ArgumentList $store_name, $store_location - $store.Open("MaxAllowed") - $store.Add($cert) - $store.Close() + # For winrm + ansible_winrm_transport: basic|certificate|kerberos|ntlm|credssp +The recommendations for WinRM would be to use Kerberos auth over HTTP if in a domain environment or Basic/NTLM over HTTPS for local accounts. CredSSP should only be used when absolutely necessary as it can be a security risk due to its use of unconstrained delegation. -.. Note:: If using ADCS to generate the certificate, then the issuing - certificate will already be imported and this step can be skipped. -The code to import the client certificate public key is: +Basic +""""" -.. code-block:: powershell +Basic authentication is one of the simplest authentication options to use but is +also the most insecure. This is because the username and password are simply +base64 encoded, and if a secure channel is not in use (eg, HTTPS) then it can be +decoded by anyone. Basic authentication can only be used for local accounts (not domain accounts). - $cert = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2 "cert.pem" +The following example shows host vars configured for basic authentication: - $store_name = [System.Security.Cryptography.X509Certificates.StoreName]::TrustedPeople - $store_location = [System.Security.Cryptography.X509Certificates.StoreLocation]::LocalMachine - $store = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Store -ArgumentList $store_name, $store_location - $store.Open("MaxAllowed") - $store.Add($cert) - $store.Close() +.. code-block:: yaml+jinja + ansible_user: LocalUsername + ansible_password: Password -.. _winrm_certificate_mapping: + # psrp + ansible_connection: psrp + ansible_psrp_auth: basic -Mapping a Certificate to an Account -+++++++++++++++++++++++++++++++++++ + # winrm + ansible_connection: winrm + ansible_winrm_transport: basic -Once the certificate has been imported, map it to the local user account: +Basic authentication is not enabled by default on a Windows host but can be +enabled by running the following in PowerShell: .. code-block:: powershell - $username = "username" - $password = ConvertTo-SecureString -String "password" -AsPlainText -Force - $credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $username, $password - - # This is the issuer thumbprint which in the case of a self generated cert - # is the public key thumbprint, additional logic may be required for other - # scenarios - $thumbprint = (Get-ChildItem -Path cert:\LocalMachine\root | Where-Object { $_.Subject -eq "CN=$username" }).Thumbprint - - New-Item -Path WSMan:\localhost\ClientCertificate ` - -Subject "$username@localhost" ` - -URI * ` - -Issuer $thumbprint ` - -Credential $credential ` - -Force + Set-Item -Path WSMan:\localhost\Service\Auth\Basic -Value $true -Once this is complete, the hostvar ``ansible_winrm_cert_pem`` should be set to -the path of the public key and the ``ansible_winrm_cert_key_pem`` variable should be set to -the path of the private key. +Certificate +""""""""""" +See :ref:`windows_winrm_certificate` for more information on how to configure and use certificate authentication. -.. _winrm_ntlm: NTLM -^^^^^ +"""" NTLM is an older authentication mechanism used by Microsoft that can support both local and domain accounts. NTLM is enabled by default on the WinRM @@ -303,21 +333,25 @@ This example shows host variables configured to use NTLM authentication: ansible_user: LocalUsername ansible_password: Password + + # psrp + ansible_connection: psrp + ansible_psrp_auth: negotiate # or ntlm to only use NTLM + + # winrm ansible_connection: winrm ansible_winrm_transport: ntlm -.. _winrm_kerberos: -Kerberos -^^^^^^^^^ +Kerberos and Negotiate +"""""""""""""""""""""" Kerberos is the recommended authentication option to use when running in a domain environment. Kerberos supports features like credential delegation and message encryption over HTTP and is one of the more secure options that is available through WinRM. -Kerberos requires some additional setup work on the Ansible host before it can be -used properly. +Kerberos does require some additional setup work on the Ansible host before it can be used properly. See :ref:`windows_winrm_kerberos` for more information on how to configure, use, and troubleshoot Kerberos authentication. The following example shows host vars configured for Kerberos authentication: @@ -325,219 +359,18 @@ The following example shows host vars configured for Kerberos authentication: ansible_user: username@MY.DOMAIN.COM ansible_password: Password - ansible_connection: winrm - ansible_port: 5985 - ansible_winrm_transport: kerberos - -As of Ansible version 2.3, the Kerberos ticket will be created based on -``ansible_user`` and ``ansible_password``. If running on an older version of -Ansible or when ``ansible_winrm_kinit_mode`` is ``manual``, a Kerberos -ticket must already be obtained. See below for more details. - -Some extra host variables can be set: - -.. code-block:: yaml - - ansible_winrm_kinit_mode: managed/manual (manual means Ansible will not obtain a ticket) - ansible_winrm_kinit_cmd: the kinit binary to use to obtain a Kerberos ticket (default to kinit) - ansible_winrm_service: overrides the SPN prefix that is used, the default is ``HTTP`` and should rarely ever need changing - ansible_winrm_kerberos_delegation: allows the credentials to traverse multiple hops - ansible_winrm_kerberos_hostname_override: the hostname to be used for the Kerberos exchange - -.. _winrm_kerberos_install: - -Installing the Kerberos Library -+++++++++++++++++++++++++++++++ - -Some system dependencies must be installed before using Kerberos. The script below lists the dependencies based on the distro: - -.. code-block:: shell - - # Through Yum (RHEL/Centos/Fedora for the older version) - yum -y install gcc python-devel krb5-devel krb5-libs krb5-workstation - - # Through DNF (RHEL/Centos/Fedora for the newer version) - dnf -y install gcc python3-devel krb5-devel krb5-libs krb5-workstation - - # Through Apt (Ubuntu older than 20.04 LTS (focal)) - sudo apt-get install python-dev libkrb5-dev krb5-user - - # Through Apt (Ubuntu newer than 20.04 LTS) - sudo apt-get install python3-dev libkrb5-dev krb5-user - - # Through Portage (Gentoo) - emerge -av app-crypt/mit-krb5 - emerge -av dev-python/setuptools - - # Through Pkg (FreeBSD) - sudo pkg install security/krb5 - - # Through OpenCSW (Solaris) - pkgadd -d http://get.opencsw.org/now - /opt/csw/bin/pkgutil -U - /opt/csw/bin/pkgutil -y -i libkrb5_3 - - # Through Pacman (Arch Linux) - pacman -S krb5 - - -Once the dependencies have been installed, the ``python-kerberos`` wrapper can -be installed. - -If you chose the ``pipx`` install instructions, you can install it by running -the following: - -.. code-block:: shell - - pipx inject ansible pywinrm[kerberos] # if you installed ansible with pipx - pipx inject ansible-core pywinrm[kerberos] # if you installed ansible-core with pipx - -Or, if you chose the ``pip`` install instructions: - -.. code-block:: shell - - pip install pywinrm[kerberos] - - -.. note:: - While Ansible has supported Kerberos auth through ``pywinrm`` for some - time, optional features or more secure options may only be available in - newer versions of the ``pywinrm`` and/or ``pykerberos`` libraries. It is - recommended you upgrade each version to the latest available to resolve - any warnings or errors. This can be done through tools like ``pip`` or a - system package manager like ``dnf``, ``yum``, ``apt`` but the package - names and versions available may differ between tools. - - -.. _winrm_kerberos_config: - -Configuring Host Kerberos -+++++++++++++++++++++++++ - -Once the dependencies have been installed, Kerberos needs to be configured so -that it can communicate with a domain. This configuration is done through the -``/etc/krb5.conf`` file, which is installed with the packages in the script above. - -To configure Kerberos, in the section that starts with: - -.. code-block:: ini - - [realms] - -Add the full domain name and the fully qualified domain names of the primary -and secondary Active Directory domain controllers. It should look something -like this: - -.. code-block:: ini - - [realms] - MY.DOMAIN.COM = { - kdc = domain-controller1.my.domain.com - kdc = domain-controller2.my.domain.com - } - -In the section that starts with: - -.. code-block:: ini - - [domain_realm] - -Add a line like the following for each domain that Ansible needs access for: - -.. code-block:: ini - - [domain_realm] - .my.domain.com = MY.DOMAIN.COM -You can configure other settings in this file such as the default domain. See -`krb5.conf `_ -for more details. + # psrp + ansible_connection: psrp + ansible_psrp_auth: negotiate # or kerberos to disable ntlm fallback -.. _winrm_kerberos_ticket_auto: - -Automatic Kerberos Ticket Management -++++++++++++++++++++++++++++++++++++ - -Ansible version 2.3 and later defaults to automatically managing Kerberos tickets -when both ``ansible_user`` and ``ansible_password`` are specified for a host. In -this process, a new ticket is created in a temporary credential cache for each -host. This is done before each task executes to minimize the chance of ticket -expiration. The temporary credential caches are deleted after each task -is completed and will not interfere with the default credential cache. - -To disable automatic ticket management, set ``ansible_winrm_kinit_mode=manual`` -through the inventory. - -Automatic ticket management requires a standard ``kinit`` binary on the control -host system path. To specify a different location or binary name, set the -``ansible_winrm_kinit_cmd`` hostvar to the fully qualified path to a MIT krbv5 -``kinit``-compatible binary. - -.. _winrm_kerberos_ticket_manual: - -Manual Kerberos Ticket Management -+++++++++++++++++++++++++++++++++ - -To manually manage Kerberos tickets, the ``kinit`` binary is used. To -obtain a new ticket the following command is used: - -.. code-block:: shell - - kinit username@MY.DOMAIN.COM - -.. Note:: The domain must match the configured Kerberos realm exactly, and must be in upper case. - -To see what tickets (if any) have been acquired, use the following command: - -.. code-block:: shell - - klist - -To destroy all the tickets that have been acquired, use the following command: - -.. code-block:: shell - - kdestroy - -.. _winrm_kerberos_troubleshoot: - -Troubleshooting Kerberos -++++++++++++++++++++++++ - -Kerberos is reliant on a properly configured environment to -work. To troubleshoot Kerberos issues, ensure that: - -* The hostname set for the Windows host is the FQDN and not an IP address. - * If you connect using an IP address you will get the error message `Server not found in Kerberos database`. - * To determine if you are connecting using an IP address or an FQDN run your playbook (or call the ``win_ping`` module) using the `-vvv` flag. - -* The forward and reverse DNS lookups are working properly in the domain. To - test this, ping the Windows host by name and then use the IP address returned - with ``nslookup``. The same name should be returned when using ``nslookup`` - on the IP address. - -* The Ansible host's clock is synchronized with the AD domain controller. Kerberos - is time-sensitive, and a little clock drift can cause the ticket generation - process to fail. - -* Ensure that the fully qualified domain name for the domain is configured in - the ``krb5.conf`` file. To check this, run: - - .. code-block:: console - - kinit -C username@MY.DOMAIN.COM - klist - - If the domain name returned by ``klist`` is different from the one requested, - an alias is being used. The ``krb5.conf`` file needs to be updated so that - the fully qualified domain name is used and not an alias. - -* If the default Kerberos tooling has been replaced or modified (some IdM solutions may do this), this may cause issues when installing or upgrading the Python Kerberos library. As of the time of this writing, this library is called ``pykerberos`` and is known to work with both MIT and Heimdal Kerberos libraries. To resolve ``pykerberos`` installation issues, ensure the system dependencies for Kerberos have been met (see: `Installing the Kerberos Library`_), remove any custom Kerberos tooling paths from the PATH environment variable, and retry the installation of Python Kerberos library package. + # winrm + ansible_connection: winrm + ansible_winrm_transport: kerberos -.. _winrm_credssp: CredSSP -^^^^^^^ +""""""" CredSSP authentication is a newer authentication protocol that allows credential delegation. This is achieved by encrypting the username and password @@ -557,14 +390,14 @@ To use CredSSP authentication, the host vars are configured like so: ansible_user: Username ansible_password: Password - ansible_connection: winrm - ansible_winrm_transport: credssp - -Some extra host variables that can be set as shown below: -.. code-block:: yaml + # psrp + ansible_connection: psrp + ansible_psrp_auth: credssp - ansible_winrm_credssp_disable_tlsv1_2: when true, will not use TLS 1.2 in the CredSSP auth process + # winrm + ansible_connection: winrm + ansible_winrm_transport: credssp CredSSP authentication is not enabled by default on a Windows host, but can be enabled by running the following in PowerShell: @@ -573,62 +406,31 @@ be enabled by running the following in PowerShell: Enable-WSManCredSSP -Role Server -Force -.. _winrm_credssp_install: +CredSSP requires optional Python libraries to be installed and can be done with pipx: -Installing CredSSP Library -++++++++++++++++++++++++++ - -The ``requests-credssp`` wrapper can be installed using ``pip``: - -.. code-block:: bash - - pip install pywinrm[credssp] - -.. _winrm_credssp_tls: - -CredSSP and TLS 1.2 -+++++++++++++++++++ - -By default, the ``requests-credssp`` library is configured to authenticate over -the TLS 1.2 protocol. TLS 1.2 is installed and enabled by default for Windows Server 2012 -and Windows 8 and more recent releases. - -There are two ways that older hosts can be used with CredSSP: - -* Install and enable a hotfix to enable TLS 1.2 support (recommended - for Server 2008 R2 and Windows 7). - -* Set ``ansible_winrm_credssp_disable_tlsv1_2=True`` in the inventory to run - over TLS 1.0. This is the only option when connecting to Windows Server 2008, which - has no way of supporting TLS 1.2 - -See :ref:`winrm_tls12` for more information on how to enable TLS 1.2 on the -Windows host. +.. code-block:: shell -.. _winrm _credssp_cert: + pipx inject "pypsrp[credssp]<=1.0.0" # for psrp + pipx inject "pywinrm[credssp]>=0.4.0" # for winrm -Set CredSSP Certificate -+++++++++++++++++++++++ +Or, if you chose the ``pip`` install instructions: -CredSSP works by encrypting the credentials through the TLS protocol and uses a self-signed certificate by default. The ``CertificateThumbprint`` option under the WinRM service configuration can be used to specify the thumbprint of -another certificate. +.. code-block:: shell -.. Note:: This certificate configuration is independent of the WinRM listener - certificate. With CredSSP, message transport still occurs over the WinRM listener, - but the TLS-encrypted messages inside the channel use the service-level certificate. + pip3 install "pypsrp[credssp]<=1.0.0" # for psrp + pip3 install "pywinrm[credssp]>=0.4.0" # for winrm -To explicitly set the certificate to use for CredSSP: +CredSSP works by using a TLS connection to wrap the authentication tokens and subsequent messages sent over the connection. By default it will use a self-signed certificate automatically generated by Windows. While using CredSSP over a HTTPS connection will still need to validate the HTTPS certificate used by the WinRM listener, there is no validation done on the CredSSP certificate. It is possible to configure CredSSP to use a different certificate by setting the ``CertificateThumbprint`` option under the WinRM service configuration. .. code-block:: powershell - # Note the value $certificate_thumbprint will be different in each - # situation, this needs to be set based on the cert that is used. - $certificate_thumbprint = "7C8DCBD5427AFEE6560F4AF524E325915F51172C" + # Note the value $thumprint will be different in each situation, this needs + # to be set based on the cert that is used. + $thumbprint = "7C8DCBD5427AFEE6560F4AF524E325915F51172C" # Set the thumbprint value - Set-Item -Path WSMan:\localhost\Service\CertificateThumbprint -Value $certificate_thumbprint + Set-Item -Path WSMan:\localhost\Service\CertificateThumbprint -Value $thumbprint -.. _winrm_nonadmin: Non-Administrator Accounts --------------------------- @@ -647,7 +449,6 @@ enabled. While non-administrative accounts can be used with WinRM, most typical server administration tasks require some level of administrative access, so the utility is usually limited. -.. _winrm_encrypt: WinRM Encryption ----------------- @@ -666,8 +467,15 @@ option is ``NTLM``, ``Kerberos`` or ``CredSSP``. These protocols will encrypt the WinRM payload with their own encryption method before sending it to the server. The message-level encryption is not used when running over HTTPS because the encryption uses the more secure TLS protocol instead. If both transport and -message encryption is required, set ``ansible_winrm_message_encryption=always`` -in the host vars. +message encryption is required, the following hostvars can be set: + +.. code-block:: yaml+jinja + + # psrp + ansible_psrp_message_encryption: always + + # winrm + ansible_winrm_message_encryption: always .. Note:: Message encryption over HTTP requires pywinrm>=0.3.0. @@ -685,146 +493,16 @@ requirement: absolutely required. Doing so could allow sensitive information like credentials and files to be intercepted by others on the network. -.. _winrm_inventory: - -Inventory Options ------------------- - -Ansible's Windows support relies on a few standard variables to indicate the -username, password, and connection type of the remote hosts. These variables -are most easily set up in the inventory, but can be set on the ``host_vars``/ -``group_vars`` level. - -When setting up the inventory, the following variables are required: - -.. code-block:: yaml+jinja - - # It is suggested that these be encrypted with ansible-vault: - # ansible-vault edit group_vars/windows.yml - ansible_connection: winrm - - # May also be passed on the command-line through --user - ansible_user: Administrator - - # May also be supplied at runtime with --ask-pass - ansible_password: SecretPasswordGoesHere - - -Using the variables above, Ansible will connect to the Windows host with Basic -authentication through HTTPS. If ``ansible_user`` has a UPN value like -``username@MY.DOMAIN.COM`` then the authentication option will automatically attempt -to use Kerberos unless ``ansible_winrm_transport`` has been set to something other than -``kerberos``. - -The following custom inventory variables are also supported -for additional configuration of WinRM connections: - -* ``ansible_port``: The port WinRM will run over, HTTPS is ``5986`` which is - the default while HTTP is ``5985`` - -* ``ansible_winrm_scheme``: Specify the connection scheme (``http`` or - ``https``) to use for the WinRM connection. Ansible uses ``https`` by default - unless ``ansible_port`` is ``5985`` - -* ``ansible_winrm_path``: Specify an alternate path to the WinRM endpoint, - Ansible uses ``/wsman`` by default - -* ``ansible_winrm_realm``: Specify the realm to use for Kerberos - authentication. If ``ansible_user`` contains ``@``, Ansible will use the part - of the username after ``@`` by default - -* ``ansible_winrm_transport``: Specify one or more authentication transport - options as a comma-separated list. By default, Ansible will use ``kerberos, - basic`` if the ``kerberos`` module is installed and a realm is defined, - otherwise, it will be ``plaintext`` -* ``ansible_winrm_server_cert_validation``: Specify the server certificate - validation mode (``ignore`` or ``validate``). Ansible defaults to - ``validate`` on Python 2.7.9 and higher, which will result in certificate - validation errors against the Windows self-signed certificates. Unless - verifiable certificates have been configured on the WinRM listeners, this - should be set to ``ignore`` - -* ``ansible_winrm_operation_timeout_sec``: Increase the default timeout for - WinRM operations, Ansible uses ``20`` by default - -* ``ansible_winrm_read_timeout_sec``: Increase the WinRM read timeout, Ansible - uses ``30`` by default. Useful if there are intermittent network issues and - read timeout errors keep occurring - -* ``ansible_winrm_message_encryption``: Specify the message encryption - operation (``auto``, ``always``, ``never``) to use, Ansible uses ``auto`` by - default. ``auto`` means message encryption is only used when - ``ansible_winrm_scheme`` is ``http`` and ``ansible_winrm_transport`` supports - message encryption. ``always`` means message encryption will always be used - and ``never`` means message encryption will never be used - -* ``ansible_winrm_ca_trust_path``: Used to specify a different cacert container - than the one used in the ``certifi`` module. See the HTTPS Certificate - Validation section for more details. - -* ``ansible_winrm_send_cbt``: When using ``ntlm`` or ``kerberos`` over HTTPS, - the authentication library will try to send channel binding tokens to - mitigate against man-in-the-middle attacks. This flag controls whether these - bindings will be sent or not (default: ``true``). - -* ``ansible_winrm_*``: Any additional keyword arguments supported by - ``winrm.Protocol`` may be provided in place of ``*`` - -In addition, there are also specific variables that need to be set -for each authentication option. See the section on authentication above for more information. - -.. Note:: Ansible 2.0 has deprecated the "ssh" from ``ansible_ssh_user``, - ``ansible_ssh_pass``, ``ansible_ssh_host``, and ``ansible_ssh_port`` to - become ``ansible_user``, ``ansible_password``, ``ansible_host``, and - ``ansible_port``. If using a version of Ansible prior to 2.0, the older - style (``ansible_ssh_*``) should be used instead. The shorter variables - are ignored, without warning, in older versions of Ansible. - -.. Note:: ``ansible_winrm_message_encryption`` is different from transport - encryption done over TLS. The WinRM payload is still encrypted with TLS - when run over HTTPS, even if ``ansible_winrm_message_encryption=never``. - -.. _winrm_ipv6: - -IPv6 Addresses ---------------- - -IPv6 addresses can be used instead of IPv4 addresses or hostnames. This option -is normally set in an inventory. Ansible will attempt to parse the address -using the `ipaddress `_ -package and pass to ``pywinrm`` correctly. - -When defining a host using an IPv6 address, just add the IPv6 address as you -would an IPv4 address or hostname: - -.. code-block:: ini - - [windows-server] - 2001:db8::1 - - [windows-server:vars] - ansible_user=username - ansible_password=password - ansible_connection=winrm - - -.. Note:: The ipaddress library is only included by default in Python 3.x. To - use IPv6 addresses in Python 2.7, make sure to run ``pip install ipaddress`` which installs - a backported package. - -.. _winrm_https: +.. _windows_winrm_cert_validation: HTTPS Certificate Validation ----------------------------- -As part of the TLS protocol, the certificate is validated to ensure the host -matches the subject and the client trusts the issuer of the server certificate. -When using a self-signed certificate or setting -``ansible_winrm_server_cert_validation: ignore`` these security mechanisms are -bypassed. While self-signed certificates will always need the ``ignore`` flag, -certificates that have been issued from a certificate authority can still be -validated. +As part of the TLS protocol, the certificate is validated to ensure the host matches the subject and the client trusts the issuer of the server certificate. If using a self-signed certificate, the certificate will not be trusted by the client and the connection will fail. To bypass this, set the following hostvars depending on the connection plugin used: + +* ``ansible_psrp_cert_validation: ignore`` +* ``ansible_winrm_server_cert_validation: ignore`` One of the more common ways of setting up an HTTPS listener in a domain environment is to use Active Directory Certificate Service (AD CS). AD CS is @@ -838,152 +516,13 @@ certificate of the CA can be exported as a PEM-encoded certificate. This certificate can then be copied locally to the Ansible control node and used as a source of certificate validation, otherwise known as a CA chain. -The CA chain can contain a single or multiple issuer certificates and each -entry is contained on a new line. To then use the custom CA chain as part of -the validation process, set ``ansible_winrm_ca_trust_path`` to the path of the -file. If this variable is not set, the default CA chain is used instead which -is located in the install path of the Python package -`certifi `_. - -.. Note:: Each HTTP call is done by the Python requests library which does not - use the systems built-in certificate store as a trust authority. - Certificate validation will fail if the server's certificate issuer is - only added to the system's truststore. - -.. _winrm_tls12: - -TLS 1.2 Support ----------------- - -As WinRM runs over the HTTP protocol, using HTTPS means that the TLS protocol -is used to encrypt the WinRM messages. TLS will automatically attempt to -negotiate the best protocol and cipher suite that is available to both the -client and the server. If a match cannot be found then Ansible will error out -with a message similar to: - -.. code-block:: ansible-output - - HTTPSConnectionPool(host='server', port=5986): Max retries exceeded with url: /wsman (Caused by SSLError(SSLError(1, '[SSL: UNSUPPORTED_PROTOCOL] unsupported protocol (_ssl.c:1056)'))) - -Commonly this is when the Windows host has not been configured to support -TLS v1.2 but it could also mean the Ansible control node has an older OpenSSL -version installed. - -Windows 8 and Windows Server 2012 come with TLS v1.2 installed and enabled by -default but older hosts, like Server 2008 R2 and Windows 7, have to be enabled -manually. - -.. Note:: There is a bug with the TLS 1.2 patch for Server 2008 which will stop - Ansible from connecting to the Windows host. This means that Server 2008 - cannot be configured to use TLS 1.2. Server 2008 R2 and Windows 7 are not - affected by this issue and can use TLS 1.2. - -To verify what protocol the Windows host supports, you can run the following -command on the Ansible control node: - -.. code-block:: shell - - openssl s_client -connect :5986 - -The output will contain information about the TLS session and the ``Protocol`` -line will display the version that was negotiated: - -.. code-block:: console - - New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES256-SHA - Server public key is 2048 bit - Secure Renegotiation IS supported - Compression: NONE - Expansion: NONE - No ALPN negotiated - SSL-Session: - Protocol : TLSv1 - Cipher : ECDHE-RSA-AES256-SHA - Session-ID: 962A00001C95D2A601BE1CCFA7831B85A7EEE897AECDBF3D9ECD4A3BE4F6AC9B - Session-ID-ctx: - Master-Key: .... - Start Time: 1552976474 - Timeout : 7200 (sec) - Verify return code: 21 (unable to verify the first certificate) - --- - - New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES256-GCM-SHA384 - Server public key is 2048 bit - Secure Renegotiation IS supported - Compression: NONE - Expansion: NONE - No ALPN negotiated - SSL-Session: - Protocol : TLSv1.2 - Cipher : ECDHE-RSA-AES256-GCM-SHA384 - Session-ID: AE16000050DA9FD44D03BB8839B64449805D9E43DBD670346D3D9E05D1AEEA84 - Session-ID-ctx: - Master-Key: .... - Start Time: 1552976538 - Timeout : 7200 (sec) - Verify return code: 21 (unable to verify the first certificate) - -If the host is returning ``TLSv1`` then it should be configured so that -TLS v1.2 is enable. You can do this by running the following PowerShell -script: - -.. code-block:: powershell - - Function Enable-TLS12 { - param( - [ValidateSet("Server", "Client")] - [String]$Component = "Server" - ) - - $protocols_path = 'HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols' - New-Item -Path "$protocols_path\TLS 1.2\$Component" -Force - New-ItemProperty -Path "$protocols_path\TLS 1.2\$Component" -Name Enabled -Value 1 -Type DWORD -Force - New-ItemProperty -Path "$protocols_path\TLS 1.2\$Component" -Name DisabledByDefault -Value 0 -Type DWORD -Force - } +The CA chain can contain a single or multiple issuer certificates and each entry is contained on a new line. To then use the custom CA chain as part of the validation process, set the following hostvar depending on the connection plugin used to the path of the CA PEM formatted file: - Enable-TLS12 -Component Server +* ``ansible_psrp_ca_cert`` +* ``ansible_winrm_ca_trust_path`` - # Not required but highly recommended to enable the Client side TLS 1.2 components - Enable-TLS12 -Component Client +If this variable is not set, the default CA chain is used instead which is located in the install path of the Python package `certifi `_. Some Linux distributions may have configured the underlying Python ``requests`` library that the ``psrp`` and ``winrm`` connection plugins use to use the system's certificate store rather than ``certifi``. If this is the case, the CA chain will be the same as the system's certificate store. - Restart-Computer - -The below Ansible tasks can also be used to enable TLS v1.2: - -.. code-block:: yaml+jinja - - - name: enable TLSv1.2 support - win_regedit: - path: HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\{{ item.type }} - name: '{{ item.property }}' - data: '{{ item.value }}' - type: dword - state: present - register: enable_tls12 - loop: - - type: Server - property: Enabled - value: 1 - - type: Server - property: DisabledByDefault - value: 0 - - type: Client - property: Enabled - value: 1 - - type: Client - property: DisabledByDefault - value: 0 - - - name: reboot if TLS config was applied - win_reboot: - when: enable_tls12 is changed - -There are other ways to configure the TLS protocols as well as the cipher -suites that are offered by the Windows host. One tool that can give you a GUI -to manage these settings is `IIS Crypto `_ -from Nartac Software. - -.. _winrm_limitations: WinRM limitations ------------------ @@ -1008,9 +547,7 @@ These include: Some of these limitations can be mitigated by doing one of the following: -* Set ``ansible_winrm_transport`` to ``credssp`` or ``kerberos`` (with - ``ansible_winrm_kerberos_delegation=true``) to bypass the double-hop issue - and access network resources +* Set the authentication method to use ``credssp`` or ``kerberos`` with credential delegation enabled * Use ``become`` to bypass all WinRM restrictions and run a command as it would locally. Unlike using an authentication transport like ``credssp``, this will @@ -1022,6 +559,67 @@ Some of these limitations can be mitigated by doing one of the following: restrictions but can only run a command and not modules. +WinRM Troubleshooting +--------------------- +WinRM has a wide range of configuration options, which makes its configuration complex. As a result, errors that Ansible displays could in fact be problems with the host setup instead. + +To identify a host issue, run the following command from another Windows host to test out a connection to the target Windows host. + +* To test HTTP: + +.. code-block:: powershell + + # winrm + winrs -r:http://server:5985/wsman -u:Username -p:Password ipconfig + + # psrp + Invoke-Command -ComputerName server { ipconfig } -Credential username + +* To test HTTPS: + +.. code-block:: powershell + + # winrm + winrs -r:https://server:5986/wsman -u:Username -p:Password -ssl ipconfig + + # psrp + Invoke-Command -UseSSL -ComputerName server { ipconfig } -Credential username + + # psrp ignoring certs + $sessionOption = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck + Invoke-Command -UseSSL -ComputerName server { ipconfig } -Credential username -SessionOption $sessionOption + +To verify that the target hostname is resolvable on the Ansible control node, run one of the following commands: + +.. code-block:: bash + + dig +search server + + # May fail if the Windows firewall is set to block ICMP pings + # but will show the hostname if resolvable. + ping server + +To verify that the WinRM service is listening and a firewall is not blocking the connection you can use ``nc`` to test the connection over the WinRM port: + +.. code-block:: bash + + # HTTP port + > nc -zv server 5985 + Connection to server port 5985 [tcp/wsman] succeeded! + + # HTTPS port + > nc -zv server 5986 + Connection to server port 5986 [tcp/wsmans] succeeded! + +To verify that WinRM has a HTTPS listener and is working you can use ``openssl s_client`` to test the connection and view the certificate details with: + +.. code-block:: bash + + echo '' | openssl s_client -connect server:5986 + +.. note:: + The ``openssl s_client`` command will use the system trust store to validate the certificate which may not align with the trust store used in Ansible. See :ref:`windows_winrm_cert_validation` for more information. + .. seealso:: :ref:`playbooks_intro` diff --git a/docs/docsite/rst/os_guide/windows_winrm_certificate.rst b/docs/docsite/rst/os_guide/windows_winrm_certificate.rst new file mode 100644 index 00000000000..080202c1fa8 --- /dev/null +++ b/docs/docsite/rst/os_guide/windows_winrm_certificate.rst @@ -0,0 +1,212 @@ +.. _windows_winrm_certificate: + +WinRM Certificate Authentication +================================ + +WinRM certificate authentication is a method of authenticating to a Windows host using X.509 certificates instead of a username and password. + +.. contents:: + :local: + +Certificate authentication does have some disadvantages compared to SSH key based authentication such as: + +* it can only be mapped to a local Windows user, no domain accounts +* the username and password must be mapped to the certificate, if the password changes, the cert will need to be re-mapped +* an administrator on the Windows host can retrieve the local user password through the certificate mapping +* Ansible cannot use encrypted private keys, they must be stored without encryption +* Ansible cannot use the certs and private keys stored as a var, they must be a file + + +Ansible Configuration +--------------------- + +Certificate authentication uses certificates as keys similar to SSH key pairs. The public and private key is stored on the Ansible control node to use for authentication. The following example shows the hostvars configured for certificate authentication: + +.. code-block:: yaml+jinja + + # psrp + ansible_connection: psrp + ansible_psrp_auth: certificate + ansible_psrp_certificate_pem: /path/to/certificate/public_key.pem + ansible_psrp_certificate_key_pem: /path/to/certificate/private_key.pem + + # winrm + ansible_connection: winrm + ansible_winrm_transport: certificate + ansible_winrm_cert_pem: /path/to/certificate/public_key.pem + ansible_winrm_cert_key_pem: /path/to/certificate/private_key.pem + +Certificate authentication is not enabled by default on a Windows host but can be enabled by running the following in PowerShell: + +.. code-block:: powershell + + Set-Item -Path WSMan:\localhost\Service\Auth\Certificate -Value $true + +The private key cannot be encrypted due to a limitation of the underlying Python library used by Ansible. + +.. note:: + For enabling certificate authentication with a TLS 1.3 connection, Python 3.8+, 3.7.1, or 3.6.7 and Python package urllib3>=2.0.7 or newer are required. + + +Certificate Generation +---------------------- + +The first step of using certificate authentication is to generate a certificate and private key. The certificate must be generated with the following properties: + +* ``Extended Key Usage`` must include ``clientAuth (1.3.6.1.5.5.7.3.2)`` +* ``Subject Alternative Name`` must include ``otherName`` entry for ``userPrincipalName (1.3.6.1.4.1.311.20.2.3)`` + +The ``userPrincipalName`` value can be anything but in this guide we will use the value ``$USERNAME@localhost`` where ``$USERNAME`` is the name of the user that the certificate will be mapped to. + +This can be done through a variety of methods, such as OpenSSL, PowerShell, or Active Directory Certificate Services. The following example shows how to generate a certificate using OpenSSL: + +.. code-block:: bash + + # Set the username to the name of the user the certificate will be mapped to + USERNAME="local-user" + + cat > openssl.conf << EOL + distinguished_name = req_distinguished_name + + [req_distinguished_name] + [v3_req_client] + extendedKeyUsage = clientAuth + subjectAltName = otherName:1.3.6.1.4.1.311.20.2.3;UTF8:${USERNAME}@localhost + EOL + + openssl req \ + -new \ + -sha256 \ + -subj "/CN=${USERNAME}" \ + -newkey rsa:2048 \ + -nodes \ + -keyout cert.key \ + -out cert.csr \ + -config openssl.conf \ + -reqexts v3_req_client + + openssl x509 \ + -req \ + -in cert.csr \ + -sha256 \ + -out cert.pem \ + -days 365 \ + -extfile openssl.conf \ + -extensions v3_req_client \ + -key cert.key + + rm openssl.conf cert.csr + +The following example shows how to generate a certificate using PowerShell: + +.. code-block:: powershell + + # Set the username to the name of the user the certificate will be mapped to + $username = 'local-user' + + $clientParams = @{ + CertStoreLocation = 'Cert:\CurrentUser\My' + NotAfter = (Get-Date).AddYears(1) + Provider = 'Microsoft Software Key Storage Provider' + Subject = "CN=$username" + TextExtension = @("2.5.29.37={text}1.3.6.1.5.5.7.3.2","2.5.29.17={text}upn=$username@localhost") + Type = 'Custom' + } + $cert = New-SelfSignedCertificate @clientParams + $certKeyName = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey( + $cert).Key.UniqueName + + # Exports the public cert.pem and key cert.pfx + Set-Content -Path "cert.pem" -Value @( + "-----BEGIN CERTIFICATE-----" + [Convert]::ToBase64String($cert.RawData) -replace ".{64}", "$&`n" + "-----END CERTIFICATE-----" + ) + $certPfxBytes = $cert.Export('Pfx', '') + [System.IO.File]::WriteAllBytes("$pwd\cert.pfx", $certPfxBytes) + + # Removes the private key and cert from the store after exporting + $keyPath = [System.IO.Path]::Combine($env:AppData, 'Microsoft', 'Crypto', 'Keys', $certKeyName) + Remove-Item -LiteralPath "Cert:\CurrentUser\My\$($cert.Thumbprint)" -Force + Remove-Item -LiteralPath $keyPath -Force + +As PowerShell cannot generate a PKCS8 PEM private key, we need to use OpenSSL to convert the ``cert.pfx`` file to a PEM private key: + +.. code-block:: bash + + openssl pkcs12 \ + -in cert.pfx \ + -nocerts \ + -nodes \ + -passin pass: | + sed -ne '/-BEGIN PRIVATE KEY-/,/-END PRIVATE KEY-/p' > cert.key + +The ``cert.pem`` is the public key and the ``cert.key`` is the plaintext private key. These files must be accessible by the Ansible control node to use for authentication. The private key does not need to be present on the Windows node. + + +Windows Configuration +--------------------- + +Once the public and private key has been generated we need to import and trust the public key and configure the user mapping on the Windows host. +The Windows host does not need access to the private key, only the public key ``cert.pem`` needs to be accessible to configure the certificate authentication. + + +Import Certificate to the Certificate Store +""""""""""""""""""""""""""""""""""""""""""" + +For Windows to trust the certificate it must be imported into the ``LocalMachine\TrustedPeople`` certificate store. You can do this by running the following: + +.. code-block:: powershell + + $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new("cert.pem") + + $store = Get-Item -LiteralPath Cert:\LocalMachine\TrustedPeople + $store.Open('ReadWrite') + $store.Add($cert) + $store.Dispose() + +If the cert is self-signed, or issued by a CA that is not trusted by the host, you will need to import the CA certificate into the trusted root store. As our example uses a self-signed cert, we will import that certificate as a trusted CA but in a production environment you would import the CA that signed the certificate. + +.. code-block:: powershell + + $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new("cert.pem") + + $store = Get-Item -LiteralPath Cert:\LocalMachine\Root + $store.Open('ReadWrite') + $store.Add($cert) + $store.Dispose() + + +Mapping Certificate to a Local Account +"""""""""""""""""""""""""""""""""""""" + +Once the certificate has been imported into the ``LocalMachine\TrustedPeople`` store, the WinRM service can create the mapping between the certificate and a local account. This is done by running the following: + +.. code-block:: powershell + + # Will prompt for the password of the user. + $credential = Get-Credential local-user + + $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new("cert.pem") + $certChain = [System.Security.Cryptography.X509Certificates.X509Chain]::new() + [void]$certChain.Build($cert) + $caThumbprint = $certChain.ChainElements.Certificate[-1].Thumbprint + + $certMapping = @{ + Path = 'WSMan:\localhost\ClientCertificate' + Subject = $cert.GetNameInfo('UpnName', $false) + Issuer = $caThumbprint + Credential = $credential + Force = $true + } + New-Item @certMapping + +The ``Subject`` is the value of the ``userPrincipalName`` in the certificate SAN entry. The ``Issuer`` is the thumbprint of the CA certificate that issued our certificate. The ``Credential`` is the username and password of the local user we are mapping the certificate to. + +Using Ansible +""""""""""""" + +The following Ansible playbook can be used to create a local user and map the certificate provided to use for certificate authentication. It needs to be called ``username`` and ``cert_pem`` variable set to the name of the user to create and the path to the public key PEM file that was generated. This playbook expects ``cert_pem`` to be a self signed certificate, if using a certificate issued by a CA, you will have to edit it so it copies that across and imports it to the ``LocalMachine\Root`` store instead. + +.. literalinclude:: yaml/winrm_cert_auth_setup.yaml + :language: yaml diff --git a/docs/docsite/rst/os_guide/windows_winrm_kerberos.rst b/docs/docsite/rst/os_guide/windows_winrm_kerberos.rst new file mode 100644 index 00000000000..7b508a7f7fb --- /dev/null +++ b/docs/docsite/rst/os_guide/windows_winrm_kerberos.rst @@ -0,0 +1,298 @@ +.. _windows_winrm_kerberos: + +Kerberos Authentication +======================= + +Kerberos authentication is a modern method used in Windows environments for authentication. It allows both the client and server to verify each others identities and supports modern encryption methods like AES. + +.. contents:: + :local: + + +Installing Kerberos +------------------- + +Kerberos is provided through a GSSAPI library which is part of a system package. Some distributions install the Kerberos packages by default but others may require manual installation. + +To install the Kerberos libraries on a RHEL/Fedora based system: + +.. code-block:: bash + + $ sudo dnf install krb5-devel krb5-libs krb5-workstation python3-devel + +For a Debian/Ubuntu based system: + +.. code-block:: bash + + $ sudo apt-get install krb5-user libkrb5-dev python3-dev + +For an Arch Linux based system: + +.. code-block:: bash + + $ sudo pacman -S krb5 + +For a FreeBSD based system: + +.. code-block:: bash + + $ sudo pkg install heimdal + +.. note:: + The ``python3-devel`` / ``python3-dev`` packages can be ignored if using Kerberos with the ``ssh`` connection plugin. They are only needed if using a WinRM based connection with Kerberos authentication. + +Once installed the ``kinit``, ``klist``, and ``krb5-config`` packages will be available. You can test them out with the following command: + +.. code-block:: bash + + $ krb5-config --version + + Kerberos 5 release 1.21.3 + +The ``psrp`` and ``winrm`` connection plugins require extra Python libraries for Kerberos authentication. The following step can be skipped if using Kerberos with the ``ssh`` connection. + +If you chose the ``pipx`` install instructions for Ansible, you can install those requirements by running the following: + +.. code-block:: shell + + pipx inject "pypsrp[kerberos]<=1.0.0" # for psrp + pipx inject "pywinrm[kerberos]>=0.4.0" # for winrm + +Or, if you chose the ``pip`` install instructions: + +.. code-block:: shell + + pip3 install "pypsrp[kerberos]<=1.0.0" # for psrp + pip3 install "pywinrm[kerberos]>=0.4.0" # for winrm + + +Configuring Host Kerberos +------------------------- + +Once the dependencies have been installed, Kerberos needs to be configured so that it can communicate with a domain. Most Kerberos implementations can either find a domain using DNS or through manual configuration in the ``/etc/krb5.conf`` file. For details on what can be set in the ``/etc/krb5.conf`` file see `krb5.conf `_ for more details. A simple ``krb5.conf`` file that uses DNS to lookup the KDC would be: + +.. code-block:: ini + + [libdefaults] + # Not required but helpful if the realm cannot be determined from + # the hostname + default_realm = MY.DOMAIN.COM + + # Enabled KDC lookups from DNS SRV records + dns_lookup_kdc = true + +With the above configuration when a Kerberos ticket is requested for the server ``server.my.domain.com`` the Kerberos library will do an SRV lookup for ``_kerberos._udp.my.domain.com`` and ``_kerberos._tcp.my.domain.com`` to find the KDC. If you wish to manually set the KDC realms you can use the following configuration: + +.. code-block:: ini + + [libdefaults] + default_realm = MY.DOMAIN.COM + dns_lookup_kdc = false + + [realms] + MY.DOMAIN.COM = { + kdc = domain-controller1.my.domain.com + kdc = domain-controller2.my.domain.com + } + + [domain_realm] + .my.domain.com = MY.DOMAIN.COM + my.domain.com = MY.DOMAIN.COM + +With this configuration any request for a ticket with the DNS suffix ``.my.domain.com`` and ``my.domain.com`` itself will be sent to the KDC ``domain-controller1.my.domain.com`` with a fallback to ``domain-controller2.my.domain.com``. + +More information on how the Kerberos library attempts to find the KDC can be found in the `MIT Kerberos Documentation `_. + +.. note:: + The information in this section assumes you are using the MIT Kerberos implementation which is typically the default on most Linux distributions. Some platforms like FreeBSD or macOS use a different GSSAPI implementation called Heimdal which acts in a similar way to MIT Kerberos but some behaviors may be different. + + +.. _winrm_kerberos_verify_config: + +Verifying Kerberos Configuration +-------------------------------- + +To verify that Kerberos is working correctly, you can use the ``kinit`` command to obtain a ticket for a user in the domain. The following command will request a ticket for the user ``username`` in the domain ``MY.DOMAIN.COM``: + +.. code-block:: bash + + $ kinit username@MY.DOMAIN.COM + Password for username@REALM.COM + +If the password is correct, the command will return without any output. To verify that the ticket has been obtained, you can use the ``klist`` command: + +.. code-block:: bash + + > klist + Ticket cache: KCM:1000 + Default principal: username@MY.DOMAIN.COM + + Valid starting Expires Service principal + 29/08/24 13:54:51 29/08/24 23:54:51 krbtgt/MY.DOMAIN.COM@MY.DOMAIN.COM + renew until 05/09/24 13:54:48 + +If successful, this validates that the Kerberos configuration is correct and that the user can obtain a Ticket Granting Ticket (``TGT``) from the KDC. If ``kinit`` is unable to find the KDC for the requested realm, verify your Kerberos configuration by ensuring DNS can locate the KDC using the SRV records or that the KDC is manually mapped in the ``krb5.conf``. + +On MIT Kerberos based systems, you can use the ``kvno`` command to verify that you are able to retrieve a service ticket for a particular service. For example, if you are using a WinRM based connection to authenticate with ``server.my.domain.com`` you can use the following command to verify that your TGT is able to get a service ticket for the target server: + +.. code-block:: bash + + $ kvno http/server.my.domain.com + http/server2025.domain.test@DOMAIN.TEST: kvno = 2 + +The ``klist`` command can also be used to verify the ticket was stored in the Kerberos cache: + +.. code-block:: bash + + $ klist + Ticket cache: KCM:1000 + Default principal: username@MY.DOMAIN.COM + + Valid starting Expires Service principal + 29/08/24 13:54:51 29/08/24 23:54:51 krbtgt/MY.DOMAIN.COM@MY.DOMAIN.COM + renew until 05/09/24 13:54:48 + 29/08/24 13:55:30 29/08/24 23:55:30 http/server.my.domain.com@MY.DOMAIN.COM + renew until 05/09/24 13:55:30 + +In the above example we have the TGT stored under the ``krbtgt`` service principal and our ``http/server.my.domain.com`` under its own service principal. + +The ``kdestroy`` command can be used to remove the ticket cache. + + +Ticket Management +----------------- + +For Kerberos authentication to work with Ansible, a Kerberos TGT for a user must be present so that Ansible can request a service ticket for the target server. Some connection plugins like ``ssh`` require the TGT to already be present and accessible to the Ansible control process. Other connection plugins, like ``psrp`` and ``winrm``, can automatically obtain a TGT for the user if the user's password is provided in the inventory. + +To retrieve a TGT manually for a user, run the ``kinit`` command with the user's username and domain as shown in :ref:`winrm_kerberos_verify_config`. This TGT will be used automatically when Kerberos authentication is requested by the connection plugin in Ansible. + +If you are using the ``psrp`` or ``winrm`` connection plugin and the user's password is provided in the inventory, the connection plugin will automatically obtain a TGT for the user. This is done by running the ``kinit`` command with the user's username and password. The TGT will be stored in a temporary credential cache and will be used for the task. + + +Delegation +---------- + +Kerberos delegation allows the credentials to traverse multiple hops. This is useful when you need to authenticate to a server and then have that server authenticate to another server on your behalf. To enable delegation, you must: + +* request a forwardable TGT when obtaining a ticket with ``kinit`` +* request the connection plugin to allow delegation to the server +* the AD user is not marked as sensitive and cannot be delegated and is not a member of the ``Protected Users`` group +* depending on the ``krb5.conf`` configuration, the target server may need to allow unconstrained delegation through its AD object delegation settings + +To request a forwardable TGT, either add the ``-f`` flag to the ``kinit`` command or set the ``forwardable = true`` option in the ``[libdefaults]`` section of the ``krb5.conf`` file. If you are using the ``psrp`` or ``winrm`` connection plugin to retrieve the TGT from the user's password in the inventory, it will automatically request a forwardable TGT if the connection plugin is configured to use delegation. + +To have the connection plugin delegate the credentials it will need to set the following hostvar in the inventory: + +.. code-block:: yaml+jinja + + # psrp + ansible_psrp_negotiate_delegate: true + + # winrm + ansible_winrm_kerberos_delegation: true + + # ssh + ansible_ssh_common_args: -o GSSAPIDelegateCredentials=yes + +.. note:: + It is also possible to set ``GSSAPIDelegateCredentials yes`` in the ``~/.ssh/config`` file to allow delegation for all SSH connections. + +To verify if a user is allowed to delegate their credentials, you can run the following PowerShell script on a Windows host in the same domain: + +.. code-block:: powershell + + Function Test-IsDelegatable { + [CmdletBinding()] + param ( + [Parameter(Mandatory)] + [string] + $UserName + ) + + $NOT_DELEGATED = 0x00100000 + + $searcher = [ADSISearcher]"(&(objectClass=user)(objectCategory=person)(sAMAccountName=$UserName))" + $res = $searcher.FindOne() + if (-not $res) { + Write-Error -Message "Failed to find user '$UserName'" + } + else { + $uac = $res.Properties.useraccountcontrol[0] + $memberOf = @($res.Properties.memberof) + + $isSensitive = [bool]($uac -band $NOT_DELEGATED) + $isProtectedUser = [bool]($memberOf -like 'CN=Protected Users,*').Count + + -not ($isSensitive -or $isProtectedUser) + } + } + + Test-IsDelegatable -UserName username + +Newer versions of MIT Kerberos have added a configuration option ``enforce_ok_as_delegate`` in the ``[libdefaults]`` section of the ``krb5.conf`` file. If this option is set to ``true`` delegation will only work if the target server account allows unconstrained delegation. To check or set unconstrained delegation on a Windows computer host, you can use the following PowerShell script: + +.. code-block:: powershell + + # Check if the server allows unconstrained delegation + (Get-ADComputer -Identity WINHOST -Properties TrustedForDelegation).TrustedForDelegation + + # Enable unconstrained delegation + Set-ADComputer -Identity WINHOST -TrustedForDelegation $true + +To verify that delegation is working, you can use the ``klist.exe`` command on the Windows node to verify that the ticket has been forwarded. The output should show the ticket server is for ``krbtgt/MY.DOMAIN.COM @ MY.CDOMAIN.COM`` and the ticket flags contained ``forwarded``. + +.. code-block:: shell + + $ ansible WINHOST -m ansible.windows.win_command -a klist.exe + + WINHOST | CHANGED | rc=0 >> + + Current LogonId is 0:0x82b6977 + + Cached Tickets: (1) + + #0> Client: username @ MY.DOMAIN.COM + Server: krbtgt/MY.DOMAIN.COM @ MY.DOMAIN.COM + KerbTicket Encryption Type: AES-256-CTS-HMAC-SHA1-96 + Ticket Flags 0x60a10000 -> forwardable forwarded renewable pre_authent name_canonicalize + Start Time: 8/30/2024 14:15:18 (local) + End Time: 8/31/2024 0:12:49 (local) + Renew Time: 9/6/2024 14:12:49 (local) + Session Key Type: AES-256-CTS-HMAC-SHA1-96 + Cache Flags: 0x1 -> PRIMARY + Kdc Called: + +If anything goes wrong, the output for ``klist.exe`` will not have the ``forwarded`` flag and the server will be for the target server principal and not ``krbtgt``. + +.. code-block:: shell + + $ ansible WINHOST -m ansible.windows.win_command -a klist.exe + + WINHOST | CHANGED | rc=0 >> + + Current LogonId is 0:0x82c312c + + Cached Tickets: (1) + + #0> Client: username @ MY.DOMAIN.COM + Server: http/winhost.my.domain.com @ MY.DOMAIN.COM + KerbTicket Encryption Type: AES-256-CTS-HMAC-SHA1-96 + Ticket Flags 0x40a10000 -> forwardable renewable pre_authent name_canonicalize + Start Time: 8/30/2024 14:16:24 (local) + End Time: 8/31/2024 0:16:12 (local) + Renew Time: 0 + Session Key Type: AES-256-CTS-HMAC-SHA1-96 + Cache Flags: 0x8 -> ASC + Kdc Called: + + +Troubleshooting Kerberos +------------------------ + +Kerberos is reliant on a properly configured environment to work. Some common issues that can cause Kerberos authentication to fail are: + +* The hostname set for the Windows host is an alias or an IP address +* The time on the Ansible control node is not synchronized with the AD domain controller +* The KDC realm is not set correctly in the ``krb5.conf`` file or cannot be resolved through DNS + +If using the MIT Kerberos implementation, you can set the environment variable ``KRB5_TRACE=/dev/stdout`` to get more detailed information on what the Kerberos library is doing. This can be useful for debugging issues with the Kerberos library such as the KDC lookup behavior, time sync issues, and server name lookup failures. diff --git a/docs/docsite/rst/os_guide/yaml/winrm_cert_auth_setup.yaml b/docs/docsite/rst/os_guide/yaml/winrm_cert_auth_setup.yaml new file mode 100644 index 00000000000..facfbbf5d25 --- /dev/null +++ b/docs/docsite/rst/os_guide/yaml/winrm_cert_auth_setup.yaml @@ -0,0 +1,118 @@ +- name: Setup WinRM Client Cert Authentication + hosts: windows + gather_facts: false + + tasks: + - name: Verify required facts are setup + ansible.builtin.assert: + that: + - cert_pem is defined + - username is defined + + - name: Check that the required files are present + ansible.builtin.stat: + path: '{{ cert_pem }}' + delegate_to: localhost + run_once: true + register: local_cert_stat + + - name: Fail if cert PEM is not present + ansible.builtin.assert: + that: + - local_cert_stat.stat.exists + + - name: Generate local user password + ansible.builtin.set_fact: + user_password: "{{ lookup('ansible.builtin.password', playbook_dir ~ '/user_password', length=15) }}" + + - name: Create local user + ansible.windows.win_user: + name: '{{ username }}' + groups: + - Administrators + - Users + update_password: always + password: '{{ user_password }}' + user_cannot_change_password: true + password_never_expires: true + + - name: Copy across client certificate + ansible.windows.win_copy: + src: '{{ cert_pem }}' + dest: C:\Windows\TEMP\cert.pem + + - name: Import client certificate + ansible.windows.win_certificate_store: + path: C:\Windows\TEMP\cert.pem + state: present + store_location: LocalMachine + store_name: '{{ item }}' + register: client_cert_info + loop: + - Root + - TrustedPeople + + - name: Enable WinRM Certificate auth + ansible.windows.win_powershell: + script: | + $ErrorActionPreference = 'Stop' + $Ansible.Changed = $false + + $authPath = 'WSMan:\localhost\Service\Auth\Certificate' + if ((Get-Item -LiteralPath $authPath).Value -ne 'true') { + Set-Item -LiteralPath $authPath -Value true + $Ansible.Changed = $true + } + + - name: Setup Client Certificate Mapping + ansible.windows.win_powershell: + parameters: + Thumbprint: '{{ client_cert_info.results[0].thumbprints[0] }}' + sensitive_parameters: + - name: Credential + username: '{{ username }}' + password: '{{ user_password }}' + script: | + param( + [Parameter(Mandatory)] + [PSCredential] + $Credential, + + [Parameter(Mandatory)] + [string] + $Thumbprint + ) + + $ErrorActionPreference = 'Stop' + $Ansible.Changed = $false + + $userCert = Get-Item -LiteralPath "Cert:\LocalMachine\TrustedPeople\$Thumbprint" + $subject = $userCert.GetNameInfo('UpnName', $false) # SAN userPrincipalName + + $certChain = New-Object -TypeName Security.Cryptography.X509Certificates.X509Chain + [void]$certChain.Build($userCert) + $caThumbprint = $certChain.ChainElements.Certificate[-1].Thumbprint + + $mappings = Get-ChildItem -LiteralPath WSMan:\localhost\ClientCertificate | + Where-Object { + $mapping = $_ | Get-Item + "Subject=$subject" -in $mapping.Keys + } + + if ($mappings -and "issuer=$($caThumbprint)" -notin $mappings.Keys) { + $null = $mappings | Remove-Item -Force -Recurse + $mappings = $null + $Ansible.Changed = $true + } + + if (-not $mappings) { + $certMapping = @{ + Path = 'WSMan:\localhost\ClientCertificate' + Subject = $subject + Issuer = $caThumbprint + Credential = $Credential + Force = $true + } + $null = New-Item @certMapping + $Ansible.Changed = $true + } diff --git a/docs/docsite/rst/user_guide/windows_faq.rst b/docs/docsite/rst/user_guide/windows_faq.rst index 0dc92a9f329..ec937f8d13b 100644 --- a/docs/docsite/rst/user_guide/windows_faq.rst +++ b/docs/docsite/rst/user_guide/windows_faq.rst @@ -3,4 +3,4 @@ Windows Frequently Asked Questions ================================== -This page has moved to :ref:`windows_faq`. \ No newline at end of file +This page has moved to :ref:`working_with_windows`. \ No newline at end of file diff --git a/docs/docsite/rst/user_guide/windows_setup.rst b/docs/docsite/rst/user_guide/windows_setup.rst index 95ac6457436..1614b3fd499 100644 --- a/docs/docsite/rst/user_guide/windows_setup.rst +++ b/docs/docsite/rst/user_guide/windows_setup.rst @@ -3,4 +3,4 @@ Setting up a Windows Host ========================= -This page has moved to :ref:`windows_setup`. \ No newline at end of file +This page has moved to :ref:`working_with_windows`. \ No newline at end of file From 2f20082a3bb22f7687ede91e14706c3545df322c Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Sat, 14 Sep 2024 23:18:53 -0500 Subject: [PATCH 502/536] ci: refresh dev dependencies (#1888) --- tests/formatters.txt | 2 +- tests/static.txt | 2 +- tests/tag.txt | 2 +- tests/typing.txt | 8 ++++---- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/tests/formatters.txt b/tests/formatters.txt index d4f150de305..25197481cf7 100644 --- a/tests/formatters.txt +++ b/tests/formatters.txt @@ -16,5 +16,5 @@ packaging==24.1 # via black pathspec==0.12.1 # via black -platformdirs==4.3.2 +platformdirs==4.3.3 # via black diff --git a/tests/static.txt b/tests/static.txt index 6c5de9e1de0..eb7429b58a7 100644 --- a/tests/static.txt +++ b/tests/static.txt @@ -4,5 +4,5 @@ # # pip-compile --allow-unsafe --output-file=tests/static.txt --strip-extras tests/static.in # -ruff==0.6.4 +ruff==0.6.5 # via -r tests/static.in diff --git a/tests/tag.txt b/tests/tag.txt index e57ef431d82..177f3250cb7 100644 --- a/tests/tag.txt +++ b/tests/tag.txt @@ -18,7 +18,7 @@ packaging==24.1 # via -r tests/tag.in pygments==2.18.0 # via rich -rich==13.8.0 +rich==13.8.1 # via typer shellingham==1.5.4 # via typer diff --git a/tests/typing.txt b/tests/typing.txt index 30f74ad60dc..5573e9252f5 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -32,7 +32,7 @@ gitdb==4.0.11 # via gitpython gitpython==3.1.43 # via -r tests/tag.in -idna==3.8 +idna==3.9 # via requests jinja2==3.1.4 # via -r tests/../hacking/pr_labeler/requirements.txt @@ -52,7 +52,7 @@ packaging==24.1 # via # -r tests/tag.in # nox -platformdirs==4.3.2 +platformdirs==4.3.3 # via virtualenv pycparser==2.22 # via cffi @@ -66,7 +66,7 @@ pynacl==1.5.0 # via pygithub requests==2.32.3 # via pygithub -rich==13.8.0 +rich==13.8.1 # via typer shellingham==1.5.4 # via typer @@ -82,7 +82,7 @@ typing-extensions==4.12.2 # mypy # pygithub # typer -urllib3==2.2.2 +urllib3==2.2.3 # via # pygithub # requests From 7220bccfde8ba62073c9fcd6852456ca9cd75926 Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Sun, 15 Sep 2024 14:24:44 +0200 Subject: [PATCH 503/536] Fix Ansible 11 roadmap (#1892) --- docs/docsite/rst/roadmap/COLLECTIONS_11.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/roadmap/COLLECTIONS_11.rst b/docs/docsite/rst/roadmap/COLLECTIONS_11.rst index 7d8a333c335..5a9be096182 100644 --- a/docs/docsite/rst/roadmap/COLLECTIONS_11.rst +++ b/docs/docsite/rst/roadmap/COLLECTIONS_11.rst @@ -33,7 +33,7 @@ Release schedule :2024-11-15: Last day to trigger an Ansible-11.0.0rc2 release because of major defects in Ansible-11.0.0rc1. :2024-11-19: Ansible-11.0.0rc2 when necessary, otherwise Ansible-11.0.0 release. :2024-11-26: Ansible-11.0.0 release when Ansible-11.0.0rc2 was necessary. -:2024-11-19 or 2023-11-26: Create the ansible-build-data directory and files for Ansible-11. +:2024-11-19 or 2023-11-26: Create the ansible-build-data directory and files for Ansible-12. :2024-12-02: Release of ansible-core 2.18.1. :2024-12-03: Release of Ansible-11.1.0 (bugfix + compatible features: every four weeks.) From 61db4dafb04e3f9d8c91e47fdbf78aaf085bd1ae Mon Sep 17 00:00:00 2001 From: "ansible-documentation-bot[bot]" <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> Date: Mon, 16 Sep 2024 17:45:01 +0100 Subject: [PATCH 504/536] ci: refresh docs build dependencies (#1891) Co-authored-by: Ansible Documentation Bot <147556122+ansible-documentation-bot[bot]@users.noreply.github.com> --- tests/requirements-relaxed.txt | 14 +++++++------- tests/requirements.txt | 14 +++++++------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index e76e462a707..022ded198e2 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -26,7 +26,7 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-changelog==0.30.0 # via antsibull-docs -antsibull-core==3.0.2 +antsibull-core==3.1.0 # via antsibull-docs antsibull-docs==2.14.0 # via -r tests/requirements-relaxed.in @@ -34,9 +34,10 @@ antsibull-docs-parser==1.1.0 # via antsibull-docs antsibull-docutils==1.0.0 # via antsibull-changelog -antsibull-fileutils==1.0.0 +antsibull-fileutils==1.0.1 # via # antsibull-changelog + # antsibull-core # antsibull-docs asyncio-pool==0.6.0 # via antsibull-docs @@ -66,7 +67,7 @@ frozenlist==1.4.1 # via # aiohttp # aiosignal -idna==3.8 +idna==3.9 # via # requests # yarl @@ -79,7 +80,7 @@ jinja2==3.1.4 # sphinx markupsafe==2.1.5 # via jinja2 -multidict==6.0.5 +multidict==6.1.0 # via # aiohttp # yarl @@ -107,7 +108,6 @@ pyproject-hooks==1.1.0 pyyaml==6.0.2 # via # -r tests/requirements-relaxed.in - # antsibull-core # antsibull-docs # antsibull-fileutils requests==2.32.3 @@ -173,9 +173,9 @@ typing-extensions==4.12.2 # via # pydantic # pydantic-core -urllib3==2.2.2 +urllib3==2.2.3 # via requests -yarl==1.11.0 +yarl==1.11.1 # via aiohttp # The following packages are considered to be unsafe in a requirements file: diff --git a/tests/requirements.txt b/tests/requirements.txt index 88821dec103..ba8f1cfdd7e 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -26,7 +26,7 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-changelog==0.30.0 # via antsibull-docs -antsibull-core==3.0.2 +antsibull-core==3.1.0 # via antsibull-docs antsibull-docs==2.14.0 # via @@ -36,9 +36,10 @@ antsibull-docs-parser==1.1.0 # via antsibull-docs antsibull-docutils==1.0.0 # via antsibull-changelog -antsibull-fileutils==1.0.0 +antsibull-fileutils==1.0.1 # via # antsibull-changelog + # antsibull-core # antsibull-docs asyncio-pool==0.6.0 # via antsibull-docs @@ -68,7 +69,7 @@ frozenlist==1.4.1 # via # aiohttp # aiosignal -idna==3.8 +idna==3.9 # via # requests # yarl @@ -81,7 +82,7 @@ jinja2==3.1.4 # sphinx markupsafe==2.1.5 # via jinja2 -multidict==6.0.5 +multidict==6.1.0 # via # aiohttp # yarl @@ -109,7 +110,6 @@ pyproject-hooks==1.1.0 pyyaml==6.0.2 # via # -r tests/requirements-relaxed.in - # antsibull-core # antsibull-docs # antsibull-fileutils requests==2.32.3 @@ -179,9 +179,9 @@ typing-extensions==4.12.2 # pydantic # pydantic-core # rstcheck -urllib3==2.2.2 +urllib3==2.2.3 # via requests -yarl==1.11.0 +yarl==1.11.1 # via aiohttp # The following packages are considered to be unsafe in a requirements file: From d97cc2745c442c1104196ab5eca51170bc09a3e8 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Tue, 17 Sep 2024 03:15:08 -0500 Subject: [PATCH 505/536] Add caveat about installing collections from git (#1894) --- .../rst/shared_snippets/installing_collections_git_repo.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt b/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt index 045887389a0..c0f158de519 100644 --- a/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt +++ b/docs/docsite/rst/shared_snippets/installing_collections_git_repo.txt @@ -1,4 +1,4 @@ -You can install a collection from a git repository instead of from Galaxy or Automation Hub. As a developer, installing from a git repository lets you review your collection before you create the tarball and publish the collection. As a user, installing from a git repository lets you use collections or versions that are not in Galaxy or Automation Hub yet. +You can install a collection from a git repository instead of from Galaxy or Automation Hub. As a developer, installing from a git repository lets you review your collection before you create the tarball and publish the collection. As a user, installing from a git repository lets you use collections or versions that are not in Galaxy or Automation Hub yet. This functionality is meant as a minimal shortcut for developers of content as previously described, and git repositories may not support the full set of features from the ``ansible-galaxy`` CLI. In complex cases, a more flexible option may be to ``git clone`` the repository into the correct file structure of the collection installation directory. The repository must contain a ``galaxy.yml`` or ``MANIFEST.json`` file. This file provides metadata such as the version number and namespace of the collection. From 1c004b00bf8deec4db48e044239173d640a2a68d Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 17 Sep 2024 09:24:14 +0100 Subject: [PATCH 506/536] Nightly builds for package docs publishing workflow (#1869) * Nightly builds for package docs publishing workflow (#1663) --- .github/workflows/build-package-docs.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index e3773486a90..93882a5e19b 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -2,6 +2,8 @@ name: Ansible package docs build on: + schedule: + - cron: '17 5 * * *' # Run at 05:17 am workflow_dispatch: inputs: repository-owner: From 7138e42716a7a33fb87d5bf6ce590fa9ec291f68 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 17 Sep 2024 14:07:31 -0500 Subject: [PATCH 507/536] pr_labeler: re-architect triager script (#1882) This commit reorganizes the issue/PR triager script and updates the workflow to run more efficiently. - Make the script a proper Python package instead of an unwieldy single file - Use locked dependencies and UV to decrease workflow runtime to under 10 seconds. --- .github/workflows/labeler.yml | 11 +- hacking/pr_labeler/.gitignore | 1 + hacking/pr_labeler/label.py | 405 ------------------ hacking/pr_labeler/pr_labeler/__init__.py | 0 hacking/pr_labeler/pr_labeler/__main__.py | 13 + hacking/pr_labeler/pr_labeler/actions.py | 138 ++++++ hacking/pr_labeler/pr_labeler/cli.py | 113 +++++ hacking/pr_labeler/pr_labeler/cli_context.py | 99 +++++ hacking/pr_labeler/pr_labeler/constants.py | 22 + .../{ => pr_labeler}/data/docs_team_info.md | 0 .../{ => pr_labeler}/data/no_body_nag.md | 0 .../data/porting_guide_changes.md | 0 hacking/pr_labeler/pr_labeler/github_utils.py | 117 +++++ hacking/pr_labeler/pr_labeler/jinja.py | 26 ++ hacking/pr_labeler/pr_labeler/py.typed | 0 hacking/pr_labeler/pr_labeler/utils.py | 19 + hacking/pr_labeler/pyproject.toml | 27 ++ hacking/pr_labeler/requirements.txt | 2 +- noxfile.py | 2 +- tests/pr_labeler.in | 1 + tests/pr_labeler.txt | 51 +++ tests/typing.txt | 11 +- 22 files changed, 643 insertions(+), 415 deletions(-) create mode 100644 hacking/pr_labeler/.gitignore delete mode 100644 hacking/pr_labeler/label.py create mode 100644 hacking/pr_labeler/pr_labeler/__init__.py create mode 100644 hacking/pr_labeler/pr_labeler/__main__.py create mode 100644 hacking/pr_labeler/pr_labeler/actions.py create mode 100644 hacking/pr_labeler/pr_labeler/cli.py create mode 100644 hacking/pr_labeler/pr_labeler/cli_context.py create mode 100644 hacking/pr_labeler/pr_labeler/constants.py rename hacking/pr_labeler/{ => pr_labeler}/data/docs_team_info.md (100%) rename hacking/pr_labeler/{ => pr_labeler}/data/no_body_nag.md (100%) rename hacking/pr_labeler/{ => pr_labeler}/data/porting_guide_changes.md (100%) create mode 100644 hacking/pr_labeler/pr_labeler/github_utils.py create mode 100644 hacking/pr_labeler/pr_labeler/jinja.py create mode 100644 hacking/pr_labeler/pr_labeler/py.typed create mode 100644 hacking/pr_labeler/pr_labeler/utils.py create mode 100644 hacking/pr_labeler/pyproject.toml create mode 120000 tests/pr_labeler.in create mode 100644 tests/pr_labeler.txt diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml index 7b69e67a9b2..501729b85e4 100644 --- a/.github/workflows/labeler.yml +++ b/.github/workflows/labeler.yml @@ -44,10 +44,13 @@ jobs: uses: actions/setup-python@v5 with: python-version: "3.11" + - name: Set up UV + run: curl -LsSf https://astral.sh/uv/install.sh | sh - name: Setup venv run: | - python -m venv venv - ./venv/bin/pip install -r hacking/pr_labeler/requirements.txt + uv venv venv + uv pip install --python venv \ + -e hacking/pr_labeler -c tests/pr_labeler.txt - name: "Run the issue labeler" if: "github.event.issue || inputs.type == 'issue'" env: @@ -55,7 +58,7 @@ jobs: GITHUB_TOKEN: ${{ steps.create_token.outputs.token }} number: "${{ github.event.issue.number || inputs.number }}" run: | - ./venv/bin/python hacking/pr_labeler/label.py issue "${number}" + ./venv/bin/ad-triage issue "${number}" - name: "Run the PR labeler" if: "github.event.pull_request || inputs.type == 'pr'" env: @@ -63,4 +66,4 @@ jobs: GITHUB_TOKEN: ${{ steps.create_token.outputs.token }} number: "${{ github.event.number || inputs.number }}" run: | - ./venv/bin/python hacking/pr_labeler/label.py pr "${number}" + ./venv/bin/ad-triage pr "${number}" diff --git a/hacking/pr_labeler/.gitignore b/hacking/pr_labeler/.gitignore new file mode 100644 index 00000000000..3feb78adc66 --- /dev/null +++ b/hacking/pr_labeler/.gitignore @@ -0,0 +1 @@ +*.egg-info/ diff --git a/hacking/pr_labeler/label.py b/hacking/pr_labeler/label.py deleted file mode 100644 index 160b20fbd62..00000000000 --- a/hacking/pr_labeler/label.py +++ /dev/null @@ -1,405 +0,0 @@ -# Copyright (C) 2023 Maxwell G -# SPDX-License-Identifier: GPL-3.0-or-later - -from __future__ import annotations - -import dataclasses -import json -import os -import re -from collections.abc import Callable, Collection -from contextlib import suppress -from functools import cached_property -from pathlib import Path -from typing import Any, ClassVar, Union - -import github -import github.Auth -import github.Issue -import github.PullRequest -import github.Repository -import typer -from codeowners import CodeOwners, OwnerTuple -from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoescape - -OWNER = "ansible" -REPO = "ansible-documentation" -LABELS_BY_CODEOWNER: dict[OwnerTuple, list[str]] = { - ("TEAM", "@ansible/steering-committee"): ["sc_approval"], -} -HERE = Path(__file__).resolve().parent -ROOT = HERE.parent.parent -CODEOWNERS = (ROOT / ".github/CODEOWNERS").read_text("utf-8") -JINJA2_ENV = Environment( - loader=FileSystemLoader(HERE / "data"), - autoescape=select_autoescape(), - trim_blocks=True, - undefined=StrictUndefined, -) -NEW_CONTRIBUTOR_LABEL = "new_contributor" - -IssueOrPrCtx = Union["IssueLabelerCtx", "PRLabelerCtx"] -IssueOrPr = Union["github.Issue.Issue", "github.PullRequest.PullRequest"] - - -# TODO: If we end up needing to log more things with more granularity, -# switch to something like `logging` -def log(ctx: IssueOrPrCtx, *args: object) -> None: - print(f"{ctx.member.number}:", *args) - - -def get_repo( - args: GlobalArgs, authed: bool = True -) -> tuple[github.Github, github.Repository.Repository]: - gclient = github.Github( - auth=github.Auth.Token(os.environ["GITHUB_TOKEN"]) if authed else None, - ) - repo_obj = gclient.get_repo(args.full_repo) - return gclient, repo_obj - - -def get_event_info() -> dict[str, Any]: - event_json = os.environ.get("event_json") - if not event_json: - return {} - with suppress(json.JSONDecodeError): - return json.loads(event_json) - return {} - - -@dataclasses.dataclass() -class GlobalArgs: - owner: str - repo: str - use_author_association: bool - - @property - def full_repo(self) -> str: - return f"{self.owner}/{self.repo}" - - -@dataclasses.dataclass() -class LabelerCtx: - client: github.Github - repo: github.Repository.Repository - dry_run: bool - event_info: dict[str, Any] - issue: github.Issue.Issue - global_args: GlobalArgs - - TYPE: ClassVar[str] - - @property - def member(self) -> IssueOrPr: - raise NotImplementedError - - @property - def event_member(self) -> dict[str, Any]: - raise NotImplementedError - - @cached_property - def previously_labeled(self) -> frozenset[str]: - labels: set[str] = set() - events = ( - self.member.get_events() - if isinstance(self.member, github.Issue.Issue) - else self.member.get_issue_events() - ) - for event in events: - if event.event in ("labeled", "unlabeled"): - assert event.label - labels.add(event.label.name) - return frozenset(labels) - - -@dataclasses.dataclass() -class IssueLabelerCtx(LabelerCtx): - issue: github.Issue.Issue - - TYPE = "issue" - - @property - def member(self) -> IssueOrPr: - return self.issue - - @property - def event_member(self) -> dict[str, Any]: - return self.event_info.get("issue", {}) - - -@dataclasses.dataclass() -class PRLabelerCtx(LabelerCtx): - pr: github.PullRequest.PullRequest - - TYPE = "pull request" - - @property - def member(self) -> IssueOrPr: - return self.pr - - @property - def event_member(self) -> dict[str, Any]: - return self.event_info.get("pull_request", {}) - - -def create_comment(ctx: IssueOrPrCtx, body: str) -> None: - if ctx.dry_run: - return - if isinstance(ctx, IssueLabelerCtx): - ctx.issue.create_comment(body) - else: - ctx.pr.create_issue_comment(body) - - -def get_data_file(name: str, **kwargs: Any) -> str: - """ - Template a data file - """ - return JINJA2_ENV.get_template(name).render(**kwargs).rstrip("\n") - - -def create_boilerplate_comment(ctx: IssueOrPrCtx, name: str, **kwargs) -> None: - """ - Add a boilerplate comment if it hasn't already been added - """ - tmpl = get_data_file(name, ctx=ctx, **kwargs) - tmpl_lines = tmpl.splitlines() - last = tmpl_lines[-1] - if not (last.startswith("")): - raise ValueError( - "Last line must of the template" - " must have an identifying boilerplate comment" - ) - for comment in ctx.issue.get_comments(): - if comment.body.splitlines()[-1] == last: - log(ctx, name, "boilerplate was already commented") - return - msg = f"Templating {name} boilerplate" - if kwargs: - msg += f" with {kwargs}" - log(ctx, msg) - create_comment(ctx, tmpl) - - -def get_team_members(ctx: IssueOrPrCtx, team: str) -> list[str]: - """ - Get the members of a Github team - """ - return [ - user.login - for user in ctx.client.get_organization(ctx.repo.organization.login) - .get_team_by_slug(team) - .get_members() - ] - - -def handle_codeowner_labels(ctx: PRLabelerCtx) -> None: - labels = LABELS_BY_CODEOWNER.copy() - owners = CodeOwners(CODEOWNERS) - files = ctx.pr.get_files() - for file in files: - for owner in owners.of(file.filename): - if labels_to_add := labels.pop(owner, None): - add_label_if_new(ctx, labels_to_add) - if not labels: - return - - -def add_label_if_new(ctx: IssueOrPrCtx, labels: Collection[str] | str) -> None: - """ - Add a label to a PR if it wasn't added in the past - """ - labels = {labels} if isinstance(labels, str) else labels - labels = set(labels) - ctx.previously_labeled - if not labels: - return - log(ctx, "Adding labels", *map(repr, labels)) - if not ctx.dry_run: - ctx.member.add_to_labels(*labels) - - -def is_new_contributor_assoc(ctx: IssueOrPrCtx) -> bool: - """ - Determine whether a user has previously contributed. - Requires authentication as a regular user and does not work with an app - token. - """ - author_association = ctx.event_member.get( - "author_association", ctx.member.raw_data["author_association"] - ) - log(ctx, "author_association is", author_association) - return author_association in {"FIRST_TIMER", "FIRST_TIME_CONTRIBUTOR"} - - -def is_new_contributor_manual(ctx: IssueOrPrCtx) -> bool: - """ - Determine whether a user has previously opened an issue or PR in this repo - without needing special API access. - """ - query_data = { - "repo": "ansible/ansible-documentation", - "author": ctx.issue.user.login, - # Avoid potential race condition where a new contributor opens multiple - # PRs or issues at once. - # Better to welcome twice than not at all. - "is": "closed", - } - issues = ctx.client.search_issues("", **query_data) - for issue in issues: - if issue.number != ctx.issue.number: - return False - return True - - -def new_contributor_welcome(ctx: IssueOrPrCtx) -> None: - """ - Welcome a new contributor to the repo with a message and a label - """ - is_new_contributor: Callable[[IssueOrPrCtx], bool] = ( - is_new_contributor_assoc - if ctx.global_args.use_author_association - else is_new_contributor_manual - ) - if ( - # Contributor has already been welcomed - NEW_CONTRIBUTOR_LABEL in ctx.previously_labeled - # - or not is_new_contributor(ctx) - ): - return - log(ctx, "Welcoming new contributor") - add_label_if_new(ctx, NEW_CONTRIBUTOR_LABEL) - create_comment(ctx, get_data_file("docs_team_info.md")) - - -def no_body_nag(ctx: IssueOrPrCtx) -> None: - """ - Complain if a non-bot user creates a PR or issue without body text - """ - if ctx.member.user.login.endswith("[bot]") or (ctx.member.body or "").strip(): - return - create_boilerplate_comment(ctx, "no_body_nag.md") - - -def warn_porting_guide_change(ctx: PRLabelerCtx) -> None: - """ - Complain if a non-bot user outside of the Release Management WG changes - porting_guide - """ - user = ctx.pr.user.login - if user.endswith("[bot]"): - return - - # If the API token does not have permisisons to view teams in the ansible - # org, fall back to an empty list. - members = [] - try: - members = get_team_members(ctx, "release-management-wg") - except github.UnknownObjectException: - log(ctx, "Failed to get members of @ansible/release-management-wg") - if user in members: - return - - matches: list[str] = [] - for file in ctx.pr.get_files(): - if re.fullmatch( - # Match community porting guides but not core porting guides - r"docs/docsite/rst/porting_guides/porting_guide_\d.*.rst", - file.filename, - ): - matches.append(file.filename) - if not matches: - return - create_boilerplate_comment(ctx, "porting_guide_changes.md", changed_files=matches) - - -APP = typer.Typer() - - -@APP.callback() -def cb( - *, - click_ctx: typer.Context, - owner: str = OWNER, - repo: str = REPO, - use_author_association: bool = False, -): - """ - Basic triager for ansible/ansible-documentation - """ - click_ctx.obj = GlobalArgs(owner, repo, use_author_association) - - -@APP.command(name="pr") -def process_pr( - *, - click_ctx: typer.Context, - pr_number: int, - dry_run: bool = False, - authed_dry_run: bool = False, - force_process_closed: bool = False, -) -> None: - global_args = click_ctx.ensure_object(GlobalArgs) - - authed = not dry_run - if authed_dry_run: - dry_run = True - authed = True - - gclient, repo = get_repo(global_args, authed) - pr = repo.get_pull(pr_number) - ctx = PRLabelerCtx( - client=gclient, - repo=repo, - pr=pr, - dry_run=dry_run, - event_info=get_event_info(), - issue=pr.as_issue(), - global_args=global_args, - ) - if not force_process_closed and pr.state != "open": - log(ctx, "Refusing to process closed ticket") - return - - handle_codeowner_labels(ctx) - new_contributor_welcome(ctx) - no_body_nag(ctx) - warn_porting_guide_change(ctx) - - -@APP.command(name="issue") -def process_issue( - *, - click_ctx: typer.Context, - issue_number: int, - dry_run: bool = False, - authed_dry_run: bool = False, - force_process_closed: bool = False, -) -> None: - global_args = click_ctx.ensure_object(GlobalArgs) - - authed = not dry_run - if authed_dry_run: - dry_run = True - authed = True - gclient, repo = get_repo(global_args, authed) - issue = repo.get_issue(issue_number) - ctx = IssueLabelerCtx( - client=gclient, - repo=repo, - issue=issue, - dry_run=dry_run, - event_info=get_event_info(), - global_args=global_args, - ) - if not force_process_closed and issue.state != "open": - log(ctx, "Refusing to process closed ticket") - return - - add_label_if_new(ctx, "needs_triage") - new_contributor_welcome(ctx) - no_body_nag(ctx) - - -if __name__ == "__main__": - APP() diff --git a/hacking/pr_labeler/pr_labeler/__init__.py b/hacking/pr_labeler/pr_labeler/__init__.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/hacking/pr_labeler/pr_labeler/__main__.py b/hacking/pr_labeler/pr_labeler/__main__.py new file mode 100644 index 00000000000..a873c924ea0 --- /dev/null +++ b/hacking/pr_labeler/pr_labeler/__main__.py @@ -0,0 +1,13 @@ +# Copyright (C) 2023 Maxwell G +# SPDX-License-Identifier: GPL-3.0-or-later + +""" +Module entrypoint +""" + +from __future__ import annotations + +from .cli import APP + +if __name__ == "__main__": + APP() diff --git a/hacking/pr_labeler/pr_labeler/actions.py b/hacking/pr_labeler/pr_labeler/actions.py new file mode 100644 index 00000000000..018deff1f80 --- /dev/null +++ b/hacking/pr_labeler/pr_labeler/actions.py @@ -0,0 +1,138 @@ +# Copyright (C) 2023 Maxwell G +# SPDX-License-Identifier: GPL-3.0-or-later + +""" +Triager action functions +""" + +from __future__ import annotations + +import re +from collections.abc import Callable, Collection +from typing import TYPE_CHECKING + +import github +from codeowners import CodeOwners + +from .constants import CODEOWNERS, LABELS_BY_CODEOWNER, NEW_CONTRIBUTOR_LABEL +from .github_utils import ( + create_comment, + get_team_members, + is_new_contributor_assoc, + is_new_contributor_manual, +) +from .jinja import get_data_file +from .utils import log + +if TYPE_CHECKING: + from .cli_context import IssueOrPrCtx, PRLabelerCtx + + +def create_boilerplate_comment(ctx: IssueOrPrCtx, name: str, **kwargs) -> None: + """ + Add a boilerplate comment if it hasn't already been added + """ + tmpl = get_data_file(name, ctx=ctx, **kwargs) + tmpl_lines = tmpl.splitlines() + last = tmpl_lines[-1] + if not (last.startswith("")): + raise ValueError( + "Last line must of the template" + " must have an identifying boilerplate comment" + ) + for comment in ctx.issue.get_comments(): + if comment.body.splitlines()[-1] == last: + log(ctx, name, "boilerplate was already commented") + return + msg = f"Templating {name} boilerplate" + if kwargs: + msg += f" with {kwargs}" + log(ctx, msg) + create_comment(ctx, tmpl) + + +def add_label_if_new(ctx: IssueOrPrCtx, labels: Collection[str] | str) -> None: + """ + Add a label to a PR if it wasn't added in the past + """ + labels = {labels} if isinstance(labels, str) else labels + labels = set(labels) - ctx.previously_labeled + if not labels: + return + log(ctx, "Adding labels", *map(repr, labels)) + if not ctx.dry_run: + ctx.member.add_to_labels(*labels) + + +def handle_codeowner_labels(ctx: PRLabelerCtx) -> None: + labels = LABELS_BY_CODEOWNER.copy() + owners = CodeOwners(CODEOWNERS) + files = ctx.pr.get_files() + for file in files: + for owner in owners.of(file.filename): + if labels_to_add := labels.pop(owner, None): + add_label_if_new(ctx, labels_to_add) + if not labels: + return + + +def new_contributor_welcome(ctx: IssueOrPrCtx) -> None: + """ + Welcome a new contributor to the repo with a message and a label + """ + is_new_contributor: Callable[[IssueOrPrCtx], bool] = ( + is_new_contributor_assoc + if ctx.global_args.use_author_association + else is_new_contributor_manual + ) + if ( + # Contributor has already been welcomed + NEW_CONTRIBUTOR_LABEL in ctx.previously_labeled + # + or not is_new_contributor(ctx) + ): + return + log(ctx, "Welcoming new contributor") + add_label_if_new(ctx, NEW_CONTRIBUTOR_LABEL) + create_comment(ctx, get_data_file("docs_team_info.md")) + + +def warn_porting_guide_change(ctx: PRLabelerCtx) -> None: + """ + Complain if a non-bot user outside of the Release Management WG changes + porting_guide + """ + user = ctx.pr.user.login + if user.endswith("[bot]"): + return + + # If the API token does not have permisisons to view teams in the ansible + # org, fall back to an empty list. + members = [] + try: + members = get_team_members(ctx, "release-management-wg") + except github.UnknownObjectException: + log(ctx, "Failed to get members of @ansible/release-management-wg") + if user in members: + return + + matches: list[str] = [] + for file in ctx.pr.get_files(): + if re.fullmatch( + # Match community porting guides but not core porting guides + r"docs/docsite/rst/porting_guides/porting_guide_\d.*.rst", + file.filename, + ): + matches.append(file.filename) + if not matches: + return + create_boilerplate_comment(ctx, "porting_guide_changes.md", changed_files=matches) + + +def no_body_nag(ctx: IssueOrPrCtx) -> None: + """ + Complain if a non-bot user creates a PR or issue without body text + """ + if ctx.member.user.login.endswith("[bot]") or (ctx.member.body or "").strip(): + return + create_boilerplate_comment(ctx, "no_body_nag.md") diff --git a/hacking/pr_labeler/pr_labeler/cli.py b/hacking/pr_labeler/pr_labeler/cli.py new file mode 100644 index 00000000000..8e7b15e9529 --- /dev/null +++ b/hacking/pr_labeler/pr_labeler/cli.py @@ -0,0 +1,113 @@ +# Copyright (C) 2023 Maxwell G +# SPDX-License-Identifier: GPL-3.0-or-later + +""" +CLI entrypoints +""" + +from __future__ import annotations + +import typer + +from .actions import ( + add_label_if_new, + handle_codeowner_labels, + new_contributor_welcome, + no_body_nag, + warn_porting_guide_change, +) +from .cli_context import GlobalArgs, IssueLabelerCtx, PRLabelerCtx +from .constants import OWNER, REPO +from .github_utils import get_event_info, get_repo +from .utils import log + +APP = typer.Typer() + + +@APP.callback() +def cb( + *, + click_ctx: typer.Context, + owner: str = OWNER, + repo: str = REPO, + use_author_association: bool = False, +): + """ + Basic triager for ansible/ansible-documentation + """ + click_ctx.obj = GlobalArgs(owner, repo, use_author_association) + + +@APP.command(name="pr") +def process_pr( + *, + click_ctx: typer.Context, + pr_number: int, + dry_run: bool = False, + authed_dry_run: bool = False, + force_process_closed: bool = False, +) -> None: + global_args = click_ctx.ensure_object(GlobalArgs) + + authed = not dry_run + if authed_dry_run: + dry_run = True + authed = True + + gclient, repo = get_repo(global_args.full_repo, authed) + pr = repo.get_pull(pr_number) + ctx = PRLabelerCtx( + client=gclient, + repo=repo, + pr=pr, + dry_run=dry_run, + event_info=get_event_info(), + issue=pr.as_issue(), + global_args=global_args, + ) + if not force_process_closed and pr.state != "open": + log(ctx, "Refusing to process closed ticket") + return + + handle_codeowner_labels(ctx) + new_contributor_welcome(ctx) + no_body_nag(ctx) + warn_porting_guide_change(ctx) + + +@APP.command(name="issue") +def process_issue( + *, + click_ctx: typer.Context, + issue_number: int, + dry_run: bool = False, + authed_dry_run: bool = False, + force_process_closed: bool = False, +) -> None: + global_args = click_ctx.ensure_object(GlobalArgs) + + authed = not dry_run + if authed_dry_run: + dry_run = True + authed = True + gclient, repo = get_repo(global_args.full_repo, authed) + issue = repo.get_issue(issue_number) + ctx = IssueLabelerCtx( + client=gclient, + repo=repo, + issue=issue, + dry_run=dry_run, + event_info=get_event_info(), + global_args=global_args, + ) + if not force_process_closed and issue.state != "open": + log(ctx, "Refusing to process closed ticket") + return + + add_label_if_new(ctx, "needs_triage") + new_contributor_welcome(ctx) + no_body_nag(ctx) + + +if __name__ == "__main__": + APP() diff --git a/hacking/pr_labeler/pr_labeler/cli_context.py b/hacking/pr_labeler/pr_labeler/cli_context.py new file mode 100644 index 00000000000..484a2a9f00b --- /dev/null +++ b/hacking/pr_labeler/pr_labeler/cli_context.py @@ -0,0 +1,99 @@ +# Copyright (C) 2023 Maxwell G +# SPDX-License-Identifier: GPL-3.0-or-later + +""" +CLI context objects +""" + +from __future__ import annotations + +import dataclasses +from functools import cached_property +from typing import TYPE_CHECKING, Any, ClassVar + +import github +import github.Issue +import github.PullRequest +import github.Repository + +if TYPE_CHECKING: + from typing_extensions import TypeAlias + + from .github_utils import IssueOrPr + +IssueOrPrCtx: TypeAlias = "IssueLabelerCtx | PRLabelerCtx" + + +@dataclasses.dataclass() +class GlobalArgs: + owner: str + repo: str + use_author_association: bool + + @property + def full_repo(self) -> str: + return f"{self.owner}/{self.repo}" + + +@dataclasses.dataclass() +class LabelerCtx: + client: github.Github + repo: github.Repository.Repository + dry_run: bool + event_info: dict[str, Any] + issue: github.Issue.Issue + global_args: GlobalArgs + + TYPE: ClassVar[str] + + @property + def member(self) -> IssueOrPr: + raise NotImplementedError + + @property + def event_member(self) -> dict[str, Any]: + raise NotImplementedError + + @cached_property + def previously_labeled(self) -> frozenset[str]: + labels: set[str] = set() + events = ( + self.member.get_events() + if isinstance(self.member, github.Issue.Issue) + else self.member.get_issue_events() + ) + for event in events: + if event.event in ("labeled", "unlabeled"): + assert event.label + labels.add(event.label.name) + return frozenset(labels) + + +@dataclasses.dataclass() +class IssueLabelerCtx(LabelerCtx): + issue: github.Issue.Issue + + TYPE = "issue" + + @property + def member(self) -> IssueOrPr: + return self.issue + + @property + def event_member(self) -> dict[str, Any]: + return self.event_info.get("issue", {}) + + +@dataclasses.dataclass() +class PRLabelerCtx(LabelerCtx): + pr: github.PullRequest.PullRequest + + TYPE = "pull request" + + @property + def member(self) -> IssueOrPr: + return self.pr + + @property + def event_member(self) -> dict[str, Any]: + return self.event_info.get("pull_request", {}) diff --git a/hacking/pr_labeler/pr_labeler/constants.py b/hacking/pr_labeler/pr_labeler/constants.py new file mode 100644 index 00000000000..949de61370f --- /dev/null +++ b/hacking/pr_labeler/pr_labeler/constants.py @@ -0,0 +1,22 @@ +# Copyright (C) 2023 Maxwell G +# SPDX-License-Identifier: GPL-3.0-or-later + +""" +Constants for the tagging script +""" + +from __future__ import annotations + +from pathlib import Path + +from codeowners import OwnerTuple + +OWNER = "ansible" +REPO = "ansible-documentation" +LABELS_BY_CODEOWNER: dict[OwnerTuple, list[str]] = { + ("TEAM", "@ansible/steering-committee"): ["sc_approval"], +} +HERE = Path(__file__).resolve().parent +ROOT = HERE.parent.parent.parent +CODEOWNERS = (ROOT / ".github/CODEOWNERS").read_text("utf-8") +NEW_CONTRIBUTOR_LABEL = "new_contributor" diff --git a/hacking/pr_labeler/data/docs_team_info.md b/hacking/pr_labeler/pr_labeler/data/docs_team_info.md similarity index 100% rename from hacking/pr_labeler/data/docs_team_info.md rename to hacking/pr_labeler/pr_labeler/data/docs_team_info.md diff --git a/hacking/pr_labeler/data/no_body_nag.md b/hacking/pr_labeler/pr_labeler/data/no_body_nag.md similarity index 100% rename from hacking/pr_labeler/data/no_body_nag.md rename to hacking/pr_labeler/pr_labeler/data/no_body_nag.md diff --git a/hacking/pr_labeler/data/porting_guide_changes.md b/hacking/pr_labeler/pr_labeler/data/porting_guide_changes.md similarity index 100% rename from hacking/pr_labeler/data/porting_guide_changes.md rename to hacking/pr_labeler/pr_labeler/data/porting_guide_changes.md diff --git a/hacking/pr_labeler/pr_labeler/github_utils.py b/hacking/pr_labeler/pr_labeler/github_utils.py new file mode 100644 index 00000000000..dd1243da6c2 --- /dev/null +++ b/hacking/pr_labeler/pr_labeler/github_utils.py @@ -0,0 +1,117 @@ +# Copyright (C) 2023 Maxwell G +# SPDX-License-Identifier: GPL-3.0-or-later + +""" +Utilities for working with the Github API +""" + +from __future__ import annotations + +import json +import os +from contextlib import suppress +from typing import TYPE_CHECKING, Any + +import github +import github.Auth +import github.Issue +import github.PullRequest +import github.Repository + +from .cli_context import IssueLabelerCtx, IssueOrPrCtx +from .utils import log + +if TYPE_CHECKING: + from typing_extensions import TypeAlias + + +IssueOrPr: TypeAlias = "github.Issue.Issue | github.PullRequest.PullRequest" + + +def get_repo( + full_repo: str, + authed: bool = True, +) -> tuple[github.Github, github.Repository.Repository]: + """ + Create a Github client and return a `github.Repository.Repository` object + + Args: + full_repo: OWNER/NAME of the repository + authed: + Whether to create an authenticated Github client with the + `$GITHUB_TOKEN` environment variable as the key + """ + gclient = github.Github( + auth=github.Auth.Token(os.environ["GITHUB_TOKEN"]) if authed else None, + ) + repo_obj = gclient.get_repo(full_repo) + return gclient, repo_obj + + +def get_event_info() -> dict[str, Any]: + """ + Load Github event JSON data from `$event_data` + """ + event_json = os.environ.get("event_json") + if not event_json: + return {} + with suppress(json.JSONDecodeError): + return json.loads(event_json) + return {} + + +# Operations + + +def get_team_members(ctx: IssueOrPrCtx, team: str) -> list[str]: + """ + Get the members of a Github team + """ + return [ + user.login + for user in ctx.client.get_organization(ctx.repo.organization.login) + .get_team_by_slug(team) + .get_members() + ] + + +def create_comment(ctx: IssueOrPrCtx, body: str) -> None: + if ctx.dry_run: + return + if isinstance(ctx, IssueLabelerCtx): + ctx.issue.create_comment(body) + else: + ctx.pr.create_issue_comment(body) + + +def is_new_contributor_assoc(ctx: IssueOrPrCtx) -> bool: + """ + Determine whether a user has previously contributed. + Requires authentication as a regular user and does not work with an app + token. + """ + author_association = ctx.event_member.get( + "author_association", ctx.member.raw_data["author_association"] + ) + log(ctx, "author_association is", author_association) + return author_association in {"FIRST_TIMER", "FIRST_TIME_CONTRIBUTOR"} + + +def is_new_contributor_manual(ctx: IssueOrPrCtx) -> bool: + """ + Determine whether a user has previously opened an issue or PR in this repo + without needing special API access. + """ + query_data = { + "repo": "ansible/ansible-documentation", + "author": ctx.issue.user.login, + # Avoid potential race condition where a new contributor opens multiple + # PRs or issues at once. + # Better to welcome twice than not at all. + "is": "closed", + } + issues = ctx.client.search_issues("", **query_data) + for issue in issues: + if issue.number != ctx.issue.number: + return False + return True diff --git a/hacking/pr_labeler/pr_labeler/jinja.py b/hacking/pr_labeler/pr_labeler/jinja.py new file mode 100644 index 00000000000..8d6ce1878e7 --- /dev/null +++ b/hacking/pr_labeler/pr_labeler/jinja.py @@ -0,0 +1,26 @@ +# Copyright (C) 2023 Maxwell G +# SPDX-License-Identifier: GPL-3.0-or-later + +""" +Utilities for Jinja2 templating +""" + +from __future__ import annotations + +from typing import Any, cast + +from jinja2 import Environment, PackageLoader, StrictUndefined, select_autoescape + +JINJA2_ENV = Environment( + loader=PackageLoader(cast(str, __package__), "data"), + autoescape=select_autoescape(), + trim_blocks=True, + undefined=StrictUndefined, +) + + +def get_data_file(name: str, **kwargs: Any) -> str: + """ + Template a data file + """ + return JINJA2_ENV.get_template(name).render(**kwargs).rstrip("\n") diff --git a/hacking/pr_labeler/pr_labeler/py.typed b/hacking/pr_labeler/pr_labeler/py.typed new file mode 100644 index 00000000000..e69de29bb2d diff --git a/hacking/pr_labeler/pr_labeler/utils.py b/hacking/pr_labeler/pr_labeler/utils.py new file mode 100644 index 00000000000..62020e8509e --- /dev/null +++ b/hacking/pr_labeler/pr_labeler/utils.py @@ -0,0 +1,19 @@ +# Copyright (C) 2023 Maxwell G +# SPDX-License-Identifier: GPL-3.0-or-later + +""" +Generic utilities +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from .cli_context import IssueOrPrCtx + + +# TODO: If we end up needing to log more things with more granularity, +# switch to something like `logging` +def log(ctx: IssueOrPrCtx, *args: object) -> None: + print(f"{ctx.member.number}:", *args) diff --git a/hacking/pr_labeler/pyproject.toml b/hacking/pr_labeler/pyproject.toml new file mode 100644 index 00000000000..54e960789e2 --- /dev/null +++ b/hacking/pr_labeler/pyproject.toml @@ -0,0 +1,27 @@ +[build-system] +requires = ["setuptools"] +backend = "setuptools.build_meta" + +[project] +name = "ad-internal-pr-labeler" +description = "Internal package to triage ansible-documentation issues and PRs" +classifiers = [ + # Internal package + "Private :: Do Not Upload", +] +version = "0" +requires-python = ">=3.9" +dynamic = ["dependencies"] + +[project.scripts] +ad-triage = "pr_labeler.cli:APP" + +[tool.setuptools.dynamic] +dependencies = {file = "requirements.txt"} + +[tool.setuptools.packages.find] +where = ["."] +include = ["pr_labeler*"] + +[tool.uv] +cache-keys = [{ file = "requirements.txt" }] diff --git a/hacking/pr_labeler/requirements.txt b/hacking/pr_labeler/requirements.txt index b9cdb4ce636..7b037bcf275 100644 --- a/hacking/pr_labeler/requirements.txt +++ b/hacking/pr_labeler/requirements.txt @@ -1,4 +1,4 @@ codeowners jinja2 pygithub -typer +typer-slim diff --git a/noxfile.py b/noxfile.py index 66f328eb954..491c700d638 100644 --- a/noxfile.py +++ b/noxfile.py @@ -10,7 +10,7 @@ import nox LINT_FILES: tuple[str, ...] = ( - "hacking/pr_labeler/label.py", + "hacking/pr_labeler/pr_labeler", "hacking/tagger/tag.py", "noxfile.py", *iglob("docs/bin/*.py"), diff --git a/tests/pr_labeler.in b/tests/pr_labeler.in new file mode 120000 index 00000000000..8ccfcc790b9 --- /dev/null +++ b/tests/pr_labeler.in @@ -0,0 +1 @@ +../hacking/pr_labeler/requirements.txt \ No newline at end of file diff --git a/tests/pr_labeler.txt b/tests/pr_labeler.txt new file mode 100644 index 00000000000..c98afc07fde --- /dev/null +++ b/tests/pr_labeler.txt @@ -0,0 +1,51 @@ +# +# This file is autogenerated by pip-compile with Python 3.11 +# by the following command: +# +# pip-compile --allow-unsafe --output-file=tests/pr_labeler.txt --strip-extras tests/pr_labeler.in +# +certifi==2024.8.30 + # via requests +cffi==1.17.1 + # via + # cryptography + # pynacl +charset-normalizer==3.3.2 + # via requests +click==8.1.7 + # via typer-slim +codeowners==0.7.0 + # via -r tests/pr_labeler.in +cryptography==43.0.1 + # via pyjwt +deprecated==1.2.14 + # via pygithub +idna==3.8 + # via requests +jinja2==3.1.4 + # via -r tests/pr_labeler.in +markupsafe==2.1.5 + # via jinja2 +pycparser==2.22 + # via cffi +pygithub==2.4.0 + # via -r tests/pr_labeler.in +pyjwt==2.9.0 + # via pygithub +pynacl==1.5.0 + # via pygithub +requests==2.32.3 + # via pygithub +typer-slim==0.12.5 + # via -r tests/pr_labeler.in +typing-extensions==4.12.2 + # via + # codeowners + # pygithub + # typer-slim +urllib3==2.2.3 + # via + # pygithub + # requests +wrapt==1.16.0 + # via deprecated diff --git a/tests/typing.txt b/tests/typing.txt index 5573e9252f5..421cca04549 100644 --- a/tests/typing.txt +++ b/tests/typing.txt @@ -15,7 +15,9 @@ cffi==1.17.1 charset-normalizer==3.3.2 # via requests click==8.1.7 - # via typer + # via + # typer + # typer-slim codeowners==0.7.0 # via -r tests/../hacking/pr_labeler/requirements.txt colorlog==6.8.2 @@ -73,15 +75,16 @@ shellingham==1.5.4 smmap==5.0.1 # via gitdb typer==0.12.5 - # via - # -r tests/../hacking/pr_labeler/requirements.txt - # -r tests/tag.in + # via -r tests/tag.in +typer-slim==0.12.5 + # via -r tests/../hacking/pr_labeler/requirements.txt typing-extensions==4.12.2 # via # codeowners # mypy # pygithub # typer + # typer-slim urllib3==2.2.3 # via # pygithub From 107a3c4383704ee7763ff75f4a8dd0e814671bdf Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Mon, 9 Sep 2024 16:42:58 -0500 Subject: [PATCH 508/536] nox: add actionlint to lint Github Actions workflows This PR integrates [actionlint](https://github.com/rhysd/actionlint) into our CI pipeline to check our Github Actions for best practices and common errors. --- .github/workflows/reusable-nox.yml | 2 ++ README.md | 5 +++ noxfile.py | 49 ++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+) diff --git a/.github/workflows/reusable-nox.yml b/.github/workflows/reusable-nox.yml index bf8ac66ab75..2f8b8a92900 100644 --- a/.github/workflows/reusable-nox.yml +++ b/.github/workflows/reusable-nox.yml @@ -23,6 +23,8 @@ jobs: python-versions: "3.11" - session: "checkers(docs-build)" python-versions: "3.11" + - session: "actionlint" + python-versions: "3.11" name: "Run nox ${{ matrix.session }} session" steps: - name: Check out repo diff --git a/README.md b/README.md index 9ec6cd5a5be..2712aabf09d 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,11 @@ The `nox` configuration also contains session to run automated docs checkers. nox -s lint ``` + The `actionlint` linter that is run as part of the `lint` session requires + `podman` or `docker` to be installed. + If both container engines are installed, `podman` is preferred. + Set `CONTAINER_ENGINE=docker` to change this behavior. + ### Checking spelling Use [`codespell`](https://github.com/codespell-project/codespell) to check for common spelling mistakes in the documentation source. diff --git a/noxfile.py b/noxfile.py index 491c700d638..5961a5b132a 100644 --- a/noxfile.py +++ b/noxfile.py @@ -2,6 +2,7 @@ import os import shlex +import shutil from argparse import ArgumentParser, BooleanOptionalAction from glob import iglob from pathlib import Path @@ -45,6 +46,29 @@ def install(session: nox.Session, *args, req: str, **kwargs): session.install("-r", f"tests/{req}.in", *args, **kwargs) +CONTAINER_ENGINES = ("podman", "docker") +CHOSEN_CONTAINER_ENGINE = os.environ.get("CONTAINER_ENGINE") +ACTIONLINT_IMAGE = "docker.io/rhysd/actionlint" + + +def _get_container_engine(session: nox.Session) -> str: + path: str | None = None + if CHOSEN_CONTAINER_ENGINE: + path = shutil.which(CHOSEN_CONTAINER_ENGINE) + if not path: + session.error( + f"CONTAINER_ENGINE {CHOSEN_CONTAINER_ENGINE!r} does not exist!" + ) + return path + for engine in CONTAINER_ENGINES: + if path := shutil.which(engine): + return path + session.error( + f"None of the following container engines were found: {CONTAINER_ENGINES}." + f" {session.name} requires a container engine installed." + ) + + @nox.session def static(session: nox.Session): """ @@ -93,12 +117,37 @@ def spelling(session: nox.Session): ) +@nox.session +def actionlint(session: nox.Session) -> None: + """ + Run actionlint to lint Github Actions workflows. + The actionlint tool is run in a Podman/Docker container. + """ + engine = _get_container_engine(session) + session.run_always(engine, "pull", ACTIONLINT_IMAGE, external=True) + session.run( + engine, + "run", + "--rm", + # fmt: off + "--volume", f"{Path.cwd()}:/pwd:z", + "--workdir", "/pwd", + # fmt: on + ACTIONLINT_IMAGE, + # Disable shellcheck for now + "-shellcheck=", + *session.posargs, + external=True, + ) + + @nox.session def lint(session: nox.Session): session.notify("typing") session.notify("static") session.notify("formatters") session.notify("spelling") + session.notify("actionlint") requirements_files = list( From b5e957a567c5a9a84920be3cdba3fe86cbaf5198 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Sat, 14 Sep 2024 15:12:16 -0500 Subject: [PATCH 509/536] lint actionlint: enable shellcheck integration --- .github/workflows/build-package-docs.yaml | 16 +++++++++------- .github/workflows/reusable-pip-compile.yml | 2 ++ noxfile.py | 2 -- 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/.github/workflows/build-package-docs.yaml b/.github/workflows/build-package-docs.yaml index 93882a5e19b..5d95397fe78 100644 --- a/.github/workflows/build-package-docs.yaml +++ b/.github/workflows/build-package-docs.yaml @@ -80,7 +80,7 @@ jobs: - name: Set the COLLECTION_LIST variable if: env.PACKAGE_VERSION != 'devel' run: >- - echo COLLECTION_LIST='"${PACKAGE_VERSION}"' + echo COLLECTION_LIST="${PACKAGE_VERSION}" >> "${GITHUB_ENV}" - name: Set the VERSION variable @@ -93,7 +93,7 @@ jobs: - name: Create a tarball with the build contents run: >- tar -czvf - ansible-package-docs-html-"${PACKAGE_VERSION}"-$(date '+%Y-%m-%d')-${{ + ansible-package-docs-html-"${PACKAGE_VERSION}"-"$(date '+%Y-%m-%d')"-${{ github.run_id }}-${{ github.run_number @@ -117,11 +117,13 @@ jobs: steps: - name: Log the workflow inputs if deployed run: | - echo "## Deployment details :shipit:" >> "${GITHUB_STEP_SUMMARY}" - echo "Publish to: ${{ github.event.inputs.deployment-environment }}" >> "${GITHUB_STEP_SUMMARY}" - echo "Package version: ${{ github.event.inputs.ansible-package-version }}" >> "${GITHUB_STEP_SUMMARY}" - echo "Owner: ${{ github.event.inputs.repository-owner }}" >> "${GITHUB_STEP_SUMMARY}" - echo "Branch: ${{ github.event.inputs.repository-branch }}" >> "${GITHUB_STEP_SUMMARY}" + { + echo "## Deployment details :shipit:"; + echo "Publish to: ${{ github.event.inputs.deployment-environment }}"; + echo "Package version: ${{ github.event.inputs.ansible-package-version }}"; + echo "Owner: ${{ github.event.inputs.repository-owner }}"; + echo "Branch: ${{ github.event.inputs.repository-branch }}"; + } >> "${GITHUB_STEP_SUMMARY}" notify-build-failures: if: failure() diff --git a/.github/workflows/reusable-pip-compile.yml b/.github/workflows/reusable-pip-compile.yml index b96bd0353a0..5fcb9db3915 100644 --- a/.github/workflows/reusable-pip-compile.yml +++ b/.github/workflows/reusable-pip-compile.yml @@ -94,7 +94,9 @@ jobs: run: | set -x git diff || : + # shellcheck disable=SC2086 git add ${changed_files} + # shellcheck disable=SC2086 if git diff-index --quiet HEAD ${changed_files}; then echo "Nothing to do!" exit diff --git a/noxfile.py b/noxfile.py index 5961a5b132a..395d3aaf101 100644 --- a/noxfile.py +++ b/noxfile.py @@ -134,8 +134,6 @@ def actionlint(session: nox.Session) -> None: "--workdir", "/pwd", # fmt: on ACTIONLINT_IMAGE, - # Disable shellcheck for now - "-shellcheck=", *session.posargs, external=True, ) From 57a43c166393b4380a901d2cd2878c69b03538b3 Mon Sep 17 00:00:00 2001 From: Pysis Date: Thu, 19 Sep 2024 05:36:37 -0400 Subject: [PATCH 510/536] Update other_tools_and_programs.rst (#1915) * Update other_tools_and_programs.rst Mention `ansible-shell` first-party inclusion as `ansible-console`. * Update docs/docsite/rst/community/other_tools_and_programs.rst Confirming received code review nits. Co-authored-by: Don Naro * Update docs/docsite/rst/community/other_tools_and_programs.rst Completely removing mention of deprecated project. Co-authored-by: Maxwell G --------- Co-authored-by: Don Naro Co-authored-by: Maxwell G --- docs/docsite/rst/community/other_tools_and_programs.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docsite/rst/community/other_tools_and_programs.rst b/docs/docsite/rst/community/other_tools_and_programs.rst index 4a87c77e628..82ab7a7d5cd 100644 --- a/docs/docsite/rst/community/other_tools_and_programs.rst +++ b/docs/docsite/rst/community/other_tools_and_programs.rst @@ -99,7 +99,6 @@ Other tools =========== - `Ansible Inventory Grapher `_ - visually displays inventory inheritance hierarchies and at what level a variable is defined in inventory. -- `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. From c84880386a2f123ad5ee999bccfea4a502868663 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Mon, 23 Sep 2024 08:35:59 +0200 Subject: [PATCH 511/536] getting_started_ee/build_execution_environment.rst: temporary sample fix (#1924) --- .../build_execution_environment.rst | 31 +++++++++++++++---- 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/getting_started_ee/build_execution_environment.rst b/docs/docsite/rst/getting_started_ee/build_execution_environment.rst index fb9adbea972..86ff9694cb2 100644 --- a/docs/docsite/rst/getting_started_ee/build_execution_environment.rst +++ b/docs/docsite/rst/getting_started_ee/build_execution_environment.rst @@ -16,12 +16,31 @@ To build your first EE: #. Create a ``execution-environment.yml`` file that specifies dependencies to include in the image. - .. literalinclude:: yaml/execution-environment.yml - :language: yaml - - > The `psycopg2-binary` Python package is included in the `requirements.txt` file for the collection. - > For collections that do not include `requirements.txt` files, you need to specify Python dependencies explicitly. - > See the `Ansible Builder documentation `_ for details. + .. code-block:: yaml + + version: 3 + + images: + base_image: + name: quay.io/fedora/fedora:latest + + dependencies: + ansible_core: + package_pip: ansible-core + ansible_runner: + package_pip: ansible-runner + system: + - openssh-clients + - sshpass + galaxy: + collections: + - name: community.postgresql + + .. note:: + + The `psycopg2-binary` Python package is included in the `requirements.txt` file for the collection. + For collections that do not include `requirements.txt` files, you need to specify Python dependencies explicitly. + See the `Ansible Builder documentation `_ for details. #. Build a EE container image called ``postgresql_ee``. From dc6a39e00d3dc80d02bb15fbf3612e0d6707a5bd Mon Sep 17 00:00:00 2001 From: Don Naro Date: Tue, 24 Sep 2024 13:07:56 +0100 Subject: [PATCH 512/536] [devel] update tagger versions for stable-2.18 (#1932) * tagger versions * fix typo --- hacking/tagger/tag.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hacking/tagger/tag.py b/hacking/tagger/tag.py index d2067583160..a404fc4887f 100755 --- a/hacking/tagger/tag.py +++ b/hacking/tagger/tag.py @@ -42,10 +42,10 @@ DEFAULT_ANSIBLE_CORE_CHECKOUT = ROOT.parent.joinpath("ansible") DEFAULT_REMOTE = "origin" DEFAULT_ACTIVE_BRANCHES: tuple[str, ...] = ( - "stable-2.14", "stable-2.15", "stable-2.16", "stable-2.17", + "stable-2.18", ) From dce75072faa1d63ce3cf61646a8feb633685e2b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9E=97=E5=8D=9A=E4=BB=81=20Buo-ren=20Lin?= Date: Wed, 25 Sep 2024 13:32:34 +0800 Subject: [PATCH 513/536] many: Fix title case of Git references (#1938) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * many: Fix title case of Git references Currently many references of the Git software don't use title case, this patch fixes them while leaving those that should remain lowercase intact: * `git` command call in code blocks. * Git references in changelog entries should stay consistent with the revision title. Fixes #1935. Signed-off-by: 林博仁(Buo-ren Lin) * Update docs/docsite/rst/dev_guide/testing_integration.rst Fix command markup. Co-authored-by: Felix Fontein * Update hacking/README.md Also fix title case of Python. Co-authored-by: Felix Fontein --------- Signed-off-by: 林博仁(Buo-ren Lin) Co-authored-by: Felix Fontein --- CONTRIBUTING.md | 2 +- .../rst/collections_guide/collections_installing.rst | 4 ++-- .../collection_release_with_branches.rst | 2 +- .../collection_requirements.rst | 4 ++-- .../rst/community/documentation_contributions.rst | 2 +- docs/docsite/rst/community/maintainers_workflow.rst | 2 +- .../docsite/rst/community/other_tools_and_programs.rst | 2 +- .../dev_guide/developing_collections_contributing.rst | 2 +- .../rst/dev_guide/developing_collections_creating.rst | 2 +- .../dev_guide/developing_collections_distributing.rst | 6 +++--- .../rst/dev_guide/developing_collections_shared.rst | 4 ++-- .../rst/dev_guide/developing_collections_structure.rst | 2 +- .../rst/dev_guide/developing_modules_in_groups.rst | 2 +- docs/docsite/rst/dev_guide/developing_rebasing.rst | 2 +- docs/docsite/rst/dev_guide/testing.rst | 4 ++-- .../dev_guide/testing/sanity/integration-aliases.rst | 2 +- docs/docsite/rst/dev_guide/testing_httptester.rst | 2 +- docs/docsite/rst/dev_guide/testing_integration.rst | 2 +- docs/docsite/rst/dev_guide/testing_running_locally.rst | 4 ++-- docs/docsite/rst/galaxy/user_guide.rst | 10 +++++----- .../docsite/rst/inventory_guide/connection_details.rst | 2 +- docs/docsite/rst/inventory_guide/intro_inventory.rst | 2 +- docs/docsite/rst/reference_appendices/faq.rst | 4 ++-- docs/docsite/rst/reference_appendices/glossary.rst | 2 +- hacking/README.md | 2 +- hacking/ticket_stubs/README.md | 2 +- 26 files changed, 38 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index be7da611765..75c8f4cf037 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,7 +40,7 @@ nondescriptive commit messages. For other more complex changes—especially those that involve the docs build scripts or other tooling code—it may be desirable to preserve the full commit history to keep logical changes separated and avoid clobbering useful metadata -so the git history remains useful in the future. The maintainer who merges the +so the Git history remains useful in the future. The maintainer who merges the PR can select the merge mode through the dropdown menu next to the green merge button. Generally, maintainers should apply PRs using `Squash and merge`. diff --git a/docs/docsite/rst/collections_guide/collections_installing.rst b/docs/docsite/rst/collections_guide/collections_installing.rst index 880f78de4a7..7c346bbb882 100644 --- a/docs/docsite/rst/collections_guide/collections_installing.rst +++ b/docs/docsite/rst/collections_guide/collections_installing.rst @@ -109,7 +109,7 @@ You can also include signatures in addition to those provided by the distributio ansible-galaxy collection install my_namespace.my_collection --signature https://examplehost.com/detached_signature.asc --keyring ~/.ansible/pubring.kbx -GnuPG verification only occurs for collections installed from a distribution server. User-provided signatures are not used to verify collections installed from git repositories, source directories, or URLs/paths to tar.gz files. +GnuPG verification only occurs for collections installed from a distribution server. User-provided signatures are not used to verify collections installed from Git repositories, source directories, or URLs/paths to tar.gz files. You can also include additional signatures in the collection ``requirements.yml`` file under the ``signatures`` key. @@ -202,7 +202,7 @@ Installing a collection from source files .. include:: ../shared_snippets/installing_collections_file.rst -Installing a collection from a git repository +Installing a collection from a Git repository --------------------------------------------- .. include:: ../shared_snippets/installing_collections_git_repo.txt diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst index 0eae079863c..1aaece95ee8 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst @@ -255,7 +255,7 @@ Releasing when more minor versions are expected The format is reStructuredText but not a list as for regular changelog fragments. This text will be inserted into the changelog. - Add to git and commit. + Add to Git and commit. 5. Generate the changelogs. diff --git a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst index acd549632bb..1784b702ddd 100644 --- a/docs/docsite/rst/community/collection_contributors/collection_requirements.rst +++ b/docs/docsite/rst/community/collection_contributors/collection_requirements.rst @@ -375,7 +375,7 @@ and lower barriers to contribution. Repository management ===================== -* Every collection MUST have a public git repository. +* Every collection MUST have a public Git repository. * Releases of the collection MUST be tagged in its repository. * The ``git`` utility with the ``tag`` argument MUST be used to tag the releases. @@ -383,7 +383,7 @@ Repository management * Tag names MAY have a ``v`` prefix. * Tag names MUST have a consistent format from release to release. -* Collection artifacts released to Galaxy MUST be built from the sources that are tagged in the collection's git repository as that release. +* 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. diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index aad80389ad2..c830a0914ea 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -6,7 +6,7 @@ Contributing to the Ansible Documentation Ansible has a lot of documentation and a small team of writers. Community support helps us keep up with new features, fixes, and changes. -Improving the documentation is an easy way to make your first contribution to the Ansible project. You do not have to be a programmer, since most of our documentation is written in YAML (module documentation) or `reStructuredText `_ (rST). Some collection-level documentation is written in a subset of `Markdown `_. If you are using Ansible, you already use YAML in your playbooks. rST and Markdown are mostly just text. You do not even need git experience, if you use the ``Edit on GitHub`` option. +Improving the documentation is an easy way to make your first contribution to the Ansible project. You do not have to be a programmer, since most of our documentation is written in YAML (module documentation) or `reStructuredText `_ (rST). Some collection-level documentation is written in a subset of `Markdown `_. If you are using Ansible, you already use YAML in your playbooks. rST and Markdown are mostly just text. You do not even need Git experience, if you use the ``Edit on GitHub`` option. If you find a typo, a broken example, a missing topic, or any other error or omission on this documentation website, let us know. Here are some ways to support Ansible documentation: diff --git a/docs/docsite/rst/community/maintainers_workflow.rst b/docs/docsite/rst/community/maintainers_workflow.rst index 09675502e43..62c001c3fe1 100644 --- a/docs/docsite/rst/community/maintainers_workflow.rst +++ b/docs/docsite/rst/community/maintainers_workflow.rst @@ -51,7 +51,7 @@ Collection maintainers are responsible for releasing new versions of a collectio #. Planning and announcement. #. Generating a changelog. -#. Creating a release git tag and pushing it. +#. Creating a release Git tag and pushing it. #. Automatically publishing the release tarball on `Ansible Galaxy `_ through the `Zuul dashboard `_. #. Final announcement. #. Optionally, `file a request to include a new collection into the Ansible package `_. diff --git a/docs/docsite/rst/community/other_tools_and_programs.rst b/docs/docsite/rst/community/other_tools_and_programs.rst index 82ab7a7d5cd..68589bb5a26 100644 --- a/docs/docsite/rst/community/other_tools_and_programs.rst +++ b/docs/docsite/rst/community/other_tools_and_programs.rst @@ -40,7 +40,7 @@ Sublime A closed-source, subscription GUI text editor. You can customize the GUI with themes and install packages for language highlighting and other refinements. You can install Sublime on Linux, macOS and Windows. Useful Sublime plugins include: -* `GitGutter `_ - shows information about files in a git repository. +* `GitGutter `_ - shows information about files in a Git repository. * `SideBarEnhancements `_ - provides enhancements to the operations on Sidebar of Files and Folders. * `Sublime Linter `_ - a code-linting framework for Sublime Text 3. * `Pretty YAML `_ - prettifies YAML for Sublime Text 2 and 3. diff --git a/docs/docsite/rst/dev_guide/developing_collections_contributing.rst b/docs/docsite/rst/dev_guide/developing_collections_contributing.rst index 5fc71fee8e1..a1e2984b20c 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_contributing.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_contributing.rst @@ -4,7 +4,7 @@ Contributing to collections *************************** -If you want to add functionality to an existing collection, modify a collection you are using to fix a bug, or change the behavior of a module in a collection, clone the git repository for that collection and make changes on a branch. You can combine changes to a collection with a local checkout of Ansible (``source hacking/env-setup``). +If you want to add functionality to an existing collection, modify a collection you are using to fix a bug, or change the behavior of a module in a collection, clone the Git repository for that collection and make changes on a branch. You can combine changes to a collection with a local checkout of Ansible (``source hacking/env-setup``). You should first check the collection repository to see if it has specific contribution guidelines. These are typically listed in the README.md or CONTRIBUTING.md files within the repository. See :ref:`collection_quickstart` for more general guidelines and :ref:`testing_running_locally` for testing guidelines. diff --git a/docs/docsite/rst/dev_guide/developing_collections_creating.rst b/docs/docsite/rst/dev_guide/developing_collections_creating.rst index ee70217730c..af44d273696 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_creating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_creating.rst @@ -42,7 +42,7 @@ There are a few special namespaces: :local: - The `local namespace `_ does not contain any collection on Ansible Galaxy, and the intention is that this will never change. You can use the ``local`` namespace for collections that are locally on your machine or locally in your git repositories, without having to fear collisions with actually existing collections on Ansible Galaxy. + The `local namespace `_ does not contain any collection on Ansible Galaxy, and the intention is that this will never change. You can use the ``local`` namespace for collections that are locally on your machine or locally in your Git repositories, without having to fear collisions with actually existing collections on Ansible Galaxy. .. _creating_new_collections: diff --git a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst index 167726dc481..1569d22f83c 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst @@ -301,7 +301,7 @@ Installing your collection locally You have two options for installing your collection locally: * Install your collection locally from the tarball. - * Install your collection locally from your git repository. + * Install your collection locally from your Git repository. Installing your collection locally from the tarball ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -316,10 +316,10 @@ Install the tarball into a directory configured in :ref:`COLLECTIONS_PATHS` so A .. _collections_scm_install: -Installing your collection locally from a git repository +Installing your collection locally from a Git repository ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To install your collection locally from a git repository, specify the repository and the branch you want to install: +To install your collection locally from a Git repository, specify the repository and the branch you want to install: .. code-block:: bash diff --git a/docs/docsite/rst/dev_guide/developing_collections_shared.rst b/docs/docsite/rst/dev_guide/developing_collections_shared.rst index baba9422766..11da101d24f 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_shared.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_shared.rst @@ -72,7 +72,7 @@ Listing collection dependencies We recommend that collections work as standalone, independent units, depending only on ansible-core. However, if your collection must depend on features and functionality from another collection, list the other collection or collections under ``dependencies`` in your collection's :file:`galaxy.yml` file. Use the :file:`meta/runtime.yml` file to set the ansible-core version that your collection depends on. For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`. -You can use git repositories for collection dependencies during local development and testing. For example: +You can use Git repositories for collection dependencies during local development and testing. For example: .. code-block:: yaml @@ -80,7 +80,7 @@ You can use git repositories for collection dependencies during local developmen .. warning:: - Do not use git repositories as dependencies for published collections. Dependencies for published collections must be other published collections. + Do not use Git repositories as dependencies for published collections. Dependencies for published collections must be other published collections. .. seealso:: diff --git a/docs/docsite/rst/dev_guide/developing_collections_structure.rst b/docs/docsite/rst/dev_guide/developing_collections_structure.rst index 6c15c31973e..a75c4a7f29b 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_structure.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_structure.rst @@ -204,7 +204,7 @@ Ansible Collections are tested much like Ansible itself, by using the `ansible-t See :ref:`testing_collections` for specific information on how to test collections with ``ansible-test``. -When reading the :ref:`developing_testing` documentation, there will be content that applies to running Ansible from source code through a git clone, which is typical of an Ansible developer. However, it is not always typical for an Ansible Collection author to be running Ansible from source but instead from a stable release, and to create Collections it is not necessary to run Ansible from source. Therefore, when references of dealing with `ansible-test` binary paths, command completion, or environment variables are presented throughout the :ref:`developing_testing` documentation; keep in mind that it is not needed for Ansible Collection Testing because the act of installing the stable release of Ansible containing `ansible-test` is expected to setup those things for you. +When reading the :ref:`developing_testing` documentation, there will be content that applies to running Ansible from source code through a Git clone, which is typical of an Ansible developer. However, it is not always typical for an Ansible Collection author to be running Ansible from source but instead from a stable release, and to create Collections it is not necessary to run Ansible from source. Therefore, when references of dealing with `ansible-test` binary paths, command completion, or environment variables are presented throughout the :ref:`developing_testing` documentation; keep in mind that it is not needed for Ansible Collection Testing because the act of installing the stable release of Ansible containing `ansible-test` is expected to setup those things for you. meta directory diff --git a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst index 8298f6c0d8b..4eed09ada40 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst @@ -64,7 +64,7 @@ Your collection should include the following files to be usable: When you have these files ready, review the :ref:`developing_modules_checklist` again. If you are creating a new collection, you are responsible for all procedures related to your repository, including setting rules for contributions, finding reviewers, and testing and maintaining the code in your collection. -New to git or GitHub +New to Git or GitHub ==================== We realize this may be your first use of Git or GitHub. The following guides may be of use: diff --git a/docs/docsite/rst/dev_guide/developing_rebasing.rst b/docs/docsite/rst/dev_guide/developing_rebasing.rst index e08ac451db4..038f88eed94 100644 --- a/docs/docsite/rst/dev_guide/developing_rebasing.rst +++ b/docs/docsite/rst/dev_guide/developing_rebasing.rst @@ -77,7 +77,7 @@ Updating your pull request Now that you've rebased your branch, you need to push your changes to GitHub to update your PR. -Since rebasing re-writes git history, you will need to use a force push: +Since rebasing re-writes Git history, you will need to use a force push: .. code-block:: shell-session diff --git a/docs/docsite/rst/dev_guide/testing.rst b/docs/docsite/rst/dev_guide/testing.rst index 51a37524fa2..6e743a6f338 100644 --- a/docs/docsite/rst/dev_guide/testing.rst +++ b/docs/docsite/rst/dev_guide/testing.rst @@ -80,7 +80,7 @@ Rerunning a failing CI job Occasionally you may find your PR fails due to a reason unrelated to your change. This could happen for several reasons, including: -* a temporary issue accessing an external resource, such as a yum or git repo +* a temporary issue accessing an external resource, such as a yum or Git repo * a timeout creating a virtual machine to run the tests on If either issue appears to be the case, you can rerun the Azure Pipelines test by: @@ -152,7 +152,7 @@ Use the pull request number when you fetch the proposed changes and create your The first command fetches the proposed changes from the pull request and creates a new branch named ``testing_PRXXXX``, where the XXXX is the actual number associated with the pull request (for example, 65381). The second command checks out the newly created branch. .. note:: - If the GitHub user interface shows that the pull request will not merge cleanly, we do not recommend proceeding if you are not somewhat familiar with git and coding, as you will have to resolve a merge conflict. This is the responsibility of the original pull request contributor. + If the GitHub user interface shows that the pull request will not merge cleanly, we do not recommend proceeding if you are not somewhat familiar with Git and coding, as you will have to resolve a merge conflict. This is the responsibility of the original pull request contributor. .. note:: Some users do not create feature branches, which can cause problems when they have multiple, unrelated commits in their version of ``devel``. If the source looks like ``someuser:devel``, make sure there is only one commit listed on the pull request. diff --git a/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst b/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst index bc97b2e3cd5..02c7397847a 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst @@ -55,7 +55,7 @@ Some test dependencies are automatically discovered: Aliases can be used to declare dependencies that are not handled automatically: - ``needs/target/TARGET`` - Requires use of the test target ``TARGET``. -- ``needs/file/PATH`` - Requires use of the file ``PATH`` relative to the git root. +- ``needs/file/PATH`` - Requires use of the file ``PATH`` relative to the Git root. Skipping -------- diff --git a/docs/docsite/rst/dev_guide/testing_httptester.rst b/docs/docsite/rst/dev_guide/testing_httptester.rst index c9d364cf853..09f6fedbab2 100644 --- a/docs/docsite/rst/dev_guide/testing_httptester.rst +++ b/docs/docsite/rst/dev_guide/testing_httptester.rst @@ -9,7 +9,7 @@ httptester Overview ======== -``httptester`` is a docker container used to host certain resources required by :ref:`testing_integration`. This is to avoid CI tests requiring external resources (such as git or package repos) which, if temporarily unavailable, would cause tests to fail. +``httptester`` is a docker container used to host certain resources required by :ref:`testing_integration`. This is to avoid CI tests requiring external resources (such as Git or package repos) which, if temporarily unavailable, would cause tests to fail. HTTP Testing endpoint which provides the following capabilities: diff --git a/docs/docsite/rst/dev_guide/testing_integration.rst b/docs/docsite/rst/dev_guide/testing_integration.rst index e830ba032b1..13988e0059e 100644 --- a/docs/docsite/rst/dev_guide/testing_integration.rst +++ b/docs/docsite/rst/dev_guide/testing_integration.rst @@ -58,7 +58,7 @@ files in the ``tests/integration/`` directory. Prerequisites ============= -Some tests assume things like hg, svn, and git are installed, and in path. Some tests +Some tests assume things like ``hg``, ``svn``, and ``git`` are installed, and in path. Some tests (such as those for Amazon Web Services) need separate definitions, which will be covered later in this document. diff --git a/docs/docsite/rst/dev_guide/testing_running_locally.rst b/docs/docsite/rst/dev_guide/testing_running_locally.rst index 0d03189bf41..86fac4a62b2 100644 --- a/docs/docsite/rst/dev_guide/testing_running_locally.rst +++ b/docs/docsite/rst/dev_guide/testing_running_locally.rst @@ -27,7 +27,7 @@ Before running ``ansible-test``, set up your environment for :ref:`testing_an_an Testing an Ansible Collection ----------------------------- -If you are testing an Ansible Collection, you need a copy of the collection, preferably a git clone. +If you are testing an Ansible Collection, you need a copy of the collection, preferably a Git clone. For example, to work with the ``community.windows`` collection, follow these steps: 1. Clone the collection you want to test into a valid collection root: @@ -67,7 +67,7 @@ For example, to work with the ``community.windows`` collection, follow these ste Testing ``ansible-core`` ------------------------ -If you are testing ``ansible-core`` itself, you need a copy of the ``ansible-core`` source code, preferably a git clone. +If you are testing ``ansible-core`` itself, you need a copy of the ``ansible-core`` source code, preferably a Git clone. Having an installed copy of ``ansible-core`` is not sufficient or required. For example, to work with the ``ansible-core`` source cloned from GitHub, follow these steps: diff --git a/docs/docsite/rst/galaxy/user_guide.rst b/docs/docsite/rst/galaxy/user_guide.rst index 1caaef4f1cf..fd447fa7520 100644 --- a/docs/docsite/rst/galaxy/user_guide.rst +++ b/docs/docsite/rst/galaxy/user_guide.rst @@ -108,7 +108,7 @@ This returns everything found in Galaxy for the role: Installing roles from Galaxy ============================ -The ``ansible-galaxy`` command comes bundled with Ansible, and you can use it to install roles from Galaxy or directly from a git based SCM. You can +The ``ansible-galaxy`` command comes bundled with Ansible, and you can use it to install roles from Galaxy or directly from a Git based SCM. You can also use it to create a new role, remove roles, or perform tasks on the Galaxy website. The command line tool by default communicates with the Galaxy website API using the server address *https://galaxy.ansible.com*. If you run your own internal Galaxy server @@ -150,7 +150,7 @@ The following provides an example of using ``--roles-path`` to install the role Installing a specific version of a role --------------------------------------- -When the Galaxy server imports a role, it imports any git tags matching the `Semantic Version `_ format as versions. +When the Galaxy server imports a role, it imports any Git tags matching the `Semantic Version `_ format as versions. In turn, you can download a specific version of a role by specifying one of the imported tags. To see the available versions for a role: @@ -165,7 +165,7 @@ To install a specific version of a role from Galaxy, append a comma and the valu $ ansible-galaxy role install geerlingguy.apache,3.2.0 -It is also possible to point directly to the git repository and specify a branch name or commit hash as the version. For example, the following will +It is also possible to point directly to the Git repository and specify a branch name or commit hash as the version. For example, the following will install a specific commit: .. code-block:: bash @@ -191,7 +191,7 @@ Each role in the file will have one or more of the following attributes: src The source of the role. Use the format *namespace.role_name*, if downloading from Galaxy; otherwise, provide a URL pointing - to a repository within a git based SCM. See the examples below. This is a required attribute. + to a repository within a Git based SCM. See the examples below. This is a required attribute. scm Specify the SCM. As of this writing only *git* or *hg* are allowed. See the examples below. Defaults to *git*. version: @@ -207,7 +207,7 @@ Use the following example as a guide for specifying roles in *requirements.yml*: # from galaxy - name: yatesr.timezone - # from locally cloned git repository (git+file:// requires full paths) + # from locally cloned Git repository (git+file:// requires full paths) - src: git+file:///home/bennojoy/nginx # from GitHub diff --git a/docs/docsite/rst/inventory_guide/connection_details.rst b/docs/docsite/rst/inventory_guide/connection_details.rst index 2c462e32b4d..d7ef373449e 100644 --- a/docs/docsite/rst/inventory_guide/connection_details.rst +++ b/docs/docsite/rst/inventory_guide/connection_details.rst @@ -120,4 +120,4 @@ Other connection methods ------------------------ Ansible can use a variety of connection methods beyond SSH. You can select any connection plugin, including managing things locally and managing chroot, lxc, and jail containers. -A mode called 'ansible-pull' can also invert the system and have systems 'phone home' with scheduled git checkouts to pull configuration directives from a central repository. +A mode called 'ansible-pull' can also invert the system and have systems 'phone home' with scheduled Git checkouts to pull configuration directives from a central repository. diff --git a/docs/docsite/rst/inventory_guide/intro_inventory.rst b/docs/docsite/rst/inventory_guide/intro_inventory.rst index 1e7286c6033..11aa6cec56a 100644 --- a/docs/docsite/rst/inventory_guide/intro_inventory.rst +++ b/docs/docsite/rst/inventory_guide/intro_inventory.rst @@ -508,7 +508,7 @@ file gets too big, or when you want to use :ref:`Ansible Vault` For ``ansible-playbook`` you can also add ``group_vars/`` and ``host_vars/`` directories to your playbook directory. Other Ansible commands (for example, ``ansible``, ``ansible-console``, and so on) will only look for ``group_vars/`` and ``host_vars/`` in the inventory directory. If you want other commands to load group and host variables from a playbook directory, you must provide the ``--playbook-dir`` option on the command line. If you load inventory files from both the playbook directory and the inventory directory, variables in the playbook directory will override variables set in the inventory directory. -Keeping your inventory file and variables in a git repo (or other version control) +Keeping your inventory file and variables in a Git repo (or other version control) is an excellent way to track changes to your inventory and host variables. .. _how_we_merge: diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index eb985bd21fd..3e11695088a 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -379,7 +379,7 @@ What is the best way to make content reusable/redistributable? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ If you have not done so already, read all about "Roles" in the playbooks documentation. This helps you make playbook content -self-contained, and works well with things like git submodules for sharing content with others. +self-contained, and works well with things like Git submodules for sharing content with others. If some of these plugin types look strange to you, see the API documentation for more details about ways Ansible can be extended. @@ -906,7 +906,7 @@ The native jinja2 functionality actually allows us to return full Python objects How do I submit a change to the documentation? ++++++++++++++++++++++++++++++++++++++++++++++ -Documentation for Ansible is kept in the main project git repository, and complete instructions +Documentation for Ansible is kept in the main project Git repository, and complete instructions for contributing can be found in the docs README `viewable on GitHub `_. Thanks! diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst index dbe442a8ef3..361a2c87d60 100644 --- a/docs/docsite/rst/reference_appendices/glossary.rst +++ b/docs/docsite/rst/reference_appendices/glossary.rst @@ -383,7 +383,7 @@ when a term comes up on the :ref:`Ansible Forum`. choices. :command:`ansible-pull` works by checking configuration orders out of - git on a crontab and then managing the machine locally, using the + Git on a crontab and then managing the machine locally, using the :term:`local connection` plugin. Pulp 3 Galaxy diff --git a/hacking/README.md b/hacking/README.md index 03c0868676a..2da6c9fccbd 100644 --- a/hacking/README.md +++ b/hacking/README.md @@ -5,7 +5,7 @@ env-setup --------- The 'env-setup' script modifies your environment to allow you to run -ansible from a git checkout using python >= 3.8. +ansible from a Git checkout using Python >= 3.8. First, set up your environment to run from the checkout: diff --git a/hacking/ticket_stubs/README.md b/hacking/ticket_stubs/README.md index 2ab983f76af..0c6e0f036b9 100644 --- a/hacking/ticket_stubs/README.md +++ b/hacking/ticket_stubs/README.md @@ -3,4 +3,4 @@ What's this? This is a directory of common responses to save some typing when responding to GitHub tickets to avoid some carpal tunnel syndrome events as Ansible maintainers deal with the ticket influx. -They are present in the project git repo (on GitHub) so it's easy for people to share and update these snippets of text. +They are present in the project Git repo (on GitHub) so it's easy for people to share and update these snippets of text. From 55f443da03a6997efb9dedb36769091ffd4b6cbe Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 25 Sep 2024 17:31:25 +0300 Subject: [PATCH 514/536] Add Ansible 11 porting guide (#1943) * Add Ansible 11 porting guide. * Fix porting guide. --- .../rst/porting_guides/porting_guide_11.rst | 361 ++++++++++++++++++ .../rst/porting_guides/porting_guides.rst | 1 + 2 files changed, 362 insertions(+) create mode 100644 docs/docsite/rst/porting_guides/porting_guide_11.rst diff --git a/docs/docsite/rst/porting_guides/porting_guide_11.rst b/docs/docsite/rst/porting_guides/porting_guide_11.rst new file mode 100644 index 00000000000..fed8fe170de --- /dev/null +++ b/docs/docsite/rst/porting_guides/porting_guide_11.rst @@ -0,0 +1,361 @@ +.. + THIS DOCUMENT IS AUTOMATICALLY GENERATED BY ANTSIBULL! PLEASE DO NOT EDIT MANUALLY! (YOU PROBABLY WANT TO EDIT porting_guide_core_2.18.rst) + +.. _porting_11_guide: + +======================== +Ansible 11 Porting Guide +======================== + +.. contents:: + :depth: 2 + + +Ansible 11 is based on Ansible-core 2.18. + +We suggest you read this page along with the `Ansible 11 Changelog `_ to understand what updates you may need to make. + +Porting Guide for v11.0.0a1 +=========================== + +Added Collections +----------------- + +- ieisystem.inmanage (version 2.0.0) +- kubevirt.core (version 2.1.0) +- vmware.vmware (version 1.5.0) + +Known Issues +------------ + +Ansible-core +~~~~~~~~~~~~ + +- ansible-test - When using ansible-test containers with Podman on a Ubuntu 24.04 host, ansible-test must be run as a non-root user to avoid permission issues caused by AppArmor. +- ansible-test - When using the Fedora 40 container with Podman on a Ubuntu 24.04 host, the ``unix-chkpwd`` AppArmor profile must be disabled on the host to allow SSH connections to the container. + +ansible.netcommon +~~~~~~~~~~~~~~~~~ + +- libssh - net_put and net_get fail when the destination file intended to be fetched is not present. + +community.docker +~~~~~~~~~~~~~~~~ + +- docker_container - when specifying a MAC address for a container's network, and the network is attached after container creation (for example, due to idempotency checks), the MAC address is at least in some cases ignored by the Docker Daemon (https://github.com/ansible-collections/community.docker/pull/933). + +community.general +~~~~~~~~~~~~~~~~~ + +- homectl - the module does not work under Python 3.13 or newer, since it relies on the removed ``crypt`` standard library module (https://github.com/ansible-collections/community.general/issues/4691, https://github.com/ansible-collections/community.general/pull/8497). +- udm_user - the module does not work under Python 3.13 or newer, since it relies on the removed ``crypt`` standard library module (https://github.com/ansible-collections/community.general/issues/4690, https://github.com/ansible-collections/community.general/pull/8497). + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. +- idrac_support_assist - Issue(308550) - This module fails when the NFS share path contains sub directory. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + +Breaking Changes +---------------- + +Ansible-core +~~~~~~~~~~~~ + +- Stopped wrapping all commands sent over SSH on a Windows target with a ``powershell.exe`` executable. This results in one less process being started on each command for Windows to improve efficiency, simplify the code, and make ``raw`` an actual raw command run with the default shell configured on the Windows sshd settings. This should have no affect on most tasks except for ``raw`` which now is not guaranteed to always be running in a PowerShell shell and from having the console output codepage set to UTF-8. To avoid this issue either swap to using ``ansible.windows.win_command``, ``ansible.windows.win_shell``, ``ansible.windows.win_powershell`` or manually wrap the raw command with the shell commands needed to set the output console encoding. +- assert - Nested templating may result in an inability for the conditional to be evaluated. See the porting guide for more information. +- persistent connection plugins - The ``ANSIBLE_CONNECTION_PATH`` config option no longer has any effect. + +community.mysql +~~~~~~~~~~~~~~~ + +- collection - support of mysqlclient connector is deprecated - use PyMySQL connector instead! We will stop testing against it in collection version 4.0.0 and remove the related code in 5.0.0 (https://github.com/ansible-collections/community.mysql/issues/654). +- mysql_info - The ``users_info`` filter returned variable ``plugin_auth_string`` contains the hashed password and it's misleading, it will be removed from community.mysql 4.0.0. Use the `plugin_hash_string` return value instead (https://github.com/ansible-collections/community.mysql/pull/629). +- mysql_user - the ``user`` alias of the ``name`` argument has been deprecated and will be removed in collection version 5.0.0. Use the ``name`` argument instead. + +community.vmware +~~~~~~~~~~~~~~~~ + +- Adding a dependency on the ``vmware.vmware`` collection (https://github.com/ansible-collections/community.vmware/pull/2159). +- Depending on ``vmware-vcenter`` and ``vmware-vapi-common-client`` instead of ``https://github.com/vmware/vsphere-automation-sdk-python.git`` (https://github.com/ansible-collections/community.vmware/pull/2163). +- Dropping support for pyVmomi < 8.0.3.0.1 (https://github.com/ansible-collections/community.vmware/pull/2163). +- Module utils - Removed ``vmware.run_command_in_guest()`` (https://github.com/ansible-collections/community.vmware/pull/2175). +- Removed support for ansible-core version < 2.17.0. +- vmware_dvs_portgroup - Removed ``security_override`` alias for ``mac_management_override`` and support for ``securityPolicyOverrideAllowed`` which has been deprected in the vSphere API (https://github.com/ansible-collections/community.vmware/issues/1998). +- vmware_dvs_portgroup_info - Removed ``security_override`` because it's deprecated in the vSphere API (https://github.com/ansible-collections/community.vmware/issues/1998). +- vmware_guest_tools_info - Removed deprecated ``vm_tools_install_status`` from the result (https://github.com/ansible-collections/community.vmware/issues/2078). + +community.zabbix +~~~~~~~~~~~~~~~~ + +- All Roles - Remove support for Centos 7 +- All Roles - Remove support for Python2 +- All Roles - Removed support for Debian 10. +- All Roles - Removed support for Ubuntu 18.08 (Bionic) +- Remove support for Ansible < 2.15 and Python < 3.9 +- Remove support for Zabbix 6.2 +- Removed support for Zabbix 6.2 +- zabbix_agent role - Remove support for `zabbix_agent_zabbix_alias`. +- zabbix_agent role - Remove support for `zabbix_get_package` variable. +- zabbix_agent role - Remove support for `zabbix_sender_package` variable. +- zabbix_agent role - Remove support for all `zabbix_agent2_*` variables. + +hetzner.hcloud +~~~~~~~~~~~~~~ + +- Drop support for ansible-core 2.14. + +kubernetes.core +~~~~~~~~~~~~~~~ + +- Remove support for ``ansible-core<2.15`` (https://github.com/ansible-collections/kubernetes.core/pull/737). + +vmware.vmware_rest +~~~~~~~~~~~~~~~~~~ + +- Removing any support for ansible-core <=2.14 + +Major Changes +------------- + +ansible.netcommon +~~~~~~~~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.15.0`, since previous ansible-core versions are EoL now. + +ansible.posix +~~~~~~~~~~~~~ + +- Dropping support for Ansible 2.9, ansible-core 2.15 will be minimum required version for this release + +arista.eos +~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.15.0` due to the end-of-life status of previous `ansible-core` versions. + +check_point.mgmt +~~~~~~~~~~~~~~~~ + +- New R82 Resource Modules +- Support relative positioning for sections + +cisco.asa +~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.15.0`, since previous ansible-core versions are EoL now. + +cisco.ios +~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.15.0`, since previous ansible-core versions are EoL now. + +cisco.iosxr +~~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.15.0`, since previous ansible-core versions are EoL now. + +cisco.nxos +~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.15.0`, since previous ansible-core versions are EoL now. + +community.vmware +~~~~~~~~~~~~~~~~ + +- vmware_guest_tools_upgrade - Subsitute the deprecated ``guest.toolsStatus`` (https://github.com/ansible-collections/community.vmware/pull/2174). +- vmware_vm_shell - Subsitute the deprecated ``guest.toolsStatus`` (https://github.com/ansible-collections/community.vmware/pull/2174). + +community.zabbix +~~~~~~~~~~~~~~~~ + +- All Roles - Add support for openSUSE Leap 15 and SLES 15. +- All Roles - Separate installation of Zabbix repo from all other roles and link them together. + +containers.podman +~~~~~~~~~~~~~~~~~ + +- Add mount and unmount for volumes +- Add multiple subnets for networks +- Add new options for podman_container +- Add new options to pod module +- Add podman search +- Improve idempotency for networking in podman_container +- Redesign idempotency for Podman Pod module + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- Added support to use session ID for authentication of iDRAC, OpenManage Enterprise and OpenManage Enterprise Modular. +- idrac_secure_boot - This module allows to import the secure boot certificate. +- idrac_server_config_profile - This module is enhanced to allow you to export and import custom defaults on iDRAC. +- idrac_support_assist - This module allows to run and export SupportAssist collection logs on iDRAC. +- ome_configuration_compliance_baseline - This module is enhanced to schedule the remediation job and stage the reboot. +- ome_session - This module allows you to create and delete the sessions on OpenManage Enterprise and OpenManage Enterprise Modular. + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Add a sanity_test.yaml file to trigger CI tests in GitHub. +- Support Ansible-core 2.17. +- Support new FOS versions 7.4.4. + +grafana.grafana +~~~~~~~~~~~~~~~ + +- Add a config check before restarting mimir by @panfantastic in https://github.com/grafana/grafana-ansible-collection/pull/198 +- Add support for configuring feature_toggles in grafana role by @LexVar in https://github.com/grafana/grafana-ansible-collection/pull/173 +- Backport post-setup healthcheck from agent to alloy by @v-zhuravlev in https://github.com/grafana/grafana-ansible-collection/pull/213 +- Bump ansible-lint from 24.2.3 to 24.5.0 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/207 +- Bump ansible-lint from 24.5.0 to 24.6.0 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/216 +- Bump braces from 3.0.2 to 3.0.3 in the npm_and_yarn group across 1 directory by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/218 +- Bump pylint from 3.1.0 to 3.1.1 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/200 +- Bump pylint from 3.1.1 to 3.2.2 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/208 +- Bump pylint from 3.2.2 to 3.2.3 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/217 +- Bump pylint from 3.2.3 to 3.2.5 by @dependabot in https://github.com/grafana/grafana-ansible-collection/pull/234 +- Change from config.river to config.alloy by @cardasac in https://github.com/grafana/grafana-ansible-collection/pull/225 +- Fix Grafana Configuration for Unified and Legacy Alerting Based on Version by @voidquark in https://github.com/grafana/grafana-ansible-collection/pull/215 +- Support adding alloy user to extra groups by @v-zhuravlev in https://github.com/grafana/grafana-ansible-collection/pull/212 +- Updated result.json['message'] to result.json()['message'] by @CPreun in https://github.com/grafana/grafana-ansible-collection/pull/223 +- fix:mimir molecule should use ansible core 2.16 by @GVengelen in https://github.com/grafana/grafana-ansible-collection/pull/254 + +ibm.qradar +~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.15.0`, since previous ansible-core versions are EoL now. + +junipernetworks.junos +~~~~~~~~~~~~~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.15.0`, since previous ansible-core versions are EoL now. + +splunk.es +~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.15.0`, since previous ansible-core versions are EoL now. + +vyos.vyos +~~~~~~~~~ + +- Bumping `requires_ansible` to `>=2.15.0`, since previous ansible-core versions are EoL now. + +Removed Collections +------------------- + +- frr.frr (previously included version: 2.0.2) +- inspur.sm (previously included version: 2.3.0) +- netapp.storagegrid (previously included version: 21.12.0) +- openvswitch.openvswitch (previously included version: 2.1.1) +- t_systems_mms.icinga_director (previously included version: 2.0.1) + +Removed Features +---------------- + +- The ``frr.frr`` collection has been removed because it does not support ansible-core 2.18 (https://forum.ansible.com/t/6243). +- The ``inspur.sm`` collection was considered unmaintained and removed from Ansible 11 (https://forum.ansible.com/t/2854). Users can still install this collection with ``ansible-galaxy collection install inspur.sm``. +- The ``netapp.storagegrid`` collection was considered unmaintained and removed from Ansible 11 (https://forum.ansible.com/t/2811). Users can still install this collection with ``ansible-galaxy collection install netapp.storagegrid``. +- The ``openvswitch.openvswitch`` collection has been removed because it does not support ansible-core 2.18 (https://forum.ansible.com/t/6245). + +Ansible-core +~~~~~~~~~~~~ + +- Play - removed deprecated ``ROLE_CACHE`` property in favor of ``role_cache``. +- Remove deprecated `VariableManager._get_delegated_vars` method (https://github.com/ansible/ansible/issues/82950) +- Removed Python 3.10 as a supported version on the controller. Python 3.11 or newer is required. +- Removed support for setting the ``vars`` keyword to lists of dictionaries. It is now required to be a single dictionary. +- loader - remove deprecated non-inclusive words (https://github.com/ansible/ansible/issues/82947). +- paramiko_ssh - removed deprecated ssh_args from the paramiko_ssh connection plugin (https://github.com/ansible/ansible/issues/82939). +- paramiko_ssh - removed deprecated ssh_common_args from the paramiko_ssh connection plugin (https://github.com/ansible/ansible/issues/82940). +- paramiko_ssh - removed deprecated ssh_extra_args from the paramiko_ssh connection plugin (https://github.com/ansible/ansible/issues/82941). +- play_context - remove deprecated PlayContext.verbosity property (https://github.com/ansible/ansible/issues/82945). +- utils/listify - remove deprecated 'loader' argument from listify_lookup_plugin_terms API (https://github.com/ansible/ansible/issues/82949). + +ansible.posix +~~~~~~~~~~~~~ + +- skippy - Remove skippy pluglin as it is no longer supported(https://github.com/ansible-collections/ansible.posix/issues/350). + +community.grafana +~~~~~~~~~~~~~~~~~ + +- removed check and handling of mangled api key in `grafana_dashboard` lookup +- removed deprecated `message` argument in `grafana_dashboard` + +community.okd +~~~~~~~~~~~~~ + +- k8s - Support for ``merge_type=json`` has been removed in version 4.0.0. Please use ``kubernetes.core.k8s_json_patch`` instead (https://github.com/openshift/community.okd/pull/226). + +kubernetes.core +~~~~~~~~~~~~~~~ + +- k8s - Support for ``merge_type=json`` has been removed in version 4.0.0. Please use ``kubernetes.core.k8s_json_patch`` instead (https://github.com/ansible-collections/kubernetes.core/pull/722). +- k8s_exec - the previously deprecated ``result.return_code`` return value has been removed, consider using ``result.rc`` instead (https://github.com/ansible-collections/kubernetes.core/pull/726). +- module_utils/common.py - the previously deprecated ``K8sAnsibleMixin`` class has been removed (https://github.com/ansible-collections/kubernetes.core/pull/726). +- module_utils/common.py - the previously deprecated ``configuration_digest()`` function has been removed (https://github.com/ansible-collections/kubernetes.core/pull/726). +- module_utils/common.py - the previously deprecated ``get_api_client()`` function has been removed (https://github.com/ansible-collections/kubernetes.core/pull/726). +- module_utils/common.py - the previously deprecated ``unique_string()`` function has been removed (https://github.com/ansible-collections/kubernetes.core/pull/726). + +Deprecated Features +------------------- + +Ansible-core +~~~~~~~~~~~~ + +- Deprecate ``ansible.module_utils.basic.AnsibleModule.safe_eval`` and ``ansible.module_utils.common.safe_eval`` as they are no longer used. +- persistent connection plugins - The ``ANSIBLE_CONNECTION_PATH`` config option no longer has any effect, and will be removed in a future release. +- yum_repository - deprecate ``async`` option as it has been removed in RHEL 8 and will be removed in ansible-core 2.22. +- yum_repository - the following options are deprecated: ``deltarpm_metadata_percentage``, ``gpgcakey``, ``http_caching``, ``keepalive``, ``metadata_expire_filter``, ``mirrorlist_expire``, ``protect``, ``ssl_check_cert_permissions``, ``ui_repoid_vars`` as they have no effect for dnf as an underlying package manager. The options will be removed in ansible-core 2.22. + +amazon.aws +~~~~~~~~~~ + +- iam_role - support for creating and deleting IAM instance profiles using the ``create_instance_profile`` and ``delete_instance_profile`` options has been deprecated and will be removed in a release after 2026-05-01. To manage IAM instance profiles the ``amazon.aws.iam_instance_profile`` module can be used instead (https://github.com/ansible-collections/amazon.aws/pull/2221). + +cisco.ios +~~~~~~~~~ + +- ios_bgp_address_family - deprecated attribute password in favour of password_options within neigbhors. +- ios_bgp_global - deprecated attributes aggregate_address, bestpath, inject_map, ipv4_with_subnet, ipv6_with_subnet, nopeerup_delay, distribute_list, address, tag, ipv6_addresses, password, route_map, route_server_context and scope +- ios_linkagg - deprecate legacy module ios_linkagg +- ios_lldp - deprecate legacy module ios_lldp + +community.docker +~~~~~~~~~~~~~~~~ + +- The collection deprecates support for all ansible-core versions that are currently End of Life, `according to the ansible-core support matrix `__. This means that the next major release of the collection will no longer support ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. + +community.general +~~~~~~~~~~~~~~~~~ + +- CmdRunner module util - setting the value of the ``ignore_none`` parameter within a ``CmdRunner`` context is deprecated and that feature should be removed in community.general 12.0.0 (https://github.com/ansible-collections/community.general/pull/8479). +- MH decorator cause_changes module utils - deprecate parameters ``on_success`` and ``on_failure`` (https://github.com/ansible-collections/community.general/pull/8791). +- git_config - the ``list_all`` option has been deprecated and will be removed in community.general 11.0.0. Use the ``community.general.git_config_info`` module instead (https://github.com/ansible-collections/community.general/pull/8453). +- git_config - using ``state=present`` without providing ``value`` is deprecated and will be disallowed in community.general 11.0.0. Use the ``community.general.git_config_info`` module instead to read a value (https://github.com/ansible-collections/community.general/pull/8453). +- pipx - support for versions of the command line tool ``pipx`` older than ``1.7.0`` is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/8793). +- pipx_info - support for versions of the command line tool ``pipx`` older than ``1.7.0`` is deprecated and will be removed in community.general 11.0.0 (https://github.com/ansible-collections/community.general/pull/8793). + +community.grafana +~~~~~~~~~~~~~~~~~ + +- Deprecate `grafana_notification_channel`. It will be removed in version 3.0.0 + +community.routeros +~~~~~~~~~~~~~~~~~~ + +- The collection deprecates support for all Ansible/ansible-base/ansible-core versions that are currently End of Life, `according to the ansible-core support matrix `__. This means that the next major release of the collection will no longer support Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. + +community.sops +~~~~~~~~~~~~~~ + +- The collection deprecates support for all Ansible/ansible-base/ansible-core versions that are currently End of Life, `according to the ansible-core support matrix `__. This means that the next major release of the collection will no longer support Ansible 2.9, ansible-base 2.10, ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, and ansible-core 2.14. + +community.vmware +~~~~~~~~~~~~~~~~ + +- vmware_cluster - the module has been deprecated and will be removed in community.vmware 6.0.0 (https://github.com/ansible-collections/community.vmware/pull/2143). +- vmware_cluster_drs - the module has been deprecated and will be removed in community.vmware 6.0.0 (https://github.com/ansible-collections/community.vmware/pull/2136). +- vmware_cluster_vcls - the module has been deprecated and will be removed in community.vmware 6.0.0 (https://github.com/ansible-collections/community.vmware/pull/2156). diff --git a/docs/docsite/rst/porting_guides/porting_guides.rst b/docs/docsite/rst/porting_guides/porting_guides.rst index 248636a3cee..b235f9dcef3 100644 --- a/docs/docsite/rst/porting_guides/porting_guides.rst +++ b/docs/docsite/rst/porting_guides/porting_guides.rst @@ -10,6 +10,7 @@ This section lists porting guides that can help you in updating playbooks, plugi :maxdepth: 1 :glob: + porting_guide_11 porting_guide_10 porting_guide_9 porting_guide_8 From b57d4725171c4c796ae4ad75431026a7322e1959 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Mon, 30 Sep 2024 08:33:02 -0500 Subject: [PATCH 515/536] dev gitiginore: sync with ansible core (#1951) Fixes: https://github.com/ansible/ansible-documentation/issues/1937 --- .gitignore | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 680520eb406..fe1eaed9155 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,7 @@ docs/docsite/rst/index.rst docs/docsite/rst/cli/ansible-*.rst docs/docsite/rst/cli/ansible.rst docs/docsite/rst/dev_guide/collections_galaxy_meta.rst +docs/docsite/rst/dev_guide/testing/sanity/index.rst.new docs/docsite/rst/dev_guide/index.rst docs/docsite/rst/modules/*.rst docs/docsite/rst/collections/*.rst @@ -90,6 +91,8 @@ Vagrantfile /lib/ansible_base.egg-info/ # First used in the `devel` branch during Ansible 2.11 development. /lib/ansible_core.egg-info/ +# First used in the `devel` branch during Ansible 2.18 development. +/ansible_core.egg-info/ # vendored lib dir lib/ansible/_vendor/* !lib/ansible/_vendor/__init__.py @@ -97,8 +100,6 @@ lib/ansible/_vendor/* /test/integration/cloud-config-*.* !/test/integration/cloud-config-*.*.template .python-version -/hacking/tests/selinux/*.mod -/hacking/tests/selinux/*.pp # Release directory packaging/release/ansible_release /.cache/ From 99a74bfb8e8fae1a9fe087f78d2effff7386a490 Mon Sep 17 00:00:00 2001 From: Akira Yokochi Date: Tue, 1 Oct 2024 01:20:59 +0900 Subject: [PATCH 516/536] fix 2.18 python requirement version (#1945) --- .../rst/reference_appendices/release_and_maintenance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst index 3a114c1d276..5dedccf2987 100644 --- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst +++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst @@ -169,7 +169,7 @@ Dates listed indicate the start date of the maintenance cycle. | Critical: 19 May 2025 | Security: 03 Nov 2025 - May 2026 - - | Python 3.10 - 3.13 + - | Python 3.11 - 3.13 - | Python 3.8 - 3.13 | PowerShell 5.1 * - `2.17`_ From bf81c101e7efc337bc76e2c3f01842547f4adc2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9E=97=E5=8D=9A=E4=BB=81=20Buo-ren=20Lin?= Date: Tue, 1 Oct 2024 04:49:17 +0800 Subject: [PATCH 517/536] playbooks_filters: Mention the usage of the ansible.builtin.split filter (#1929) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * playbooks_filters: Mention the usage of the ansible.builtin.split filter This is a filter I frequently used in my project, it should mentioned in the documentation so that it can be easily recognized by users. Fixes #1928. * Update docs/docsite/rst/playbook_guide/playbooks_filters.rst Fix inconsistent heading markup style. Co-authored-by: Felix Fontein * playbooks_filters: Fix incorrect _dict_filter label location Signed-off-by: 林博仁(Buo-ren Lin) * playbooks_filters: Fix incorrect argument of the split builtin filter Signed-off-by: 林博仁(Buo-ren Lin) * playbooks_filters: Fix incorrect example input and output Signed-off-by: 林博仁(Buo-ren Lin) * Update docs/docsite/rst/playbook_guide/playbooks_filters.rst Increase verbosity. Co-authored-by: Felix Fontein --------- Signed-off-by: 林博仁(Buo-ren Lin) Co-authored-by: Felix Fontein --- .../rst/playbook_guide/playbooks_filters.rst | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index b9f475a4cd8..bb15adb6f32 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -116,6 +116,29 @@ If you are unsure of the underlying Python type of a variable, you can use the : You should note that, while this may seem like a useful filter for checking that you have the right type of data in a variable, you should often prefer :ref:`type tests `, which will allow you to test for specific data types. +Transforming strings into lists +------------------------------- + +Use the :ansplugin:`ansible.builtin.split#filter` filter to transform a character/string delimited string into a list of items suitable for :ref:`looping `. For example, if you want to split a string variable `fruits` by commas, you can use: + +.. code-block:: yaml+jinja + + {{ fruits | split(',') }} + +String data (before applying the :ansplugin:`ansible.builtin.split#filter` filter): + +.. code-block:: yaml + + fruits: apple,banana,orange + +List data (after applying the :ansplugin:`ansible.builtin.split#filter` filter): + +.. code-block:: yaml + + - apple + - banana + - orange + .. _dict_filter: Transforming dictionaries into lists From ecbda9b98c910d7a9d0e638d2042d5d168ed391d Mon Sep 17 00:00:00 2001 From: quicktus Date: Wed, 2 Oct 2024 17:24:31 +0000 Subject: [PATCH 518/536] Update introduction.rst (#1960) --- docs/docsite/rst/getting_started/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/getting_started/introduction.rst b/docs/docsite/rst/getting_started/introduction.rst index a542bd16ea4..ae7dcc4996a 100644 --- a/docs/docsite/rst/getting_started/introduction.rst +++ b/docs/docsite/rst/getting_started/introduction.rst @@ -23,7 +23,7 @@ Agent-less architecture Low maintenance overhead by avoiding the installation of additional software across IT infrastructure. Simplicity - Automation playbooks use straightforward YAML syntax for code that reads like documentation. Ansible is also decentralized, using SSH existing OS credentials to access to remote machines. + Automation playbooks use straightforward YAML syntax for code that reads like documentation. Ansible is also decentralized, using SSH with existing OS credentials to access to remote machines. Scalability and flexibility Easily and quickly scale the systems you automate through a modular design that supports a large range of operating systems, cloud platforms, and network devices. From e6f2cc9ffc318c8dee2368e573114a8b90a585f8 Mon Sep 17 00:00:00 2001 From: dancorrigan1 Date: Wed, 2 Oct 2024 12:26:38 -0500 Subject: [PATCH 519/536] Moved when condition after task name for block example (#1961) when condition should come after name in blocks See: https://ansible.readthedocs.io/projects/lint/rules/key-order/ --- docs/docsite/rst/playbook_guide/playbooks_blocks.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst index c521ff7e3b6..523928bc5b8 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_blocks.rst @@ -20,6 +20,7 @@ All tasks in a block inherit directives applied at the block level. Most of what tasks: - name: Install, configure, and start Apache + when: ansible_facts['distribution'] == 'CentOS' block: - name: Install httpd and memcached ansible.builtin.yum: @@ -38,7 +39,6 @@ All tasks in a block inherit directives applied at the block level. Most of what name: bar state: started enabled: True - when: ansible_facts['distribution'] == 'CentOS' become: true become_user: root ignore_errors: true From f9cd50b68abf27b77604f1be25a23b54f4bd8614 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 3 Oct 2024 12:07:41 +0300 Subject: [PATCH 520/536] Remove no longer applicable part. (#1970) --- docs/docsite/rst/dev_guide/developing_collections_migrating.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_collections_migrating.rst b/docs/docsite/rst/dev_guide/developing_collections_migrating.rst index 6cd63d84ba2..9a5959d7242 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_migrating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_migrating.rst @@ -24,7 +24,6 @@ If the collection from which you are going to migrate content is included in the #. When the next major release of the old collection is prepared: * remove the module/plugin from the old collection - * remove the symlink stored in ``plugin/modules`` directory if appropriate (mainly when removing from ``community.general`` and ``community.network``) * remove related unit and integration tests * remove specific module utils (if they are NOT used by other modules/plugins or ``module_utils``) * remove specific documentation fragments if there are any in the old collection From f109b783e5704abbdfb52d4e024e5ff45697b19b Mon Sep 17 00:00:00 2001 From: Don Naro Date: Fri, 4 Oct 2024 06:16:34 +0100 Subject: [PATCH 521/536] issue #1925 ee getting started missing content (#1975) This change follows up on PR #1924 by restoring the literalinclude and fixing the note that used invalid syntax. --- .../build_execution_environment.rst | 27 ++++--------------- 1 file changed, 5 insertions(+), 22 deletions(-) diff --git a/docs/docsite/rst/getting_started_ee/build_execution_environment.rst b/docs/docsite/rst/getting_started_ee/build_execution_environment.rst index 86ff9694cb2..5d8bb684dc1 100644 --- a/docs/docsite/rst/getting_started_ee/build_execution_environment.rst +++ b/docs/docsite/rst/getting_started_ee/build_execution_environment.rst @@ -16,31 +16,14 @@ To build your first EE: #. Create a ``execution-environment.yml`` file that specifies dependencies to include in the image. - .. code-block:: yaml - - version: 3 - - images: - base_image: - name: quay.io/fedora/fedora:latest - - dependencies: - ansible_core: - package_pip: ansible-core - ansible_runner: - package_pip: ansible-runner - system: - - openssh-clients - - sshpass - galaxy: - collections: - - name: community.postgresql + .. literalinclude:: yaml/execution-environment.yml + :language: yaml .. note:: - The `psycopg2-binary` Python package is included in the `requirements.txt` file for the collection. - For collections that do not include `requirements.txt` files, you need to specify Python dependencies explicitly. - See the `Ansible Builder documentation `_ for details. + The `psycopg2-binary` Python package is included in the `requirements.txt` file for the collection. + For collections that do not include `requirements.txt` files, you need to specify Python dependencies explicitly. + See the `Ansible Builder documentation `_ for details. #. Build a EE container image called ``postgresql_ee``. From 946806ed16a4a9ccfcd0d84d2ac2b08cd7420c47 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Mon, 7 Oct 2024 16:00:48 +0100 Subject: [PATCH 522/536] add project survey 2024 banner (#1979) * add project survey 2024 banner * update survey referral link --- docs/docsite/.templates/banner.html | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/docsite/.templates/banner.html b/docs/docsite/.templates/banner.html index 7f0dc156f45..28280bcbb8c 100644 --- a/docs/docsite/.templates/banner.html +++ b/docs/docsite/.templates/banner.html @@ -16,13 +16,12 @@ var banner = ''; var extra_banner = ''; /*use extra_banner for when we want something extra, like a survey or Community Day notice */ - /* var extra_banner = + var extra_banner = '
' + '

' + - 'Discuss Ansible in the new Ansible Forum!' + + 'We want to hear from you! Help us gain insights into the state of the Ansible ecosystem by taking the Ansible Project Survey 2024.' + '

' + '
'; - */ // Create a banner if we're not on the official docs site if (location.host == "docs.testing.ansible.com") { document.write('
' + From 6ce04d5be6146e76d61a3e633652db9fbbc9afaa Mon Sep 17 00:00:00 2001 From: Alicia Cozine <879121+acozine@users.noreply.github.com> Date: Tue, 8 Oct 2024 10:07:00 -0500 Subject: [PATCH 523/536] draft fix for issue 1850, adds detail for running an ad hoc command to gather facts (#1885) Co-authored-by: Alicia Cozine --- docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst b/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst index f27870a715a..7ab357dfb50 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_vars_facts.rst @@ -20,7 +20,7 @@ Ansible facts are data related to your remote systems, including operating syste ansible.builtin.debug: var: ansible_facts -To see the 'raw' information as gathered, run this command at the command line: +If you have already created an :ref:`inventory` and configured working SSH credentials, you can see the 'raw' information for any host in your inventory by running this :ref:`ad-hoc ansible command` at the command line: .. code-block:: shell From 7063491dc83e79f81ff7f3196061a34b2d642d32 Mon Sep 17 00:00:00 2001 From: Alicia Cozine <879121+acozine@users.noreply.github.com> Date: Tue, 8 Oct 2024 12:51:44 -0500 Subject: [PATCH 524/536] Update playbooks_error_handling.rst (#1982) Closes #1895. Correct example so it behaves as described in the docs. The message "No such file or directory" is sent to stderr, not to stdout. --- docs/docsite/rst/playbook_guide/playbooks_error_handling.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst index 8e2a3cb4b97..65d92fddc93 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_error_handling.rst @@ -116,13 +116,13 @@ You can also combine multiple conditions for failure. This task will fail if bot register: result failed_when: - result.rc == 0 - - '"No such" not in result.stdout' + - '"No such" not in result.stderr' If you want the task to fail when only one condition is satisfied, change the ``failed_when`` definition to .. code-block:: yaml - failed_when: result.rc == 0 or "No such" not in result.stdout + failed_when: result.rc == 0 or "No such" not in result.stderr If you have too many conditions to fit neatly into one line, you can split it into a multi-line YAML value with ``>``. From 60cf13a3c07c17e1520264bbb27ae411ca42a13e Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 8 Oct 2024 20:58:42 +0200 Subject: [PATCH 525/536] Add porting guide for Ansible 9.11.0. (#1988) --- .../rst/porting_guides/porting_guide_9.rst | 83 ++++++++++++++----- 1 file changed, 64 insertions(+), 19 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_9.rst b/docs/docsite/rst/porting_guides/porting_guide_9.rst index 9d651d89f8f..4d9da252673 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_9.rst @@ -84,6 +84,19 @@ Porting custom scripts Networking ========== +Porting Guide for v9.11.0 +========================= + +Deprecated Features +------------------- + +- The ``ngine_io.exoscale`` collection has been deprecated. + It will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. + See `Collections Removal Process for unmaintained collections `__ for more details (`https://forum.ansible.com/t/2572 `__). +- The sensu.sensu_go collection will be removed from Ansible 12 due to violations of the Ansible inclusion requirements. + The collection has \ `unresolved sanity test failures `__. + See `Collections Removal Process for collections not satisfying the collection requirements `__ for more details, including for how this can be cancelled (`https://forum.ansible.com/t/8380 `__). + Porting Guide for v9.10.0 ========================= @@ -158,8 +171,12 @@ fortinet.fortios Deprecated Features ------------------- -- The ``frr.frr`` collection has been deprecated by the maintainers. Since they've also announced to not support ansible-core 2.18, it will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/6243). -- The ``openvswitch.openvswitch`` collection has been deprecated by the maintainers. Since they've also announced to not support ansible-core 2.18, it will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/6245). +- The ``frr.frr`` collection has been deprecated. + It will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. + See `Collections Removal Process for unmaintained collections `__ for more details (`https://forum.ansible.com/t/6243 `__). +- The ``openvswitch.openvswitch`` collection has been deprecated. + It will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. + See `Collections Removal Process for unmaintained collections `__ for more details (`https://forum.ansible.com/t/6245 `__). Porting Guide for v9.7.0 ======================== @@ -320,9 +337,13 @@ fortinet.fortios Deprecated Features ------------------- -- The ``inspur.sm`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/2854). -- The ``netapp.storagegrid`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/2811). -- The ``purestorage.fusion`` collection is officially unmaintained and has been archived. Therefore, it will be removed from Ansible 10 (https://forum.ansible.com/t/3712). +- The ``inspur.sm`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. + See `Collections Removal Process for unmaintained collections `__ for more details, including for how this can be cancelled (`https://forum.ansible.com/t/2854 `__). +- The ``netapp.storagegrid`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. + See `Collections Removal Process for unmaintained collections `__ for more details, including for how this can be cancelled (`https://forum.ansible.com/t/2811 `__). +- The ``purestorage.fusion`` collection has been deprecated. + It will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. + See `Collections Removal Process for unmaintained collections `__ for more details (`https://forum.ansible.com/t/3712 `__). community.crypto ~~~~~~~~~~~~~~~~ @@ -677,12 +698,20 @@ Removed Collections Removed Features ---------------- -- The deprecated servicenow.servicenow collection has been removed from Ansible 7, but accidentally re-added to Ansible 8. It has been removed again from Ansible 9 (https://github.com/ansible-community/community-topics/issues/246). -- The ngine_io.vultr collection has been removed from Ansible 9, because it is officially unmaintained and has been archived. The successor collection ``vultr.cloud`` (using the recent v2 Vultr API) covers the same functionality but might not have compatible syntax (https://github.com/ansible-community/community-topics/issues/257). -- ``cisco.nso`` was considered unmaintained and removed from Ansible 9 as per the `removal from Ansible process `_. Users can still install this collection with ``ansible-galaxy collection install cisco.nso``. -- ``community.fortios`` was considered unmaintained and removed from Ansible 9 as per the `removal from Ansible process `_. Users can still install this collection with ``ansible-galaxy collection install community.fortios``. -- ``community.google`` was considered unmaintained and removed from Ansible 9 as per the `removal from Ansible process `_. Users can still install this collection with ``ansible-galaxy collection install community.google``. -- ``community.skydive`` was considered unmaintained and removed from Ansible 9 as per the `removal from Ansible process `_. Users can still install this collection with ``ansible-galaxy collection install community.skydive``. +- The ``cisco.nso`` collection was considered unmaintained and has been removed from Ansible 9 (`https://github.com/ansible-community/community-topics/issues/155 `__). + Users can still install this collection with ``ansible-galaxy collection install cisco.nso``. +- The ``community.fortios`` collection was considered unmaintained and has been removed from Ansible 9 (`https://github.com/ansible-community/community-topics/issues/162 `__). + Users can still install this collection with ``ansible-galaxy collection install community.fortios``. +- The ``community.google`` collection was considered unmaintained and has been removed from Ansible 9 (`https://github.com/ansible-community/community-topics/issues/160 `__). + Users can still install this collection with ``ansible-galaxy collection install community.google``. +- The ``community.skydive`` collection was considered unmaintained and has been removed from Ansible 9 (`https://github.com/ansible-community/community-topics/issues/171 `__). + Users can still install this collection with ``ansible-galaxy collection install community.skydive``. +- The ``ngine_io.vultr`` collection was considered unmaintained and has been removed from Ansible 9 (`https://github.com/ansible-community/community-topics/issues/257 `__). + Users can still install this collection with ``ansible-galaxy collection install ngine_io.vultr``. +- The servicenow.servicenow collection has been removed from Ansible 9. + The deprecated servicenow.servicenow collection has been removed from Ansible 7, but accidentally re-added to Ansible 8. + See `the removal discussion `__ for details. + Users can still install this collection with ``ansible-galaxy collection install servicenow.servicenow``. Ansible-core ~~~~~~~~~~~~ @@ -797,14 +826,30 @@ hetzner.hcloud Deprecated Features ------------------- -- The ``community.azure`` collection is officially unmaintained and has been archived. Therefore, it will be removed from Ansible 10. There is already a successor collection ``azure.azcollection`` in the community package which should cover the same functionality (https://github.com/ansible-community/community-topics/issues/263). -- The ``hpe.nimble`` collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/254). -- The collection ``community.sap`` has been renamed to ``community.sap_libs``. For now both collections are included in Ansible. The content in ``community.sap`` has deprecated redirects to the new collection in Ansible 9.0.0, and the collection will be removed from Ansible 10 completely. Please update your FQCNs for ``community.sap``. -- The collection ``ibm.spectrum_virtualize`` has been renamed to ``ibm.storage_virtualize``. For now, both collections are included in Ansible. The content in ``ibm.spectrum_virtualize`` will be replaced with deprecated redirects to the new collection in Ansible 10.0.0, and these redirects will eventually be removed from Ansible. Please update your FQCNs for ``ibm.spectrum_virtualize``. -- The collection ``t_systems_mms.icinga_director`` has been renamed to ``telekom_mms.icinga_director``. For now both collections are included in Ansible. The content in ``t_systems_mms.icinga_director`` has been replaced with deprecated redirects to the new collection in Ansible 9.0.0, and these redirects will be removed from Ansible 11. Please update your FQCNs for ``t_systems_mms.icinga_director``. -- The netapp.azure collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/234). -- The netapp.elementsw collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/235). -- The netapp.um_info collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. See `the removal process for details on how this works `__ (https://github.com/ansible-community/community-topics/issues/244). +- The ``community.azure`` collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. + See `Collections Removal Process for unmaintained collections `__ for more details, including for how this can be cancelled (`https://github.com/ansible-community/community-topics/issues/263 `__). +- The ``hpe.nimble`` collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. + See `Collections Removal Process for unmaintained collections `__ for more details, including for how this can be cancelled (`https://github.com/ansible-community/community-topics/issues/254 `__). +- The ``netapp.azure`` collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. + See `Collections Removal Process for unmaintained collections `__ for more details, including for how this can be cancelled (`https://github.com/ansible-community/community-topics/issues/234 `__). +- The ``netapp.elementsw`` collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. + See `Collections Removal Process for unmaintained collections `__ for more details, including for how this can be cancelled (`https://github.com/ansible-community/community-topics/issues/235 `__). +- The ``netapp.um_info`` collection is considered unmaintained and will be removed from Ansible 10 if no one starts maintaining it again before Ansible 10. + See `Collections Removal Process for unmaintained collections `__ for more details, including for how this can be cancelled (`https://github.com/ansible-community/community-topics/issues/244 `__). +- The collection ``community.sap`` was renamed to ``community.sap_libs``. + For now both collections are included in Ansible. + The collection will be completely removed from Ansible 10. + Please update your FQCNs from ``community.sap`` to ``community.sap_libs``. +- The collection ``ibm.spectrum_virtualize`` was renamed to ``ibm.storage_virtualize``. + For now both collections are included in Ansible. + The content in ``ibm.spectrum_virtualize`` will be replaced by deprecated redirects in Ansible 10.0.0. + The collection will be completely removed from Ansible eventually. + Please update your FQCNs from ``ibm.spectrum_virtualize`` to ``ibm.storage_virtualize``. +- The collection ``t_systems_mms.icinga_director`` was renamed to ``telekom_mms.icinga_director``. + For now both collections are included in Ansible. + The content in ``t_systems_mms.icinga_director`` has been replaced by deprecated redirects in Ansible 9.0.0. + The collection will be completely removed from Ansible 11. + Please update your FQCNs from ``t_systems_mms.icinga_director`` to ``telekom_mms.icinga_director``. Ansible-core ~~~~~~~~~~~~ From 652880b6004615b866440f16c3967ede82f404a3 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 8 Oct 2024 20:59:07 +0200 Subject: [PATCH 526/536] Add porting guide for Ansible 10.5.0. (#1987) --- .../rst/porting_guides/porting_guide_10.rst | 87 ++++++++++++++++--- 1 file changed, 74 insertions(+), 13 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_10.rst b/docs/docsite/rst/porting_guides/porting_guide_10.rst index a91df8d7746..8d7042419e1 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_10.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_10.rst @@ -103,6 +103,51 @@ Networking No notable changes +Porting Guide for v10.5.0 +========================= + +Known Issues +------------ + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. +- idrac_support_assist - Issue(308550) - This module fails when the NFS share path contains sub directory. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + +Major Changes +------------- + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_secure_boot - This module allows to Configure attributes, import, or export secure boot certificate, and reset keys. +- idrac_system_erase - This module allows to Erase system and storage components of the server on iDRAC. + +Deprecated Features +------------------- + +- The ``ngine_io.exoscale`` collection has been deprecated. + It will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. + See `Collections Removal Process for unmaintained collections `__ for more details (`https://forum.ansible.com/t/2572 `__). +- The collection ``t_systems_mms.icinga_director`` was renamed to ``telekom_mms.icinga_director``. + For now both collections are included in Ansible. + The content in ``t_systems_mms.icinga_director`` has been replaced by deprecated redirects in Ansible 9.0.0. + The collection will be completely removed from Ansible 11. + Please update your FQCNs from ``t_systems_mms.icinga_director`` to ``telekom_mms.icinga_director``. +- The sensu.sensu_go collection will be removed from Ansible 12 due to violations of the Ansible inclusion requirements. + The collection has \ `unresolved sanity test failures `__. + See `Collections Removal Process for collections not satisfying the collection requirements `__ for more details, including for how this can be cancelled (`https://forum.ansible.com/t/8380 `__). + +community.general +~~~~~~~~~~~~~~~~~ + +- hipchat - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The module is therefore deprecated and will be removed from community.general 11.0.0 if nobody provides compelling reasons to still keep it (https://github.com/ansible-collections/community.general/pull/8919). + Porting Guide for v10.4.0 ========================= @@ -261,8 +306,12 @@ grafana.grafana Deprecated Features ------------------- -- The ``frr.frr`` collection has been deprecated by the maintainers. Since they've also announced to not support ansible-core 2.18, it will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/6243). -- The ``openvswitch.openvswitch`` collection has been deprecated by the maintainers. Since they've also announced to not support ansible-core 2.18, it will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/6245). +- The ``frr.frr`` collection has been deprecated. + It will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. + See `Collections Removal Process for unmaintained collections `__ for more details (`https://forum.ansible.com/t/6243 `__). +- The ``openvswitch.openvswitch`` collection has been deprecated. + It will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. + See `Collections Removal Process for unmaintained collections `__ for more details (`https://forum.ansible.com/t/6245 `__). Porting Guide for v10.1.0 ========================= @@ -621,15 +670,25 @@ Removed Collections Removed Features ---------------- -- The ``gluster.gluster`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/225). Users can still install this collection with ``ansible-galaxy collection install gluster.gluster``. -- The ``hpe.nimble`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/254). Users can still install this collection with ``ansible-galaxy collection install hpe.nimble``. -- The ``netapp.aws`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/223). Users can still install this collection with ``ansible-galaxy collection install netapp.aws``. -- The ``netapp.azure`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/234). Users can still install this collection with ``ansible-galaxy collection install netapp.azure``. -- The ``netapp.elementsw`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/235). Users can still install this collection with ``ansible-galaxy collection install netapp.elementsw``. -- The ``netapp.um_info`` collection was considered unmaintained and removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/244). Users can still install this collection with ``ansible-galaxy collection install netapp.um_info``. -- The deprecated ``community.azure`` collection has been removed. There is a successor collection ``azure.azcollection`` in the community package which should cover the same functionality. -- The deprecated ``community.sap`` collection has been removed from Ansible 10 (https://github.com/ansible-community/community-topics/issues/247). There is a successor collection ``community.sap_libs`` in the community package which should cover the same functionality. -- The deprecated ``purestorage.fusion`` collection has been removed (https://forum.ansible.com/t/3712). +- The ``community.azure`` collection was considered unmaintained and has been removed from Ansible 10 (`https://github.com/ansible-community/community-topics/issues/263 `__). + Users can still install this collection with ``ansible-galaxy collection install community.azure``. +- The ``gluster.gluster`` collection was considered unmaintained and has been removed from Ansible 10 (`https://github.com/ansible-community/community-topics/issues/225 `__). + Users can still install this collection with ``ansible-galaxy collection install gluster.gluster``. +- The ``hpe.nimble`` collection was considered unmaintained and has been removed from Ansible 10 (`https://github.com/ansible-community/community-topics/issues/254 `__). + Users can still install this collection with ``ansible-galaxy collection install hpe.nimble``. +- The ``netapp.aws`` collection was considered unmaintained and has been removed from Ansible 10 (`https://github.com/ansible-community/community-topics/issues/223 `__). + Users can still install this collection with ``ansible-galaxy collection install netapp.aws``. +- The ``netapp.azure`` collection was considered unmaintained and has been removed from Ansible 10 (`https://github.com/ansible-community/community-topics/issues/234 `__). + Users can still install this collection with ``ansible-galaxy collection install netapp.azure``. +- The ``netapp.elementsw`` collection was considered unmaintained and has been removed from Ansible 10 (`https://github.com/ansible-community/community-topics/issues/235 `__). + Users can still install this collection with ``ansible-galaxy collection install netapp.elementsw``. +- The ``netapp.um_info`` collection was considered unmaintained and has been removed from Ansible 10 (`https://github.com/ansible-community/community-topics/issues/244 `__). + Users can still install this collection with ``ansible-galaxy collection install netapp.um_info``. +- The collection ``community.sap`` has been completely removed from Ansible. + It has been renamed to ``community.sap_libs``. + The collection will be completely removed from Ansible eventually. + Please update your FQCNs from ``community.sap`` to ``community.sap_libs``. +- The deprecated ``purestorage.fusion`` collection has been removed (`https://forum.ansible.com/t/3712 `__). Ansible-core ~~~~~~~~~~~~ @@ -715,8 +774,10 @@ junipernetworks.junos Deprecated Features ------------------- -- The ``inspur.sm`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/2854). -- The ``netapp.storagegrid`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. See `the removal process for details on how this works `__ (https://forum.ansible.com/t/2811). +- The ``inspur.sm`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. + See `Collections Removal Process for unmaintained collections `__ for more details, including for how this can be cancelled (`https://forum.ansible.com/t/2854 `__). +- The ``netapp.storagegrid`` collection is considered unmaintained and will be removed from Ansible 11 if no one starts maintaining it again before Ansible 11. + See `Collections Removal Process for unmaintained collections `__ for more details, including for how this can be cancelled (`https://forum.ansible.com/t/2811 `__). Ansible-core ~~~~~~~~~~~~ From 1abc44e3a58b092e545cfa0e87125092bf222419 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Wed, 9 Oct 2024 21:55:33 +0200 Subject: [PATCH 527/536] Upgrade antsibull-docs to 2.15.0 and antsibull-core to 3.3.0. (#1994) --- tests/constraints.in | 2 +- tests/requirements-relaxed.txt | 4 ++-- tests/requirements.txt | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/constraints.in b/tests/constraints.in index 2d0442acf47..30d0fca2285 100644 --- a/tests/constraints.in +++ b/tests/constraints.in @@ -2,4 +2,4 @@ # and antsibull-docs that production builds rely upon. sphinx == 7.2.5 -antsibull-docs == 2.14.0 # currently approved version +antsibull-docs == 2.15.0 # currently approved version diff --git a/tests/requirements-relaxed.txt b/tests/requirements-relaxed.txt index 022ded198e2..51e21ed1d9d 100644 --- a/tests/requirements-relaxed.txt +++ b/tests/requirements-relaxed.txt @@ -26,9 +26,9 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-changelog==0.30.0 # via antsibull-docs -antsibull-core==3.1.0 +antsibull-core==3.3.0 # via antsibull-docs -antsibull-docs==2.14.0 +antsibull-docs==2.15.0 # via -r tests/requirements-relaxed.in antsibull-docs-parser==1.1.0 # via antsibull-docs diff --git a/tests/requirements.txt b/tests/requirements.txt index ba8f1cfdd7e..8286a2188e3 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -26,9 +26,9 @@ ansible-pygments==0.1.1 # sphinx-ansible-theme antsibull-changelog==0.30.0 # via antsibull-docs -antsibull-core==3.1.0 +antsibull-core==3.3.0 # via antsibull-docs -antsibull-docs==2.14.0 +antsibull-docs==2.15.0 # via # -c tests/constraints.in # -r tests/requirements-relaxed.in From d69846789baca85c94aa988da910fc81afa15a28 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 10 Oct 2024 18:59:07 +0100 Subject: [PATCH 528/536] update docs team info page (#1996) * update docs team info page * Update hacking/pr_labeler/pr_labeler/data/docs_team_info.md Co-authored-by: Sandra McCann --------- Co-authored-by: Sandra McCann --- hacking/pr_labeler/pr_labeler/data/docs_team_info.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hacking/pr_labeler/pr_labeler/data/docs_team_info.md b/hacking/pr_labeler/pr_labeler/data/docs_team_info.md index ceb5c67a51b..3f518979de5 100644 --- a/hacking/pr_labeler/pr_labeler/data/docs_team_info.md +++ b/hacking/pr_labeler/pr_labeler/data/docs_team_info.md @@ -1,2 +1,2 @@ -Thanks for your Ansible docs contribution! We talk about Ansible documentation on matrix at [#docs:ansible.im](https://matrix.to/#/#docs:ansible.im) and on libera IRC at #ansible-docs if you ever want to join us and chat about the docs! We meet there on Tuesdays (see [the Ansible calendar](https://github.com/ansible/community/blob/main/meetings/README.md)) and welcome additions to our [weekly agenda items](https://forum.ansible.com/t/documentation-working-group-agenda/153) - scroll down to find the upcoming agenda and add a comment to put something new on that agenda. +Thanks for your Ansible docs contribution! We talk about Ansible documentation on matrix at [#docs:ansible.im](https://matrix.to/#/#docs:ansible.im) if you ever want to join us and chat about the docs! We meet on matrix every Tuesday. See [the Ansible calendar](https://forum.ansible.com/upcoming-events) for meeting details. We welcome additions to our [weekly agenda items](https://forum.ansible.com/t/documentation-working-group-agenda/153/7) too. You can add the `dawgs-meeting` tag to a forum topic to bring it up at the next meeting. From 3590f6550dda80110990d6635cdb0db35fbda931 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 10 Oct 2024 19:01:54 +0100 Subject: [PATCH 529/536] Documenting the branching process (#1956) * resolves #1772 documenting the branching process * Update README.md Co-authored-by: Maxwell G * Update README.md Co-authored-by: Felix Fontein * updates and suggestions * update the support matrix section * Update README.md Co-authored-by: Maxwell G * Update README.md Co-authored-by: Maxwell G * updates and suggestions * maintainers guide * rm active branch example * Update MAINTAINERS.md Co-authored-by: Sandra McCann --------- Co-authored-by: Maxwell G Co-authored-by: Felix Fontein Co-authored-by: Sandra McCann --- MAINTAINERS.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +-- 2 files changed, 83 insertions(+), 2 deletions(-) create mode 100644 MAINTAINERS.md diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 00000000000..a662740efd1 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,81 @@ +# Maintainers guide + +Find details about maintaining the `ansible-documentation` repository. +Note that maintainers have privileged access to the repository to perform special functions such as branching for new versions and preparing Ansible documentation for publishing. +If you're interested in becoming a maintainer, or want to get in touch with us, please join us on matrix at [#docs:ansible.im](https://matrix.to/#/#docs:ansible.im). +We have weekly meetings on matrix every Tuesday (see [the Ansible calendar](https://forum.ansible.com/upcoming-events)) and welcome additions to our [weekly agenda items](https://forum.ansible.com/t/documentation-working-group-agenda/153). + +## Branching for new stable versions + +The branching strategy for this repository mirrors the [`ansible/ansible`](https://github.com/ansible/ansible) repository. +When a new `stable-*` branch is created in the core repository, a corresponding branch in the `ansible-documentation` repository needs to be created. +There are various other changes that should occur around the same time that the new stable branch is cut. + +### Creating stable branches + +Create new stable branches as follows: + +```bash +# Make sure your checkout is up to date. +git fetch upstream + +# Create a new stable branch against the devel branch. +git checkout -b stable-2.18 upstream/devel + +# Push the new stable branch to the repository. +git push upstream stable-2.18 +``` + +After the new stable branch is created, the following changes should be committed as pull requests to the new stable branch: + +* Update the core branch in the `docs/ansible-core-branch.txt` file. +* Remove devel-only tooling. +* Update Python versions in the support matrix. + +### Updating the core branch + +The script that grafts portions of the core repository uses the `docs/ansible-core-branch.txt` file to specify which branch to clone. +When a new stable branch is created, modify the file so that it specifies the correct version. + +```bash +sed -i 's/devel/stable-2.18/g' docs/ansible-core-branch.txt +``` + +### Removing devel-only tooling + +There are some scripts and other tooling artefacts that should be on the `devel` branch only. +After creating a new stable branch, remove the appropriate files and references. + +```bash +# Remove the following workflow files, the tagger script, and tagger requirements. +git rm -r .github/workflows/pip-compile-dev.yml .github/workflows/pip-compile-docs.yml .github/workflows/reusable-pip-compile.yml .github/workflows/tag.yml hacking/tagger tests/tag.* +``` + +Next, remove references to the tagger dependencies as follows: + +1. Remove the reference from the typing input file. + + ```bash + sed -i '/-r tag.in/d' tests/typing.in + ``` + +2. Clean up the typing lockfile. + + ```bash + nox -s pip-compile -- --no-upgrade + ``` + +3. Open `noxfile.py` and remove `"hacking/tagger/tag.py",` from the `LINT_FILES` tuple. + +### Update Python versions in the support matrix + +The minimum supported Python version changes with each Ansible core version. +This requires an update to the support matrix documentation after a new stable branch is created to reflect the appropriate Control Node Python versions. + +Uncomment the new stable version from the `ansible-core support matrix` section in the `docs/docsite/rst/reference_appendices/release_and_maintenance.rst` file. +Submit a PR with the changes and request a core team review. + +### Updating the tagger script + +Update the list of active branches in the `hacking/tagger/tag.py` script on the `devel` branch. +Add the new stable branch and remove the lowest version from the `DEFAULT_ACTIVE_BRANCHES` tuple. diff --git a/README.md b/README.md index 2712aabf09d..3bb09ee9c03 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,7 @@ The lock files contain tested dependencies that are automatically updated on a w If you'd like to use untested dependencies, set `PINNED=false` as in the following example: -``` +```bash PINNED=false nox -s "checkers(docs-build)" ``` @@ -158,7 +158,7 @@ This will determine any missing `ansible-core` tags and create them in `ansible- nox -s tag # If you use a different upstream remote, specify the name. -nox -s tag -- --remote tag +nox -s tag -- --remote tag # If your core repo is not in the same filesystem location, specify the path. nox -s tag -- --core tag From 8c0f92fcdc31f2edcbe771417cd46c00607bbc21 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 10 Oct 2024 19:30:44 +0100 Subject: [PATCH 530/536] Matrix not matrix (#2000) --- MAINTAINERS.md | 5 +++-- hacking/pr_labeler/pr_labeler/data/docs_team_info.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/MAINTAINERS.md b/MAINTAINERS.md index a662740efd1..7d1425cc206 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -2,8 +2,9 @@ Find details about maintaining the `ansible-documentation` repository. Note that maintainers have privileged access to the repository to perform special functions such as branching for new versions and preparing Ansible documentation for publishing. -If you're interested in becoming a maintainer, or want to get in touch with us, please join us on matrix at [#docs:ansible.im](https://matrix.to/#/#docs:ansible.im). -We have weekly meetings on matrix every Tuesday (see [the Ansible calendar](https://forum.ansible.com/upcoming-events)) and welcome additions to our [weekly agenda items](https://forum.ansible.com/t/documentation-working-group-agenda/153). +If you're interested in becoming a maintainer, or want to get in touch with us, please join us on Matrix at [#docs:ansible.im](https://matrix.to/#/#docs:ansible.im). +We have weekly meetings on Matrix every Tuesday. +See [the Ansible calendar](https://forum.ansible.com/upcoming-events) for meeting details. ## Branching for new stable versions diff --git a/hacking/pr_labeler/pr_labeler/data/docs_team_info.md b/hacking/pr_labeler/pr_labeler/data/docs_team_info.md index 3f518979de5..e850a21c012 100644 --- a/hacking/pr_labeler/pr_labeler/data/docs_team_info.md +++ b/hacking/pr_labeler/pr_labeler/data/docs_team_info.md @@ -1,2 +1,2 @@ -Thanks for your Ansible docs contribution! We talk about Ansible documentation on matrix at [#docs:ansible.im](https://matrix.to/#/#docs:ansible.im) if you ever want to join us and chat about the docs! We meet on matrix every Tuesday. See [the Ansible calendar](https://forum.ansible.com/upcoming-events) for meeting details. We welcome additions to our [weekly agenda items](https://forum.ansible.com/t/documentation-working-group-agenda/153/7) too. You can add the `dawgs-meeting` tag to a forum topic to bring it up at the next meeting. +Thanks for your Ansible docs contribution! We talk about Ansible documentation on Matrix at [#docs:ansible.im](https://matrix.to/#/#docs:ansible.im) if you ever want to join us and chat about the docs! We meet on Matrix every Tuesday. See [the Ansible calendar](https://forum.ansible.com/upcoming-events) for meeting details. We welcome additions to our [weekly agenda items](https://forum.ansible.com/t/documentation-working-group-agenda/153/7) too. You can add the `dawgs-meeting` tag to a forum topic to bring it up at the next meeting. From c41abec27c167b6787f59c9102d6eb358232f97c Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Tue, 15 Oct 2024 16:34:40 +0200 Subject: [PATCH 531/536] Add ecosystem_project_resources.rst document (#2007) * Add ecosystem_project_resources.rst document * Fix rst * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Don Naro * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Sandra McCann * Update docs/docsite/rst/community/ecosystem_project_resources.rst Co-authored-by: Sandra McCann * Update docs/docsite/rst/community/ecosystem_project_resources.rst --------- Co-authored-by: Don Naro Co-authored-by: Sandra McCann --- docs/docsite/rst/community/advanced_index.rst | 3 +- .../community/ecosystem_project_resources.rst | 41 +++++++++++++++++++ 2 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 docs/docsite/rst/community/ecosystem_project_resources.rst diff --git a/docs/docsite/rst/community/advanced_index.rst b/docs/docsite/rst/community/advanced_index.rst index b07b72ff17a..6ccc9269b90 100644 --- a/docs/docsite/rst/community/advanced_index.rst +++ b/docs/docsite/rst/community/advanced_index.rst @@ -4,7 +4,7 @@ Advanced Contributor Guide ********************************************** -This guide focuses on contributors who are committers, GitHub admins, or release managers. +This guide focuses on contributors who are committers, GitHub admins, release managers, or Ansible ecosystem project developers. .. toctree:: :maxdepth: 1 @@ -12,3 +12,4 @@ This guide focuses on contributors who are committers, GitHub admins, or release committer_guidelines release_managers github_admins + ecosystem_project_resources diff --git a/docs/docsite/rst/community/ecosystem_project_resources.rst b/docs/docsite/rst/community/ecosystem_project_resources.rst new file mode 100644 index 00000000000..e9f681074a3 --- /dev/null +++ b/docs/docsite/rst/community/ecosystem_project_resources.rst @@ -0,0 +1,41 @@ +.. _ecosystem_project_dev_resources: + +*********************************************** +Ansible Ecosystem Project Development Resources +*********************************************** + +This document lists resources to help contributors interested in developing a community project in the `Ansible ecosystem `_. + +.. note:: + + Any improvements to the resources listed in this document or to the document itself are very welcome! Please submit an issue or pull request in the corresponding GitHub repository. + +.. _onboarding_toolkit: + +Onboarding toolkit +================== + +The `Ansible Onboarding toolkit `_ provides guidelines on setting up GitHub repositories for new projects as well as the type of documentation your project should include. + +Despite being originally developed for Ansible ecosystem projects under the ``ansible-community`` GitHub organization, everyone is welcome to use the onboarding toolkit. + +Project template +================ + +The `Ansible project-template `_ is a GitHub repository template for Ansible ecosystem projects that contains: + +* Files normally present in every repository such as README, license, code of conduct, and so on. +* A docsite template that you are encouraged to use with your project to provide a consistent experience across the Ansible project ecosystem. + +Please take a look at the `docsite `_ built from the project-template to see it in action. + +You are welcome to take the template, fill in your project-specific information, build it using `Sphinx `_, and then publish it. + +Even if your project is not new and already has documentation, we recommend you take a look at the template and check if there is anything missed in documentation for your project users, contributors, and maintainers. + +List of community-curated projects +================================== + +Whether your project repository is under the ``ansible-community`` GitHub organization or under your own one, you are welcome to include your project in the `Awesome Ansible list `_. + +Before letting the community know about your shiny project by adding it to the list, make sure it satisfies the standards explained in the :ref:`onboarding_toolkit` to provide the best user and contributor experience. From d499606aa8678751bd25aa7d95517b2f9cd2723b Mon Sep 17 00:00:00 2001 From: Mario Lenz Date: Tue, 15 Oct 2024 19:52:54 +0200 Subject: [PATCH 532/536] Add porting guide for Ansible 11.0.0a2 (#2014) --- .../rst/porting_guides/porting_guide_11.rst | 91 ++++++++++++++++++- 1 file changed, 87 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/porting_guides/porting_guide_11.rst b/docs/docsite/rst/porting_guides/porting_guide_11.rst index fed8fe170de..edcfaef0946 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_11.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_11.rst @@ -15,6 +15,83 @@ Ansible 11 is based on Ansible-core 2.18. We suggest you read this page along with the `Ansible 11 Changelog `_ to understand what updates you may need to make. +Porting Guide for v11.0.0a2 +=========================== + +Known Issues +------------ + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_diagnostics - Issue(285322) - This module doesn't support export of diagnostics file to HTTP and HTTPS share via SOCKS proxy. +- idrac_firmware - Issue(279282) - This module does not support firmware update using HTTP, HTTPS, and FTP shares with authentication on iDRAC8. +- idrac_storage_volume - Issue(290766) - The module will report success instead of showing failure for new virtual creation on the BOSS-N1 controller if a virtual disk is already present on the same controller. +- idrac_support_assist - Issue(308550) - This module fails when the NFS share path contains sub directory. +- ome_diagnostics - Issue(279193) - Export of SupportAssist collection logs to the share location fails on OME version 4.0.0. +- ome_smart_fabric_uplink - Issue(186024) - The module supported by OpenManage Enterprise Modular, however it does not allow the creation of multiple uplinks of the same name. If an uplink is created using the same name as an existing uplink, then the existing uplink is modified. + +Breaking Changes +---------------- + +cloud.common +~~~~~~~~~~~~ + +- cloud.common collection - Support for ansible-core < 2.15 has been dropped (https://github.com/ansible-collections/cloud.common/pull/145/files). + +Major Changes +------------- + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_secure_boot - This module allows to Configure attributes, import, or export secure boot certificate, and reset keys. +- idrac_system_erase - This module allows to Erase system and storage components of the server on iDRAC. + +fortinet.fortios +~~~~~~~~~~~~~~~~ + +- Improve the logic for SET function to send GET request first then PUT or POST +- Mantis +- Support new FOS versions 7.6.0. + +ieisystem.inmanage +~~~~~~~~~~~~~~~~~~ + +- Add new modules system_lock_mode_info, edit_system_lock_mode(https://github.com/ieisystem/ieisystem.inmanage/pull/24). + +kaytus.ksmanage +~~~~~~~~~~~~~~~ + +- Add new modules system_lock_mode_info, edit_system_lock_mode(https://github.com/ieisystem/kaytus.ksmanage/pull/27). + +Removed Collections +------------------- + +- ngine_io.exoscale (previously included version: 1.1.0) + +Removed Features +---------------- + +- The deprecated ``ngine_io.exoscale`` collection has been removed (`https://forum.ansible.com/t/2572 `__). + +Deprecated Features +------------------- + +- The sensu.sensu_go collection will be removed from Ansible 12 due to violations of the Ansible inclusion requirements. + The collection has \ `unresolved sanity test failures `__. + See `Collections Removal Process for collections not satisfying the collection requirements `__ for more details, including for how this can be cancelled (`https://forum.ansible.com/t/8380 `__). + +community.general +~~~~~~~~~~~~~~~~~ + +- hipchat - the hipchat service has been discontinued and the self-hosted variant has been End of Life since 2020. The module is therefore deprecated and will be removed from community.general 11.0.0 if nobody provides compelling reasons to still keep it (https://github.com/ansible-collections/community.general/pull/8919). + +community.network +~~~~~~~~~~~~~~~~~ + +- This collection and all content in it is unmaintained and deprecated (https://forum.ansible.com/t/8030). If you are interested in maintaining parts of the collection, please copy them to your own repository, and tell others about in the Forum discussion. See the `collection creator path `__ for details. + Porting Guide for v11.0.0a1 =========================== @@ -254,10 +331,16 @@ Removed Collections Removed Features ---------------- -- The ``frr.frr`` collection has been removed because it does not support ansible-core 2.18 (https://forum.ansible.com/t/6243). -- The ``inspur.sm`` collection was considered unmaintained and removed from Ansible 11 (https://forum.ansible.com/t/2854). Users can still install this collection with ``ansible-galaxy collection install inspur.sm``. -- The ``netapp.storagegrid`` collection was considered unmaintained and removed from Ansible 11 (https://forum.ansible.com/t/2811). Users can still install this collection with ``ansible-galaxy collection install netapp.storagegrid``. -- The ``openvswitch.openvswitch`` collection has been removed because it does not support ansible-core 2.18 (https://forum.ansible.com/t/6245). +- The ``inspur.sm`` collection was considered unmaintained and has been removed from Ansible 11 (`https://forum.ansible.com/t/2854 `__). + Users can still install this collection with ``ansible-galaxy collection install inspur.sm``. +- The ``netapp.storagegrid`` collection was considered unmaintained and has been removed from Ansible 11 (`https://forum.ansible.com/t/2811 `__). + Users can still install this collection with ``ansible-galaxy collection install netapp.storagegrid``. +- The collection ``t_systems_mms.icinga_director`` has been completely removed from Ansible. + It has been renamed to ``telekom_mms.icinga_director``. + ``t_systems_mms.icinga_director`` has been replaced by deprecated redirects to ``telekom_mms.icinga_director`` in Ansible 9.0.0. + Please update your FQCNs from ``t_systems_mms.icinga_director`` to ``telekom_mms.icinga_director``. +- The deprecated ``frr.frr`` collection has been removed (`https://forum.ansible.com/t/6243 `__). +- The deprecated ``openvswitch.openvswitch`` collection has been removed (`https://forum.ansible.com/t/6245 `__). Ansible-core ~~~~~~~~~~~~ From e455e4f1fef1d7caf7bf4a8fc2d5885c752c3748 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Tue, 15 Oct 2024 20:07:16 +0200 Subject: [PATCH 533/536] Update docs build to support the new antsibull-docs 2.15.0 features (#2001) * Provide information for antsibull-docs 2.15.0. * I don't think 'named' will ever get implemented. * The paths might be relative to the old CWD. * Show which commands are run. --- .../command_plugins/docs_build.py | 78 ++++++++++++------- 1 file changed, 51 insertions(+), 27 deletions(-) diff --git a/hacking/build_library/build_ansible/command_plugins/docs_build.py b/hacking/build_library/build_ansible/command_plugins/docs_build.py index e064bfdddad..d0843b91171 100644 --- a/hacking/build_library/build_ansible/command_plugins/docs_build.py +++ b/hacking/build_library/build_ansible/command_plugins/docs_build.py @@ -39,7 +39,7 @@ class NoSuchFile(Exception): # Helpers # -def find_latest_ansible_dir(build_data_working): +def find_latest_ansible_dir(build_data_working) -> tuple[str, "packaging.version.Version"]: """Find the most recent ansible major version.""" # imports here so that they don't cause unnecessary deps for all of the plugins from packaging.version import InvalidVersion, Version @@ -47,7 +47,7 @@ def find_latest_ansible_dir(build_data_working): ansible_directories = glob.glob(os.path.join(build_data_working, '[0-9.]*')) # Find the latest ansible version directory - latest = None + latest_dir = None latest_ver = Version('0') for directory_name in (d for d in ansible_directories if os.path.isdir(d)): try: @@ -61,12 +61,12 @@ def find_latest_ansible_dir(build_data_working): if new_version > latest_ver: latest_ver = new_version - latest = directory_name + latest_dir = directory_name - if latest is None: + if latest_dir is None: raise NoSuchFile('Could not find an ansible data directory in {0}'.format(build_data_working)) - return latest + return latest_dir, latest_ver def parse_deps_file(filename): @@ -84,7 +84,7 @@ def write_deps_file(filename, deps_data): f.write(f'{key}: {value}\n') -def find_latest_deps_file(build_data_working, ansible_version): +def find_latest_deps_file(build_data_working, ansible_version: str) -> tuple[str, "packaging.version.Version"]: """Find the most recent ansible deps file for the given ansible major version.""" # imports here so that they don't cause unnecessary deps for all of the plugins from packaging.version import Version @@ -95,19 +95,19 @@ def find_latest_deps_file(build_data_working, ansible_version): raise Exception('No deps files exist for version {0}'.format(ansible_version)) # Find the latest version of the deps file for this major version - latest = None + latest_deps_file = None latest_ver = Version('0') for filename in deps_files: deps_data = parse_deps_file(filename) new_version = Version(deps_data['_ansible_version']) if new_version > latest_ver: latest_ver = new_version - latest = filename + latest_deps_file = filename - if latest is None: + if latest_deps_file is None: raise NoSuchFile('Could not find an ansible deps file in {0}'.format(data_dir)) - return latest + return latest_deps_file, latest_ver # @@ -133,9 +133,18 @@ def generate_core_docs(args): f.write(yaml.dump(deps_file_contents)) # Generate the plugin rst - return antsibull_docs.run(['antsibull-docs', 'stable', '--deps-file', modified_deps_file, - '--ansible-core-source', str(args.top_dir), - '--dest-dir', args.output_dir]) + full_command = [ + 'antsibull-docs', + 'stable', + '--deps-file', + modified_deps_file, + '--ansible-core-source', + str(args.top_dir), + '--dest-dir', + args.output_dir, + ] + print(f"Running {full_command!r}:") + return antsibull_docs.run(full_command) # If we make this more than just a driver for antsibull: # Run other rst generation @@ -164,16 +173,21 @@ def generate_full_docs(args): if args.ansible_build_data: build_data_working = args.ansible_build_data - ansible_version = args.ansible_version + ansible_version: str = args.ansible_version if ansible_version is None: - ansible_version = find_latest_ansible_dir(build_data_working) - params = ['devel', '--pieces-file', os.path.join(ansible_version, 'ansible.in')] + devel_dir, devel_version = find_latest_ansible_dir(build_data_working) + params = ['devel', '--pieces-file', 'ansible.in', '--major-version', str(devel_version.major)] + cwd = str(devel_dir) else: - latest_filename = find_latest_deps_file(build_data_working, ansible_version) + latest_deps_file, ansible_version_ver = find_latest_deps_file(build_data_working, ansible_version) + deps_dir = os.path.dirname(latest_deps_file) # Make a copy of the deps file so that we can set the ansible-core version we'll use modified_deps_file = os.path.join(tmp_dir, 'ansible.deps') - shutil.copyfile(latest_filename, modified_deps_file) + shutil.copyfile(latest_deps_file, modified_deps_file) + + # Make a copy of collection-meta.yaml + shutil.copyfile(os.path.join(deps_dir, 'collection-meta.yaml'), os.path.join(tmp_dir, 'collection-meta.yaml')) # Put our version of ansible-core into the deps file deps_data = parse_deps_file(modified_deps_file) @@ -182,12 +196,23 @@ def generate_full_docs(args): write_deps_file(modified_deps_file, deps_data) - params = ['stable', '--deps-file', modified_deps_file] + params = ['stable', '--deps-file', 'ansible.deps', '--version', str(ansible_version_ver)] + cwd = str(tmp_dir) - # Generate the plugin rst - return antsibull_docs.run(['antsibull-docs'] + params + - ['--ansible-core-source', str(args.top_dir), - '--dest-dir', args.output_dir]) + old_cwd = os.getcwd() + try: + os.chdir(cwd) + # Generate the plugin rst + full_command = ['antsibull-docs'] + params + [ + '--ansible-core-source', + os.path.join(old_cwd, str(args.top_dir)), + '--dest-dir', + os.path.join(old_cwd, args.output_dir), + ] + print(f"Running {full_command!r} in {cwd!r}:") + return antsibull_docs.run(full_command) + finally: + os.chdir(old_cwd) # If we make this more than just a driver for antsibull: # Run other rst generation @@ -199,7 +224,6 @@ class CollectionPluginDocs(Command): _ACTION_HELP = """Action to perform. full: Regenerate the rst for the full ansible website. core: Regenerate the rst for plugins in ansible-core and then build the website. - named: Regenerate the rst for the named plugins and then build the website. """ @classmethod @@ -212,7 +236,7 @@ def init_parser(cls, add_parser): ' hierarchy.') # I think we should make the actions a subparser but need to look in git history and see if # we tried that and changed it for some reason. - parser.add_argument('action', action='store', choices=('full', 'core', 'named'), + parser.add_argument('action', action='store', choices=('full', 'core'), default='full', help=cls._ACTION_HELP) parser.add_argument("-o", "--output-dir", action="store", dest="output_dir", default=DEFAULT_OUTPUT_DIR, @@ -249,7 +273,7 @@ def main(args): if args.action == 'core': return generate_core_docs(args) - # args.action == 'named' (Invalid actions are caught by argparse) - raise NotImplementedError('Building docs for specific files is not yet implemented') + + raise NotImplementedError('New actions have to be explicitly supported by the code') # return 0 From ac8886120b8e8930bf68fe58d822868b01ccaf14 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Tue, 15 Oct 2024 13:07:44 -0500 Subject: [PATCH 534/536] Pip compile check mode (#1950) * nox pip-compile: support check mode Support a custom --check flag to fail if pip-compile made any changes so we can check that that lockfiles are in sync with the input (.in) files. * ci: remove push trigger for pip-compile workflows Now that we have the pip-compile-check job, this is redundant. PR checks will fail if lockfiles are out-of-sync, so there's no need to run the complete pip-compile workflow that performs a full update of the dependencies. Complete updates are still performed on a weekly basis. --- .github/workflows/pip-compile-dev.yml | 7 ------- .github/workflows/pip-compile-docs.yml | 7 ------- .github/workflows/reusable-nox.yml | 11 ++++++++++- noxfile.py | 12 +++++++++++- 4 files changed, 21 insertions(+), 16 deletions(-) diff --git a/.github/workflows/pip-compile-dev.yml b/.github/workflows/pip-compile-dev.yml index 86564df9635..98727d90deb 100644 --- a/.github/workflows/pip-compile-dev.yml +++ b/.github/workflows/pip-compile-dev.yml @@ -12,13 +12,6 @@ name: "Refresh dev dependencies" labels: required: false type: string - push: - branches: - - devel - paths: - - .github/workflows/reusable-pip-compile.yml - - ".github/workflows/pip-compile-dev.yml" - - "tests/*.in" jobs: refresh: diff --git a/.github/workflows/pip-compile-docs.yml b/.github/workflows/pip-compile-docs.yml index 0e183ab6615..8c42c90c840 100644 --- a/.github/workflows/pip-compile-docs.yml +++ b/.github/workflows/pip-compile-docs.yml @@ -18,13 +18,6 @@ name: "Refresh docs build dependencies" labels: required: false type: string - push: - branches: - - devel - paths: - - .github/workflows/reusable-pip-compile.yml - - ".github/workflows/pip-compile-docs.yml" - - "tests/*.in" jobs: refresh: diff --git a/.github/workflows/reusable-nox.yml b/.github/workflows/reusable-nox.yml index 2f8b8a92900..1793e35e026 100644 --- a/.github/workflows/reusable-nox.yml +++ b/.github/workflows/reusable-nox.yml @@ -11,6 +11,10 @@ jobs: fail-fast: false matrix: include: + # Inputs: + # session: name of session + # python-versions: comma-separated list of Python versions to install + # extra-args (optional): extra arguments to pass to nox session. - session: static python-versions: "3.11" - session: formatters_check @@ -25,6 +29,9 @@ jobs: python-versions: "3.11" - session: "actionlint" python-versions: "3.11" + - session: "pip-compile" + extra-args: "--check" + python-versions: "3.11" name: "Run nox ${{ matrix.session }} session" steps: - name: Check out repo @@ -38,4 +45,6 @@ jobs: nox -e clone-core - name: "Run nox -e ${{ matrix.session }}" run: | - nox -e "${{ matrix.session }}" + # Using GHA expression interpolation is fine here, + # as we control all the inputs. + nox -e "${{ matrix.session }}" -- ${{ matrix.extra-args }} diff --git a/noxfile.py b/noxfile.py index 395d3aaf101..d9192fd6fca 100644 --- a/noxfile.py +++ b/noxfile.py @@ -162,7 +162,14 @@ def pip_compile(session: nox.Session, req: str): # Use --upgrade by default unless a user passes -P. args = list(session.posargs) - if not any( + + # Support a custom --check flag to fail if pip-compile made any changes + # so we can check that that lockfiles are in sync with the input (.in) files. + check_mode = "--check" in args + if check_mode: + # Remove from args, as pip-compile doesn't actually support --check. + args.remove("--check") + elif not any( arg.startswith(("-P", "--upgrade-package", "--no-upgrade")) for arg in args ): args.append("--upgrade") @@ -176,6 +183,9 @@ def pip_compile(session: nox.Session, req: str): ) # fmt: on + if check_mode and session.run("git", "diff", "tests", silent=True, external=True): + session.error("Check mode: files were changed") + @nox.session(name="clone-core") def clone_core(session: nox.Session): From 495d91595f20a115bae15022a4d2f0c0e6f15116 Mon Sep 17 00:00:00 2001 From: Abhijeet Kasurde Date: Tue, 15 Oct 2024 11:10:46 -0700 Subject: [PATCH 535/536] Remove unsupported API example (#1939) * Python API example is unsupported and difficult to maintain with each new release. Signed-off-by: Abhijeet Kasurde --- docs/docsite/rst/dev_guide/developing_api.rst | 24 +--- examples/scripts/uptime.py | 132 ------------------ 2 files changed, 1 insertion(+), 155 deletions(-) delete mode 100755 examples/scripts/uptime.py diff --git a/docs/docsite/rst/dev_guide/developing_api.rst b/docs/docsite/rst/dev_guide/developing_api.rst index 4f6d5890b2c..d7fed9bea78 100644 --- a/docs/docsite/rst/dev_guide/developing_api.rst +++ b/docs/docsite/rst/dev_guide/developing_api.rst @@ -6,33 +6,11 @@ Python API .. contents:: Topics -.. note:: This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible. If you want to use Python API only for executing playbooks or modules, consider `ansible-runner `_ first. - -There are several ways to use Ansible from an API perspective. You can use -the Ansible Python API to control nodes, you can extend Ansible to respond to various Python events, you can -write plugins, and you can plug in inventory data from external data sources. This document -gives a basic overview and examples of the Ansible execution and playbook API. +.. attention:: The Ansible API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible. If you want to use Python API only for executing playbooks or modules, consider `ansible-runner `_ first. If you would like to use Ansible programmatically from a language other than Python, trigger events asynchronously, or have access control and logging demands, please see the `AWX project `_. -.. note:: Because Ansible relies on forking processes, this API is not thread safe. - -.. _python_api_example: - -Python API example -================== - -This example is a simple demonstration that shows how to minimally run a couple of tasks: - -.. literalinclude:: ../../../../examples/scripts/uptime.py - :language: python - -.. note:: Ansible emits warnings and errors through the display object, which prints directly to stdout, stderr and the Ansible log. - -The source code for the ``ansible`` -command line tools (``lib/ansible/cli/``) is `available on GitHub `_. - .. seealso:: :ref:`developing_inventory` diff --git a/examples/scripts/uptime.py b/examples/scripts/uptime.py deleted file mode 100755 index cdb1f6653a3..00000000000 --- a/examples/scripts/uptime.py +++ /dev/null @@ -1,132 +0,0 @@ -#!/usr/bin/env python - -from __future__ import (absolute_import, division, print_function) -__metaclass__ = type - -import json -import shutil - -import ansible.constants as C -from ansible.executor.task_queue_manager import TaskQueueManager -from ansible.module_utils.common.collections import ImmutableDict -from ansible.inventory.manager import InventoryManager -from ansible.parsing.dataloader import DataLoader -from ansible.playbook.play import Play -from ansible.plugins.callback import CallbackBase -from ansible.plugins.loader import init_plugin_loader -from ansible.vars.manager import VariableManager -from ansible import context - - -# Create a callback plugin so we can capture the output -class ResultsCollectorJSONCallback(CallbackBase): - """A sample callback plugin used for performing an action as results come in. - - If you want to collect all results into a single object for processing at - the end of the execution, look into utilizing the ``json`` callback plugin - or writing your own custom callback plugin. - """ - - def __init__(self, *args, **kwargs): - super(ResultsCollectorJSONCallback, self).__init__(*args, **kwargs) - self.host_ok = {} - self.host_unreachable = {} - self.host_failed = {} - - def v2_runner_on_unreachable(self, result): - host = result._host - self.host_unreachable[host.get_name()] = result - - def v2_runner_on_ok(self, result, *args, **kwargs): - """Print a json representation of the result. - - Also, store the result in an instance attribute for retrieval later - """ - host = result._host - self.host_ok[host.get_name()] = result - print(json.dumps({host.name: result._result}, indent=4)) - - def v2_runner_on_failed(self, result, *args, **kwargs): - host = result._host - self.host_failed[host.get_name()] = result - - -def main(): - init_plugin_loader() - host_list = ['localhost', 'www.example.com', 'www.google.com'] - # since the API is constructed for CLI it expects certain options to always be set in the context object - context.CLIARGS = ImmutableDict(module_path=['/to/mymodules', '/usr/share/ansible'], forks=10, become=None, - become_method=None, become_user=None, check=False, diff=False, verbosity=0) - # required for - # https://github.com/ansible/ansible/blob/devel/lib/ansible/inventory/manager.py#L204 - sources = ','.join(host_list) - if len(host_list) == 1: - sources += ',' - - # initialize needed objects - loader = DataLoader() # Takes care of finding and reading yaml, json and ini files - passwords = dict(vault_pass='secret') - - # Instantiate our ResultsCollectorJSONCallback for handling results as they come in. Ansible expects this to be one of its main display outlets - results_callback = ResultsCollectorJSONCallback() - - # create inventory, use path to host config file as source or hosts in a comma separated string - inventory = InventoryManager(loader=loader, sources=sources) - - # variable manager takes care of merging all the different sources to give you a unified view of variables available in each context - variable_manager = VariableManager(loader=loader, inventory=inventory) - - # instantiate task queue manager, which takes care of forking and setting up all objects to iterate over host list and tasks - # IMPORTANT: This also adds library dirs paths to the module loader - # IMPORTANT: and so it must be initialized before calling `Play.load()`. - tqm = TaskQueueManager( - inventory=inventory, - variable_manager=variable_manager, - loader=loader, - passwords=passwords, - stdout_callback=results_callback, # Use our custom callback instead of the ``default`` callback plugin, which prints to stdout - ) - - # create data structure that represents our play, including tasks, this is basically what our YAML loader does internally. - play_source = dict( - name="Ansible Play", - hosts=host_list, - gather_facts='no', - tasks=[ - dict(action=dict(module='shell', args='ls'), register='shell_out'), - dict(action=dict(module='debug', args=dict(msg='{{shell_out.stdout}}'))), - dict(action=dict(module='command', args=dict(cmd='/usr/bin/uptime'))), - ] - ) - - # Create play object, playbook objects use .load instead of init or new methods, - # this will also automatically create the task objects from the info provided in play_source - play = Play().load(play_source, variable_manager=variable_manager, loader=loader) - - # Actually run it - try: - result = tqm.run(play) # most interesting data for a play is actually sent to the callback's methods - finally: - # we always need to cleanup child procs and the structures we use to communicate with them - tqm.cleanup() - if loader: - loader.cleanup_all_tmp_files() - - # Remove ansible tmpdir - shutil.rmtree(C.DEFAULT_LOCAL_TMP, True) - - print("UP ***********") - for host, result in results_callback.host_ok.items(): - print('{0} >>> {1}'.format(host, result._result['stdout'])) - - print("FAILED *******") - for host, result in results_callback.host_failed.items(): - print('{0} >>> {1}'.format(host, result._result['msg'])) - - print("DOWN *********") - for host, result in results_callback.host_unreachable.items(): - print('{0} >>> {1}'.format(host, result._result['msg'])) - - -if __name__ == '__main__': - main() From 58659cf320ae8cfcb23a2df0ac8eb622f2702a5c Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Tue, 15 Oct 2024 14:11:17 -0400 Subject: [PATCH 536/536] Tagging nuance (#1900) * Tagging nuance (cherry picked from commit 0cf6e62673cf7368e5223f52f335d4d9ab7bb1de) * izpell * ammended for handlers * remove flush example * add ref on handler limitations --- .../rst/playbook_guide/playbooks_handlers.rst | 3 +- .../rst/playbook_guide/playbooks_tags.rst | 37 +++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst index 1b3c2111859..953c1014711 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_handlers.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_handlers.rst @@ -211,4 +211,5 @@ Since Ansible 2.14 :ansplugin:`meta tasks ` are all Limitations ----------- -A handler cannot run ``import_role`` or ``include_role``. +A handler cannot run ``import_role`` nor ``include_role``. +Handlers :ref:`ignore tags `. diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst index 98d782c0d2e..89124f01057 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst @@ -9,9 +9,13 @@ If you have a large playbook, it may be useful to run only specific parts of it #. Add tags to your tasks, either individually or with tag inheritance from a block, play, role, or import. #. Select or skip tags when you run your playbook. +.. note:: + The ``tags`` keyword is part of 'pre processing' the playbook and has high precedence when deciding what tasks are available to consider for execution. + .. contents:: :local: + Adding tags with the tags keyword ================================= @@ -81,6 +85,14 @@ You can apply the same tag to more than one individual task. This example tags s If you ran these four tasks in a playbook with ``--tags ntp``, Ansible would run the three tasks tagged ``ntp`` and skip the one task that does not have that tag. +.. _tags_on_handlers: + +Adding tags to handlers +^^^^^^^^^^^^^^^^^^^^^^^ + +Handlers are a special case of tasks that only execute when notified, as such they ignore all tags and cannot be selected for nor against. + + .. _tags_on_blocks: Adding tags to blocks @@ -121,6 +133,23 @@ If you want to apply a tag to many, but not all, of the tasks in your play, use tags: filesharing +Be mindful that ``tag`` selection supersedes most other logic, including ``block`` error handling. Setting a tag on a task in a ``block`` but not in the ``rescue`` or ``always`` section will prevent those from triggering if your tags selection does not cover the tasks in those sections. + +.. code-block:: yaml + + - block: + - debug: msg=run with tag, but always fail + failed_when: true + tags: example + + rescue: + - debug: msg=I always run because the block always fails, except if you select to only run 'example' tag + + always: + - debug: msg=I always run, except if you select to only run 'example' tag + +This example runs all 3 tasks if called without specifying ``--tags`` but only runs the first task if you run with ``--tags example``. + .. _tags_on_plays: Adding tags to plays @@ -156,6 +185,8 @@ If all the tasks in a play should get the same tag, you can add the tag at the l tasks: ... +.. note:: + The tasks tagged will include all implicit tasks (like fact gathering) of the play, including those added via roles. .. _tags_on_roles: @@ -192,6 +223,12 @@ or: # using YAML shorthand, this is equivalent to: # - { role: foo, tags: ["bar", "baz"] } + +.. note:: + When adding a tag at the role level, not only are all tasks tagged, but the role's dependencies also have their tasks tagged. + See the tag inheritance section for details. + + .. _tags_on_includes: Adding tags to includes