1. ansible
  2. Commit b80ca85a694a714c93e241f281d0871be91fedd6
Browse code

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)

Alicia Cozine authored on 2019/10/31 02:42:24
Showing 26 changed files
docs/docsite/README.md
History View file @ b80ca85
... ... 
@@ -1,51 +1,176 @@
1 
-Homepage and Documentation Source for Ansible
2 
-=============================================
1 
+Ansible documentation
2 
+=====================
3 3
4 
-This project hosts the source behind [docs.ansible.com](https://docs.ansible.com/)
4 
+This project hosts the source behind [docs.ansible.com](https://docs.ansible.com/).
5 5
6 
-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.
6 
+To create clear, concise, consistent, useful materials on docs.ansible.com, please refer to the following information.
7 7
8 
-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.
9 8
10 
-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/`.
9 
+About Ansible
10 
+-------------
11 
+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).
11 12
12 
-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`.
13 
+To install Ansible, see the [Installation Guide](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html).
13 14
15 
+The following sections provide information and resources on contributing to Ansible documentation.
16 
+
17 
+Contributions
18 
+=============
19 
+Ansible documentation is written in ReStructuredText(RST). Contributions to the documentation are welcome.
20 
+
21 
+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).
22 
+
23 
+Filing issues
24 
+-------------
14 25 
 If you do not want to learn the reStructuredText format, you can also [file issues] about documentation problems on the Ansible GitHub project.
15 26
16 
-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.
27 
+Editing docs directly on GitHub
28 
+-------------------------------
29 
+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.
30 
+
31 
+Ansible style guide
32 
+===================
33 
+
34 
+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).
35 
+
36 
+reStructuredText
37 
+----------------
38 
+The Ansible style guide also includes useful guidelines on writing in reStructuredText. Please see the style guide for reStructuredText formatting guidelines for:
39 
+* header notation
40 
+* internal navigation
41 
+* linking
42 
+* local table of contents
43 
+
44 
+
45 
+Tools
46 
+=====
47 
+
48 
+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.
49 
+
50 
+Popular editors
51 
+---------------
52 
+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).
53 
+
54 
+Building documentation
55 
+----------------------
56 
+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.
57 
+
58 
+Github
59 
+------
60 
+[Ansible documentation](https://github.com/ansible/ansible/tree/devel/docs/docsite) is hosted on the Ansible Github project.
61 
+
62 
+The following sections describe the workflows required to start developing or submit changes to Ansible documentation.
63 
+
17 64
18 
-To install sphinx and the required theme, install ``pip`` and then ``pip install sphinx sphinx_rtd_theme``
65 
+## Setting up Git
19 66
20 
-[file issues]: https://github.com/ansible/ansible/issues
21 
-[module-docs]: https://docs.ansible.com/developing_modules.html#documenting-your-module
22 67
23 
-HEADERS
24 
-=======
68 
+GitHub provides a set of [Git cheatsheets](https://github.github.com/training-kit/) in multiple languages.
25 69
26 
-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:
70 
+1. First [Install Git](https://help.github.com/en/articles/set-up-git)
27 71
72 
+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).
73 
+
74 
+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.
75 
+
76 
+4. [Clone](https://help.github.com/en/articles/cloning-a-repository) from your fork to create a copy on your local machine.
77 
+
78 
+  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:
79 
+`git@github.com:{yourusername}/ansible.git`
80 
+
81 
+
82 
+```
83 
+$ git clone  git@github.com:{yourusername}/ansible.git
28 84 
 ```
29 
-##########################
30 
-# with overline, for parts
31 
-##########################
32 85
33 
-*****************************
34 
-* with overline, for chapters
35 
-*****************************
86 
+5. Navigate to the new directory by entering the following from the command line on your local machine:
87 
+```
88 
+$ cd {repository-name}
89 
+```
36 90
37 
-=, for sections
38 
-===============
91 
+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.
92 
+```
93 
+$ git remote add upstream git://github.com/ansible/ansible.git
94 
+```
39 95
40 
--, for subsections
96 
+7. Check your settings.
97 
+```
98 
+$ git remote -v
99 
+origin    https://github.com/{YOUR_USERNAME}/{YOUR_FORK}.git (fetch)
100 
+origin    https://github.com/{YOUR_USERNAME}/{YOUR_FORK}.git (push)
101 
+upstream  https://github.com/{ORIGINAL_OWNER}/{ORIGINAL_REPOSITORY}.git (fetch)
102 
+upstream  https://github.com/{ORIGINAL_OWNER}/{ORIGINAL_REPOSITORY}.git (push)
103 
+```
41 104
42 
-^, for sub-subsections
43 
-^^^^^^^^^^^^^^^^^^^^^
105 
+## Creating a topic branch
44 106
45 
-", for paragraphs
46 
-"""""""""""""""""
107 
+Create a topic branch for new documentation submissions or larger changes.
47 108
109 
+1. Fetch updates from ``origin``:
110 
+```
111 
+$ git fetch origin
112 
+```
113 
+2. Checkout a new branch based on ``devel``:
48 114 
 ```
115 
+$ git checkout -b {branch name}
116 
+```
117 
+3. Create new documents or make changes to existing files.
118 
+4. Add new or changed files:
119 
+```
120 
+$ git add {file name}
121 
+```
122 
+5. Commit your changes or additions. Be sure to include a commit message:
123 
+```
124 
+$ git commit -m "new message"
125 
+```
126 
+6. Push your updates back to `origin`:
127 
+```
128 
+$ git push -u origin {branch name}
129 
+```
130 
+
131 
+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.
132 
+
133 
+
134 
+When final additions or changes are pushed back to your fork you can open a pull request (PR).
135 
+
136 
+
137 
+Working with pull requests (PRs)
138 
+--------------------------------
139 
+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.
140 
+
141 
+## Creating a pull request
142 
+1. Navigate to your personal fork: https://github.com/{yourusername}/ansible
143 
+2. Click **Pull requests** and then click **New pull requests**.
144 
+3. Use the drop-down menus, set the **base repository** to the stable branch and set the **head repository** to your topic branch.
145 
+4. Apply appropriate labels. Include **backport** and **documentation**.
146 
+6. Fill in the PR summary using the following template:
147 
+
148 
+```
149 
+##### SUMMARY
150 
+
151 
+##### ISSUE TYPE
152 
+
153 
+##### COMPONENT NAME
154 
+docs.ansible.com
155 
+##### ANSIBLE VERSION
156 
+
157 
+##### ADDITIONAL INFORMATION
158 
+
159 
+```
160 
+NOTE:
161 
+If you put 'closes <issuenumber> '  in the summary, ansible will automatically close the issue on merge.
162 
+
163 
+7. Click **Create pull request**.
164 
+
165 
+
166 
+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.
167 
+
168 
+## Backporting a pull request
169 
+
170 
+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.
171 
+
172 
+See [Backporting merged PRs](https://docs.ansible.com/ansible/devel/community/development_process.html?highlight=backport#backporting-merged-prs) for a complete worklfow.
173 
+
174 
+## Other Git workflows
49 175
50 
-We do have pages littered with ```````` headers, but those should be removed for one of the above.
176 
+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.
docs/docsite/rst/dev_guide/developing_collections.rst
History View file @ b80ca85
... ... 
@@ -60,7 +60,7 @@ See :ref:`collections_galaxy_meta` for details.
60 60 
 docs directory
61 61 
 ---------------
62 62
63 
-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.
63 
+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.
64 64
65 65 
 Use ``ansible-doc`` to view documentation for plugins inside a collection:
66 66
docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst
History View file @ b80ca85
... ... 
@@ -644,22 +644,23 @@ for every call, it's preferable to use :ref:`module_defaults <module_defaults>`.
644 644
645 645 
 .. code-block:: yaml
646 646
647 
-   - name: set connection information for all tasks
647 
+   - name: set connection information for aws modules and run tasks
648 648 
      module_defaults:
649 649 
        group/aws:
650 650 
          aws_access_key: "{{ aws_access_key }}"
651 651 
          aws_secret_key: "{{ aws_secret_key }}"
652 652 
          security_token: "{{ security_token }}"
653 653 
          region: "{{ aws_region }}"
654 
-     no_log: yes
655 654
656 
-   - name: Do Something
657 
-     ec2_instance:
658 
-       ... params ...
655 
+     block:
659 656
660 
-   - name: Do Something Else
661 
-     ec2_instance:
662 
-       ... params ...
657 
+     - name: Do Something
658 
+       ec2_instance:
659 
+         ... params ...
660 
+
661 
+     - name: Do Something Else
662 
+       ec2_instance:
663 
+         ... params ...
663 664
664 665 
 AWS Permissions for Integration Tests
665 666 
 -------------------------------------
docs/docsite/rst/dev_guide/style_guide/index.rst
History View file @ b80ca85
... ... 
@@ -57,6 +57,7 @@ are easily understood by English speakers.
57 57 
 They may be harder to understand for others and are also tricky for automated translation.
58 58
59 59 
 Use the following English terms in place of Latin terms or abbreviations:
60 
+
60 61 
 +-------------------------------+------------------------------+
61 62 
 | Latin                         | English                      |
62 63 
 +===============================+==============================+
docs/docsite/rst/galaxy/dev_guide.rst
History View file @ b80ca85
63 64 
new file mode 100644
... ... 
@@ -0,0 +1,248 @@
0 
+.. _developing_galaxy:
1 
+
2 
+**********************
3 
+Galaxy Developer Guide
4 
+**********************
5 
+
6 
+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>`_.
7 
+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.
8 
+
9 
+.. contents::
10 
+   :local:
11 
+   :depth: 2
12 
+
13 
+.. _creating_collections_galaxy:
14 
+
15 
+Creating collections for Galaxy
16 
+===============================
17 
+
18 
+Collections are a distribution format for Ansible content. You can use collections to package and distribute playbooks, roles, modules, and plugins.
19 
+You can publish and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.
20 
+
21 
+See :ref:`developing_collections` for details on how to create collections.
22 
+
23 
+.. _creating_roles_galaxy:
24 
+
25 
+
26 
+Creating roles for Galaxy
27 
+=========================
28 
+
29 
+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
30 
+
31 
+.. code-block:: bash
32 
+
33 
+   $ ansible-galaxy init role_name
34 
+
35 
+The above will create the following directory structure in the current working directory:
36 
+
37 
+.. code-block:: text
38 
+
39 
+   role_name/
40 
+       README.md
41 
+       .travis.yml
42 
+       defaults/
43 
+           main.yml
44 
+       files/
45 
+       handlers/
46 
+           main.yml
47 
+       meta/
48 
+           main.yml
49 
+       templates/
50 
+       tests/
51 
+           inventory
52 
+           test.yml
53 
+       vars/
54 
+           main.yml
55 
+
56 
+If you want to create a repository for the role the repository root should be `role_name`.
57 
+
58 
+Force
59 
+-----
60 
+
61 
+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
62 
+use the *--force* option. Force will create the above subdirectories and files, replacing anything that matches.
63 
+
64 
+Container enabled
65 
+-----------------
66 
+
67 
+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
68 
+with default files appropriate for a Container Enabled role. For instance, the README.md has a slightly different structure, the *.travis.yml* file tests
69 
+the role using `Ansible Container <https://github.com/ansible/ansible-container>`_, and the meta directory includes a *container.yml* file.
70 
+
71 
+Using a custom role skeleton
72 
+----------------------------
73 
+
74 
+A custom role skeleton directory can be supplied as follows:
75 
+
76 
+.. code-block:: bash
77 
+
78 
+   $ ansible-galaxy init --role-skeleton=/path/to/skeleton role_name
79 
+
80 
+When a skeleton is provided, init will:
81 
+
82 
+- copy all files and directories from the skeleton to the new role
83 
+- any .j2 files found outside of a templates folder will be rendered as templates. The only useful variable at the moment is role_name
84 
+- The .git folder and any .git_keep files will not be copied
85 
+
86 
+Alternatively, the role_skeleton and ignoring of files can be configured via ansible.cfg
87 
+
88 
+.. code-block:: text
89 
+
90 
+  [galaxy]
91 
+  role_skeleton = /path/to/skeleton
92 
+  role_skeleton_ignore = ^.git$,^.*/.git_keep$
93 
+
94 
+Authenticate with Galaxy
95 
+------------------------
96 
+
97 
+Using the ``import``, ``delete`` and ``setup`` commands to manage your roles on the Galaxy website requires authentication, and the ``login`` command
98 
+can be used to do just that. Before you can use the ``login`` command, you must create an account on the Galaxy website.
99 
+
100 
+The ``login`` command requires using your GitHub credentials. You can use your username and password, or you can create a `personal access token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_. If you choose to create a token, grant minimal access to the token, as it is used just to verify identify.
101 
+
102 
+The following shows authenticating with the Galaxy website using a GitHub username and password:
103 
+
104 
+.. code-block:: text
105 
+
106 
+   $ ansible-galaxy login
107 
+
108 
+   We need your GitHub login to identify you.
109 
+   This information will not be sent to Galaxy, only to api.github.com.
110 
+   The password will not be displayed.
111 
+
112 
+   Use --github-token if you do not want to enter your password.
113 
+
114 
+   GitHub Username: dsmith
115 
+   Password for dsmith:
116 
+   Successfully logged into Galaxy as dsmith
117 
+
118 
+When you choose to use your username and password, your password is not sent to Galaxy. It is used to authenticates with GitHub and create a personal access token.
119 
+It then sends the token to Galaxy, which in turn verifies that your identity and returns a Galaxy access token. After authentication completes the GitHub token is
120 
+destroyed.
121 
+
122 
+If you do not wish to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the *--github-token* option to pass a personal access token that you create.
123 
+
124 
+
125 
+Import a role
126 
+-------------
127 
+
128 
+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 
+
130 
+Use the following to import to role:
131 
+
132 
+.. code-block:: bash
133 
+
134 
+  $ ansible-galaxy import github_user github_repo
135 
+
136 
+By default the command will wait for Galaxy to complete the import process, displaying the results as the import progresses:
137 
+
138 
+.. code-block:: text
139 
+
140 
+      Successfully submitted import request 41
141 
+      Starting import 41: role_name=myrole repo=githubuser/ansible-role-repo ref=
142 
+      Retrieving GitHub repo githubuser/ansible-role-repo
143 
+      Accessing branch: master
144 
+      Parsing and validating meta/main.yml
145 
+      Parsing galaxy_tags
146 
+      Parsing platforms
147 
+      Adding dependencies
148 
+      Parsing and validating README.md
149 
+      Adding repo tags as role versions
150 
+      Import completed
151 
+      Status SUCCESS : warnings=0 errors=0
152 
+
153 
+Branch
154 
+^^^^^^
155 
+
156 
+Use the *--branch* option to import a specific branch. If not specified, the default branch for the repo will be used.
157 
+
158 
+Role name
159 
+^^^^^^^^^
160 
+
161 
+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.
162 
+
163 
+No wait
164 
+^^^^^^^
165 
+
166 
+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*.
167 
+
168 
+Delete a role
169 
+-------------
170 
+
171 
+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.
172 
+
173 
+Use the following to delete a role:
174 
+
175 
+.. code-block:: bash
176 
+
177 
+  $ ansible-galaxy delete github_user github_repo
178 
+
179 
+This only removes the role from Galaxy. It does not remove or alter the actual GitHub repository.
180 
+
181 
+
182 
+Travis integrations
183 
+-------------------
184 
+
185 
+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
186 
+automatically trigger an import in Galaxy, updating the search index with the latest information about the role.
187 
+
188 
+You create the integration using the ``setup`` command, but before an integration can be created, you must first authenticate using the ``login`` command; you will
189 
+also need an account in Travis, and your Travis token. Once you're ready, use the following command to create the integration:
190 
+
191 
+.. code-block:: bash
192 
+
193 
+  $ ansible-galaxy setup travis github_user github_repo xxx-travis-token-xxx
194 
+
195 
+The setup command requires your Travis token, however the token is not stored in Galaxy. It is used along with the GitHub username and repo to create a hash as described
196 
+in `the Travis documentation <https://docs.travis-ci.com/user/notifications/>`_. The hash is stored in Galaxy and used to verify notifications received from Travis.
197 
+
198 
+The setup command enables Galaxy to respond to notifications. To configure Travis to run a build on your repository and send a notification, follow the
199 
+`Travis getting started guide <https://docs.travis-ci.com/user/getting-started/>`_.
200 
+
201 
+To instruct Travis to notify Galaxy when a build completes, add the following to your .travis.yml file:
202 
+
203 
+.. code-block:: text
204 
+
205 
+    notifications:
206 
+        webhooks: https://galaxy.ansible.com/api/v1/notifications/
207 
+
208 
+
209 
+List Travis integrations
210 
+^^^^^^^^^^^^^^^^^^^^^^^^
211 
+
212 
+Use the *--list* option to display your Travis integrations:
213 
+
214 
+.. code-block:: bash
215 
+
216 
+      $ ansible-galaxy setup --list
217 
+
218 
+
219 
+      ID         Source     Repo
220 
+      ---------- ---------- ----------
221 
+      2          travis     github_user/github_repo
222 
+      1          travis     github_user/github_repo
223 
+
224 
+
225 
+Remove Travis integrations
226 
+^^^^^^^^^^^^^^^^^^^^^^^^^^
227 
+
228 
+Use the *--remove* option to disable and remove a Travis integration:
229 
+
230 
+  .. code-block:: bash
231 
+
232 
+    $ ansible-galaxy setup --remove ID
233 
+
234 
+Provide the ID of the integration to be disabled. You can find the ID by using the *--list* option.
235 
+
236 
+
237 
+.. seealso::
238 
+  `collections <collections>`_
239 
+    Sharable collections of modules, playbooks and roles
240 
+  `roles <playbooks_reuse_roles>`_
241 
+    Reusable tasks, handlers, and other files in a known directory structure
242 
+  :ref:`playbooks_reuse_roles`
243 
+    All about ansible roles
244 
+  `Mailing List <https://groups.google.com/group/ansible-project>`_
245 
+    Questions? Help? Ideas?  Stop by the list on Google Groups
246 
+  `irc.freenode.net <http://irc.freenode.net>`_
247 
+    #ansible IRC chat channel
docs/docsite/rst/galaxy/dev_guide/creating_collections.rst
History View file @ b80ca85
0 248 
deleted file mode 100644
... ... 
@@ -1,11 +0,0 @@
1 
-.. _creating_collections_galaxy:
2 
-
3 
-*******************************
4 
-Creating collections for Galaxy
5 
-*******************************
6 
-
7 
-
8 
-Collections are a distribution format for Ansible content. You can use collections to package and distribute playbooks, roles, modules, and plugins.
9 
-You can publish and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_.
10 
-
11 
-See :ref:`developing_collections` for details on how to create collections.
docs/docsite/rst/galaxy/dev_guide/creating_roles.rst
History View file @ b80ca85
12 1 
deleted file mode 100644
... ... 
@@ -1,222 +0,0 @@
1 
-.. _creating_roles_galaxy:
2 
-
3 
-*************************
4 
-Creating roles for Galaxy
5 
-*************************
6 
-
7 
-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
8 
-
9 
-.. code-block:: bash
10 
-
11 
-   $ ansible-galaxy init role_name
12 
-
13 
-The above will create the following directory structure in the current working directory:
14 
-
15 
-.. code-block:: text
16 
-
17 
-   role_name/
18 
-       README.md
19 
-       .travis.yml
20 
-       defaults/
21 
-           main.yml
22 
-       files/
23 
-       handlers/
24 
-           main.yml
25 
-       meta/
26 
-           main.yml
27 
-       templates/
28 
-       tests/
29 
-           inventory
30 
-           test.yml
31 
-       vars/
32 
-           main.yml
33 
-
34 
-If you want to create a repository for the role the repository root should be `role_name`.
35 
-
36 
-Force
37 
-=====
38 
-
39 
-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
40 
-use the *--force* option. Force will create the above subdirectories and files, replacing anything that matches.
41 
-
42 
-Container Enabled
43 
-=================
44 
-
45 
-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
46 
-with default files appropriate for a Container Enabled role. For instance, the README.md has a slightly different structure, the *.travis.yml* file tests
47 
-the role using `Ansible Container <https://github.com/ansible/ansible-container>`_, and the meta directory includes a *container.yml* file.
48 
-
49 
-Using a Custom Role Skeleton
50 
-============================
51 
-
52 
-A custom role skeleton directory can be supplied as follows:
53 
-
54 
-.. code-block:: bash
55 
-
56 
-   $ ansible-galaxy init --role-skeleton=/path/to/skeleton role_name
57 
-
58 
-When a skeleton is provided, init will:
59 
-
60 
-- copy all files and directories from the skeleton to the new role
61 
-- any .j2 files found outside of a templates folder will be rendered as templates. The only useful variable at the moment is role_name
62 
-- The .git folder and any .git_keep files will not be copied
63 
-
64 
-Alternatively, the role_skeleton and ignoring of files can be configured via ansible.cfg
65 
-
66 
-.. code-block:: text
67 
-
68 
-  [galaxy]
69 
-  role_skeleton = /path/to/skeleton
70 
-  role_skeleton_ignore = ^.git$,^.*/.git_keep$
71 
-
72 
-Authenticate with Galaxy
73 
-========================
74 
-
75 
-Using the ``import``, ``delete`` and ``setup`` commands to manage your roles on the Galaxy website requires authentication, and the ``login`` command
76 
-can be used to do just that. Before you can use the ``login`` command, you must create an account on the Galaxy website.
77 
-
78 
-The ``login`` command requires using your GitHub credentials. You can use your username and password, or you can create a `personal access token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_. If you choose to create a token, grant minimal access to the token, as it is used just to verify identify.
79 
-
80 
-The following shows authenticating with the Galaxy website using a GitHub username and password:
81 
-
82 
-.. code-block:: text
83 
-
84 
-   $ ansible-galaxy login
85 
-
86 
-   We need your GitHub login to identify you.
87 
-   This information will not be sent to Galaxy, only to api.github.com.
88 
-   The password will not be displayed.
89 
-
90 
-   Use --github-token if you do not want to enter your password.
91 
-
92 
-   GitHub Username: dsmith
93 
-   Password for dsmith:
94 
-   Successfully logged into Galaxy as dsmith
95 
-
96 
-When you choose to use your username and password, your password is not sent to Galaxy. It is used to authenticates with GitHub and create a personal access token.
97 
-It then sends the token to Galaxy, which in turn verifies that your identity and returns a Galaxy access token. After authentication completes the GitHub token is
98 
-destroyed.
99 
-
100 
-If you do not wish to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the *--github-token* option to pass a personal access token that you create.
101 
-
102 
-
103 
-Import a role
104 
-=============
105 
-
106 
-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.
107 
-
108 
-Use the following to import to role:
109 
-
110 
-.. code-block:: bash
111 
-
112 
-  $ ansible-galaxy import github_user github_repo
113 
-
114 
-By default the command will wait for Galaxy to complete the import process, displaying the results as the import progresses:
115 
-
116 
-.. code-block:: text
117 
-
118 
-      Successfully submitted import request 41
119 
-      Starting import 41: role_name=myrole repo=githubuser/ansible-role-repo ref=
120 
-      Retrieving GitHub repo githubuser/ansible-role-repo
121 
-      Accessing branch: master
122 
-      Parsing and validating meta/main.yml
123 
-      Parsing galaxy_tags
124 
-      Parsing platforms
125 
-      Adding dependencies
126 
-      Parsing and validating README.md
127 
-      Adding repo tags as role versions
128 
-      Import completed
129 
-      Status SUCCESS : warnings=0 errors=0
130 
-
131 
-Branch
132 
-
133 
-Use the *--branch* option to import a specific branch. If not specified, the default branch for the repo will be used.
134 
-
135 
-Role name
136 
-
137 
-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.
138 
-
139 
-No wait
140 
-
141 
-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*.
142 
-
143 
-Delete a role
144 
-=============
145 
-
146 
-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.
147 
-
148 
-Use the following to delete a role:
149 
-
150 
-.. code-block:: bash
151 
-
152 
-  $ ansible-galaxy delete github_user github_repo
153 
-
154 
-This only removes the role from Galaxy. It does not remove or alter the actual GitHub repository.
155 
-
156 
-
157 
-Travis integrations
158 
-===================
159 
-
160 
-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
161 
-automatically trigger an import in Galaxy, updating the search index with the latest information about the role.
162 
-
163 
-You create the integration using the ``setup`` command, but before an integration can be created, you must first authenticate using the ``login`` command; you will
164 
-also need an account in Travis, and your Travis token. Once you're ready, use the following command to create the integration:
165 
-
166 
-.. code-block:: bash
167 
-
168 
-  $ ansible-galaxy setup travis github_user github_repo xxx-travis-token-xxx
169 
-
170 
-The setup command requires your Travis token, however the token is not stored in Galaxy. It is used along with the GitHub username and repo to create a hash as described
171 
-in `the Travis documentation <https://docs.travis-ci.com/user/notifications/>`_. The hash is stored in Galaxy and used to verify notifications received from Travis.
172 
-
173 
-The setup command enables Galaxy to respond to notifications. To configure Travis to run a build on your repository and send a notification, follow the
174 
-`Travis getting started guide <https://docs.travis-ci.com/user/getting-started/>`_.
175 
-
176 
-To instruct Travis to notify Galaxy when a build completes, add the following to your .travis.yml file:
177 
-
178 
-.. code-block:: text
179 
-
180 
-    notifications:
181 
-        webhooks: https://galaxy.ansible.com/api/v1/notifications/
182 
-
183 
-
184 
-List Travis integrations
185 
-
186 
-Use the *--list* option to display your Travis integrations:
187 
-
188 
-.. code-block:: bash
189 
-
190 
-      $ ansible-galaxy setup --list
191 
-
192 
-
193 
-      ID         Source     Repo
194 
-      ---------- ---------- ----------
195 
-      2          travis     github_user/github_repo
196 
-      1          travis     github_user/github_repo
197 
-
198 
-
199 
-Remove Travis integrations
200 
-
201 
-Use the *--remove* option to disable and remove a Travis integration:
202 
-
203 
-  .. code-block:: bash
204 
-
205 
-    $ ansible-galaxy setup --remove ID
206 
-
207 
-Provide the ID of the integration to be disabled. You can find the ID by using the *--list* option.
208 
-
209 
-
210 
-.. seealso::
211 
-
212 
-   :ref:`playbooks_reuse_roles`
213 
-       All about ansible roles
214 
-   `Mailing List <https://groups.google.com/group/ansible-project>`_
215 
-       Questions? Help? Ideas?  Stop by the list on Google Groups
216 
-   `irc.freenode.net <http://irc.freenode.net>`_
217 
-       #ansible IRC chat channel
docs/docsite/rst/galaxy/dev_guide/index.rst
History View file @ b80ca85
218 1 
deleted file mode 100644
... ... 
@@ -1,20 +0,0 @@
1 
-.. _developing_galaxy:
2 
-
3 
-***************
4 
-Developer Guide
5 
-***************
6 
-
7 
-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>`_.
8 
-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.
9 
-
10 
-.. toctree::
11 
-   :maxdepth: 2
12 
-
13 
-   creating_collections
14 
-   creating_roles
15 
-
16 
-.. seealso::
17 
-  `collections <collections>`_
18 
-    Sharable collections of modules, playbooks and roles
19 
-  `roles <playbooks_reuse_roles>`_
20 
-    Reusable tasks, handlers, and other files in a known directory structure
docs/docsite/rst/galaxy/user_guide.rst
History View file @ b80ca85
21 1 
new file mode 100644
... ... 
@@ -0,0 +1,391 @@
0 
+.. _using_galaxy:
1 
+.. _ansible_galaxy:
2 
+
3 
+*****************
4 
+Galaxy User Guide
5 
+*****************
6 
+
7 
+:dfn:`Ansible Galaxy` refers to the `Galaxy <https://galaxy.ansible.com>`_  website, a free site for finding, downloading, and sharing community developed roles.
8 
+
9 
+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>`_.
10 
+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.
11 
+
12 
+.. contents::
13 
+   :local:
14 
+   :depth: 2
15 
+.. _finding_galaxy_collections:
16 
+
17 
+Finding collections on Galaxy
18 
+=============================
19 
+
20 
+To find collections on Galaxy:
21 
+
22 
+#. Click the :guilabel:`Search` icon in the left-hand navigation.
23 
+#. Set the filter to *collection*.
24 
+#. Set other filters and press :guilabel:`enter`.
25 
+
26 
+Galaxy presents a list of collections that match your search criteria.
27 
+
28 
+.. _installing_galaxy_collections:
29 
+
30 
+Installing collections from Galaxy
31 
+==================================
32 
+
33 
+.. include:: ../shared_snippets/installing_collections.txt
34 
+
35 
+
36 
+Installing an older version of a collection
37 
+-------------------------------------------
38 
+
39 
+.. include:: ../shared_snippets/installing_older_collection.txt
40 
+
41 
+Install multiple collections with a requirements file
42 
+-----------------------------------------------------
43 
+
44 
+.. include:: ../shared_snippets/installing_multiple_collections.txt
45 
+
46 
+Galaxy server configuration list
47 
+--------------------------------
48 
+
49 
+.. include:: ../shared_snippets/galaxy_server_list.txt
50 
+
51 
+
52 
+.. _finding_galaxy_roles:
53 
+
54 
+Finding roles on Galaxy
55 
+=======================
56 
+
57 
+Search the Galaxy database by tags, platforms, author and multiple keywords. For example:
58 
+
59 
+.. code-block:: bash
60 
+
61 
+    $ ansible-galaxy search elasticsearch --author geerlingguy
62 
+
63 
+The search command will return a list of the first 1000 results matching your search:
64 
+
65 
+.. code-block:: text
66 
+
67 
+    Found 2 roles matching your search:
68 
+
69 
+    Name                              Description
70 
+    ----                              -----------
71 
+    geerlingguy.elasticsearch         Elasticsearch for Linux.
72 
+    geerlingguy.elasticsearch-curator Elasticsearch curator for Linux.
73 
+
74 
+
75 
+Get more information about a role
76 
+---------------------------------
77 
+
78 
+Use the ``info`` command to view more detail about a specific role:
79 
+
80 
+.. code-block:: bash
81 
+
82 
+    $ ansible-galaxy info username.role_name
83 
+
84 
+This returns everything found in Galaxy for the role:
85 
+
86 
+.. code-block:: text
87 
+
88 
+    Role: username.role_name
89 
+        description: Installs and configures a thing, a distributed, highly available NoSQL thing.
90 
+        active: True
91 
+        commit: c01947b7bc89ebc0b8a2e298b87ab416aed9dd57
92 
+        commit_message: Adding travis
93 
+        commit_url: https://github.com/username/repo_name/commit/c01947b7bc89ebc0b8a2e298b87ab
94 
+        company: My Company, Inc.
95 
+        created: 2015-12-08T14:17:52.773Z
96 
+        download_count: 1
97 
+        forks_count: 0
98 
+        github_branch:
99 
+        github_repo: repo_name
100 
+        github_user: username
101 
+        id: 6381
102 
+        is_valid: True
103 
+        issue_tracker_url:
104 
+        license: Apache
105 
+        min_ansible_version: 1.4
106 
+        modified: 2015-12-08T18:43:49.085Z
107 
+        namespace: username
108 
+        open_issues_count: 0
109 
+        path: /Users/username/projects/roles
110 
+        scm: None
111 
+        src: username.repo_name
112 
+        stargazers_count: 0
113 
+        travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=master
114 
+        version:
115 
+        watchers_count: 1
116 
+
117 
+
118 
+.. _installing_galaxy_roles:
119 
+
120 
+Installing roles from Galaxy
121 
+============================
122 
+
123 
+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
124 
+also use it to create a new role, remove roles, or perform tasks on the Galaxy website.
125 
+
126 
+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>`_
127 
+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
128 
+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`.
129 
+
130 
+
131 
+Installing roles
132 
+----------------
133 
+
134 
+Use the ``ansible-galaxy`` command to download roles from the `Galaxy website <https://galaxy.ansible.com>`_
135 
+
136 
+.. code-block:: bash
137 
+
138 
+  $ ansible-galaxy install namespace.role_name
139 
+
140 
+Setting where to install roles
141 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
142 
+
143 
+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``.
144 
+
145 
+You can override this with one of the following options:
146 
+
147 
+* Set the environment variable :envvar:`ANSIBLE_ROLES_PATH` in your session.
148 
+* Define ``roles_path`` in an ``ansible.cfg`` file.
149 
+* Use the ``--roles-path`` option for the ``ansible-galaxy`` command.
150 
+
151 
+The following provides an example of using ``--roles-path`` to install the role into the current working directory:
152 
+
153 
+.. code-block:: bash
154 
+
155 
+    $ ansible-galaxy install --roles-path . geerlingguy.apache
156 
+
157 
+.. seealso::
158 
+
159 
+   :ref:`intro_configuration`
160 
+      All about configuration files
161 
+
162 
+Installing a specific version of a role
163 
+---------------------------------------
164 
+
165 
+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.
166 
+
167 
+To see the available versions for a role:
168 
+
169 
+#. Locate the role on the Galaxy search page.
170 
+#. Click on the name to view more details, including the available versions.
171 
+
172 
+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>`_.
173 
+
174 
+To install a specific version of a role from Galaxy, append a comma and the value of a GitHub release tag. For example:
175 
+
176 
+.. code-block:: bash
177 
+
178 
+   $ ansible-galaxy install geerlingguy.apache,v1.0.0
179 
+
180 
+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
181 
+install a specific commit:
182 
+
183 
+.. code-block:: bash
184 
+
185 
+   $ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25
186 
+
187 
+Installing multiple roles from a file
188 
+-------------------------------------
189 
+
190 
+You can install multiple roles by including the roles in a :file:`requirements.yml` file. The format of the file is YAML, and the
191 
+file extension must be either *.yml* or *.yaml*.
192 
+
193 
+Use the following command to install roles included in :file:`requirements.yml:`
194 
+
195 
+.. code-block:: bash
196 
+
197 
+    $ ansible-galaxy install -r requirements.yml
198 
+
199 
+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,
200 
+"basic" format.
201 
+
202 
+Each role in the file will have one or more of the following attributes:
203 
+
204 
+   src
205 
+     The source of the role. Use the format *namespace.role_name*, if downloading from Galaxy; otherwise, provide a URL pointing
206 
+     to a repository within a git based SCM. See the examples below. This is a required attribute.
207 
+   scm
208 
+     Specify the SCM. As of this writing only *git* or *hg* are allowed. See the examples below. Defaults to *git*.
209 
+   version:
210 
+     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*.
211 
+   name:
212 
+     Download the role to a specific name. Defaults to the Galaxy name when downloading from Galaxy, otherwise it defaults
213 
+     to the name of the repository.
214 
+
215 
+Use the following example as a guide for specifying roles in *requirements.yml*:
216 
+
217 
+.. code-block:: yaml
218 
+
219 
+    # from galaxy
220 
+    - src: yatesr.timezone
221 
+
222 
+    # from GitHub
223 
+    - src: https://github.com/bennojoy/nginx
224 
+
225 
+    # from GitHub, overriding the name and specifying a specific tag
226 
+    - src: https://github.com/bennojoy/nginx
227 
+      version: master
228 
+      name: nginx_role
229 
+
230 
+    # from a webserver, where the role is packaged in a tar.gz
231 
+    - src: https://some.webserver.example.com/files/master.tar.gz
232 
+      name: http-role-gz
233 
+
234 
+    # from a webserver, where the role is packaged in a tar.bz2
235 
+    - src: https://some.webserver.example.com/files/master.tar.bz2
236 
+      name: http-role-bz2
237 
+
238 
+    # from a webserver, where the role is packaged in a tar.xz (Python 3.x only)
239 
+    - src: https://some.webserver.example.com/files/master.tar.xz
240 
+      name: http-role-xz
241 
+
242 
+    # from Bitbucket
243 
+    - src: git+https://bitbucket.org/willthames/git-ansible-galaxy
244 
+      version: v1.4
245 
+
246 
+    # from Bitbucket, alternative syntax and caveats
247 
+    - src: https://bitbucket.org/willthames/hg-ansible-galaxy
248 
+      scm: hg
249 
+
250 
+    # from GitLab or other git-based scm, using git+ssh
251 
+    - src: git@gitlab.company.com:mygroup/ansible-base.git
252 
+      scm: git
253 
+      version: "0.1"  # quoted, so YAML doesn't parse this as a floating-point value
254 
+
255 
+Installing multiple roles from multiple files
256 
+---------------------------------------------
257 
+
258 
+For large projects, the ``include`` directive in a :file:`requirements.yml` file provides the ability to split a large file into multiple smaller files.
259 
+
260 
+For example, a project may have a :file:`requirements.yml` file, and a :file:`webserver.yml` file.
261 
+
262 
+Below are the contents of the :file:`webserver.yml` file:
263 
+
264 
+.. code-block:: bash
265 
+
266 
+    # from github
267 
+    - src: https://github.com/bennojoy/nginx
268 
+
269 
+    # from Bitbucket
270 
+    - src: git+http://bitbucket.org/willthames/git-ansible-galaxy
271 
+      version: v1.4
272 
+
273 
+The following shows the contents of the :file:`requirements.yml` file that now includes the :file:`webserver.yml` file:
274 
+
275 
+.. code-block:: bash
276 
+
277 
+  # from galaxy
278 
+  - src: yatesr.timezone
279 
+  - include: <path_to_requirements>/webserver.yml
280 
+
281 
+To install all the roles from both files, pass the root file, in this case :file:`requirements.yml` on the
282 
+command line, as follows:
283 
+
284 
+.. code-block:: bash
285 
+
286 
+    $ ansible-galaxy install -r requirements.yml
287 
+
288 
+.. _galaxy_dependencies:
289 
+
290 
+Dependencies
291 
+------------
292 
+
293 
+Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependencies will automatically be installed.
294 
+
295 
+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
296 
+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``.
297 
+
298 
+The following shows an example ``meta/main.yml`` file with dependent roles:
299 
+
300 
+.. code-block:: yaml
301 
+
302 
+    ---
303 
+    dependencies:
304 
+      - geerlingguy.java
305 
+
306 
+    galaxy_info:
307 
+      author: geerlingguy
308 
+      description: Elasticsearch for Linux.
309 
+      company: "Midwestern Mac, LLC"
310 
+      license: "license (BSD, MIT)"
311 
+      min_ansible_version: 2.4
312 
+      platforms:
313 
+      - name: EL
314 
+        versions:
315 
+        - all
316 
+      - name: Debian
317 
+        versions:
318 
+        - all
319 
+      - name: Ubuntu
320 
+        versions:
321 
+        - all
322 
+      galaxy_tags:
323 
+        - web
324 
+        - system
325 
+        - monitoring
326 
+        - logging
327 
+        - lucene
328 
+        - elk
329 
+        - elasticsearch
330 
+
331 
+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.
332 
+
333 
+Roles listed as dependencies are subject to conditionals and tag filtering, and may not execute fully depending on
334 
+what tags and conditionals are applied.
335 
+
336 
+If the source of a role is Galaxy, specify the role in the format *namespace.role_name*:
337 
+
338 
+.. code-block:: yaml
339 
+
340 
+    dependencies:
341 
+      - geerlingguy.apache
342 
+      - geerlingguy.ansible
343 
+
344 
+
345 
+Alternately, you can specify the role dependencies in the complex form used in  :file:`requirements.yml` as follows:
346 
+
347 
+.. code-block:: yaml
348 
+
349 
+    dependencies:
350 
+      - src: geerlingguy.ansible
351 
+      - src: git+https://github.com/geerlingguy/ansible-role-composer.git
352 
+        version: 775396299f2da1f519f0d8885022ca2d6ee80ee8
353 
+        name: composer
354 
+
355 
+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`.
356 
+
357 
+.. note::
358 
+
359 
+    Galaxy expects all role dependencies to exist in Galaxy, and therefore dependencies to be specified in the
360 
+    ``namespace.role_name`` format. If you import a role with a dependency where the ``src`` value is a URL, the import process will fail.
361 
+
362 
+List installed roles
363 
+--------------------
364 
+
365 
+Use ``list`` to show the name and version of each role installed in the *roles_path*.
366 
+
367 
+.. code-block:: bash
368 
+
369 
+    $ ansible-galaxy list
370 
+      - ansible-network.network-engine, v2.7.2
371 
+      - ansible-network.config_manager, v2.6.2
372 
+      - ansible-network.cisco_nxos, v2.7.1
373 
+      - ansible-network.vyos, v2.7.3
374 
+    - ansible-network.cisco_ios, v2.7.0
375 
+
376 
+Remove an installed role
377 
+------------------------
378 
+
379 
+Use ``remove`` to delete a role from *roles_path*:
380 
+
381 
+.. code-block:: bash
382 
+
383 
+    $ ansible-galaxy remove namespace.role_name
384 
+
385 
+
386 
+.. seealso::
387 
+  `collections <collections>`_
388 
+    Sharable collections of modules, playbooks and roles
389 
+  `roles <playbooks_reuse_roles>`_
390 
+    Reusable tasks, handlers, and other files in a known directory structure
docs/docsite/rst/galaxy/user_guide/finding_collections.rst
History View file @ b80ca85
0 391 
deleted file mode 100644
... ... 
@@ -1,14 +0,0 @@
1 
-
2 
-.. _finding_galaxy_collections:
3 
-
4 
-*****************************
5 
-Finding collections on Galaxy
6 
-*****************************
7 
-
8 
-To find collections on Galaxy:
9 
-
10 
-#. Click the :guilabel:`Search` icon in the left-hand navigation.
11 
-#. Set the filter to *collection*.
12 
-#. Set other filters and press *enter*.
13 
-
14 
-Galaxy presents a list of collections that match your search criteria.
docs/docsite/rst/galaxy/user_guide/finding_roles.rst
History View file @ b80ca85
15 1 
deleted file mode 100644
... ... 
@@ -1,66 +0,0 @@
1 
-
2 
-.. _finding_galaxy_roles:
3 
-
4 
-*************************
5 
-Finding roles on Galaxy
6 
-*************************
7 
-
8 
-Search the Galaxy database by tags, platforms, author and multiple keywords. For example:
9 
-
10 
-.. code-block:: bash
11 
-
12 
-    $ ansible-galaxy search elasticsearch --author geerlingguy
13 
-
14 
-The search command will return a list of the first 1000 results matching your search:
15 
-
16 
-.. code-block:: text
17 
-
18 
-    Found 2 roles matching your search:
19 
-
20 
-    Name                              Description
21 
-    ----                              -----------
22 
-    geerlingguy.elasticsearch         Elasticsearch for Linux.
23 
-    geerlingguy.elasticsearch-curator Elasticsearch curator for Linux.
24 
-
25 
-
26 
-Get more information about a role
27 
-=================================
28 
-
29 
-Use the ``info`` command to view more detail about a specific role:
30 
-
31 
-.. code-block:: bash
32 
-
33 
-    $ ansible-galaxy info username.role_name
34 
-
35 
-This returns everything found in Galaxy for the role:
36 
-
37 
-.. code-block:: text
38 
-
39 
-    Role: username.role_name
40 
-        description: Installs and configures a thing, a distributed, highly available NoSQL thing.
41 
-        active: True
42 
-        commit: c01947b7bc89ebc0b8a2e298b87ab416aed9dd57
43 
-        commit_message: Adding travis
44 
-        commit_url: https://github.com/username/repo_name/commit/c01947b7bc89ebc0b8a2e298b87ab
45 
-        company: My Company, Inc.
46 
-        created: 2015-12-08T14:17:52.773Z
47 
-        download_count: 1
48 
-        forks_count: 0
49 
-        github_branch:
50 
-        github_repo: repo_name
51 
-        github_user: username
52 
-        id: 6381
53 
-        is_valid: True
54 
-        issue_tracker_url:
55 
-        license: Apache
56 
-        min_ansible_version: 1.4
57 
-        modified: 2015-12-08T18:43:49.085Z
58 
-        namespace: username
59 
-        open_issues_count: 0
60 
-        path: /Users/username/projects/roles
61 
-        scm: None
62 
-        src: username.repo_name
63 
-        stargazers_count: 0
64 
-        travis_status_url: https://travis-ci.org/username/repo_name.svg?branch=master
65 
-        version:
66 
-        watchers_count: 1
docs/docsite/rst/galaxy/user_guide/index.rst
History View file @ b80ca85
67 1 
deleted file mode 100644
... ... 
@@ -1,26 +0,0 @@
1 
-.. _using_galaxy:
2 
-.. _ansible_galaxy:
3 
-
4 
-**********
5 
-User Guide
6 
-**********
7 
-
8 
-:dfn:`Ansible Galaxy` refers to the `Galaxy <https://galaxy.ansible.com>`_  website, a free site for finding, downloading, and sharing community developed roles.
9 
-
10 
-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>`_.
11 
-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.
12 
-
13 
-.. toctree::
14 
-   :maxdepth: 2
15 
-
16 
-   finding_collections
17 
-   finding_roles
18 
-   installing_collections
19 
-   installing_roles
20 
-
21 
-
22 
-.. seealso::
23 
-  `collections <collections>`_
24 
-    Sharable collections of modules, playbooks and roles
25 
-  `roles <playbooks_reuse_roles>`_
26 
-    Reusable tasks, handlers, and other files in a known directory structure
docs/docsite/rst/galaxy/user_guide/installing_collections.rst
History View file @ b80ca85
27 1 
deleted file mode 100644
... ... 
@@ -1,22 +0,0 @@
1 
-.. _installing_galaxy_collections:
2 
-
3 
-Installing collections from Galaxy
4 
-==================================
5 
-
6 
-.. include:: ../../shared_snippets/installing_collections.txt
7 
-
8 
-
9 
-Installing an older version of a collection
10 
-
11 
-.. include:: ../../shared_snippets/installing_older_collection.txt
12 
-
13 
-Install multiple collections with a requirements file
14 
-
15 
-.. include:: ../../shared_snippets/installing_multiple_collections.txt
16 
-
17 
-Galaxy server configuration list
18 
-
19 
-.. include:: ../../shared_snippets/galaxy_server_list.txt
docs/docsite/rst/galaxy/user_guide/installing_roles.rst
History View file @ b80ca85
20 1 
deleted file mode 100644
... ... 
@@ -1,218 +0,0 @@
1 
-Installing roles from Galaxy
2 
-============================
3 
-
4 
-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
5 
-also use it to create a new role, remove roles, or perform tasks on the Galaxy website.
6 
-
7 
-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>`_
8 
-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
9 
-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`.
10 
-
11 
-
12 
-Installing Roles
13 
-
14 
-Use the ``ansible-galaxy`` command to download roles from the `Galaxy website <https://galaxy.ansible.com>`_
15 
-
16 
-.. code-block:: bash
17 
-
18 
-  $ ansible-galaxy install username.role_name
19 
-
20 
-roles_path
21 
-^^^^^^^^^^
22 
-
23 
-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``.
24 
-
25 
-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.
26 
-
27 
-The following provides an example of using ``--roles-path`` to install the role into the current working directory:
28 
-
29 
-.. code-block:: bash
30 
-
31 
-    $ ansible-galaxy install --roles-path . geerlingguy.apache
32 
-
33 
-.. seealso::
34 
-
35 
-   :ref:`intro_configuration`
36 
-      All about configuration files
37 
-
38 
-Installing a specific version of a role
39 
-
40 
-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:
41 
-
42 
-.. code-block:: bash
43 
-
44 
-   $ ansible-galaxy install geerlingguy.apache,v1.0.0
45 
-
46 
-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
47 
-install a specific commit:
48 
-
49 
-.. code-block:: bash
50 
-
51 
-   $ ansible-galaxy install git+https://github.com/geerlingguy/ansible-role-apache.git,0b7cd353c0250e87a26e0499e59e7fd265cc2f25
52 
-
53 
-
54 
-Installing multiple roles from a file
55 
-
56 
-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
57 
-file extension must be either *.yml* or *.yaml*.
58 
-
59 
-Use the following command to install roles included in *requirements.yml*:
60 
-
61 
-.. code-block:: bash
62 
-
63 
-    $ ansible-galaxy install -r requirements.yml
64 
-
65 
-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,
66 
-"basic" format.
67 
-
68 
-Each role in the file will have one or more of the following attributes:
69 
-
70 
-   src
71 
-     The source of the role. Use the format *username.role_name*, if downloading from Galaxy; otherwise, provide a URL pointing
72 
-     to a repository within a git based SCM. See the examples below. This is a required attribute.
73 
-   scm
74 
-     Specify the SCM. As of this writing only *git* or *hg* are allowed. See the examples below. Defaults to *git*.
75 
-   version:
76 
-     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*.
77 
-   name:
78 
-     Download the role to a specific name. Defaults to the Galaxy name when downloading from Galaxy, otherwise it defaults
79 
-     to the name of the repository.
80 
-
81 
-Use the following example as a guide for specifying roles in *requirements.yml*:
82 
-
83 
-.. code-block:: text
84 
-
85 
-    # from galaxy
86 
-    - src: yatesr.timezone
87 
-
88 
-    # from GitHub
89 
-    - src: https://github.com/bennojoy/nginx
90 
-
91 
-    # from GitHub, overriding the name and specifying a specific tag
92 
-    - src: https://github.com/bennojoy/nginx
93 
-      version: master
94 
-      name: nginx_role
95 
-
96 
-    # from a webserver, where the role is packaged in a tar.gz
97 
-    - src: https://some.webserver.example.com/files/master.tar.gz
98 
-      name: http-role-gz
99 
-
100 
-    # from a webserver, where the role is packaged in a tar.bz2
101 
-    - src: https://some.webserver.example.com/files/master.tar.bz2
102 
-      name: http-role-bz2
103 
-
104 
-    # from a webserver, where the role is packaged in a tar.xz (Python 3.x only)
105 
-    - src: https://some.webserver.example.com/files/master.tar.xz
106 
-      name: http-role-xz
107 
-
108 
-    # from Bitbucket
109 
-    - src: git+https://bitbucket.org/willthames/git-ansible-galaxy
110 
-      version: v1.4
111 
-
112 
-    # from Bitbucket, alternative syntax and caveats
113 
-    - src: https://bitbucket.org/willthames/hg-ansible-galaxy
114 
-      scm: hg
115 
-
116 
-    # from GitLab or other git-based scm, using git+ssh
117 
-    - src: git@gitlab.company.com:mygroup/ansible-base.git
118 
-      scm: git
119 
-      version: "0.1"  # quoted, so YAML doesn't parse this as a floating-point value
120 
-
121 
-Installing multiple roles from multiple files
122 
-
123 
-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.
124 
-
125 
-Use the following command to install roles includes in *requirements.yml*  + *webserver.yml*
126 
-
127 
-.. code-block:: bash
128 
-
129 
-    ansible-galaxy install -r requirements.yml
130 
-
131 
-Content of the *requirements.yml* file:
132 
-
133 
-.. code-block:: text
134 
-
135 
-    # from galaxy
136 
-    - src: yatesr.timezone
137 
-
138 
-    - include: <path_to_requirements>/webserver.yml
139 
-
140 
-
141 
-Content of the *webserver.yml* file:
142 
-
143 
-.. code-block:: text
144 
-
145 
-    # from github
146 
-    - src: https://github.com/bennojoy/nginx
147 
-
148 
-    # from Bitbucket
149 
-    - src: git+https://bitbucket.org/willthames/git-ansible-galaxy
150 
-      version: v1.4
151 
-
152 
-.. _galaxy_dependencies:
153 
-
154 
-Dependencies
155 
-
156 
-Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependencies will automatically be installed.
157 
-
158 
-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
159 
-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``.
160 
-
161 
-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.
162 
-
163 
-Roles listed as dependencies are subject to conditionals and tag filtering, and may not execute fully depending on
164 
-what tags and conditionals are applied.
165 
-
166 
-Dependencies found in Galaxy can be specified as follows:
167 
-
168 
-.. code-block:: text
169 
-
170 
-    dependencies:
171 
-      - geerlingguy.apache
172 
-      - geerlingguy.ansible
173 
-
174 
-
175 
-The complex form can also be used as follows:
176 
-
177 
-.. code-block:: text
178 
-
179 
-    dependencies:
180 
-      - src: geerlingguy.ansible
181 
-      - src: git+https://github.com/geerlingguy/ansible-role-composer.git
182 
-        version: 775396299f2da1f519f0d8885022ca2d6ee80ee8
183 
-        name: composer
184 
-
185 
-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`.
186 
-
187 
-.. note::
188 
-
189 
-    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
190 
-    ``username.role_name`` format. If you import a role with a dependency where the ``src`` value is a URL, the import process will fail.
191 
-
192 
-List installed roles
193 
-
194 
-Use ``list`` to show the name and version of each role installed in the *roles_path*.
195 
-
196 
-.. code-block:: bash
197 
-
198 
-    $ ansible-galaxy list
199 
-
200 
-    - chouseknecht.role-install_mongod, master
201 
-    - chouseknecht.test-role-1, v1.0.2
202 
-    - chrismeyersfsu.role-iptables, master
203 
-    - chrismeyersfsu.role-required_vars, master
204 
-
205 
-Remove an installed role
206 
-
207 
-Use ``remove`` to delete a role from *roles_path*:
208 
-
209 
-.. code-block:: bash
210 
-
211 
-    $ ansible-galaxy remove username.role_name
docs/docsite/rst/index.rst
History View file @ b80ca85
... ... 
@@ -64,8 +64,8 @@ Ansible releases a new major release of Ansible approximately three to four time
64 64 
    :maxdepth: 2
65 65 
    :caption: Ansible Galaxy
66 66
67 
-   galaxy/user_guide/index
68 
-   galaxy/dev_guide/index
67 
+   galaxy/user_guide.rst
68 
+   galaxy/dev_guide.rst
69 69
70 70
71 71 
 .. toctree::
docs/docsite/rst/user_guide/playbooks_environment.rst
History View file @ b80ca85
... ... 
@@ -5,11 +5,11 @@ Setting the Environment (and Working With Proxies)
5 5
6 6 
 .. versionadded:: 1.1
7 7
8 
-It is quite possible that you may need to get package updates through a proxy, or even get some package
9 
-updates through a proxy and access other packages not through a proxy.  Or maybe a script you might wish to
10 
-call may also need certain environment variables set to run properly.
8 
+The ``environment`` keyword allows you to set an environment varaible for the action to be taken on the remote target.
9 
+For example, it is quite possible that you may need to set a proxy for a task that does http requests.
10 
+Or maybe a utility or script that are called may also need certain environment variables set to run properly.
11 11
12 
-Ansible makes it easy for you to configure the remote execution environment by using the 'environment' keyword.  Here is an example::
12 
+Here is an example::
13 13
14 14 
     - hosts: all
15 15 
       remote_user: root
... ... 
@@ -23,6 +23,10 @@ Ansible makes it easy for you to configure the remote execution environment by u
23 23 
           environment:
24 24 
             http_proxy: http://proxy.example.com:8080
25 25
26 
+.. note::
27 
+   ``environment:`` does not affect Ansible itself, ONLY the context of the specific task action and this does not include
28 
+    Ansible's own configuration settings nor the execution of any other plugins, including lookups, filters, and so on.
29 
+
26 30 
 The environment can also be stored in a variable, and accessed like so::
27 31
28 32 
     - hosts: all
... ... 
@@ -104,6 +108,10 @@ Some language-specific version managers (such as rbenv and nvm) require environm
104 104 
           path: '{{ node_app_dir }}'
105 105 
         when: packagejson.stat.exists
106 106
107 
+.. note::
108 
+   ``ansible_env:`` is normally populated by fact gathering (M(gather_facts)) and the value of the variables depends on the user
109 
+   that did the gathering action. If you change remote_user/become_user you might end up using the wrong values for those variables.
110 
+
107 111 
 You might also want to simply specify the environment for a single task::
108 112
109 113 
     ---
... ... 
@@ -119,9 +127,6 @@ You might also want to simply specify the environment for a single task::
119 119 
         RBENV_ROOT: '{{ rbenv_root }}'
120 120 
         PATH: '{{ rbenv_root }}/bin:{{ rbenv_root }}/shims:{{ rbenv_plugins }}/ruby-build/bin:{{ ansible_env.PATH }}'
121 121
122 
-.. note::
123 
-   ``environment:`` does not affect Ansible itself, ONLY the context of the specific task action and this does not include Ansible's own configuration settings.
124 
-
125 122 
 .. seealso::
126 123
127 124 
    :ref:`playbooks_intro`
docs/docsite/rst/user_guide/playbooks_variables.rst
History View file @ b80ca85
... ... 
@@ -1044,7 +1044,7 @@ Basically, anything that goes into "role defaults" (the defaults folder inside t
1044 1044 
           If you define a variable twice in a play's ``vars:`` section, the second one wins.
1045 1045 
 .. note:: The previous describes the default config ``hash_behaviour=replace``, switch to ``merge`` to only partially overwrite.
1046 1046 
 .. note:: Group loading follows parent/child relationships. Groups of the same 'parent/child' level are then merged following alphabetical order.
1047 
-          This last one can be superceeded by the user via ``ansible_group_priority``, which defaults to ``1`` for all groups.
1047 
+          This last one can be superseded by the user via ``ansible_group_priority``, which defaults to ``1`` for all groups.
1048 1048 
           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/.
1049 1049
1050 1050 
 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::
docs/docsite/rst/user_guide/windows_winrm.rst
History View file @ b80ca85
... ... 
@@ -818,7 +818,7 @@ The below Ansible tasks can also be used to enable TLS v1.2:
818 818 
         data: '{{ item.value }}'
819 819 
         type: dword
820 820 
         state: present
821 
-        register: enable_tls12
821 
+      register: enable_tls12
822 822 
       loop:
823 823 
       - type: Server
824 824 
         property: Enabled
lib/ansible/modules/cloud/amazon/aws_batch_compute_environment.py
History View file @ b80ca85
... ... 
@@ -151,9 +151,11 @@ EXAMPLES = '''
151 151 
         tag1: value1
152 152 
         tag2: value2
153 153 
       service_role: arn:aws:iam::<account>:role/service-role/<role>
154 
+    register: aws_batch_compute_environment_action
154 155
155 156 
   - name: show results
156 
-    debug: var=aws_batch_compute_environment_action
157 
+    debug:
158 
+      var: aws_batch_compute_environment_action
157 159 
 '''
158 160
159 161 
 RETURN = '''
lib/ansible/modules/cloud/amazon/aws_batch_job_queue.py
History View file @ b80ca85
... ... 
@@ -67,7 +67,7 @@ EXAMPLES = '''
67 67 
     state: present
68 68 
   tasks:
69 69 
   - name: My Batch Job Queue
70 
-    batch_job_queue:
70 
+    aws_batch_job_queue:
71 71 
       job_queue_name: jobQueueName
72 72 
       state: present
73 73 
       region: us-east-1
... ... 
@@ -78,9 +78,11 @@ EXAMPLES = '''
78 78 
           compute_environment: my_compute_env1
79 79 
         - order: 2
80 80 
           compute_environment: my_compute_env2
81 
+    register: batch_job_queue_action
81 82
82 83 
   - name: show results
83 
-    debug: var=batch_job_queue_action
84 
+    debug:
85 
+      var: batch_job_queue_action
84 86 
 '''
85 87
86 88 
 RETURN = '''
lib/ansible/modules/cloud/amazon/ec2_launch_template.py
History View file @ b80ca85
... ... 
@@ -44,10 +44,8 @@ options:
44 44 
     default: latest
45 45 
   state:
46 46 
     description:
47 
-    - Whether the launch template should exist or not. To delete only a
48 
-      specific version of a launch template, combine I(state=absent) with
49 
-      the I(version) option. By default, I(state=absent) will remove all
50 
-      versions of the template.
47 
+    - Whether the launch template should exist or not.
48 
+    - Deleting specific versions of a launch template is not supported at this time.
51 49 
     choices: [present, absent]
52 50 
     default: present
53 51 
   block_device_mappings:
lib/ansible/modules/cloud/amazon/elb_application_lb_info.py
History View file @ b80ca85
... ... 
@@ -57,7 +57,8 @@ EXAMPLES = '''
57 57 
     names: "alb-name"
58 58 
     region: "aws-region"
59 59 
   register: alb_info
60 
-- debug: var=alb_info
60 
+- debug:
61 
+    var: alb_info
61 62 
 '''
62 63
63 64 
 RETURN = '''
lib/ansible/modules/cloud/amazon/lambda_policy.py
History View file @ b80ca85
... ... 
@@ -111,9 +111,11 @@ EXAMPLES = '''
111 111 
       principal: s3.amazonaws.com
112 112 
       source_arn: arn:aws:s3:eu-central-1:123456789012:bucketName
113 113 
       source_account: 123456789012
114 
+    register: lambda_policy_action
114 115
115 116 
   - name: show results
116 
-    debug: var=lambda_policy_action
117 
+    debug:
118 
+      var: lambda_policy_action
117 119
118 120 
 '''
119 121
lib/ansible/modules/files/template.py
History View file @ b80ca85
... ... 
@@ -64,7 +64,7 @@ EXAMPLES = r'''
64 64
65 65 
 - 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
66 66 
   template:
67 
-    src: named.conf_{{ ansible_os_family}}.j2
67 
+    src: named.conf_{{ ansible_os_family }}.j2
68 68 
     dest: /etc/named.conf
69 69 
     group: named
70 70 
     setype: named_conf_t
lib/ansible/modules/packaging/os/package.py
History View file @ b80ca85
... ... 
@@ -59,4 +59,11 @@ EXAMPLES = '''
59 59 
   package:
60 60 
     name: "{{ apache }}"
61 61 
     state: absent
62 
+
63 
+- name: install the latest version of Apache and MariaDB
64 
+  package:
65 
+    name:
66 
+      - httpd
67 
+      - mariadb-server
68 
+    state: latest
62 69 
 '''
lib/ansible/plugins/lookup/password.py
History View file @ b80ca85
... ... 
@@ -73,10 +73,10 @@ EXAMPLES = """
73 73 
     password: "{{ lookup('password', '/tmp/passwordfile chars=ascii_letters') }}"
74 74 
     priv: '{{ client }}_{{ tier }}_{{ role }}.*:ALL'
75 75
76 
-- name: create a mysql user with a random password using only digits
76 
+- name: create a mysql user with an 8 character random password using only digits
77 77 
   mysql_user:
78 78 
     name: "{{ client }}"
79 
-    password: "{{ lookup('password', '/tmp/passwordfile chars=digits') }}"
79 
+    password: "{{ lookup('password', '/tmp/passwordfile length=8 chars=digits') }}"
80 80 
     priv: "{{ client }}_{{ tier }}_{{ role }}.*:ALL"
81 81
82 82 
 - name: create a mysql user with a random password using many different char sets