diff --git a/.codespellignorelines b/.codespellignorelines new file mode 100644 index 0000000000..5993654135 --- /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 0000000000..e59b06502e --- /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 0000000000..ee4f01c1e0 --- /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 befde05507..5931b4f448 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 a43f6c634d..ba56fb1a09 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 172c5abce4..1f18d861c9 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 4a379dcda6..25f4f52a4f 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 7067a5a266..5cd0e20a83 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 124d112439..31a07ceacc 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 7a20affc25..e51e4a9cc0 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 5f21662894..fc0fecceaf 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 8616143369..dce4ed934f 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 ddf79c954b..02dbb68a68 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 3bd50fdc25..56849b379d 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 ee6ff67fe9..e4c53d59e5 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 ab2e7a73b2..31ad113623 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 d347812b9c..c4ec680dbe 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 5aa5f11ce9..e99ab1dd5a 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 6aa5a8117d..280097a359 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 d4e42d8ac2..70a3b57f2b 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 1b6509f933..7d29a7d79e 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 7c1812a4e1..52674d7764 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 be5aa77092..499863e3d4 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 0baf58a5e2..354daddcf1 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 3d883f5644..e4b12bfc95 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 cc7e39bc50..880fbf4bc9 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 0000000000..e3da9e4b09 --- /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 0000000000..1b5e612768 --- /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