From ceb474bb9e95058bd0cd031e01707754377cff2c Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 19 Sep 2018 23:02:01 -0400 Subject: [PATCH] [WIP] Backport/2.7/batch port (#45859) Batch of docs backports: * docs: Clarify include_task v import_tasks with conditionals (#43856) (cherry picked from commit 6be42a2a0ec6afb1e8a2f5f48bef4e9c1588dd34) * Add single quotes around package name (#45152) (cherry picked from commit 0d81386144298af42810fbf4d88668c67425d29c) * prefer ansible_facts namespace and dict notation (#44980) (cherry picked from commit 44510448b07c16bbf7767076e2392f47dcb7e824) * fix cherrypick conflict - scenario_guides * Update implicit_localhost.rst (#45455) (cherry picked from commit f68cd1acc65fe7914f4adda7eb3b6f2b1a78ef1e) * updated fbsd install instructions (#45309) (cherry picked from commit e9c2695ce745cf42d1c69166d838ad17555d8b99) * Change "Defaulting Undefined Variables" (#41379) (cherry picked from commit e35c4be1c1a5e40d1b5e2b33ac04e83e4a5fc4e7) * adds license details to dev guide pages (#45574) (cherry picked from commit 6e68d77f6dde19f5eb5c77e5f0829958597c2333) * FAQ: fix a typo, add link to 'vars' lookup (#42412) (cherry picked from commit 95649dc793e178b9b9d796865db0a1ce2c2c2355) * Fix link and toctree (#45595) (cherry picked from commit 6999bf318f7c786abdabdfa9c129a5151172cd61) * Improve the local toctree (and title) (#45590) (cherry picked from commit afea00fa9fe3e5a04b17e4016e61b9399d4a1a50) * Add undocumented configuration parameter and explain in porting guide (#36059) (cherry picked from commit a892a6ef03a0b4e0e6fc7b66c20f82154cad8a8d) * Simplify PPA installation for Ubuntu (#45690) (cherry picked from commit 78e9f452a5bb9d2c8b1d1ae9bdaa3bd86e1b972b) * adding git+ssh uri scheme (#36025) (cherry picked from commit 84a42577740b14d77e9571dfd242261b91283d94) * Add workaround for non-standard kerberos environments (#41465) (cherry picked from commit 4e532e0ad99396cbfc5dd32a0b02efcc57523b99) * Restore license agreement (#45809) (cherry picked from commit f430f60541899792356efd3ba7f31f7324731f10) * partial cherry-pick - lenovo doc update PR 45483 --- .../rst/community/committer_guidelines.rst | 30 ++++---- docs/docsite/rst/community/communication.rst | 18 ++--- .../contributor_license_agreement.rst | 7 ++ .../rst/community/development_process.rst | 3 +- docs/docsite/rst/community/github_admins.rst | 13 ++-- docs/docsite/rst/community/how_can_I_help.rst | 23 +++--- docs/docsite/rst/community/index.rst | 19 +++-- docs/docsite/rst/community/maintainers.rst | 12 +-- .../rst/community/release_managers.rst | 27 ++++--- .../community/reporting_bugs_and_features.rst | 2 +- .../dev_guide/developing_module_utilities.rst | 2 + .../developing_modules_checklist.rst | 3 +- .../developing_modules_general_windows.rst | 9 ++- docs/docsite/rst/dev_guide/index.rst | 5 +- .../rst/dev_guide/style_guide/index.rst | 26 +++---- .../rst/dev_guide/style_guide/why_use.rst | 4 +- .../sanity/ansible-var-precedence-check.rst | 2 +- .../dev_guide/testing/sanity/docs-build.rst | 2 +- .../testing/sanity/no-wildcard-import.rst | 2 +- .../testing/sanity/pylint-ansible-test.rst | 2 +- .../docsite/rst/dev_guide/testing_compile.rst | 2 + .../rst/dev_guide/testing_documentation.rst | 2 + .../rst/dev_guide/testing_httptester.rst | 2 + .../rst/dev_guide/testing_integration.rst | 2 + docs/docsite/rst/dev_guide/testing_pep8.rst | 2 + .../rst/dev_guide/testing_running_locally.rst | 11 +-- docs/docsite/rst/dev_guide/testing_sanity.rst | 4 +- docs/docsite/rst/dev_guide/testing_units.rst | 21 +++--- .../rst/dev_guide/testing_units_modules.rst | 42 ++++++----- .../dev_guide/testing_validate-modules.rst | 2 + docs/docsite/rst/index.rst | 17 ++--- .../installation_guide/intro_installation.rst | 23 +++++- .../rst/inventory/implicit_localhost.rst | 3 + .../rst/network/user_guide/platform_cnos.rst | 69 +++++++++++++++++ .../rst/network/user_guide/platform_enos.rst | 69 +++++++++++++++++ .../rst/network/user_guide/platform_index.rst | 6 ++ .../rst/porting_guides/porting_guide_2.5.rst | 15 ++++ docs/docsite/rst/reference_appendices/faq.rst | 4 +- .../rst/reference_appendices/galaxy.rst | 2 +- .../rst/scenario_guides/guide_azure.rst | 2 +- docs/docsite/rst/scenario_guides/guides.rst | 24 +++--- docs/docsite/rst/user_guide/intro.rst | 2 + .../rst/user_guide/module_defaults_config.rst | 5 +- .../rst/user_guide/playbook_pathing.rst | 8 +- .../user_guide/playbooks_best_practices.rst | 12 +-- .../rst/user_guide/playbooks_blocks.rst | 2 +- .../rst/user_guide/playbooks_conditionals.rst | 75 +++++++++++-------- .../rst/user_guide/playbooks_filters.rst | 4 +- .../rst/user_guide/playbooks_reuse_roles.rst | 6 +- .../rst/user_guide/playbooks_tests.rst | 10 +-- .../rst/user_guide/playbooks_variables.rst | 30 +++++--- docs/docsite/rst/user_guide/windows_dsc.rst | 3 +- docs/docsite/rst/user_guide/windows_setup.rst | 1 + docs/docsite/rst/user_guide/windows_usage.rst | 1 + docs/docsite/rst/user_guide/windows_winrm.rst | 3 + examples/ansible.cfg | 9 +++ test/sanity/code-smell/docs-build.py | 1 - 57 files changed, 478 insertions(+), 229 deletions(-) create mode 100644 docs/docsite/rst/community/contributor_license_agreement.rst create mode 100644 docs/docsite/rst/network/user_guide/platform_cnos.rst create mode 100644 docs/docsite/rst/network/user_guide/platform_enos.rst diff --git a/docs/docsite/rst/community/committer_guidelines.rst b/docs/docsite/rst/community/committer_guidelines.rst index 5e91e758fab..8b9de8cf4cc 100644 --- a/docs/docsite/rst/community/committer_guidelines.rst +++ b/docs/docsite/rst/community/committer_guidelines.rst @@ -1,24 +1,25 @@ .. _community_committer_guidelines: -Committers Guidelines (for people with commit rights to Ansible on GitHub) -`````````````````````````````````````````````````````````````````````````` +********************* +Committers Guidelines +********************* -These are the guidelines for people with commit access to Ansible. Committers are essentially acting as members of the Ansible Core team, although not necessarily as an employee of Ansible and Red Hat. Please read the guidelines before you commit. +These are the guidelines for people with commit privileges on the Ansible GitHub repository. Committers are essentially acting as members of the Ansible Core team, although not necessarily as employees of Ansible and Red Hat. Please read the guidelines before you commit. These guidelines apply to everyone. At the same time, this ISN'T a process document. So just use good judgement. You've been given commit access because we trust your judgement. -That said, use the trust wisely. +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 access to do so. +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. -Features, High Level Design, and Roadmap +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, 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. 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. -Our Workflow on GitHub +Our workflow on GitHub ====================== As a committer, you may already know this, but our workflow forms a lot of our team policies. Please ensure you're aware of the following workflow steps: @@ -29,19 +30,19 @@ As a committer, you may already know this, but our workflow forms a lot of our t * Adjust code as necessary based on the Comments provided * Ask someone on the Core Team to do a final review and merge -Addendum to workflow for Committers: +Addendum to workflow for committers: ------------------------------------ -The Core Team is aware that this can be a difficult process at times. Sometimes, the team breaks the rules: Direct commits, merging their own PRs. This section is a set of guidelines. If you're changing a comma in a doc, or making a very minor change, you can use your best judgement. This is another trust thing. The process is critical for any major change, but for little things or getting something done quickly, use your best judgement and make sure people on the team are aware of your work. +The Core Team is aware that this can be a difficult process at times. Sometimes, the team breaks the rules by making direct commits or merging their own PRs. This section is a set of guidelines. If you're changing a comma in a doc, or making a very minor change, you can use your best judgement. This is another trust thing. The process is critical for any major change, but for little things or getting something done quickly, use your best judgement and make sure people on the team are aware of your work. 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. -* Module Owners: Module Owners own specific modules and have indirect commit access via the current module PR mechanisms. +* 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 `: Module maintainers own specific modules and have indirect commit access via the current module PR mechanisms. -General Rules +General rules ============= -Individuals with direct commit access to ansible/ansible are entrusted with powers that allow them to do a broad variety of things--probably more than we can write down. Rather than rules, treat these as general *guidelines*, individuals with this power are expected to use their best judgement. +Individuals with direct commit access to ansible/ansible are entrusted with powers that allow them to do a broad variety of things--probably more than we can write down. Rather than rules, treat these as general *guidelines*, individuals with this power are expected to use their best judgement. * Don't @@ -64,11 +65,12 @@ Individuals with direct commit access to ansible/ansible are entrusted with powe - Consider scope, sometimes a fix can be generalized - Keep it simple, then things are maintainable, debuggable and intelligible. -Committers are expected to continue to follow the same community and contribution guidelines followed by the rest of the Ansible community. +Committers are expected to continue to follow the same community and contribution guidelines followed by the rest of the Ansible community. 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. +---------------------+----------------------+--------------------+----------------------+ diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst index e905d0ce2ca..8be6f94c76f 100644 --- a/docs/docsite/rst/community/communication.rst +++ b/docs/docsite/rst/community/communication.rst @@ -11,7 +11,7 @@ Code of Conduct Please read and understand the :ref:`code_of_conduct`. -Mailing List Information +Mailing list information ======================== Ansible has several mailing lists. Your first post to the mailing list will be moderated (to reduce spam), so please allow up to a day or so for your first post to appear. @@ -28,12 +28,12 @@ Ansible has several mailing lists. Your first post to the mailing list will be To subscribe to a group from a non-Google account, you can send an email to the subscription address requesting the subscription. For example: `ansible-devel+subscribe@googlegroups.com` -IRC Channel -=========== +IRC channels +============ Ansible has several IRC channels on Freenode (irc.freenode.net). -General Channels +General channels ---------------- - ``#ansible`` - For general use questions and support. @@ -41,8 +41,8 @@ General Channels - ``#ansible-meeting`` - For public community meetings. We will generally announce these on one or more of the above mailing lists. See the `meeting schedule and agenda page `_ - ``#ansible-notices`` - Mostly bot output from things like GitHub, etc. -Working Group -------------- +Working groups +-------------- - ``#ansible-aws`` - For discussions on Amazon Web Services. - ``#ansible-community`` - Channel for discussing Ansible Community related things. @@ -54,20 +54,20 @@ Working Group - ``#ansible-windows`` - For discussions on Ansible & Windows. -Language specific channels +Language-specific channels -------------------------- - ``#ansible-es`` - Channel for Spanish speaking Ansible community. - ``#ansible-fr`` - Channel for French speaking Ansible community. -IRC Meetings +IRC meetings ------------ The Ansible community holds regular IRC meetings on various topics, and anyone who is interested is invited to participate. For more information about Ansible meetings, consult the `meeting schedule and agenda page `_. -Tower Support Questions +Tower support questions ======================== Ansible `Tower `_ is a UI, Server, and REST endpoint for Ansible. diff --git a/docs/docsite/rst/community/contributor_license_agreement.rst b/docs/docsite/rst/community/contributor_license_agreement.rst new file mode 100644 index 00000000000..b0a0f11736c --- /dev/null +++ b/docs/docsite/rst/community/contributor_license_agreement.rst @@ -0,0 +1,7 @@ +.. _contributor_license_agreement: + +****************************** +Contributors License Agreement +****************************** + +By contributing you agree that these contributions are your own (or approved by your employer) and you grant a full, complete, irrevocable copyright license to all users and developers of the project, present and future, pursuant to the license of the project. diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 8245721f970..1942f059659 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -1,7 +1,8 @@ .. _community_development_process: +******************************* The Ansible Development Process -=============================== +******************************* .. contents:: Topics diff --git a/docs/docsite/rst/community/github_admins.rst b/docs/docsite/rst/community/github_admins.rst index 185d95ac547..5fa837b57c0 100644 --- a/docs/docsite/rst/community/github_admins.rst +++ b/docs/docsite/rst/community/github_admins.rst @@ -1,22 +1,23 @@ +************* GitHub Admins -============= +************* .. contents:: Topics -GitHub Admins have more permissions on GitHub than normal contributors. There are +GitHub Admins have more permissions on GitHub than normal contributors or even committers. There are a few responsibilities that come with that increased power. -Add and Remove Committers -------------------------- +Adding and removing committers +============================== The Ansible Team will periodically review who is actively contributing to Ansible to grant or revoke contributors' ability to commit on their own. GitHub Admins are the people who have the power to actually manage the GitHub permissions. -Change Branch Permissions for Release -------------------------------------- +Changing branch permissions for releases +======================================== When we make releases we make people go through a :ref:`release_managers` to push commits to that branch. The GitHub admins are responsible for setting the branch so only the Release Manager can diff --git a/docs/docsite/rst/community/how_can_I_help.rst b/docs/docsite/rst/community/how_can_I_help.rst index 95c2ac182ef..be4c24d2a84 100644 --- a/docs/docsite/rst/community/how_can_I_help.rst +++ b/docs/docsite/rst/community/how_can_I_help.rst @@ -1,5 +1,6 @@ -How To Help -=========== +*************** +How can I help? +*************** .. contents:: Topics @@ -8,7 +9,7 @@ Thanks for being interested in helping the Ansible project! There are many ways to help the Ansible project...but first, please read and understand the :ref:`code_of_conduct`. Become a power user -------------------- +=================== A great way to help the Ansible project is to become a power user: @@ -21,21 +22,21 @@ A great way to help the Ansible project is to become a power user: When you become a power user, your ability and opportunities to help the Ansible project in other ways will multiply quickly. Ask and answer questions online -------------------------------- +=============================== There are many forums online where Ansible users ask and answer questions. Reach out and communicate with your fellow Ansible users. You can find the official :ref:`Ansible communication channels `. Participate in your local meetup --------------------------------- +================================ There are Ansible meetups `all over the world `_. Join your local meetup. Attend regularly. Ask good questions. Volunteer to give a presentation about how you use Ansible. If there isn't a meetup near you, we'll be happy to help you `start one `_. File and verify issues ----------------------- +====================== All software has bugs, and Ansible is no exception. When you find a bug, you can help tremendously by :ref:`telling us about it `. @@ -43,31 +44,31 @@ All software has bugs, and Ansible is no exception. When you find a bug, you can If you should discover that the bug you're trying to file already exists in an issue, you can help by verifying the behavior of the reported bug with a comment in that issue, or by reporting any additional information. Review and submit pull requests -------------------------------- +=============================== As you become more familiar with how Ansible works, you may be able to fix issues or develop new features yourself. If you think you've got a solution to a bug you've found in Ansible, or if you've got a new feature that you've written and would like to share with millions of Ansible users, read all about the :ref:`Ansible development process ` to learn how to get your code accepted into Ansible. Another good way to help is to review pull requests that other Ansible users have submitted. The Ansible community keeps a full list of `open pull requests by file `_, so if there's a particular module or plug-in that particularly interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. Become a module maintainer --------------------------- +========================== Once you've learned about the development process and have contributed code to a particular module, we encourage you to become a maintainer of that module. There are hundreds of different modules in Ansible, and the vast majority of them are written and maintained entirely by members of the Ansible community. To learn more about the responsibilities of being an Ansible module maintainer, please read our :ref:`module maintainer guidelines `. Join a working group --------------------- +==================== Working groups are a way for Ansible community members to self-organize around particular topics of interest. We have working groups around various topics. To join or create a working group, please read the `Ansible working group guidelines `_. Teach Ansible to others ------------------------ +======================= We're working on a standardized Ansible workshop called `Lightbulb `_ that can provide a good hands-on introduction to Ansible usage and concepts. Social media ------------- +============ If you like Ansible and just want to spread the good word, feel free to share on your social media platform of choice, and let us know by using ``@ansible`` or ``#ansible``. We'll be looking for you. diff --git a/docs/docsite/rst/community/index.rst b/docs/docsite/rst/community/index.rst index ba066d86969..47de8cce147 100644 --- a/docs/docsite/rst/community/index.rst +++ b/docs/docsite/rst/community/index.rst @@ -10,19 +10,24 @@ The purpose of this guide is to teach you everything you need to know about bein To get started, please read and understand the :ref:`code_of_conduct`, and then select one of the following topics. - .. toctree:: :maxdepth: 2 code_of_conduct - development_process - reporting_bugs_and_features how_can_I_help - maintainers - release_managers + reporting_bugs_and_features communication + development_process + contributor_license_agreement + triage_process other_tools_and_programs - - + ../dev_guide/style_guide/index +.. toctree:: + :caption: Guidelines for specific types of contributors + :maxdepth: 2 + committer_guidelines + maintainers + release_managers + github_admins diff --git a/docs/docsite/rst/community/maintainers.rst b/docs/docsite/rst/community/maintainers.rst index eda54a43173..2f3a36a29a7 100644 --- a/docs/docsite/rst/community/maintainers.rst +++ b/docs/docsite/rst/community/maintainers.rst @@ -14,7 +14,7 @@ In addition to the information below, module maintainers should be familiar with * Documentation on :ref:`module development ` -Maintainer Responsibilities +Maintainer responsibilities =========================== When you contribute a new module to the `ansible/ansible `_ repository, you become the maintainer for that module once it has been merged. Maintainership empowers you with the authority to accept, reject, or request revisions to pull requests on your module -- but as they say, "with great power comes great responsibility." @@ -27,10 +27,10 @@ Finally, following the `ansible-devel `_. @@ -44,7 +44,7 @@ Issues for modules, including bug reports, documentation bug reports, and featur 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. -PR Workflow +PR workflow ----------- Automated routing of pull requests is handled by a tool called `Ansibot `_. @@ -58,8 +58,8 @@ Maintainers (BOTMETA.yml) The full list of maintainers is located in `BOTMETA.yml `_. -Changing Maintainership ------------------------ +Adding and removing maintainers +=============================== Communities change over time, and no one maintains a module forever. If you'd like to propose an additional maintainer for your module, please submit a PR to ``BOTMETA.yml`` with the GitHub username of the new maintainer. diff --git a/docs/docsite/rst/community/release_managers.rst b/docs/docsite/rst/community/release_managers.rst index 3ad59ead1fa..40dfdc90e64 100644 --- a/docs/docsite/rst/community/release_managers.rst +++ b/docs/docsite/rst/community/release_managers.rst @@ -1,23 +1,22 @@ .. _release_managers: - -Release Managers -================ +************************** +Release manager guidelines +************************** .. contents:: Topics The release manager's purpose is to ensure a smooth release. To achieve that goal, they need to coordinate between: -* Developers with Commit privileges on the `Ansible github repository `_ +* Developers with commit privileges on the `Ansible GitHub repository `_ * Contributors without commit privileges * The community * Ansible documentation team * Ansible Tower team - -Pre-releases: What and Why --------------------------- +Pre-releases: what and why +========================== Pre-releases exist to draw testers. They give people who don't feel comfortable running from source control a means to get an early version of the code to test and give us feedback. To ensure we get @@ -35,18 +34,18 @@ back those changes to give people time to test between. People cannot test what we have to get those tarballs out there even if people feel they have to install more frequently. -What is Beta? -~~~~~~~~~~~~~ +Beta releases +------------- -In a Beta release, we know there are still bugs. We will continue to accept fixes for these. +In a beta release, we know there are still bugs. We will continue to accept fixes for these. Although we review these fixes, sometimes they can be invasive or potentially destabilize other areas of the code. During the beta, we will no longer accept feature submissions. -What is a Release Candidate? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Release candidates +------------------ In a release candidate, we've fixed all known blockers. Any remaining bugfixes are ones that we are willing to leave out of the release. At this point we need user testing to @@ -74,8 +73,8 @@ The last RC should be as close to the final as possible. The following things ma (like the Tower Team) which would want to test the code. -Release Process -=============== +Ansible release process +======================= The release process is kept in a `separate document `_ diff --git a/docs/docsite/rst/community/reporting_bugs_and_features.rst b/docs/docsite/rst/community/reporting_bugs_and_features.rst index 1a8c7aa5f7c..a3e2cb71223 100644 --- a/docs/docsite/rst/community/reporting_bugs_and_features.rst +++ b/docs/docsite/rst/community/reporting_bugs_and_features.rst @@ -6,7 +6,7 @@ Reporting Bugs And Requesting Features .. contents:: Topics -Reporting A Bug +Reporting a bug =============== Ansible practices responsible disclosure - if this is a security related bug, email `security@ansible.com `_ instead of filing a ticket or posting to the Google Group and you will receive a prompt response. diff --git a/docs/docsite/rst/dev_guide/developing_module_utilities.rst b/docs/docsite/rst/dev_guide/developing_module_utilities.rst index 3c375de904f..b6795875ebe 100644 --- a/docs/docsite/rst/dev_guide/developing_module_utilities.rst +++ b/docs/docsite/rst/dev_guide/developing_module_utilities.rst @@ -11,6 +11,8 @@ Ansible provides a number of module utilities that provide helper functions that The following is a list of ``module_utils`` files and a general description. The module utility source code lives in the ``./lib/ansible/module_utils`` directory under your main Ansible path - for more details on any specific module utility, please see the source code. +.. include:: shared_snippets/licensing.txt + - api.py - Adds shared support for generic API modules. - azure_rm_common.py - Definitions and utilities for Microsoft Azure Resource Manager template deployments. - basic.py - General definitions and helper utilities for Ansible modules. diff --git a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst index 475e21316c8..f37eeefd0ac 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst @@ -17,7 +17,8 @@ To contribute a module to Ansible, you must: * support Python 2.7 and Python 3.5 - if your module cannot support Python 2.7, explain the required minimum Python version and rationale in the requirements section in ``DOCUMENTATION`` * use proper :ref:`Python 3 syntax ` * follow `PEP 8 `_ Python style conventions - see :ref:`testing_pep8` for more information -* license your module with GPL 3 +* license your module under the GPL license (GPLv3 or later) +* understand the :ref:`license agreement `, which applies to all contributions * conform to Ansible's :ref:`formatting and documentation ` standards * include comprehensive :ref:`tests ` for your module * minimize module dependencies 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 99c1ca1cf84..f5c96f35987 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general_windows.rst @@ -1,8 +1,8 @@ .. _developing_modules_general_windows: -********************************************** -Windows Ansible module development walkthrough -********************************************** +************************************** +Windows module development walkthrough +************************************** In this section, we will walk through developing, testing, and debugging an Ansible Windows module. @@ -12,7 +12,8 @@ Windows host, this guide differs from the usual development walkthrough guide. What's covered in this section: -.. contents:: Topics +.. contents:: + :local: Windows environment setup diff --git a/docs/docsite/rst/dev_guide/index.rst b/docs/docsite/rst/dev_guide/index.rst index d3201347782..c9e006242fd 100644 --- a/docs/docsite/rst/dev_guide/index.rst +++ b/docs/docsite/rst/dev_guide/index.rst @@ -35,7 +35,10 @@ Find the task that best describes what you want to do: * I want to :ref:`connect Ansible to a new source of inventory `. * I want to :ref:`deprecate an outdated module `. -* I want to :ref:`contribute my module or plugin to Ansible Core `. +* I want to contribute back to the Ansible project: + + * I want to :ref:`contribute my module or plugin `. + * I want to :ref:`understand the license agreement ` for contributions to Ansible. If you prefer to read the entire guide, here's a list of the pages in order. diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst index 2f880a3d3b4..0b66ac6ebfc 100644 --- a/docs/docsite/rst/dev_guide/style_guide/index.rst +++ b/docs/docsite/rst/dev_guide/style_guide/index.rst @@ -3,29 +3,29 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -==================================== +******************* Ansible Style Guide -==================================== +******************* -.. Welcome to Ansible Style Guide's documentation! =============================================== +Welcome to the Ansible Style Guide +================================== + +Follow these guidelines to create clear, concise, useful community contributions and documentation. This guide helps us make the content on ansible.com consistent. .. toctree:: :maxdepth: 1 - :numbered: - self - why_use - resources basic_rules voice_style trademarks grammar_punctuation - spelling_word_choice - + spelling_word_choice + resources + -.. Indices and tables -.. ================== +.. Indices and tables +.. ================== -.. * :ref:`genindex` -.. * :ref:`modindex` +.. * :ref:`genindex` +.. * :ref:`modindex` .. * :ref:`search` diff --git a/docs/docsite/rst/dev_guide/style_guide/why_use.rst b/docs/docsite/rst/dev_guide/style_guide/why_use.rst index 3740eb17e0a..0c1bf51ae22 100644 --- a/docs/docsite/rst/dev_guide/style_guide/why_use.rst +++ b/docs/docsite/rst/dev_guide/style_guide/why_use.rst @@ -1,3 +1,5 @@ +:orphan: + Why Use a Style Guide? ````````````````````````````````` @@ -15,7 +17,7 @@ This style guide incorporates current Ansible resources and information so that "If you don't find it in the index, look very carefully through the entire catalogue." ― Sears, Roebuck and Co., 1897 Sears Roebuck & Co. Catalogue - + .. raw:: html diff --git a/docs/docsite/rst/dev_guide/testing/sanity/ansible-var-precedence-check.rst b/docs/docsite/rst/dev_guide/testing/sanity/ansible-var-precedence-check.rst index de1c6844566..f8354c9a375 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/ansible-var-precedence-check.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/ansible-var-precedence-check.rst @@ -1,4 +1,4 @@ -.. orphan: +:orphan: Sanity Tests » ansible-var-precedence-check =========================================== diff --git a/docs/docsite/rst/dev_guide/testing/sanity/docs-build.rst b/docs/docsite/rst/dev_guide/testing/sanity/docs-build.rst index c0d331f4d9c..001d2119137 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/docs-build.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/docs-build.rst @@ -1,4 +1,4 @@ -.. orphan: +:orphan: Sanity Tests » docs-build ========================= diff --git a/docs/docsite/rst/dev_guide/testing/sanity/no-wildcard-import.rst b/docs/docsite/rst/dev_guide/testing/sanity/no-wildcard-import.rst index da4cb813412..04c55a8148b 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/no-wildcard-import.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/no-wildcard-import.rst @@ -1,4 +1,4 @@ -.. orphan: +:orphan: Sanity Tests » no-wildcard-import ================================= diff --git a/docs/docsite/rst/dev_guide/testing/sanity/pylint-ansible-test.rst b/docs/docsite/rst/dev_guide/testing/sanity/pylint-ansible-test.rst index 67b19fdd34a..744d181cda6 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/pylint-ansible-test.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/pylint-ansible-test.rst @@ -1,4 +1,4 @@ -.. orphan: +:orphan: Sanity Tests » pylint-ansible-test ================================== diff --git a/docs/docsite/rst/dev_guide/testing_compile.rst b/docs/docsite/rst/dev_guide/testing_compile.rst index e3310a6903f..773678e6620 100644 --- a/docs/docsite/rst/dev_guide/testing_compile.rst +++ b/docs/docsite/rst/dev_guide/testing_compile.rst @@ -1,3 +1,5 @@ +:orphan: + .. _testing_compile: ************* diff --git a/docs/docsite/rst/dev_guide/testing_documentation.rst b/docs/docsite/rst/dev_guide/testing_documentation.rst index 87baef76ef7..9a36c82e043 100644 --- a/docs/docsite/rst/dev_guide/testing_documentation.rst +++ b/docs/docsite/rst/dev_guide/testing_documentation.rst @@ -1,3 +1,5 @@ +:orphan: + .. _testing_documentation: ********************* diff --git a/docs/docsite/rst/dev_guide/testing_httptester.rst b/docs/docsite/rst/dev_guide/testing_httptester.rst index e77e0107efc..9ae9e72af4c 100644 --- a/docs/docsite/rst/dev_guide/testing_httptester.rst +++ b/docs/docsite/rst/dev_guide/testing_httptester.rst @@ -1,3 +1,5 @@ +:orphan: + ********** httptester ********** diff --git a/docs/docsite/rst/dev_guide/testing_integration.rst b/docs/docsite/rst/dev_guide/testing_integration.rst index 7e783ab6479..79ff88bc33d 100644 --- a/docs/docsite/rst/dev_guide/testing_integration.rst +++ b/docs/docsite/rst/dev_guide/testing_integration.rst @@ -1,3 +1,5 @@ +:orphan: + .. _testing_integration: ***************** diff --git a/docs/docsite/rst/dev_guide/testing_pep8.rst b/docs/docsite/rst/dev_guide/testing_pep8.rst index 66a9517862a..14b235ca16a 100644 --- a/docs/docsite/rst/dev_guide/testing_pep8.rst +++ b/docs/docsite/rst/dev_guide/testing_pep8.rst @@ -1,3 +1,5 @@ +:orphan: + .. _testing_pep8: ***** diff --git a/docs/docsite/rst/dev_guide/testing_running_locally.rst b/docs/docsite/rst/dev_guide/testing_running_locally.rst index 43877097752..0d80d3d81c4 100644 --- a/docs/docsite/rst/dev_guide/testing_running_locally.rst +++ b/docs/docsite/rst/dev_guide/testing_running_locally.rst @@ -1,3 +1,5 @@ +:orphan: + .. _testing_running_locally: *************** @@ -40,13 +42,13 @@ Environment Variables When using environment variables to manipulate tests there some limitations to keep in mind. Environment variables are: -* Not propagated from the host to the test environment when using the ``--docker`` or ``--remote`` options. +* Not propagated from the host to the test environment when using the ``--docker`` or ``--remote`` options. * Not exposed to the test environment unless whitelisted in ``test/runner/lib/util.py`` in the ``common_environment`` function. * Not exposed to the test environment when using the ``--tox`` option unless whitelisted in ``test/runner/tox.ini`` by the ``passenv`` definition. - Example: ``ANSIBLE_KEEP_REMOTE_FILES=1`` can be set when running ``ansible-test integration --tox``. However, using the ``--docker`` option would - require running ``ansible-test shell`` to gain access to the Docker environment. Once at the shell prompt, the environment variable could be set - and the tests executed. This is useful for debugging tests inside a container by following the + Example: ``ANSIBLE_KEEP_REMOTE_FILES=1`` can be set when running ``ansible-test integration --tox``. However, using the ``--docker`` option would + require running ``ansible-test shell`` to gain access to the Docker environment. Once at the shell prompt, the environment variable could be set + and the tests executed. This is useful for debugging tests inside a container by following the :ref:`Debugging AnsibleModule-based modules ` instructions. Interactive Shell @@ -84,4 +86,3 @@ Reports can be generated in several different formats: To clear data between test runs, use the ``ansible-test coverage erase`` command. For a full list of features see the online help:: ansible-test coverage --help - diff --git a/docs/docsite/rst/dev_guide/testing_sanity.rst b/docs/docsite/rst/dev_guide/testing_sanity.rst index 26d8f22f254..607a64a3335 100644 --- a/docs/docsite/rst/dev_guide/testing_sanity.rst +++ b/docs/docsite/rst/dev_guide/testing_sanity.rst @@ -1,3 +1,5 @@ +:orphan: + .. _testing_sanity: ************ @@ -75,5 +77,3 @@ yamllint ~~~~~~~~ Check YAML files for syntax and formatting issues. - - diff --git a/docs/docsite/rst/dev_guide/testing_units.rst b/docs/docsite/rst/dev_guide/testing_units.rst index a9ca7f19604..492059c6723 100644 --- a/docs/docsite/rst/dev_guide/testing_units.rst +++ b/docs/docsite/rst/dev_guide/testing_units.rst @@ -1,3 +1,5 @@ +:orphan: + .. _testing_units: ********** @@ -91,7 +93,7 @@ Structuring Unit Tests Ansible drives unit tests through `pytest `_. This means that tests can either be written a simple functions which are included in any file -name like ``test_.py`` or as classes. +name like ``test_.py`` or as classes. Here is an example of a function:: @@ -102,23 +104,23 @@ Here is an example of a function:: b = 23 c = 33 assert a + b = c - + Here is an example of a class:: import unittest - + class AddTester(unittest.TestCase) - + def SetUp() self.a = 10 self.b = 23 - - # this function will + + # this function will def test_add() c = 33 assert self.a + self.b = c - # this function will + # this function will def test_subtract() c = -13 assert self.a - self.b = c @@ -127,7 +129,7 @@ Both methods work fine in most circumstances; the function-based interface is si quicker and so that's probably where you should start when you are just trying to add a few basic tests for a module. The class-based test allows more tidy set up and tear down of pre-requisites, so if you have many test cases for your module you may want to refactor -to use that. +to use that. Assertions using the simple ``assert`` function inside the tests will give full information on the cause of the failure with a trace-back of functions called during the @@ -202,9 +204,8 @@ reports. :doc:`testing_running_locally` Running tests locally including gathering and reporting coverage data `Python 3 documentation - 26.4. unittest — Unit testing framework `_ - The documentation of the unittest framework in python 3 + The documentation of the unittest framework in python 3 `Python 2 documentation - 25.3. unittest — Unit testing framework `_ The documentation of the earliest supported unittest framework - from Python 2.6 `pytest: helps you write better programs `_ The documentation of pytest - the framework actually used to run Ansible unit tests - diff --git a/docs/docsite/rst/dev_guide/testing_units_modules.rst b/docs/docsite/rst/dev_guide/testing_units_modules.rst index 83317a5a335..3783268220b 100644 --- a/docs/docsite/rst/dev_guide/testing_units_modules.rst +++ b/docs/docsite/rst/dev_guide/testing_units_modules.rst @@ -1,3 +1,5 @@ +:orphan: + .. _testing_units_modules: **************************** @@ -15,7 +17,7 @@ This document explains why, how and when you should use unit tests for Ansible m The document doesn't apply to other parts of Ansible for which the recommendations are normally closer to the Python standard. There is basic documentation for Ansible unit tests in the developer guide :doc:`testing_units`. This document should -be readable for a new Ansible module author. If you find it incomplete or confusing, +be readable for a new Ansible module author. If you find it incomplete or confusing, please open a bug or ask for help on Ansible IRC. What Are Unit Tests? @@ -69,10 +71,10 @@ When To Use Unit Tests There are a number of situations where unit tests are a better choice than integration tests. For example, testing things which are impossible, slow or very difficult to test with integration tests, such as: - + * Forcing rare / strange / random situations that can't be forced, such as specific network failures and exceptions -* Extensive testing of slow configuration APIs +* Extensive testing of slow configuration APIs * Situations where the integration tests cannot be run as part of the main Ansible continuous integraiton running in Shippable. @@ -92,11 +94,11 @@ creating a unit test when bug fixing a module, even if those tests do not often problems later. As a basic goal, every module should have at least one unit test which will give quick feedback in easy cases without having to wait for the integration tests to complete. - + Ensuring correct use of external interfaces ------------------------------------------- -Unit tests can check the way in which external services are run to ensure that they match +Unit tests can check the way in which external services are run to ensure that they match specifications or are as efficient as possible *even when the final output will not be changed*. Example: @@ -113,12 +115,12 @@ which checks that the call happens properly for the old version can help avoid t problem. In this situation it is very important to include version numbering in the test case name (see `Naming unit tests`_ below). -Providing specific design tests +Providing specific design tests -------------------------------- By building a requirement for a particular part of the code and then coding to that requirement, unit tests _can_ sometimes improve the code and -help future developers understand that code. +help future developers understand that code. Unit tests that test internal implementation details of code, on the other hand, almost always do more harm than good. Testing that your packages to install are stored in a list @@ -126,7 +128,7 @@ would slow down and confuse a future developer who might need to change that lis dictionary for efficiency. This problem can be reduced somewhat with clear test naming so that the future developer immediately knows to delete the test case, but it is often better to simply leave out the test case altogether and test for a real valuable feature -of the code, such as installing all of the packages supplied as arguments to the module. +of the code, such as installing all of the packages supplied as arguments to the module. How to unit test Ansible modules @@ -148,7 +150,7 @@ If a unit test is designed to verify compatibility with a specific software or A then include the version in the name of the unit test. As an example, ``test_v2_state_present_should_call_create_server_with_name()`` would be a -good name, ``test_create_server()`` would not be. +good name, ``test_create_server()`` would not be. Use of Mocks @@ -164,16 +166,16 @@ Ensuring failure cases are visible with mock objects ---------------------------------------------------- Functions like :meth:`module.fail_json` are normally expected to terminate execution. When you -run with a mock module object this doesn't happen since the mock always returns another mock +run with a mock module object this doesn't happen since the mock always returns another mock from a function call. You can set up the mock to raise an exception as shown above, or you can assert that these functions have not been called in each test. For example:: module = MagicMock() function_to_test(module, argument) - module.fail_json.assert_not_called() + module.fail_json.assert_not_called() This applies not only to calling the main module but almost any other -function in a module which gets the module object. +function in a module which gets the module object. Mocking of the actual module @@ -193,9 +195,9 @@ above, either by throwing an exception or ensuring that they haven't been called module.exit_json.side_effect = AnsibleExitJson(Exception) with self.assertRaises(AnsibleExitJson) as result: return = my_module.test_this_function(module, argument) - module.fail_json.assert_not_called() + module.fail_json.assert_not_called() assert return["changed"] == True - + API definition with unit test cases ----------------------------------- @@ -237,7 +239,7 @@ This is then used to create a list of states:: simple_instance_list('available', {}), simple_instance_list('available', {}), ] - + These states are then used as returns from a mock object to ensure that the ``await`` function waits through all of the states that would mean the RDS instance has not yet completed configuration:: @@ -269,10 +271,10 @@ The most common are documented below, and suggestions for others can be found by at the source code of the existing unit tests or asking on the Ansible IRC channel or mailing lists. -Module argument processing +Module argument processing -------------------------- -There are two problems with running the main function of a module: +There are two problems with running the main function of a module: * Since the module is supposed to accept arguments on ``STDIN`` it is a bit difficult to set up the arguments correctly so that the module will get them as parameters. @@ -383,7 +385,7 @@ A Complete Example The following example is a complete skeleton that reuses the mocks explained above and adds a new mock for :meth:`Ansible.get_bin_path`:: - + import json from ansible.compat.tests import unittest @@ -546,7 +548,7 @@ the code in Ansible to trigger that failure. :doc:`developing_modules` How to develop modules `Python 3 documentation - 26.4. unittest — Unit testing framework `_ - The documentation of the unittest framework in python 3 + The documentation of the unittest framework in python 3 `Python 2 documentation - 25.3. unittest — Unit testing framework `_ The documentation of the earliest supported unittest framework - from Python 2.6 `pytest: helps you write better programs `_ @@ -560,5 +562,5 @@ the code in Ansible to trigger that failure. Extreme Programming (XP), Clean Coding. Uncle Bob talks through how to benfit from this `"Why Most Unit Testing is Waste" https://rbcs-us.com/documents/Why-Most-Unit-Testing-is-Waste.pdf` An article warning against the costs of unit testing - `'A Response to "Why Most Unit Testing is Waste"' https://henrikwarne.com/2014/09/04/a-response-to-why-most-unit-testing-is-waste/` + `'A Response to "Why Most Unit Testing is Waste"' https://henrikwarne.com/2014/09/04/a-response-to-why-most-unit-testing-is-waste/` An response pointing to how to maintain the value of unit tests diff --git a/docs/docsite/rst/dev_guide/testing_validate-modules.rst b/docs/docsite/rst/dev_guide/testing_validate-modules.rst index 4fe8e1e1b2a..1fe01f4c5ea 100644 --- a/docs/docsite/rst/dev_guide/testing_validate-modules.rst +++ b/docs/docsite/rst/dev_guide/testing_validate-modules.rst @@ -1,3 +1,5 @@ +:orphan: + **************** validate-modules **************** diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst index a94fe09fec7..410e379cbcf 100644 --- a/docs/docsite/rst/index.rst +++ b/docs/docsite/rst/index.rst @@ -47,19 +47,10 @@ Ansible releases a new major release of Ansible approximately every two months. .. toctree:: :maxdepth: 2 + :glob: :caption: Scenario Guides - scenario_guides/guide_aci - scenario_guides/guide_aws - scenario_guides/guide_azure - scenario_guides/guide_cloudstack - scenario_guides/guide_docker - scenario_guides/guide_gce - scenario_guides/guide_packet - scenario_guides/guide_rax - scenario_guides/guide_rolling_upgrade - scenario_guides/guide_vagrant - scenario_guides/guide_vultr + scenario_guides/guide_* .. toctree:: :maxdepth: 2 @@ -74,7 +65,7 @@ Ansible releases a new major release of Ansible approximately every two months. network/index .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Reference & Appendices ../modules/modules_by_category @@ -89,6 +80,8 @@ Ansible releases a new major release of Ansible approximately every two months. dev_guide/testing/sanity/index reference_appendices/faq reference_appendices/glossary + reference_appendices/module_utils + reference_appendices/special_variables reference_appendices/tower diff --git a/docs/docsite/rst/installation_guide/intro_installation.rst b/docs/docsite/rst/installation_guide/intro_installation.rst index 2d50f27e16f..bb4460511d3 100644 --- a/docs/docsite/rst/installation_guide/intro_installation.rst +++ b/docs/docsite/rst/installation_guide/intro_installation.rst @@ -147,8 +147,7 @@ To configure the PPA on your machine and install ansible run these commands: $ sudo apt-get update $ sudo apt-get install software-properties-common - $ sudo apt-add-repository ppa:ansible/ansible - $ sudo apt-get update + $ sudo apt-add-repository --yes --update ppa:ansible/ansible $ sudo apt-get install ansible .. note:: On older Ubuntu distributions, "software-properties-common" is called "python-software-properties". @@ -204,9 +203,19 @@ To install the newest version, you may need to unmask the ansible package prior Latest Releases via pkg (FreeBSD) +++++++++++++++++++++++++++++++++ +Though Ansible works with both Python 2 and 3 versions, FreeBSD has different packages for each Python version. +So to install you can use: + .. code-block:: bash - $ sudo pkg install ansible + $ sudo pkg install py27-ansible + +or: + +.. code-block:: bash + + $ sudo pkg install py36-ansible + You may also wish to install from ports, run: @@ -214,6 +223,14 @@ 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``. + +Older versions of FreeBSD worked with something like this (substitute for your choice of package manager): + +.. code-block:: bash + + $ sudo pkg install ansible + .. _on_macos: Latest Releases on macOS diff --git a/docs/docsite/rst/inventory/implicit_localhost.rst b/docs/docsite/rst/inventory/implicit_localhost.rst index 72696cff3a2..43bf598f091 100644 --- a/docs/docsite/rst/inventory/implicit_localhost.rst +++ b/docs/docsite/rst/inventory/implicit_localhost.rst @@ -1,3 +1,5 @@ +:orphan: + .. _implicit_localhost: Implicit 'localhost' @@ -26,6 +28,7 @@ You can override the built-in implicit version by creating a ``localhost`` host .. note:: - This host is not targetable via any group, however it will use vars from ``host_vars`` and from the 'all' group. + - The ``inventory_file`` and ``inventory_dir`` magic variables are not available for the implicit localhost as they are dependent on **each inventory host**. - This implicit host also gets triggered by using ``127.0.0.1`` or ``::1`` as they are the IPv4 and IPv6 representations of 'localhost'. - Even though there are many ways to create it, there will only ever be ONE implicit localhost, using the name first used to create it. - Having ``connection: local`` does NOT trigger an implicit localhost, you are just changing the connection for the ``inventory_hostname``. diff --git a/docs/docsite/rst/network/user_guide/platform_cnos.rst b/docs/docsite/rst/network/user_guide/platform_cnos.rst new file mode 100644 index 00000000000..f64d836de77 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_cnos.rst @@ -0,0 +1,69 @@ +.. _cnos_platform_options: + +*************************************** +CNOS Platform Options +*************************************** + +CNOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on CNOS in Ansible. + +.. contents:: Topics + +Connections Available +================================================================================ + ++---------------------------+-----------------------------------------------+ +|.. | CLI | ++===========================+===============================================+ +| **Protocol** | SSH | ++---------------------------+-----------------------------------------------+ +| | **Credentials** | | uses SSH keys / SSH-agent if present | +| | | | accepts ``-u myuser -k`` if using password | ++---------------------------+-----------------------------------------------+ +| **Indirect Access** | via a bastion (jump host) | ++---------------------------+-----------------------------------------------+ +| | **Connection Settings** | | ``ansible_connection: network_cli`` | +| | | | | +| | | | | ++---------------------------+-----------------------------------------------+ +| | **Enable Mode** | | supported - use ``ansible_become: yes`` | +| | (Privilege Escalation) | | with ``ansible_become_method: enable`` | +| | | | and ``ansible_become_pass:`` | ++---------------------------+-----------------------------------------------+ +| **Returned Data Format** | ``stdout[0].`` | ++---------------------------+-----------------------------------------------+ + +For legacy playbooks, CNOS still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible. + +Using CLI in Ansible +================================================================================ + +Example CLI ``group_vars/cnos.yml`` +-------------------------------------------------------------------------------- + +.. code-block:: yaml + + ansible_connection: network_cli + ansible_network_os: cnos + ansible_user: myuser + ansible_ssh_pass: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_pass: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_ssh_pass`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. + +Example CLI Task +---------------- + +.. code-block:: yaml + + - name: Retreive CNOS OS version + cnos_command: + commands: show version + when: ansible_network_os == 'cnos' + +.. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_enos.rst b/docs/docsite/rst/network/user_guide/platform_enos.rst new file mode 100644 index 00000000000..6d1aa06f277 --- /dev/null +++ b/docs/docsite/rst/network/user_guide/platform_enos.rst @@ -0,0 +1,69 @@ +.. _enos_platform_options: + +*************************************** +ENOS Platform Options +*************************************** + +ENOS supports Enable Mode (Privilege Escalation). This page offers details on how to use Enable Mode on ENOS in Ansible. + +.. contents:: Topics + +Connections Available +================================================================================ + ++---------------------------+-----------------------------------------------+ +|.. | CLI | ++===========================+===============================================+ +| **Protocol** | SSH | ++---------------------------+-----------------------------------------------+ +| | **Credentials** | | uses SSH keys / SSH-agent if present | +| | | | accepts ``-u myuser -k`` if using password | ++---------------------------+-----------------------------------------------+ +| **Indirect Access** | via a bastion (jump host) | ++---------------------------+-----------------------------------------------+ +| | **Connection Settings** | | ``ansible_connection: network_cli`` | +| | | | | +| | | | | ++---------------------------+-----------------------------------------------+ +| | **Enable Mode** | | supported - use ``ansible_become: yes`` | +| | (Privilege Escalation) | | with ``ansible_become_method: enable`` | +| | | | and ``ansible_become_pass:`` | ++---------------------------+-----------------------------------------------+ +| **Returned Data Format** | ``stdout[0].`` | ++---------------------------+-----------------------------------------------+ + +For legacy playbooks, ENOS still supports ``ansible_connection: local``. We recommend modernizing to use ``ansible_connection: network_cli`` as soon as possible. + +Using CLI in Ansible +================================================================================ + +Example CLI ``group_vars/enos.yml`` +-------------------------------------------------------------------------------- + +.. code-block:: yaml + + ansible_connection: network_cli + ansible_network_os: enos + ansible_user: myuser + ansible_ssh_pass: !vault... + ansible_become: yes + ansible_become_method: enable + ansible_become_pass: !vault... + ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q bastion01"' + + +- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_ssh_pass`` configuration. +- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration. +- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables. + +Example CLI Task +---------------- + +.. code-block:: yaml + + - name: Retreive ENOS OS version + enos_command: + commands: show version + when: ansible_network_os == 'enos' + +.. include:: shared_snippets/SSH_warning.txt diff --git a/docs/docsite/rst/network/user_guide/platform_index.rst b/docs/docsite/rst/network/user_guide/platform_index.rst index 2827e9bc90c..4dfd385d5a5 100644 --- a/docs/docsite/rst/network/user_guide/platform_index.rst +++ b/docs/docsite/rst/network/user_guide/platform_index.rst @@ -10,6 +10,8 @@ Some Ansible Network platforms support multiple connection types, privilege esca :maxdepth: 2 :caption: Platform Options + platform_cnos + platform_enos platform_eos platform_exos platform_ios @@ -58,6 +60,10 @@ Settings by Platform +-------------------+-------------------------+----------------------+----------------------+------------------+------------------+ | Junos OS* | ``junos`` | in v. >=2.5 | in v. >=2.5 | N/A | in v. >=2.4 | +-------------------+-------------------------+----------------------+----------------------+------------------+------------------+ +| Lenovo CNOS | ``cnos`` | in v. >=2.5 | N/A | N/A | in v. >=2.3 | ++-------------------+-------------------------+----------------------+----------------------+------------------+------------------+ +| Lenovo ENOS | ``enos`` | in v. >=2.5 | N/A | N/A | in v. >=2.5 | ++-------------------+-------------------------+----------------------+----------------------+------------------+------------------+ | MikroTik RouterOS | ``routeros`` | in v. >=2.7 | N/A | N/A | N/A | +-------------------+-------------------------+----------------------+----------------------+------------------+------------------+ | Nokia SR OS | ``sros`` | in v. >=2.5 | N/A | N/A | in v. >=2.4 | 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 ce0ef8f1ba7..da15bd33eec 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.5.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.5.rst @@ -137,6 +137,21 @@ See :ref:`playbooks_tests` for more information. Additionally, a script was created to assist in the conversion for tests using filter syntax to proper jinja test syntax. This script has been used to convert all of the Ansible integration tests to the correct format. There are a few limitations documented, and all changes made by this script should be evaluated for correctness before executing the modified playbooks. The script can be found at `https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py `_. +Ansible fact namespacing +------------------------ + +Ansible facts, which have historically been written to names like ``ansible_*`` +in the main facts namespace, have been placed in their own new namespace, +``ansible_facts.*`` For example, the fact ``ansible_distribution`` is now best +queried through the variable structure ``ansible_facts.distribution``. + +A new configuration variable, ``inject_facts_as_vars``, has been added to +ansible.cfg. Its default setting, 'True', keeps the 2.4 behavior of facts +variables being set in the old ``ansible_*`` locations (while also writing them +to the new namespace). This variable is expected to be set to 'False' in a +future release. When ``inject_facts_as_vars`` is set to False, you must +refer to ansible_facts through the new ``ansible_facts.*`` namespace. + Modules ======= diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index e029b801b5a..639bbc255e4 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -344,7 +344,7 @@ Also see dynamic_variables_. How do I access a group variable? +++++++++++++++++++++++++++++++++ -Techinically, you don't, Ansible does not really use groups directly. Groups are label for host selection and a way to bulk assign variables, they are not a first class entity, Ansible only cares about Hosts and Tasks. +Technically, you don't, Ansible does not really use groups directly. Groups are label for host selection and a way to bulk assign variables, they are not a first class entity, Ansible only cares about Hosts and Tasks. That said, you could just access the variable by selecting a host that is part of that group, see first_host_in_a_group_ below for an example. @@ -580,7 +580,7 @@ The above DOES NOT WORK as you expect, if you need to use a dynamic variable use {{ hostvars[inventory_hostname]['somevar_' + other_var] }} -For 'non host vars' you can use the vars lookup plugin: +For 'non host vars' you can use the :ref:`vars lookup` plugin: .. code-block:: jinja diff --git a/docs/docsite/rst/reference_appendices/galaxy.rst b/docs/docsite/rst/reference_appendices/galaxy.rst index e70c80f468f..f2271a19cca 100644 --- a/docs/docsite/rst/reference_appendices/galaxy.rst +++ b/docs/docsite/rst/reference_appendices/galaxy.rst @@ -131,7 +131,7 @@ Use the following example as a guide for specifying roles in *requirements.yml*: - src: https://bitbucket.org/willthames/hg-ansible-galaxy scm: hg - # from GitLab or other git-based scm + # from GitLab or other git-based scm, using git+ssh - src: git@gitlab.company.com:mygroup/ansible-base.git scm: git version: "0.1" # quoted, so YAML doesn't parse this as a floating-point value diff --git a/docs/docsite/rst/scenario_guides/guide_azure.rst b/docs/docsite/rst/scenario_guides/guide_azure.rst index 7762cd0a7ee..dc16c844096 100644 --- a/docs/docsite/rst/scenario_guides/guide_azure.rst +++ b/docs/docsite/rst/scenario_guides/guide_azure.rst @@ -12,7 +12,7 @@ installed on the host running Ansible. .. code-block:: bash - $ pip install ansible[azure] + $ pip install 'ansible[azure]' If you are running Ansible from source, you can install the dependencies from the root directory of the Ansible repo. diff --git a/docs/docsite/rst/scenario_guides/guides.rst b/docs/docsite/rst/scenario_guides/guides.rst index 4f91d570ecd..958937fdabf 100644 --- a/docs/docsite/rst/scenario_guides/guides.rst +++ b/docs/docsite/rst/scenario_guides/guides.rst @@ -1,21 +1,15 @@ -Detailed Guides -``````````````` +:orphan: -This section is new and evolving. The idea here is to explore particular use cases in greater depth and provide a more "top down" explanation of some basic features. +*************** +Scenario Guides +*************** + +The guides in this section explore particular use cases in greater depth and provide a more "top-down" explanation of some basic features. .. toctree:: + :glob: :maxdepth: 1 - guide_aci - guide_aws - guide_azure - guide_rax - guide_gce - guide_cloudstack - guide_vagrant - guide_rolling_upgrade - guide_docker - guide_packet - guide_vultr + guide_* -Pending topics may include: Docker, Jenkins, Google Compute Engine, Linode/DigitalOcean, Continuous Deployment, and more. +Pending topics may include: Jenkins, Linode/DigitalOcean, Continuous Deployment, and more. diff --git a/docs/docsite/rst/user_guide/intro.rst b/docs/docsite/rst/user_guide/intro.rst index bb0e5315670..1ac0cb77a54 100644 --- a/docs/docsite/rst/user_guide/intro.rst +++ b/docs/docsite/rst/user_guide/intro.rst @@ -1,3 +1,5 @@ +:orphan: + Introduction ============ diff --git a/docs/docsite/rst/user_guide/module_defaults_config.rst b/docs/docsite/rst/user_guide/module_defaults_config.rst index 1b09ff55daa..2db81f09919 100644 --- a/docs/docsite/rst/user_guide/module_defaults_config.rst +++ b/docs/docsite/rst/user_guide/module_defaults_config.rst @@ -1,7 +1,10 @@ +:orphan: + .. _module_defaults_config: +***************************** Module Defaults Configuration -============================= +***************************** Ansible 2.7 adds a preview-status feature to group together modules that share common sets of parameters. This makes it easier to author playbooks making heavy use of API-based modules such as cloud modules. By default Ansible ships diff --git a/docs/docsite/rst/user_guide/playbook_pathing.rst b/docs/docsite/rst/user_guide/playbook_pathing.rst index 9dd213d2513..2c754314811 100644 --- a/docs/docsite/rst/user_guide/playbook_pathing.rst +++ b/docs/docsite/rst/user_guide/playbook_pathing.rst @@ -1,6 +1,8 @@ -======================= +:orphan: + +*********************** Search paths in Ansible -======================= +*********************** Absolute paths are not an issue as they always have a known start, but relative paths ... well, they are relative. @@ -32,7 +34,7 @@ i.e :: The current working directory (cwd) is not searched. If you see it, it just happens to coincide with one of the paths above. If you `include` a task file from a role, it will NOT trigger role behavior, this only happens when running as a role, `include_role` will work. -A new variable `ansible_search_path` var will have the search path used, in order (but without the appended subdirs). Using 5 "v"s (`-vvvvv`) should show the detail of the search as it happens. +A new variable `ansible_search_path` var will have the search path used, in order (but without the appended subdirs). Using 5 "v"s (`-vvvvv`) should show the detail of the search as it happens. As for includes, they try the path of the included file first and fall back to the play/role that includes them. diff --git a/docs/docsite/rst/user_guide/playbooks_best_practices.rst b/docs/docsite/rst/user_guide/playbooks_best_practices.rst index 0d21a3372bd..70a45e30aeb 100644 --- a/docs/docsite/rst/user_guide/playbooks_best_practices.rst +++ b/docs/docsite/rst/user_guide/playbooks_best_practices.rst @@ -394,11 +394,12 @@ This makes a dynamic group of hosts matching certain criteria, even if that grou --- - # talk to all hosts just so we can learn about them - - hosts: all + - name: talk to all hosts just so we can learn about them + hosts: all tasks: - - group_by: - key: os_{{ ansible_distribution }} + - name: Classify hosts depending on their OS distribution + group_by: + key: os_{{ ansible_facts['distribution'] }} # now just on the CentOS hosts... @@ -426,7 +427,8 @@ Alternatively, if only variables are needed:: - hosts: all tasks: - - include_vars: "os_{{ ansible_distribution }}.yml" + - name: Set OS distribution dependant variables + include_vars: "os_{{ ansible_facts['distribution'] }}.yml" - debug: var: asdf diff --git a/docs/docsite/rst/user_guide/playbooks_blocks.rst b/docs/docsite/rst/user_guide/playbooks_blocks.rst index 8fa97ef8f4c..51d34df2a81 100644 --- a/docs/docsite/rst/user_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/user_guide/playbooks_blocks.rst @@ -25,7 +25,7 @@ Blocks allow for logical grouping of tasks and in play error handling. Most of w name: bar state: started enabled: True - when: ansible_distribution == 'CentOS' + when: ansible_facts['distribution'] == 'CentOS' become: true become_user: root diff --git a/docs/docsite/rst/user_guide/playbooks_conditionals.rst b/docs/docsite/rst/user_guide/playbooks_conditionals.rst index 379ab055486..72fb742bf54 100644 --- a/docs/docsite/rst/user_guide/playbooks_conditionals.rst +++ b/docs/docsite/rst/user_guide/playbooks_conditionals.rst @@ -22,23 +22,22 @@ Sometimes you will want to skip a particular step on a particular host. This could be something as simple as not installing a certain package if the operating system is a particular version, or it could be something like performing some cleanup steps if a filesystem is getting full. -This is easy to do in Ansible with the `when` clause, which contains a raw Jinja2 expression without double curly braces (see :doc:`playbooks_variables`). +This is easy to do in Ansible with the `when` clause, which contains a raw Jinja2 expression without double curly braces (see :ref:`group_by_module`). It's actually pretty simple:: tasks: - name: "shut down Debian flavored systems" command: /sbin/shutdown -t now - when: ansible_os_family == "Debian" - # note that Ansible facts and vars like ansible_os_family can be used - # directly in conditionals without double curly braces + when: ansible_facts['os_family'] == "Debian" + # note that all variables can be directly in conditionals without double curly braces You can also use parentheses to group conditions:: tasks: - name: "shut down CentOS 6 and Debian 7 systems" command: /sbin/shutdown -t now - when: (ansible_distribution == "CentOS" and ansible_distribution_major_version == "6") or - (ansible_distribution == "Debian" and ansible_distribution_major_version == "7") + when: (ansible_facts['distribution'] == "CentOS" and ansible_facts['distribution_major_version'] == "6") or + (ansible_facts['distribution'] == "Debian" and ansible_facts['distribution_major_version'] == "7") Multiple conditions that all need to be true (a logical 'and') can also be specified as a list:: @@ -46,8 +45,8 @@ Multiple conditions that all need to be true (a logical 'and') can also be speci - name: "shut down CentOS 6 systems" command: /sbin/shutdown -t now when: - - ansible_distribution == "CentOS" - - ansible_distribution_major_version == "6" + - ansible_facts['distribution'] == "CentOS" + - ansible_facts['distribution_major_version'] == "6" A number of Jinja2 "tests" and "filters" can also be used in when statements, some of which are unique and provided by Ansible. Suppose we want to ignore the error of one statement and then @@ -72,17 +71,18 @@ decide to do something conditionally based on success or failure:: .. note:: both `success` and `succeeded` work (`fail`/`failed`, etc). -As a reminder, to see what facts are available on a particular system, you can do the following:: +To see what facts are available on a particular system, you can do the following in a playbook:: + + - debug: var=ansible_facts - ansible hostname.example.com -m setup Tip: Sometimes you'll get back a variable that's a string and you'll want to do a math operation comparison on it. You can do this like so:: tasks: - shell: echo "only on Red Hat 6, derivatives, and later" - when: ansible_os_family == "RedHat" and ansible_lsb.major_release|int >= 6 + when: ansible_facts['os_family'] == "RedHat" and ansible_facts['lsb']['major_release']|int >= 6 -.. note:: the above example requires the lsb_release package on the target host in order to return the ansible_lsb.major_release fact. +.. note:: the above example requires the lsb_release package on the target host in order to return the 'lsb major_release' fact. Variables defined in the playbooks or inventory can also be used. An example may be the execution of a task based on a variable's boolean value:: @@ -170,18 +170,20 @@ Or with a role:: - hosts: webservers roles: - role: debian_stock_config - when: ansible_os_family == 'Debian' + when: ansible_facts['os_family'] == 'Debian' You will note a lot of 'skipped' output by default in Ansible when using this approach on systems that don't match the criteria. -Read up on the 'group_by' module in the :doc:`modules` docs for a more streamlined way to accomplish the same thing. +In many cases the ``group_by`` module (see :doc:`modules`) can be a more streamlined way to accomplish the same thing; see +:ref:`os_variance`. -When used with `include_*` tasks instead of imports, the conditional is applied _only_ to the include task itself and not any other -tasks within the included file(s). A common situation where this distinction is important is as follows:: +When a conditional is used with ``include_*`` tasks instead of imports, it is applied `only` to the include task itself and not +to any other tasks within the included file(s). A common situation where this distinction is important is as follows:: - # include a file to define a variable when it is not already defined + # We wish to include a file to define a variable when it is not + # already defined # main.yml - - include_tasks: other_tasks.yml + - import_tasks: other_tasks.yml # note "import" when: x is not defined # other_tasks.yml @@ -190,8 +192,19 @@ tasks within the included file(s). A common situation where this distinction is - debug: var: x -In the above example, if ``import_tasks`` had been used instead both included tasks would have also been skipped. With ``include_tasks`` -instead, the tasks are executed as expected because the conditional is not applied to them. +This expands at include time to the equivalent of:: + + - set_fact: + x: foo + when: x is not defined + - debug: + var: x + when: x is not defined + +Thus if ``x`` is initially undefined, the ``debug`` task will be skipped. By using ``include_tasks`` instead of ``import_tasks``, +both tasks from ``other_tasks.yml`` will be executed as expected. + +For more information on the differences between ``include`` v ``import`` see :ref:`playbooks_reuse`. .. _conditional_imports: @@ -211,13 +224,13 @@ but it is easily handled with a minimum of syntax in an Ansible Playbook:: remote_user: root vars_files: - "vars/common.yml" - - [ "vars/{{ ansible_os_family }}.yml", "vars/os_defaults.yml" ] + - [ "vars/{{ ansible_facts['os_family'] }}.yml", "vars/os_defaults.yml" ] tasks: - name: make sure apache is started service: name={{ apache }} state=started .. note:: - The variable 'ansible_os_family' is being interpolated into + The variable "ansible_facts['os_family']" is being interpolated into the list of filenames being defined for vars_files. As a reminder, the various YAML files contain just keys and values:: @@ -254,7 +267,7 @@ The following example shows how to template out a configuration file that was ve loop: "{{ query('first_found', { 'files': myfiles, 'paths': mypaths}) }}" vars: myfiles: - - "{{ansible_distribution}}.conf" + - "{{ansible_facts['distribution']}}.conf" - default.conf mypaths: ['search_location_one/somedir/', '/opt/other_location/somedir/'] @@ -325,10 +338,10 @@ The following Facts are frequently used in Conditionals - see above for examples .. _ansible_distribution: -ansible_distribution --------------------- +ansible_facts['distribution'] +----------------------------- -Possible values:: +Possible values (sample, not complete list):: Alpine Altlinux @@ -353,17 +366,17 @@ Possible values:: .. _ansible_distribution_major_version: -ansible_distribution_major_version ----------------------------------- +ansible_facts['distribution_major_version'] +------------------------------------------- This will be the major version of the operating system. For example, the value will be `16` for Ubuntu 16.04. .. _ansible_os_family: -ansible_os_family ------------------ +ansible_facts['os_family'] +-------------------------- -Possible values:: +Possible values (sample, not complete list):: AIX Alpine diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst index d8cbebcc422..7eab897cc0d 100644 --- a/docs/docsite/rst/user_guide/playbooks_filters.rst +++ b/docs/docsite/rst/user_guide/playbooks_filters.rst @@ -89,8 +89,8 @@ Jinja2 provides a useful 'default' filter that is often a better approach to fai In the above example, if the variable 'some_variable' is not defined, the value used will be 5, rather than an error being raised. -If the variable evaluates to an empty string, the second parameter of the filter should be set to -`true`:: +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``:: {{ lookup('env', 'MY_USER') | default('admin', true) }} diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst index 404f563bc31..c143bc87989 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst @@ -46,9 +46,9 @@ Other YAML files may be included in certain directories. For example, it is comm # roles/example/tasks/main.yml - name: added in 2.4, previously you used 'include' import_tasks: redhat.yml - when: ansible_os_family|lower == 'redhat' + when: ansible_facts['os_family']|lower == 'redhat' - import_tasks: debian.yml - when: ansible_os_family|lower == 'debian' + when: ansible_facts['os_family']|lower == 'debian' # roles/example/tasks/redhat.yml - yum: @@ -163,7 +163,7 @@ You can conditionally import a role and execute it's tasks:: tasks: - include_role: name: some_role - when: "ansible_os_family == 'RedHat'" + when: "ansible_facts['os_family'] == 'RedHat'" diff --git a/docs/docsite/rst/user_guide/playbooks_tests.rst b/docs/docsite/rst/user_guide/playbooks_tests.rst index 83be5fe6647..5163fc20678 100644 --- a/docs/docsite/rst/user_guide/playbooks_tests.rst +++ b/docs/docsite/rst/user_guide/playbooks_tests.rst @@ -43,7 +43,7 @@ To match strings against a substring or a regex, use the "match" or "search" fil url: "http://example.com/users/foo/resources/bar" tasks: - - debug: + - debug: msg: "matched pattern 1" when: url is match("http://example.com/users/.*/resources/.*") @@ -67,14 +67,14 @@ Version Comparison .. note:: In 2.5 ``version_compare`` was renamed to ``version`` -To compare a version number, such as checking if the ``ansible_distribution_version`` +To compare a version number, such as checking if the ``ansible_facts['distribution_version']`` version is greater than or equal to '12.04', you can use the ``version`` test. -The ``version`` test can also be used to evaluate the ``ansible_distribution_version``:: +The ``version`` test can also be used to evaluate the ``ansible_facts['distribution_version']``:: - {{ ansible_distribution_version is version('12.04', '>=') }} + {{ ansible_facts['distribution_version'] is version('12.04', '>=') }} -If ``ansible_distribution_version`` is greater than or equal to 12.04, this test returns True, otherwise False. +If ``ansible_facts['distribution_version']`` is greater than or equal to 12.04, this test returns True, otherwise False. The ``version`` test accepts the following operators:: diff --git a/docs/docsite/rst/user_guide/playbooks_variables.rst b/docs/docsite/rst/user_guide/playbooks_variables.rst index 4328e04765e..c1433d0ed0c 100644 --- a/docs/docsite/rst/user_guide/playbooks_variables.rst +++ b/docs/docsite/rst/user_guide/playbooks_variables.rst @@ -161,11 +161,17 @@ Information discovered from systems: Facts There are other places where variables can come from, but these are a type of variable that are discovered, not set by the user. -Facts are information derived from speaking with your remote systems. +Facts are information derived from speaking with your remote systems. You can find a complete set under the ``ansible_facts`` variable, +most facts are also 'injected' as top level variables preserving the ``ansible_`` prefix, but some are dropped due to conflicts. +This can be disabled via the :ref:INJECT_FACTS_AS_VARS setting. An example of this might be the IP address of the remote host, or what the operating system is. -To see what information is available, try the following:: +To see what information is available, try the following in a play:: + + - debug: var=ansible_facts + +To see the 'raw' information as gathered:: ansible hostname -m setup @@ -406,15 +412,15 @@ This will return a large amount of variable data, which may look like this, as t In the above the model of the first harddrive may be referenced in a template or playbook as:: - {{ ansible_devices.sda.model }} + {{ ansible_facts['devices']['sda']['model'] }} Similarly, the hostname as the system reports it is:: - {{ ansible_nodename }} + {{ ansible_facts['nodename'] }} and the unqualified hostname shows the string before the first period(.):: - {{ ansible_hostname }} + {{ ansible_facts['hostname'] }} Facts are frequently used in conditionals (see :doc:`playbooks_conditionals`) and also in templates. @@ -475,11 +481,11 @@ And you will see the following fact added:: And this data can be accessed in a ``template/playbook`` as:: - {{ ansible_local.preferences.general.asdf }} + {{ ansible_local['preferences']['general']['asdf'] }} The local namespace prevents any user supplied fact from overriding system facts or variables defined elsewhere in the playbook. -.. note:: The key part in the key=value pairs will be converted into lowercase inside the ansible_local variable. Using the example above, if the ini file contained ``XYZ=3`` in the ``[general]`` section, then you should expect to access it as: ``{{ ansible_local.preferences.general.xyz }}`` and not ``{{ ansible_local.preferences.general.XYZ }}``. This is because Ansible uses Python's `ConfigParser`_ which passes all option names through the `optionxform`_ method and this method's default implementation converts option names to lower case. +.. note:: The key part in the key=value pairs will be converted into lowercase inside the ansible_local variable. Using the example above, if the ini file contained ``XYZ=3`` in the ``[general]`` section, then you should expect to access it as: ``{{ ansible_local['preferences']['general']['xyz'] }}`` and not ``{{ ansible_local['preferences']['general']['XYZ'] }}``. This is because Ansible uses Python's `ConfigParser`_ which passes all option names through the `optionxform`_ method and this method's default implementation converts option names to lower case. .. _ConfigParser: https://docs.python.org/2/library/configparser.html .. _optionxform: https://docs.python.org/2/library/configparser.html#ConfigParser.RawConfigParser.optionxform @@ -526,7 +532,7 @@ Fact Caching As shown elsewhere in the docs, it is possible for one server to reference variables about another, like so:: - {{ hostvars['asdf.example.com']['ansible_os_family'] }} + {{ hostvars['asdf.example.com']['ansible_facts']['os_family'] }} With "Fact Caching" disabled, in order to do this, Ansible must have already talked to 'asdf.example.com' in the current play, or another play up higher in the playbook. This is the default configuration of ansible. @@ -615,11 +621,11 @@ We already described facts a little higher up in the documentation. Some provided facts, like networking information, are made available as nested data structures. To access them a simple ``{{ foo }}`` is not sufficient, but it is still easy to do. Here's how we get an IP address:: - {{ ansible_eth0["ipv4"]["address"] }} + {{ ansible_facts["eth0"]["ipv4"]["address"] }} OR alternatively:: - {{ ansible_eth0.ipv4.address }} + {{ ansible_facts.eth0.ipv4.address }} Similarly, this is how we access the first element of an array:: @@ -641,7 +647,7 @@ or set of playbooks, you can still get the variables, but you will not be able t If your database server wants to use the value of a 'fact' from another node, or an inventory variable assigned to another node, it's easy to do so within a template or even an action line:: - {{ hostvars['test.example.com']['ansible_distribution'] }} + {{ hostvars['test.example.com']['ansible_facts']['distribution'] }} Additionally, ``group_names`` is a list (array) of all the groups the current host is in. This can be used in templates using Jinja2 syntax to make template source files that vary based on the group membership (or role) of the host @@ -666,7 +672,7 @@ A frequently used idiom is walking a group to find all IP addresses in that grou .. code-block:: jinja {% for host in groups['app_servers'] %} - {{ hostvars[host]['ansible_eth0']['ipv4']['address'] }} + {{ hostvars[host]['ansible_facts']['eth0']['ipv4']['address'] }} {% endfor %} An example of this could include pointing a frontend proxy server to all of the app servers, setting up the correct firewall rules between servers, etc. diff --git a/docs/docsite/rst/user_guide/windows_dsc.rst b/docs/docsite/rst/user_guide/windows_dsc.rst index cf52dca6b6e..f3ea637d785 100644 --- a/docs/docsite/rst/user_guide/windows_dsc.rst +++ b/docs/docsite/rst/user_guide/windows_dsc.rst @@ -2,6 +2,7 @@ Desired State Configuration =========================== .. contents:: Topics + :local: What is Desired State Configuration? ```````````````````````````````````` @@ -387,7 +388,7 @@ Setup IIS Website An introduction to playbooks :doc:`playbooks_best_practices` Best practices advice - `List of Windows Modules :ref:`` + :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/windows_setup.rst b/docs/docsite/rst/user_guide/windows_setup.rst index 693e778389c..fa8710e639a 100644 --- a/docs/docsite/rst/user_guide/windows_setup.rst +++ b/docs/docsite/rst/user_guide/windows_setup.rst @@ -3,6 +3,7 @@ Setting up a Windows Host This document discusses the setup that is required before Ansible can communicate with a Microsoft Windows host. .. contents:: Topics + :local: Host Requirements ````````````````` diff --git a/docs/docsite/rst/user_guide/windows_usage.rst b/docs/docsite/rst/user_guide/windows_usage.rst index e68c9e30ba2..d8acf3f222d 100644 --- a/docs/docsite/rst/user_guide/windows_usage.rst +++ b/docs/docsite/rst/user_guide/windows_usage.rst @@ -6,6 +6,7 @@ when it comes to components like path separators and OS-specific tasks. This document covers details specific to using Ansible for Windows. .. contents:: Topics + :local: Use Cases ````````` diff --git a/docs/docsite/rst/user_guide/windows_winrm.rst b/docs/docsite/rst/user_guide/windows_winrm.rst index 42c35803917..be1a3811690 100644 --- a/docs/docsite/rst/user_guide/windows_winrm.rst +++ b/docs/docsite/rst/user_guide/windows_winrm.rst @@ -4,6 +4,7 @@ Unlike Linux/Unix hosts, which use SSH by default, Windows hosts are configured with WinRM. This topic covers how to configure and use WinRM with Ansible. .. contents:: Topics + :local: What is WinRM? `````````````` @@ -426,6 +427,8 @@ work. To troubleshoot Kerberos issues, ensure that: an alias is being used. The ``krb5.conf`` file needs to be updated so that the fully qualified domain name is used and not an alias. +* If the default kerberos tooling has been replaced or modified (some IdM solutions may do this), this may cause issues when installing or upgrading the Python Kerberos library. As of the time of this writing, this library is called ``pykerberos`` and is known to work with both MIT and Heimdal Kerberos libraries. To resolve ``pykerberos`` installation issues, ensure the system dependencies for Kerberos have been met (see: `Installing the Kerberos Library`_), remove any custom Kerberos tooling paths from the PATH environment variable, and retry the installation of Python Kerberos library package. + CredSSP ------- CredSSP authentication is a newer authentication protocol that allows diff --git a/examples/ansible.cfg b/examples/ansible.cfg index f01abf56bfe..1bccd57c080 100644 --- a/examples/ansible.cfg +++ b/examples/ansible.cfg @@ -55,6 +55,15 @@ # environment. # gather_timeout = 10 +# Ansible facts are available inside the ansible_facts.* dictionary +# namespace. This setting maintains the behaviour which was the default prior +# to 2.5, duplicating these variables into the main namespace, each with a +# prefix of 'ansible_'. +# This variable is set to True by default for backwards compatibility. It +# will be changed to a default of 'False' in a future release. +# ansible_facts. +# inject_facts_as_vars = True + # additional paths to search for roles in, colon separated #roles_path = /etc/ansible/roles diff --git a/test/sanity/code-smell/docs-build.py b/test/sanity/code-smell/docs-build.py index 2d366b6ffbe..362c74ad44e 100755 --- a/test/sanity/code-smell/docs-build.py +++ b/test/sanity/code-smell/docs-build.py @@ -38,7 +38,6 @@ def main(): ignore_codes = [ 'reference-target-not-found', - 'not-in-toc-tree', ] used_ignore_codes = set()