mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
Clarify how tag inheritance works (#28942)
Fixes #20119 Another crack at PR #27147
This commit is contained in:
Sam Doran
scottb
parent
596dc8c442
commit
cc7e38890c
3 changed files with 50 additions and 42 deletions
|
|
@ -1,7 +1,7 @@
|
|||
Ansible Galaxy
|
||||
++++++++++++++
|
||||
|
||||
*Ansible Galaxy* refers to the `Galaxy <https://galaxy.ansible.com>`_ website where users can share roles, and to a command line tool for installing,
|
||||
*Ansible Galaxy* refers to the `Galaxy <https://galaxy.ansible.com>`_ website where users can share roles, and to a command line tool for installing,
|
||||
creating and managing roles.
|
||||
|
||||
.. contents:: Topics
|
||||
|
|
@ -9,11 +9,11 @@ creating and managing roles.
|
|||
The Website
|
||||
```````````
|
||||
|
||||
`Galaxy <https://galaxy.ansible.com>`_, is a free site for finding, downloading, and sharing community developed roles. Downloading roles from Galaxy is
|
||||
`Galaxy <https://galaxy.ansible.com>`_, is a free site for finding, downloading, and sharing community developed roles. Downloading roles from Galaxy is
|
||||
a great way to jumpstart your automation projects.
|
||||
|
||||
You can also use the site to share roles that you create. By authenticating with the site using your GitHub account, you're able to *import* roles, making
|
||||
them available to the Ansible community. Imported roles become available in the Galaxy search index and visible on the site, allowing users to
|
||||
You can also use the site to share roles that you create. By authenticating with the site using your GitHub account, you're able to *import* roles, making
|
||||
them available to the Ansible community. Imported roles become available in the Galaxy search index and visible on the site, allowing users to
|
||||
discover and download them.
|
||||
|
||||
Learn more by viewing `the About page <https://galaxy.ansible.com/intro>`_.
|
||||
|
|
@ -21,7 +21,7 @@ Learn more by viewing `the About page <https://galaxy.ansible.com/intro>`_.
|
|||
The command line tool
|
||||
`````````````````````
|
||||
|
||||
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
|
||||
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>`_
|
||||
|
|
@ -55,7 +55,7 @@ The following provides an example of using *--roles-path* to install the role in
|
|||
.. seealso::
|
||||
|
||||
:doc:`intro_configuration`
|
||||
All about configuration files
|
||||
All about configuration files
|
||||
|
||||
version
|
||||
=======
|
||||
|
|
@ -64,7 +64,7 @@ You can install a specific version of a role from Galaxy by appending a comma an
|
|||
|
||||
::
|
||||
|
||||
$ ansible-galaxy install geerlingguy.apache,v1.0.0
|
||||
$ 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:
|
||||
|
|
@ -77,7 +77,7 @@ install a specific commit:
|
|||
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
|
||||
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*:
|
||||
|
|
@ -93,14 +93,14 @@ 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.
|
||||
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 supported. See the examples below. Defaults to *git*.
|
||||
Specify the SCM. As of this writing only *git* or *hg* are supported. 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 *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.
|
||||
to the name of the repository.
|
||||
|
||||
Use the following example as a guide for specifying roles in *requirements.yml*:
|
||||
|
||||
|
|
@ -116,7 +116,7 @@ Use the following example as a guide for specifying roles in *requirements.yml*:
|
|||
- 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
|
||||
|
|
@ -128,7 +128,7 @@ Use the following example as a guide for specifying roles in *requirements.yml*:
|
|||
# from Bitbucket, alternative syntax and caveats
|
||||
- src: http://bitbucket.org/willthames/hg-ansible-galaxy
|
||||
scm: hg
|
||||
|
||||
|
||||
# from GitLab or other git-based scm
|
||||
- src: git@gitlab.company.com:mygroup/ansible-base.git
|
||||
scm: git
|
||||
|
|
@ -171,35 +171,39 @@ Dependencies
|
|||
|
||||
Roles can also be dependent on other roles, and when you install a role that has dependencies, those dependenices 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*. The more complex format used in *requirements.yml* is also supported, allowing you to provide src, scm, version and name.
|
||||
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``. The more complex format used in ``requirements.yml`` is also supported, 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 depeneding on
|
||||
what tags and conditinoals are applied.
|
||||
|
||||
Dependencies found in Galaxy can be specified as follows:
|
||||
|
||||
::
|
||||
::
|
||||
|
||||
dependencies:
|
||||
- geerlingguy.apache
|
||||
- geerlingguy.apache
|
||||
- geerlingguy.ansible
|
||||
|
||||
|
||||
The complex form can also be used as follows:
|
||||
The complex form can also be used as follows:
|
||||
|
||||
::
|
||||
|
||||
dependencies:
|
||||
- src: geerlingguy.ansible
|
||||
- src: git+https://github.com/geerlingguy/ansible-role-composer.git
|
||||
- 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 :doc:`playbooks_reuse_roles`.
|
||||
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 :doc:`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.
|
||||
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.
|
||||
|
||||
Create roles
|
||||
------------
|
||||
|
|
@ -211,7 +215,7 @@ Use the ``init`` command to initialize the base structure of a new role, saving
|
|||
$ ansible-galaxy init role_name
|
||||
|
||||
The above will create the following directory structure in the current working directory:
|
||||
|
||||
|
||||
::
|
||||
|
||||
README.md
|
||||
|
|
@ -233,7 +237,7 @@ The above will create the following directory structure in the current working d
|
|||
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
|
||||
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
|
||||
|
|
@ -279,7 +283,7 @@ Search the Galaxy database by tags, platforms, author and multiple keywords. For
|
|||
The search command will return a list of the first 1000 results matching your search:
|
||||
|
||||
::
|
||||
|
||||
|
||||
Found 2 roles matching your search:
|
||||
|
||||
Name Description
|
||||
|
|
@ -358,7 +362,7 @@ 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.
|
||||
can be used to do just that. Before you can use the ``login`` command, you must create an account on the Galaxy website.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -378,11 +382,11 @@ The following shows authenticating with the Galaxy website using a GitHub userna
|
|||
Password for dsmith:
|
||||
Successfully logged into Galaxy as dsmith
|
||||
|
||||
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.
|
||||
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.
|
||||
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
|
||||
destroyed.
|
||||
destroyed.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
|
||||
|
|
@ -390,7 +394,7 @@ 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.
|
||||
been granted access.
|
||||
|
||||
Use the following to import to role:
|
||||
|
||||
|
|
@ -449,20 +453,20 @@ 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 <http://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.
|
||||
You can create an integration or connection between a role in Galaxy and `Travis <http://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.
|
||||
|
||||
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
|
||||
also need an account in Travis, and your Travis token. Once you're ready, use the following command to create the integration:
|
||||
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
|
||||
also need an account in Travis, and your Travis token. Once you're ready, use the following command to create the integration:
|
||||
|
||||
::
|
||||
|
||||
$ ansible-galaxy setup travis github_user github_repo xxx-travis-token-xxx
|
||||
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
`Travis getting started guide <https://docs.travis-ci.com/user/getting-started/>`_.
|
||||
|
||||
To instruct Travis to notify Galaxy when a build completes, add the following to your .travis.yml file:
|
||||
|
|
|
|||
|
|
@ -83,7 +83,7 @@ When used in this manner, the order of execution for your playbook is as follows
|
|||
|
||||
- Any ``pre_tasks`` defined in the play.
|
||||
- Any handlers triggered so far will be run.
|
||||
- Each role listed in ``roles`` will execute in turn. Any role dependencies defined in the roles ``meta/main.yml`` will be run first.
|
||||
- Each role listed in ``roles`` will execute in turn. Any role dependencies defined in the roles ``meta/main.yml`` will be run first, subject to tag filtering and conditionals.
|
||||
- Any ``tasks`` defined in the play.
|
||||
- Any handlers triggered so far will be run.
|
||||
- Any ``post_tasks`` defined in the play.
|
||||
|
|
@ -93,7 +93,7 @@ When used in this manner, the order of execution for your playbook is as follows
|
|||
See below for more information regarding role dependencies.
|
||||
|
||||
.. note::
|
||||
If using tags with tasks (described later as a means of only running part of a playbook), be sure to also tag your pre_tasks and post_tasks and pass those along as well, especially if the pre and post tasks are used for monitoring outage window control or load balancing.
|
||||
If using tags with tasks (described later as a means of only running part of a playbook), be sure to also tag your pre_tasks, post_tasks, and role dependencies and pass those along as well, especially if the pre/post tasks and role dependencies are used for monitoring outage window control or load balancing.
|
||||
|
||||
As of Ansible 2.4, you can now use roles inline with any other tasks using ``import_role`` or ``include_role``::
|
||||
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ On the other hand, if you want to run a playbook *without* certain tasks, you co
|
|||
|
||||
Tag Reuse
|
||||
```````````````
|
||||
You can apply the same tag name to more than one task, in the same file
|
||||
You can apply the same tag name to more than one task, in the same file
|
||||
or included files. This will run all tasks with that tag.
|
||||
|
||||
Example::
|
||||
|
|
@ -62,8 +62,7 @@ Example::
|
|||
Tag Inheritance
|
||||
```````````````
|
||||
|
||||
You can apply tags to more than tasks, but they ONLY affect the tasks themselves. Applying tags anywhere else is just a
|
||||
convenience so you don't have to write it on every task::
|
||||
You can apply tags to more than tasks, but they ONLY affect the tasks themselves. Applying tags anywhere else is just a convenience so you don't have to write it on every task::
|
||||
|
||||
- hosts: all
|
||||
tags:
|
||||
|
|
@ -90,6 +89,11 @@ All of these apply the specified tags to EACH task inside the play, included
|
|||
file, or role, so that these tasks can be selectively run when the playbook
|
||||
is invoked with the corresponding tags.
|
||||
|
||||
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.
|
||||
|
||||
You can see which tags are applied to tasks by running ``ansible-playbook`` with the ``--list-tasks`` option. You can display all tags using the ``--list-tags`` option.
|
||||
|
||||
.. _special_tags:
|
||||
|
||||
Special Tags
|
||||
|
|
|
|||
Loading…
Reference in a new issue