WIP: Backport/2.10/71588 (#71626)
* Add dual index pages for roadmaps (part of #71566) (cherry picked from commitb518a5db14) * Docsite: replace Latin phrases to English (#71588) Replace Latin phrases like "e.g." and "i.e." and "etc." with English phrases. * Update docs/docsite/rst/community/committer_guidelines.rst * Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst * Update docs/docsite/rst/dev_guide/developing_program_flow_modules.rst * Update docs/docsite/rst/dev_guide/module_lifecycle.rst * Update docs/docsite/rst/user_guide/intro_inventory.rst * Update docs/docsite/rst/user_guide/playbooks_loops.rst * Update docs/docsite/rst/user_guide/playbooks_reuse.rst * Update docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst * Update docs/docsite/rst/dev_guide/testing.rst * Update docs/docsite/rst/dev_guide/testing_integration.rst * Update docs/docsite/rst/porting_guides/porting_guide_2.5.rst * Update docs/docsite/rst/reference_appendices/faq.rst (cherry picked from commit7bfeed3e24) * fix index page and TOCs * adds old roadmap index * adds toctree ref for old roadmaps Co-authored-by: Sandra McCann <samccann@redhat.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru> Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
This commit is contained in:
Alicia Cozine
GitHub
parent
1af7c6c003
commit
43e0aa5b57
62 changed files with 199 additions and 131 deletions
|
|
@ -15,7 +15,7 @@ If you abuse the trust and break components and builds, and so on, the trust lev
|
|||
Features, high-level design, and roadmap
|
||||
========================================
|
||||
|
||||
As a core team member, you are an integral part of the team that develops the :ref:`roadmap <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.
|
||||
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 changes completed and released as scheduled. Obligations to users, the community, and customers must come first. Because of these commitments, a feature you want to develop yourself may not get into a release if it affects a lot of other parts within Ansible.
|
||||
|
||||
Any other new features and changes to high level design should go through the proposal process (TBD), to ensure the community and core team have had a chance to review the idea and approve it. The core team has sole responsibility for merging new features based on proposals.
|
||||
|
||||
|
|
@ -49,7 +49,7 @@ Individuals with direct commit access to ansible/ansible are entrusted with powe
|
|||
- Commit directly.
|
||||
- Merge your own PRs. Someone else should have a chance to review and approve the PR merge. If you are a Core Committer, you have a small amount of leeway here for very minor changes.
|
||||
- Forget about alternate environments. Consider the alternatives--yes, people have bad environments, but they are the ones who need us the most.
|
||||
- Drag your community team members down. Always discuss the technical merits, but you should never address the person's limitations (you can later go for beers and call them idiots, but not in IRC/GitHub/and so on.).
|
||||
- Drag your community team members down. Always discuss the technical merits, but you should never address the person's limitations (you can later go for beers and call them idiots, but not in IRC/GitHub/and so on).
|
||||
- Forget about the maintenance burden. Some things are really cool to have, but they might not be worth shoehorning in if the maintenance burden is too great.
|
||||
- Break playbooks. Always keep backwards compatibility in mind.
|
||||
- Forget to keep it simple. Complexity breeds all kinds of problems.
|
||||
|
|
@ -57,11 +57,11 @@ Individuals with direct commit access to ansible/ansible are entrusted with powe
|
|||
* Do
|
||||
|
||||
- Squash, avoid merges whenever possible, use GitHub's squash commits or cherry pick if needed (bisect thanks you).
|
||||
- Be active. Committers who have no activity on the project (through merges, triage, commits, and so on.) will have their permissions suspended.
|
||||
- Be active. Committers who have no activity on the project (through merges, triage, commits, and so on) will have their permissions suspended.
|
||||
- Consider backwards compatibility (goes back to "don't break existing playbooks").
|
||||
- Write tests. PRs with tests are looked at with more priority than PRs without tests that should have them included. While not all changes require tests, be sure to add them for bug fixes or functionality changes.
|
||||
- Discuss with other committers, specially when you are unsure of something.
|
||||
- Document! If your PR is a new feature or a change to behavior, make sure you've updated all associated documentation or have notified the right people to do so. It also helps to add the version of Core against which this documentation is compatible (to avoid confusion with stable versus devel docs, for backwards compatibility, and so on.).
|
||||
- Document! If your PR is a new feature or a change to behavior, make sure you've updated all associated documentation or have notified the right people to do so. It also helps to add the version of ``ansible-base`` against which this documentation is compatible (to avoid confusion between stable and devel docs, for backwards compatibility, and so on).
|
||||
- Consider scope, sometimes a fix can be generalized
|
||||
- Keep it simple, then things are maintainable, debuggable and intelligible.
|
||||
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ A great documentation GitHub issue or PR includes:
|
|||
|
||||
- a specific title
|
||||
- a detailed description of the problem (even for a PR - it's hard to evaluate a suggested change unless we know what problem it's meant to solve)
|
||||
- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on.)
|
||||
- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on)
|
||||
|
||||
|
||||
Verifying your documentation PR
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ Going deeper
|
|||
* I need functionality that Ansible does not offer. How do I :ref:`request a feature <request_features>`?
|
||||
* How do I :ref:`contribute to an Ansible-maintained collection <contributing_maintained_collections>`?
|
||||
* I am waiting for a particular feature. How do I see what is :ref:`planned for future Ansible Releases <roadmaps>`?
|
||||
* 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 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 would like to participate in conversations about features and fixes. How do I review GitHub issues and pull requests?
|
||||
* I found a typo or another problem on docs.ansible.com. How can I :ref:`improve the documentation <community_documentation_contributions>`?
|
||||
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ The ``ansible-doc`` command requires the fully qualified collection name (FQCN)
|
|||
plugins directory
|
||||
------------------
|
||||
|
||||
Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on, without having to import a role in every play.
|
||||
Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on without having to import a role in every play.
|
||||
|
||||
Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins.
|
||||
|
||||
|
|
@ -565,7 +565,7 @@ Create a PR against the old collection repo to remove the modules, module_utils,
|
|||
Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:
|
||||
|
||||
#. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage.
|
||||
#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (i.e. 2.0.0, 3.0.0, etc.).
|
||||
#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (in other words, 2.0.0, 3.0.0, and so on).
|
||||
|
||||
|
||||
Adding the content to the new collection
|
||||
|
|
|
|||
|
|
@ -135,7 +135,7 @@ Modules must output valid JSON only. Follow these guidelines for creating correc
|
|||
* Be consistent about returns (some modules are too random), unless it is detrimental to the state/action.
|
||||
* Make returns reusable--most of the time you don't want to read it, but you do want to process it and re-purpose it.
|
||||
* Return diff if in diff mode. This is not required for all modules, as it won't make sense for certain ones, but please include it when applicable.
|
||||
* Enable your return values to be serialized as JSON with Python's standard `JSON encoder and decoder <https://docs.python.org/3/library/json.html>`_ library. Basic python types (strings, int, dicts, lists, etc) are serializable.
|
||||
* Enable your return values to be serialized as JSON with Python's standard `JSON encoder and decoder <https://docs.python.org/3/library/json.html>`_ library. Basic python types (strings, int, dicts, lists, and so on) are serializable.
|
||||
* Do not return an object via exit_json(). Instead, convert the fields you need from the object into the fields of a dictionary and return the dictionary.
|
||||
* Results from many hosts will be aggregated at once, so your module should return only relevant output. Returning the entire contents of a log file is generally bad form.
|
||||
|
||||
|
|
|
|||
|
|
@ -104,7 +104,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
|
|||
:description:
|
||||
|
||||
* A detailed description (generally two or more sentences).
|
||||
* Must be written in full sentences, i.e. with capital letters and periods/full stops.
|
||||
* Must be written in full sentences, in other words, with capital letters and periods/full stops.
|
||||
* Shouldn't mention the module name.
|
||||
* Make use of multiple entries rather than using one long paragraph.
|
||||
* Don't quote complete values unless it is required by YAML.
|
||||
|
|
@ -112,7 +112,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
|
|||
:version_added:
|
||||
|
||||
* The version of Ansible when the module was added.
|
||||
* This is a string, and not a float, i.e. ``version_added: '2.1'``
|
||||
* This is a string, and not a float, for example, ``version_added: '2.1'``
|
||||
|
||||
:author:
|
||||
|
||||
|
|
@ -178,8 +178,8 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
|
|||
|
||||
:version_added:
|
||||
|
||||
* Only needed if this option was extended after initial Ansible release, i.e. this is greater than the top level `version_added` field.
|
||||
* This is a string, and not a float, i.e. ``version_added: '2.3'``.
|
||||
* Only needed if this option was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field.
|
||||
* This is a string, and not a float, for example, ``version_added: '2.3'``.
|
||||
|
||||
:suboptions:
|
||||
|
||||
|
|
@ -367,8 +367,8 @@ Otherwise, for each value returned, provide the following fields. All fields are
|
|||
:sample:
|
||||
One or more examples.
|
||||
:version_added:
|
||||
Only needed if this return was extended after initial Ansible release, i.e. this is greater than the top level `version_added` field.
|
||||
This is a string, and not a float, i.e. ``version_added: '2.3'``.
|
||||
Only needed if this return was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field.
|
||||
This is a string, and not a float, for example, ``version_added: '2.3'``.
|
||||
:contains:
|
||||
Optional. To describe nested return values, set ``type: complex``, ``type: dict``, or ``type: list``/``elements: dict`` and repeat the elements above for each sub-field.
|
||||
|
||||
|
|
|
|||
|
|
@ -151,13 +151,13 @@ The ``construct_url()`` method takes 2 required arguments:
|
|||
* **self** - passed automatically with the class instance
|
||||
* **root_class** - A dictionary consisting of ``aci_class``, ``aci_rn``, ``target_filter``, and ``module_object`` keys
|
||||
|
||||
+ **aci_class**: The name of the class used by the APIC, e.g. ``fvTenant``
|
||||
+ **aci_class**: The name of the class used by the APIC, for example ``fvTenant``
|
||||
|
||||
+ **aci_rn**: The relative name of the object, e.g. ``tn-ACME``
|
||||
+ **aci_rn**: The relative name of the object, for example ``tn-ACME``
|
||||
|
||||
+ **target_filter**: A dictionary with key-value pairs that make up the query string for selecting a subset of entries, e.g. ``{'name': 'ACME'}``
|
||||
+ **target_filter**: A dictionary with key-value pairs that make up the query string for selecting a subset of entries, for example ``{'name': 'ACME'}``
|
||||
|
||||
+ **module_object**: The particular object for this class, e.g. ``ACME``
|
||||
+ **module_object**: The particular object for this class, for example ``ACME``
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -220,7 +220,7 @@ The ``aci.payload()`` method is used to build a dictionary of the proposed objec
|
|||
|
||||
The ``aci.payload()`` method takes two required arguments and 1 optional argument, depending on if the module manages child objects.
|
||||
|
||||
* ``aci_class`` is the APIC name for the object's class, e.g. ``aci_class='fvBD'``
|
||||
* ``aci_class`` is the APIC name for the object's class, for example ``aci_class='fvBD'``
|
||||
* ``class_config`` is the appropriate dictionary to be used as the payload for the POST request
|
||||
|
||||
+ The keys should match the names used by the APIC.
|
||||
|
|
|
|||
|
|
@ -141,7 +141,7 @@ To provision the environment as is, run the following:
|
|||
Unlike setting up a single Windows instance with Vagrant, these hosts can also
|
||||
be accessed using the IP address directly as well as through the forwarded
|
||||
ports. It is easier to access it over the host only network adapter as the
|
||||
normal protocol ports are used, e.g. RDP is still over ``3389``. In cases where
|
||||
normal protocol ports are used, for example RDP is still over ``3389``. In cases where
|
||||
the host cannot be resolved using the host only network IP, the following
|
||||
protocols can be access over ``127.0.0.1`` using these forwarded ports:
|
||||
|
||||
|
|
@ -179,8 +179,8 @@ When creating a new module there are a few things to keep in mind:
|
|||
- Ensure the code runs under Powershell v3 and higher on Windows Server 2008 and higher; if higher minimum Powershell or OS versions are required, ensure the documentation reflects this clearly
|
||||
- Ansible runs modules under strictmode version 2.0. Be sure to test with that enabled by putting ``Set-StrictMode -Version 2.0`` at the top of your dev script
|
||||
- Favor native Powershell cmdlets over executable calls if possible
|
||||
- Use the full cmdlet name instead of aliases, e.g. ``Remove-Item`` over ``rm``
|
||||
- Use named parameters with cmdlets, e.g. ``Remove-Item -Path C:\temp`` over ``Remove-Item C:\temp``
|
||||
- Use the full cmdlet name instead of aliases, for example ``Remove-Item`` over ``rm``
|
||||
- Use named parameters with cmdlets, for example ``Remove-Item -Path C:\temp`` over ``Remove-Item C:\temp``
|
||||
|
||||
A very basic Powershell module `win_environment <https://github.com/ansible-collections/ansible.windows/blob/master/plugins/modules/win_environment.ps1>`_ incorporates best practices for Powershell modules. It demonstrates how to implement check-mode and diff-support, and also shows a warning to the user when a specific condition is met.
|
||||
|
||||
|
|
@ -400,7 +400,7 @@ the various modules that call that util.
|
|||
|
||||
An example of this would be to have a module util that handles authentication and communication against an API This
|
||||
util can be used by multiple modules to expose a common set of module options like the API endpoint, username,
|
||||
password, timeout, cert validation, etc, without having to add those options to each module spec.
|
||||
password, timeout, cert validation, and so on without having to add those options to each module spec.
|
||||
|
||||
The standard convention for a module util that has a shared argument spec would have
|
||||
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ values as :term:`JSON`, and various file operations.
|
|||
.. note:: In Ansible, up to version 2.0.x, the official Python modules used the
|
||||
:ref:`module_replacer` framework. For module authors, :ref:`Ansiballz` is
|
||||
largely a superset of :ref:`module_replacer` functionality, so you usually
|
||||
do not need to know about one versus the other.
|
||||
do not need to understand the differences between them.
|
||||
|
||||
.. _flow_powershell_modules:
|
||||
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ Find the task that best describes what you want to do:
|
|||
* an :ref:`OpenStack module <OpenStack_module_development>`.
|
||||
* an :ref:`oVirt/RHV module <oVirt_module_development>`.
|
||||
* a :ref:`VMware module <VMware_module_development>`.
|
||||
* I want to :ref:`write a series of related modules <developing_modules_in_groups>` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, etc.).
|
||||
* I want to :ref:`write a series of related modules <developing_modules_in_groups>` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, and so on).
|
||||
|
||||
* I want to refine my code:
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ To deprecate a module, you must:
|
|||
:removed_in: A ``string``, such as ``"2.10"``; the version of Ansible where the module will be replaced with a docs-only module stub. Usually current release +4. Mutually exclusive with :removed_by_date:.
|
||||
:remove_by_date: (Added in Ansible 2.10). An ISO 8601 formatted date when the module will be removed. Usually 2 years from the date the module is deprecated. Mutually exclusive with :removed_in:.
|
||||
:why: Optional string that used to detail why this has been removed.
|
||||
:alternative: Inform users they should do instead, i.e. ``Use M(whatmoduletouseinstead) instead.``.
|
||||
:alternative: Inform users they should do instead, for example, ``Use M(whatmoduletouseinstead) instead.``.
|
||||
|
||||
* note: with the advent of collections and ``routing.yml`` we might soon require another entry in this file to mark the deprecation.
|
||||
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ Modules
|
|||
Ansible works by connecting to your nodes and pushing out scripts called "Ansible modules" to them. Most modules accept parameters that describe the desired state of the system.
|
||||
Ansible then executes these modules (over SSH by default), and removes them when finished. Your library of modules can reside on any machine, and there are no servers, daemons, or databases required.
|
||||
|
||||
You can :ref:`write your own modules <developing_modules_general>`, though you should first consider :ref:`whether you should <developing_modules>`. Typically you'll work with your favorite terminal program, a text editor, and probably a version control system to keep track of changes to your content. You may write specialized modules in any language that can return JSON (Ruby, Python, bash, etc).
|
||||
You can :ref:`write your own modules <developing_modules_general>`, though you should first consider :ref:`whether you should <developing_modules>`. Typically you'll work with your favorite terminal program, a text editor, and probably a version control system to keep track of changes to your content. You may write specialized modules in any language that can return JSON (Ruby, Python, bash, and so on).
|
||||
|
||||
Module utilities
|
||||
================
|
||||
|
|
@ -34,7 +34,7 @@ Plugins
|
|||
Inventory
|
||||
=========
|
||||
|
||||
By default, Ansible represents the machines it manages in a file (INI, YAML, etc.) that puts all of your managed machines in groups of your own choosing.
|
||||
By default, Ansible represents the machines it manages in a file (INI, YAML, and so on) that puts all of your managed machines in groups of your own choosing.
|
||||
|
||||
To add new machines, there is no additional SSL signing server involved, so there's never any hassle deciding why a particular machine didn't get linked up due to obscure NTP or DNS issues.
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ want to implement some functionality that uses a new feature of boto3, it should
|
|||
feature actually needs to be run, with a message stating the missing feature and minimum required
|
||||
version of boto3.
|
||||
|
||||
Use feature testing (e.g. ``hasattr('boto3.module', 'shiny_new_method')``) to check whether boto3
|
||||
Use feature testing (for example, ``hasattr('boto3.module', 'shiny_new_method')``) to check whether boto3
|
||||
supports a feature rather than version checking. For example, from the ``ec2`` module:
|
||||
|
||||
.. code-block:: python
|
||||
|
|
@ -575,7 +575,7 @@ boto3_tag_list_to_ansible_dict
|
|||
Converts a boto3 tag list to an Ansible dict. Boto3 returns tags as a list of dicts containing keys
|
||||
called 'Key' and 'Value' by default. This key names can be overridden when calling the function.
|
||||
For example, if you have already camel_cased your list of tags you may want to pass lowercase key
|
||||
names instead i.e. 'key' and 'value'.
|
||||
names instead, in other words, 'key' and 'value'.
|
||||
|
||||
This function converts the list in to a single dict where the dict key is the tag key and the dict
|
||||
value is the tag value.
|
||||
|
|
@ -611,7 +611,7 @@ is True by default. If purge is False then any existing tags will not be modifi
|
|||
|
||||
This function is useful when using boto3 'add_tags' and 'remove_tags' functions. Be sure to use the
|
||||
other helper function `boto3_tag_list_to_ansible_dict` to get an appropriate tag dict before
|
||||
calling this function. Since the AWS APIs are not uniform (e.g. EC2 versus Lambda) this will work
|
||||
calling this function. Since the AWS APIs are not uniform (for example, EC2 is different from Lambda) this will work
|
||||
without modification for some (Lambda) and others may need modification before using these values
|
||||
(such as EC2, with requires the tags to unset to be in the form `[{'Key': key1}, {'Key': key2}]`).
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ Basic rules
|
|||
|
||||
Use standard American English
|
||||
-----------------------------
|
||||
Ansible uses Standard American English. Watch for common words that are spelled differently in American English (color vs colour, organize vs organise, etc.).
|
||||
Ansible uses Standard American English. Watch for common words that are spelled differently in American English (color vs colour, organize vs organise, and so on).
|
||||
|
||||
Write for a global audience
|
||||
---------------------------
|
||||
|
|
@ -54,7 +54,7 @@ Highlight menu items and commands
|
|||
---------------------------------
|
||||
When documenting menus or commands, it helps to **bold** what is important.
|
||||
|
||||
For menu procedures, bold the menu names, button names, etc to help the user find them on the GUI:
|
||||
For menu procedures, bold the menu names, button names, and so on to help the user find them on the GUI:
|
||||
|
||||
1. On the **File** menu, click **Open**.
|
||||
2. Type a name in the **User Name** field.
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ Gender References
|
|||
~~~~~~~~~~~~~~~~~~
|
||||
Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers."
|
||||
|
||||
It is fine to use "you" when giving instructions and "the user," "new users," etc. in more general explanations.
|
||||
It is fine to use "you" when giving instructions and "the user," "new users," and so on. in more general explanations.
|
||||
|
||||
Never use "one" in place of "you" when writing technical documentation. Using "one" is far too formal.
|
||||
|
||||
|
|
@ -137,7 +137,7 @@ In professionally printed material (particularly books, magazines, and newspaper
|
|||
|
||||
Lists
|
||||
~~~~~~~
|
||||
Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, etc.
|
||||
Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, and so on.
|
||||
|
||||
Capitalize the first word of each bullet. Unless it is obvious that it is just a list of items, such as a list of items like:
|
||||
* computer
|
||||
|
|
@ -189,7 +189,7 @@ Use a semicolon to separate items in a series if the items contain commas:
|
|||
|
||||
- Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner.
|
||||
|
||||
Use a semicolon before a conjunctive adverb (however, therefore, otherwise, namely, for example, etc.):
|
||||
Use a semicolon before a conjunctive adverb (however, therefore, otherwise, namely, for example, and so on):
|
||||
- I think; therefore, I am.
|
||||
|
||||
Spacing after sentences
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Why test your Ansible contributions?
|
|||
|
||||
If you're a developer, one of the most valuable things you can do is to look at GitHub issues and help fix bugs, since bug-fixing is almost always prioritized over feature development. Even for non-developers, helping to test pull requests for bug fixes and features is still immensely valuable.
|
||||
|
||||
Ansible users who understand how to write playbooks and roles should be able to test their work. GitHub pull requests will automatically run a variety of tests (e.g., Shippable) that show bugs in action. However, contributors must also test their work outside of the automated GitHub checks and show evidence of these tests in the PR to ensure that their work will be more likely to be reviewed and merged.
|
||||
Ansible users who understand how to write playbooks and roles should be able to test their work. GitHub pull requests will automatically run a variety of tests (for example, Shippable) that show bugs in action. However, contributors must also test their work outside of the automated GitHub checks and show evidence of these tests in the PR to ensure that their work will be more likely to be reviewed and merged.
|
||||
|
||||
Read on to learn how Ansible is tested, how to test your contributions locally, and how to extend testing capabilities.
|
||||
|
||||
|
|
@ -123,7 +123,7 @@ Here's how:
|
|||
sent may have mistakes or malicious code that could have a negative impact on your system. We recommend
|
||||
doing all testing on a virtual machine, whether a cloud instance, or locally. Some users like Vagrant
|
||||
or Docker for this, but they are optional. It is also useful to have virtual machines of different Linux or
|
||||
other flavors, since some features (apt vs. yum, for example) are specific to those OS versions.
|
||||
other flavors, since some features (for example, package managers such as apt or yum) are specific to those OS versions.
|
||||
|
||||
|
||||
Create a fresh area to work::
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ integration_config.yml
|
|||
|
||||
Making your own version of ``integration_config.yml`` can allow for setting some
|
||||
tunable parameters to help run the tests better in your environment. Some
|
||||
tests (e.g. cloud) will only run when access credentials are provided. For more
|
||||
tests (for example, cloud tests) will only run when access credentials are provided. For more
|
||||
information about supported credentials, refer to the various ``cloud-config-*.template``
|
||||
files in the ``test/integration/`` directory.
|
||||
|
||||
|
|
|
|||
|
|
@ -29,11 +29,11 @@ Over time the above list will be reduced as tests are ported to the ``ansible-te
|
|||
Running Cloud Tests
|
||||
====================
|
||||
|
||||
Cloud tests exercise capabilities of cloud modules (e.g. ec2_key). These are
|
||||
Cloud tests exercise capabilities of cloud modules (for example, ec2_key). These are
|
||||
not 'tests run in the cloud' so much as tests that leverage the cloud modules
|
||||
and are organized by cloud provider.
|
||||
|
||||
Some AWS tests may use environment variables. It is recommended to either unset any AWS environment variables( such as ``AWS_DEFAULT_PROFILE``, ``AWS_SECRET_ACCESS_KEY``, etc) or be sure that the environment variables match the credentials provided in ``credentials.yml`` to ensure the tests run with consistency to their full capability on the expected account. See `AWS CLI docs <https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html>`_ for information on creating a profile.
|
||||
Some AWS tests may use environment variables. It is recommended to either unset any AWS environment variables( such as ``AWS_DEFAULT_PROFILE``, ``AWS_SECRET_ACCESS_KEY``, and so on) or be sure that the environment variables match the credentials provided in ``credentials.yml`` to ensure the tests run with consistency to their full capability on the expected account. See `AWS CLI docs <https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html>`_ for information on creating a profile.
|
||||
|
||||
Subsets of tests may be run by ``#commenting`` out unnecessary roles in the appropriate playbook, such as ``test/integration/amazon.yml``.
|
||||
|
||||
|
|
@ -68,7 +68,7 @@ The testing-iam-policy.json.j2 file contains a policy which can be given to the
|
|||
running the tests to give close to minimum rights required to run the tests. Please note
|
||||
that this does not fully restrict the user; The user has wide privileges for viewing
|
||||
account definitions and is also able to manage some resources that are not related to
|
||||
testing (e.g. AWS lambdas with different names) primarily due to the limitations of the
|
||||
testing (for example, AWS lambdas with different names) primarily due to the limitations of the
|
||||
Amazon ARN notation. At the very least the policy limits the user to one region, however
|
||||
tests should not be run in a primary production account in any case.
|
||||
|
||||
|
|
@ -94,7 +94,7 @@ Run the tests by doing::
|
|||
cd test/integration/
|
||||
# TARGET is the name of the test from the list at the top of this page
|
||||
#make TARGET
|
||||
# e.g.
|
||||
# for example
|
||||
make amazon
|
||||
# To run all cloud tests you can do:
|
||||
make cloud
|
||||
|
|
|
|||
|
|
@ -95,7 +95,7 @@ Codes
|
|||
invalid-extension Naming Error Official Ansible modules must have a ``.py`` extension for python modules or a ``.ps1`` for powershell modules
|
||||
invalid-module-schema Documentation Error ``AnsibleModule`` schema validation error
|
||||
invalid-requires-extension Naming Error Module ``#AnsibleRequires -CSharpUtil`` should not end in .cs, Module ``#Requires`` should not end in .psm1
|
||||
invalid-tagged-version Documentation Error All version numbers specified in code have to be explicitly tagged with the collection name, i.e. ``community.general:1.2.3`` or ``ansible.builtin:2.10``
|
||||
invalid-tagged-version Documentation Error All version numbers specified in code have to be explicitly tagged with the collection name, in other words, ``community.general:1.2.3`` or ``ansible.builtin:2.10``
|
||||
last-line-main-call Syntax Error Call to ``main()`` not the last line (or ``removed_module()`` in the case of deprecated & docs only modules)
|
||||
missing-doc-fragment Documentation Error ``DOCUMENTATION`` fragment missing
|
||||
missing-existing-doc-fragment Documentation Warning Pre-existing ``DOCUMENTATION`` fragment missing
|
||||
|
|
|
|||
|
|
@ -83,7 +83,7 @@ Which Ansible version to install is based on your particular needs. You can choo
|
|||
|
||||
|
||||
Ansible creates new releases two to three times a year. Due to this short release cycle,
|
||||
minor bugs will generally be fixed in the next release versus maintaining backports on the stable branch.
|
||||
minor bugs will generally be fixed in the next release rather than maintaining backports on the stable branch.
|
||||
Major bugs will still have maintenance releases when needed, though these are infrequent.
|
||||
|
||||
|
||||
|
|
@ -143,7 +143,7 @@ To configure the PPA on your machine and install Ansible run these commands:
|
|||
$ sudo apt-add-repository --yes --update ppa:ansible/ansible
|
||||
$ sudo apt install ansible
|
||||
|
||||
.. note:: On older Ubuntu distributions, "software-properties-common" is called "python-software-properties". You may want to use ``apt-get`` instead of ``apt`` in older versions. Also, be aware that only newer distributions (i.e. 18.04, 18.10, etc.) have a ``-u`` or ``--update`` flag, so adjust your script accordingly.
|
||||
.. note:: On older Ubuntu distributions, "software-properties-common" is called "python-software-properties". You may want to use ``apt-get`` instead of ``apt`` in older versions. Also, be aware that only newer distributions (in other words, 18.04, 18.10, and so on) have a ``-u`` or ``--update`` flag, so adjust your script accordingly.
|
||||
|
||||
Debian/Ubuntu packages can also be built from the source checkout, run:
|
||||
|
||||
|
|
@ -210,7 +210,7 @@ You may also wish to install from ports, run:
|
|||
|
||||
$ sudo make -C /usr/ports/sysutils/ansible install
|
||||
|
||||
You can also choose a specific version, i.e ``ansible25``.
|
||||
You can also choose a specific version, for example ``ansible25``.
|
||||
|
||||
Older versions of FreeBSD worked with something like this (substitute for your choice of package manager):
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ Developing network resource modules
|
|||
Understanding network and security resource modules
|
||||
===================================================
|
||||
|
||||
Network and security devices separate configuration into sections (such as interfaces, VLANs, and so on) that apply to a network or security service. Ansible resource modules take advantage of this to allow users to configure subsections or resources within the device configuration. Resource modules provide a consistent experience across different network and security devices. For example, a network resource module may only update the configuration for a specific portion of the network interfaces, VLANs, ACLs, and so on, for a network device. The resource module:
|
||||
Network and security devices separate configuration into sections (such as interfaces, VLANs, and so on) that apply to a network or security service. Ansible resource modules take advantage of this to allow users to configure subsections or resources within the device configuration. Resource modules provide a consistent experience across different network and security devices. For example, a network resource module may only update the configuration for a specific portion of the network interfaces, VLANs, ACLs, and so on for a network device. The resource module:
|
||||
|
||||
#. Fetches a piece of the configuration (fact gathering), for example, the interfaces configuration.
|
||||
#. Converts the returned configuration into key-value pairs.
|
||||
|
|
|
|||
|
|
@ -691,7 +691,7 @@ Example ssh config file (~/.ssh/config)
|
|||
|
||||
# Note: Due to the way that Paramiko reads the SSH Config file,
|
||||
# you need to specify the NETCONF port that the host uses.
|
||||
# i.e. It does not automatically use ansible_port
|
||||
# In other words, it does not automatically use ansible_port
|
||||
# As a result you need either:
|
||||
|
||||
Host junos01
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Become plugins work to ensure that Ansible can use certain privilege escalation
|
|||
commands to work with the target machine as well as the modules required to execute the tasks specified in
|
||||
the play.
|
||||
|
||||
These utilities (``sudo``, ``su``, ``doas``, etc) generally let you 'become' another user to execute a command
|
||||
These utilities (``sudo``, ``su``, ``doas``, and so on) generally let you 'become' another user to execute a command
|
||||
with the permissions of that user.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ After providing any required options, you can view the populated inventory with
|
|||
|
||||
If you are using an inventory plugin in a playbook-adjacent collection and want to test your setup with ``ansible-inventory``, you will need to use the ``--playbook-dir`` flag.
|
||||
|
||||
Your inventory source might be a directory of inventory configuration files. The constructed inventory plugin only operates on those hosts already in inventory, so you may want the constructed inventory configuration parsed at a particular point (such as last). Ansible parses the directory recursively, alphabetically. You cannot configure the parsing approach, so name your files to make it work predictably. Inventory plugins that extend constructed features directly can work around that restriction by adding constructed options in addition to the inventory plugin options. Otherwise, you can use ``-i`` with multiple sources to impose a specific order, e.g. ``-i demo.aws_ec2.yml -i clouds.yml -i constructed.yml``.
|
||||
Your inventory source might be a directory of inventory configuration files. The constructed inventory plugin only operates on those hosts already in inventory, so you may want the constructed inventory configuration parsed at a particular point (such as last). Ansible parses the directory recursively, alphabetically. You cannot configure the parsing approach, so name your files to make it work predictably. Inventory plugins that extend constructed features directly can work around that restriction by adding constructed options in addition to the inventory plugin options. Otherwise, you can use ``-i`` with multiple sources to impose a specific order, for example ``-i demo.aws_ec2.yml -i clouds.yml -i constructed.yml``.
|
||||
|
||||
You can create dynamic groups using host variables with the constructed ``keyed_groups`` option. The option ``groups`` can also be used to create groups and ``compose`` creates and modifies host variables. Here is an aws_ec2 example utilizing constructed features:
|
||||
|
||||
|
|
@ -105,7 +105,7 @@ Now the output of ``ansible-inventory -i demo.aws_ec2.yml --graph``:
|
|||
| |--ec2-12-345-678-901.compute-1.amazonaws.com
|
||||
|--@ungrouped
|
||||
|
||||
If a host does not have the variables in the configuration above (i.e. ``tags.Name``, ``tags``, ``private_ip_address``), the host will not be added to groups other than those that the inventory plugin creates and the ``ansible_host`` host variable will not be modified.
|
||||
If a host does not have the variables in the configuration above (in other words, ``tags.Name``, ``tags``, ``private_ip_address``), the host will not be added to groups other than those that the inventory plugin creates and the ``ansible_host`` host variable will not be modified.
|
||||
|
||||
Inventory plugins that support caching can use the general settings for the fact cache defined in the ``ansible.cfg`` file's ``[defaults]`` section or define inventory-specific settings in the ``[inventory]`` section. Individual plugins can define plugin-specific cache settings in their config file:
|
||||
|
||||
|
|
|
|||
|
|
@ -288,15 +288,15 @@ Since the ansible-2.0 plugin system is more advanced, it is easier to adapt your
|
|||
|
||||
You may find the following tips useful:
|
||||
|
||||
* Check whether the ansible-2.0 class(es) are available and if they are missing (ansible-1.9.x) mimic them with the needed methods (e.g. ``__init__``)
|
||||
* Check whether the ansible-2.0 class(es) are available and if they are missing (ansible-1.9.x) mimic them with the needed methods (for example, ``__init__``)
|
||||
|
||||
* When ansible-2.0 python modules are imported, and they fail (ansible-1.9.x), catch the ``ImportError`` exception and perform the equivalent imports for ansible-1.9.x. With possible translations (e.g. importing specific methods).
|
||||
* When ansible-2.0 python modules are imported, and they fail (ansible-1.9.x), catch the ``ImportError`` exception and perform the equivalent imports for ansible-1.9.x. With possible translations (for example, importing specific methods).
|
||||
|
||||
* Use the existence of these methods as a qualifier to what version of Ansible you are running. So rather than using version checks, you can do capability checks instead. (See examples below)
|
||||
|
||||
* Document for each if-then-else case for which specific version each block is needed. This will help others to understand how they have to adapt their plugins, but it will also help you to remove the older ansible-1.9.x support when it is deprecated.
|
||||
|
||||
* When doing plugin development, it is very useful to have the ``warning()`` method during development, but it is also important to emit warnings for deadends (cases that you expect should never be triggered) or corner cases (e.g. cases where you expect misconfigurations).
|
||||
* When doing plugin development, it is very useful to have the ``warning()`` method during development, but it is also important to emit warnings for deadends (cases that you expect should never be triggered) or corner cases (for example, cases where you expect misconfigurations).
|
||||
|
||||
* It helps to look at other plugins in ansible-1.9.x and ansible-2.0 to understand how the API works and what modules, classes and methods are available.
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ Playbook
|
|||
Dynamic includes and attribute inheritance
|
||||
------------------------------------------
|
||||
|
||||
In Ansible version 2.4, the concept of dynamic includes (``include_tasks``) versus static imports (``import_tasks``) was introduced to clearly define the differences in how ``include`` works between dynamic and static includes.
|
||||
In Ansible version 2.4, the concept of dynamic includes (``include_tasks``), as opposed to static imports (``import_tasks``), was introduced to clearly define the differences in how ``include`` works between dynamic and static includes.
|
||||
|
||||
All attributes applied to a dynamic ``include_*`` would only apply to the include itself, while attributes applied to a
|
||||
static ``import_*`` would be inherited by the tasks within.
|
||||
|
|
|
|||
|
|
@ -246,7 +246,7 @@ best solution is to explicitly set ``ansible_python_interpreter`` to the path
|
|||
of the correct interpreter for those target systems.
|
||||
|
||||
You can still set ``ansible_python_interpreter`` to a specific path at any
|
||||
variable level (as a host variable, in vars files, in playbooks, etc.).
|
||||
variable level (as a host variable, in vars files, in playbooks, and so on).
|
||||
If you prefer to use the Python interpreter discovery behavior, use
|
||||
one of the four new values for ``ansible_python_interpreter`` introduced in
|
||||
Ansible 2.8:
|
||||
|
|
@ -286,7 +286,7 @@ use the discovered Python, regardless of whether :command:`/usr/bin/python` exis
|
|||
:literal:`auto_legacy` setting provides compatibility with previous versions of Ansible that always
|
||||
defaulted to :command:`/usr/bin/python`.
|
||||
|
||||
If you installed Python and dependencies (``boto``, etc.) to
|
||||
If you installed Python and dependencies (``boto``, and so on) to
|
||||
:command:`/usr/bin/python` as a workaround on distros with a different default Python
|
||||
interpreter (for example, Ubuntu 16.04+, RHEL8, Fedora 23+), you have two
|
||||
options:
|
||||
|
|
|
|||
|
|
@ -704,7 +704,7 @@ Noteworthy module changes
|
|||
* The deprecated ``force`` option in ``win_firewall_rule`` has been removed.
|
||||
* :ref:`openssl_certificate <openssl_certificate_module>`'s ``ownca`` provider creates authority key identifiers if not explicitly disabled with ``ownca_create_authority_key_identifier: no``. This is only the case for the ``cryptography`` backend, which is selected by default if the ``cryptography`` library is available.
|
||||
* :ref:`openssl_certificate <openssl_certificate_module>`'s ``ownca`` and ``selfsigned`` providers create subject key identifiers if not explicitly disabled with ``ownca_create_subject_key_identifier: never_create`` resp. ``selfsigned_create_subject_key_identifier: never_create``. If a subject key identifier is provided by the CSR, it is taken; if not, it is created from the public key. This is only the case for the ``cryptography`` backend, which is selected by default if the ``cryptography`` library is available.
|
||||
* :ref:`openssh_keypair <openssh_keypair_module>` now applies the same file permissions and ownership to both public and private keys (both get the same ``mode``, ``owner``, ``group``, etc.). If you need to change permissions / ownership on one key, use the :ref:`file <file_module>` to modify it after it is created.
|
||||
* :ref:`openssh_keypair <openssh_keypair_module>` now applies the same file permissions and ownership to both public and private keys (both get the same ``mode``, ``owner``, ``group``, and so on). If you need to change permissions / ownership on one key, use the :ref:`file <file_module>` to modify it after it is created.
|
||||
|
||||
|
||||
Plugins
|
||||
|
|
|
|||
|
|
@ -102,7 +102,7 @@ A string with a generic message relayed to the user.
|
|||
|
||||
rc
|
||||
``
|
||||
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains 'return code' of these utilities.
|
||||
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains 'return code' of these utilities.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -181,7 +181,7 @@ A boolean that indicates if the task was skipped or not
|
|||
|
||||
stderr
|
||||
``````
|
||||
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc), this field contains the error output of these utilities.
|
||||
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on), this field contains the error output of these utilities.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -199,7 +199,7 @@ When `stderr` is returned we also always provide this field which is a list of s
|
|||
|
||||
stdout
|
||||
``````
|
||||
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, etc). This field contains the normal output of these utilities.
|
||||
Some modules execute command line utilities or are geared for executing commands directly (raw, shell, command, and so on). This field contains the normal output of these utilities.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
|
|||
|
|
@ -150,7 +150,7 @@ requires Python 2, you can also report a bug on our `bug tracker
|
|||
|
||||
Do not replace the shebang lines of your python modules. Ansible will do this for you automatically at deploy time.
|
||||
|
||||
Also, this works for ANY interpreter, i.e ruby: ``ansible_ruby_interpreter``, perl: ``ansible_perl_interpreter``, etc,
|
||||
Also, this works for ANY interpreter, for example ruby: ``ansible_ruby_interpreter``, perl: ``ansible_perl_interpreter``, and so on,
|
||||
so you can use this for custom modules written in any scripting language and control the interpreter location.
|
||||
|
||||
Keep in mind that if you put ``env`` in your module shebang line (``#!/usr/bin/env <other>``),
|
||||
|
|
@ -515,7 +515,7 @@ The ``mkpasswd`` utility that is available on most Linux systems is also a great
|
|||
mkpasswd --method=sha-512
|
||||
|
||||
|
||||
If this utility is not installed on your system (e.g. you are using macOS) then you can still easily
|
||||
If this utility is not installed on your system (for example, you are using macOS) then you can still easily
|
||||
generate these passwords using Python. First, ensure that the `Passlib <https://foss.heptapod.net/python-libs/passlib/-/wikis/home>`_
|
||||
password hashing library is installed:
|
||||
|
||||
|
|
@ -608,8 +608,8 @@ We also offer free web-based training classes on a regular basis. See our
|
|||
|
||||
.. _web_interface:
|
||||
|
||||
Is there a web interface / REST API / etc?
|
||||
++++++++++++++++++++++++++++++++++++++++++
|
||||
Is there a web interface / REST API / GUI?
|
||||
++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
Yes! Ansible, Inc makes a great product that makes Ansible even more powerful and easy to use. See :ref:`ansible_tower`.
|
||||
|
||||
|
|
@ -692,7 +692,7 @@ but you can still access the original via ``hostvars``::
|
|||
|
||||
original_host: "{{ hostvars[inventory_hostname]['ansible_host'] }}"
|
||||
|
||||
This works for all overridden connection variables, like ``ansible_user``, ``ansible_port``, etc.
|
||||
This works for all overridden connection variables, like ``ansible_user``, ``ansible_port``, and so on.
|
||||
|
||||
|
||||
.. _scp_protocol_error_filename:
|
||||
|
|
|
|||
|
|
@ -256,7 +256,7 @@ when a term comes up on the mailing list.
|
|||
|
||||
Lookup Plugin
|
||||
A lookup plugin is a way to get data into Ansible from the outside world.
|
||||
Lookup plugins are an extension of Jinja2 and can be accessed in templates, e.g.,
|
||||
Lookup plugins are an extension of Jinja2 and can be accessed in templates, for example,
|
||||
``{{ lookup('file','/path/to/file') }}``.
|
||||
These are how such things as ``with_items``, are implemented.
|
||||
There are also lookup plugins like ``file`` which loads data from
|
||||
|
|
@ -307,7 +307,7 @@ when a term comes up on the mailing list.
|
|||
things. Ansible uses it as a conductor would conduct an orchestra.
|
||||
A datacenter or cloud architecture is full of many systems, playing
|
||||
many parts -- web servers, database servers, maybe load balancers,
|
||||
monitoring systems, continuous integration systems, etc. In
|
||||
monitoring systems, continuous integration systems, and so on. In
|
||||
performing any process, it is necessary to touch systems in particular
|
||||
orders, often to simulate rolling updates or to deploy software
|
||||
correctly. Some system may perform some steps, then others, then
|
||||
|
|
@ -381,7 +381,7 @@ when a term comes up on the mailing list.
|
|||
Roles
|
||||
Roles are units of organization in Ansible. Assigning a role to
|
||||
a group of :term:`hosts <Host>` (or a set of :term:`groups <group>`,
|
||||
or :term:`host patterns <Globbing>`, etc.) implies that they should
|
||||
or :term:`host patterns <Globbing>`, and so on) implies that they should
|
||||
implement a specific behavior. A role may include applying certain
|
||||
variable values, certain :term:`tasks`, and certain :term:`handlers`
|
||||
-- or just one or more of these things. Because of the file structure
|
||||
|
|
@ -419,7 +419,7 @@ when a term comes up on the mailing list.
|
|||
Native OpenSSH as an Ansible transport is specified with ``-c ssh``
|
||||
(or a config file, or a directive in the :term:`playbook <playbooks>`)
|
||||
and can be useful if wanting to login via Kerberized SSH or using SSH
|
||||
jump hosts, etc. In 1.2.1, ``ssh`` will be used by default if the
|
||||
jump hosts, and so on. In 1.2.1, ``ssh`` will be used by default if the
|
||||
OpenSSH binary on the control machine is sufficiently new.
|
||||
Previously, Ansible selected ``paramiko`` as a default. Using
|
||||
a client that supports ``ControlMaster`` and ``ControlPersist`` is
|
||||
|
|
@ -485,7 +485,7 @@ when a term comes up on the mailing list.
|
|||
usage of YAML stemmed from Michael DeHaan's first use of it inside of
|
||||
Cobbler around 2006. YAML is fairly popular in the dynamic language
|
||||
community and the format has libraries available for serialization in
|
||||
many languages (Python, Perl, Ruby, etc.).
|
||||
many languages (Python, Perl, Ruby, and so on).
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
|
|
|||
|
|
@ -47,5 +47,5 @@ auto_silent
|
|||
Same as ``auto``, but does not issue warnings.
|
||||
|
||||
You can still set ``ansible_python_interpreter`` to a specific path at any
|
||||
variable level (for example, in host_vars, in vars files, in playbooks, etc.).
|
||||
variable level (for example, in host_vars, in vars files, in playbooks, and so on).
|
||||
Setting a specific path completely disables automatic interpreter discovery; Ansible always uses the path specified.
|
||||
|
|
|
|||
|
|
@ -38,13 +38,13 @@ ansible_index_var
|
|||
The name of the value provided to ``loop_control.index_var``. Added in ``2.9``
|
||||
|
||||
ansible_parent_role_names
|
||||
When the current role is being executed by means of an :ref:`include_role <include_role_module>` or :ref:`import_role <import_role_module>` action, this variable contains a list of all parent roles, with the most recent role (i.e. the role that included/imported this role) being the first item in the list.
|
||||
When multiple inclusions occur, this list lists the *last* role (i.e. the role that included this role) as the *first* item in the list. It is also possible that a specific role exists more than once in this list.
|
||||
When the current role is being executed by means of an :ref:`include_role <include_role_module>` or :ref:`import_role <import_role_module>` action, this variable contains a list of all parent roles, with the most recent role (in other words, the role that included/imported this role) being the first item in the list.
|
||||
When multiple inclusions occur, this list lists the *last* role (in other words, the role that included this role) as the *first* item in the list. It is also possible that a specific role exists more than once in this list.
|
||||
|
||||
For example: When role **A** includes role **B**, inside role B, ``ansible_parent_role_names`` will equal to ``['A']``. If role **B** then includes role **C**, the list becomes ``['B', 'A']``.
|
||||
|
||||
ansible_parent_role_paths
|
||||
When the current role is being executed by means of an :ref:`include_role <include_role_module>` or :ref:`import_role <import_role_module>` action, this variable contains a list of all parent roles, with the most recent role (i.e. the role that included/imported this role) being the first item in the list.
|
||||
When the current role is being executed by means of an :ref:`include_role <include_role_module>` or :ref:`import_role <import_role_module>` action, this variable contains a list of all parent roles, with the most recent role (in other words, the role that included/imported this role) being the first item in the list.
|
||||
Please refer to ``ansible_parent_role_names`` for the order of items in this list.
|
||||
|
||||
ansible_play_batch
|
||||
|
|
@ -77,7 +77,7 @@ ansible_run_tags
|
|||
Contents of the ``--tags`` CLI option, which specifies which tags will be included for the current run.
|
||||
|
||||
ansible_search_path
|
||||
Current search path for action plugins and lookups, i.e where we search for relative paths when you do ``template: src=myfile``
|
||||
Current search path for action plugins and lookups, in other words, where we search for relative paths when you do ``template: src=myfile``
|
||||
|
||||
ansible_skip_tags
|
||||
Contents of the ``--skip-tags`` CLI option, which specifies which tags will be skipped for the current run.
|
||||
|
|
@ -110,7 +110,7 @@ inventory_file
|
|||
The file name of the inventory source in which the `inventory_hostname` was first defined
|
||||
|
||||
omit
|
||||
Special variable that allows you to 'omit' an option in a task, i.e ``- user: name=bob home={{ bobs_home|default(omit) }}``
|
||||
Special variable that allows you to 'omit' an option in a task, for example ``- user: name=bob home={{ bobs_home|default(omit) }}``
|
||||
|
||||
play_hosts
|
||||
Deprecated, the same as ansible_play_batch
|
||||
|
|
|
|||
|
|
@ -97,7 +97,7 @@ AWS
|
|||
|
||||
- ec2_instance
|
||||
- ec2_vpc: Allow the addition of secondary IPv4 CIDRS to existing VPCs.
|
||||
- AWS Network Load Balancer support (NLB module, ASG support, etc)
|
||||
- AWS Network Load Balancer support (NLB module, ASG support, and so on)
|
||||
- rds_instance
|
||||
|
||||
Azure
|
||||
|
|
|
|||
27
docs/docsite/rst/roadmap/ansible_base_roadmap_index.rst
Normal file
27
docs/docsite/rst/roadmap/ansible_base_roadmap_index.rst
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
.. _ansible_base_roadmaps:
|
||||
|
||||
ansible-base Roadmap
|
||||
=====================
|
||||
|
||||
The ``ansible-base`` team develops a roadmap for each major and minor ``ansible-base`` release. The latest roadmap shows current work; older roadmaps provide a history of the project. We don't publish roadmaps for subminor versions. So 2.10 and 2.11 have roadmaps, but 2.10.1 does not.
|
||||
|
||||
We incorporate team and community feedback in each roadmap, and aim for further transparency and better inclusion of both community desires and submissions.
|
||||
|
||||
Each roadmap offers a *best guess*, based on the ``ansible-base`` team's experience and on requests and feedback from the community, of what will be included in a given release. However, some items on the roadmap may be dropped due to time constraints, lack of community maintainers, and so on.
|
||||
|
||||
Each roadmap is published both as an idea of what is upcoming in ``ansible-base``, and as a medium for seeking further feedback from the community.
|
||||
|
||||
You can submit feedback on the current roadmap in multiple ways:
|
||||
|
||||
- Edit the agenda of an IRC `Core Team Meeting <https://github.com/ansible/community/blob/master/meetings/README.md>`_ (preferred)
|
||||
- Post on the ``#ansible-devel`` Freenode IRC channel
|
||||
- Email the ansible-devel list
|
||||
|
||||
See :ref:`Ansible communication channels <communication>` for details on how to join and use the email lists and IRC channels.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
:caption: ansible-base Roadmaps
|
||||
|
||||
ROADMAP_2_10
|
||||
26
docs/docsite/rst/roadmap/ansible_roadmap_index.rst
Normal file
26
docs/docsite/rst/roadmap/ansible_roadmap_index.rst
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
.. _ansible_roadmaps:
|
||||
|
||||
Ansible Roadmap
|
||||
===============
|
||||
|
||||
The Ansible team develops a roadmap for each major and minor Ansible release. The latest roadmap shows current work; older roadmaps provide a history of the project. We don't publish roadmaps for subminor versions. So 2.10 and 2.11 have roadmaps, but 2.10.1 does not.
|
||||
|
||||
We incorporate team and community feedback in each roadmap, and aim for further transparency and better inclusion of both community desires and submissions.
|
||||
|
||||
Each roadmap offers a *best guess*, based on the Ansible team's experience and on requests and feedback from the community, of what will be included in a given release. However, some items on the roadmap may be dropped due to time constraints, lack of community maintainers, and so on.
|
||||
|
||||
Each roadmap is published both as an idea of what is upcoming in Ansible, and as a medium for seeking further feedback from the community.
|
||||
|
||||
You can submit feedback on the current roadmap in multiple ways:
|
||||
|
||||
- Edit the agenda of an IRC `Ansible Community Meeting <https://github.com/ansible/community/issues/539>`_ (preferred)
|
||||
- Post on the ``#ansible-community`` Freenode IRC channel
|
||||
|
||||
See :ref:`Ansible communication channels <communication>` for details on how to join and use the IRC channels.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
:caption: Ansible Release Roadmaps
|
||||
|
||||
COLLECTIONS_2_10
|
||||
|
|
@ -22,12 +22,8 @@ See :ref:`Ansible communication channels <communication>` for details on how to
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
:caption: Ansible Release Roadmaps
|
||||
:caption: Ansible Roadmaps
|
||||
|
||||
COLLECTIONS_2_10
|
||||
ROADMAP_2_10
|
||||
ROADMAP_2_9
|
||||
ROADMAP_2_8
|
||||
ROADMAP_2_7
|
||||
ROADMAP_2_6
|
||||
ROADMAP_2_5
|
||||
ansible_base_roadmap_index
|
||||
ansible_roadmap_index
|
||||
old_roadmap_index
|
||||
|
|
|
|||
19
docs/docsite/rst/roadmap/old_roadmap_index.rst
Normal file
19
docs/docsite/rst/roadmap/old_roadmap_index.rst
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
.. _old_roadmaps:
|
||||
|
||||
Older Roadmaps
|
||||
===============
|
||||
|
||||
Older roadmaps are listed here to provide a history of the Ansible project.
|
||||
|
||||
See :ref:`roadmaps` to find current Ansible and ``ansible-base`` roadmaps.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
:caption: Older Roadmaps
|
||||
|
||||
ROADMAP_2_9
|
||||
ROADMAP_2_8
|
||||
ROADMAP_2_7
|
||||
ROADMAP_2_6
|
||||
ROADMAP_2_5
|
||||
|
|
@ -591,7 +591,7 @@ APIC error messages
|
|||
The following error messages may occur and this section can help you understand what exactly is going on and how to fix/avoid them.
|
||||
|
||||
APIC Error 122: unknown managed object class 'polUni'
|
||||
In case you receive this error while you are certain your aci_rest payload and object classes are seemingly correct, the issue might be that your payload is not in fact correct JSON (e.g. the sent payload is using single quotes, rather than double quotes), and as a result the APIC is not correctly parsing your object classes from the payload. One way to avoid this is by using a YAML or an XML formatted payload, which are easier to construct correctly and modify later.
|
||||
In case you receive this error while you are certain your aci_rest payload and object classes are seemingly correct, the issue might be that your payload is not in fact correct JSON (for example, the sent payload is using single quotes, rather than double quotes), and as a result the APIC is not correctly parsing your object classes from the payload. One way to avoid this is by using a YAML or an XML formatted payload, which are easier to construct correctly and modify later.
|
||||
|
||||
|
||||
APIC Error 400: invalid data at line '1'. Attributes are missing, tag 'attributes' must be specified first, before any other tag
|
||||
|
|
@ -619,7 +619,7 @@ All below issues either have been reported to the vendor, and most can simply be
|
|||
Specific requests may not reflect changes correctly (`#35401 <https://github.com/ansible/ansible/issues/35041>`_)
|
||||
There is a known issue where specific requests to the APIC do not properly reflect changed in the resulting output, even when we request those changes explicitly from the APIC. In one instance using the path ``api/node/mo/uni/infra.xml`` fails, where ``api/node/mo/uni/infra/.xml`` does work correctly.
|
||||
|
||||
**NOTE:** A workaround is to register the task return values (e.g. ``register: this``) and influence when the task should report a change by adding: ``changed_when: this.imdata != []``.
|
||||
**NOTE:** A workaround is to register the task return values (for example, ``register: this``) and influence when the task should report a change by adding: ``changed_when: this.imdata != []``.
|
||||
|
||||
|
||||
Specific requests are known to not be idempotent (`#35050 <https://github.com/ansible/ansible/issues/35050>`_)
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ After stepping through the tutorial you will have:
|
|||
* Your Client ID, which is found in the "client id" box in the "Configure" page of your application in the Azure portal
|
||||
* Your Secret key, generated when you created the application. You cannot show the key after creation.
|
||||
If you lost the key, you must create a new one in the "Configure" page of your application.
|
||||
* And finally, a tenant ID. It's a UUID (e.g. ABCDEFGH-1234-ABCD-1234-ABCDEFGHIJKL) pointing to the AD containing your
|
||||
* And finally, a tenant ID. It's a UUID (for example, ABCDEFGH-1234-ABCD-1234-ABCDEFGHIJKL) pointing to the AD containing your
|
||||
application. You will find it in the URL from within the Azure portal, or in the "view endpoints" of any given URL.
|
||||
|
||||
|
||||
|
|
@ -364,7 +364,7 @@ azure_rm.ini file in your current working directory.
|
|||
|
||||
NOTE: An .ini file will take precedence over environment variables.
|
||||
|
||||
NOTE: The name of the .ini file is the basename of the inventory script (i.e. 'azure_rm') with a '.ini'
|
||||
NOTE: The name of the .ini file is the basename of the inventory script (in other words, 'azure_rm') with a '.ini'
|
||||
extension. This allows you to copy, rename and customize the inventory script and have matching .ini files all in
|
||||
the same directory.
|
||||
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ Or alternatively starting with Debian 9 and Ubuntu 16.04:
|
|||
|
||||
$ sudo apt install python-cs
|
||||
|
||||
.. note:: cs also includes a command line interface for ad-hoc interaction with the CloudStack API e.g. ``$ cs listVirtualMachines state=Running``.
|
||||
.. note:: cs also includes a command line interface for ad-hoc interaction with the CloudStack API, for example ``$ cs listVirtualMachines state=Running``.
|
||||
|
||||
Limitations and Known Issues
|
||||
````````````````````````````
|
||||
|
|
@ -58,7 +58,7 @@ The structure of the ini file must look like this:
|
|||
|
||||
.. versionadded:: 2.4
|
||||
|
||||
The ENV variables support ``CLOUDSTACK_*`` as written in the documentation of the library ``cs``, like e.g ``CLOUDSTACK_TIMEOUT``, ``CLOUDSTACK_METHOD``, etc. has been implemented into Ansible. It is even possible to have some incomplete config in your cloudstack.ini:
|
||||
The ENV variables support ``CLOUDSTACK_*`` as written in the documentation of the library ``cs``, like ``CLOUDSTACK_TIMEOUT``, ``CLOUDSTACK_METHOD``, and so on. has been implemented into Ansible. It is even possible to have some incomplete config in your cloudstack.ini:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -84,7 +84,7 @@ and fulfill the missing data by either setting ENV variables or tasks params:
|
|||
|
||||
Regions
|
||||
```````
|
||||
If you use more than one CloudStack region, you can define as many sections as you want and name them as you like, e.g.:
|
||||
If you use more than one CloudStack region, you can define as many sections as you want and name them as you like, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -163,7 +163,7 @@ Below you see an example how it can be used in combination with Ansible's block
|
|||
CLOUDSTACK_PROJECT: web-app
|
||||
CLOUDSTACK_ZONE: sf-1
|
||||
|
||||
.. Note:: You are still able overwrite the environment variables using the module arguments, e.g. ``zone: sf-2``
|
||||
.. Note:: You are still able overwrite the environment variables using the module arguments, for example ``zone: sf-2``
|
||||
|
||||
.. Note:: Unlike ``CLOUDSTACK_REGION`` these additional environment variables are ignored in the CLI ``cs``.
|
||||
|
||||
|
|
@ -275,7 +275,7 @@ In the third task we add static NAT to the VMs having a public IP defined.
|
|||
|
||||
.. Note:: The public IP addresses must have been acquired in advance, also see ``cs_ip_address``
|
||||
|
||||
.. Note:: For some modules, e.g. ``cs_sshkeypair`` you usually want this to be executed only once, not for every VM. Therefore you would make a separate play for it targeting localhost. You find an example in the use cases below.
|
||||
.. Note:: For some modules, for example ``cs_sshkeypair`` you usually want this to be executed only once, not for every VM. Therefore you would make a separate play for it targeting localhost. You find an example in the use cases below.
|
||||
|
||||
Use Case: Provisioning on a Basic Networking CloudStack setup
|
||||
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
|
|
|||
|
|
@ -262,7 +262,7 @@ Configuration File
|
|||
Using a configuration file provides a means for defining a set of Docker APIs from which to build an inventory.
|
||||
|
||||
The default name of the file is derived from the name of the inventory script. By default the script will look for
|
||||
basename of the script (i.e. docker) with an extension of '.yml'.
|
||||
basename of the script (in other words, docker) with an extension of '.yml'.
|
||||
|
||||
You can also override the default name of the script by defining DOCKER_CONFIG_FILE in the environment.
|
||||
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ The 'device_ids' and 'hostnames' parameters are mutually exclusive. The followin
|
|||
|
||||
- hostnames: [mydev1, mydev2]
|
||||
|
||||
In addition, hostnames can contain a special '%d' formatter along with a 'count' parameter that lets you easily expand hostnames that follow a simple name and number pattern; i.e. ``hostnames: "mydev%d", count: 2`` will expand to [mydev1, mydev2].
|
||||
In addition, hostnames can contain a special '%d' formatter along with a 'count' parameter that lets you easily expand hostnames that follow a simple name and number pattern; in other words, ``hostnames: "mydev%d", count: 2`` will expand to [mydev1, mydev2].
|
||||
|
||||
If your playbook acts on existing Packet devices, you can only pass the 'hostname' and 'device_ids' parameters. The following playbook shows how you can reboot a specific Packet device by setting the 'hostname' parameter:
|
||||
|
||||
|
|
|
|||
|
|
@ -154,7 +154,7 @@ to the next section.
|
|||
Host Inventory
|
||||
``````````````
|
||||
|
||||
Once your nodes are spun up, you'll probably want to talk to them again. The best way to handle this is to use the "rax" inventory plugin, which dynamically queries Rackspace Cloud and tells Ansible what nodes you have to manage. You might want to use this even if you are spinning up cloud instances via other tools, including the Rackspace Cloud user interface. The inventory plugin can be used to group resources by metadata, region, OS, etc. Utilizing metadata is highly recommended in "rax" and can provide an easy way to sort between host groups and roles. If you don't want to use the ``rax.py`` dynamic inventory script, you could also still choose to manually manage your INI inventory file, though this is less recommended.
|
||||
Once your nodes are spun up, you'll probably want to talk to them again. The best way to handle this is to use the "rax" inventory plugin, which dynamically queries Rackspace Cloud and tells Ansible what nodes you have to manage. You might want to use this even if you are spinning up cloud instances via other tools, including the Rackspace Cloud user interface. The inventory plugin can be used to group resources by metadata, region, OS, and so on. Utilizing metadata is highly recommended in "rax" and can provide an easy way to sort between host groups and roles. If you don't want to use the ``rax.py`` dynamic inventory script, you could also still choose to manually manage your INI inventory file, though this is less recommended.
|
||||
|
||||
In Ansible it is quite possible to use multiple dynamic inventory plugins along with INI file data. Just put them in a common directory and be sure the scripts are chmod +x, and the INI-based ones are not.
|
||||
|
||||
|
|
|
|||
|
|
@ -246,7 +246,7 @@ This means that for each tag that exists on your Scaleway compute nodes, a group
|
|||
Scaleway S3 object storage
|
||||
==========================
|
||||
|
||||
`Object Storage <https://www.scaleway.com/object-storage>`_ allows you to store any kind of objects (documents, images, videos, etc.).
|
||||
`Object Storage <https://www.scaleway.com/object-storage>`_ allows you to store any kind of objects (documents, images, videos, and so on).
|
||||
As the Scaleway API is S3 compatible, Ansible supports it natively through the modules: :ref:`s3_bucket_module`, :ref:`aws_s3_module`.
|
||||
|
||||
You can find many examples in the `scaleway_s3 integration tests <https://github.com/ansible/ansible-legacy-tests/tree/devel/test/legacy/roles/scaleway_s3>`_.
|
||||
|
|
|
|||
|
|
@ -164,7 +164,7 @@ Run all Vultr tests:
|
|||
$ ansible-test integration cloud/vultr/ -v --diff --allow-unsupported
|
||||
|
||||
|
||||
To run a specific test, e.g. vultr_account_info:
|
||||
To run a specific test, for example vultr_account_info:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
|
|
|||
|
|
@ -545,7 +545,7 @@ Detailed information about the files that comprise the virtual machine.
|
|||
file (vim.vm.FileLayoutEx.FileInfo, optional)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Information about all the files that constitute the virtual machine including configuration files, disks, swap file, suspend file, log files, core files, memory file etc.
|
||||
Information about all the files that constitute the virtual machine including configuration files, disks, swap file, suspend file, log files, core files, memory file and so on.
|
||||
|
||||
disk (vim.vm.FileLayoutEx.DiskLayout, optional)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
|
|
|||
|
|
@ -180,7 +180,7 @@ Not supported by all connection plugins
|
|||
|
||||
Privilege escalation methods must also be supported by the connection plugin
|
||||
used. Most connection plugins will warn if they do not support become. Some
|
||||
will just ignore it as they always run as root (jail, chroot, etc).
|
||||
will just ignore it as they always run as root (jail, chroot, and so on).
|
||||
|
||||
Only one method may be enabled per host
|
||||
---------------------------------------
|
||||
|
|
|
|||
|
|
@ -310,7 +310,7 @@ In a playbook, you can control the collections Ansible searches for modules and
|
|||
- debug:
|
||||
msg: '{{ lookup("my_namespace.my_collection.lookup1", 'param1')| my_namespace.my_collection.filter1 }}'
|
||||
|
||||
The ``collections`` keyword merely creates an ordered 'search path' for non-namespaced plugin and role references. It does not install content or otherwise change Ansible's behavior around the loading of plugins or roles. Note that an FQCN is still required for non-action or module plugins (e.g., lookups, filters, tests).
|
||||
The ``collections`` keyword merely creates an ordered 'search path' for non-namespaced plugin and role references. It does not install content or otherwise change Ansible's behavior around the loading of plugins or roles. Note that an FQCN is still required for non-action or module plugins (for example, lookups, filters, tests).
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Let's start with a quick definition of each type of plugin:
|
|||
Loops and list comprehensions
|
||||
=============================
|
||||
|
||||
Most programming languages have loops (``for``, ``while``, etc.) and list comprehensions to do transformations on lists including lists of objects. Jinja2 has a few filters that provide this functionality: ``map``, ``select``, ``reject``, ``selectattr``, ``rejectattr``.
|
||||
Most programming languages have loops (``for``, ``while``, and so on) and list comprehensions to do transformations on lists including lists of objects. Jinja2 has a few filters that provide this functionality: ``map``, ``select``, ``reject``, ``selectattr``, ``rejectattr``.
|
||||
|
||||
- map: this is a basic for loop that just allows you to change every item in a list, using the 'attribute' keyword you can do the transformation based on attributes of the list elements.
|
||||
- select/reject: this is a for loop with a condition, that allows you to create a subset of a list that matches (or not) based on the result of the condition.
|
||||
|
|
@ -141,7 +141,7 @@ Another way is to avoid adding elements to the list in the first place, so you c
|
|||
Complex Type transformations
|
||||
=============================
|
||||
|
||||
Jinja provides filters for simple data type transformations (``int``, ``bool``, etc), but when you want to transform data structures things are not as easy.
|
||||
Jinja provides filters for simple data type transformations (``int``, ``bool``, and so on), but when you want to transform data structures things are not as easy.
|
||||
You can use loops and list comprehensions as shown above to help, also other filters and lookups can be chained and leveraged to achieve more complex transformations.
|
||||
|
||||
|
||||
|
|
@ -150,7 +150,7 @@ You can use loops and list comprehensions as shown above to help, also other fil
|
|||
Create dictionary from list
|
||||
---------------------------
|
||||
|
||||
In most languages it is easy to create a dictionary (a.k.a. map/associative array/hash etc.) from a list of pairs, in Ansible there are a couple of ways to do it and the best one for you might depend on the source of your data.
|
||||
In most languages it is easy to create a dictionary (a.k.a. map/associative array/hash and so on) from a list of pairs, in Ansible there are a couple of ways to do it and the best one for you might depend on the source of your data.
|
||||
|
||||
|
||||
These example produces ``{"a": "b", "c": "d"}``
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ or as a group variable in inventory:
|
|||
Setting up SSH keys
|
||||
-------------------
|
||||
|
||||
By default, Ansible assumes you are using SSH keys to connect to remote machines. SSH keys are encouraged, but you can use password authentication if needed with the ``--ask-pass`` option. If you need to provide a password for :ref:`privilege escalation <become>` (sudo, pbrun, etc.), use ``--ask-become-pass``.
|
||||
By default, Ansible assumes you are using SSH keys to connect to remote machines. SSH keys are encouraged, but you can use password authentication if needed with the ``--ask-pass`` option. If you need to provide a password for :ref:`privilege escalation <become>` (sudo, pbrun, and so on), use ``--ask-become-pass``.
|
||||
|
||||
.. include:: shared_snippets/SSH_password_prompt.txt
|
||||
|
||||
|
|
|
|||
|
|
@ -219,7 +219,7 @@ Looking at the playbook, you can see it is made up of two plays. The first play
|
|||
- hosts: monitoring
|
||||
tasks: []
|
||||
|
||||
What's going on here, and why are there no tasks? You might know that Ansible gathers "facts" from the servers before operating upon them. These facts are useful for all sorts of things: networking information, OS/distribution versions, etc. In our case, we need to know something about all of the monitoring servers in our environment before we perform the update, so this simple play forces a fact-gathering step on our monitoring servers. You will see this pattern sometimes, and it's a useful trick to know.
|
||||
What's going on here, and why are there no tasks? You might know that Ansible gathers "facts" from the servers before operating upon them. These facts are useful for all sorts of things: networking information, OS/distribution versions, and so on. In our case, we need to know something about all of the monitoring servers in our environment before we perform the update, so this simple play forces a fact-gathering step on our monitoring servers. You will see this pattern sometimes, and it's a useful trick to know.
|
||||
|
||||
The next part is the update play. The first part looks like this:
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ Ansible integrates seamlessly with `Cobbler <https://cobbler.github.io>`_, a Lin
|
|||
While primarily used to kickoff OS installations and manage DHCP and DNS, Cobbler has a generic
|
||||
layer that can represent data for multiple configuration management systems (even at the same time) and serve as a 'lightweight CMDB'.
|
||||
|
||||
To tie your Ansible inventory to Cobbler, copy `this script <https://raw.githubusercontent.com/ansible-collections/community.general/main/scripts/inventory/cobbler.py>`_ to ``/etc/ansible`` and ``chmod +x`` the file. Run ``cobblerd`` any time you use Ansible and use the ``-i`` command line option (e.g. ``-i /etc/ansible/cobbler.py``) to communicate with Cobbler using Cobbler's XMLRPC API.
|
||||
To tie your Ansible inventory to Cobbler, copy `this script <https://raw.githubusercontent.com/ansible-collections/community.general/main/scripts/inventory/cobbler.py>`_ to ``/etc/ansible`` and ``chmod +x`` the file. Run ``cobblerd`` any time you use Ansible and use the ``-i`` command line option (for example, ``-i /etc/ansible/cobbler.py``) to communicate with Cobbler using Cobbler's XMLRPC API.
|
||||
|
||||
Add a ``cobbler.ini`` file in ``/etc/ansible`` so Ansible knows where the Cobbler server is and some cache improvements can be used. For example:
|
||||
|
||||
|
|
@ -104,7 +104,7 @@ And technically, though there is no major good reason to do it, this also works
|
|||
|
||||
ansible webserver -m shell -a "echo {{ a }}"
|
||||
|
||||
So in other words, you can use those variables in arguments/actions as well.
|
||||
So, in other words, you can use those variables in arguments/actions as well.
|
||||
|
||||
.. _openstack_example:
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ How to build your inventory
|
|||
|
||||
Ansible works against multiple managed nodes or "hosts" in your infrastructure at the same time, using a list or group of lists known as inventory. Once your inventory is defined, you use :ref:`patterns <intro_patterns>` to select the hosts or groups you want Ansible to run against.
|
||||
|
||||
The default location for inventory is a file called ``/etc/ansible/hosts``. You can specify a different inventory file at the command line using the ``-i <path>`` option. You can also use multiple inventory files at the same time, and/or pull inventory from dynamic or cloud sources or different formats (YAML, ini, etc), as described in :ref:`intro_dynamic_inventory`.
|
||||
The default location for inventory is a file called ``/etc/ansible/hosts``. You can specify a different inventory file at the command line using the ``-i <path>`` option. You can also use multiple inventory files at the same time, and/or pull inventory from dynamic or cloud sources or different formats (YAML, ini, and so on), as described in :ref:`intro_dynamic_inventory`.
|
||||
Introduced in version 2.4, Ansible has :ref:`inventory_plugins` to make this flexible and customizable.
|
||||
|
||||
.. contents::
|
||||
|
|
@ -72,8 +72,8 @@ Hosts in multiple groups
|
|||
|
||||
You can (and probably will) put each host in more than one group. For example a production webserver in a datacenter in Atlanta might be included in groups called [prod] and [atlanta] and [webservers]. You can create groups that track:
|
||||
|
||||
* What - An application, stack or microservice. (For example, database servers, web servers, etc).
|
||||
* Where - A datacenter or region, to talk to local DNS, storage, etc. (For example, east, west).
|
||||
* What - An application, stack or microservice. (For example, database servers, web servers, and so on).
|
||||
* Where - A datacenter or region, to talk to local DNS, storage, and so on. (For example, east, west).
|
||||
* When - The development stage, to avoid testing on production resources. (For example, prod, test).
|
||||
|
||||
Extending the previous YAML inventory to include what, when, and where would look like:
|
||||
|
|
@ -421,7 +421,7 @@ All hosts in the 'raleigh' group will have the variables defined in these files
|
|||
available to them. This can be very useful to keep your variables organized when a single
|
||||
file gets too big, or when you want to use :ref:`Ansible Vault<playbooks_vault>` on some group variables.
|
||||
|
||||
You can also add ``group_vars/`` and ``host_vars/`` directories to your playbook directory. The ``ansible-playbook`` command looks for these directories in the current working directory by default. Other Ansible commands (for example, ``ansible``, ``ansible-console``, etc.) will only look for ``group_vars/`` and ``host_vars/`` in the inventory directory. If you want other commands to load group and host variables from a playbook directory, you must provide the ``--playbook-dir`` option on the command line.
|
||||
You can also add ``group_vars/`` and ``host_vars/`` directories to your playbook directory. The ``ansible-playbook`` command looks for these directories in the current working directory by default. Other Ansible commands (for example, ``ansible``, ``ansible-console``, and so on) will only look for ``group_vars/`` and ``host_vars/`` in the inventory directory. If you want other commands to load group and host variables from a playbook directory, you must provide the ``--playbook-dir`` option on the command line.
|
||||
If you load inventory files from both the playbook directory and the inventory directory, variables in the playbook directory will override variables set in the inventory directory.
|
||||
|
||||
Keeping your inventory file and variables in a git repo (or other version control)
|
||||
|
|
@ -611,7 +611,7 @@ ansible_shell_executable
|
|||
This sets the shell the ansible controller will use on the target machine,
|
||||
overrides ``executable`` in :file:`ansible.cfg` which defaults to
|
||||
:command:`/bin/sh`. You should really only change it if is not possible
|
||||
to use :command:`/bin/sh` (i.e. :command:`/bin/sh` is not installed on the target
|
||||
to use :command:`/bin/sh` (in other words, if :command:`/bin/sh` is not installed on the target
|
||||
machine or cannot be run from sudo.).
|
||||
|
||||
Examples from an Ansible-INI host file:
|
||||
|
|
|
|||
|
|
@ -25,8 +25,8 @@ The magic of 'local' paths
|
|||
|
||||
Lookups and action plugins both use a special 'search magic' to find things, taking the current play into account, it uses from most specific to most general playbook dir in which a task is contained (this includes roles and includes).
|
||||
|
||||
Using this magic, relative paths get attempted first with a 'files|templates|vars' appended (if not already present), depending on action being taken, 'files' is the default. (i.e include_vars will use vars/). The paths will be searched from most specific to most general (i.e role before play).
|
||||
dependent roles WILL be traversed (i.e task is in role2, role2 is a dependency of role1, role2 will be looked at first, then role1, then play).
|
||||
Using this magic, relative paths get attempted first with a 'files|templates|vars' appended (if not already present), depending on action being taken, 'files' is the default. (in other words, include_vars will use vars/). The paths will be searched from most specific to most general (in other words, role before play).
|
||||
dependent roles WILL be traversed (in other words, task is in role2, role2 is a dependency of role1, role2 will be looked at first, then role1, then play).
|
||||
i.e ::
|
||||
|
||||
role search path is rolename/{files|vars|templates}/, rolename/tasks/.
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ You can provide default values for variables directly in your templates using th
|
|||
In the above example, if the variable 'some_variable' is not defined, Ansible uses the default value 5, rather than raising an "undefined variable" error and failing. If you are working within a role, you can also add a ``defaults/main.yml`` to define the default values for variables in your role.
|
||||
|
||||
Beginning in version 2.8, attempting to access an attribute of an Undefined value in Jinja will return another Undefined value, rather than throwing an error immediately. This means that you can now simply use
|
||||
a default with a value in a nested data structure (i.e :code:`{{ foo.bar.baz | default('DEFAULT') }}`) when you do not know if the intermediate values are defined.
|
||||
a default with a value in a nested data structure (in other words, :code:`{{ foo.bar.baz | default('DEFAULT') }}`) when you do not know if the intermediate values are defined.
|
||||
|
||||
If you want to use the default value when variables evaluate to false or an empty string you have to set the second parameter to ``true``::
|
||||
|
||||
|
|
@ -1456,7 +1456,7 @@ To replace text in a string with regex, use the "regex_replace" filter::
|
|||
{{ hosts | map('regex_replace', '(.*)', '\\1:80') | list }}
|
||||
|
||||
.. note::
|
||||
Prior to ansible 2.0, if "regex_replace" filter was used with variables inside YAML arguments (as opposed to simpler 'key=value' arguments), then you needed to escape backreferences (e.g. ``\\1``) with 4 backslashes (``\\\\``) instead of 2 (``\\``).
|
||||
Prior to ansible 2.0, if "regex_replace" filter was used with variables inside YAML arguments (as opposed to simpler 'key=value' arguments), then you needed to escape backreferences (for example, ``\\1``) with 4 backslashes (``\\\\``) instead of 2 (``\\``).
|
||||
|
||||
.. versionadded:: 2.0
|
||||
|
||||
|
|
@ -1585,7 +1585,7 @@ To create a namespaced UUIDv5 using the default Ansible namespace '361E6D51-FAEC
|
|||
|
||||
To make use of one attribute from each item in a list of complex variables, use the :func:`Jinja2 map filter <jinja2:map>`::
|
||||
|
||||
# get a comma-separated list of the mount points (e.g. "/,/mnt/stuff") on a host
|
||||
# get a comma-separated list of the mount points (for example, "/,/mnt/stuff") on a host
|
||||
{{ ansible_mounts | map(attribute='mount') | join(',') }}
|
||||
|
||||
Handling dates and times
|
||||
|
|
@ -1596,7 +1596,7 @@ To get a date object from a string use the `to_datetime` filter::
|
|||
# Get total amount of seconds between two dates. Default date format is %Y-%m-%d %H:%M:%S but you can pass your own format
|
||||
{{ (("2016-08-14 20:00:12" | to_datetime) - ("2015-12-25" | to_datetime('%Y-%m-%d'))).total_seconds() }}
|
||||
|
||||
# Get remaining seconds after delta has been calculated. NOTE: This does NOT convert years, days, hours, etc to seconds. For that, use total_seconds()
|
||||
# Get remaining seconds after delta has been calculated. NOTE: This does NOT convert years, days, hours, and so on to seconds. For that, use total_seconds()
|
||||
{{ (("2016-08-14 20:00:12" | to_datetime) - ("2016-08-14 18:00:00" | to_datetime)).seconds }}
|
||||
# This expression evaluates to "12" and not "132". Delta is 2 hours, 12 seconds
|
||||
|
||||
|
|
|
|||
|
|
@ -272,8 +272,8 @@ More information on the patterns can be found in :ref:`intro_patterns`.
|
|||
|
||||
.. _query_vs_lookup:
|
||||
|
||||
Ensuring list input for ``loop``: ``query`` vs. ``lookup``
|
||||
==========================================================
|
||||
Ensuring list input for ``loop``: using ``query`` rather than ``lookup``
|
||||
========================================================================
|
||||
|
||||
The ``loop`` keyword requires a list as input, but the ``lookup`` keyword returns a string of comma-separated values by default. Ansible 2.5 introduced a new Jinja2 function named :ref:`query <query>` that always returns a list, offering a simpler interface and more predictable output from lookup plugins when using the ``loop`` keyword.
|
||||
|
||||
|
|
|
|||
|
|
@ -108,7 +108,7 @@ Ansible 2.7 adds a preview-status feature to group together modules that share c
|
|||
|
||||
* The `docker_stack <docker_stack_module>`_ module is not included in the ``docker`` defaults group.
|
||||
|
||||
Use the groups with ``module_defaults`` by prefixing the group name with ``group/`` - e.g. ``group/aws``.
|
||||
Use the groups with ``module_defaults`` by prefixing the group name with ``group/`` - for example ``group/aws``.
|
||||
|
||||
In a playbook, you can set module defaults for whole groups of modules, such as setting a common AWS region.
|
||||
|
||||
|
|
|
|||
|
|
@ -84,8 +84,8 @@ See :ref:`ansible_variable_precedence` for more details on variable inheritance
|
|||
|
||||
.. _dynamic_vs_static:
|
||||
|
||||
Comparing includes and imports: dynamic vs. static
|
||||
--------------------------------------------------
|
||||
Comparing includes and imports: dynamic and static re-use
|
||||
------------------------------------------------------------
|
||||
|
||||
Each approach to re-using distributed Ansible artifacts has advantages and limitations. You may choose dynamic re-use for some playbooks and static re-use for others. Although you can use both dynamic and static re-use in a single playbook, it is best to select one approach per playbook. Mixing static and dynamic re-use can introduce difficult-to-diagnose bugs into your playbooks. This table summarizes the main differences so you can choose the best approach for each playbook you create.
|
||||
|
||||
|
|
|
|||
|
|
@ -197,7 +197,7 @@ As always with :ref:`delegation <playbooks_delegation>`, the action will be exec
|
|||
:code:`when: inventory_hostname == ansible_play_hosts_all[0]` construct.
|
||||
|
||||
.. note::
|
||||
Any conditional (i.e `when:`) will use the variables of the 'first host' to decide if the task runs or not, no other hosts will be tested.
|
||||
Any conditional (in other words, `when:`) will use the variables of the 'first host' to decide if the task runs or not, no other hosts will be tested.
|
||||
|
||||
.. note::
|
||||
If you want to avoid the default behavior of setting the fact for all hosts, set ``delegate_facts: True`` for the specific task or block.
|
||||
|
|
|
|||
|
|
@ -271,7 +271,7 @@ JSON string format
|
|||
ansible-playbook release.yml --extra-vars '{"version":"1.23.45","other_variable":"foo"}'
|
||||
ansible-playbook arcade.yml --extra-vars '{"pacman":"mrs","ghosts":["inky","pinky","clyde","sue"]}'
|
||||
|
||||
When passing variables with ``--extra-vars``, you must escape quotes and other special characters appropriately for both your markup (e.g. JSON), and for your shell::
|
||||
When passing variables with ``--extra-vars``, you must escape quotes and other special characters appropriately for both your markup (for example, JSON), and for your shell::
|
||||
|
||||
ansible-playbook arcade.yml --extra-vars "{\"name\":\"Conan O\'Brien\"}"
|
||||
ansible-playbook arcade.yml --extra-vars '{"name":"Conan O'\\\''Brien"}'
|
||||
|
|
|
|||
|
|
@ -534,7 +534,7 @@ If your task or playbook requires multiple encrypted variables or files that you
|
|||
|
||||
ansible-playbook --vault-id dev@dev-password --vault-id prod@prompt site.yml
|
||||
|
||||
By default the vault ID labels (dev, prod etc.) are only hints. Ansible attempts to decrypt vault content with each password. The password with the same label as the encrypted data will be tried first, after that each vault secret will be tried in the order they were provided on the command line.
|
||||
By default the vault ID labels (dev, prod and so on) are only hints. Ansible attempts to decrypt vault content with each password. The password with the same label as the encrypted data will be tried first, after that each vault secret will be tried in the order they were provided on the command line.
|
||||
|
||||
Where the encrypted data has no label, or the label does not match any of the provided labels, the passwords will be tried in the order they are specified. In the example above, the 'dev' password will be tried first, then the 'prod' password for cases where Ansible doesn't know which vault ID is used to encrypt something.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue