diff options
| author | Alicia Cozine <879121+acozine@users.noreply.github.com> | 2019-10-30 12:42:24 -0500 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2019-10-30 12:42:24 -0500 |
| commit | b80ca85a694a714c93e241f281d0871be91fedd6 (patch) | |
| tree | 93f6ca869d20981f9248c0d4e1e56ba9dfcd07d6 | |
| parent | 12820ba64ff5a70eec8ce274cbea576267cffb64 (diff) | |
| download | ansible-b80ca85a694a714c93e241f281d0871be91fedd6.tar.gz | |
Backport/2.9/docs (#64073)
* clarify no subfolders and md only for collections /docs folder (#63808)
(cherry picked from commit 6a2902c8d55f366bd577436effa2426b04ce65ee)
* Fixed example error in windows_winrm user guide (#63922)
The example code to configure TLS 1.2 Support using Ansible had an indention error. The register variable 'enable_tls12' was not indented. This caused the subsequent task to fail since the variable was not registered.
(cherry picked from commit c562e17659abefce44a5e64fd798e6000b84a6f7)
* Fix doc errors in AWS modules (#63851)
* Fix register/debug in aws_batch_compute_environment
* Fix aws_batch_job_queue doc errors
* Fix module naming: `batch_job_queue` > `aws_batch_job_queue`
* Fix missing register
* Update debug task to use modern YAML format
* Fix missing register + debug for lambda_policy
* Fix YAML syntax for elb_application_lb_info module
(cherry picked from commit e4f16368ed8060dd7a15a0078b4a21fb86d85baf)
* Update documentation for package module (#63909)
It is not clear from the documentation that list can be used
(cherry picked from commit 7f2c367d78c1773e5e908e31196fd07a698db9ee)
* [ec2_launch_template] Update description of state param (#63147)
Currently, it is not possible to delete specific versions of an ec2 launch template. The module docs incorrectly suggest that there is a `version` param to the module that can be used to do that. This patch aims to correct that error.
(cherry picked from commit 7ea72607534ce996c311c17ee4c6aaf83989ae9e)
* template: Add a space in example block (#63930)
(cherry picked from commit f279715c29530c9148616a5c3fa5af846586cb18)
* revisions to docsite README (#63957)
(cherry picked from commit 5c962ef859b37ac3a9707a3e1ac88f4b34b78038)
* combine galaxy.com install roles details (#63486)
(cherry picked from commit ee8a0882054b7f633cd8bc075ffc61b8eb136d4b)
* Correct a typo (#64020)
(cherry picked from commit 18f4f0549faabefbd0457cde0dd86b0d0fed406b)
* Update password.py (#63965)
Update the examples of the password lookup plugin to show how multiple options are joined together.
(cherry picked from commit 92daec5d0bce5dfbb73fda52910de2a74d59fa7e)
* Fix indentation of example (#63789)
Remove no_log since module_defaults aren't displayed like set_fact was
(cherry picked from commit 1e52782d6ba6e3e2c9d140ec47558c034f0d394f)
* add newline to render table correctly (#63769)
(cherry picked from commit 1aee11c86026e8493ce9acba30175fadcd6dc70f)
* clarified some points on environment keyword usage (#64065)
(cherry picked from commit 885ee62b53247bc0985bfb12a39149d7ab9d3f2d)
25 files changed, 645 insertions, 461 deletions
diff --git a/docs/docsite/README.md b/docs/docsite/README.md index ec2f5a2ebf..84516f0931 100644 --- a/docs/docsite/README.md +++ b/docs/docsite/README.md @@ -1,51 +1,176 @@ -Homepage and Documentation Source for Ansible -============================================= +Ansible documentation +===================== -This project hosts the source behind [docs.ansible.com](https://docs.ansible.com/) +This project hosts the source behind [docs.ansible.com](https://docs.ansible.com/). -Contributions to the documentation are welcome. To make changes, submit a pull request that changes the reStructuredText files in the `rst/` directory only, and the core team can do a docs build and push the static files. +To create clear, concise, consistent, useful materials on docs.ansible.com, please refer to the following information. -If you wish to verify output from the markup such as link references, you may install sphinx and build the documentation by running `make webdocs` from the `ansible/docs/docsite` directory. -To include module documentation you'll need to run `make webdocs` at the top level of the repository. The generated html files are in `docsite/htmlout/`. +About Ansible +------------- +Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks such as continuous deployments or zero downtime rolling updates. Learn more about Ansible [here](https://docs.ansible.com/ansible/latest/index.html). -To limit module documentation building to a specific module, run `MODULES=NAME make webdocs` instead. This should make testing module documentation syntax much faster. Instead of a single module, you can also specify a comma-separated list of modules. In order to skip building documentation for all modules, specify non-existing module name, for example `MODULES=none make webdocs`. +To install Ansible, see the [Installation Guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html). +The following sections provide information and resources on contributing to Ansible documentation. + +Contributions +============= +Ansible documentation is written in ReStructuredText(RST). Contributions to the documentation are welcome. + +The Ansible community produces guidance on contributions, building documentation, and submitting pull requests, which you can find in [Contributing to the Ansible Documentation](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html). + +Filing issues +------------- If you do not want to learn the reStructuredText format, you can also [file issues] about documentation problems on the Ansible GitHub project. -Note that module documentation can actually be [generated from a DOCUMENTATION docstring][module-docs] in the modules directory, so corrections to modules written as such need to be made in the module source, rather than in docsite source. +Editing docs directly on GitHub +------------------------------- +For typos and other quick fixes, you can edit the documentation right from the site. See [Editing docs directly on GitHub](https://docs.ansible.com/ansible/devel/community/documentation_contributions.html#editing-docs-directly-on-github) for more information. + +Ansible style guide +=================== + +To create clear, concise, consistent, useful materials on docs.ansible.com, follow the guidelines found in the [Ansible Style Guide](https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html#linguistic-guidelines). + +reStructuredText +---------------- +The Ansible style guide also includes useful guidelines on writing in reStructuredText. Please see the style guide for reStructuredText formatting guidelines for: +* header notation +* internal navigation +* linking +* local table of contents + + +Tools +===== + +The Ansible community provides resources on tools used to write, test, and build documentation. In this section you will find some helpful links and workflow recommendations to get started writing or editing documentation. + +Popular editors +--------------- +The Ansible community uses a range of tools for working with the Ansible project. Find a list of some of the most popular of these tools [here](https://docs.ansible.com/ansible/latest/community/other_tools_and_programs.html#popular-editors). + +Building documentation +---------------------- +Building the documentation is the best way to check for errors and review your changes. Ansible documentation is built using Sphinx. For resources on Sphinx and building documentation, see [building the documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally) in the Ansible Community Guide. + +Github +------ +[Ansible documentation](https://github.com/ansible/ansible/tree/devel/docs/docsite) is hosted on the Ansible Github project. + +The following sections describe the workflows required to start developing or submit changes to Ansible documentation. + -To install sphinx and the required theme, install ``pip`` and then ``pip install sphinx sphinx_rtd_theme`` +## Setting up Git -[file issues]: https://github.com/ansible/ansible/issues -[module-docs]: https://docs.ansible.com/developing_modules.html#documenting-your-module -HEADERS -======= +GitHub provides a set of [Git cheatsheets](https://github.github.com/training-kit/) in multiple languages. -RST allows for arbitrary hierarchy for the headers, it will 'learn on the fly'. We also want a standard that all our documents can follow: +1. First [Install Git](https://help.github.com/en/articles/set-up-git) +2. Perform the initial Git setup tasks, as described in [First Time Git Setup](link:https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup). + +3. Navigate to https://github.com/ansible/ansible and [create a fork](https://help.github.com/en/articles/fork-a-repo). This will create your own version of the repository which you can find at https://github.com/{yourusername}/ansible where {yourusername} is the username you created in GitHub. + +4. [Clone](https://help.github.com/en/articles/cloning-a-repository) from your fork to create a copy on your local machine. + + NOTE: It is possible to clone using SSH so you don't have to enter a username/password every time you push. Find instructions at [Connecting to GitHub with SSH](https://help.github.com/articles/connecting-to-github-with-ssh/) and [Which Remote URL Should I Use](https://help.github.com/articles/which-remote-url-should-i-use/). When using SSH, the origin lines will appear like this: +`git@github.com:{yourusername}/ansible.git` + + +``` +$ git clone git@github.com:{yourusername}/ansible.git ``` -########################## -# with overline, for parts -########################## -***************************** -* with overline, for chapters -***************************** +5. Navigate to the new directory by entering the following from the command line on your local machine: +``` +$ cd {repository-name} +``` -=, for sections -=============== +6. Add a git remote to your local repository to link to the upstream version of the documentation. This makes it easier to update your fork and local version of the documentation. +``` +$ git remote add upstream git://github.com/ansible/ansible.git +``` --, for subsections ------------------- +7. Check your settings. +``` +$ git remote -v +origin https://github.com/{YOUR_USERNAME}/{YOUR_FORK}.git (fetch) +origin https://github.com/{YOUR_USERNAME}/{YOUR_FORK}.git (push) +upstream https://github.com/{ORIGINAL_OWNER}/{ORIGINAL_REPOSITORY}.git (fetch) +upstream https://github.com/{ORIGINAL_OWNER}/{ORIGINAL_REPOSITORY}.git (push) +``` -^, for sub-subsections -^^^^^^^^^^^^^^^^^^^^^ +## Creating a topic branch -", for paragraphs -""""""""""""""""" +Create a topic branch for new documentation submissions or larger changes. +1. Fetch updates from ``origin``: +``` +$ git fetch origin +``` +2. Checkout a new branch based on ``devel``: ``` +$ git checkout -b {branch name} +``` +3. Create new documents or make changes to existing files. +4. Add new or changed files: +``` +$ git add {file name} +``` +5. Commit your changes or additions. Be sure to include a commit message: +``` +$ git commit -m "new message" +``` +6. Push your updates back to `origin`: +``` +$ git push -u origin {branch name} +``` + +Once you have completed this workflow, it is a good idea to build the documentation and ensure everything is correct and that it works. As a contributor, you are required to prove that See [building the documentation locally](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#building-the-documentation-locally) in the Ansible Community Guide for more on building documentation. + + +When final additions or changes are pushed back to your fork you can open a pull request (PR). + + +Working with pull requests (PRs) +-------------------------------- +Pull requests represent the stage in a contribution where you are ready to submit your work for review and inclusion in the documentation. When a PR is opened, a reviewer will check the work and potentially open a dialog around your proposed changes. PRs should include specific information, which you can find in [Opening a new issue and/or PR](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#opening-a-new-issue-and-or-pr) in the Ansible Community Guide. + +## Creating a pull request +1. Navigate to your personal fork: https://github.com/{yourusername}/ansible +2. Click **Pull requests** and then click **New pull requests**. +3. Use the drop-down menus, set the **base repository** to the stable branch and set the **head repository** to your topic branch. +4. Apply appropriate labels. Include **backport** and **documentation**. +6. Fill in the PR summary using the following template: + +``` +##### SUMMARY + +##### ISSUE TYPE + +##### COMPONENT NAME +docs.ansible.com +##### ANSIBLE VERSION + +##### ADDITIONAL INFORMATION + +``` +NOTE: +If you put 'closes <issuenumber> ' in the summary, ansible will automatically close the issue on merge. + +7. Click **Create pull request**. + + +A reviewer will evaluate your contribution. They may open a dialog around the PR and suggest revisions or, if the PR meets acceptance criteria, will merge it to the base branch. + +## Backporting a pull request + +All Ansible PRs must be merged to the `devel` branch first. Most users may, however, use a prior stable branch. Evaluate your pull request to determine if it applies to a prior branch. + +See [Backporting merged PRs](https://docs.ansible.com/ansible/devel/community/development_process.html?highlight=backport#backporting-merged-prs) for a complete worklfow. + +## Other Git workflows -We do have pages littered with ```````` headers, but those should be removed for one of the above. +In addition to creating a pull request and backporting, other workflows exist to help keep your topic branches and pull requests up-to-date. See the [Developer Guide](https://docs.ansible.com/ansible/devel/dev_guide/developing_rebasing.html) on `git rebase` to learn more about rebasing a pull request. diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index 70e8091d59..fc363b0d94 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -60,7 +60,7 @@ See :ref:`collections_galaxy_meta` for details. docs directory --------------- -Keep general documentation for the collection here. Plugins and modules still keep their specific documentation embedded as Python docstrings. Use the ``docs`` folder to describe how to use the roles and plugins the collection provides, role requirements, and so on. Currently we are looking at Markdown as the standard format for documentation files, but this is subject to change. +Put general documentation for the collection here. Keep the specific documentation for plugins and modules embedded as Python docstrings. Use the ``docs`` folder to describe how to use the roles and plugins the collection provides, role requirements, and so on. Use markdown and do not add subfolders. Use ``ansible-doc`` to view documentation for plugins inside a collection: diff --git a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst index 43e46dd1dd..0bbb942cc0 100644 --- a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst +++ b/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst @@ -644,22 +644,23 @@ for every call, it's preferable to use :ref:`module_defaults <module_defaults>`. .. code-block:: yaml - - name: set connection information for all tasks + - name: set connection information for aws modules and run tasks module_defaults: group/aws: aws_access_key: "{{ aws_access_key }}" aws_secret_key: "{{ aws_secret_key }}" security_token: "{{ security_token }}" region: "{{ aws_region }}" - no_log: yes - - name: Do Something - ec2_instance: - ... params ... + block: - - name: Do Something Else - ec2_instance: - ... params ... + - name: Do Something + ec2_instance: + ... params ... + + - name: Do Something Else + ec2_instance: + ... params ... AWS Permissions for Integration Tests ------------------------------------- diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst index 5a6a353291..ea6fdb5e7a 100644 --- a/docs/docsite/rst/dev_guide/style_guide/index.rst +++ b/docs/docsite/rst/dev_guide/style_guide/index.rst @@ -57,6 +57,7 @@ are easily understood by English speakers. They may be harder to understand for others and are also tricky for automated translation. Use the following English terms in place of Latin terms or abbreviations: + +-------------------------------+------------------------------+ | Latin | English | +===============================+==============================+ diff --git a/docs/docsite/rst/galaxy/dev_guide/creating_roles.rst b/docs/docsite/rst/galaxy/dev_guide.rst index bca976287c..4ee2467da2 100644 --- a/docs/docsite/rst/galaxy/dev_guide/creating_roles.rst +++ b/docs/docsite/rst/galaxy/dev_guide.rst @@ -1,8 +1,31 @@ +.. _developing_galaxy: + +********************** +Galaxy Developer Guide +********************** + +You can host collections and roles on Galaxy to share with the Ansible community. Galaxy content is formated in pre-packaged units of work such as `roles <playbooks_reuse_roles>`_, and new in Galaxy 3.2, `collections <collections>`_. +You can create roles for provisioning infrastructure, deploying applications, and all of the tasks you do everyday. Taking this a step further, you can create collections which provide a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins. + +.. contents:: + :local: + :depth: 2 + +.. _creating_collections_galaxy: + +Creating collections for Galaxy +=============================== + +Collections are a distribution format for Ansible content. You can use collections to package and distribute playbooks, roles, modules, and plugins. +You can publish and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_. + +See :ref:`developing_collections` for details on how to create collections. + .. _creating_roles_galaxy: -************************* + Creating roles for Galaxy -************************* +========================= Use the ``init`` command to initialize the base structure of a new role, saving time on creating the various directories and main.yml files a role requires @@ -34,20 +57,20 @@ The above will create the following directory structure in the current working d If you want to create a repository for the role the repository root should be `role_name`. Force -===== +----- If a directory matching the name of the role already exists in the current working directory, the init command will result in an error. To ignore the error use the *--force* option. Force will create the above subdirectories and files, replacing anything that matches. -Container Enabled -================= +Container enabled +----------------- If you are creating a Container Enabled role, pass ``--type container`` to ``ansible-galaxy init``. This will create the same directory structure as above, but populate it with default files appropriate for a Container Enabled role. For instance, the README.md has a slightly different structure, the *.travis.yml* file tests the role using `Ansible Container <https://github.com/ansible/ansible-container>`_, and the meta directory includes a *container.yml* file. -Using a Custom Role Skeleton -============================ +Using a custom role skeleton +---------------------------- A custom role skeleton directory can be supplied as follows: @@ -70,7 +93,7 @@ Alternatively, the role_skeleton and ignoring of files can be configured via ans role_skeleton_ignore = ^.git$,^.*/.git_keep$ Authenticate with Galaxy -======================== +------------------------ Using the ``import``, ``delete`` and ``setup`` commands to manage your roles on the Galaxy website requires authentication, and the ``login`` command can be used to do just that. Before you can use the ``login`` command, you must create an account on the Galaxy website. @@ -101,7 +124,7 @@ If you do not wish to use your GitHub password, or if you have two-factor authen Import a role -============= +------------- The ``import`` command requires that you first authenticate using the ``login`` command. Once authenticated you can import any GitHub repository that you own or have been granted access. @@ -129,22 +152,22 @@ By default the command will wait for Galaxy to complete the import process, disp Status SUCCESS : warnings=0 errors=0 Branch ------- +^^^^^^ Use the *--branch* option to import a specific branch. If not specified, the default branch for the repo will be used. Role name ---------- +^^^^^^^^^ By default the name given to the role will be derived from the GitHub repository name. However, you can use the *--role-name* option to override this and set the name. No wait -------- +^^^^^^^ If the *--no-wait* option is present, the command will not wait for results. Results of the most recent import for any of your roles is available on the Galaxy web site by visiting *My Imports*. Delete a role -============= +------------- The ``delete`` command requires that you first authenticate using the ``login`` command. Once authenticated you can remove a role from the Galaxy web site. You are only allowed to remove roles where you have access to the repository in GitHub. @@ -158,7 +181,7 @@ This only removes the role from Galaxy. It does not remove or alter the actual G Travis integrations -=================== +------------------- You can create an integration or connection between a role in Galaxy and `Travis <https://travis-ci.org>`_. Once the connection is established, a build in Travis will automatically trigger an import in Galaxy, updating the search index with the latest information about the role. @@ -185,7 +208,7 @@ To instruct Travis to notify Galaxy when a build completes, add the following to List Travis integrations ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ Use the *--list* option to display your Travis integrations: @@ -201,7 +224,7 @@ Use the *--list* option to display your Travis integrations: Remove Travis integrations ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ Use the *--remove* option to disable and remove a Travis integration: @@ -213,10 +236,13 @@ Provide the ID of the integration to be disabled. You can find the ID by using t .. seealso:: - - :ref:`playbooks_reuse_roles` - All about ansible roles - `Mailing List <https://groups.google.com/group/ansible-project>`_ - Questions? Help? Ideas? Stop by the list on Google Groups - `irc.freenode.net <http://irc.freenode.net>`_ - #ansible IRC chat channel + `collections <collections>`_ + Sharable collections of modules, playbooks and roles + `roles <playbooks_reuse_roles>`_ + Reusable tasks, handlers, and other files in a known directory structure + :ref:`playbooks_reuse_roles` + All about ansible roles + `Mailing List <https://groups.google.com/group/ansible-project>`_ + Questions? Help? Ideas? Stop by the list on Google Groups + `irc.freenode.net <http://irc.freenode.net>`_ + #ansible IRC chat channel diff --git a/docs/docsite/rst/galaxy/dev_guide/creating_collections.rst b/docs/docsite/rst/galaxy/dev_guide/creating_collections.rst deleted file mode 100644 index db135374ac..0000000000 --- a/docs/docsite/rst/galaxy/dev_guide/creating_collections.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _creating_collections_galaxy: - -******************************* -Creating collections for Galaxy -******************************* - - -Collections are a distribution format for Ansible content. You can use collections to package and distribute playbooks, roles, modules, and plugins. -You can publish and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_. - -See :ref:`developing_collections` for details on how to create collections. diff --git a/docs/docsite/rst/galaxy/dev_guide/index.rst b/docs/docsite/rst/galaxy/dev_guide/index.rst deleted file mode 100644 index 468b530fb1..0000000000 --- a/docs/docsite/rst/galaxy/dev_guide/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _developing_galaxy: - -*************** -Developer Guide -*************** - -You can host collections and roles on Galaxy to share with the Ansible community. Galaxy content is formated in pre-packaged units of work such as `roles <playbooks_reuse_roles>`_, and new in Galaxy 3.2, `collections <collections>`_. -You can create roles for provisioning infrastructure, deploying applications, and all of the tasks you do everyday. Taking this a step further, you can create collections which provide a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins. - -.. toctree:: - :maxdepth: 2 - - creating_collections - creating_roles - -.. seealso:: - `collections <collections>`_ - Sharable collections of modules, playbooks and roles - `roles <playbooks_reuse_roles>`_ - Reusable tasks, handlers, and other files in a known directory structure diff --git a/docs/docsite/rst/galaxy/user_guide.rst b/docs/docsite/rst/galaxy/user_guide.rst new file mode 100644 index 0000000000..a80141e07f --- /dev/null +++ b/docs/docsite/rst/galaxy/user_guide.rst @@ -0,0 +1,391 @@ +.. _using_galaxy: +.. _ansible_galaxy: + +***************** +Galaxy User Guide +***************** + +:dfn:`Ansible Galaxy` refers to the `Galaxy <https://galaxy.ansible.com>`_ website, a free site for finding, downloading, and sharing community developed roles. + +Use Galaxy to jump-start your automation project with great content from the Ansible community. Galaxy provides pre-packaged units of work such as `roles <playbooks_reuse_roles>`_, and new in Galaxy 3.2, `collections <collections>`_. +You can find roles for provisioning infrastructure, deploying applications, and all of the tasks you do everyday. The collection format provides a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins. + +.. contents:: + :local: + :depth: 2 +.. _finding_galaxy_collections: + +Finding collections on Galaxy +============================= + +To find collections on Galaxy: + +#. Click the :guilabel:`Search` icon in the left-hand navigation. +#. Set the filter to *collection*. +#. Set other filters and press :guilabel:`enter`. + +Galaxy presents a list of collections that match your search criteria. + +.. _installing_galaxy_collections: + +Installing collections from Galaxy +================================== + +.. include:: ../shared_snippets/installing_collections.txt + + +Installing an older version of a collection +------------------------------------------- + +.. include:: ../shared_snippets/installing_older_collection.txt + +Install multiple collections with a requirements file +----------------------------------------------------- + +.. include:: ../shared_snippets/installing_multiple_collections.txt + +Galaxy server configuration list +-------------------------------- + +.. include:: ../shared_snippets/galaxy_server_list.txt + + +.. _finding_galaxy_roles: + +Finding roles on Galaxy +======================= + +Search the Galaxy database by tags, platforms, author and multiple keywords. For example: + +.. code-block:: bash + + $ ansible-galaxy search elasticsearch --author geerlingguy + +The search command will return a list of the first 1000 results matching your search: + +.. code-block:: text + + Found 2 roles matching your search: + + Name Description + ---- ----------- + geerlingguy.elasticsearch Elasticsearch for Linux. + geerlingguy.elasticsearch-curator Elasticsearch curator for Linux. + + +Get more information about a role +--------------------------------- + +Use the ``info`` command to view more detail about a specific role: + +.. code-block:: bash + + $ ansible-galaxy info username.role_name + +This returns everything found in Galaxy for the role: + +.. code-block:: text + + Role: username.role_name + description: Installs and configures a thing, a distributed, highly available NoSQL thing. + active: True + commit: c01947b7bc89ebc0b8a2e298b87ab416aed9dd57 + commit_message: Adding travis + commit_url: https://github.com/username/repo_name/commit/c01947b7bc89ebc0b8a2e298b87ab + company: My Company, Inc. + created: 2015-12-08T14:17:52.773Z + download_count: 1 + forks_count: 0 + github_branch: + github_repo: repo_name + github_user: username + id: 6381 + is_valid: True + issue_tracker_url: + license: Apache + min_ansible_version: 1.4 + modified: 2015-12-08T18:43:49.085Z + namespace: username + open_issues_count: 0 + path: /Users/username/projects/roles + scm: None + src: username.repo_name + stargazers_count: 0 + travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=master + version: + watchers_count: 1 + + +.. _installing_galaxy_roles: + +Installing roles from Galaxy +============================ + +The ``ansible-galaxy`` command comes bundled with Ansible, and you can use it to install roles from Galaxy or directly from a git based SCM. You can +also use it to create a new role, remove roles, or perform tasks on the Galaxy website. + +The command line tool by default communicates with the Galaxy website API using the server address *https://galaxy.ansible.com*. Since the `Galaxy project <https://github.com/ansible/galaxy>`_ +is an open source project, you may be running your own internal Galaxy server and wish to override the default server address. You can do this using the *--server* option +or by setting the Galaxy server value in your *ansible.cfg* file. For information on setting the value in *ansible.cfg* see :ref:`galaxy_server`. + + +Installing roles +---------------- + +Use the ``ansible-galaxy`` command to download roles from the `Galaxy website <https://galaxy.ansible.com>`_ + +.. code-block:: bash + + $ ansible-galaxy install namespace.role_name + +Setting where to install roles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, Ansible downloads roles to the first writable directory in the default list of paths ``~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles``. This installs roles in the home directory of the user running ``ansible-galaxy``. + +You can override this with one of the following options: + +* Set the environment variable :envvar:`ANSIBLE_ROLES_PATH` in your session. +* Define ``roles_path`` in an ``ansible.cfg`` file. +* Use the ``--roles-path`` option for the ``ansible-galaxy`` command. + +The following provides an example of using ``--roles-path`` to install the role into the current working directory: + +.. code-block:: bash + + $ ansible-galaxy install --roles-path . geerlingguy.apache + +.. seealso:: + + :ref:`intro_configuration` + All about configuration files + +Installing a specific version of a role +--------------------------------------- + +When the Galaxy server imports a role, it imports any git tags matching the Semantic Version format as versions. In turn, you can download a specific version of a role by specifying one of the imported tags. + +To see the available versions for a role: + +#. Locate the role on the Galaxy search page. +#. Click on the name to view more details, including the available versions. + +You can also navigate directly to the role using the /<namespace>/<role name>. For example, to view the role geerlingguy.apache, go to `<https://galaxy.ansible.com/geerlingguy/apache>`_. + +To install a specific version of a role from Galaxy, append a comma and the value of a GitHub release tag. For example: + +.. code-block:: bash + + $ ansible-galaxy install geerlingguy.apache,v1.0.0 + +It is also possible to point directly to the git repository and specify a branch name or commit hash as the version. For example, the following will +install a specific commit: + +.. code-block:: bash + + $ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25 + +Installing multiple roles from a file +------------------------------------- + +You can install multiple roles by including the roles in a :file:`requirements.yml` file. The format of the file is YAML, and the +file extension must be either *.yml* or *.yaml*. + +Use the following command to install roles included in :file:`requirements.yml:` + +.. code-block:: bash + + $ ansible-galaxy install -r requirements.yml + +Again, the extension is important. If the *.yml* extension is left off, the ``ansible-galaxy`` CLI assumes the file is in an older, now deprecated, +"basic" format. + +Each role in the file will have one or more of the following attributes: + + src + The source of the role. Use the format *namespace.role_name*, if downloading from Galaxy; otherwise, provide a URL pointing + to a repository within a git based SCM. See the examples below. This is a required attribute. + scm + Specify the SCM. As of this writing only *git* or *hg* are allowed. See the examples below. Defaults to *git*. + version: + The version of the role to download. Provide a release tag value, commit hash, or branch name. Defaults to the branch set as a default in the repository, otherwise defaults to the *master*. + name: + Download the role to a specific name. Defaults to the Galaxy name when downloading from Galaxy, otherwise it defaults + to the name of the repository. + +Use the following example as a guide for specifying roles in *requirements.yml*: + +.. code-block:: yaml + + # from galaxy + - src: yatesr.timezone + + # from GitHub + - src: https://github.com/bennojoy/nginx + + # from GitHub, overriding the name and specifying a specific tag + - src: https://github.com/bennojoy/nginx + version: master + name: nginx_role + + # from a webserver, where the role is packaged in a tar.gz + - src: https://some.webserver.example.com/files/master.tar.gz + name: http-role-gz + + # from a webserver, where the role is packaged in a tar.bz2 + - src: https://some.webserver.example.com/files/master.tar.bz2 + name: http-role-bz2 + + # from a webserver, where the role is packaged in a tar.xz (Python 3.x only) + - src: https://some.webserver.example.com/files/master.tar.xz + name: http-role-xz + + # from Bitbucket + - src: git+https://bitbucket.org/willthames/git-ansible-galaxy + version: v1.4 + + # from Bitbucket, alternative syntax and caveats + - src: https://bitbucket.org/willthames/hg-ansible-galaxy + scm: hg + + # from GitLab or other git-based scm, using git+ssh + - src: git@gitlab.company.com:mygroup/ansible-base.git + scm: git + version: "0.1" # quoted, so YAML doesn't parse this as a floating-point value + +Installing multiple roles from multiple files +--------------------------------------------- + +For large projects, the ``include`` directive in a :file:`requirements.yml` file provides the ability to split a large file into multiple smaller files. + +For example, a project may have a :file:`requirements.yml` file, and a :file:`webserver.yml` file. + +Below are the contents of the :file:`webserver.yml` file: + +.. code-block:: bash + + # from github + - src: https://github.com/bennojoy/nginx + + # from Bitbucket + - src: git+http://bitbucket.org/willthames/git-ansible-galaxy + version: v1.4 + +The following shows the contents of the :file:`requirements.yml` file that now includes the :file:`webserver.yml` file: + +.. code-block:: bash + + # from galaxy + - src: yatesr.timezone + - include: <path_to_requirements>/webserver.yml + +To install all the roles from both files, pass the root file, in this case :file:`requirements.yml` on the +command line, as follows: + +.. code-block:: bash + + $ ansible-galaxy install -r requirements.yml + +.. _galaxy_dependencies: + +Dependencies +------------ + +Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependencies will automatically be installed. + +You specify role dependencies in the ``meta/main.yml`` file by providing a list of roles. If the source of a role is Galaxy, you can simply specify the role in +the format ``namespace.role_name``. You can also use the more complex format in ``requirements.yml``, allowing you to provide ``src``, ``scm``, ``version``, and ``name``. + +The following shows an example ``meta/main.yml`` file with dependent roles: + +.. code-block:: yaml + + --- + dependencies: + - geerlingguy.java + + galaxy_info: + author: geerlingguy + description: Elasticsearch for Linux. + company: "Midwestern Mac, LLC" + license: "license (BSD, MIT)" + min_ansible_version: 2.4 + platforms: + - name: EL + versions: + - all + - name: Debian + versions: + - all + - name: Ubuntu + versions: + - all + galaxy_tags: + - web + - system + - monitoring + - logging + - lucene + - elk + - elasticsearch + +Tags are inherited *down* the dependency chain. In order for tags to be applied to a role and all its dependencies, the tag should be applied to the role, not to all the tasks within a role. + +Roles listed as dependencies are subject to conditionals and tag filtering, and may not execute fully depending on +what tags and conditionals are applied. + +If the source of a role is Galaxy, specify the role in the format *namespace.role_name*: + +.. code-block:: yaml + + dependencies: + - geerlingguy.apache + - geerlingguy.ansible + + +Alternately, you can specify the role dependencies in the complex form used in :file:`requirements.yml` as follows: + +.. code-block:: yaml + + dependencies: + - src: geerlingguy.ansible + - src: git+https://github.com/geerlingguy/ansible-role-composer.git + version: 775396299f2da1f519f0d8885022ca2d6ee80ee8 + name: composer + +When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :ref:`playbooks_reuse_roles`. + +.. note:: + + Galaxy expects all role dependencies to exist in Galaxy, and therefore dependencies to be specified in the + ``namespace.role_name`` format. If you import a role with a dependency where the ``src`` value is a URL, the import process will fail. + +List installed roles +-------------------- + +Use ``list`` to show the name and version of each role installed in the *roles_path*. + +.. code-block:: bash + + $ ansible-galaxy list + - ansible-network.network-engine, v2.7.2 + - ansible-network.config_manager, v2.6.2 + - ansible-network.cisco_nxos, v2.7.1 + - ansible-network.vyos, v2.7.3 + - ansible-network.cisco_ios, v2.7.0 + +Remove an installed role +------------------------ + +Use ``remove`` to delete a role from *roles_path*: + +.. code-block:: bash + + $ ansible-galaxy remove namespace.role_name + + +.. seealso:: + `collections <collections>`_ + Sharable collections of modules, playbooks and roles + `roles <playbooks_reuse_roles>`_ + Reusable tasks, handlers, and other files in a known directory structure diff --git a/docs/docsite/rst/galaxy/user_guide/finding_collections.rst b/docs/docsite/rst/galaxy/user_guide/finding_collections.rst deleted file mode 100644 index 356e8e0146..0000000000 --- a/docs/docsite/rst/galaxy/user_guide/finding_collections.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. _finding_galaxy_collections: - -***************************** -Finding collections on Galaxy -***************************** - -To find collections on Galaxy: - -#. Click the :guilabel:`Search` icon in the left-hand navigation. -#. Set the filter to *collection*. -#. Set other filters and press *enter*. - -Galaxy presents a list of collections that match your search criteria. diff --git a/docs/docsite/rst/galaxy/user_guide/finding_roles.rst b/docs/docsite/rst/galaxy/user_guide/finding_roles.rst deleted file mode 100644 index 4d52fb74db..0000000000 --- a/docs/docsite/rst/galaxy/user_guide/finding_roles.rst +++ /dev/null @@ -1,66 +0,0 @@ - -.. _finding_galaxy_roles: - -************************* -Finding roles on Galaxy -************************* - -Search the Galaxy database by tags, platforms, author and multiple keywords. For example: - -.. code-block:: bash - - $ ansible-galaxy search elasticsearch --author geerlingguy - -The search command will return a list of the first 1000 results matching your search: - -.. code-block:: text - - Found 2 roles matching your search: - - Name Description - ---- ----------- - geerlingguy.elasticsearch Elasticsearch for Linux. - geerlingguy.elasticsearch-curator Elasticsearch curator for Linux. - - -Get more information about a role -================================= - -Use the ``info`` command to view more detail about a specific role: - -.. code-block:: bash - - $ ansible-galaxy info username.role_name - -This returns everything found in Galaxy for the role: - -.. code-block:: text - - Role: username.role_name - description: Installs and configures a thing, a distributed, highly available NoSQL thing. - active: True - commit: c01947b7bc89ebc0b8a2e298b87ab416aed9dd57 - commit_message: Adding travis - commit_url: https://github.com/username/repo_name/commit/c01947b7bc89ebc0b8a2e298b87ab - company: My Company, Inc. - created: 2015-12-08T14:17:52.773Z - download_count: 1 - forks_count: 0 - github_branch: - github_repo: repo_name - github_user: username - id: 6381 - is_valid: True - issue_tracker_url: - license: Apache - min_ansible_version: 1.4 - modified: 2015-12-08T18:43:49.085Z - namespace: username - open_issues_count: 0 - path: /Users/username/projects/roles - scm: None - src: username.repo_name - stargazers_count: 0 - travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=master - version: - watchers_count: 1 diff --git a/docs/docsite/rst/galaxy/user_guide/index.rst b/docs/docsite/rst/galaxy/user_guide/index.rst deleted file mode 100644 index 0aa0a371be..0000000000 --- a/docs/docsite/rst/galaxy/user_guide/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _using_galaxy: -.. _ansible_galaxy: - -********** -User Guide -********** - -:dfn:`Ansible Galaxy` refers to the `Galaxy <https://galaxy.ansible.com>`_ website, a free site for finding, downloading, and sharing community developed roles. - -Use Galaxy to jump-start your automation project with great content from the Ansible community. Galaxy provides pre-packaged units of work such as `roles <playbooks_reuse_roles>`_, and new in Galaxy 3.2, `collections <collections>`_. -You can find roles for provisioning infrastructure, deploying applications, and all of the tasks you do everyday. The collection format provides a comprehensive package of automation that may include multiple playbooks, roles, modules, and plugins. - -.. toctree:: - :maxdepth: 2 - - finding_collections - finding_roles - installing_collections - installing_roles - - -.. seealso:: - `collections <collections>`_ - Sharable collections of modules, playbooks and roles - `roles <playbooks_reuse_roles>`_ - Reusable tasks, handlers, and other files in a known directory structure diff --git a/docs/docsite/rst/galaxy/user_guide/installing_collections.rst b/docs/docsite/rst/galaxy/user_guide/installing_collections.rst deleted file mode 100644 index 4d1e4e5c21..0000000000 --- a/docs/docsite/rst/galaxy/user_guide/installing_collections.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _installing_galaxy_collections: - -Installing collections from Galaxy -================================== - -.. include:: ../../shared_snippets/installing_collections.txt - - -Installing an older version of a collection -------------------------------------------- - -.. include:: ../../shared_snippets/installing_older_collection.txt - -Install multiple collections with a requirements file ------------------------------------------------------ - -.. include:: ../../shared_snippets/installing_multiple_collections.txt - -Galaxy server configuration list --------------------------------- - -.. include:: ../../shared_snippets/galaxy_server_list.txt diff --git a/docs/docsite/rst/galaxy/user_guide/installing_roles.rst b/docs/docsite/rst/galaxy/user_guide/installing_roles.rst deleted file mode 100644 index 172df19d80..0000000000 --- a/docs/docsite/rst/galaxy/user_guide/installing_roles.rst +++ /dev/null @@ -1,218 +0,0 @@ -Installing roles from Galaxy -============================ - -The ``ansible-galaxy`` command comes bundled with Ansible, and you can use it to install roles from Galaxy or directly from a git based SCM. You can -also use it to create a new role, remove roles, or perform tasks on the Galaxy website. - -The command line tool by default communicates with the Galaxy website API using the server address *https://galaxy.ansible.com*. Since the `Galaxy project <https://github.com/ansible/galaxy>`_ -is an open source project, you may be running your own internal Galaxy server and wish to override the default server address. You can do this using the *--server* option -or by setting the Galaxy server value in your *ansible.cfg* file. For information on setting the value in *ansible.cfg* see :ref:`galaxy_server`. - - -Installing Roles ----------------- - -Use the ``ansible-galaxy`` command to download roles from the `Galaxy website <https://galaxy.ansible.com>`_ - -.. code-block:: bash - - $ ansible-galaxy install username.role_name - -roles_path -^^^^^^^^^^ - -By default Ansible downloads roles to the first writable directory in the default list of paths ``~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles``. This will install roles in the home directory of the user running ``ansible-galaxy``. - -You can override this by setting the environment variable :envvar:`ANSIBLE_ROLES_PATH` in your session, defining ``roles_path`` in an ``ansible.cfg`` file, or by using the ``--roles-path`` option. - -The following provides an example of using ``--roles-path`` to install the role into the current working directory: - -.. code-block:: bash - - $ ansible-galaxy install --roles-path . geerlingguy.apache - -.. seealso:: - - :ref:`intro_configuration` - All about configuration files - -Installing a specific version of a role ---------------------------------------- - -You can install a specific version of a role from Galaxy by appending a comma and the value of a GitHub release tag. For example: - -.. code-block:: bash - - $ ansible-galaxy install geerlingguy.apache,v1.0.0 - -It's also possible to point directly to the git repository and specify a branch name or commit hash as the version. For example, the following will -install a specific commit: - -.. code-block:: bash - - $ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25 - - -Installing multiple roles from a file -------------------------------------- - -Beginning with Ansible 1.8 it is possible to install multiple roles by including the roles in a *requirements.yml* file. The format of the file is YAML, and the -file extension must be either *.yml* or *.yaml*. - -Use the following command to install roles included in *requirements.yml*: - -.. code-block:: bash - - $ ansible-galaxy install -r requirements.yml - -Again, the extension is important. If the *.yml* extension is left off, the ``ansible-galaxy`` CLI assumes the file is in an older, now deprecated, -"basic" format. - -Each role in the file will have one or more of the following attributes: - - src - The source of the role. Use the format *username.role_name*, if downloading from Galaxy; otherwise, provide a URL pointing - to a repository within a git based SCM. See the examples below. This is a required attribute. - scm - Specify the SCM. As of this writing only *git* or *hg* are allowed. See the examples below. Defaults to *git*. - version: - The version of the role to download. Provide a release tag value, commit hash, or branch name. Defaults to the branch set as a default in the repository, otherwise defaults to the *master*. - name: - Download the role to a specific name. Defaults to the Galaxy name when downloading from Galaxy, otherwise it defaults - to the name of the repository. - -Use the following example as a guide for specifying roles in *requirements.yml*: - -.. code-block:: text - - # from galaxy - - src: yatesr.timezone - - # from GitHub - - src: https://github.com/bennojoy/nginx - - # from GitHub, overriding the name and specifying a specific tag - - src: https://github.com/bennojoy/nginx - version: master - name: nginx_role - - # from a webserver, where the role is packaged in a tar.gz - - src: https://some.webserver.example.com/files/master.tar.gz - name: http-role-gz - - # from a webserver, where the role is packaged in a tar.bz2 - - src: https://some.webserver.example.com/files/master.tar.bz2 - name: http-role-bz2 - - # from a webserver, where the role is packaged in a tar.xz (Python 3.x only) - - src: https://some.webserver.example.com/files/master.tar.xz - name: http-role-xz - - # from Bitbucket - - src: git+https://bitbucket.org/willthames/git-ansible-galaxy - version: v1.4 - - # from Bitbucket, alternative syntax and caveats - - src: https://bitbucket.org/willthames/hg-ansible-galaxy - scm: hg - - # from GitLab or other git-based scm, using git+ssh - - src: git@gitlab.company.com:mygroup/ansible-base.git - scm: git - version: "0.1" # quoted, so YAML doesn't parse this as a floating-point value - -Installing multiple roles from multiple files ---------------------------------------------- - -At a basic level, including requirements files allows you to break up bits of roles into smaller files. Role includes pull in roles from other files. - -Use the following command to install roles includes in *requirements.yml* + *webserver.yml* - -.. code-block:: bash - - ansible-galaxy install -r requirements.yml - -Content of the *requirements.yml* file: - -.. code-block:: text - - # from galaxy - - src: yatesr.timezone - - - include: <path_to_requirements>/webserver.yml - - -Content of the *webserver.yml* file: - -.. code-block:: text - - # from github - - src: https://github.com/bennojoy/nginx - - # from Bitbucket - - src: git+https://bitbucket.org/willthames/git-ansible-galaxy - version: v1.4 - -.. _galaxy_dependencies: - -Dependencies ------------- - -Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependencies will automatically be installed. - -You specify role dependencies in the ``meta/main.yml`` file by providing a list of roles. If the source of a role is Galaxy, you can simply specify the role in -the format ``username.role_name``. You can also use the more complex format in ``requirements.yml``, allowing you to provide ``src``, ``scm``, ``version``, and ``name``. - -Tags are inherited *down* the dependency chain. In order for tags to be applied to a role and all its dependencies, the tag should be applied to the role, not to all the tasks within a role. - -Roles listed as dependencies are subject to conditionals and tag filtering, and may not execute fully depending on -what tags and conditionals are applied. - -Dependencies found in Galaxy can be specified as follows: - -.. code-block:: text - - dependencies: - - geerlingguy.apache - - geerlingguy.ansible - - -The complex form can also be used as follows: - -.. code-block:: text - - dependencies: - - src: geerlingguy.ansible - - src: git+https://github.com/geerlingguy/ansible-role-composer.git - version: 775396299f2da1f519f0d8885022ca2d6ee80ee8 - name: composer - -When dependencies are encountered by ``ansible-galaxy``, it will automatically install each dependency to the ``roles_path``. To understand how dependencies are handled during play execution, see :ref:`playbooks_reuse_roles`. - -.. note:: - - At the time of this writing, the Galaxy website expects all role dependencies to exist in Galaxy, and therefore dependencies to be specified in the - ``username.role_name`` format. If you import a role with a dependency where the ``src`` value is a URL, the import process will fail. - -List installed roles --------------------- - -Use ``list`` to show the name and version of each role installed in the *roles_path*. - -.. code-block:: bash - - $ ansible-galaxy list - - - chouseknecht.role-install_mongod, master - - chouseknecht.test-role-1, v1.0.2 - - chrismeyersfsu.role-iptables, master - - chrismeyersfsu.role-required_vars, master - -Remove an installed role ------------------------- - -Use ``remove`` to delete a role from *roles_path*: - -.. code-block:: bash - - $ ansible-galaxy remove username.role_name diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst index ce4e8cf8b5..53e38ac6e0 100644 --- a/docs/docsite/rst/index.rst +++ b/docs/docsite/rst/index.rst @@ -64,8 +64,8 @@ Ansible releases a new major release of Ansible approximately three to four time :maxdepth: 2 :caption: Ansible Galaxy - galaxy/user_guide/index - galaxy/dev_guide/index + galaxy/user_guide.rst + galaxy/dev_guide.rst .. toctree:: diff --git a/docs/docsite/rst/user_guide/playbooks_environment.rst b/docs/docsite/rst/user_guide/playbooks_environment.rst index a89ade3f8f..d3afa5369a 100644 --- a/docs/docsite/rst/user_guide/playbooks_environment.rst +++ b/docs/docsite/rst/user_guide/playbooks_environment.rst @@ -5,11 +5,11 @@ Setting the Environment (and Working With Proxies) .. versionadded:: 1.1 -It is quite possible that you may need to get package updates through a proxy, or even get some package -updates through a proxy and access other packages not through a proxy. Or maybe a script you might wish to -call may also need certain environment variables set to run properly. +The ``environment`` keyword allows you to set an environment varaible for the action to be taken on the remote target. +For example, it is quite possible that you may need to set a proxy for a task that does http requests. +Or maybe a utility or script that are called may also need certain environment variables set to run properly. -Ansible makes it easy for you to configure the remote execution environment by using the 'environment' keyword. Here is an example:: +Here is an example:: - hosts: all remote_user: root @@ -23,6 +23,10 @@ Ansible makes it easy for you to configure the remote execution environment by u environment: http_proxy: http://proxy.example.com:8080 +.. note:: + ``environment:`` does not affect Ansible itself, ONLY the context of the specific task action and this does not include + Ansible's own configuration settings nor the execution of any other plugins, including lookups, filters, and so on. + The environment can also be stored in a variable, and accessed like so:: - hosts: all @@ -104,6 +108,10 @@ Some language-specific version managers (such as rbenv and nvm) require environm path: '{{ node_app_dir }}' when: packagejson.stat.exists +.. note:: + ``ansible_env:`` is normally populated by fact gathering (M(gather_facts)) and the value of the variables depends on the user + that did the gathering action. If you change remote_user/become_user you might end up using the wrong values for those variables. + You might also want to simply specify the environment for a single task:: --- @@ -119,9 +127,6 @@ You might also want to simply specify the environment for a single task:: RBENV_ROOT: '{{ rbenv_root }}' PATH: '{{ rbenv_root }}/bin:{{ rbenv_root }}/shims:{{ rbenv_plugins }}/ruby-build/bin:{{ ansible_env.PATH }}' -.. note:: - ``environment:`` does not affect Ansible itself, ONLY the context of the specific task action and this does not include Ansible's own configuration settings. - .. seealso:: :ref:`playbooks_intro` diff --git a/docs/docsite/rst/user_guide/playbooks_variables.rst b/docs/docsite/rst/user_guide/playbooks_variables.rst index b5dd80788b..d099a52d4c 100644 --- a/docs/docsite/rst/user_guide/playbooks_variables.rst +++ b/docs/docsite/rst/user_guide/playbooks_variables.rst @@ -1044,7 +1044,7 @@ Basically, anything that goes into "role defaults" (the defaults folder inside t If you define a variable twice in a play's ``vars:`` section, the second one wins. .. note:: The previous describes the default config ``hash_behaviour=replace``, switch to ``merge`` to only partially overwrite. .. note:: Group loading follows parent/child relationships. Groups of the same 'parent/child' level are then merged following alphabetical order. - This last one can be superceeded by the user via ``ansible_group_priority``, which defaults to ``1`` for all groups. + This last one can be superseded by the user via ``ansible_group_priority``, which defaults to ``1`` for all groups. This variable, ``ansible_group_priority``, can only be set in the inventory source and not in group_vars/ as the variable is used in the loading of group_vars/. Another important thing to consider (for all versions) is that connection variables override config, command line and play/role/task specific options and keywords. See :ref:`general_precedence_rules` for more details. For example, if your inventory specifies ``ansible_user: ramon`` and you run:: diff --git a/docs/docsite/rst/user_guide/windows_winrm.rst b/docs/docsite/rst/user_guide/windows_winrm.rst index 7e44461a49..6bc9f3f6f3 100644 --- a/docs/docsite/rst/user_guide/windows_winrm.rst +++ b/docs/docsite/rst/user_guide/windows_winrm.rst @@ -818,7 +818,7 @@ The below Ansible tasks can also be used to enable TLS v1.2: data: '{{ item.value }}' type: dword state: present - register: enable_tls12 + register: enable_tls12 loop: - type: Server property: Enabled diff --git a/lib/ansible/modules/cloud/amazon/aws_batch_compute_environment.py b/lib/ansible/modules/cloud/amazon/aws_batch_compute_environment.py index 59898cdc2d..acf1e9e8c3 100644 --- a/lib/ansible/modules/cloud/amazon/aws_batch_compute_environment.py +++ b/lib/ansible/modules/cloud/amazon/aws_batch_compute_environment.py @@ -151,9 +151,11 @@ EXAMPLES = ''' tag1: value1 tag2: value2 service_role: arn:aws:iam::<account>:role/service-role/<role> + register: aws_batch_compute_environment_action - name: show results - debug: var=aws_batch_compute_environment_action + debug: + var: aws_batch_compute_environment_action ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/amazon/aws_batch_job_queue.py b/lib/ansible/modules/cloud/amazon/aws_batch_job_queue.py index 15c2fa025a..e733e8b156 100644 --- a/lib/ansible/modules/cloud/amazon/aws_batch_job_queue.py +++ b/lib/ansible/modules/cloud/amazon/aws_batch_job_queue.py @@ -67,7 +67,7 @@ EXAMPLES = ''' state: present tasks: - name: My Batch Job Queue - batch_job_queue: + aws_batch_job_queue: job_queue_name: jobQueueName state: present region: us-east-1 @@ -78,9 +78,11 @@ EXAMPLES = ''' compute_environment: my_compute_env1 - order: 2 compute_environment: my_compute_env2 + register: batch_job_queue_action - name: show results - debug: var=batch_job_queue_action + debug: + var: batch_job_queue_action ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/amazon/ec2_launch_template.py b/lib/ansible/modules/cloud/amazon/ec2_launch_template.py index 13567f2880..dfc4421b06 100644 --- a/lib/ansible/modules/cloud/amazon/ec2_launch_template.py +++ b/lib/ansible/modules/cloud/amazon/ec2_launch_template.py @@ -44,10 +44,8 @@ options: default: latest state: description: - - Whether the launch template should exist or not. To delete only a - specific version of a launch template, combine I(state=absent) with - the I(version) option. By default, I(state=absent) will remove all - versions of the template. + - Whether the launch template should exist or not. + - Deleting specific versions of a launch template is not supported at this time. choices: [present, absent] default: present block_device_mappings: diff --git a/lib/ansible/modules/cloud/amazon/elb_application_lb_info.py b/lib/ansible/modules/cloud/amazon/elb_application_lb_info.py index 6f16818639..5878e8bfbf 100644 --- a/lib/ansible/modules/cloud/amazon/elb_application_lb_info.py +++ b/lib/ansible/modules/cloud/amazon/elb_application_lb_info.py @@ -57,7 +57,8 @@ EXAMPLES = ''' names: "alb-name" region: "aws-region" register: alb_info -- debug: var=alb_info +- debug: + var: alb_info ''' RETURN = ''' diff --git a/lib/ansible/modules/cloud/amazon/lambda_policy.py b/lib/ansible/modules/cloud/amazon/lambda_policy.py index 0d208310a8..08f09795aa 100644 --- a/lib/ansible/modules/cloud/amazon/lambda_policy.py +++ b/lib/ansible/modules/cloud/amazon/lambda_policy.py @@ -111,9 +111,11 @@ EXAMPLES = ''' principal: s3.amazonaws.com source_arn: arn:aws:s3:eu-central-1:123456789012:bucketName source_account: 123456789012 + register: lambda_policy_action - name: show results - debug: var=lambda_policy_action + debug: + var: lambda_policy_action ''' diff --git a/lib/ansible/modules/files/template.py b/lib/ansible/modules/files/template.py index 3afcbae3d6..949c800ce6 100644 --- a/lib/ansible/modules/files/template.py +++ b/lib/ansible/modules/files/template.py @@ -64,7 +64,7 @@ EXAMPLES = r''' - name: Copy a version of named.conf that is dependent on the OS. setype obtained by doing ls -Z /etc/named.conf on original file template: - src: named.conf_{{ ansible_os_family}}.j2 + src: named.conf_{{ ansible_os_family }}.j2 dest: /etc/named.conf group: named setype: named_conf_t diff --git a/lib/ansible/modules/packaging/os/package.py b/lib/ansible/modules/packaging/os/package.py index 73f268105f..b48a5dcf07 100644 --- a/lib/ansible/modules/packaging/os/package.py +++ b/lib/ansible/modules/packaging/os/package.py @@ -59,4 +59,11 @@ EXAMPLES = ''' package: name: "{{ apache }}" state: absent + +- name: install the latest version of Apache and MariaDB + package: + name: + - httpd + - mariadb-server + state: latest ''' diff --git a/lib/ansible/plugins/lookup/password.py b/lib/ansible/plugins/lookup/password.py index 3ebe120be9..41cc3a61c5 100644 --- a/lib/ansible/plugins/lookup/password.py +++ b/lib/ansible/plugins/lookup/password.py @@ -73,10 +73,10 @@ EXAMPLES = """ password: "{{ lookup('password', '/tmp/passwordfile chars=ascii_letters') }}" priv: '{{ client }}_{{ tier }}_{{ role }}.*:ALL' -- name: create a mysql user with a random password using only digits +- name: create a mysql user with an 8 character random password using only digits mysql_user: name: "{{ client }}" - password: "{{ lookup('password', '/tmp/passwordfile chars=digits') }}" + password: "{{ lookup('password', '/tmp/passwordfile length=8 chars=digits') }}" priv: "{{ client }}_{{ tier }}_{{ role }}.*:ALL" - name: create a mysql user with a random password using many different char sets |