archive
/
ansible
mirror of https://github.com/ansible/ansible.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Backport/2.9/docs (#64073)

Browse Source 
* clarify no subfolders and md only for collections /docs folder (#63808)

(cherry picked from commit 6a2902c8d5)

* 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 c562e17659)

* 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 e4f16368ed)

* Update documentation for package module (#63909)
It is not clear from the documentation that list can be used

(cherry picked from commit 7f2c367d78)

* [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 7ea7260753)

* template: Add a space in example block (#63930)

(cherry picked from commit f279715c29)

* revisions to docsite  README (#63957)

(cherry picked from commit 5c962ef859)

* combine galaxy.com install roles details (#63486)

(cherry picked from commit ee8a088205)

* Correct a typo (#64020)

(cherry picked from commit 18f4f0549f)

* Update password.py (#63965)
Update the examples of the password lookup plugin to show how multiple options are joined together.

(cherry picked from commit 92daec5d0b)

* Fix indentation of example (#63789)
Remove no_log since module_defaults aren't displayed like set_fact was

(cherry picked from commit 1e52782d6b)

* add newline to render table correctly (#63769)

(cherry picked from commit 1aee11c860)

* clarified some points on environment keyword usage (#64065)

(cherry picked from commit 885ee62b53)
pull/64163/head
Alicia Cozine 5 years ago committed by GitHub
parent 12820ba64f
commit b80ca85a69
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
25 changed files with 645 additions and 461 deletions
Show Stats Download Patch File Download Diff File

183
docs/docsite/README.md
Unescape Escape View File

@ -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.

2
docs/docsite/rst/dev_guide/developing_collections.rst
Unescape Escape View File

@ -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:

5
docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst
Unescape Escape View File

@ -644,14 +644,15 @@ 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
block:
- name: Do Something
ec2_instance:

1
docs/docsite/rst/dev_guide/style_guide/index.rst
Unescape Escape View File

@ -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 |
+===============================+==============================+

60
docs/docsite/rst/galaxy/dev_guide/creating_roles.rst → docs/docsite/rst/galaxy/dev_guide.rst
Unescape Escape View File

@ -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,7 +236,10 @@ Provide the ID of the integration to be disabled. You can find the ID by using t
.. 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
:ref:`playbooks_reuse_roles`
All about ansible roles
`Mailing List <https://groups.google.com/group/ansible-project>`_

11
docs/docsite/rst/galaxy/dev_guide/creating_collections.rst
Unescape Escape View File

@ -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.

20
docs/docsite/rst/galaxy/dev_guide/index.rst
Unescape Escape View File

@ -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

391
docs/docsite/rst/galaxy/user_guide.rst
Unescape Escape View File

@ -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

14
docs/docsite/rst/galaxy/user_guide/finding_collections.rst
Unescape Escape View File

@ -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.

66
docs/docsite/rst/galaxy/user_guide/finding_roles.rst
Unescape Escape View File

@ -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

26
docs/docsite/rst/galaxy/user_guide/index.rst
Unescape Escape View File

@ -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

22
docs/docsite/rst/galaxy/user_guide/installing_collections.rst
Unescape Escape View File

@ -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

218
docs/docsite/rst/galaxy/user_guide/installing_roles.rst
Unescape Escape View File

@ -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

4
docs/docsite/rst/index.rst
Unescape Escape View File

@ -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::

19
docs/docsite/rst/user_guide/playbooks_environment.rst
Unescape Escape View File

@ -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`

2
docs/docsite/rst/user_guide/playbooks_variables.rst
Unescape Escape View File

@ -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::

4
lib/ansible/modules/cloud/amazon/aws_batch_compute_environment.py
Unescape Escape View File

@ -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 = '''

6
lib/ansible/modules/cloud/amazon/aws_batch_job_queue.py
Unescape Escape View File

@ -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 = '''

6
lib/ansible/modules/cloud/amazon/ec2_launch_template.py
Unescape Escape View File

@ -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:

3
lib/ansible/modules/cloud/amazon/elb_application_lb_info.py
Unescape Escape View File

@ -57,7 +57,8 @@ EXAMPLES = '''
names: "alb-name"
region: "aws-region"
register: alb_info
- debug: var=alb_info
- debug:
var: alb_info
'''
RETURN = '''

4
lib/ansible/modules/cloud/amazon/lambda_policy.py
Unescape Escape View File

@ -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
'''

2
lib/ansible/modules/files/template.py
Unescape Escape View File

@ -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

7
lib/ansible/modules/packaging/os/package.py
Unescape Escape View File

@ -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
'''

4
lib/ansible/plugins/lookup/password.py
Unescape Escape View File

@ -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

Write Preview
Loading…
Cancel
Save