diff options
| author | Alicia Cozine <879121+acozine@users.noreply.github.com> | 2019-10-08 19:33:58 -0500 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2019-10-08 19:33:58 -0500 |
| commit | 4e5c13e0757bd5b1fbd7add33da1edfea23fe3fc (patch) | |
| tree | fe75bcdafca243a1430828ef2bade86857131bca | |
| parent | d29802ee46bab088cf24c529203ffb3b59f8246a (diff) | |
| download | ansible-4e5c13e0757bd5b1fbd7add33da1edfea23fe3fc.tar.gz | |
Backport/2.9/docs (#63247)
* add more anchors to collections docs (#62827)
(cherry picked from commit 7e01de96d741c6fb8a1ce04f92873ffb57c9b1b5)
* add anchors to support galaxy links (#62808)
(cherry picked from commit 1b3bf33bdf2530adb3a7cbf8055007acb09b3bb2)
* doc: fix typos (#62852)
(cherry picked from commit b33ae1494936cd04fa89bce51e6068829fc89a91)
* Add some documentation about using plugins in collections (#62465)
- FQCN requirements
- Sharing code in collections
- Limitations with inventory caching
(cherry picked from commit d41050b28b2d3e8d4a97ce13344b04fc87f703a2)
* Remove Latin phrases from the docs (#62419)
* add styleguide about avoiding use of latin words
(cherry picked from commit e7436e278f8945dd73b066c47280c1a17bc18ebe)
* ovirt: Fixing typo in ovirt_disk examples (#62962)
(cherry picked from commit 50dc41cca2e6d75a05e933c5286f41bde235b65f)
* vmware guidlines: adjust the location of cloud-config-vcenter.ini.template (#62970)
Update the location of the cloud-config-vcenter.ini.template template.
The file has been moved by: 2e7d36a3f969b31570d7ee34e3f1f971c5c586a9.
(cherry picked from commit 7ecfa4a471ae17ee15aa51f684bf7d340805d432)
* Prefer https:// links in the docs site (#62939)
This is a follow-up of last year's 1a11cec. It deals with links which
at that point either were not present or did not support https://.
(cherry picked from commit c8315bfd6097f680ae79de5e4d4ee23d0c1068c0)
* fix minor typos (#62950)
(cherry picked from commit ad580a71c475b570cdbd4c79aaf0082ecccdf5fc)
* Modernize Vagrant documentation (#62923)
* By requiring a slightly newer Vagrant version (from 2015) we get the
same generated Ansible inventory format is still used by today's
version of Vagrant. That extended inventory format also has the
benefit of allowing for simpler Ansible examples.
* Switching to a current and supported Ubuntu LTS version.
(cherry picked from commit 0d79013f51ca67eddcb1a3f6ff0f4453b659ee81)
* add ios/iosxr deprecated modules (#62908)
(cherry picked from commit 6bbd9c9eca5992d9fc53dd8fd8814205afaf508d)
42 files changed, 158 insertions, 86 deletions
diff --git a/docs/docsite/rst/community/committer_guidelines.rst b/docs/docsite/rst/community/committer_guidelines.rst index 5c83718c3e..3218cc846a 100644 --- a/docs/docsite/rst/community/committer_guidelines.rst +++ b/docs/docsite/rst/community/committer_guidelines.rst @@ -10,12 +10,12 @@ These guidelines apply to everyone. At the same time, this ISN'T a process docum That said, use the trust wisely. -If you abuse the trust and break components and builds, etc., the trust level falls and you may be asked not to commit or you may lose your commit privileges. +If you abuse the trust and break components and builds, and so on, the trust level falls and you may be asked not to commit or you may lose your commit privileges. Features, high-level design, and roadmap ======================================== -As a core team member, you are an integral part of the team that develops the :ref:`roadmap <roadmaps>`. 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, etc. for various releases. Red Hat, the company, and the Ansible team must get these committed features (etc.) 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 <roadmaps>`. 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. 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. @@ -38,7 +38,7 @@ The Core Team is aware that this can be a difficult process at times. Sometimes, Roles on Core ============= * Core committers: Fine to do PRs for most things, but we should have a timebox. Hanging PRs may merge on the judgement of these devs. -* :ref:`Module maintainers <maintainers>`: Module maintainers own specific modules and have indirect commit access via the current module PR mechanisms. +* :ref:`Module maintainers <maintainers>`: Module maintainers own specific modules and have indirect commit access through the current module PR mechanisms. General rules ============= @@ -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/etc.). + - 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, etc.) 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, etc.). + - 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.). - Consider scope, sometimes a fix can be generalized - Keep it simple, then things are maintainable, debuggable and intelligible. @@ -71,7 +71,7 @@ Committers are expected to continue to follow the same community and contributio People ====== -Individuals who've been asked to become a part of this group have generally been contributing in significant ways to the Ansible community for some time. Should they agree, they are requested to add their names and GitHub IDs to this file, in the section below, via a pull request. Doing so indicates that these individuals agree to act in the ways that their fellow committers trust that they will act. +Individuals who've been asked to become a part of this group have generally been contributing in significant ways to the Ansible community for some time. Should they agree, they are requested to add their names and GitHub IDs to this file, in the section below, through a pull request. Doing so indicates that these individuals agree to act in the ways that their fellow committers trust that they will act. +---------------------+----------------------+--------------------+----------------------+ | Name | GitHub ID | IRC Nick | Other | diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index b19c3ec02b..9f6f332535 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -22,7 +22,7 @@ Ansible has several mailing lists. Your first post to the mailing list will be * `Ansible Container List <https://groups.google.com/forum/#!forum/ansible-container>`_ is for users and developers of the Ansible Container project. * `Ansible Development List <https://groups.google.com/forum/#!forum/ansible-devel>`_ is for learning how to develop on Ansible, asking about prospective feature design, or discussions about extending ansible or features in progress. * `Ansible Lockdown List <https://groups.google.com/forum/#!forum/ansible-lockdown>`_ is for all things related to Ansible Lockdown projects, including DISA STIG automation and CIS Benchmarks. -* `Ansible Outreach List <https://groups.google.com/forum/#!forum/ansible-outreach>`_ help with promoting Ansible and `Ansible Meetups <http://ansible.meetup.com/>`_ +* `Ansible Outreach List <https://groups.google.com/forum/#!forum/ansible-outreach>`_ help with promoting Ansible and `Ansible Meetups <https://ansible.meetup.com/>`_ * `Ansible Project List <https://groups.google.com/forum/#!forum/ansible-project>`_ is for sharing Ansible tips, answering questions, and general user discussion. * `Molecule List <https://groups.google.com/forum/#!forum/molecule-users>`_ is designed to aid with the development and testing of Ansible roles with Molecule. diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 985454f0d1..d2630377f7 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -27,7 +27,7 @@ If you want to follow the conversation about what features will be added to Ansi Micro development: the lifecycle of a PR ======================================== -Ansible accepts code via **pull requests** ("PRs" for short). GitHub provides a great overview of `how the pull request process works <https://help.github.com/articles/about-pull-requests/>`_ in general. The ultimate goal of any pull request is to get merged and become part of Ansible Core. +Ansible accepts code through **pull requests** ("PRs" for short). GitHub provides a great overview of `how the pull request process works <https://help.github.com/articles/about-pull-requests/>`_ in general. The ultimate goal of any pull request is to get merged and become part of Ansible Core. Here's an overview of the PR lifecycle: * Contributor opens a PR @@ -107,7 +107,7 @@ Information labels - **feature_pull_request**: applied by the bot based on the templatized description of the PR. - **networking**: applied by the bot based on the paths of the modified files. - **owner_pr**: largely deprecated. Formerly workflow, now informational. Originally, PRs submitted by the maintainer would automatically go to **shipit** based on this label. If the submitter is also a maintainer, we notify the other maintainers and still require one of the maintainers (including the submitter) to give a **shipit**. -- **pending_action**: applied by the bot to PRs that are not moving. Reviewed every couple of weeks by the community team, who tries to figure out the appropriate action (closure, asking for new maintainers, etc). +- **pending_action**: applied by the bot to PRs that are not moving. Reviewed every couple of weeks by the community team, who tries to figure out the appropriate action (closure, asking for new maintainers, and so on). Special Labels @@ -164,7 +164,7 @@ an existing one, so we can trace the change back to the PR that introduced it. To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory. The file name should include the PR number and a description of the change. It must end with the file extension ``.yaml``. For example: ``40696-user-backup-shadow-file.yaml`` A single changelog fragment may contain multiple sections but most will only contain one section. -The toplevel keys (bugfixes, major_changes, etc) are defined in the +The toplevel keys (bugfixes, major_changes, and so on) are defined in the `config file <https://github.com/ansible/ansible/blob/devel/changelogs/config.yaml>`_ for our release note tool. Here are the valid sections and a description of each: **major_changes** diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 41bca63837..e7229810f8 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -49,7 +49,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, etc.) +- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on.) Before you open a complex documentation PR ========================================== diff --git a/docs/docsite/rst/community/index.rst b/docs/docsite/rst/community/index.rst index 26f3534ca3..2afd006cb7 100644 --- a/docs/docsite/rst/community/index.rst +++ b/docs/docsite/rst/community/index.rst @@ -36,7 +36,7 @@ Going deeper * I think Ansible is broken. How do I :ref:`report a bug <reporting_bugs>`? * I need functionality that Ansible doesn't offer. How do I :ref:`request a feature <request_features>`? * I'm waiting for a particular feature. How do I see what's :ref:`planned for future Ansible Releases <roadmaps>`? -* I have a specific Ansible interest or expertise (for example, VMware, Linode, etc.). How do I get involved in a :ref:`working group <working_group_list>`? +* 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 <working_group_list>`? * I'd 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 <community_documentation_contributions>`? diff --git a/docs/docsite/rst/community/maintainers.rst b/docs/docsite/rst/community/maintainers.rst index 631e19a9a3..94e4acc0da 100644 --- a/docs/docsite/rst/community/maintainers.rst +++ b/docs/docsite/rst/community/maintainers.rst @@ -42,7 +42,7 @@ Issues Issues for modules, including bug reports, documentation bug reports, and feature requests, are tracked in the `ansible repository <https://github.com/ansible/ansible/issues>`_. -Issues for modules are routed to their maintainers via an automated process. This process is still being refined, and currently depends upon the issue creator to provide adequate details (specifically, providing the proper module name) in order to route it correctly. If you are a maintainer of a specific module, it is recommended that you periodically search module issues for issues which mention your module's name (or some variation on that name), as well as setting an appropriate notification process for receiving notification of mentions of your GitHub ID. +Issues for modules are routed to their maintainers by an automated process. This process is still being refined, and currently depends upon the issue creator to provide adequate details (specifically, providing the proper module name) in order to route it correctly. If you are a maintainer of a specific module, it is recommended that you periodically search module issues for issues which mention your module's name (or some variation on that name), as well as setting an appropriate notification process for receiving notification of mentions of your GitHub ID. PR workflow ----------- diff --git a/docs/docsite/rst/community/other_tools_and_programs.rst b/docs/docsite/rst/community/other_tools_and_programs.rst index 06c21303e4..c7cc6c5bad 100644 --- a/docs/docsite/rst/community/other_tools_and_programs.rst +++ b/docs/docsite/rst/community/other_tools_and_programs.rst @@ -59,7 +59,7 @@ Visual Studio Code An open-source, free GUI text editor created and maintained by Microsoft. Useful Visual Studio Code plugins include: -* `YAML Support by Red Hat <https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml>`_ - provides YAML support via yaml-language-server with built-in Kubernetes and Kedge syntax support. +* `YAML Support by Red Hat <https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml>`_ - provides YAML support through yaml-language-server with built-in Kubernetes and Kedge syntax support. * `Ansible Syntax Highlighting Extension <https://marketplace.visualstudio.com/items?itemName=haaaad.ansible>`_ - YAML & Jinja2 support. * `Visual Studio Code extension for Ansible <https://marketplace.visualstudio.com/items?itemName=vscoss.vscode-ansible>`_ - provides autocompletion, syntax highlighting. @@ -103,7 +103,7 @@ Other Tools - `Ansible Inventory Grapher <https://github.com/willthames/ansible-inventory-grapher>`_ - visually displays inventory inheritance hierarchies and at what level a variable is defined in inventory. - `Ansible Playbook Grapher <https://github.com/haidaraM/ansible-playbook-grapher>`_ - A command line tool to create a graph representing your Ansible playbook tasks and roles. - `Ansible Shell <https://github.com/dominis/ansible-shell>`_ - an interactive shell for Ansible with built-in tab completion for all the modules. -- `Ansible Silo <https://github.com/groupon/ansible-silo>`_ - a self-contained Ansible environment via Docker. +- `Ansible Silo <https://github.com/groupon/ansible-silo>`_ - a self-contained Ansible environment by Docker. - `Ansigenome <https://github.com/nickjj/ansigenome>`_ - a command line tool designed to help you manage your Ansible roles. - `ARA <https://github.com/openstack/ara>`_ - records Ansible playbook runs and makes the recorded data available and intuitive for users and systems by integrating with Ansible as a callback plugin. - `Awesome Ansible <https://github.com/jdauphant/awesome-ansible>`_ - a collaboratively curated list of awesome Ansible resources. diff --git a/docs/docsite/rst/community/reporting_bugs_and_features.rst b/docs/docsite/rst/community/reporting_bugs_and_features.rst index bcd222b998..d55ea995a1 100644 --- a/docs/docsite/rst/community/reporting_bugs_and_features.rst +++ b/docs/docsite/rst/community/reporting_bugs_and_features.rst @@ -21,7 +21,7 @@ Knowing your Ansible version and the exact commands you are running, and what yo Do not use the issue tracker for "how do I do this" type questions. These are great candidates for IRC or the mailing list instead where things are likely to be more of a discussion. -To be respectful of reviewers' time and allow us to help everyone efficiently, please provide minimal well-reduced and well-commented examples versus sharing your entire production playbook. Include playbook snippets and output where possible. +To be respectful of reviewers' time and allow us to help everyone efficiently, please provide minimal well-reduced and well-commented examples rather than sharing your entire production playbook. Include playbook snippets and output where possible. When sharing YAML in playbooks, formatting can be preserved by using `code blocks <https://help.github.com/articles/creating-and-highlighting-code-blocks/>`_. diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index eb3c61764b..70e8091d59 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -13,6 +13,8 @@ You can publish and use collections through `Ansible Galaxy <https://galaxy.ansi :local: :depth: 2 +.. _collection_structure: + Collection structure ==================== @@ -45,6 +47,7 @@ and other tools need in order to package, build and publish the collection:: * See the `draft collection <https://github.com/bcoca/collection>`_ for an example of a full collection structure. * Not all directories are currently in use. Those are placeholders for future features. +.. _galaxy_yml: galaxy.yml ---------- @@ -52,6 +55,7 @@ galaxy.yml A collection must have a ``galaxy.yml`` file that contains the necessary information to build a collection artifact. See :ref:`collections_galaxy_meta` for details. +.. _collections_doc_dir: docs directory --------------- @@ -68,11 +72,14 @@ The ``ansible-doc`` command requires the fully qualified collection name (FQCN) .. note:: The Ansible collection namespace is defined in the ``galaxy.yml`` file and is not equivalent to the GitHub repository name. +.. _collections_plugin_dir: plugins directory ------------------ -Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by any other plugin 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. module_utils ^^^^^^^^^^^^ @@ -109,6 +116,11 @@ In the Python example the ``module_util`` in question is called ``qradar`` such not_rest_data_keys=['state'] ) +Note that importing something from an ``__init__.py`` file requires using the file name: + +.. code-block:: python + + from ansible_collections.namespace.collection_name.plugins.callback.__init__ import CustomBaseClass In the PowerShell example the ``module_util`` in question is called ``hyperv`` such that the FCQN is ``ansible_example.community.plugins.module_utils.hyperv``: @@ -129,6 +141,7 @@ In the PowerShell example the ``module_util`` in question is called ``hyperv`` s $module.ExitJson() +.. _collections_roles_dir: roles directory ---------------- @@ -255,6 +268,8 @@ You can publish collections to Galaxy using the ``ansible-galaxy collection publ .. note:: Once you upload a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before you upload it. +.. _upload_collection_ansible_galaxy: + Upload using ansible-galaxy ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -272,8 +287,10 @@ without waiting for the import result, use the ``--no-wait`` argument and manual The API key is a secret token used by Ansible Galaxy to protect your content. You can find your API key at your `Galaxy profile preferences <https://galaxy.ansible.com/me/preferences>`_ page. -Upload from the Galaxy website -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _upload_collection_galaxy: + +Upload a collection from the Galaxy website +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To upload your collection artifact directly on Galaxy: @@ -287,6 +304,7 @@ namespace, the upload request will fail. Once Galaxy uploads and accepts a collection, you will be redirected to the **My Imports** page, which displays output from the import process, including any errors or warnings about the metadata and content contained in the collection. +.. _collection_versions: Collection versions ------------------- @@ -301,6 +319,8 @@ Collection versions use `Sematic Versioning <https://semver.org/>`_ for version * Increment minor (for example: y in `x.y.z`) version number for new functionality in a backwards compatible manner. * Increment patch (for example: z in `x.y.z`) version number for backwards compatible bug fixes. +.. _migrate_to_collection: + Migrating Ansible content to a collection ========================================= diff --git a/docs/docsite/rst/dev_guide/developing_inventory.rst b/docs/docsite/rst/dev_guide/developing_inventory.rst index 13c880f184..e93787014f 100644 --- a/docs/docsite/rst/dev_guide/developing_inventory.rst +++ b/docs/docsite/rst/dev_guide/developing_inventory.rst @@ -74,6 +74,8 @@ The first thing you want to do is use the base class: NAME = 'myplugin' # used internally by Ansible, it should match the file name but not required +If the inventory plugin is in a collection the NAME should be in the format of 'namespace.collection_name.myplugin'. + This class has a couple of methods each plugin should implement and a few helpers for parsing the inventory source and updating the inventory. After you have the basic plugin working you might want to to incorporate other features by adding more base classes: 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 9a5b6935e4..c013197d6b 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general_aci.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general_aci.rst @@ -325,7 +325,7 @@ You can test your ``construct_url()`` and ``payload()`` arguments without access import json from ansible.module_utils.network.aci.aci import ACIModule - # Just another class mimicking a bare AnsibleModule class for construct_url() and payload() methods + # Just another class mimicing a bare AnsibleModule class for construct_url() and payload() methods class AltModule(): params = dict( host='dummy', diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 2bbfe0d2a3..3c8c19d333 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -150,7 +150,7 @@ see the source code for the `action plugins included with Ansible Core <https:// Cache plugins ------------- -Cache plugins store gathered facts and data retrieved by inventory plugins. +Cache plugins store gathered facts and data retrieved by inventory plugins. Only fact caching is currently supported by cache plugins in collections. Import cache plugins using the cache_loader so you can use ``self.set_options()`` and ``self.get_option(<option_name>)``. If you import a cache plugin directly in the code base, you can only access options via ``ansible.constants``, and you break the cache plugin's ability to be used by an inventory plugin. @@ -246,7 +246,7 @@ but with an extra option so you can see how configuration works in Ansible versi """ CALLBACK_VERSION = 2.0 CALLBACK_TYPE = 'aggregate' - CALLBACK_NAME = 'timer' + CALLBACK_NAME = 'namespace.collection_name.timer' # only needed if you ship it and don't want to enable by default CALLBACK_NEEDS_WHITELIST = True @@ -320,7 +320,7 @@ Lookup plugins pull in data from external data stores. Lookup plugins can be use Lookup plugins are very flexible, allowing you to retrieve and return any type of data. When writing lookup plugins, always return data of a consistent type that can be easily consumed in a playbook. Avoid parameters that change the returned data type. If there is a need to return a single value sometimes and a complex dictionary other times, write two different lookup plugins. -Ansible includes many :ref:`filters <playbooks_filters>` which can be used to manipulate the data returned by a lookup plugin. Sometimes it makes sense to do the filtering inside the lookup plugin, other times it is better to return results that can be filtered in the playbook. Keep in mind how the data will be referenced when determing the appropriate level of filtering to be done inside the lookup plugin. +Ansible includes many :ref:`filters <playbooks_filters>` which can be used to manipulate the data returned by a lookup plugin. Sometimes it makes sense to do the filtering inside the lookup plugin, other times it is better to return results that can be filtered in the playbook. Keep in mind how the data will be referenced when determining the appropriate level of filtering to be done inside the lookup plugin. Here's a simple lookup plugin implementation --- this lookup returns the contents of a text file as a variable: @@ -389,7 +389,7 @@ The following is an example of how this lookup is called:: --- - hosts: all vars: - contents: "{{ lookup('file', '/etc/foo.txt') }}" + contents: "{{ lookup('namespace.collection_name.file', '/etc/foo.txt') }}" tasks: @@ -418,7 +418,7 @@ Vars plugins Vars plugins inject additional variable data into Ansible runs that did not come from an inventory source, playbook, or command line. Playbook constructs like 'host_vars' and 'group_vars' work using vars plugins. -Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4. +Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4. Vars plugins are unsupported by collections. Older plugins used a ``run`` method as their main body/work: 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 6618bb4ced..2560007648 100644 --- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst @@ -620,7 +620,7 @@ no_log aliases """"""" -``aliases`` accepts a list of alternative argument names for the argument, such as the case where the argument is ``name`` but the module accepts ``aliases=['pkg']`` to allow ``pkg`` to be interchangably with ``name`` +``aliases`` accepts a list of alternative argument names for the argument, such as the case where the argument is ``name`` but the module accepts ``aliases=['pkg']`` to allow ``pkg`` to be interchangeably with ``name`` options """"""" diff --git a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst index b68b045793..c0d706ade0 100644 --- a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst +++ b/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst @@ -347,7 +347,7 @@ API throttling (rate limiting) and pagination ============================================= For methods that return a lot of results, boto3 often provides -`paginators <http://boto3.readthedocs.io/en/latest/guide/paginators.html>`_. If the method +`paginators <https://boto3.readthedocs.io/en/latest/guide/paginators.html>`_. If the method you're calling has ``NextToken`` or ``Marker`` parameters, you should probably check whether a paginator exists (the top of each boto3 service reference page has a link to Paginators, if the service has any). To use paginators, obtain a paginator object, @@ -640,7 +640,7 @@ to your test in the following variables: * `security_token` So all invocations of AWS modules in the test should set these parameters. To avoid duplication these -for every call, it's preferable to use `YAML Anchors <http://blog.daemonl.com/2016/02/yaml.html>`_. For example: +for every call, it's preferable to use `YAML Anchors <https://blog.daemonl.com/2016/02/yaml.html>`_. For example: .. code-block:: yaml diff --git a/docs/docsite/rst/dev_guide/platforms/openstack_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/openstack_guidelines.rst index 3417342f31..ac3f686f0c 100644 --- a/docs/docsite/rst/dev_guide/platforms/openstack_guidelines.rst +++ b/docs/docsite/rst/dev_guide/platforms/openstack_guidelines.rst @@ -46,7 +46,7 @@ Libraries standard input such as auth and ssl support. * All modules should include ``extends_documentation_fragment: openstack``. * All complex cloud interaction or interoperability code should be housed in - the `openstacksdk <http://git.openstack.org/cgit/openstack/openstacksdk>`_ + the `openstacksdk <https://git.openstack.org/cgit/openstack/openstacksdk>`_ library. * All OpenStack API interactions should happen via the openstacksdk and not via OpenStack Client libraries. The OpenStack Client libraries do no have end diff --git a/docs/docsite/rst/dev_guide/platforms/ovirt_dev_guide.rst b/docs/docsite/rst/dev_guide/platforms/ovirt_dev_guide.rst index 56df167143..3789c0e303 100644 --- a/docs/docsite/rst/dev_guide/platforms/ovirt_dev_guide.rst +++ b/docs/docsite/rst/dev_guide/platforms/ovirt_dev_guide.rst @@ -44,7 +44,7 @@ Libraries along with ``ovirt_full_argument_spec``. - All info modules should use ``extends_documentation_fragment``: ``ovirt_info`` to go along with ``ovirt_info_full_argument_spec``. -- Functions that are common to all modules should be implemeneted in the +- Functions that are common to all modules should be implemented in the ``module_utils/ovirt.py`` file, so they can be reused. - Python SDK version 4 must be used. @@ -214,7 +214,7 @@ Testing ------- - Integration testing is currently done in oVirt's CI system - `on Jenkins <http://jenkins.ovirt.org/view/All/job/ovirt-system-tests_ansible-suite-master/>`__ + `on Jenkins <https://jenkins.ovirt.org/view/All/job/ovirt-system-tests_ansible-suite-master/>`__ and `on GitHub <https://github.com/oVirt/ovirt-system-tests/tree/master/ansible-suite-master/>`__. - Please consider using these integration tests if you create a new module or add a new feature to an existing diff --git a/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst index ea3a3d2e6f..948268bac6 100644 --- a/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst +++ b/docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst @@ -89,7 +89,7 @@ Configure your installation Prepare a configuration file that describes your set-up. The file should be called :file:`test/integration/cloud-config-vcenter.ini` and based on -:file:`test/integration/cloud-config-vcenter.ini.template`. For instance, if you've deployed your lab with +:file:`test/lib/ansible_test/config/cloud-config-vcenter.ini.template`. For instance, if you've deployed your lab with `vmware-on-libvirt <https://github.com/goneri/vmware-on-libvirt>`: .. code-block:: ini 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 ff64564c7a..eade01ec7d 100644 --- a/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst +++ b/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst @@ -61,7 +61,7 @@ For menu procedures, bold the menu names, button names, etc to help the user fin 3. In the **Open** dialog box, click **Save**. 4. On the toolbar, click the **Open File** icon. -For code or command snippets, use the RST `code-block directive <http://www.sphinx-doc.org/en/1.5/markup/code.html#directive-code-block>`_:: +For code or command snippets, use the RST `code-block directive <https://www.sphinx-doc.org/en/1.5/markup/code.html#directive-code-block>`_:: .. code-block:: bash diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst index 789c9d991d..5a6a353291 100644 --- a/docs/docsite/rst/dev_guide/style_guide/index.rst +++ b/docs/docsite/rst/dev_guide/style_guide/index.rst @@ -48,6 +48,30 @@ Header case Headers should be written in sentence case. For example, this section's title is ``Header case``, not ``Header Case`` or ``HEADER CASE``. + +Avoid using Latin phrases +------------------------- + +Latin words and phrases like ``e.g.`` or ``etc.`` +are easily understood by English speakers. +They may be harder to understand for others and are also tricky for automated translation. + +Use the following English terms in place of Latin terms or abbreviations: ++-------------------------------+------------------------------+ +| Latin | English | ++===============================+==============================+ +| i.e | in other words | ++-------------------------------+------------------------------+ +| e.g. | for example | ++-------------------------------+------------------------------+ +| etc | and so on | ++-------------------------------+------------------------------+ +| via | by/ through | ++-------------------------------+------------------------------+ +| vs./versus | rather than/against | ++-------------------------------+------------------------------+ + + reStructuredText guidelines =========================== @@ -57,7 +81,7 @@ We follow these technical or mechanical guidelines on all rST pages: Header notation --------------- -`Section headers in reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_ +`Section headers in reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_ can use a variety of notations. Sphinx will 'learn on the fly' when creating a hierarchy of headers. To make our documents easy to read and to edit, we follow a standard set of header notations. @@ -111,7 +135,7 @@ We use: Internal navigation ------------------- -`Anchors (also called labels) and links <http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_ +`Anchors (also called labels) and links <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_ work together to help users find related content. Local tables of contents also help users navigate quickly to the information they need. All internal links should use the ``:ref:`` syntax. diff --git a/docs/docsite/rst/network/getting_started/network_resources.rst b/docs/docsite/rst/network/getting_started/network_resources.rst index 499697b7a8..c0fbd7b2a9 100644 --- a/docs/docsite/rst/network/getting_started/network_resources.rst +++ b/docs/docsite/rst/network/getting_started/network_resources.rst @@ -44,4 +44,4 @@ Join us on: * Freenode IRC - ``#ansible-network`` Freenode channel -* Slack - `<http://ansiblenetwork.slack.com>`_ +* Slack - `<https://ansiblenetwork.slack.com>`_ diff --git a/docs/docsite/rst/network/user_guide/platform_cnos.rst b/docs/docsite/rst/network/user_guide/platform_cnos.rst index 664d792471..70201d7f38 100644 --- a/docs/docsite/rst/network/user_guide/platform_cnos.rst +++ b/docs/docsite/rst/network/user_guide/platform_cnos.rst @@ -65,7 +65,7 @@ Example CLI Task .. code-block:: yaml - - name: Retreive CNOS OS version + - name: Retrieve CNOS OS version cnos_command: commands: show version when: ansible_network_os == 'cnos' diff --git a/docs/docsite/rst/network/user_guide/platform_enos.rst b/docs/docsite/rst/network/user_guide/platform_enos.rst index 142ccf771c..02f7386a7e 100644 --- a/docs/docsite/rst/network/user_guide/platform_enos.rst +++ b/docs/docsite/rst/network/user_guide/platform_enos.rst @@ -67,7 +67,7 @@ Example CLI Task .. code-block:: yaml - - name: Retreive ENOS OS version + - name: Retrieve ENOS OS version enos_command: commands: show version when: ansible_network_os == 'enos' diff --git a/docs/docsite/rst/network/user_guide/platform_index.rst b/docs/docsite/rst/network/user_guide/platform_index.rst index 6083c25d2d..cbbad65e28 100644 --- a/docs/docsite/rst/network/user_guide/platform_index.rst +++ b/docs/docsite/rst/network/user_guide/platform_index.rst @@ -41,7 +41,7 @@ Settings by Platform .. raw:: html <style> - /* Style for this single table. Add delimiters between header colums */ + /* Style for this single table. Add delimiters between header columns */ table#network-platform-table thead tr th.head { border-left-width: 1px; border-left-color: rgb(225, 228, 229); diff --git a/docs/docsite/rst/network/user_guide/platform_nxos.rst b/docs/docsite/rst/network/user_guide/platform_nxos.rst index ed61fdefbc..9a5743bdb9 100644 --- a/docs/docsite/rst/network/user_guide/platform_nxos.rst +++ b/docs/docsite/rst/network/user_guide/platform_nxos.rst @@ -137,7 +137,7 @@ Cisco Nexus Platform Support Matrix The following platforms and software versions have been certified by Cisco to work with this version of Ansible. -.. table:: Platform / Software Mininum Requirements +.. table:: Platform / Software Minimum Requirements :align: center =================== ===================== diff --git a/docs/docsite/rst/plugins/cache.rst b/docs/docsite/rst/plugins/cache.rst index 66ffbc30e5..e6cad2b895 100644 --- a/docs/docsite/rst/plugins/cache.rst +++ b/docs/docsite/rst/plugins/cache.rst @@ -34,6 +34,13 @@ or in the ``ansible.cfg`` file: [defaults] fact_caching=redis +If the cache plugin is in a collection use the fully qualified name: + +.. code-block:: ini + + [defaults] + fact_caching = namespace.collection_name.cache_plugin_name + You will also need to configure other settings specific to each plugin. Consult the individual plugin documentation or the Ansible :ref:`configuration <ansible_configuration_settings>` for more details. @@ -43,7 +50,7 @@ A custom cache plugin is enabled by dropping it into a ``cache_plugins`` directo Enabling Inventory Cache Plugins -------------------------------- -Inventory may be cached using a file-based cache plugin (like jsonfile). Check the specific inventory plugin to see if it supports caching. +Inventory may be cached using a file-based cache plugin (like jsonfile). Check the specific inventory plugin to see if it supports caching. Cache plugins inside a collection are not supported for caching inventory. If an inventory-specific cache plugin is not specified Ansible will fall back to caching inventory with the fact cache plugin options. The inventory cache is disabled by default. You may enable it via environment variable: diff --git a/docs/docsite/rst/plugins/callback.rst b/docs/docsite/rst/plugins/callback.rst index 0614a0c9b6..3160eb120f 100644 --- a/docs/docsite/rst/plugins/callback.rst +++ b/docs/docsite/rst/plugins/callback.rst @@ -34,7 +34,7 @@ Most callbacks shipped with Ansible are disabled by default and need to be white .. code-block:: ini - #callback_whitelist = timer, mail, profile_roles + #callback_whitelist = timer, mail, profile_roles, collection_namespace.collection_name.custom_callback Setting a callback plugin for ``ansible-playbook`` -------------------------------------------------- diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst index 0576b35c54..d9984627d1 100644 --- a/docs/docsite/rst/plugins/inventory.rst +++ b/docs/docsite/rst/plugins/inventory.rst @@ -31,6 +31,15 @@ This list also establishes the order in which each plugin tries to parse an inve [inventory] enable_plugins = advanced_host_list, constructed, yaml +The ``auto`` inventory plugin can be used to automatically determines which inventory plugin to use for a YAML configuration file. It can also be used for inventory plugins in a collection. + +To whitelist specific inventory plugins in a collection you need to use the fully qualified name: + +.. code-block:: ini + + [inventory] + enable_plugins = namespace.collection_name.inventory_plugin_name + .. _using_inventory: @@ -55,6 +64,12 @@ Or for the openstack plugin the file has to be called ``clouds.yml`` or ``openst # clouds.yml or openstack.(yml|yaml) plugin: openstack +To use a plugin in a collection provide the fully qualified name: + +.. code-block:: yaml + + plugin: namespace.collection_name.inventory_plugin_name + The ``auto`` inventory plugin is enabled by default and works by using the ``plugin`` field to indicate the plugin that should attempt to parse it. You can configure the whitelist/precedence of inventory plugins used to parse source using the `ansible.cfg` ['inventory'] ``enable_plugins`` list. After enabling the plugin and providing any required options, you can view the populated inventory with ``ansible-inventory -i demo.aws_ec2.yml --graph``: .. code-block:: text @@ -65,6 +80,8 @@ The ``auto`` inventory plugin is enabled by default and works by using the ``plu | |--ec2-98-765-432-10.compute-1.amazonaws.com |--@ungrouped: +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. + You can set the default inventory path (via ``inventory`` in the `ansible.cfg` [defaults] section or the :envvar:`ANSIBLE_INVENTORY` environment variable) to your inventory source(s). Now running ``ansible-inventory --graph`` should yield the same output as when you passed your YAML configuration source(s) directly. You can add custom inventory plugins to your plugin path to use in the same way. 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``. @@ -135,6 +152,8 @@ Here is an example of setting inventory caching with some fact caching defaults cache = yes cache_connection = /tmp/ansible_inventory +Besides cache plugins shipped with Ansible, cache plugins eligible for caching inventory can also reside in a custom cache plugin path. Cache plugins in collections are not supported yet for inventory. + .. _inventory_plugin_list: Plugin List 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 74cc252156..6550ef68b5 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst @@ -254,7 +254,7 @@ Inventory plugins have been fine tuned, and we have started to add some common f Shell ----- -Shell plugins have been migrated to the new plugin configuration framework. It is now possible to customize more settings, and settings which were previously 'global' can now also be overriden using host specific variables. +Shell plugins have been migrated to the new plugin configuration framework. It is now possible to customize more settings, and settings which were previously 'global' can now also be overridden using host specific variables. For example, ``system_temps`` is a new setting that allows you to control what Ansible will consider a 'system temporary dir'. This is used when escalating privileges for a non-administrative user. Previously this was hardcoded to '/tmp', which some systems cannot use for privilege escalation. This setting now defaults to ``[ '/var/tmp', '/tmp']``. 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 cb2793f3e5..cdd4880cbb 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.9.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.9.rst @@ -135,6 +135,16 @@ The following modules will be removed in Ansible 2.13. Please update update your * eos_vlan use :ref:`eos_vlans <eos_vlans_module>` instead. +* ios_interface use :ref:`ios_interfaces <ios_interfaces_module>` instead. + +* ios_l2_interface use :ref:`ios_l2_interfaces <ios_l2_interfaces_module>` instead. + +* ios_l3_interface use :ref:`ios_l3_interfaces <ios_l3_interfaces_module>` instead. + +* ios_vlan use :ref:`ios_vlans <ios_vlans_module>` instead. + +* iosxr_interface use :ref:`iosxr_interfaces <iosxr_interfaces_module>` instead. + * junos_interface use :ref:`junos_interfaces <junos_interfaces_module>` instead. * junos_l2_interface use :ref:`junos_l2_interfaces <junos_l2_interfaces_module>` instead. diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index 5f59fdc67a..7a689b0a60 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -233,9 +233,9 @@ value:: Questions? Help? Ideas? Stop by the list on Google Groups `irc.freenode.net <http://irc.freenode.net>`_ #ansible IRC chat channel and #yaml for YAML specific questions - `YAML 1.1 Specification <http://yaml.org/spec/1.1/>`_ + `YAML 1.1 Specification <https://yaml.org/spec/1.1/>`_ The Specification for YAML 1.1, which PyYAML and libyaml are currently implementing - `YAML 1.2 Specification <http://yaml.org/spec/1.2/spec.html>`_ + `YAML 1.2 Specification <https://yaml.org/spec/1.2/spec.html>`_ For completeness, YAML 1.2 is the successor of 1.1 diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index b0ded2d85b..83936c3ee2 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -246,7 +246,7 @@ There are a few common errors that one might run into when trying to execute Ans * When ``pipelining = False`` in `/etc/ansible/ansible.cfg` then Ansible modules are transferred in binary mode via sftp however execution of python fails with .. error:: - SyntaxError: Non-UTF-8 code starting with \'\\x83\' in file /a/user1/.ansible/tmp/ansible-tmp-1548232945.35-274513842609025/AnsiballZ_stat.py on line 1, but no encoding declared; see http://python.org/dev/peps/pep-0263/ for details + SyntaxError: Non-UTF-8 code starting with \'\\x83\' in file /a/user1/.ansible/tmp/ansible-tmp-1548232945.35-274513842609025/AnsiballZ_stat.py on line 1, but no encoding declared; see https://python.org/dev/peps/pep-0263/ for details To fix it set ``pipelining = True`` in `/etc/ansible/ansible.cfg`. @@ -651,7 +651,7 @@ but you can still access the original via ``hostvars``:: original_host: "{{ hostvars[inventory_hostname]['ansible_host'] }}" -This works for all overriden connection variables, like ``ansible_user``, ``ansible_port``, etc. +This works for all overridden connection variables, like ``ansible_user``, ``ansible_port``, etc. .. _scp_protocol_error_filename: diff --git a/docs/docsite/rst/scenario_guides/guide_aci.rst b/docs/docsite/rst/scenario_guides/guide_aci.rst index e71e39bd65..d112646202 100644 --- a/docs/docsite/rst/scenario_guides/guide_aci.rst +++ b/docs/docsite/rst/scenario_guides/guide_aci.rst @@ -611,7 +611,7 @@ The :ref:`aci_rest <aci_rest_module>` module is a wrapper around the APIC REST A All below issues either have been reported to the vendor, and most can simply be avoided. Too many consecutive API calls may result in connection throttling - Starting with ACI v3.1 the APIC will actively throttle password-based authenticated connection rates over a specific treshold. This is as part of an anti-DDOS measure but can act up when using Ansible with ACI using password-based authentication. Currently, one solution is to increase this threshold within the nginx configuration, but using signature-based authentication is recommended. + Starting with ACI v3.1 the APIC will actively throttle password-based authenticated connection rates over a specific threshold. This is as part of an anti-DDOS measure but can act up when using Ansible with ACI using password-based authentication. Currently, one solution is to increase this threshold within the nginx configuration, but using signature-based authentication is recommended. **NOTE:** It is advisable to use signature-based authentication with ACI as it not only prevents connection-throttling, but also improves general performance when using the ACI modules. diff --git a/docs/docsite/rst/scenario_guides/guide_vagrant.rst b/docs/docsite/rst/scenario_guides/guide_vagrant.rst index 5ec362bf85..f49477b040 100644 --- a/docs/docsite/rst/scenario_guides/guide_vagrant.rst +++ b/docs/docsite/rst/scenario_guides/guide_vagrant.rst @@ -33,19 +33,13 @@ Ansible provisioner to manage a single machine: .. code-block:: ruby - # This guide is optimized for Vagrant 1.7 and above. - # Although versions 1.6.x should behave very similarly, it is recommended - # to upgrade instead of disabling the requirement below. - Vagrant.require_version ">= 1.7.0" + # This guide is optimized for Vagrant 1.8 and above. + # Older versions of Vagrant put less info in the inventory they generate. + Vagrant.require_version ">= 1.8.0" Vagrant.configure(2) do |config| - config.vm.box = "ubuntu/trusty64" - - # Disable the new default behavior introduced in Vagrant 1.7, to - # ensure that all Vagrant machines will use the same SSH key pair. - # See https://github.com/hashicorp/vagrant/issues/5005 - config.ssh.insert_key = false + config.vm.box = "ubuntu/bionic64" config.vm.provision "ansible" do |ansible| ansible.verbose = "v" @@ -85,7 +79,7 @@ illustrated by this example: .. code-block:: bash - $ PYTHONUNBUFFERED=1 ANSIBLE_FORCE_COLOR=true ANSIBLE_HOST_KEY_CHECKING=false ANSIBLE_SSH_ARGS='-o UserKnownHostsFile=/dev/null -o ControlMaster=auto -o ControlPersist=60s' ansible-playbook --private-key=/home/someone/.vagrant.d/insecure_private_key --user=vagrant --connection=ssh --limit='machine1' --inventory-file=/home/someone/coding-in-a-project/.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory playbook.yml + $ PYTHONUNBUFFERED=1 ANSIBLE_FORCE_COLOR=true ANSIBLE_HOST_KEY_CHECKING=false ANSIBLE_SSH_ARGS='-o UserKnownHostsFile=/dev/null -o IdentitiesOnly=yes -o ControlMaster=auto -o ControlPersist=60s' ansible-playbook --connection=ssh --timeout=30 --limit="default" --inventory-file=/home/someone/coding-in-a-project/.vagrant/provisioners/ansible/inventory -v playbook.yml This information can be quite useful to debug integration issues and can also be used to manually execute Ansible from a shell, as explained in the next @@ -109,26 +103,15 @@ single machine environment may look something like this: # Generated by Vagrant - default ansible_ssh_host=127.0.0.1 ansible_ssh_port=2222 + default ansible_host=127.0.0.1 ansible_port=2222 ansible_user='vagrant' ansible_ssh_private_key_file='/home/someone/coding-in-a-project/.vagrant/machines/default/virtualbox/private_key' If you want to run Ansible manually, you will want to make sure to pass ``ansible`` or ``ansible-playbook`` commands the correct arguments, at least -for the *username*, the *SSH private key* and the *inventory*. - -Here is an example using the Vagrant global insecure key (``config.ssh.insert_key`` -must be set to ``false`` in your ``Vagrantfile``): - -.. code-block:: bash - - $ ansible-playbook --private-key=~/.vagrant.d/insecure_private_key -u vagrant -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory playbook.yml - -Here is a second example using the random private key that Vagrant 1.7+ -automatically configures for each new VM (each key is stored in a path like -``.vagrant/machines/[machine name]/[provider]/private_key``): +for the *inventory*. .. code-block:: bash - $ ansible-playbook --private-key=.vagrant/machines/default/virtualbox/private_key -u vagrant -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory playbook.yml + $ ansible-playbook -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory playbook.yml Advanced Usages ``````````````` @@ -136,7 +119,7 @@ Advanced Usages The "Tips and Tricks" chapter of the `Ansible Provisioner documentation <https://www.vagrantup.com/docs/provisioning/ansible.html>`_ provides detailed information about more advanced Ansible features like: - - how to parallely execute a playbook in a multi-machine environment + - how to execute a playbook in parallel within a multi-machine environment - how to integrate a local ``ansible.cfg`` configuration file .. seealso:: diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst index fb5c71522f..620f8e0aaf 100644 --- a/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst +++ b/docs/docsite/rst/scenario_guides/vmware_scenarios/scenario_remove_vm.rst @@ -41,7 +41,7 @@ Caveats - All variable names and VMware object names are case sensitive. - You need to use Python 2.7.9 version in order to use ``validate_certs`` option, as this version is capable of changing the SSL verification behaviours. -- ``vmware_guest`` module tries to mimick VMware Web UI and workflow, so the virtual machine must be in powered off state in order to remove it from the VMware inventory. +- ``vmware_guest`` module tries to mimic VMware Web UI and workflow, so the virtual machine must be in powered off state in order to remove it from the VMware inventory. .. warning:: diff --git a/docs/docsite/rst/user_guide/collections_using.rst b/docs/docsite/rst/user_guide/collections_using.rst index 3a180a7a0f..61f04749eb 100644 --- a/docs/docsite/rst/user_guide/collections_using.rst +++ b/docs/docsite/rst/user_guide/collections_using.rst @@ -12,6 +12,8 @@ You can install and use collections through `Ansible Galaxy <https://galaxy.ansi :local: :depth: 2 +.. _collections_installing: + Installing collections ====================== @@ -49,6 +51,10 @@ You can also keep a collection adjacent to the current playbook, under a ``colle │ └── my_collection/<collection structure lives here> +See :ref:`collection_structure` for details on the collection directory structure. + +.. _collections_older_version: + Installing an older version of a collection ------------------------------------------- diff --git a/docs/docsite/rst/user_guide/playbooks_best_practices.rst b/docs/docsite/rst/user_guide/playbooks_best_practices.rst index 3ce8dfd700..a63c56c1c6 100644 --- a/docs/docsite/rst/user_guide/playbooks_best_practices.rst +++ b/docs/docsite/rst/user_guide/playbooks_best_practices.rst @@ -427,7 +427,7 @@ Alternatively, if only variables are needed:: - hosts: all tasks: - - name: Set OS distribution dependant variables + - name: Set OS distribution dependent variables include_vars: "os_{{ ansible_facts['distribution'] }}.yml" - debug: var: asdf diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst index dca9cf9fa8..aff571a03c 100644 --- a/docs/docsite/rst/user_guide/playbooks_filters.rst +++ b/docs/docsite/rst/user_guide/playbooks_filters.rst @@ -286,7 +286,7 @@ To always exhaust all list use ``zip_longest``:: msg: "{{ [1,2,3] | zip_longest(['a','b','c','d','e','f'], [21, 22, 23], fillvalue='X') | list }}" -Similarly to the output of the ``items2dict`` filter mentioned above, these filters can be used to contruct a ``dict``:: +Similarly to the output of the ``items2dict`` filter mentioned above, these filters can be used to construct a ``dict``:: {{ dict(keys_list | zip(values_list)) }} @@ -565,7 +565,7 @@ Or, alternatively print out the ports in a comma separated string:: .. note:: Here, quoting literals using backticks avoids escaping quotes and maintains readability. -Or, using YAML `single quote escaping <http://yaml.org/spec/current.html#id2534365>`_:: +Or, using YAML `single quote escaping <https://yaml.org/spec/current.html#id2534365>`_:: - name: "Display all ports from cluster1" debug: @@ -824,7 +824,7 @@ To sort a VLAN list:: {{ [3003, 3004, 3005, 100, 1688, 3002, 3999] | vlan_parser }} -This example renders the folllowing sorted list:: +This example renders the following sorted list:: ['100,1688,3002-3005,3999'] diff --git a/docs/docsite/rst/user_guide/playbooks_variables.rst b/docs/docsite/rst/user_guide/playbooks_variables.rst index 53bbafd27f..b5dd80788b 100644 --- a/docs/docsite/rst/user_guide/playbooks_variables.rst +++ b/docs/docsite/rst/user_guide/playbooks_variables.rst @@ -1229,7 +1229,7 @@ For information about advanced YAML syntax used to declare variables and have mo Best practices in playbooks :ref:`special_variables` List of special variables - `User Mailing List <http://groups.google.com/group/ansible-devel>`_ + `User Mailing List <https://groups.google.com/group/ansible-devel>`_ Have a question? Stop by the google group! `irc.freenode.net <http://irc.freenode.net>`_ #ansible IRC chat channel diff --git a/docs/docsite/rst/user_guide/windows_dsc.rst b/docs/docsite/rst/user_guide/windows_dsc.rst index 649c1d0998..a78f09b8eb 100644 --- a/docs/docsite/rst/user_guide/windows_dsc.rst +++ b/docs/docsite/rst/user_guide/windows_dsc.rst @@ -84,7 +84,7 @@ used - in this case the ``resource_name`` should be set to ``Registry``. The installed; if left blank it will default to the latest version. The other options are parameters that are used to define the resource, such as ``Key`` and ``ValueName``. While the options in the task are not case sensitive, -keeping the case as-is is recommended becuase it makes it easier to distinguish DSC +keeping the case as-is is recommended because it makes it easier to distinguish DSC resource options from Ansible's ``win_dsc`` options. This is what the Ansible task version of the above DSC Registry resource would look like: diff --git a/docs/docsite/rst/user_guide/windows_usage.rst b/docs/docsite/rst/user_guide/windows_usage.rst index 6ce5dea2d3..245db79664 100644 --- a/docs/docsite/rst/user_guide/windows_usage.rst +++ b/docs/docsite/rst/user_guide/windows_usage.rst @@ -388,7 +388,7 @@ standard: .. Note:: You should only quote strings when it is absolutely necessary or required by YAML, and then use single quotes. -The YAML specification considers the following `escape sequences <http://yaml.org/spec/current.html#id2517668>`_: +The YAML specification considers the following `escape sequences <https://yaml.org/spec/current.html#id2517668>`_: * ``\0``, ``\\``, ``\"``, ``\_``, ``\a``, ``\b``, ``\e``, ``\f``, ``\n``, ``\r``, ``\t``, ``\v``, ``\L``, ``\N`` and ``\P`` -- Single character escape diff --git a/lib/ansible/config/base.yml b/lib/ansible/config/base.yml index 5de0f5c9bc..40c554537f 100644 --- a/lib/ansible/config/base.yml +++ b/lib/ansible/config/base.yml @@ -1655,7 +1655,7 @@ PERSISTENT_CONNECT_TIMEOUT: PERSISTENT_CONNECT_RETRY_TIMEOUT: name: Persistence connection retry timeout default: 15 - description: This controls the retry timeout for presistent connection to connect to the local domain socket. + description: This controls the retry timeout for persistent connection to connect to the local domain socket. env: [{name: ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT}] ini: - {key: connect_retry_timeout, section: persistent_connection} @@ -1663,7 +1663,7 @@ PERSISTENT_CONNECT_RETRY_TIMEOUT: PERSISTENT_COMMAND_TIMEOUT: name: Persistence command timeout default: 30 - description: This controls the amount of time to wait for response from remote device before timing out presistent connection. + description: This controls the amount of time to wait for response from remote device before timing out persistent connection. env: [{name: ANSIBLE_PERSISTENT_COMMAND_TIMEOUT}] ini: - {key: command_timeout, section: persistent_connection} diff --git a/lib/ansible/modules/cloud/ovirt/ovirt_disk.py b/lib/ansible/modules/cloud/ovirt/ovirt_disk.py index 4ffac7d2aa..961d682615 100644 --- a/lib/ansible/modules/cloud/ovirt/ovirt_disk.py +++ b/lib/ansible/modules/cloud/ovirt/ovirt_disk.py @@ -120,6 +120,7 @@ options: description: - "I(True) if the disk should be bootable. By default when disk is created it isn't bootable." type: bool + default: 'no' shareable: description: - "I(True) if the disk should be shareable. By default when disk is created it isn't shareable." @@ -254,7 +255,7 @@ EXAMPLES = ''' # Export disk as image to Glance domain # Since Ansible 2.4 -- ovirt_disks: +- ovirt_disk: id: 7de90f31-222c-436c-a1ca-7e655bd5b60c image_provider: myglance state: exported |