[2.10] Docsite backport 71909, 71859, 71858, 71857, 71854, 71834 (#71937)
* Docsite: improve user_guide/intro_inventory (#71859) (cherry picked from commit25bfda8417) * Docsite: improve user_guide/playbooks_tags (#71858) (cherry picked from commitc3841b8440) * Docsite: improve user_guide/playbooks_reuse_roles (#71857) * Docsite: improve user_guide/playbooks_reuse_roles * fix (cherry picked from commit7a0a2f188b) * Docsite: update Migrating Ansible content to a different collection (#71854) Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit2655fc0c23) * Docsite: improve user_guide/intro_adhoc (#71909) (cherry picked from commited6fb2e3f6) * Docsite: improve user_guide/playbooks_reuse (#71834) (cherry picked from commit3db4be2c3b)
This commit is contained in:
Andrew Klychkov
GitHub
parent
5fc0dc1956
commit
5282ab853d
6 changed files with 166 additions and 138 deletions
|
|
@ -534,17 +534,41 @@ Migrating Ansible content to a different collection
|
|||
|
||||
First, look at `Ansible Collection Checklist <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_.
|
||||
|
||||
To migrate content from one collection to another, you need to create three PRs as follows:
|
||||
To migrate content from one collection to another, if the collections are parts of `Ansible distribution <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible.in>`_:
|
||||
|
||||
#. Create a PR against the old collection to remove the content.
|
||||
#. Create a PR against the new collection to add the files removed in step 1.
|
||||
#. Update the ``ansible/ansible:devel`` branch entries for all files moved.
|
||||
#. Copy content from the source (old) collection to the target collection.
|
||||
#. Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the source collection. The deprecation must be released after the copied content has been included in a release of the target collection.
|
||||
#. When the next major release comes:
|
||||
|
||||
* remove the module/plugin from the source collection
|
||||
* add ``redirect`` to the corresponding entry in ``meta/runtime.yml``
|
||||
* remove ``removal_version`` from there
|
||||
|
||||
According to the above, you need to create at least three PRs as follows:
|
||||
|
||||
#. Create a PR against the target collection to copy the content.
|
||||
#. Deprecate the module/plugin in the source collection.
|
||||
#. Later create a PR against the source collection to remove the content according to the schedule.
|
||||
|
||||
|
||||
Adding the content to the new collection
|
||||
----------------------------------------
|
||||
|
||||
Create a PR in the new collection to:
|
||||
|
||||
#. Copy ALL the related files from the old collection.
|
||||
#. If it is an action plugin, include the corresponding module with documentation.
|
||||
#. If it is a module, check if it has a corresponding action plugin that should move with it.
|
||||
#. Check ``meta/`` for relevant updates to ``runtime.yml`` if it exists.
|
||||
#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN.
|
||||
#. Review ``tests/sanity/ignore-*.txt`` entries in the old collection.
|
||||
#. Update ``meta/runtime.yml`` in the old collection.
|
||||
|
||||
|
||||
Removing the content from the old collection
|
||||
----------------------------------------------
|
||||
--------------------------------------------
|
||||
|
||||
Create a PR against the old collection repo to remove the modules, module_utils, plugins, and docs_fragments related to this migration:
|
||||
Create a PR against the source collection repository to remove the modules, module_utils, plugins, and docs_fragments related to this migration:
|
||||
|
||||
#. If you are removing an action plugin, remove the corresponding module that contains the documentation.
|
||||
#. If you are removing a module, remove any corresponding action plugin that should stay with it.
|
||||
|
|
@ -554,11 +578,6 @@ Create a PR against the old collection repo to remove the modules, module_utils,
|
|||
#. if you are removing from content from ``community.general`` or ``community.network``, remove entries from ``.github/BOTMETA.yml``.
|
||||
#. Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in particular deprecated entries.
|
||||
#. Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new collection name.
|
||||
#. If possible, do not yet add deprecation warnings to the new ``meta/runtime.yml`` entries, but only for a later major release. So the order should be:
|
||||
1. Remove content, add redirects in 3.0.0;
|
||||
2. Deprecate redirects in 4.0.0;
|
||||
3. Set removal version to 5.0.0 or later.
|
||||
|
||||
|
||||
.. warning::
|
||||
|
||||
|
|
@ -568,34 +587,15 @@ Create a PR against the old collection repo to remove the modules, module_utils,
|
|||
#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (in other words, 2.0.0, 3.0.0, and so on).
|
||||
|
||||
|
||||
Adding the content to the new collection
|
||||
-----------------------------------------
|
||||
|
||||
Create a PR in the new collection to:
|
||||
|
||||
#. Add ALL the files removed in first PR (from the old collection).
|
||||
#. If it is an action plugin, include the corresponding module with documentation.
|
||||
#. If it is a module, check if it has a corresponding action plugin that should move with it.
|
||||
#. Check ``meta/ `` for relevant updates to ``action_groups.yml`` and ``runtime.yml`` if they exist.
|
||||
#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN.
|
||||
#. Review ``tests/sanity/ignore-\*.txt`` entries.
|
||||
#. Update ``meta/runtime.yml``.
|
||||
|
||||
Updating ``ansible/ansible:devel`` branch entries for all files moved
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Create a third PR on ``ansible/ansible`` repository to:
|
||||
|
||||
#. Update ``lib/ansible/config/ansible_builtin_runtime.yml`` (the redirect entry).
|
||||
#. Update ``.github/BOTMETA.yml`` (the migrated_to entry)
|
||||
|
||||
BOTMETA.yml
|
||||
-----------
|
||||
|
||||
The `BOTMETA.yml <https://github.com/ansible/ansible/blob/devel/.github/BOTMETA.yml>`_ in the ansible/ansible GitHub repository is the source of truth for:
|
||||
The ``BOTMETA.yml``, for example in `community.general collection repository <https://github.com/ansible-collections/community.general/blob/main/.github/BOTMETA.yml>`_, is the source of truth for:
|
||||
|
||||
* ansibullbot
|
||||
|
||||
If the old and/or new collection has ``ansibullbot``, its ``BOTMETA.yml`` must be updated correspondingly.
|
||||
|
||||
Ansibulbot will know how to redirect existing issues and PRs to the new repo.
|
||||
The build process for docs.ansible.com will know where to find the module docs.
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ achieve a form of idempotence by checking the current state before they begin an
|
|||
Rebooting servers
|
||||
-----------------
|
||||
|
||||
The default module for the ``ansible`` command-line utility is the :ref:`command module<command_module>`. You can use an ad-hoc task to call the command module and reboot all web servers in Atlanta, 10 at a time. Before Ansible can do this, you must have all servers in Atlanta listed in a a group called [atlanta] in your inventory, and you must have working SSH credentials for each machine in that group. To reboot all the servers in the [atlanta] group:
|
||||
The default module for the ``ansible`` command-line utility is the :ref:`ansible.builtin.command module<command_module>`. You can use an ad-hoc task to call the command module and reboot all web servers in Atlanta, 10 at a time. Before Ansible can do this, you must have all servers in Atlanta listed in a group called [atlanta] in your inventory, and you must have working SSH credentials for each machine in that group. To reboot all the servers in the [atlanta] group:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -62,11 +62,11 @@ If you add ``--ask-become-pass`` or ``-K``, Ansible prompts you for the password
|
|||
syntax, use the `shell` module instead. Read more about the differences on the
|
||||
:ref:`working_with_modules` page.
|
||||
|
||||
So far all our examples have used the default 'command' module. To use a different module, pass ``-m`` for module name. For example, to use the :ref:`shell module <shell_module>`:
|
||||
So far all our examples have used the default 'command' module. To use a different module, pass ``-m`` for module name. For example, to use the :ref:`ansible.builtin.shell module <shell_module>`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible raleigh -m shell -a 'echo $TERM'
|
||||
$ ansible raleigh -m ansible.builtin.shell -a 'echo $TERM'
|
||||
|
||||
When running any command with the Ansible *ad hoc* CLI (as opposed to
|
||||
:ref:`Playbooks <working_with_playbooks>`), pay particular attention to shell quoting rules, so
|
||||
|
|
@ -83,29 +83,29 @@ An ad-hoc task can harness the power of Ansible and SCP to transfer many files t
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible atlanta -m copy -a "src=/etc/hosts dest=/tmp/hosts"
|
||||
$ ansible atlanta -m ansible.builtin.copy -a "src=/etc/hosts dest=/tmp/hosts"
|
||||
|
||||
If you plan to repeat a task like this, use the :ref:`template<template_module>` module in a playbook.
|
||||
If you plan to repeat a task like this, use the :ref:`ansible.builtin.template<template_module>` module in a playbook.
|
||||
|
||||
The :ref:`file<file_module>` module allows changing ownership and permissions on files. These
|
||||
The :ref:`ansible.builtin.file<file_module>` module allows changing ownership and permissions on files. These
|
||||
same options can be passed directly to the ``copy`` module as well:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible webservers -m file -a "dest=/srv/foo/a.txt mode=600"
|
||||
$ ansible webservers -m file -a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=mdehaan"
|
||||
$ ansible webservers -m ansible.builtin.file -a "dest=/srv/foo/a.txt mode=600"
|
||||
$ ansible webservers -m ansible.builtin.file -a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=mdehaan"
|
||||
|
||||
The ``file`` module can also create directories, similar to ``mkdir -p``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible webservers -m file -a "dest=/path/to/c mode=755 owner=mdehaan group=mdehaan state=directory"
|
||||
$ ansible webservers -m ansible.builtin.file -a "dest=/path/to/c mode=755 owner=mdehaan group=mdehaan state=directory"
|
||||
|
||||
As well as delete directories (recursively) and delete files:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible webservers -m file -a "dest=/path/to/c state=absent"
|
||||
$ ansible webservers -m ansible.builtin.file -a "dest=/path/to/c state=absent"
|
||||
|
||||
.. _managing_packages:
|
||||
|
||||
|
|
@ -116,25 +116,25 @@ You might also use an ad-hoc task to install, update, or remove packages on mana
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible webservers -m yum -a "name=acme state=present"
|
||||
$ ansible webservers -m ansible.builtin.yum -a "name=acme state=present"
|
||||
|
||||
To ensure a specific version of a package is installed:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible webservers -m yum -a "name=acme-1.5 state=present"
|
||||
$ ansible webservers -m ansible.builtin.yum -a "name=acme-1.5 state=present"
|
||||
|
||||
To ensure a package is at the latest version:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible webservers -m yum -a "name=acme state=latest"
|
||||
$ ansible webservers -m ansible.builtin.yum -a "name=acme state=latest"
|
||||
|
||||
To ensure a package is not installed:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible webservers -m yum -a "name=acme state=absent"
|
||||
$ ansible webservers -m ansible.builtin.yum -a "name=acme state=absent"
|
||||
|
||||
Ansible has modules for managing packages under many platforms. If there is no module for your package manager, you can install packages using the command module or create a module for your package manager.
|
||||
|
||||
|
|
@ -147,11 +147,11 @@ You can create, manage, and remove user accounts on your managed nodes with ad-h
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible all -m user -a "name=foo password=<crypted password here>"
|
||||
$ ansible all -m ansible.builtin.user -a "name=foo password=<crypted password here>"
|
||||
|
||||
$ ansible all -m user -a "name=foo state=absent"
|
||||
$ ansible all -m ansible.builtin.user -a "name=foo state=absent"
|
||||
|
||||
See the :ref:`user <user_module>` module documentation for details on all of the available options, including
|
||||
See the :ref:`ansible.builtin.user <user_module>` module documentation for details on all of the available options, including
|
||||
how to manipulate groups and group membership.
|
||||
|
||||
.. _managing_services:
|
||||
|
|
@ -163,19 +163,19 @@ Ensure a service is started on all webservers:
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible webservers -m service -a "name=httpd state=started"
|
||||
$ ansible webservers -m ansible.builtin.service -a "name=httpd state=started"
|
||||
|
||||
Alternatively, restart a service on all webservers:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible webservers -m service -a "name=httpd state=restarted"
|
||||
$ ansible webservers -m ansible.builtin.service -a "name=httpd state=restarted"
|
||||
|
||||
Ensure a service is stopped:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible webservers -m service -a "name=httpd state=stopped"
|
||||
$ ansible webservers -m ansible.builtin.service -a "name=httpd state=stopped"
|
||||
|
||||
.. _gathering_facts:
|
||||
|
||||
|
|
@ -186,9 +186,9 @@ Facts represent discovered variables about a system. You can use facts to implem
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible all -m setup
|
||||
$ ansible all -m ansible.builtin.setup
|
||||
|
||||
You can also filter this output to display only certain facts, see the :ref:`setup <setup_module>` module documentation for details.
|
||||
You can also filter this output to display only certain facts, see the :ref:`ansible.builtin.setup <setup_module>` module documentation for details.
|
||||
|
||||
Now that you understand the basic elements of Ansible execution, you are ready to learn to automate repetitive tasks using :ref:`Ansible Playbooks <playbooks_intro>`.
|
||||
|
||||
|
|
|
|||
|
|
@ -72,9 +72,9 @@ Hosts in multiple groups
|
|||
|
||||
You can (and probably will) put each host in more than one group. For example a production webserver in a datacenter in Atlanta might be included in groups called [prod] and [atlanta] and [webservers]. You can create groups that track:
|
||||
|
||||
* What - An application, stack or microservice. (For example, database servers, web servers, and so on).
|
||||
* Where - A datacenter or region, to talk to local DNS, storage, and so on. (For example, east, west).
|
||||
* When - The development stage, to avoid testing on production resources. (For example, prod, test).
|
||||
* What - An application, stack or microservice (for example, database servers, web servers, and so on).
|
||||
* Where - A datacenter or region, to talk to local DNS, storage, and so on (for example, east, west).
|
||||
* When - The development stage, to avoid testing on production resources (for example, prod, test).
|
||||
|
||||
Extending the previous YAML inventory to include what, when, and where would look like:
|
||||
|
||||
|
|
@ -651,23 +651,23 @@ Here is an example of how to instantly deploy to created containers:
|
|||
|
||||
.. code-block:: yaml
|
||||
|
||||
- name: create jenkins container
|
||||
docker_container:
|
||||
- name: Create a jenkins container
|
||||
community.general.docker_container:
|
||||
docker_host: myserver.net:4243
|
||||
name: my_jenkins
|
||||
image: jenkins
|
||||
|
||||
- name: add container to inventory
|
||||
add_host:
|
||||
- name: Add the container to inventory
|
||||
ansible.builtin.add_host:
|
||||
name: my_jenkins
|
||||
ansible_connection: docker
|
||||
ansible_docker_extra_args: "--tlsverify --tlscacert=/path/to/ca.pem --tlscert=/path/to/client-cert.pem --tlskey=/path/to/client-key.pem -H=tcp://myserver.net:4243"
|
||||
ansible_user: jenkins
|
||||
changed_when: false
|
||||
|
||||
- name: create directory for ssh keys
|
||||
- name: Create a directory for ssh keys
|
||||
delegate_to: my_jenkins
|
||||
file:
|
||||
ansible.builtin.file:
|
||||
path: "/var/jenkins_home/.ssh/jupiter"
|
||||
state: directory
|
||||
|
||||
|
|
@ -743,8 +743,8 @@ without affecting database servers:
|
|||
|
||||
- hosts: dbservers
|
||||
tasks:
|
||||
- name: allow access from 10.0.0.1
|
||||
iptables:
|
||||
- name: Allow access from 10.0.0.1
|
||||
ansible.builtin.iptables:
|
||||
chain: INPUT
|
||||
jump: ACCEPT
|
||||
source: 10.0.0.1
|
||||
|
|
|
|||
|
|
@ -56,7 +56,9 @@ You can still use the bare :ref:`roles <roles_keyword>` keyword at the play leve
|
|||
Includes: dynamic re-use
|
||||
------------------------
|
||||
|
||||
Including roles, tasks, or variables adds them to a playbook dynamically. Ansible processes included files and roles as they come up in a playbook, so included tasks can be affected by the results of earlier tasks within the top-level playbook. Included roles and tasks are similar to handlers - they may or may not run, depending on the results of other tasks in the top-level playbook. The primary advantage of using ``include_*`` statements is looping. When a loop is used with an include, the included tasks or role will be executed once for each item in the loop.
|
||||
Including roles, tasks, or variables adds them to a playbook dynamically. Ansible processes included files and roles as they come up in a playbook, so included tasks can be affected by the results of earlier tasks within the top-level playbook. Included roles and tasks are similar to handlers - they may or may not run, depending on the results of other tasks in the top-level playbook.
|
||||
|
||||
The primary advantage of using ``include_*`` statements is looping. When a loop is used with an include, the included tasks or role will be executed once for each item in the loop.
|
||||
|
||||
You can pass variables into includes. See :ref:`ansible_variable_precedence` for more details on variable inheritance and precedence.
|
||||
|
||||
|
|
@ -73,9 +75,11 @@ You can pass variables to imports. You must pass variables if you want to run an
|
|||
- import_tasks: wordpress.yml
|
||||
vars:
|
||||
wp_user: timmy
|
||||
|
||||
- import_tasks: wordpress.yml
|
||||
vars:
|
||||
wp_user: alice
|
||||
|
||||
- import_tasks: wordpress.yml
|
||||
vars:
|
||||
wp_user: bob
|
||||
|
|
@ -129,13 +133,13 @@ You can also use includes and imports in the :ref:`handlers` section of a playbo
|
|||
.. code-block:: yaml
|
||||
|
||||
# restarts.yml
|
||||
- name: restart apache
|
||||
service:
|
||||
- name: Restart apache
|
||||
ansible.builtin.service:
|
||||
name: apache
|
||||
state: restarted
|
||||
|
||||
- name: restart mysql
|
||||
service:
|
||||
- name: Restart mysql
|
||||
ansible.builtin.service:
|
||||
name: mysql
|
||||
state: restarted
|
||||
|
||||
|
|
@ -144,36 +148,36 @@ You can trigger handlers from either an import or an include, but the procedure
|
|||
Triggering included (dynamic) handlers
|
||||
--------------------------------------
|
||||
|
||||
Includes are executed at run-time, so the name of the include exists during play execution, but the included tasks do not exist until the include itself is triggered. To use the ``restart apache`` task with dynamic re-use, refer to the name of the include itself. This approach triggers all tasks in the included file as handlers. For example, with the task file shown above:
|
||||
Includes are executed at run-time, so the name of the include exists during play execution, but the included tasks do not exist until the include itself is triggered. To use the ``Restart apache`` task with dynamic re-use, refer to the name of the include itself. This approach triggers all tasks in the included file as handlers. For example, with the task file shown above:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
- trigger an included (dynamic) handler
|
||||
hosts: localhost
|
||||
handlers:
|
||||
- name: restart services
|
||||
- name: Restart services
|
||||
include_tasks: restarts.yml
|
||||
tasks:
|
||||
- command: "true"
|
||||
notify: restart services
|
||||
notify: Restart services
|
||||
|
||||
Triggering imported (static) handlers
|
||||
-------------------------------------
|
||||
|
||||
Imports are processed before the play begins, so the name of the import no longer exists during play execution, but the names of the individual imported tasks do exist. To use the ``restart apache`` task with static re-use, refer to the name of each task or tasks within the imported file. For example, with the task file shown above:
|
||||
Imports are processed before the play begins, so the name of the import no longer exists during play execution, but the names of the individual imported tasks do exist. To use the ``Restart apache`` task with static re-use, refer to the name of each task or tasks within the imported file. For example, with the task file shown above:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
- trigger an imported (static) handler
|
||||
hosts: localhost
|
||||
handlers:
|
||||
- name: restart services
|
||||
- name: Restart services
|
||||
import_tasks: restarts.yml
|
||||
tasks:
|
||||
- command: "true"
|
||||
notify: restart apache
|
||||
notify: Restart apache
|
||||
- command: "true"
|
||||
notify: restart mysql
|
||||
notify: Restart mysql
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
|
|
|||
|
|
@ -51,22 +51,23 @@ You can add other YAML files in some directories. For example, you can place pla
|
|||
.. code-block:: yaml
|
||||
|
||||
# roles/example/tasks/main.yml
|
||||
- name: install the correct web server for RHEL
|
||||
- name: Install the correct web server for RHEL
|
||||
import_tasks: redhat.yml
|
||||
when: ansible_facts['os_family']|lower == 'redhat'
|
||||
- name: install the correct web server for debian
|
||||
|
||||
- name: Install the correct web server for Debian
|
||||
import_tasks: debian.yml
|
||||
when: ansible_facts['os_family']|lower == 'debian'
|
||||
|
||||
# roles/example/tasks/redhat.yml
|
||||
- install web server
|
||||
yum:
|
||||
- name: Install web server
|
||||
ansible.builtin.yum:
|
||||
name: "httpd"
|
||||
state: present
|
||||
|
||||
# roles/example/tasks/debian.yml
|
||||
- install web server
|
||||
apt:
|
||||
- name: Install web server
|
||||
ansible.builtin.apt:
|
||||
name: "apache2"
|
||||
state: present
|
||||
|
||||
|
|
@ -174,11 +175,16 @@ To include a role:
|
|||
---
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- debug:
|
||||
- name: Print a message
|
||||
ansible.builtin.debug:
|
||||
msg: "this task runs before the example role"
|
||||
- include_role:
|
||||
|
||||
- name: Include the example role
|
||||
include_role:
|
||||
name: example
|
||||
- debug:
|
||||
|
||||
- name: Print a message
|
||||
ansible.builtin.debug:
|
||||
msg: "this task runs after the example role"
|
||||
|
||||
You can pass other keywords, including variables and tags, when including roles:
|
||||
|
|
@ -188,7 +194,8 @@ You can pass other keywords, including variables and tags, when including roles:
|
|||
---
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- include_role:
|
||||
- name: Include the foo_app_instance role
|
||||
include_role:
|
||||
name: foo_app_instance
|
||||
vars:
|
||||
dir: '/opt/a'
|
||||
|
|
@ -205,7 +212,8 @@ You can conditionally include a role:
|
|||
---
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- include_role:
|
||||
- name: Include the some_role role
|
||||
include_role:
|
||||
name: some_role
|
||||
when: "ansible_facts['os_family'] == 'RedHat'"
|
||||
|
||||
|
|
@ -219,11 +227,16 @@ You can reuse roles statically anywhere in the ``tasks`` section of a play using
|
|||
---
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- debug:
|
||||
- name: Print a message
|
||||
ansible.builtin.debug:
|
||||
msg: "before we run our role"
|
||||
- import_role:
|
||||
|
||||
- name: Import the example role
|
||||
import_role:
|
||||
name: example
|
||||
- debug:
|
||||
|
||||
- name: Print a message
|
||||
ansible.builtin.debug:
|
||||
msg: "after we ran our role"
|
||||
|
||||
You can pass other keywords, including variables and tags, when importing roles:
|
||||
|
|
@ -233,7 +246,8 @@ You can pass other keywords, including variables and tags, when importing roles:
|
|||
---
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- import_role:
|
||||
- name: Import the foo_app_instance role
|
||||
import_role:
|
||||
name: foo_app_instance
|
||||
vars:
|
||||
dir: '/opt/a'
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@ Tags
|
|||
|
||||
If you have a large playbook, it may be useful to run only specific parts of it instead of running the entire playbook. You can do this with Ansible tags. Using tags to execute or skip selected tasks is a two-step process:
|
||||
|
||||
#. Add tags to your tasks, either individually or with tag inheritance from a block, play, role, or import
|
||||
#. Select or skip tags when you run your playbook
|
||||
#. Add tags to your tasks, either individually or with tag inheritance from a block, play, role, or import.
|
||||
#. Select or skip tags when you run your playbook.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
|
@ -25,8 +25,8 @@ At the simplest level, you can apply one or more tags to an individual task. You
|
|||
.. code-block:: yaml
|
||||
|
||||
tasks:
|
||||
- install the servers
|
||||
yum:
|
||||
- name: Install the servers
|
||||
ansible.builtin.yum:
|
||||
name:
|
||||
- httpd
|
||||
- memcached
|
||||
|
|
@ -35,8 +35,8 @@ At the simplest level, you can apply one or more tags to an individual task. You
|
|||
- packages
|
||||
- webservers
|
||||
|
||||
- configure the service
|
||||
template:
|
||||
- name: Configure the service
|
||||
ansible.builtin.template:
|
||||
src: templates/src.j2
|
||||
dest: /etc/foo.conf
|
||||
tags:
|
||||
|
|
@ -49,29 +49,29 @@ You can apply the same tag to more than one individual task. This example tags s
|
|||
---
|
||||
# file: roles/common/tasks/main.yml
|
||||
|
||||
- name: be sure ntp is installed
|
||||
yum:
|
||||
- name: Install ntp
|
||||
ansible.builtin.yum:
|
||||
name: ntp
|
||||
state: present
|
||||
tags: ntp
|
||||
|
||||
- name: be sure ntp is configured
|
||||
template:
|
||||
- name: Configure ntp
|
||||
ansible.builtin.template:
|
||||
src: ntp.conf.j2
|
||||
dest: /etc/ntp.conf
|
||||
notify:
|
||||
- restart ntpd
|
||||
tags: ntp
|
||||
|
||||
- name: be sure ntpd is running and enabled
|
||||
service:
|
||||
- name: Enable and run ntpd
|
||||
ansible.builtin.service:
|
||||
name: ntpd
|
||||
state: started
|
||||
enabled: yes
|
||||
tags: ntp
|
||||
|
||||
- name: be sure file sharing is installed
|
||||
yum:
|
||||
- name: Install NFS utils
|
||||
ansible.builtin.yum:
|
||||
name:
|
||||
- nfs-utils
|
||||
- nfs-util-lib
|
||||
|
|
@ -94,7 +94,7 @@ You add tags to includes the same way you add tags to any other task:
|
|||
---
|
||||
# file: roles/common/tasks/main.yml
|
||||
|
||||
- name: dynamic re-use of database tasks
|
||||
- name: Dynamic re-use of database tasks
|
||||
include_tasks: db.yml
|
||||
tags: db
|
||||
|
||||
|
|
@ -105,7 +105,8 @@ You can add a tag only to the dynamic include of a role. In this example, the ``
|
|||
---
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- include_role:
|
||||
- name: Include the bar role
|
||||
include_role:
|
||||
name: bar
|
||||
tags:
|
||||
- foo
|
||||
|
|
@ -130,24 +131,26 @@ If you want to apply a tag to many, but not all, of the tasks in your play, use
|
|||
tasks:
|
||||
- block:
|
||||
tags: ntp
|
||||
- name: be sure ntp is installed
|
||||
yum:
|
||||
- name: Install ntp
|
||||
ansible.builtin.yum:
|
||||
name: ntp
|
||||
state: present
|
||||
- name: be sure ntp is configured
|
||||
template:
|
||||
|
||||
- name: Configure ntp
|
||||
ansible.builtin.template:
|
||||
src: ntp.conf.j2
|
||||
dest: /etc/ntp.conf
|
||||
notify:
|
||||
- restart ntpd
|
||||
- name: be sure ntpd is running and enabled
|
||||
service:
|
||||
|
||||
- name: Enable and run ntpd
|
||||
ansible.builtin.service:
|
||||
name: ntpd
|
||||
state: started
|
||||
enabled: yes
|
||||
|
||||
- name: be sure file sharing is installed
|
||||
yum:
|
||||
- name: Install NFS utils
|
||||
ansible.builtin.yum:
|
||||
name:
|
||||
- nfs-utils
|
||||
- nfs-util-lib
|
||||
|
|
@ -164,20 +167,20 @@ If all the tasks in a play should get the same tag, you can add the tag at the l
|
|||
- hosts: all
|
||||
tags: ntp
|
||||
tasks:
|
||||
- name: be sure ntp is installed
|
||||
yum:
|
||||
- name: Install ntp
|
||||
ansible.builtin.yum:
|
||||
name: ntp
|
||||
state: present
|
||||
|
||||
- name: be sure ntp is configured
|
||||
template:
|
||||
- name: Configure ntp
|
||||
ansible.builtin.template:
|
||||
src: ntp.conf.j2
|
||||
dest: /etc/ntp.conf
|
||||
notify:
|
||||
- restart ntpd
|
||||
|
||||
- name: be sure ntpd is running and enabled
|
||||
service:
|
||||
- name: Enable and run ntpd
|
||||
ansible.builtin.service:
|
||||
name: ntpd
|
||||
state: started
|
||||
enabled: yes
|
||||
|
|
@ -232,13 +235,15 @@ You can also apply a tag or tags to all the tasks imported by the static ``impor
|
|||
---
|
||||
- hosts: webservers
|
||||
tasks:
|
||||
- import_role:
|
||||
- name: Import the foo role
|
||||
import_role:
|
||||
name: foo
|
||||
tags:
|
||||
- bar
|
||||
- baz
|
||||
|
||||
- import_tasks: foo.yml
|
||||
- name: Import tasks from foo.yml
|
||||
import_tasks: foo.yml
|
||||
tags: [ web, foo ]
|
||||
|
||||
.. _apply_keyword:
|
||||
|
|
@ -252,7 +257,7 @@ If you want tag inheritance, you probably want to use imports. However, using bo
|
|||
|
||||
.. code-block:: yaml
|
||||
|
||||
- name: applies the db tag to the include and to all tasks in db.yaml
|
||||
- name: Apply the db tag to the include and to all tasks in db.yaml
|
||||
include_tasks:
|
||||
file: db.yml
|
||||
# adds 'db' tag to tasks within db.yml
|
||||
|
|
@ -266,7 +271,8 @@ Or you can use a block:
|
|||
.. code-block:: yaml
|
||||
|
||||
- block:
|
||||
- include_tasks: db.yml
|
||||
- name: Include tasks from db.yml
|
||||
include_tasks: db.yml
|
||||
tags: db
|
||||
|
||||
.. _special_tags:
|
||||
|
|
@ -281,12 +287,14 @@ For example:
|
|||
.. code-block:: yaml
|
||||
|
||||
tasks:
|
||||
- debug:
|
||||
- name: Print a message
|
||||
ansible.builtin.debug:
|
||||
msg: "Always runs"
|
||||
tags:
|
||||
- always
|
||||
|
||||
- debug:
|
||||
- name: Print a message
|
||||
ansible.builtin.debug:
|
||||
msg: "runs when you use tag1"
|
||||
tags:
|
||||
- tag1
|
||||
|
|
@ -305,8 +313,9 @@ For example:
|
|||
.. code-block:: yaml
|
||||
|
||||
tasks:
|
||||
- Rarely-used debug task
|
||||
debug: msg="{{ showmevar }}"
|
||||
- name: Run the rarely-used debug task
|
||||
ansible.builtin.debug:
|
||||
msg: '{{ showmevar }}'
|
||||
tags: [ never, debug ]
|
||||
|
||||
The rarely-used debug task in the example above only runs when you specifically request the ``debug`` or ``never`` tags.
|
||||
|
|
@ -371,19 +380,19 @@ If you have a role or a tasks file with tags defined at the task or block level,
|
|||
|
||||
# mixed.yml
|
||||
tasks:
|
||||
- name: task with no tags
|
||||
debug:
|
||||
- name: Run the task with no tags
|
||||
ansible.builtin.debug:
|
||||
msg: this task has no tags
|
||||
|
||||
- name: tagged task
|
||||
debug:
|
||||
- name: Run the tagged task
|
||||
ansible.builtin.debug:
|
||||
msg: this task is tagged with mytag
|
||||
tags: mytag
|
||||
|
||||
- block:
|
||||
- name: First block task with mytag
|
||||
- name: Run the first block task with mytag
|
||||
...
|
||||
- name: Second block task with mytag
|
||||
- name: Run the second block task with mytag
|
||||
...
|
||||
tags:
|
||||
- mytag
|
||||
|
|
@ -395,7 +404,8 @@ And you might include the tasks file above in a playbook:
|
|||
# myplaybook.yml
|
||||
- hosts: all
|
||||
tasks:
|
||||
- include_tasks:
|
||||
- name: Run tasks from mixed.yml
|
||||
include_tasks:
|
||||
name: mixed.yml
|
||||
tags: mytag
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue