diff --git a/docs/docsite/rst/community/committer_guidelines.rst b/docs/docsite/rst/community/committer_guidelines.rst index fb5eac9780e..2caa3a56a7c 100644 --- a/docs/docsite/rst/community/committer_guidelines.rst +++ b/docs/docsite/rst/community/committer_guidelines.rst @@ -15,7 +15,7 @@ If you abuse the trust and break components and builds, and so on, the trust lev Features, high-level design, and roadmap ======================================== -As a core team member, you are an integral part of the team that develops the :ref:`roadmap `. Please be engaged, and push for the features and fixes that you want to see. Also keep in mind that Red Hat, as a company, will commit to certain features, fixes, APIs, and so on. for various releases. Red Hat, the company, and the Ansible team must get these committed features (and so on.) completed and released as scheduled. Obligations to users, the community, and customers must come first. Because of these commitments, a feature you want to develop yourself may not get into a release if it impacts a lot of other parts within Ansible. +As a core team member, you are an integral part of the team that develops the :ref:`roadmap `. Please be engaged, and push for the features and fixes that you want to see. Also keep in mind that Red Hat, as a company, will commit to certain features, fixes, APIs, and so on, for various releases. Red Hat, the company, and the Ansible team must get these changes completed and released as scheduled. Obligations to users, the community, and customers must come first. Because of these commitments, a feature you want to develop yourself may not get into a release if it affects a lot of other parts within Ansible. Any other new features and changes to high level design should go through the proposal process (TBD), to ensure the community and core team have had a chance to review the idea and approve it. The core team has sole responsibility for merging new features based on proposals. @@ -49,7 +49,7 @@ Individuals with direct commit access to ansible/ansible are entrusted with powe - Commit directly. - Merge your own PRs. Someone else should have a chance to review and approve the PR merge. If you are a Core Committer, you have a small amount of leeway here for very minor changes. - Forget about alternate environments. Consider the alternatives--yes, people have bad environments, but they are the ones who need us the most. - - Drag your community team members down. Always discuss the technical merits, but you should never address the person's limitations (you can later go for beers and call them idiots, but not in IRC/GitHub/and so on.). + - Drag your community team members down. Always discuss the technical merits, but you should never address the person's limitations (you can later go for beers and call them idiots, but not in IRC/GitHub/and so on). - Forget about the maintenance burden. Some things are really cool to have, but they might not be worth shoehorning in if the maintenance burden is too great. - Break playbooks. Always keep backwards compatibility in mind. - Forget to keep it simple. Complexity breeds all kinds of problems. @@ -57,11 +57,11 @@ Individuals with direct commit access to ansible/ansible are entrusted with powe * Do - Squash, avoid merges whenever possible, use GitHub's squash commits or cherry pick if needed (bisect thanks you). - - Be active. Committers who have no activity on the project (through merges, triage, commits, and so on.) will have their permissions suspended. + - Be active. Committers who have no activity on the project (through merges, triage, commits, and so on) will have their permissions suspended. - Consider backwards compatibility (goes back to "don't break existing playbooks"). - Write tests. PRs with tests are looked at with more priority than PRs without tests that should have them included. While not all changes require tests, be sure to add them for bug fixes or functionality changes. - Discuss with other committers, specially when you are unsure of something. - - Document! If your PR is a new feature or a change to behavior, make sure you've updated all associated documentation or have notified the right people to do so. It also helps to add the version of Core against which this documentation is compatible (to avoid confusion with stable versus devel docs, for backwards compatibility, and so on.). + - Document! If your PR is a new feature or a change to behavior, make sure you've updated all associated documentation or have notified the right people to do so. It also helps to add the version of ``ansible-base`` against which this documentation is compatible (to avoid confusion between stable and devel docs, for backwards compatibility, and so on). - Consider scope, sometimes a fix can be generalized - Keep it simple, then things are maintainable, debuggable and intelligible. diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 387f25221fe..7b135580879 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -53,7 +53,7 @@ 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) -- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on.) +- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on) Verifying your documentation PR diff --git a/docs/docsite/rst/community/index.rst b/docs/docsite/rst/community/index.rst index d98fd328eb1..be08228c89a 100644 --- a/docs/docsite/rst/community/index.rst +++ b/docs/docsite/rst/community/index.rst @@ -37,7 +37,7 @@ Going deeper * I need functionality that Ansible does not offer. How do I :ref:`request a feature `? * How do I :ref:`contribute to an Ansible-maintained collection `? * I am waiting for a particular feature. How do I see what is :ref:`planned for future Ansible Releases `? -* I have a specific Ansible interest or expertise (for example, VMware, Linode, and so on.). How do I get involved in a :ref:`working group `? +* I have a specific Ansible interest or expertise (for example, VMware, Linode, and so on). How do I get involved in a :ref:`working group `? * I would like to participate in conversations about features and fixes. How do I review GitHub issues and pull requests? * I found a typo or another problem on docs.ansible.com. How can I :ref:`improve the documentation `? diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index f7ad370266e..c812573a083 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -80,7 +80,7 @@ The ``ansible-doc`` command requires the fully qualified collection name (FQCN) plugins directory ------------------ -Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on, without having to import a role in every play. +Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on without having to import a role in every play. Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins. @@ -565,7 +565,7 @@ Create a PR against the old collection repo to remove the modules, module_utils, Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning: #. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage. - #. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (i.e. 2.0.0, 3.0.0, etc.). + #. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (in other words, 2.0.0, 3.0.0, and so on). Adding the content to the new collection diff --git a/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst b/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst index 8e694cb51ab..862741cd2c6 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst @@ -135,7 +135,7 @@ Modules must output valid JSON only. Follow these guidelines for creating correc * Be consistent about returns (some modules are too random), unless it is detrimental to the state/action. * Make returns reusable--most of the time you don't want to read it, but you do want to process it and re-purpose it. * Return diff if in diff mode. This is not required for all modules, as it won't make sense for certain ones, but please include it when applicable. -* Enable your return values to be serialized as JSON with Python's standard `JSON encoder and decoder `_ library. Basic python types (strings, int, dicts, lists, etc) are serializable. +* Enable your return values to be serialized as JSON with Python's standard `JSON encoder and decoder `_ library. Basic python types (strings, int, dicts, lists, and so on) are serializable. * Do not return an object via exit_json(). Instead, convert the fields you need from the object into the fields of a dictionary and return the dictionary. * Results from many hosts will be aggregated at once, so your module should return only relevant output. Returning the entire contents of a log file is generally bad form. diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index c3f342580d2..ce196e5cfe5 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -104,7 +104,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require :description: * A detailed description (generally two or more sentences). - * Must be written in full sentences, i.e. with capital letters and periods/full stops. + * Must be written in full sentences, in other words, with capital letters and periods/full stops. * Shouldn't mention the module name. * Make use of multiple entries rather than using one long paragraph. * Don't quote complete values unless it is required by YAML. @@ -112,7 +112,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require :version_added: * The version of Ansible when the module was added. - * This is a string, and not a float, i.e. ``version_added: '2.1'`` + * This is a string, and not a float, for example, ``version_added: '2.1'`` :author: @@ -178,8 +178,8 @@ 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, i.e. this is greater than the top level `version_added` field. - * This is a string, and not a float, i.e. ``version_added: '2.3'``. + * 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'``. :suboptions: @@ -367,8 +367,8 @@ 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, i.e. this is greater than the top level `version_added` field. - This is a string, and not a float, i.e. ``version_added: '2.3'``. + 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: complex``, ``type: dict``, or ``type: list``/``elements: dict`` and repeat the elements above for each sub-field. diff --git a/docs/docsite/rst/dev_guide/developing_modules_general_aci.rst b/docs/docsite/rst/dev_guide/developing_modules_general_aci.rst index 63fd1f95e79..97ee2b42a5f 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general_aci.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general_aci.rst @@ -151,13 +151,13 @@ The ``construct_url()`` method takes 2 required arguments: * **self** - passed automatically with the class instance * **root_class** - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``module_object`` keys - + **aci_class**: The name of the class used by the APIC, e.g. ``fvTenant`` + + **aci_class**: The name of the class used by the APIC, for example ``fvTenant`` - + **aci_rn**: The relative name of the object, e.g. ``tn-ACME`` + + **aci_rn**: The relative name of the object, for example ``tn-ACME`` - + **target_filter**: A dictionary with key-value pairs that make up the query string for selecting a subset of entries, e.g. ``{'name': 'ACME'}`` + + **target_filter**: A dictionary with key-value pairs that make up the query string for selecting a subset of entries, for example ``{'name': 'ACME'}`` - + **module_object**: The particular object for this class, e.g. ``ACME`` + + **module_object**: The particular object for this class, for example ``ACME`` Example: @@ -220,7 +220,7 @@ The ``aci.payload()`` method is used to build a dictionary of the proposed objec The ``aci.payload()`` method takes two required arguments and 1 optional argument, depending on if the module manages child objects. -* ``aci_class`` is the APIC name for the object's class, e.g. ``aci_class='fvBD'`` +* ``aci_class`` is the APIC name for the object's class, for example ``aci_class='fvBD'`` * ``class_config`` is the appropriate dictionary to be used as the payload for the POST request + The keys should match the names used by the APIC. 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 f76cbffe947..3dd66c2ed88 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst @@ -141,7 +141,7 @@ To provision the environment as is, run the following: Unlike setting up a single Windows instance with Vagrant, these hosts can also be accessed using the IP address directly as well as through the forwarded ports. It is easier to access it over the host only network adapter as the -normal protocol ports are used, e.g. RDP is still over ``3389``. In cases where +normal protocol ports are used, for example RDP is still over ``3389``. In cases where the host cannot be resolved using the host only network IP, the following protocols can be access over ``127.0.0.1`` using these forwarded ports: @@ -179,8 +179,8 @@ When creating a new module there are a few things to keep in mind: - Ensure the code runs under Powershell v3 and higher on Windows Server 2008 and higher; if higher minimum Powershell or OS versions are required, ensure the documentation reflects this clearly - Ansible runs modules under strictmode version 2.0. Be sure to test with that enabled by putting ``Set-StrictMode -Version 2.0`` at the top of your dev script - Favor native Powershell cmdlets over executable calls if possible -- Use the full cmdlet name instead of aliases, e.g. ``Remove-Item`` over ``rm`` -- Use named parameters with cmdlets, e.g. ``Remove-Item -Path C:\temp`` over ``Remove-Item C:\temp`` +- Use the full cmdlet name instead of aliases, for example ``Remove-Item`` over ``rm`` +- Use named parameters with cmdlets, for example ``Remove-Item -Path C:\temp`` over ``Remove-Item C:\temp`` A very basic Powershell module `win_environment `_ incorporates best practices for Powershell modules. It demonstrates how to implement check-mode and diff-support, and also shows a warning to the user when a specific condition is met. @@ -400,7 +400,7 @@ the various modules that call that util. An example of this would be to have a module util that handles authentication and communication against an API This util can be used by multiple modules to expose a common set of module options like the API endpoint, username, -password, timeout, cert validation, etc, without having to add those options to each module spec. +password, timeout, cert validation, and so on without having to add those options to each module spec. The standard convention for a module util that has a shared argument spec would have 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 bd583cfe3ab..22c60cf9a1d 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -63,7 +63,7 @@ values as :term:`JSON`, and various file operations. .. note:: In Ansible, up to version 2.0.x, the official Python modules used the :ref:`module_replacer` framework. For module authors, :ref:`Ansiballz` is largely a superset of :ref:`module_replacer` functionality, so you usually - do not need to know about one versus the other. + do not need to understand the differences between them. .. _flow_powershell_modules: diff --git a/docs/docsite/rst/dev_guide/index.rst b/docs/docsite/rst/dev_guide/index.rst index e77f0aad6ad..c4aea0a16e2 100644 --- a/docs/docsite/rst/dev_guide/index.rst +++ b/docs/docsite/rst/dev_guide/index.rst @@ -32,7 +32,7 @@ Find the task that best describes what you want to do: * an :ref:`OpenStack module `. * an :ref:`oVirt/RHV module `. * a :ref:`VMware module `. - * I want to :ref:`write a series of related modules ` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, etc.). + * I want to :ref:`write a series of related modules ` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, and so on). * I want to refine my code: diff --git a/docs/docsite/rst/dev_guide/module_lifecycle.rst b/docs/docsite/rst/dev_guide/module_lifecycle.rst index 461ee59e792..1201fffabbf 100644 --- a/docs/docsite/rst/dev_guide/module_lifecycle.rst +++ b/docs/docsite/rst/dev_guide/module_lifecycle.rst @@ -30,7 +30,7 @@ To deprecate a module, 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 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, i.e. ``Use M(whatmoduletouseinstead) instead.``. + :alternative: Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``. * note: with the advent of collections and ``routing.yml`` we might soon require another entry in this file to mark the deprecation. diff --git a/docs/docsite/rst/dev_guide/overview_architecture.rst b/docs/docsite/rst/dev_guide/overview_architecture.rst index 587e1963400..fdd90625b6b 100644 --- a/docs/docsite/rst/dev_guide/overview_architecture.rst +++ b/docs/docsite/rst/dev_guide/overview_architecture.rst @@ -19,7 +19,7 @@ Modules Ansible works by connecting to your nodes and pushing out scripts called "Ansible modules" to them. Most modules accept parameters that describe the desired state of the system. Ansible then executes these modules (over SSH by default), and removes them when finished. Your library of modules can reside on any machine, and there are no servers, daemons, or databases required. -You can :ref:`write your own modules `, though you should first consider :ref:`whether you should `. Typically you'll work with your favorite terminal program, a text editor, and probably a version control system to keep track of changes to your content. You may write specialized modules in any language that can return JSON (Ruby, Python, bash, etc). +You can :ref:`write your own modules `, though you should first consider :ref:`whether you should `. Typically you'll work with your favorite terminal program, a text editor, and probably a version control system to keep track of changes to your content. You may write specialized modules in any language that can return JSON (Ruby, Python, bash, and so on). Module utilities ================ @@ -34,7 +34,7 @@ Plugins Inventory ========= -By default, Ansible represents the machines it manages in a file (INI, YAML, etc.) that puts all of your managed machines in groups of your own choosing. +By default, Ansible represents the machines it manages in a file (INI, YAML, and so on) that puts all of your managed machines in groups of your own choosing. To add new machines, there is no additional SSL signing server involved, so there's never any hassle deciding why a particular machine didn't get linked up due to obscure NTP or DNS issues. diff --git a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst index 94c2fe8b8ea..acce3de4976 100644 --- a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst +++ b/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst @@ -26,7 +26,7 @@ want to implement some functionality that uses a new feature of boto3, it should feature actually needs to be run, with a message stating the missing feature and minimum required version of boto3. -Use feature testing (e.g. ``hasattr('boto3.module', 'shiny_new_method')``) to check whether boto3 +Use feature testing (for example, ``hasattr('boto3.module', 'shiny_new_method')``) to check whether boto3 supports a feature rather than version checking. For example, from the ``ec2`` module: .. code-block:: python @@ -575,7 +575,7 @@ boto3_tag_list_to_ansible_dict Converts a boto3 tag list to an Ansible dict. Boto3 returns tags as a list of dicts containing keys called 'Key' and 'Value' by default. This key names can be overridden when calling the function. For example, if you have already camel_cased your list of tags you may want to pass lowercase key -names instead i.e. 'key' and 'value'. +names instead, in other words, 'key' and 'value'. This function converts the list in to a single dict where the dict key is the tag key and the dict value is the tag value. @@ -611,7 +611,7 @@ is True by default. If purge is False then any existing tags will not be modifi This function is useful when using boto3 'add_tags' and 'remove_tags' functions. Be sure to use the other helper function `boto3_tag_list_to_ansible_dict` to get an appropriate tag dict before -calling this function. Since the AWS APIs are not uniform (e.g. EC2 versus Lambda) this will work +calling this function. Since the AWS APIs are not uniform (for example, EC2 is different from Lambda) this will work without modification for some (Lambda) and others may need modification before using these values (such as EC2, with requires the tags to unset to be in the form `[{'Key': key1}, {'Key': key2}]`). diff --git a/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst b/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst index eade01ec7d9..034aece5409 100644 --- a/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst +++ b/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst @@ -7,7 +7,7 @@ Basic rules Use standard American English ----------------------------- -Ansible uses Standard American English. Watch for common words that are spelled differently in American English (color vs colour, organize vs organise, etc.). +Ansible uses Standard American English. Watch for common words that are spelled differently in American English (color vs colour, organize vs organise, and so on). Write for a global audience --------------------------- @@ -54,7 +54,7 @@ Highlight menu items and commands --------------------------------- When documenting menus or commands, it helps to **bold** what is important. -For menu procedures, bold the menu names, button names, etc to help the user find them on the GUI: +For menu procedures, bold the menu names, button names, and so on to help the user find them on the GUI: 1. On the **File** menu, click **Open**. 2. Type a name in the **User Name** field. 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 c5229db3537..4505e2d0f5c 100644 --- a/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst +++ b/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst @@ -101,7 +101,7 @@ Gender References ~~~~~~~~~~~~~~~~~~ Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." -It is fine to use "you" when giving instructions and "the user," "new users," etc. in more general explanations. +It is fine to use "you" when giving instructions and "the user," "new users," and so on. in more general explanations. Never use "one" in place of "you" when writing technical documentation. Using "one" is far too formal. @@ -137,7 +137,7 @@ In professionally printed material (particularly books, magazines, and newspaper Lists ~~~~~~~ -Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, etc. +Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, and so on. Capitalize the first word of each bullet. Unless it is obvious that it is just a list of items, such as a list of items like: * computer @@ -189,7 +189,7 @@ Use a semicolon to separate items in a series if the items contain commas: - Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner. -Use a semicolon before a conjunctive adverb (however, therefore, otherwise, namely, for example, etc.): +Use a semicolon before a conjunctive adverb (however, therefore, otherwise, namely, for example, and so on): - I think; therefore, I am. Spacing after sentences diff --git a/docs/docsite/rst/dev_guide/testing.rst b/docs/docsite/rst/dev_guide/testing.rst index 68189b16be8..024f59bb9fd 100644 --- a/docs/docsite/rst/dev_guide/testing.rst +++ b/docs/docsite/rst/dev_guide/testing.rst @@ -13,7 +13,7 @@ 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. -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 (e.g., Shippable) 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, Shippable) 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. Read on to learn how Ansible is tested, how to test your contributions locally, and how to extend testing capabilities. @@ -123,7 +123,7 @@ Here's how: sent may have mistakes or malicious code that could have a negative impact on your system. We recommend doing all testing on a virtual machine, whether a cloud instance, or locally. Some users like Vagrant or Docker for this, but they are optional. It is also useful to have virtual machines of different Linux or - other flavors, since some features (apt vs. yum, for example) are specific to those OS versions. + other flavors, since some features (for example, package managers such as apt or yum) are specific to those OS versions. Create a fresh area to work:: diff --git a/docs/docsite/rst/dev_guide/testing_integration.rst b/docs/docsite/rst/dev_guide/testing_integration.rst index d59924937d4..0880e5b1347 100644 --- a/docs/docsite/rst/dev_guide/testing_integration.rst +++ b/docs/docsite/rst/dev_guide/testing_integration.rst @@ -47,7 +47,7 @@ integration_config.yml 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 (e.g. cloud) will only run when access credentials are provided. For more +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. diff --git a/docs/docsite/rst/dev_guide/testing_integration_legacy.rst b/docs/docsite/rst/dev_guide/testing_integration_legacy.rst index dec50a4f4e3..759285e3a49 100644 --- a/docs/docsite/rst/dev_guide/testing_integration_legacy.rst +++ b/docs/docsite/rst/dev_guide/testing_integration_legacy.rst @@ -29,11 +29,11 @@ Over time the above list will be reduced as tests are ported to the ``ansible-te Running Cloud Tests ==================== -Cloud tests exercise capabilities of cloud modules (e.g. ec2_key). These are +Cloud tests exercise capabilities of cloud modules (for example, ec2_key). These are not 'tests run in the cloud' so much as tests that leverage the cloud modules and are organized by cloud provider. -Some AWS tests may use environment variables. It is recommended to either unset any AWS environment variables( such as ``AWS_DEFAULT_PROFILE``, ``AWS_SECRET_ACCESS_KEY``, etc) or be sure that the environment variables match the credentials provided in ``credentials.yml`` to ensure the tests run with consistency to their full capability on the expected account. See `AWS CLI docs `_ for information on creating a profile. +Some AWS tests may use environment variables. It is recommended to either unset any AWS environment variables( such as ``AWS_DEFAULT_PROFILE``, ``AWS_SECRET_ACCESS_KEY``, and so on) or be sure that the environment variables match the credentials provided in ``credentials.yml`` to ensure the tests run with consistency to their full capability on the expected account. See `AWS CLI docs `_ for information on creating a profile. Subsets of tests may be run by ``#commenting`` out unnecessary roles in the appropriate playbook, such as ``test/integration/amazon.yml``. @@ -68,7 +68,7 @@ The testing-iam-policy.json.j2 file contains a policy which can be given to the running the tests to give close to minimum rights required to run the tests. Please note that this does not fully restrict the user; The user has wide privileges for viewing account definitions and is also able to manage some resources that are not related to -testing (e.g. AWS lambdas with different names) primarily due to the limitations of the +testing (for example, AWS lambdas with different names) primarily due to the limitations of the Amazon ARN notation. At the very least the policy limits the user to one region, however tests should not be run in a primary production account in any case. @@ -94,7 +94,7 @@ Run the tests by doing:: cd test/integration/ # TARGET is the name of the test from the list at the top of this page #make TARGET - # e.g. + # for example make amazon # To run all cloud tests you can do: make cloud diff --git a/docs/docsite/rst/dev_guide/testing_validate-modules.rst b/docs/docsite/rst/dev_guide/testing_validate-modules.rst index 5eb3bd0e2aa..044a2c29a49 100644 --- a/docs/docsite/rst/dev_guide/testing_validate-modules.rst +++ b/docs/docsite/rst/dev_guide/testing_validate-modules.rst @@ -95,7 +95,7 @@ Codes invalid-extension Naming Error Official Ansible modules must have a ``.py`` extension for python modules or a ``.ps1`` for powershell modules invalid-module-schema Documentation Error ``AnsibleModule`` schema validation error invalid-requires-extension Naming Error Module ``#AnsibleRequires -CSharpUtil`` should not end in .cs, Module ``#Requires`` should not end in .psm1 - invalid-tagged-version Documentation Error All version numbers specified in code have to be explicitly tagged with the collection name, i.e. ``community.general:1.2.3`` or ``ansible.builtin:2.10`` + invalid-tagged-version Documentation Error All version numbers specified in code have to be explicitly tagged with the collection name, in other words, ``community.general:1.2.3`` or ``ansible.builtin:2.10`` last-line-main-call Syntax Error Call to ``main()`` not the last line (or ``removed_module()`` in the case of deprecated & docs only modules) missing-doc-fragment Documentation Error ``DOCUMENTATION`` fragment missing missing-existing-doc-fragment Documentation Warning Pre-existing ``DOCUMENTATION`` fragment missing diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 8a55bb46cc2..7e208ecde34 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -83,7 +83,7 @@ Which Ansible version to install is based on your particular needs. You can choo Ansible creates new releases two to three times a year. Due to this short release cycle, -minor bugs will generally be fixed in the next release versus maintaining backports on the stable branch. +minor bugs will generally be fixed in the next release rather than maintaining backports on the stable branch. Major bugs will still have maintenance releases when needed, though these are infrequent. @@ -143,7 +143,7 @@ To configure the PPA on your machine and install Ansible run these commands: $ sudo apt-add-repository --yes --update ppa:ansible/ansible $ sudo apt install ansible -.. note:: On older Ubuntu distributions, "software-properties-common" is called "python-software-properties". You may want to use ``apt-get`` instead of ``apt`` in older versions. Also, be aware that only newer distributions (i.e. 18.04, 18.10, etc.) have a ``-u`` or ``--update`` flag, so adjust your script accordingly. +.. note:: On older Ubuntu distributions, "software-properties-common" is called "python-software-properties". You may want to use ``apt-get`` instead of ``apt`` in older versions. Also, be aware that only newer distributions (in other words, 18.04, 18.10, and so on) have a ``-u`` or ``--update`` flag, so adjust your script accordingly. Debian/Ubuntu packages can also be built from the source checkout, run: @@ -210,7 +210,7 @@ You may also wish to install from ports, run: $ sudo make -C /usr/ports/sysutils/ansible install -You can also choose a specific version, i.e ``ansible25``. +You can also choose a specific version, for example ``ansible25``. Older versions of FreeBSD worked with something like this (substitute for your choice of package manager): 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 3b067cbdf7c..e19067a3150 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 @@ -12,7 +12,7 @@ Developing network resource modules Understanding network and security resource modules =================================================== -Network and security devices separate configuration into sections (such as interfaces, VLANs, and so on) that apply to a network or security service. Ansible resource modules take advantage of this to allow users to configure subsections or resources within the device configuration. Resource modules provide a consistent experience across different network and security devices. For example, a network resource module may only update the configuration for a specific portion of the network interfaces, VLANs, ACLs, and so on, for a network device. The resource module: +Network and security devices separate configuration into sections (such as interfaces, VLANs, and so on) that apply to a network or security service. Ansible resource modules take advantage of this to allow users to configure subsections or resources within the device configuration. Resource modules provide a consistent experience across different network and security devices. For example, a network resource module may only update the configuration for a specific portion of the network interfaces, VLANs, ACLs, and so on for a network device. The resource module: #. Fetches a piece of the configuration (fact gathering), for example, the interfaces configuration. #. Converts the returned configuration into key-value pairs. 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 479594286f4..97f671bb2ae 100644 --- a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst +++ b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst @@ -691,7 +691,7 @@ Example ssh config file (~/.ssh/config) # Note: Due to the way that Paramiko reads the SSH Config file, # you need to specify the NETCONF port that the host uses. - # i.e. It does not automatically use ansible_port + # In other words, it does not automatically use ansible_port # As a result you need either: Host junos01 diff --git a/docs/docsite/rst/plugins/become.rst b/docs/docsite/rst/plugins/become.rst index c4bbb7e8c6f..c710bcf660a 100644 --- a/docs/docsite/rst/plugins/become.rst +++ b/docs/docsite/rst/plugins/become.rst @@ -13,7 +13,7 @@ Become plugins work to ensure that Ansible can use certain privilege escalation commands to work with the target machine as well as the modules required to execute the tasks specified in the play. -These utilities (``sudo``, ``su``, ``doas``, etc) generally let you 'become' another user to execute a command +These utilities (``sudo``, ``su``, ``doas``, and so on) generally let you 'become' another user to execute a command with the permissions of that user. diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst index f49c8265d41..a34796bb2ae 100644 --- a/docs/docsite/rst/plugins/inventory.rst +++ b/docs/docsite/rst/plugins/inventory.rst @@ -64,7 +64,7 @@ After providing any required options, you can view the populated inventory with If you are using an inventory plugin in a playbook-adjacent collection and want to test your setup with ``ansible-inventory``, you will need to use the ``--playbook-dir`` flag. -Your inventory source might be a directory of inventory configuration files. The constructed inventory plugin only operates on those hosts already in inventory, so you may want the constructed inventory configuration parsed at a particular point (such as last). Ansible parses the directory recursively, alphabetically. You cannot configure the parsing approach, so name your files to make it work predictably. Inventory plugins that extend constructed features directly can work around that restriction by adding constructed options in addition to the inventory plugin options. Otherwise, you can use ``-i`` with multiple sources to impose a specific order, e.g. ``-i demo.aws_ec2.yml -i clouds.yml -i constructed.yml``. +Your inventory source might be a directory of inventory configuration files. The constructed inventory plugin only operates on those hosts already in inventory, so you may want the constructed inventory configuration parsed at a particular point (such as last). Ansible parses the directory recursively, alphabetically. You cannot configure the parsing approach, so name your files to make it work predictably. Inventory plugins that extend constructed features directly can work around that restriction by adding constructed options in addition to the inventory plugin options. Otherwise, you can use ``-i`` with multiple sources to impose a specific order, for example ``-i demo.aws_ec2.yml -i clouds.yml -i constructed.yml``. You can create dynamic groups using host variables with the constructed ``keyed_groups`` option. The option ``groups`` can also be used to create groups and ``compose`` creates and modifies host variables. Here is an aws_ec2 example utilizing constructed features: @@ -105,7 +105,7 @@ Now the output of ``ansible-inventory -i demo.aws_ec2.yml --graph``: | |--ec2-12-345-678-901.compute-1.amazonaws.com |--@ungrouped -If a host does not have the variables in the configuration above (i.e. ``tags.Name``, ``tags``, ``private_ip_address``), the host will not be added to groups other than those that the inventory plugin creates and the ``ansible_host`` host variable will not be modified. +If a host does not have the variables in the configuration above (in other words, ``tags.Name``, ``tags``, ``private_ip_address``), the host will not be added to groups other than those that the inventory plugin creates and the ``ansible_host`` host variable will not be modified. Inventory plugins that support caching can use the general settings for the fact cache defined in the ``ansible.cfg`` file's ``[defaults]`` section or define inventory-specific settings in the ``[inventory]`` section. Individual plugins can define plugin-specific cache settings in their config file: diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst index 95e1fccf410..697bb87a862 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst @@ -288,15 +288,15 @@ Since the ansible-2.0 plugin system is more advanced, it is easier to adapt your You may find the following tips useful: -* Check whether the ansible-2.0 class(es) are available and if they are missing (ansible-1.9.x) mimic them with the needed methods (e.g. ``__init__``) +* Check whether the ansible-2.0 class(es) are available and if they are missing (ansible-1.9.x) mimic them with the needed methods (for example, ``__init__``) -* When ansible-2.0 python modules are imported, and they fail (ansible-1.9.x), catch the ``ImportError`` exception and perform the equivalent imports for ansible-1.9.x. With possible translations (e.g. importing specific methods). +* When ansible-2.0 python modules are imported, and they fail (ansible-1.9.x), catch the ``ImportError`` exception and perform the equivalent imports for ansible-1.9.x. With possible translations (for example, importing specific methods). * Use the existence of these methods as a qualifier to what version of Ansible you are running. So rather than using version checks, you can do capability checks instead. (See examples below) * Document for each if-then-else case for which specific version each block is needed. This will help others to understand how they have to adapt their plugins, but it will also help you to remove the older ansible-1.9.x support when it is deprecated. -* When doing plugin development, it is very useful to have the ``warning()`` method during development, but it is also important to emit warnings for deadends (cases that you expect should never be triggered) or corner cases (e.g. cases where you expect misconfigurations). +* When doing plugin development, it is very useful to have the ``warning()`` method during development, but it is also important to emit warnings for deadends (cases that you expect should never be triggered) or corner cases (for example, cases where you expect misconfigurations). * It helps to look at other plugins in ansible-1.9.x and ansible-2.0 to understand how the API works and what modules, classes and methods are available. diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst index 65fbe5511d2..e5b99a52eaa 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst @@ -20,7 +20,7 @@ Playbook Dynamic includes and attribute inheritance ------------------------------------------ -In Ansible version 2.4, the concept of dynamic includes (``include_tasks``) versus static imports (``import_tasks``) was introduced to clearly define the differences in how ``include`` works between dynamic and static includes. +In Ansible version 2.4, the concept of dynamic includes (``include_tasks``), as opposed to static imports (``import_tasks``), was introduced to clearly define the differences in how ``include`` works between dynamic and static includes. All attributes applied to a dynamic ``include_*`` would only apply to the include itself, while attributes applied to a static ``import_*`` would be inherited by the tasks within. diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst index 1347eb61860..4c7904da6d4 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst @@ -246,7 +246,7 @@ best solution is to explicitly set ``ansible_python_interpreter`` to the path of the correct interpreter for those target systems. You can still set ``ansible_python_interpreter`` to a specific path at any -variable level (as a host variable, in vars files, in playbooks, etc.). +variable level (as a host variable, in vars files, in playbooks, and so on). If you prefer to use the Python interpreter discovery behavior, use one of the four new values for ``ansible_python_interpreter`` introduced in Ansible 2.8: @@ -286,7 +286,7 @@ use the discovered Python, regardless of whether :command:`/usr/bin/python` exis :literal:`auto_legacy` setting provides compatibility with previous versions of Ansible that always defaulted to :command:`/usr/bin/python`. -If you installed Python and dependencies (``boto``, etc.) to +If you installed Python and dependencies (``boto``, and so on) to :command:`/usr/bin/python` as a workaround on distros with a different default Python interpreter (for example, Ubuntu 16.04+, RHEL8, Fedora 23+), you have two options: diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.9.rst b/docs/docsite/rst/porting_guides/porting_guide_2.9.rst index 049fd3079d8..ec1096497cc 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.9.rst @@ -704,7 +704,7 @@ Noteworthy module changes * The deprecated ``force`` option in ``win_firewall_rule`` has been removed. * :ref:`openssl_certificate `'s ``ownca`` provider creates authority key identifiers if not explicitly disabled with ``ownca_create_authority_key_identifier: no``. This is only the case for the ``cryptography`` backend, which is selected by default if the ``cryptography`` library is available. * :ref:`openssl_certificate `'s ``ownca`` and ``selfsigned`` providers create subject key identifiers if not explicitly disabled with ``ownca_create_subject_key_identifier: never_create`` resp. ``selfsigned_create_subject_key_identifier: never_create``. If a subject key identifier is provided by the CSR, it is taken; if not, it is created from the public key. This is only the case for the ``cryptography`` backend, which is selected by default if the ``cryptography`` library is available. -* :ref:`openssh_keypair ` now applies the same file permissions and ownership to both public and private keys (both get the same ``mode``, ``owner``, ``group``, etc.). If you need to change permissions / ownership on one key, use the :ref:`file ` to modify it after it is created. +* :ref:`openssh_keypair ` now applies the same file permissions and ownership to both public and private keys (both get the same ``mode``, ``owner``, ``group``, and so on). If you need to change permissions / ownership on one key, use the :ref:`file ` to modify it after it is created. Plugins diff --git a/docs/docsite/rst/reference_appendices/common_return_values.rst b/docs/docsite/rst/reference_appendices/common_return_values.rst index 5dfa8a72c12..e24a30c418e 100644 --- a/docs/docsite/rst/reference_appendices/common_return_values.rst +++ b/docs/docsite/rst/reference_appendices/common_return_values.rst @@ -102,7 +102,7 @@ A string with a generic message relayed to the user. rc `` -Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains 'return code' of these utilities. +Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains 'return code' of these utilities. .. code-block:: console @@ -181,7 +181,7 @@ A boolean that indicates if the task was skipped or not stderr `````` -Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains the error output of these utilities. +Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains the error output of these utilities. .. code-block:: console @@ -199,7 +199,7 @@ When `stderr` is returned we also always provide this field which is a list of s stdout `````` -Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc). This field contains the normal output of these utilities. +Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on). This field contains the normal output of these utilities. .. code-block:: console diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index c544a8d8e02..d6d99eae4f3 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -150,7 +150,7 @@ requires Python 2, you can also report a bug on our `bug tracker Do not replace the shebang lines of your python modules. Ansible will do this for you automatically at deploy time. -Also, this works for ANY interpreter, i.e ruby: ``ansible_ruby_interpreter``, perl: ``ansible_perl_interpreter``, etc, +Also, this works for ANY interpreter, for example ruby: ``ansible_ruby_interpreter``, perl: ``ansible_perl_interpreter``, and so on, 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 ``), @@ -515,7 +515,7 @@ The ``mkpasswd`` utility that is available on most Linux systems is also a great mkpasswd --method=sha-512 -If this utility is not installed on your system (e.g. you are using macOS) then you can still easily +If this utility is not installed on your system (for example, you are using macOS) then you can still easily generate these passwords using Python. First, ensure that the `Passlib `_ password hashing library is installed: @@ -608,8 +608,8 @@ We also offer free web-based training classes on a regular basis. See our .. _web_interface: -Is there a web interface / REST API / etc? -++++++++++++++++++++++++++++++++++++++++++ +Is there a web interface / REST API / GUI? +++++++++++++++++++++++++++++++++++++++++++++ Yes! Ansible, Inc makes a great product that makes Ansible even more powerful and easy to use. See :ref:`ansible_tower`. @@ -692,7 +692,7 @@ but you can still access the original via ``hostvars``:: original_host: "{{ hostvars[inventory_hostname]['ansible_host'] }}" -This works for all overridden connection variables, like ``ansible_user``, ``ansible_port``, etc. +This works for all overridden connection variables, like ``ansible_user``, ``ansible_port``, and so on. .. _scp_protocol_error_filename: diff --git a/docs/docsite/rst/reference_appendices/glossary.rst b/docs/docsite/rst/reference_appendices/glossary.rst index 1e83a69ba3d..6b36a7ead69 100644 --- a/docs/docsite/rst/reference_appendices/glossary.rst +++ b/docs/docsite/rst/reference_appendices/glossary.rst @@ -256,7 +256,7 @@ when a term comes up on the mailing list. Lookup Plugin A lookup plugin is a way to get data into Ansible from the outside world. - Lookup plugins are an extension of Jinja2 and can be accessed in templates, e.g., + Lookup plugins are an extension of Jinja2 and can be accessed in templates, for example, ``{{ lookup('file','/path/to/file') }}``. These are how such things as ``with_items``, are implemented. There are also lookup plugins like ``file`` which loads data from @@ -307,7 +307,7 @@ when a term comes up on the mailing list. things. Ansible uses it as a conductor would conduct an orchestra. A datacenter or cloud architecture is full of many systems, playing many parts -- web servers, database servers, maybe load balancers, - monitoring systems, continuous integration systems, etc. In + monitoring systems, continuous integration systems, and so on. In performing any process, it is necessary to touch systems in particular orders, often to simulate rolling updates or to deploy software correctly. Some system may perform some steps, then others, then @@ -381,7 +381,7 @@ when a term comes up on the mailing list. Roles Roles are units of organization in Ansible. Assigning a role to a group of :term:`hosts ` (or a set of :term:`groups `, - or :term:`host patterns `, etc.) implies that they should + or :term:`host patterns `, and so on) implies that they should implement a specific behavior. A role may include applying certain variable values, certain :term:`tasks`, and certain :term:`handlers` -- or just one or more of these things. Because of the file structure @@ -419,7 +419,7 @@ when a term comes up on the mailing list. Native OpenSSH as an Ansible transport is specified with ``-c ssh`` (or a config file, or a directive in the :term:`playbook `) and can be useful if wanting to login via Kerberized SSH or using SSH - jump hosts, etc. In 1.2.1, ``ssh`` will be used by default if the + jump hosts, and so on. In 1.2.1, ``ssh`` will be used by default if the OpenSSH binary on the control machine is sufficiently new. Previously, Ansible selected ``paramiko`` as a default. Using a client that supports ``ControlMaster`` and ``ControlPersist`` is @@ -485,7 +485,7 @@ when a term comes up on the mailing list. usage of YAML stemmed from Michael DeHaan's first use of it inside of Cobbler around 2006. YAML is fairly popular in the dynamic language community and the format has libraries available for serialization in - many languages (Python, Perl, Ruby, etc.). + many languages (Python, Perl, Ruby, and so on). .. seealso:: diff --git a/docs/docsite/rst/reference_appendices/interpreter_discovery.rst b/docs/docsite/rst/reference_appendices/interpreter_discovery.rst index 81a823778e1..9fa7d585151 100644 --- a/docs/docsite/rst/reference_appendices/interpreter_discovery.rst +++ b/docs/docsite/rst/reference_appendices/interpreter_discovery.rst @@ -47,5 +47,5 @@ auto_silent Same as ``auto``, but does not issue warnings. 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, etc.). +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. diff --git a/docs/docsite/rst/reference_appendices/special_variables.rst b/docs/docsite/rst/reference_appendices/special_variables.rst index 7b4fbf818e9..e4ecc1778ab 100644 --- a/docs/docsite/rst/reference_appendices/special_variables.rst +++ b/docs/docsite/rst/reference_appendices/special_variables.rst @@ -38,13 +38,13 @@ 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 (i.e. the role that included/imported this role) being the first item in the list. - When multiple inclusions occur, this list lists the *last* role (i.e. 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. + 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. For example: When role **A** includes role **B**, inside role B, ``ansible_parent_role_names`` will equal to ``['A']``. If role **B** then includes role **C**, the list becomes ``['B', 'A']``. ansible_parent_role_paths - When the current role is being executed by means of an :ref:`include_role ` or :ref:`import_role ` action, this variable contains a list of all parent roles, with the most recent role (i.e. the role that included/imported this role) being the first item in the list. + 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. Please refer to ``ansible_parent_role_names`` for the order of items in this list. ansible_play_batch @@ -77,7 +77,7 @@ ansible_run_tags Contents of the ``--tags`` CLI option, which specifies which tags will be included for the current run. ansible_search_path - Current search path for action plugins and lookups, i.e where we search for relative paths when you do ``template: src=myfile`` + Current search path for action plugins and lookups, in other words, where we search for relative paths when you do ``template: src=myfile`` ansible_skip_tags Contents of the ``--skip-tags`` CLI option, which specifies which tags will be skipped for the current run. @@ -110,7 +110,7 @@ inventory_file The file name of the inventory source in which the `inventory_hostname` was first defined omit - Special variable that allows you to 'omit' an option in a task, i.e ``- user: name=bob home={{ bobs_home|default(omit) }}`` + Special variable that allows you to 'omit' an option in a task, for example ``- user: name=bob home={{ bobs_home|default(omit) }}`` play_hosts Deprecated, the same as ansible_play_batch diff --git a/docs/docsite/rst/roadmap/ROADMAP_2_5.rst b/docs/docsite/rst/roadmap/ROADMAP_2_5.rst index a9c36266926..34d376ce47a 100644 --- a/docs/docsite/rst/roadmap/ROADMAP_2_5.rst +++ b/docs/docsite/rst/roadmap/ROADMAP_2_5.rst @@ -97,7 +97,7 @@ AWS - ec2_instance - ec2_vpc: Allow the addition of secondary IPv4 CIDRS to existing VPCs. - - AWS Network Load Balancer support (NLB module, ASG support, etc) + - AWS Network Load Balancer support (NLB module, ASG support, and so on) - rds_instance Azure diff --git a/docs/docsite/rst/roadmap/ansible_base_roadmap_index.rst b/docs/docsite/rst/roadmap/ansible_base_roadmap_index.rst new file mode 100644 index 00000000000..4cf7740ccbb --- /dev/null +++ b/docs/docsite/rst/roadmap/ansible_base_roadmap_index.rst @@ -0,0 +1,27 @@ +.. _ansible_base_roadmaps: + +ansible-base Roadmap +===================== + +The ``ansible-base`` team develops a roadmap for each major and minor ``ansible-base`` release. The latest roadmap shows current work; older roadmaps provide a history of the project. We don't publish roadmaps for subminor versions. So 2.10 and 2.11 have roadmaps, but 2.10.1 does not. + +We incorporate team and community feedback in each roadmap, and aim for further transparency and better inclusion of both community desires and submissions. + +Each roadmap offers a *best guess*, based on the ``ansible-base`` team's experience and on requests and feedback from the community, of what will be included in a given release. However, some items on the roadmap may be dropped due to time constraints, lack of community maintainers, and so on. + +Each roadmap is published both as an idea of what is upcoming in ``ansible-base``, and as a medium for seeking further feedback from the community. + +You can submit feedback on the current roadmap in multiple ways: + +- Edit the agenda of an IRC `Core Team Meeting `_ (preferred) +- Post on the ``#ansible-devel`` Freenode IRC channel +- Email the ansible-devel list + +See :ref:`Ansible communication channels ` for details on how to join and use the email lists and IRC channels. + +.. toctree:: + :maxdepth: 1 + :glob: + :caption: ansible-base Roadmaps + + ROADMAP_2_10 diff --git a/docs/docsite/rst/roadmap/ansible_roadmap_index.rst b/docs/docsite/rst/roadmap/ansible_roadmap_index.rst new file mode 100644 index 00000000000..d350023bfe4 --- /dev/null +++ b/docs/docsite/rst/roadmap/ansible_roadmap_index.rst @@ -0,0 +1,26 @@ +.. _ansible_roadmaps: + +Ansible Roadmap +=============== + +The Ansible team develops a roadmap for each major and minor Ansible release. The latest roadmap shows current work; older roadmaps provide a history of the project. We don't publish roadmaps for subminor versions. So 2.10 and 2.11 have roadmaps, but 2.10.1 does not. + +We incorporate team and community feedback in each roadmap, and aim for further transparency and better inclusion of both community desires and submissions. + +Each roadmap offers a *best guess*, based on the Ansible team's experience and on requests and feedback from the community, of what will be included in a given release. However, some items on the roadmap may be dropped due to time constraints, lack of community maintainers, and so on. + +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: + +- Edit the agenda of an IRC `Ansible Community Meeting `_ (preferred) +- Post on the ``#ansible-community`` Freenode IRC channel + +See :ref:`Ansible communication channels ` for details on how to join and use the IRC channels. + +.. toctree:: + :maxdepth: 1 + :glob: + :caption: Ansible Release Roadmaps + + COLLECTIONS_2_10 diff --git a/docs/docsite/rst/roadmap/index.rst b/docs/docsite/rst/roadmap/index.rst index 9abc1b532af..d1e248b0702 100644 --- a/docs/docsite/rst/roadmap/index.rst +++ b/docs/docsite/rst/roadmap/index.rst @@ -22,12 +22,8 @@ See :ref:`Ansible communication channels ` for details on how to .. toctree:: :maxdepth: 1 :glob: - :caption: Ansible Release Roadmaps + :caption: Ansible Roadmaps - COLLECTIONS_2_10 - ROADMAP_2_10 - ROADMAP_2_9 - ROADMAP_2_8 - ROADMAP_2_7 - ROADMAP_2_6 - ROADMAP_2_5 + ansible_base_roadmap_index + ansible_roadmap_index + old_roadmap_index diff --git a/docs/docsite/rst/roadmap/old_roadmap_index.rst b/docs/docsite/rst/roadmap/old_roadmap_index.rst new file mode 100644 index 00000000000..78769f17584 --- /dev/null +++ b/docs/docsite/rst/roadmap/old_roadmap_index.rst @@ -0,0 +1,19 @@ +.. _old_roadmaps: + +Older Roadmaps +=============== + +Older roadmaps are listed here to provide a history of the Ansible project. + +See :ref:`roadmaps` to find current Ansible and ``ansible-base`` roadmaps. + +.. toctree:: + :maxdepth: 1 + :glob: + :caption: Older Roadmaps + + ROADMAP_2_9 + ROADMAP_2_8 + ROADMAP_2_7 + ROADMAP_2_6 + ROADMAP_2_5 diff --git a/docs/docsite/rst/scenario_guides/guide_aci.rst b/docs/docsite/rst/scenario_guides/guide_aci.rst index f252dad7962..5fe4c648a50 100644 --- a/docs/docsite/rst/scenario_guides/guide_aci.rst +++ b/docs/docsite/rst/scenario_guides/guide_aci.rst @@ -591,7 +591,7 @@ 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 (e.g. 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. + 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 @@ -619,7 +619,7 @@ All below issues either have been reported to the vendor, and most can simply be 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 (e.g. ``register: this``) and influence when the task should report a change by adding: ``changed_when: this.imdata != []``. + **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 `_) diff --git a/docs/docsite/rst/scenario_guides/guide_azure.rst b/docs/docsite/rst/scenario_guides/guide_azure.rst index 7a3ac728f42..2317ade4a35 100644 --- a/docs/docsite/rst/scenario_guides/guide_azure.rst +++ b/docs/docsite/rst/scenario_guides/guide_azure.rst @@ -45,7 +45,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 (e.g. ABCDEFGH-1234-ABCD-1234-ABCDEFGHIJKL) pointing to the AD containing your +* And finally, a tenant ID. It's 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. @@ -364,7 +364,7 @@ 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 (i.e. 'azure_rm') with a '.ini' +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. diff --git a/docs/docsite/rst/scenario_guides/guide_cloudstack.rst b/docs/docsite/rst/scenario_guides/guide_cloudstack.rst index 38f0eb2c8aa..fcfb8120a10 100644 --- a/docs/docsite/rst/scenario_guides/guide_cloudstack.rst +++ b/docs/docsite/rst/scenario_guides/guide_cloudstack.rst @@ -27,7 +27,7 @@ Or alternatively starting with Debian 9 and Ubuntu 16.04: $ sudo apt install python-cs -.. note:: cs also includes a command line interface for ad-hoc interaction with the CloudStack API e.g. ``$ cs listVirtualMachines state=Running``. +.. 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 ```````````````````````````` @@ -58,7 +58,7 @@ The structure of the ini file must look like this: .. versionadded:: 2.4 -The ENV variables support ``CLOUDSTACK_*`` as written in the documentation of the library ``cs``, like e.g ``CLOUDSTACK_TIMEOUT``, ``CLOUDSTACK_METHOD``, etc. has been implemented into Ansible. It is even possible to have some incomplete config in your cloudstack.ini: +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 @@ -84,7 +84,7 @@ and fulfill the missing data by either setting ENV variables or tasks params: Regions ``````` -If you use more than one CloudStack region, you can define as many sections as you want and name them as you like, e.g.: +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 @@ -163,7 +163,7 @@ Below you see an example how it can be used in combination with Ansible's block CLOUDSTACK_PROJECT: web-app CLOUDSTACK_ZONE: sf-1 -.. Note:: You are still able overwrite the environment variables using the module arguments, e.g. ``zone: sf-2`` +.. 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``. @@ -275,7 +275,7 @@ 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, e.g. ``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. +.. 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ diff --git a/docs/docsite/rst/scenario_guides/guide_docker.rst b/docs/docsite/rst/scenario_guides/guide_docker.rst index a237b2e6c0f..9c992a17329 100644 --- a/docs/docsite/rst/scenario_guides/guide_docker.rst +++ b/docs/docsite/rst/scenario_guides/guide_docker.rst @@ -262,7 +262,7 @@ Configuration File Using a configuration file provides a means for defining a set of Docker APIs from which to build an inventory. The default name of the file is derived from the name of the inventory script. By default the script will look for -basename of the script (i.e. docker) with an extension of '.yml'. +basename of the script (in other words, docker) with an extension of '.yml'. You can also override the default name of the script by defining DOCKER_CONFIG_FILE in the environment. diff --git a/docs/docsite/rst/scenario_guides/guide_packet.rst b/docs/docsite/rst/scenario_guides/guide_packet.rst index 74793c579bd..99e9513f6e3 100644 --- a/docs/docsite/rst/scenario_guides/guide_packet.rst +++ b/docs/docsite/rst/scenario_guides/guide_packet.rst @@ -87,7 +87,7 @@ The 'device_ids' and 'hostnames' parameters are mutually exclusive. The followin - 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; i.e. ``hostnames: "mydev%d", count: 2`` will expand to [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: diff --git a/docs/docsite/rst/scenario_guides/guide_rax.rst b/docs/docsite/rst/scenario_guides/guide_rax.rst index 19a6dba80de..b6100b8b9ff 100644 --- a/docs/docsite/rst/scenario_guides/guide_rax.rst +++ b/docs/docsite/rst/scenario_guides/guide_rax.rst @@ -154,7 +154,7 @@ to the next section. 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 via other tools, including the Rackspace Cloud user interface. The inventory plugin can be used to group resources by metadata, region, OS, etc. 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. +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 via 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. diff --git a/docs/docsite/rst/scenario_guides/guide_scaleway.rst b/docs/docsite/rst/scenario_guides/guide_scaleway.rst index d579f8fab3b..77af9ba7274 100644 --- a/docs/docsite/rst/scenario_guides/guide_scaleway.rst +++ b/docs/docsite/rst/scenario_guides/guide_scaleway.rst @@ -246,7 +246,7 @@ This means that for each tag that exists on your Scaleway compute nodes, a group Scaleway S3 object storage ========================== -`Object Storage `_ allows you to store any kind of objects (documents, images, videos, etc.). +`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 `_. diff --git a/docs/docsite/rst/scenario_guides/guide_vultr.rst b/docs/docsite/rst/scenario_guides/guide_vultr.rst index 5bd45460663..c5d5adeca7d 100644 --- a/docs/docsite/rst/scenario_guides/guide_vultr.rst +++ b/docs/docsite/rst/scenario_guides/guide_vultr.rst @@ -164,7 +164,7 @@ Run all Vultr tests: $ ansible-test integration cloud/vultr/ -v --diff --allow-unsupported -To run a specific test, e.g. vultr_account_info: +To run a specific test, for example vultr_account_info: .. code-block:: shell diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_vm_attributes.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_vm_attributes.rst index 1e3dd8f2d9e..089c13d7e55 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_vm_attributes.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_inventory_vm_attributes.rst @@ -545,7 +545,7 @@ Detailed information about the files that comprise the virtual machine. file (vim.vm.FileLayoutEx.FileInfo, optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Information about all the files that constitute the virtual machine including configuration files, disks, swap file, suspend file, log files, core files, memory file etc. + Information about all the files that constitute the virtual machine including configuration files, disks, swap file, suspend file, log files, core files, memory file and so on. disk (vim.vm.FileLayoutEx.DiskLayout, optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/docsite/rst/user_guide/become.rst b/docs/docsite/rst/user_guide/become.rst index 0c6fc0781be..fed806bb738 100644 --- a/docs/docsite/rst/user_guide/become.rst +++ b/docs/docsite/rst/user_guide/become.rst @@ -180,7 +180,7 @@ Not supported by all connection plugins Privilege escalation methods must also be supported by the connection plugin used. Most connection plugins will warn if they do not support become. Some -will just ignore it as they always run as root (jail, chroot, etc). +will just ignore it as they always run as root (jail, chroot, and so on). Only one method may be enabled per host --------------------------------------- diff --git a/docs/docsite/rst/user_guide/collections_using.rst b/docs/docsite/rst/user_guide/collections_using.rst index 36913532583..5aa616eac31 100644 --- a/docs/docsite/rst/user_guide/collections_using.rst +++ b/docs/docsite/rst/user_guide/collections_using.rst @@ -310,7 +310,7 @@ In a playbook, you can control the collections Ansible searches for modules and - 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 (e.g., lookups, filters, tests). +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). .. seealso:: diff --git a/docs/docsite/rst/user_guide/complex_data_manipulation.rst b/docs/docsite/rst/user_guide/complex_data_manipulation.rst index b9900b50105..5aa230adaeb 100644 --- a/docs/docsite/rst/user_guide/complex_data_manipulation.rst +++ b/docs/docsite/rst/user_guide/complex_data_manipulation.rst @@ -18,7 +18,7 @@ Let's start with a quick definition of each type of plugin: Loops and list comprehensions ============================= -Most programming languages have loops (``for``, ``while``, etc.) and list comprehensions to do transformations on lists including lists of objects. Jinja2 has a few filters that provide this functionality: ``map``, ``select``, ``reject``, ``selectattr``, ``rejectattr``. +Most programming languages have loops (``for``, ``while``, and so on) and list comprehensions to do transformations on lists including lists of objects. Jinja2 has a few filters that provide this functionality: ``map``, ``select``, ``reject``, ``selectattr``, ``rejectattr``. - map: this is a basic for loop that just allows you to change every item in a list, using the 'attribute' keyword you can do the transformation based on attributes of the list elements. - select/reject: this is a for loop with a condition, that allows you to create a subset of a list that matches (or not) based on the result of the condition. @@ -141,7 +141,7 @@ Another way is to avoid adding elements to the list in the first place, so you c Complex Type transformations ============================= -Jinja provides filters for simple data type transformations (``int``, ``bool``, etc), but when you want to transform data structures things are not as easy. +Jinja provides filters for simple data type transformations (``int``, ``bool``, and so on), but when you want to transform data structures things are not as easy. You can use loops and list comprehensions as shown above to help, also other filters and lookups can be chained and leveraged to achieve more complex transformations. @@ -150,7 +150,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 etc.) 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 (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. These example produces ``{"a": "b", "c": "d"}`` diff --git a/docs/docsite/rst/user_guide/connection_details.rst b/docs/docsite/rst/user_guide/connection_details.rst index db2319a34d0..60f93cadba2 100644 --- a/docs/docsite/rst/user_guide/connection_details.rst +++ b/docs/docsite/rst/user_guide/connection_details.rst @@ -50,7 +50,7 @@ or as a group variable in inventory: Setting up SSH keys ------------------- -By default, Ansible assumes you are using SSH keys to connect to remote machines. SSH keys are encouraged, but you can use password authentication if needed with the ``--ask-pass`` option. If you need to provide a password for :ref:`privilege escalation ` (sudo, pbrun, etc.), use ``--ask-become-pass``. +By default, Ansible assumes you are using SSH keys to connect to remote machines. SSH keys are encouraged, but you can use password authentication if needed with the ``--ask-pass`` option. If you need to provide a password for :ref:`privilege escalation ` (sudo, pbrun, and so on), use ``--ask-become-pass``. .. include:: shared_snippets/SSH_password_prompt.txt diff --git a/docs/docsite/rst/user_guide/guide_rolling_upgrade.rst b/docs/docsite/rst/user_guide/guide_rolling_upgrade.rst index aff130b74b9..6f2ca7423c8 100644 --- a/docs/docsite/rst/user_guide/guide_rolling_upgrade.rst +++ b/docs/docsite/rst/user_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, etc. 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's a useful trick to know. The next part is the update play. The first part looks like this: diff --git a/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst b/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst index 75b80bea15a..aea7a0ca3e1 100644 --- a/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst +++ b/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst @@ -28,7 +28,7 @@ Ansible integrates seamlessly with `Cobbler `_, a Lin While primarily used to kickoff OS installations and manage DHCP and DNS, Cobbler has a generic layer that can represent data for multiple configuration management systems (even at the same time) and serve as a 'lightweight CMDB'. -To tie your Ansible inventory to Cobbler, copy `this script `_ to ``/etc/ansible`` and ``chmod +x`` the file. Run ``cobblerd`` any time you use Ansible and use the ``-i`` command line option (e.g. ``-i /etc/ansible/cobbler.py``) to communicate with Cobbler using Cobbler's XMLRPC API. +To tie your Ansible inventory to Cobbler, copy `this script `_ to ``/etc/ansible`` and ``chmod +x`` the file. Run ``cobblerd`` any time you use Ansible and use the ``-i`` command line option (for example, ``-i /etc/ansible/cobbler.py``) to communicate with Cobbler using Cobbler's XMLRPC API. Add a ``cobbler.ini`` file in ``/etc/ansible`` so Ansible knows where the Cobbler server is and some cache improvements can be used. For example: @@ -104,7 +104,7 @@ And technically, though there is no major good reason to do it, this also works ansible webserver -m shell -a "echo {{ a }}" -So in other words, you can use those variables in arguments/actions as well. +So, in other words, you can use those variables in arguments/actions as well. .. _openstack_example: diff --git a/docs/docsite/rst/user_guide/intro_inventory.rst b/docs/docsite/rst/user_guide/intro_inventory.rst index 87b99b6cd4e..fd83248d037 100644 --- a/docs/docsite/rst/user_guide/intro_inventory.rst +++ b/docs/docsite/rst/user_guide/intro_inventory.rst @@ -7,7 +7,7 @@ How to build your inventory Ansible works against multiple managed nodes or "hosts" in your infrastructure at the same time, using a list or group of lists known as inventory. Once your inventory is defined, you use :ref:`patterns ` to select the hosts or groups you want Ansible to run against. -The default location for inventory is a file called ``/etc/ansible/hosts``. You can specify a different inventory file at the command line using the ``-i `` option. You can also use multiple inventory files at the same time, and/or pull inventory from dynamic or cloud sources or different formats (YAML, ini, etc), as described in :ref:`intro_dynamic_inventory`. +The default location for inventory is a file called ``/etc/ansible/hosts``. You can specify a different inventory file at the command line using the ``-i `` option. You can also use multiple inventory files at the same time, and/or pull inventory from dynamic or cloud sources or different formats (YAML, ini, and so on), as described in :ref:`intro_dynamic_inventory`. Introduced in version 2.4, Ansible has :ref:`inventory_plugins` to make this flexible and customizable. .. contents:: @@ -72,8 +72,8 @@ 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: -* What - An application, stack or microservice. (For example, database servers, web servers, etc). -* Where - A datacenter or region, to talk to local DNS, storage, etc. (For example, east, west). +* 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). * When - The development stage, to avoid testing on production resources. (For example, prod, test). Extending the previous YAML inventory to include what, when, and where would look like: @@ -421,7 +421,7 @@ All hosts in the 'raleigh' group will have the variables defined in these files available to them. This can be very useful to keep your variables organized when a single file gets too big, or when you want to use :ref:`Ansible Vault` on some group variables. -You can also add ``group_vars/`` and ``host_vars/`` directories to your playbook directory. The ``ansible-playbook`` command looks for these directories in the current working directory by default. Other Ansible commands (for example, ``ansible``, ``ansible-console``, etc.) 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. +You can also add ``group_vars/`` and ``host_vars/`` directories to your playbook directory. The ``ansible-playbook`` command looks for these directories in the current working directory by default. 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) @@ -611,7 +611,7 @@ ansible_shell_executable This sets the shell the ansible controller 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 - to use :command:`/bin/sh` (i.e. :command:`/bin/sh` is not installed on the target + 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.). Examples from an Ansible-INI host file: diff --git a/docs/docsite/rst/user_guide/playbook_pathing.rst b/docs/docsite/rst/user_guide/playbook_pathing.rst index 7d59102f741..7fc6059b0b0 100644 --- a/docs/docsite/rst/user_guide/playbook_pathing.rst +++ b/docs/docsite/rst/user_guide/playbook_pathing.rst @@ -25,8 +25,8 @@ The magic of 'local' paths Lookups and action plugins both use a special 'search magic' to find things, taking the current play into account, it uses from most specific to most general playbook dir in which a task is contained (this includes roles and includes). -Using this magic, relative paths get attempted first with a 'files|templates|vars' appended (if not already present), depending on action being taken, 'files' is the default. (i.e include_vars will use vars/). The paths will be searched from most specific to most general (i.e role before play). -dependent roles WILL be traversed (i.e task is in role2, role2 is a dependency of role1, role2 will be looked at first, then role1, then play). +Using this magic, relative paths get attempted first with a 'files|templates|vars' appended (if not already present), depending on action being taken, 'files' is the default. (in other words, include_vars will use vars/). The paths will be searched from most specific to most general (in other words, role before play). +dependent roles WILL be traversed (in other words, task is in role2, role2 is a dependency of role1, role2 will be looked at first, then role1, then play). i.e :: role search path is rolename/{files|vars|templates}/, rolename/tasks/. diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst index 1487b295796..c3d394c3600 100644 --- a/docs/docsite/rst/user_guide/playbooks_filters.rst +++ b/docs/docsite/rst/user_guide/playbooks_filters.rst @@ -28,7 +28,7 @@ You can provide default values for variables directly in your templates using th 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. 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 (i.e :code:`{{ foo.bar.baz | default('DEFAULT') }}`) when you do not know if the intermediate values are defined. +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. If you want to use the default value when variables evaluate to false or an empty string you have to set the second parameter to ``true``:: @@ -1456,7 +1456,7 @@ To replace text in a string with regex, use the "regex_replace" filter:: {{ hosts | map('regex_replace', '(.*)', '\\1:80') | list }} .. note:: - Prior to ansible 2.0, if "regex_replace" filter was used with variables inside YAML arguments (as opposed to simpler 'key=value' arguments), then you needed to escape backreferences (e.g. ``\\1``) with 4 backslashes (``\\\\``) instead of 2 (``\\``). + Prior to ansible 2.0, if "regex_replace" filter was used with variables inside YAML arguments (as opposed to simpler 'key=value' arguments), then you needed to escape backreferences (for example, ``\\1``) with 4 backslashes (``\\\\``) instead of 2 (``\\``). .. versionadded:: 2.0 @@ -1585,7 +1585,7 @@ To create a namespaced UUIDv5 using the default Ansible namespace '361E6D51-FAEC To make use of one attribute from each item in a list of complex variables, use the :func:`Jinja2 map filter `:: - # get a comma-separated list of the mount points (e.g. "/,/mnt/stuff") on a host + # get a comma-separated list of the mount points (for example, "/,/mnt/stuff") on a host {{ ansible_mounts | map(attribute='mount') | join(',') }} Handling dates and times @@ -1596,7 +1596,7 @@ To get a date object from a string use the `to_datetime` filter:: # 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 {{ (("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, etc to seconds. For that, use 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 diff --git a/docs/docsite/rst/user_guide/playbooks_loops.rst b/docs/docsite/rst/user_guide/playbooks_loops.rst index e90c92bdd30..f36857e5260 100644 --- a/docs/docsite/rst/user_guide/playbooks_loops.rst +++ b/docs/docsite/rst/user_guide/playbooks_loops.rst @@ -272,8 +272,8 @@ More information on the patterns can be found in :ref:`intro_patterns`. .. _query_vs_lookup: -Ensuring list input for ``loop``: ``query`` vs. ``lookup`` -========================================================== +Ensuring list input for ``loop``: using ``query`` rather than ``lookup`` +======================================================================== The ``loop`` keyword requires a list as input, but the ``lookup`` keyword returns a string of comma-separated values by default. Ansible 2.5 introduced a new Jinja2 function named :ref:`query ` that always returns a list, offering a simpler interface and more predictable output from lookup plugins when using the ``loop`` keyword. diff --git a/docs/docsite/rst/user_guide/playbooks_module_defaults.rst b/docs/docsite/rst/user_guide/playbooks_module_defaults.rst index 4e43542c9a2..b217c624165 100644 --- a/docs/docsite/rst/user_guide/playbooks_module_defaults.rst +++ b/docs/docsite/rst/user_guide/playbooks_module_defaults.rst @@ -108,7 +108,7 @@ Ansible 2.7 adds a preview-status feature to group together modules that share c * The `docker_stack `_ module is not included in the ``docker`` defaults group. -Use the groups with ``module_defaults`` by prefixing the group name with ``group/`` - e.g. ``group/aws``. +Use the groups with ``module_defaults`` by prefixing the group name with ``group/`` - for example ``group/aws``. In a playbook, you can set module defaults for whole groups of modules, such as setting a common AWS region. diff --git a/docs/docsite/rst/user_guide/playbooks_reuse.rst b/docs/docsite/rst/user_guide/playbooks_reuse.rst index ef9863212d7..c5265f07bb3 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse.rst @@ -84,8 +84,8 @@ See :ref:`ansible_variable_precedence` for more details on variable inheritance .. _dynamic_vs_static: -Comparing includes and imports: dynamic vs. static --------------------------------------------------- +Comparing includes and imports: dynamic and static re-use +------------------------------------------------------------ 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. diff --git a/docs/docsite/rst/user_guide/playbooks_strategies.rst b/docs/docsite/rst/user_guide/playbooks_strategies.rst index 26b48af5d1e..a97f0447956 100644 --- a/docs/docsite/rst/user_guide/playbooks_strategies.rst +++ b/docs/docsite/rst/user_guide/playbooks_strategies.rst @@ -197,7 +197,7 @@ As always with :ref:`delegation `, the action will be exec :code:`when: inventory_hostname == ansible_play_hosts_all[0]` construct. .. note:: - Any conditional (i.e `when:`) will use the variables of the 'first host' to decide if the task runs or not, no other hosts will be tested. + Any conditional (in other words, `when:`) will use the variables of the 'first host' to decide if the task runs or not, no other hosts will be tested. .. note:: If you want to avoid the default behavior of setting the fact for all hosts, set ``delegate_facts: True`` for the specific task or block. diff --git a/docs/docsite/rst/user_guide/playbooks_variables.rst b/docs/docsite/rst/user_guide/playbooks_variables.rst index 3487c0696ea..00277f3b7a6 100644 --- a/docs/docsite/rst/user_guide/playbooks_variables.rst +++ b/docs/docsite/rst/user_guide/playbooks_variables.rst @@ -271,7 +271,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 (e.g. 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:: ansible-playbook arcade.yml --extra-vars "{\"name\":\"Conan O\'Brien\"}" ansible-playbook arcade.yml --extra-vars '{"name":"Conan O'\\\''Brien"}' diff --git a/docs/docsite/rst/user_guide/vault.rst b/docs/docsite/rst/user_guide/vault.rst index ae0618748ed..0f5d035b710 100644 --- a/docs/docsite/rst/user_guide/vault.rst +++ b/docs/docsite/rst/user_guide/vault.rst @@ -534,7 +534,7 @@ If your task or playbook requires multiple encrypted variables or files that you ansible-playbook --vault-id dev@dev-password --vault-id prod@prompt site.yml -By default the vault ID labels (dev, prod etc.) are only hints. Ansible attempts to decrypt vault content with each password. The password with the same label as the encrypted data will be tried first, after that each vault secret will be tried in the order they were provided on the command line. +By default the vault ID labels (dev, prod and so on) are only hints. Ansible attempts to decrypt vault content with each password. The password with the same label as the encrypted data will be tried first, after that each vault secret will be tried in the order they were provided on the command line. Where the encrypted data has no label, or the label does not match any of the provided labels, the passwords will be tried in the order they are specified. In the example above, the 'dev' password will be tried first, then the 'prod' password for cases where Ansible doesn't know which vault ID is used to encrypt something.