Docs: User guide overhaul, part 5 (#70307)
This commit is contained in:
Alicia Cozine
GitHub
parent
f1f782fc37
commit
db354c0300
29 changed files with 499 additions and 608 deletions
|
|
@ -483,4 +483,4 @@ If you receive an connection error please double check the inventory and playboo
|
|||
|
||||
* :ref:`network_guide`
|
||||
* :ref:`intro_inventory`
|
||||
* :ref:`Vault best practices <best_practices_for_variables_and_vaults>`
|
||||
* :ref:`Keeping vaulted variables visible <tip_for_variables_and_vaults>`
|
||||
|
|
|
|||
|
|
@ -698,7 +698,7 @@ Please see the section below for a link to IRC and the Google Group, where you c
|
|||
:ref:`working_with_playbooks`
|
||||
An introduction to playbooks
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices advice
|
||||
Tips and tricks for playbooks
|
||||
`User Mailing List <https://groups.google.com/group/ansible-project>`_
|
||||
Have a question? Stop by the google group!
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
|
|
|
|||
|
|
@ -494,7 +494,7 @@ when a term comes up on the mailing list.
|
|||
:ref:`working_with_playbooks`
|
||||
An introduction to playbooks
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices advice
|
||||
Tips and tricks for playbooks
|
||||
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
|
||||
Have a question? Stop by the google group!
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
|
|
|
|||
|
|
@ -543,7 +543,7 @@ ansible_port
|
|||
ansible_user
|
||||
The user name to use when connecting to the host
|
||||
ansible_password
|
||||
The password to use to authenticate to the host (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`)
|
||||
The password to use to authenticate to the host (never store this variable in plain text; always use a vault. See :ref:`tip_for_variables_and_vaults`)
|
||||
|
||||
|
||||
Specific to the SSH connection:
|
||||
|
|
@ -575,7 +575,7 @@ ansible_become_method
|
|||
ansible_become_user
|
||||
Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows to set the user you become through privilege escalation
|
||||
ansible_become_password
|
||||
Equivalent to ``ansible_sudo_password`` or ``ansible_su_password``, allows you to set the privilege escalation password (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`)
|
||||
Equivalent to ``ansible_sudo_password`` or ``ansible_su_password``, allows you to set the privilege escalation password (never store this variable in plain text; always use a vault. See :ref:`tip_for_variables_and_vaults`)
|
||||
ansible_become_exe
|
||||
Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``, allows you to set the executable for the escalation method selected
|
||||
ansible_become_flags
|
||||
|
|
|
|||
|
|
@ -4,68 +4,66 @@
|
|||
Module Maintenance & Support
|
||||
****************************
|
||||
|
||||
If you are using a module and you discover a bug, you may want to know where to report that bug, who is responsible for fixing it, and how you can track changes to the module. If you are a Red Hat subscriber, you may want to know whether you can get support for the issue you are facing.
|
||||
|
||||
Starting in Ansible 2.10, most modules live in collections. The distribution method for each collection reflects the maintenance and support for the modules in that collection.
|
||||
|
||||
.. contents::
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
Maintenance
|
||||
===========
|
||||
|
||||
To clarify who maintains each included module, adding features and fixing bugs, each included module now has associated metadata that provides information about maintenance.
|
||||
.. table::
|
||||
:class: documentation-table
|
||||
|
||||
Core
|
||||
----
|
||||
============================= ========================================== ==========================
|
||||
Collection Code location Maintained by
|
||||
============================= ========================================== ==========================
|
||||
ansible.builtin `ansible/ansible repo`_ on GitHub core team
|
||||
|
||||
:ref:`Core Maintained<core_supported>` modules are maintained by the Ansible Engineering Team.
|
||||
These modules are integral to the basic foundations of the Ansible distribution.
|
||||
distributed on Galaxy various; follow ``repo`` link community or partners
|
||||
|
||||
Network
|
||||
-------
|
||||
distributed on Automation Hub various; follow ``repo`` link content team or partners
|
||||
============================= ========================================== ==========================
|
||||
|
||||
:ref:`Network Maintained<network_supported>` modules are are maintained by the Ansible Network Team. Please note there are additional networking modules that are categorized as Certified or Community not maintained by Ansible.
|
||||
|
||||
|
||||
Certified
|
||||
---------
|
||||
|
||||
`Certified <https://access.redhat.com/articles/3642632>`_ modules are maintained by Ansible Partners.
|
||||
|
||||
Community
|
||||
---------
|
||||
|
||||
:ref:`Community Maintained<community_supported>` modules are submitted and maintained by the Ansible community. These modules are not maintained by Ansible, and are included as a convenience.
|
||||
.. _ansible/ansible repo: https://github.com/ansible/ansible/tree/devel/lib/ansible/modules
|
||||
|
||||
Issue Reporting
|
||||
===============
|
||||
|
||||
If you believe you have found a bug in a module and are already running the latest stable or development version of Ansible, first look at the `issue tracker in the Ansible repo <https://github.com/ansible/ansible/issues>`_ to see if an issue has already been filed. If not, please file one.
|
||||
If you find a bug that affects a plugin in the main Ansible repo:
|
||||
|
||||
Should you have a question rather than a bug report, inquiries are welcome on the `ansible-project Google group <https://groups.google.com/forum/#%21forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net.
|
||||
#. Confirm that you are running the latest stable version of Ansible or the devel branch.
|
||||
#. Look at the `issue tracker in the Ansible repo <https://github.com/ansible/ansible/issues>`_ to see if an issue has already been filed.
|
||||
#. Create an issue if one does not already exist. Include as much detail as you can about the behavior you discovered.
|
||||
|
||||
For development-oriented topics, use the `ansible-devel Google group <https://groups.google.com/forum/#%21forum/ansible-devel>`_ or Ansible's #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read the :ref:`Community Guide <ansible_community_guide>`, :ref:`Testing Ansible <developing_testing>`, and the :ref:`Developer Guide <developer_guide>`.
|
||||
If you find a bug that affects a plugin in a Galaxy collection:
|
||||
|
||||
The modules are hosted on GitHub in a subdirectory of the `Ansible <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ repo.
|
||||
#. Find the collection on Galaxy.
|
||||
#. Find the issue tracker for the collection.
|
||||
#. Look there to see if an issue has already been filed.
|
||||
#. Create an issue if one does not already exist. Include as much detail as you can about the behavior you discovered.
|
||||
|
||||
NOTE: If you have a Red Hat Ansible Automation product subscription, please follow the standard issue reporting process via the `Red Hat Customer Portal <https://access.redhat.com/>`_.
|
||||
Some partner collections may be hosted in private repositories.
|
||||
|
||||
If you are not sure whether the behavior you see is a bug, if you have questions, if you want to discuss development-oriented topics, or if you just want to get in touch, use one of our Google groups or IRC channels to :ref:`communicate with Ansiblers <communication>`.
|
||||
|
||||
If you find a bug that affects a module in an Automation Hub collection:
|
||||
|
||||
#. If the collection offers an Issue Tracker link on Automation Hub, click there and open an issue on the collection repository. If it does not, follow the standard process for reporting issues on the `Red Hat Customer Portal <https://access.redhat.com/>`_. You must have a subscription to the Red Hat Ansible Automation Platform to create an issue on the portal.
|
||||
|
||||
Support
|
||||
=======
|
||||
|
||||
For more information on how included Ansible modules are supported by Red Hat,
|
||||
please refer to the following `knowledge base article <https://access.redhat.com/articles/3166901>`_ as well as other resources on the `Red Hat Customer Portal. <https://access.redhat.com/>`_
|
||||
All plugins that remain in ansible-base and all collections hosted in Automation Hub are supported by Red Hat. No other plugins or collections are supported by Red Hat. If you have a subscription to the Red Hat Ansible Automation Platform, you can find more information and resources on the `Red Hat Customer Portal. <https://access.redhat.com/>`_
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`Module index<modules_by_category>`
|
||||
A complete list of all available modules.
|
||||
:ref:`intro_adhoc`
|
||||
Examples of using modules in /usr/bin/ansible
|
||||
:ref:`working_with_playbooks`
|
||||
Examples of using modules with /usr/bin/ansible-playbook
|
||||
:ref:`developing_modules`
|
||||
How to write your own modules
|
||||
`List of Ansible Certified Modules <https://access.redhat.com/articles/3642632>`_
|
||||
High level list of Ansible certified modules from Partners
|
||||
`Mailing List <https://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
|
|
|
|||
|
|
@ -4,20 +4,21 @@
|
|||
Search paths in Ansible
|
||||
***********************
|
||||
|
||||
Absolute paths are not an issue as they always have a known start, but relative paths ... well, they are relative.
|
||||
You can control the paths Ansible searches to find resources on your control node (including configuration, modules, roles, ssh keys, and more) as well as resources on the remote nodes you are managing. Use absolute paths to tell Ansible where to find resources whenever you can. However, absolute paths are not always practical. This page covers how Ansible interprets relative search paths, along with ways to troubleshoot when Ansible cannot find the resource you need.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
Config paths
|
||||
============
|
||||
|
||||
By default these should be relative to the config file, some are specifically relative to the 'cwd' or the playbook and should have this noted in their description. Things like ssh keys are left to use 'cwd' because it mirrors how the underlying tools would use it.
|
||||
By default these should be relative to the config file, some are specifically relative to the current working directory or the playbook and should have this noted in their description. Things like ssh keys are left to use the current working directory because it mirrors how the underlying tools would use it.
|
||||
|
||||
|
||||
Task paths
|
||||
==========
|
||||
|
||||
Here things start getting complicated, there are 2 different scopes to consider, task evaluation (paths are all local, like in lookups) and task execution, which is normally on the remote, unless an action plugin is involved.
|
||||
|
||||
Some tasks that require 'local' resources use action plugins (template and copy are examples of these), in which case the path is also local.
|
||||
Task paths include two different scopes: task evaluation and task execution. For task evaluation, all paths are local, like in lookups. For task execution, which usually happens on the remote nodes, local paths do not usually apply. However, if a task uses an action plugin, it uses a local path. The template and copy modules are examples of modules that use action plugins, and therefore use local paths.
|
||||
|
||||
The magic of 'local' paths
|
||||
--------------------------
|
||||
|
|
@ -32,12 +33,10 @@ i.e ::
|
|||
play search path is playdir/{files|vars|templates}/, playdir/.
|
||||
|
||||
|
||||
The current working directory (cwd) is not searched. If you see it, it just happens to coincide with one of the paths above.
|
||||
If you `include` a task file from a role, it will NOT trigger role behavior, this only happens when running as a role, `include_role` will work.
|
||||
A new variable `ansible_search_path` var will have the search path used, in order (but without the appended subdirs). Using 5 "v"s (`-vvvvv`) should show the detail of the search as it happens.
|
||||
By default, Ansible does not search the current working directory unless it happens to coincide with one of the paths above. If you `include` a task file from a role, it will NOT trigger role behavior, this only happens when running as a role, `include_role` will work. A new variable `ansible_search_path` var will have the search path used, in order (but without the appended subdirs). Using 5 "v"s (`-vvvvv`) should show the detail of the search as it happens.
|
||||
|
||||
As for includes, they try the path of the included file first and fall back to the play/role that includes them.
|
||||
|
||||
|
||||
|
||||
.. note: The 'cwd' might vary depending on the connection plugin and if the action is local or remote. For the remote it is normally the directory on which the login shell puts the user. For local it is either the directory you executed ansible from or in some cases the playbook directory.
|
||||
.. note: The current working directory might vary depending on the connection plugin and if the action is local or remote. For the remote it is normally the directory on which the login shell puts the user. For local it is either the directory you executed ansible from or in some cases the playbook directory.
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ Separate production and staging inventory
|
|||
|
||||
You can keep your production environment separate from development, test, and staging environments by using separate inventory files or directories for each environment. This way you pick with -i what you are targeting. Keeping all your environments in one file can lead to surprises!
|
||||
|
||||
.. _best_practices_for_variables_and_vaults:
|
||||
.. _tip_for_variables_and_vaults:
|
||||
|
||||
Keep vaulted variables safely visible
|
||||
-------------------------------------
|
||||
|
|
|
|||
|
|
@ -464,7 +464,7 @@ Possible values (sample, not complete list)::
|
|||
:ref:`playbooks_reuse_roles`
|
||||
Playbook organization by roles
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices in playbooks
|
||||
Tips and tricks for playbooks
|
||||
:ref:`playbooks_variables`
|
||||
All about variables
|
||||
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
.. _playbooks_delegation:
|
||||
|
||||
Delegation and local actions
|
||||
============================
|
||||
Controlling where tasks run: delegation and local actions
|
||||
=========================================================
|
||||
|
||||
By default Ansible executes all tasks on the machines that match the ``hosts`` line of your playbook. If you want to run some tasks on a different machine, you can use delegation. For example, when updating webservers, you might want to retrieve information from your database servers. In this scenario, your play would target the webservers group and you would delegate the database tasks to your dbservers group. With delegation, you can perform a task on one host on behalf of another, or execute tasks locally on behalf of remote hosts.
|
||||
By default Ansible gathers facts and executes all tasks on the machines that match the ``hosts`` line of your playbook. This page shows you how to delegate tasks to a different machine or group, delegate facts to specific machines or groups, or run an entire playbook locally. Using these approaches, you can manage inter-related environments precisely and efficiently. For example, when updating your webservers, you might need to remove them from a load-balanced pool temporarily. You cannot perform this task on the webservers themselves. By delegating the task to localhost, you keep all the tasks within the same play.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
|
@ -99,52 +99,10 @@ Delegating Ansible tasks is like delegating tasks in the real world - your groce
|
|||
|
||||
This task gathers facts for the machines in the dbservers group and assigns the facts to those machines, even though the play targets the app_servers group. This way you can lookup `hostvars['dbhost1']['ansible_default_ipv4']['address']` even though dbservers were not part of the play, or left out by using `--limit`.
|
||||
|
||||
.. _run_once:
|
||||
|
||||
Run once
|
||||
--------
|
||||
|
||||
If you want a task to run only on the first host in your batch of hosts, set ``run_once`` to true on that task::
|
||||
|
||||
---
|
||||
# ...
|
||||
|
||||
tasks:
|
||||
|
||||
# ...
|
||||
|
||||
- command: /opt/application/upgrade_db.py
|
||||
run_once: true
|
||||
|
||||
# ...
|
||||
|
||||
Ansible executes this task on the first host in the current batch and applies all results and facts to all the hosts in the same batch. This approach is similar to applying a conditional to a task such as::
|
||||
|
||||
- command: /opt/application/upgrade_db.py
|
||||
when: inventory_hostname == webservers[0]
|
||||
|
||||
However, with ``run_once``, the results are applied to all the hosts. To specify an individual host to execute on, delegate the task::
|
||||
|
||||
- command: /opt/application/upgrade_db.py
|
||||
run_once: true
|
||||
delegate_to: web01.example.org
|
||||
|
||||
As always with delegation, the action will be executed on the delegated host, but the information is still that of the original host in the task.
|
||||
|
||||
.. note::
|
||||
When used together with "serial", tasks marked as "run_once" will be run on one host in *each* serial batch. If the task must run only once regardless of "serial" mode, use
|
||||
:code:`when: inventory_hostname == ansible_play_hosts_all[0]` construct.
|
||||
|
||||
.. note::
|
||||
Any conditional (i.e `when:`) will use the variables of the 'first host' to decide if the task runs or not, no other hosts will be tested.
|
||||
|
||||
.. note::
|
||||
If you want to avoid the default behavior of setting the fact for all hosts, set `delegate_facts: True` for the specific task or block.
|
||||
|
||||
.. _local_playbooks:
|
||||
|
||||
Local playbooks
|
||||
```````````````
|
||||
---------------
|
||||
|
||||
It may be useful to use a playbook locally on a remote host, rather than by connecting over SSH. This can be useful for assuring the configuration of a system by putting a playbook in a crontab. This may also be used
|
||||
to run a playbook inside an OS installer, such as an Anaconda kickstart.
|
||||
|
|
@ -165,11 +123,12 @@ use the default remote connection type::
|
|||
under {{ ansible_playbook_python }}. Be sure to set ansible_python_interpreter: "{{ ansible_playbook_python }}" in
|
||||
host_vars/localhost.yml, for example. You can avoid this issue by using ``local_action`` or ``delegate_to: localhost`` instead.
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`playbooks_intro`
|
||||
An introduction to playbooks
|
||||
:ref:`playbooks_strategies`
|
||||
More ways to control how and where Ansible executes
|
||||
`Ansible Examples on GitHub <https://github.com/ansible/ansible-examples>`_
|
||||
Many examples of full-stack deployments
|
||||
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
|
||||
|
|
|
|||
|
|
@ -231,7 +231,7 @@ You can also use blocks to define responses to task errors. This approach is sim
|
|||
:ref:`playbooks_intro`
|
||||
An introduction to playbooks
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices in playbooks
|
||||
Tips and tricks for playbooks
|
||||
:ref:`playbooks_conditionals`
|
||||
Conditional statements in playbooks
|
||||
:ref:`playbooks_variables`
|
||||
|
|
|
|||
|
|
@ -1652,7 +1652,7 @@ This can then be used to reference hashes in Pod specifications::
|
|||
:ref:`playbooks_reuse_roles`
|
||||
Playbook organization by roles
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices in playbooks
|
||||
Tips and tricks for playbooks
|
||||
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
|
||||
Have a question? Stop by the google group!
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
|
|
|
|||
|
|
@ -737,7 +737,7 @@ the filter ``slaac()`` generates an IPv6 address for a given network and a MAC A
|
|||
:ref:`playbooks_reuse_roles`
|
||||
Playbook organization by roles
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices in playbooks
|
||||
Tips and tricks for playbooks
|
||||
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
|
||||
Have a question? Stop by the google group!
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
|
|
|
|||
|
|
@ -430,7 +430,7 @@ Migrating from with_X to loop
|
|||
:ref:`playbooks_reuse_roles`
|
||||
Playbook organization by roles
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices in playbooks
|
||||
Tips and tricks for playbooks
|
||||
:ref:`playbooks_conditionals`
|
||||
Conditional statements in playbooks
|
||||
:ref:`playbooks_variables`
|
||||
|
|
|
|||
|
|
@ -188,7 +188,7 @@ Imports are processed before the play begins, so the name of the import no longe
|
|||
:ref:`playbooks_loops`
|
||||
Loops in playbooks
|
||||
:ref:`playbooks_best_practices`
|
||||
Various tips about managing playbooks in the real world
|
||||
Tips and tricks for playbooks
|
||||
:ref:`ansible_galaxy`
|
||||
How to share roles on galaxy, role management
|
||||
`GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ The content on this page has been moved to :ref:`playbooks_reuse`.
|
|||
:ref:`working_with_playbooks`
|
||||
Review the basic Playbook language features
|
||||
:ref:`playbooks_best_practices`
|
||||
Various tips about managing playbooks in the real world
|
||||
Tips and tricks for playbooks
|
||||
:ref:`playbooks_variables`
|
||||
All about variables in playbooks
|
||||
:ref:`playbooks_conditionals`
|
||||
|
|
|
|||
|
|
@ -441,7 +441,7 @@ Read the `Ansible Galaxy documentation <https://galaxy.ansible.com/docs/>`_ page
|
|||
:ref:`working_with_playbooks`
|
||||
Review the basic Playbook language features
|
||||
:ref:`playbooks_best_practices`
|
||||
Tips for managing playbooks in the real world
|
||||
Tips and tricks for playbooks
|
||||
:ref:`playbooks_variables`
|
||||
Variables in playbooks
|
||||
:ref:`playbooks_conditionals`
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ As you write more playbooks and roles, you might have some special use cases. Fo
|
|||
../plugins/plugins
|
||||
playbooks_prompts
|
||||
playbooks_tags
|
||||
playbooks_vault
|
||||
vault
|
||||
playbooks_startnstep
|
||||
../reference_appendices/playbooks_keywords
|
||||
playbooks_lookups
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ or pass it on the command line: `ansible-playbook -f 30 my_playbook.yml`.
|
|||
Using keywords to control execution
|
||||
-----------------------------------
|
||||
|
||||
In addition to strategies, several :ref:`keywords<playbook_keywords>` also affect play execution. You can set a number, a percentage, or a list of numbers of hosts you want to manage at a time with ``serial``. Ansible completes the play on the specified number or percentage of hosts before starting the next batch of hosts. You can restrict the number of workers allotted to a block or task with ``throttle``. You can control how Ansible selects the next host in a group to execute against with ``order``. These keywords are not strategies. They are directives or options applied to a play, block, or task.
|
||||
In addition to strategies, several :ref:`keywords<playbook_keywords>` also affect play execution. You can set a number, a percentage, or a list of numbers of hosts you want to manage at a time with ``serial``. Ansible completes the play on the specified number or percentage of hosts before starting the next batch of hosts. You can restrict the number of workers allotted to a block or task with ``throttle``. You can control how Ansible selects the next host in a group to execute against with ``order``. You can run a task on a single host with ``run_once``. These keywords are not strategies. They are directives or options applied to a play, block, or task.
|
||||
|
||||
.. _rolling_update_batch_size:
|
||||
|
||||
|
|
@ -160,10 +160,54 @@ shuffle:
|
|||
|
||||
Other keywords that affect play execution include ``ignore_errors``, ``ignore_unreachable``, and ``any_errors_fatal``. These options are documented in :ref:`playbooks_error_handling`.
|
||||
|
||||
.. _run_once:
|
||||
|
||||
Running on a single machine with ``run_once``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you want a task to run only on the first host in your batch of hosts, set ``run_once`` to true on that task::
|
||||
|
||||
---
|
||||
# ...
|
||||
|
||||
tasks:
|
||||
|
||||
# ...
|
||||
|
||||
- command: /opt/application/upgrade_db.py
|
||||
run_once: true
|
||||
|
||||
# ...
|
||||
|
||||
Ansible executes this task on the first host in the current batch and applies all results and facts to all the hosts in the same batch. This approach is similar to applying a conditional to a task such as::
|
||||
|
||||
- command: /opt/application/upgrade_db.py
|
||||
when: inventory_hostname == webservers[0]
|
||||
|
||||
However, with ``run_once``, the results are applied to all the hosts. To run the task on a specific host, instead of the first host in the batch, delegate the task::
|
||||
|
||||
- command: /opt/application/upgrade_db.py
|
||||
run_once: true
|
||||
delegate_to: web01.example.org
|
||||
|
||||
As always with :ref:`delegation <playbooks_delegation>`, the action will be executed on the delegated host, but the information is still that of the original host in the task.
|
||||
|
||||
.. note::
|
||||
When used together with ``serial``, tasks marked as ``run_once`` will be run on one host in *each* serial batch. If the task must run only once regardless of ``serial`` mode, use
|
||||
:code:`when: inventory_hostname == ansible_play_hosts_all[0]` construct.
|
||||
|
||||
.. note::
|
||||
Any conditional (i.e `when:`) will use the variables of the 'first host' to decide if the task runs or not, no other hosts will be tested.
|
||||
|
||||
.. note::
|
||||
If you want to avoid the default behavior of setting the fact for all hosts, set ``delegate_facts: True`` for the specific task or block.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`about_playbooks`
|
||||
An introduction to playbooks
|
||||
:ref:`playbooks_delegation`
|
||||
Running tasks on or assigning facts to specific machines
|
||||
:ref:`playbooks_reuse_roles`
|
||||
Playbook organization by roles
|
||||
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ fmt
|
|||
:ref:`playbooks_reuse_roles`
|
||||
Playbook organization by roles
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices in playbooks
|
||||
Tips and tricks for playbooks
|
||||
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
|
||||
Have a question? Stop by the google group!
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
|
|
|
|||
|
|
@ -386,7 +386,7 @@ The following tasks are illustrative of the tests meant to check the status of t
|
|||
:ref:`playbooks_reuse_roles`
|
||||
Playbook organization by roles
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices in playbooks
|
||||
Tips and tricks for playbooks
|
||||
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
|
||||
Have a question? Stop by the google group!
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
|
|
|
|||
|
|
@ -437,7 +437,7 @@ For information about advanced YAML syntax used to declare variables and have mo
|
|||
:ref:`playbooks_reuse_roles`
|
||||
Playbook organization by roles
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices in playbooks
|
||||
Tips and tricks for playbooks
|
||||
:ref:`special_variables`
|
||||
List of special variables
|
||||
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
|
||||
|
|
|
|||
|
|
@ -1,157 +1,6 @@
|
|||
.. _playbooks_vault:
|
||||
:orphan:
|
||||
|
||||
Using Vault in playbooks
|
||||
Using vault in playbooks
|
||||
========================
|
||||
|
||||
.. contents:: Topics
|
||||
|
||||
The "Vault" is a feature of Ansible that allows you to keep sensitive data such as passwords or keys protected at rest, rather than as plaintext in playbooks or roles. These vaults can then be distributed or placed in source control.
|
||||
|
||||
There are 2 types of vaulted content and each has their own uses and limitations:
|
||||
|
||||
:Vaulted files:
|
||||
* The full file is encrypted in the vault, this can contain Ansible variables or any other type of content.
|
||||
* It will always be decrypted when loaded or referenced, Ansible cannot know if it needs the content unless it decrypts it.
|
||||
* It can be used for inventory, anything that loads variables (i.e vars_files, group_vars, host_vars, include_vars, etc)
|
||||
and some actions that deal with files (i.e M(copy), M(assemble), M(script), etc).
|
||||
|
||||
:Single encrypted variable:
|
||||
* Only specific variables are encrypted inside a normal 'variable file'.
|
||||
* Does not work for other content, only variables.
|
||||
* Decrypted on demand, so you can have vaulted variables with different vault secrets and only provide those needed.
|
||||
* You can mix vaulted and non vaulted variables in the same file, even inline in a play or role.
|
||||
|
||||
.. warning::
|
||||
* Vault ONLY protects data 'at rest'. Once decrypted, play and plugin authors are responsible for avoiding any secret disclosure,
|
||||
see :ref:`no_log <keep_secret_data>` for details on hiding output.
|
||||
|
||||
To enable this feature, a command line tool, :ref:`ansible-vault` is used to edit files, and a command line flag :option:`--ask-vault-pass <ansible-vault-create --ask-vault-pass>`, :option:`--vault-password-file <ansible-vault-create --vault-password-file>` or :option:`--vault-id <ansible-playbook --vault-id>` is used. You can also modify your ``ansible.cfg`` file to specify the location of a password file or configure Ansible to always prompt for the password. These options require no command line flag usage.
|
||||
|
||||
For best practices advice, refer to :ref:`best_practices_for_variables_and_vaults`.
|
||||
|
||||
Running a Playbook With Vault
|
||||
`````````````````````````````
|
||||
|
||||
To run a playbook that contains vault-encrypted data files, you must provide the vault password.
|
||||
|
||||
To specify the vault-password interactively::
|
||||
|
||||
ansible-playbook site.yml --ask-vault-pass
|
||||
|
||||
This prompt will then be used to decrypt (in memory only) any vault encrypted files that are accessed.
|
||||
|
||||
Alternatively, passwords can be specified with a file or a script (the script version will require Ansible 1.7 or later). When using this flag, ensure permissions on the file are such that no one else can access your key and do not add your key to source control::
|
||||
|
||||
ansible-playbook site.yml --vault-password-file ~/.vault_pass.txt
|
||||
|
||||
ansible-playbook site.yml --vault-password-file ~/.vault_pass.py
|
||||
|
||||
The password should be a string stored as a single line in the file.
|
||||
|
||||
If you are using a script instead of a flat file, ensure that it is marked as executable, and that the password is printed to standard output. If your script needs to prompt for data, prompts can be sent to standard error.
|
||||
|
||||
.. note::
|
||||
You can also set :envvar:`ANSIBLE_VAULT_PASSWORD_FILE` environment variable, e.g. ``ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass.txt`` and Ansible will automatically search for the password in that file.
|
||||
|
||||
This is something you may wish to do if using Ansible from a continuous integration system like Jenkins.
|
||||
|
||||
The :option:`--vault-password-file <ansible-pull --vault-password-file>` option can also be used with the :ref:`ansible-pull` command if you wish, though this would require distributing the keys to your nodes, so understand the implications -- vault is more intended for push mode.
|
||||
|
||||
|
||||
Multiple Vault Passwords
|
||||
````````````````````````
|
||||
|
||||
Ansible 2.4 and later support the concept of multiple vaults that are encrypted with different passwords
|
||||
Different vaults can be given a label to distinguish them (generally values like dev, prod etc.).
|
||||
|
||||
The :option:`--ask-vault-pass <ansible-playbook --ask-vault-pass>` and
|
||||
:option:`--vault-password-file <ansible-playbook --vault-password-file>` options can be used as long as
|
||||
only a single password is needed for any given run.
|
||||
|
||||
Alternatively the :option:`--vault-id <ansible-playbook --vault-id>` option can be used to provide the
|
||||
password and indicate which vault label it's for. This can be clearer when multiple vaults are used within
|
||||
a single inventory. For example:
|
||||
|
||||
To be prompted for the 'dev' password:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook site.yml --vault-id dev@prompt
|
||||
|
||||
To get the 'dev' password from a file or script:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook site.yml --vault-id dev@~/.vault_pass.txt
|
||||
|
||||
ansible-playbook site.yml --vault-id dev@~/.vault_pass.py
|
||||
|
||||
If multiple vault passwords are required for a single run, :option:`--vault-id <ansible-playbook --vault-id>` must
|
||||
be used as it can be specified multiple times to provide the multiple passwords. For example:
|
||||
|
||||
To read the 'dev' password from a file and prompt for the 'prod' password:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook site.yml --vault-id dev@~/.vault_pass.txt --vault-id prod@prompt
|
||||
|
||||
The :option:`--ask-vault-pass <ansible-playbook --ask-vault-pass>` or
|
||||
:option:`--vault-password-file <ansible-playbook --vault-password-file>` options can be used to specify one of
|
||||
the passwords, but it's generally cleaner to avoid mixing these with :option:`--vault-id <ansible-playbook --vault-id>`.
|
||||
|
||||
.. note::
|
||||
By default the vault label (dev, prod etc.) is just a hint. Ansible will try to decrypt each
|
||||
vault with every provided password.
|
||||
|
||||
Setting the config option :ref:`DEFAULT_VAULT_ID_MATCH` will change this behavior so that each password
|
||||
is only used to decrypt data that was encrypted with the same label. See :ref:`specifying_vault_ids`
|
||||
for more details.
|
||||
|
||||
Vault Password Client Scripts
|
||||
`````````````````````````````
|
||||
|
||||
Ansible 2.5 and later support using a single executable script to get different passwords depending on the
|
||||
vault label. These client scripts must have a file name that ends with :file:`-client`. For example:
|
||||
|
||||
To get the dev password from the system keyring using the :file:`contrib/vault/vault-keyring-client.py` script:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --vault-id dev@contrib/vault/vault-keyring-client.py
|
||||
|
||||
See :ref:`vault_password_client_scripts` for a complete explanation of this topic.
|
||||
|
||||
|
||||
.. _single_encrypted_variable:
|
||||
|
||||
Single Encrypted Variable
|
||||
`````````````````````````
|
||||
|
||||
As of version 2.3, Ansible can now use a vaulted variable that lives in an otherwise 'clear text' YAML file::
|
||||
|
||||
notsecret: myvalue
|
||||
mysecret: !vault |
|
||||
$ANSIBLE_VAULT;1.1;AES256
|
||||
66386439653236336462626566653063336164663966303231363934653561363964363833313662
|
||||
6431626536303530376336343832656537303632313433360a626438346336353331386135323734
|
||||
62656361653630373231613662633962316233633936396165386439616533353965373339616234
|
||||
3430613539666330390a313736323265656432366236633330313963326365653937323833366536
|
||||
34623731376664623134383463316265643436343438623266623965636363326136
|
||||
other_plain_text: othervalue
|
||||
|
||||
To create a vaulted variable, use the :ref:`ansible-vault encrypt_string <ansible_vault_encrypt_string>` command. See :ref:`encrypt_string` for details.
|
||||
|
||||
This vaulted variable will be decrypted with the supplied vault secret and used as a normal variable. The ``ansible-vault`` command line supports stdin and stdout for encrypting data on the fly, which can be used from your favorite editor to create these vaulted variables; you just have to be sure to add the ``!vault`` tag so both Ansible and YAML are aware of the need to decrypt. The ``|`` is also required, as vault encryption results in a multi-line string.
|
||||
|
||||
.. note::
|
||||
Inline vaults ONLY work on variables, you cannot use directly on a task's options.
|
||||
|
||||
.. _encrypt_string:
|
||||
|
||||
Using encrypt_string
|
||||
````````````````````
|
||||
|
||||
This command will output a string in the above format ready to be included in a YAML file.
|
||||
The string to encrypt can be provided via stdin, command line arguments, or via an interactive prompt.
|
||||
|
||||
See :ref:`encrypt_string_for_use_in_yaml`.
|
||||
The documentation regarding Ansible Vault has moved. The new location is here: :ref:`vault`. Please update any links you may have made directly to this page.
|
||||
|
|
|
|||
|
|
@ -1,12 +1,9 @@
|
|||
.. _plugin_filtering_config:
|
||||
|
||||
Plugin Filter Configuration
|
||||
===========================
|
||||
Blacklisting modules
|
||||
====================
|
||||
|
||||
Ansible 2.5 adds the ability for a site administrator to blacklist modules that they do not want to
|
||||
be available to Ansible. This is configured via a yaml configuration file (by default,
|
||||
:file:`/etc/ansible/plugin_filters.yml`). Use ``plugin_filters_cfg`` configuration
|
||||
in ``defaults`` section to change this configuration file path. The format of the file is:
|
||||
If you want to avoid using certain modules, you can blacklist them to prevent Ansible from loading them. To blacklist plugins, create a yaml configuration file. The default location for this file is :file:`/etc/ansible/plugin_filters.yml`, or you can select a different path for the blacklist file using the :ref:`PLUGIN_FILTERS_CFG` setting in the ``defaults`` section of your ansible.cfg. Here is an example blacklist file:
|
||||
|
||||
.. code-block:: YAML
|
||||
|
||||
|
|
@ -20,12 +17,10 @@ in ``defaults`` section to change this configuration file path. The format of th
|
|||
|
||||
The file contains two fields:
|
||||
|
||||
* a version so that it will be possible to update the format while keeping backwards
|
||||
compatibility in the future. The present version should be the string, ``"1.0"``
|
||||
* A file version so that you can update the format while keeping backwards compatibility in the future. The present version should be the string, ``"1.0"``
|
||||
|
||||
* a list of modules to blacklist. Any module listed here will not be found by Ansible when it
|
||||
searches for a module to invoke for a task.
|
||||
* A list of modules to blacklist. Any module in this list will not be loaded by Ansible when it searches for a module to invoke for a task.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``stat`` module is required for Ansible to run. So, please make sure you do not add this module in a blacklist modules list.
|
||||
You cannot blacklist the ``stat`` module, as it is required for Ansible to run.
|
||||
|
|
|
|||
|
|
@ -1,150 +1,329 @@
|
|||
.. _vault:
|
||||
|
||||
Ansible Vault
|
||||
=============
|
||||
*************************************
|
||||
Encrypting content with Ansible Vault
|
||||
*************************************
|
||||
|
||||
.. contents:: Topics
|
||||
Ansible Vault encrypts variables and files so you can protect sensitive content such as passwords or keys rather than leaving it visible as plaintext in playbooks or roles. To use Ansible Vault you need one or more passwords to encrypt and decrypt content. If you store your vault passwords in a third-party tool such as a secret manager, you need a script to access them. Use the passwords with the :ref:`ansible-vault` command-line tool to create and view encrypted variables, create encrypted files, encrypt existing files, or edit, re-key, or decrypt files. You can then place encrypted content under source control and share it more safely.
|
||||
|
||||
Ansible Vault is a feature of ansible that allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plaintext in playbooks or roles. These vault files can then be distributed or placed in source control.
|
||||
.. warning::
|
||||
* Encryption with Ansible Vault ONLY protects 'data at rest'. Once the content is decrypted ('data in use'), play and plugin authors are responsible for avoiding any secret disclosure, see :ref:`no_log <keep_secret_data>` for details on hiding output.
|
||||
|
||||
To enable this feature, a command line tool - :ref:`ansible-vault` - is used to edit files, and a command line flag (:option:`--ask-vault-pass <ansible-playbook --ask-vault-pass>`, :option:`--vault-password-file <ansible-playbook --vault-password-file>` or :option:`--vault-id <ansible-playbook --vault-id>`) is used. Alternately, you may specify the location of a password file or command Ansible to always prompt for the password in your ansible.cfg file. These options require no command line flag usage.
|
||||
You can use encrypted variables and files in ad-hoc commands and playbooks by supplying the passwords you used to encrypt them. You can modify your ``ansible.cfg`` file to specify the location of a password file or to always prompt for the password.
|
||||
|
||||
For best practices advice, refer to :ref:`best_practices_for_variables_and_vaults`.
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
.. _what_can_be_encrypted_with_vault:
|
||||
Managing vault passwords
|
||||
========================
|
||||
|
||||
What Can Be Encrypted With Vault
|
||||
````````````````````````````````
|
||||
Managing your encrypted content is easier if you develop a strategy for managing your vault passwords. A vault password can be any string you choose. There is no special command to create a vault password. However, you need to keep track of your vault passwords. Each time you encrypt a variable or file with Ansible Vault, you must provide a password. When you use an encrypted variable or file in a command or playbook, you must provide the same password that was used to encrypt it. To develop a strategy for managing vault passwords, start with two questions:
|
||||
|
||||
File-level encryption
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
* Do you want to encrypt all your content with the same password, or use different passwords for different needs?
|
||||
* Where do you want to store your password or passwords?
|
||||
|
||||
Ansible Vault can encrypt any structured data file used by Ansible.
|
||||
Choosing between a single password and multiple passwords
|
||||
---------------------------------------------------------
|
||||
|
||||
This can include "group_vars/" or "host_vars/" inventory variables, variables loaded by "include_vars" or "vars_files", or variable files passed on the ansible-playbook command line with ``-e @file.yml`` or ``-e @file.json``. Role variables and defaults are also included.
|
||||
|
||||
Ansible tasks, handlers, and so on are also data so these can be encrypted with vault as well. To hide the names of variables that you're using, you can encrypt the task files in their entirety.
|
||||
|
||||
Ansible Vault can also encrypt arbitrary files, even binary files. If a vault-encrypted file is
|
||||
given as the ``src`` argument to the :ref:`copy <copy_module>`, :ref:`template <template_module>`,
|
||||
:ref:`unarchive <unarchive_module>`, :ref:`script <script_module>` or :ref:`assemble
|
||||
<assemble_module>` modules, the file will be placed at the destination on the target host decrypted
|
||||
(assuming a valid vault password is supplied when running the play).
|
||||
|
||||
.. note::
|
||||
The advantages of file-level encryption are that it is easy to use and that password rotation is straightforward with :ref:`rekeying <rekeying_files>`.
|
||||
The drawback is that the contents of files are no longer easy to access and read. This may be problematic if it is a list of tasks (when encrypting a variables file, :ref:`best practice <best_practices_for_variables_and_vaults>` is to keep references to these variables in a non-encrypted file).
|
||||
|
||||
|
||||
Variable-level encryption
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Ansible also supports encrypting single values inside a YAML file, using the `!vault` tag to let YAML and Ansible know it uses special processing. This feature is covered in more detail :ref:`below <encrypt_string_for_use_in_yaml>`.
|
||||
|
||||
.. note::
|
||||
The advantage of variable-level encryption is that files are still easily legible even if they mix plaintext and encrypted variables.
|
||||
The drawback is that password rotation is not as simple as with file-level encryption: the :ref:`rekey <ansible_vault_rekey>` command does not work with this method.
|
||||
If you have a small team or few sensitive values, you can use a single password for everything you encrypt with Ansible Vault. Store your vault password securely in a file or a secret manager as described below.
|
||||
|
||||
If you have a larger team or many sensitive values, you can use multiple passwords. For example, you can use different passwords for different users or different levels of access. Depending on your needs, you might want a different password for each encrypted file, for each directory, or for each environment. For example, you might have a playbook that includes two vars files, one for the dev environment and one for the production environment, encrypted with two different passwords. When you run the playbook, select the correct vault password for the environment you are targeting, using a vault ID.
|
||||
|
||||
.. _vault_ids:
|
||||
|
||||
Vault IDs and Multiple Vault Passwords
|
||||
``````````````````````````````````````
|
||||
Managing multiple passwords with vault IDs
|
||||
------------------------------------------
|
||||
|
||||
If you use multiple vault passwords, you can differentiate one password from another with vault IDs. You use the vault ID in three ways:
|
||||
|
||||
A vault ID is an identifier for one or more vault secrets;
|
||||
Ansible supports multiple vault passwords.
|
||||
* Pass it with :option:`--vault-id <ansible-playbook --vault-id>` to the :ref:`ansible-vault` command when you create encrypted content
|
||||
* Include it wherever you store the password for that vault ID (see :ref:`storing_vault_passwords`)
|
||||
* Pass it with :option:`--vault-id <ansible-playbook --vault-id>` to the :ref:`ansible-playbook` command when you run a playbook that uses content you encrypted with that vault ID
|
||||
|
||||
Vault IDs provide labels to distinguish between individual vault passwords.
|
||||
When you pass a vault ID as an option to the :ref:`ansible-vault` command, you add a label (a hint or nickname) to the encrypted content. This label documents which password you used to encrypt it. The encrypted variable or file includes the vault ID label in plain text in the header. The vault ID is the last element before the encrypted content. For example::
|
||||
|
||||
To use vault IDs, you must provide an ID *label* of your choosing and a *source* to obtain its password (either ``prompt`` or a file path):
|
||||
my_encrytped_var: !vault |
|
||||
$ANSIBLE_VAULT;1.2;AES256;dev
|
||||
30613233633461343837653833666333643061636561303338373661313838333565653635353162
|
||||
3263363434623733343538653462613064333634333464660a663633623939393439316636633863
|
||||
61636237636537333938306331383339353265363239643939666639386530626330633337633833
|
||||
6664656334373166630a363736393262666465663432613932613036303963343263623137386239
|
||||
6330
|
||||
|
||||
In addition to the label, you must provide a source for the related password. The source can be a prompt, a file, or a script, depending on how you are storing your vault passwords. The pattern looks like this:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
--vault-id label@source
|
||||
|
||||
This switch is available for all Ansible commands that can interact with vaults: :ref:`ansible-vault`, :ref:`ansible-playbook`, etc.
|
||||
If your playbook uses multiple encrypted variables or files that you encrypted with different passwords, you must pass the vault IDs when you run that playbook. You can use :option:`--vault-id <ansible-playbook --vault-id>` by itself, with :option:`--vault-password-file <ansible-playbook --vault-password-file>`, or with :option:`--ask-vault-pass <ansible-playbook --ask-vault-pass>`. The pattern is the same as when you create encrypted content: include the label and the source for the matching password.
|
||||
|
||||
Vault-encrypted content can specify which vault ID it was encrypted with.
|
||||
See below for examples of encrypting content with vault IDs and using content encrypted with vault IDs. The :option:`--vault-id <ansible-playbook --vault-id>` option works with any Ansible command that interacts with vaults, including :ref:`ansible-vault`, :ref:`ansible-playbook`, and so on.
|
||||
|
||||
For example, a playbook can now include a vars file encrypted with a 'dev' vault
|
||||
ID and a 'prod' vault ID.
|
||||
Limitations of vault IDs
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. note:
|
||||
Older versions of Ansible, before 2.4, only supported using one single vault password at a time.
|
||||
Ansible does not enforce using the same password every time you use a particular vault ID label. You can encrypt different variables or files with the same vault ID label but different passwords. This usually happens when you type the password at a prompt and make a mistake. It is possible to use different passwords with the same vault ID label on purpose. For example, you could use each label as a reference to a class of passwords, rather than a single password. In this scenario, you must always know which specific password or file to use in context. However, you are more likely to encrypt two files with the same vault ID label and different passwords by mistake. If you encrypt two files with the same label but different passwords by accident, you can :ref:`rekey <rekeying_files>` one file to fix the issue.
|
||||
|
||||
Enforcing vault ID matching
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
By default the vault ID label is only a hint to remind you which password you used to encrypt a variable or file. Ansible does not check that the vault ID in the header of the encrypted content matches the vault ID you provide when you use the content. Ansible decrypts all files and variables called by your command or playbook that are encrypted with the password you provide. To check the encrypted content and decrypt it only when the vault ID it contains matches the one you provide with ``--vault-id``, set the config option :ref:`DEFAULT_VAULT_ID_MATCH`. When you set :ref:`DEFAULT_VAULT_ID_MATCH`, each password is only used to decrypt data that was encrypted with the same label. This is efficient, predictable, and can reduce errors when different values are encrypted with different passwords.
|
||||
|
||||
.. note::
|
||||
Even with the :ref:`DEFAULT_VAULT_ID_MATCH` setting enabled, Ansible does not enforce using the same password every time you use a particular vault ID label.
|
||||
|
||||
.. _storing_vault_passwords:
|
||||
|
||||
Storing and accessing vault passwords
|
||||
-------------------------------------
|
||||
|
||||
You can memorize your vault password, or manually copy vault passwords from any source and paste them at a command-line prompt, but most users store them securely and access them as needed from within Ansible. You have two options for storing vault passwords that work from within Ansible: in files, or in a third-party tool such as the system keyring or a secret manager. If you store your passwords in a third-party tool, you need a vault password client script to retrieve them from within Ansible.
|
||||
|
||||
Storing passwords in files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To store a vault password in a file, enter the password as a string on a single line in the file. Make sure the permissions on the file are appropriate. Do not add password files to source control. If you have multiple passwords, you can store them all in a single file, as long as they all have vault IDs. For each password, create a separate line and enter the vault ID, a space, then the password as a string. For example:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
dev my_dev_pass
|
||||
test my_test_pass
|
||||
prod my_prod_pass
|
||||
|
||||
|
||||
.. _vault_password_client_scripts:
|
||||
|
||||
Storing passwords in third-party tools with vault password client scripts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You can store your vault passwords on the system keyring, in a database, or in a secret manager and retrieve them from within Ansible using a vault password client script. Enter the password as a string on a single line. If your password has a vault ID, store it in a way that works with your password storage tool.
|
||||
|
||||
To create a vault password client script:
|
||||
|
||||
* Create a file with a name ending in ``-client.py``
|
||||
* Make the file executable
|
||||
* Within the script itself:
|
||||
* Print the passwords to standard output
|
||||
* Accept a ``--vault-id`` option
|
||||
* If the script prompts for data (for example, a database password), send the prompts to standard error
|
||||
|
||||
When you run a playbook that uses vault passwords stored in a third-party tool, specify the script as the source within the ``--vault-id`` flag. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --vault-id dev@contrib/vault/vault-keyring-client.py
|
||||
|
||||
Ansible executes the client script with a ``--vault-id`` option so the script knows which vault ID label you specified. For example a script loading passwords from a secret manager can use the vault ID label to pick either the 'dev' or 'prod' password. The example command above results in the following execution of the client script:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
contrib/vault/vault-keyring-client.py --vault-id dev
|
||||
|
||||
For an example of a client script that loads passwords from the system keyring, see :file:`contrib/vault/vault-keyring-client.py`.
|
||||
|
||||
|
||||
Encrypting content with Ansible Vault
|
||||
=====================================
|
||||
|
||||
Once you have a strategy for managing and storing vault passwords, you can start encrypting content. You can encrypt two types of content with Ansible Vault: variables and files. Encrypted content always includes the ``!vault`` tag, which tells Ansible and YAML that the content needs to be decrypted, and a ``|`` character, which allows multi-line strings. Encrypted content created with ``--vault-id`` also contains the vault ID label. For more details about the encryption process and the format of content encrypted with Ansible Vault, see :ref:`vault_format`. This table shows the main differences between encrypted variables and encrypted files:
|
||||
|
||||
.. table::
|
||||
:class: documentation-table
|
||||
|
||||
====================== ================================= ====================================
|
||||
.. Encrypted variables Encrypted files
|
||||
====================== ================================= ====================================
|
||||
How much is encrypted? Variables within a plaintext file The entire file
|
||||
|
||||
When is it decrypted? On demand, only when needed Whenever loaded or referenced [#f1]_
|
||||
|
||||
What can be encrypted? Only variables Any structured data file
|
||||
|
||||
====================== ================================= ====================================
|
||||
|
||||
.. [#f1] Ansible cannot know if it needs content from an encrypted file unless it decrypts the file, so it decrypts all encrypted files referenced in your playbooks and roles.
|
||||
|
||||
.. _encrypting_variables:
|
||||
.. _single_encrypted_variable:
|
||||
|
||||
Encrypting individual variables with Ansible Vault
|
||||
--------------------------------------------------
|
||||
|
||||
You can encrypt single values inside a YAML file using the :ref:`ansible-vault encrypt_string <ansible_vault_encrypt_string>` command. For one way to keep your vaulted variables safely visible, see :ref:`tip_for_variables_and_vaults`.
|
||||
|
||||
Advantages and disadvantages of encrypting variables
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
With variable-level encryption, your files are still easily legible. You can mix plaintext and encrypted variables, even inline in a play or role. However, password rotation is not as simple as with file-level encryption. You cannot :ref:`rekey <rekeying_files>` encrypted variables. Also, variable-level encryption only works on variables. If you want to encrypt tasks or other content, you must encrypt the entire file.
|
||||
|
||||
.. _encrypt_string_for_use_in_yaml:
|
||||
|
||||
Creating encrypted variables
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The :ref:`ansible-vault encrypt_string <ansible_vault_encrypt_string>` command encrypts and formats any string you type (or copy or generate) into a format that can be included in a playbook, role, or variables file. To create a basic encrypted variable, pass three options to the :ref:`ansible-vault encrypt_string <ansible_vault_encrypt_string>` command:
|
||||
|
||||
* a source for the vault password (prompt, file, or script, with or without a vault ID)
|
||||
* the string to encrypt
|
||||
* the string name (the name of the variable)
|
||||
|
||||
The pattern looks like this:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault encrypt_string <password_source> '<string_to_encrypt>' --name '<string_name_of_variable>'
|
||||
|
||||
For example, to encrypt the string 'foobar' using the only password stored in 'a_password_file' and name the variable 'the_secret':
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault encrypt_string --vault-password-file a_password_file 'foobar' --name 'the_secret'
|
||||
|
||||
The command above creates this content::
|
||||
|
||||
the_secret: !vault |
|
||||
$ANSIBLE_VAULT;1.1;AES256
|
||||
62313365396662343061393464336163383764373764613633653634306231386433626436623361
|
||||
6134333665353966363534333632666535333761666131620a663537646436643839616531643561
|
||||
63396265333966386166373632626539326166353965363262633030333630313338646335303630
|
||||
3438626666666137650a353638643435666633633964366338633066623234616432373231333331
|
||||
6564
|
||||
|
||||
To encrypt the string 'foooodev', add the vault ID label 'dev' with the 'dev' vault password stored in 'a_password_file', and call the encrypted variable 'the_dev_secret':
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault encrypt_string --vault-id dev@a_password_file 'foooodev' --name 'the_dev_secret'
|
||||
|
||||
The command above creates this content::
|
||||
|
||||
the_dev_secret: !vault |
|
||||
$ANSIBLE_VAULT;1.2;AES256;dev
|
||||
30613233633461343837653833666333643061636561303338373661313838333565653635353162
|
||||
3263363434623733343538653462613064333634333464660a663633623939393439316636633863
|
||||
61636237636537333938306331383339353265363239643939666639386530626330633337633833
|
||||
6664656334373166630a363736393262666465663432613932613036303963343263623137386239
|
||||
6330
|
||||
|
||||
To encrypt the string 'letmein' read from stdin, add the vault ID 'test' using the 'test' vault password stored in `a_password_file`, and name the variable 'test_db_password':
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
echo -n 'letmein' | ansible-vault encrypt_string --vault-id test@a_password_file --stdin-name 'test_db_password'
|
||||
|
||||
.. warning::
|
||||
|
||||
Typing secret content directly at the command line (without a prompt) leaves the secret string in your shell history. Do not do this outside of testing.
|
||||
|
||||
The command above creates this output::
|
||||
|
||||
Reading plaintext input from stdin. (ctrl-d to end input)
|
||||
db_password: !vault |
|
||||
$ANSIBLE_VAULT;1.2;AES256;dev
|
||||
61323931353866666336306139373937316366366138656131323863373866376666353364373761
|
||||
3539633234313836346435323766306164626134376564330a373530313635343535343133316133
|
||||
36643666306434616266376434363239346433643238336464643566386135356334303736353136
|
||||
6565633133366366360a326566323363363936613664616364623437336130623133343530333739
|
||||
3039
|
||||
|
||||
To be prompted for a string to encrypt, encrypt it with the 'dev' vault password from 'a_password_file', name the variable 'new_user_password' and give it the vault ID label 'dev':
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault encrypt_string --vault-id dev@a_password_file --stdin-name 'new_user_password'
|
||||
|
||||
The command above triggers this prompt:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Reading plaintext input from stdin. (ctrl-d to end input)
|
||||
|
||||
Type the string to encrypt (for example, 'hunter2'), hit ctrl-d, and wait.
|
||||
|
||||
.. warning::
|
||||
|
||||
Do not press ``Enter`` after supplying the string to encrypt. That will add a newline to the encrypted value.
|
||||
|
||||
The sequence above creates this output::
|
||||
|
||||
new_user_password: !vault |
|
||||
$ANSIBLE_VAULT;1.2;AES256;dev
|
||||
37636561366636643464376336303466613062633537323632306566653533383833366462366662
|
||||
6565353063303065303831323539656138653863353230620a653638643639333133306331336365
|
||||
62373737623337616130386137373461306535383538373162316263386165376131623631323434
|
||||
3866363862363335620a376466656164383032633338306162326639643635663936623939666238
|
||||
3161
|
||||
|
||||
You can add the output from any of the examples above to any playbook, variables file, or role for future use. Encrypted variables are larger than plain-text variables, but they protect your sensitive content while leaving the rest of the playbook, variables file, or role in plain text so you can easily read it.
|
||||
|
||||
Viewing encrypted variables
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You can view the original value of an encrypted variable using the debug module. You must pass the password that was used to encrypt the variable. For example, if you stored the variable created by the last example above in a file called 'vars.yml', you could view the unencrypted value of that variable like this:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
ansible localhost -m debug -a var="new_user_password" -e "@vars.yml" --vault-id dev@a_password_file
|
||||
|
||||
localhost | SUCCESS => {
|
||||
"new_user_password": "hunter2"
|
||||
}
|
||||
|
||||
|
||||
Encrypting files with Ansible Vault
|
||||
-----------------------------------
|
||||
|
||||
Ansible Vault can encrypt any structured data file used by Ansible, including:
|
||||
|
||||
* group variables files from inventory
|
||||
* host variables files from inventory
|
||||
* variables files passed to ansible-playbook with ``-e @file.yml`` or ``-e @file.json``
|
||||
* variables files loaded by ``include_vars`` or ``vars_files``
|
||||
* variables files in roles
|
||||
* defaults files in roles
|
||||
* tasks files
|
||||
* handlers files
|
||||
* binary files or other arbitrary files
|
||||
|
||||
The full file is encrypted in the vault.
|
||||
|
||||
Advantages and disadvantages of encrypting files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
File-level encryption is easy to use. Password rotation for encrypted files is straightforward with the :ref:`rekey <rekeying_files>` command. Encrypting files can hide not only sensitive values, but the names of the variables you use. However, with file-level encryption the contents of files are no longer easy to access and read. This may be a problem with encrypted tasks files. When encrypting a variables file, see :ref:`tip_for_variables_and_vaults` for one way to keep references to these variables in a non-encrypted file. Ansible always decrypts the entire encrypted file when it is when loaded or referenced, because Ansible cannot know if it needs the content unless it decrypts it.
|
||||
|
||||
.. _creating_files:
|
||||
|
||||
Creating Encrypted Files
|
||||
````````````````````````
|
||||
Creating encrypted files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To create a new encrypted data file, run the following command:
|
||||
To create a new encrypted data file called 'foo.yml' with the 'test' vault password from 'multi_password_file':
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault create foo.yml
|
||||
ansible-vault create --vault-id test@multi_password_file foo.yml
|
||||
|
||||
First you will be prompted for a password. After providing a password, the tool will launch whatever editor you have defined with $EDITOR, and defaults to vi. Once you are done with the editor session, the file will be saved as encrypted data.
|
||||
The tool launches an editor (whatever editor you have defined with $EDITOR, default editor is vi). Add the content. When you close the the editor session, the file is saved as encrypted data. The file header reflects the vault ID used to create it:
|
||||
|
||||
The default cipher is AES (which is shared-secret based).
|
||||
.. code-block:: text
|
||||
|
||||
To create a new encrypted data file with the Vault ID 'password1' assigned to it and be prompted for the password, run:
|
||||
``$ANSIBLE_VAULT;1.2;AES256;test``
|
||||
|
||||
To create a new encrypted data file with the vault ID 'my_new_password' assigned to it and be prompted for the password:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault create --vault-id password1@prompt foo.yml
|
||||
ansible-vault create --vault-id my_new_password@prompt foo.yml
|
||||
|
||||
|
||||
.. _editing_encrypted_files:
|
||||
|
||||
Editing Encrypted Files
|
||||
```````````````````````
|
||||
|
||||
To edit an encrypted file in place, use the :ref:`ansible-vault edit <ansible_vault_edit>` command.
|
||||
This command will decrypt the file to a temporary file and allow you to edit
|
||||
the file, saving it back when done and removing the temporary file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault edit foo.yml
|
||||
|
||||
To edit a file encrypted with the 'vault2' password file and assigned the 'pass2' vault ID:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault edit --vault-id pass2@vault2 foo.yml
|
||||
|
||||
|
||||
.. _rekeying_files:
|
||||
|
||||
Rekeying Encrypted Files
|
||||
````````````````````````
|
||||
|
||||
Should you wish to change your password on a vault-encrypted file or files, you can do so with the rekey command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault rekey foo.yml bar.yml baz.yml
|
||||
|
||||
This command can rekey multiple data files at once and will ask for the original
|
||||
password and also the new password.
|
||||
|
||||
To rekey files encrypted with the 'preprod2' vault ID and the 'ppold' file and be prompted for the new password:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault rekey --vault-id preprod2@ppold --new-vault-id preprod2@prompt foo.yml bar.yml baz.yml
|
||||
|
||||
A different ID could have been set for the rekeyed files by passing it to ``--new-vault-id``.
|
||||
Again, add content to the file in the editor and save. Be sure to store the new password you created at the prompt, so you can find it when you want to decrypt that file.
|
||||
|
||||
.. _encrypting_files:
|
||||
|
||||
Encrypting Unencrypted Files
|
||||
````````````````````````````
|
||||
Encrypting existing files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you have existing files that you wish to encrypt, use
|
||||
the :ref:`ansible-vault encrypt <ansible_vault_encrypt>` command. This command can operate on multiple files at once:
|
||||
To encrypt an existing file, use the :ref:`ansible-vault encrypt <ansible_vault_encrypt>` command. This command can operate on multiple files at once. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -156,190 +335,105 @@ To encrypt existing files with the 'project' ID and be prompted for the password
|
|||
|
||||
ansible-vault encrypt --vault-id project@prompt foo.yml bar.yml baz.yml
|
||||
|
||||
.. note::
|
||||
|
||||
It is technically possible to separately encrypt files or strings with the *same* vault ID but *different* passwords, if different password files or prompted passwords are provided each time.
|
||||
This could be desirable if you use vault IDs as references to classes of passwords (rather than a single password) and you always know which specific password or file to use in context. However this may be an unnecessarily complex use-case.
|
||||
If two files are encrypted with the same vault ID but different passwords by accident, you can use the :ref:`rekey <rekeying_files>` command to fix the issue.
|
||||
|
||||
|
||||
.. _decrypting_files:
|
||||
|
||||
Decrypting Encrypted Files
|
||||
``````````````````````````
|
||||
|
||||
If you have existing files that you no longer want to keep encrypted, you can permanently decrypt
|
||||
them by running the :ref:`ansible-vault decrypt <ansible_vault_decrypt>` command. This command will save them unencrypted
|
||||
to the disk, so be sure you do not want :ref:`ansible-vault edit <ansible_vault_edit>` instead:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault decrypt foo.yml bar.yml baz.yml
|
||||
|
||||
|
||||
.. _viewing_files:
|
||||
|
||||
Viewing Encrypted Files
|
||||
```````````````````````
|
||||
Viewing encrypted files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you want to view the contents of an encrypted file without editing it, you can use the :ref:`ansible-vault view <ansible_vault_view>` command:
|
||||
To view the contents of an encrypted file without editing it, you can use the :ref:`ansible-vault view <ansible_vault_view>` command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault view foo.yml bar.yml baz.yml
|
||||
|
||||
|
||||
.. _encrypt_string_for_use_in_yaml:
|
||||
.. _editing_encrypted_files:
|
||||
|
||||
Use encrypt_string to create encrypted variables to embed in yaml
|
||||
`````````````````````````````````````````````````````````````````
|
||||
Editing encrypted files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The :ref:`ansible-vault encrypt_string <ansible_vault_encrypt_string>` command will encrypt and format a provided string into a format
|
||||
that can be included in :ref:`ansible-playbook` YAML files.
|
||||
|
||||
To encrypt a string provided as a cli arg:
|
||||
To edit an encrypted file in place, use the :ref:`ansible-vault edit <ansible_vault_edit>` command. This command decrypts the file to a temporary file, allows you to edit the content, then saves and re-encrypts the content and removes the temporary file when you close the editor. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault encrypt_string --vault-password-file a_password_file 'foobar' --name 'the_secret'
|
||||
ansible-vault edit foo.yml
|
||||
|
||||
Result::
|
||||
|
||||
the_secret: !vault |
|
||||
$ANSIBLE_VAULT;1.1;AES256
|
||||
62313365396662343061393464336163383764373764613633653634306231386433626436623361
|
||||
6134333665353966363534333632666535333761666131620a663537646436643839616531643561
|
||||
63396265333966386166373632626539326166353965363262633030333630313338646335303630
|
||||
3438626666666137650a353638643435666633633964366338633066623234616432373231333331
|
||||
6564
|
||||
|
||||
To use a vault-id label for 'dev' vault-id:
|
||||
To edit a file encrypted with the ``vault2`` password file and assigned the vault ID ``pass2``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault encrypt_string --vault-id dev@a_password_file 'foooodev' --name 'the_dev_secret'
|
||||
ansible-vault edit --vault-id pass2@vault2 foo.yml
|
||||
|
||||
Result::
|
||||
|
||||
the_dev_secret: !vault |
|
||||
$ANSIBLE_VAULT;1.2;AES256;dev
|
||||
30613233633461343837653833666333643061636561303338373661313838333565653635353162
|
||||
3263363434623733343538653462613064333634333464660a663633623939393439316636633863
|
||||
61636237636537333938306331383339353265363239643939666639386530626330633337633833
|
||||
6664656334373166630a363736393262666465663432613932613036303963343263623137386239
|
||||
6330
|
||||
.. _rekeying_files:
|
||||
|
||||
To encrypt a string read from stdin and name it 'db_password':
|
||||
Changing the password and/or vault ID on encrypted files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To change the password on an encrypted file or files, use the :ref:`rekey <ansible_vault_rekey>` command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
echo -n 'letmein' | ansible-vault encrypt_string --vault-id dev@a_password_file --stdin-name 'db_password'
|
||||
|
||||
.. warning::
|
||||
|
||||
This method leaves the string in your shell history. Do not use it outside of testing.
|
||||
|
||||
Result::
|
||||
|
||||
Reading plaintext input from stdin. (ctrl-d to end input)
|
||||
db_password: !vault |
|
||||
$ANSIBLE_VAULT;1.2;AES256;dev
|
||||
61323931353866666336306139373937316366366138656131323863373866376666353364373761
|
||||
3539633234313836346435323766306164626134376564330a373530313635343535343133316133
|
||||
36643666306434616266376434363239346433643238336464643566386135356334303736353136
|
||||
6565633133366366360a326566323363363936613664616364623437336130623133343530333739
|
||||
3039
|
||||
|
||||
To be prompted for a string to encrypt, encrypt it, and give it the name 'new_user_password':
|
||||
ansible-vault rekey foo.yml bar.yml baz.yml
|
||||
|
||||
This command can rekey multiple data files at once and will ask for the original password and also the new password. To set a different ID for the rekeyed files, pass the new ID to ``--new-vault-id``. For example, to rekey a list of files encrypted with the 'preprod1' vault ID from the 'ppold' file to the 'preprod2' vault ID and be prompted for the new password:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault encrypt_string --vault-id dev@a_password_file --stdin-name 'new_user_password'
|
||||
|
||||
Output::
|
||||
|
||||
Reading plaintext input from stdin. (ctrl-d to end input)
|
||||
|
||||
User enters 'hunter2' and hits ctrl-d.
|
||||
|
||||
.. warning::
|
||||
|
||||
Do not press Enter after supplying the string. That will add a newline to the encrypted value.
|
||||
|
||||
Result::
|
||||
|
||||
new_user_password: !vault |
|
||||
$ANSIBLE_VAULT;1.2;AES256;dev
|
||||
37636561366636643464376336303466613062633537323632306566653533383833366462366662
|
||||
6565353063303065303831323539656138653863353230620a653638643639333133306331336365
|
||||
62373737623337616130386137373461306535383538373162316263386165376131623631323434
|
||||
3866363862363335620a376466656164383032633338306162326639643635663936623939666238
|
||||
3161
|
||||
|
||||
See also :ref:`single_encrypted_variable`
|
||||
|
||||
After you added the encrypted value to a var file (vars.yml), you can see the original value using the debug module.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
ansible localhost -m debug -a var="new_user_password" -e "@vars.yml" --ask-vault-pass
|
||||
Vault password:
|
||||
|
||||
localhost | SUCCESS => {
|
||||
"new_user_password": "hunter2"
|
||||
}
|
||||
ansible-vault rekey --vault-id preprod1@ppold --new-vault-id preprod2@prompt foo.yml bar.yml baz.yml
|
||||
|
||||
|
||||
.. _decrypting_files:
|
||||
|
||||
Decrypting encrypted files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you have an encrypted file that you no longer want to keep encrypted, you can permanently decrypt it by running the :ref:`ansible-vault decrypt <ansible_vault_decrypt>` command. This command will save the file unencrypted to the disk, so be sure you do not want to :ref:`edit <ansible_vault_edit>` it instead.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-vault decrypt foo.yml bar.yml baz.yml
|
||||
|
||||
|
||||
.. _playbooks_vault:
|
||||
.. _providing_vault_passwords:
|
||||
|
||||
Providing Vault Passwords
|
||||
`````````````````````````
|
||||
Using encrypted variables and files
|
||||
===================================
|
||||
|
||||
When all data is encrypted using a single password the :option:`--ask-vault-pass <ansible-playbook --ask-vault-pass>`
|
||||
or :option:`--vault-password-file <ansible-playbook --vault-password-file>` cli options should be used.
|
||||
When you run a task or playbook that uses encrypted variables or files, you must provide the passwords to decrypt the variables or files. You can do this at the command line or in the playbook itself.
|
||||
|
||||
For example, to use a password store in the text file :file:`/path/to/my/vault-password-file`:
|
||||
Passing a single password
|
||||
-------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
If all the encrypted variables and files your task or playbook needs use a single password, you can use the :option:`--ask-vault-pass <ansible-playbook --ask-vault-pass>` or :option:`--vault-password-file <ansible-playbook --vault-password-file>` cli options.
|
||||
|
||||
ansible-playbook --vault-password-file /path/to/my/vault-password-file site.yml
|
||||
|
||||
To prompt for a password:
|
||||
To prompt for the password:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --ask-vault-pass site.yml
|
||||
|
||||
To get the password from a vault password executable script :file:`my-vault-password.py`:
|
||||
To retrieve the password from the :file:`/path/to/my/vault-password-file` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --vault-password-file my-vault-password.py
|
||||
ansible-playbook --vault-password-file /path/to/my/vault-password-file site.yml
|
||||
|
||||
The config option :ref:`DEFAULT_VAULT_PASSWORD_FILE` can be used to specify a vault password file so that the
|
||||
:option:`--vault-password-file <ansible-playbook --vault-password-file>` cli option does not have to be
|
||||
specified every time.
|
||||
To get the password from the vault password client script :file:`my-vault-password-client.py`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --vault-password-file my-vault-password-client.py
|
||||
|
||||
|
||||
.. _specifying_vault_ids:
|
||||
|
||||
Labelling Vaults
|
||||
^^^^^^^^^^^^^^^^
|
||||
Passing vault IDs
|
||||
-----------------
|
||||
|
||||
Since Ansible 2.4 the :option:`--vault-id <ansible-playbook --vault-id>` can be used to indicate which vault ID
|
||||
('dev', 'prod', 'cloud', etc) a password is for as well as how to source the password (prompt, a file path, etc).
|
||||
|
||||
By default the vault-id label is only a hint, any values encrypted with the password will be decrypted.
|
||||
The config option :ref:`DEFAULT_VAULT_ID_MATCH` can be set to require the vault id to match the vault ID
|
||||
used when the value was encrypted.
|
||||
This can reduce errors when different values are encrypted with different passwords.
|
||||
|
||||
For example, to use a password file :file:`dev-password` for the vault-id 'dev':
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --vault-id dev@dev-password site.yml
|
||||
You can also use the :option:`--vault-id <ansible-playbook --vault-id>` option to pass a single password with its vault label. This approach is clearer when multiple vaults are used within a single inventory.
|
||||
|
||||
To prompt for the password for the 'dev' vault ID:
|
||||
|
||||
|
|
@ -347,20 +441,35 @@ To prompt for the password for the 'dev' vault ID:
|
|||
|
||||
ansible-playbook --vault-id dev@prompt site.yml
|
||||
|
||||
To get the 'dev' vault ID password from an executable script :file:`my-vault-password.py`:
|
||||
To retrieve the password for the 'dev' vault ID from the :file:`dev-password` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --vault-id dev@my-vault-password.py
|
||||
ansible-playbook --vault-id dev@dev-password site.yml
|
||||
|
||||
To get the password for the 'dev' vault ID from the vault password client script :file:`my-vault-password-client.py`:
|
||||
|
||||
The config option :ref:`DEFAULT_VAULT_IDENTITY_LIST` can be used to specify a default vault ID and password source
|
||||
so that the :option:`--vault-id <ansible-playbook --vault-id>` cli option does not have to be specified every time.
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --vault-id dev@my-vault-password-client.py
|
||||
|
||||
The :option:`--vault-id <ansible-playbook --vault-id>` option can also be used without specifying a vault-id.
|
||||
This behaviour is equivalent to :option:`--ask-vault-pass <ansible-playbook --ask-vault-pass>` or
|
||||
:option:`--vault-password-file <ansible-playbook --vault-password-file>` so is rarely used.
|
||||
Passing multiple vault passwords
|
||||
--------------------------------
|
||||
|
||||
If your task or playbook requires multiple encrypted variables or files that you encrypted with different vault IDs, you must use the :option:`--vault-id <ansible-playbook --vault-id>` option, passing multiple ``--vault-id`` options to specify the vault IDs ('dev', 'prod', 'cloud', 'db') and sources for the passwords (prompt, file, script). . For example, to use a 'dev' password read from a file and to be prompted for the 'prod' password:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --vault-id dev@dev-password --vault-id prod@prompt site.yml
|
||||
|
||||
By default the vault ID labels (dev, prod etc.) are only hints. Ansible attempts to decrypt vault content with each password. The password with the same label as the encrypted data will be tried first, after that each vault secret will be tried in the order they were provided on the command line.
|
||||
|
||||
Where the encrypted data has no label, or the label does not match any of the provided labels, the passwords will be tried in the order they are specified. In the example above, the 'dev' password will be tried first, then the 'prod' password for cases where Ansible doesn't know which vault ID is used to encrypt something.
|
||||
|
||||
Using ``--vault-id`` without a vault ID
|
||||
---------------------------------------
|
||||
|
||||
The :option:`--vault-id <ansible-playbook --vault-id>` option can also be used without specifying a vault-id. This behavior is equivalent to :option:`--ask-vault-pass <ansible-playbook --ask-vault-pass>` or :option:`--vault-password-file <ansible-playbook --vault-password-file>` so is rarely used.
|
||||
|
||||
For example, to use a password file :file:`dev-password`:
|
||||
|
||||
|
|
@ -374,89 +483,35 @@ To prompt for the password:
|
|||
|
||||
ansible-playbook --vault-id @prompt site.yml
|
||||
|
||||
To get the password from an executable script :file:`my-vault-password.py`:
|
||||
To get the password from an executable script :file:`my-vault-password-client.py`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --vault-id my-vault-password.py
|
||||
|
||||
.. note::
|
||||
Prior to Ansible 2.4, the :option:`--vault-id <ansible-playbook --vault-id>` option is not supported
|
||||
so :option:`--ask-vault-pass <ansible-playbook --ask-vault-pass>` or
|
||||
:option:`--vault-password-file <ansible-playbook --vault-password-file>` must be used.
|
||||
ansible-playbook --vault-id my-vault-password-client.py
|
||||
|
||||
|
||||
Multiple Vault Passwords
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Configuring defaults for using encrypted content
|
||||
================================================
|
||||
|
||||
Ansible 2.4 and later support using multiple vault passwords, :option:`--vault-id <ansible-playbook --vault-id>` can
|
||||
be provided multiple times.
|
||||
Setting a default vault ID
|
||||
--------------------------
|
||||
|
||||
For example, to use a 'dev' password read from a file and to be prompted for the 'prod' password:
|
||||
If you use one vault ID more frequently than any other, you can set the config option :ref:`DEFAULT_VAULT_IDENTITY_LIST` to specify a default vault ID and password source. Ansible will use the default vault ID and source any time you do not specify :option:`--vault-id <ansible-playbook --vault-id>`. You can set multiple values for this option. Setting multiple values is equivalent to passing multiple :option:`--vault-id <ansible-playbook --vault-id>` cli options.
|
||||
|
||||
.. code-block:: bash
|
||||
Setting a default password source
|
||||
---------------------------------
|
||||
|
||||
ansible-playbook --vault-id dev@dev-password --vault-id prod@prompt site.yml
|
||||
If you use one vault password file more frequently than any other, you can set the :ref:`DEFAULT_VAULT_PASSWORD_FILE` config option or the :envvar:`ANSIBLE_VAULT_PASSWORD_FILE` environment variable to specify that file. For example, if you set ``ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass.txt``, Ansible will automatically search for the password in that file. This is useful if, for example, you use Ansible from a continuous integration system such as Jenkins.
|
||||
|
||||
By default the vault ID labels (dev, prod etc.) are only hints, Ansible will attempt to decrypt vault content
|
||||
with each password. The password with the same label as the encrypted data will be tried first, after that
|
||||
each vault secret will be tried in the order they were provided on the command line.
|
||||
|
||||
Where the encrypted data doesn't have a label, or the label doesn't match any of the provided labels, the
|
||||
passwords will be tried in the order they are specified.
|
||||
|
||||
In the above case, the 'dev' password will be tried first, then the 'prod' password for cases
|
||||
where Ansible doesn't know which vault ID is used to encrypt something.
|
||||
|
||||
To add a vault ID label to the encrypted data use the :option:`--vault-id <ansible-vault-create --vault-id>` option
|
||||
with a label when encrypting the data.
|
||||
|
||||
The :ref:`DEFAULT_VAULT_ID_MATCH` config option can be set so that Ansible will only use the password with
|
||||
the same label as the encrypted data. This is more efficient and may be more predictable when multiple
|
||||
passwords are used.
|
||||
|
||||
The config option :ref:`DEFAULT_VAULT_IDENTITY_LIST` can have multiple values which is equivalent to multiple :option:`--vault-id <ansible-playbook --vault-id>` cli options.
|
||||
|
||||
The :option:`--vault-id <ansible-playbook --vault-id>` can be used in lieu of the :option:`--vault-password-file <ansible-playbook --vault-password-file>` or :option:`--ask-vault-pass <ansible-playbook --ask-vault-pass>` options,
|
||||
or it can be used in combination with them.
|
||||
|
||||
When using :ref:`ansible-vault` commands that encrypt content (:ref:`ansible-vault encrypt <ansible_vault_encrypt>`, :ref:`ansible-vault encrypt_string <ansible_vault_encrypt_string>`, etc)
|
||||
only one vault-id can be used.
|
||||
|
||||
|
||||
.. _vault_password_client_scripts:
|
||||
|
||||
Vault Password Client Scripts
|
||||
`````````````````````````````
|
||||
|
||||
When implementing a script to obtain a vault password it may be convenient to know which vault ID label was
|
||||
requested. For example a script loading passwords from a secret manager may want to use the vault ID label to pick
|
||||
either the 'dev' or 'prod' password.
|
||||
|
||||
Since Ansible 2.5 this is supported through the use of Client Scripts. A Client Script is an executable script
|
||||
with a name ending in ``-client``. Client Scripts are used to obtain vault passwords in the same way as any other
|
||||
executable script. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ansible-playbook --vault-id dev@contrib/vault/vault-keyring-client.py
|
||||
|
||||
The difference is in the implementation of the script. Client Scripts are executed with a ``--vault-id`` option
|
||||
so they know which vault ID label was requested. So the above Ansible execution results in the below execution
|
||||
of the Client Script:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
contrib/vault/vault-keyring-client.py --vault-id dev
|
||||
|
||||
:file:`contrib/vault/vault-keyring-client.py` is an example of Client Script that loads passwords from the
|
||||
system keyring.
|
||||
When are encrypted files made visible?
|
||||
======================================
|
||||
|
||||
In general, content you encrypt with Ansible Vault remains encrypted after execution. However, there is one exception. If you pass an encrypted file as the ``src`` argument to the :ref:`copy <copy_module>`, :ref:`template <template_module>`, :ref:`unarchive <unarchive_module>`, :ref:`script <script_module>` or :ref:`assemble <assemble_module>` module, the file will not be encrypted on the target host (assuming you supply the correct vault password when you run the play). This behavior is intended and useful. You can encrypt a configuration file or template to avoid sharing the details of your configuration, but when you copy that configuration to servers in your environment, you want it to be decrypted so local users and processes can access it.
|
||||
|
||||
.. _speeding_up_vault:
|
||||
|
||||
Speeding Up Vault Operations
|
||||
````````````````````````````
|
||||
Speeding up Ansible Vault
|
||||
=========================
|
||||
|
||||
If you have many encrypted files, decrypting them at startup may cause a perceptible delay. To speed this up, install the cryptography package:
|
||||
|
||||
|
|
@ -467,14 +522,10 @@ If you have many encrypted files, decrypting them at startup may cause a percept
|
|||
|
||||
.. _vault_format:
|
||||
|
||||
Vault Format
|
||||
````````````
|
||||
Format of files encrypted with Ansible Vault
|
||||
============================================
|
||||
|
||||
A vault encrypted file is a UTF-8 encoded txt file.
|
||||
|
||||
The file format includes a newline terminated header.
|
||||
|
||||
For example::
|
||||
Ansible Vault creates UTF-8 encoded txt files. The file format includes a newline terminated header. For example::
|
||||
|
||||
$ANSIBLE_VAULT;1.1;AES256
|
||||
|
||||
|
|
@ -482,25 +533,23 @@ or::
|
|||
|
||||
$ANSIBLE_VAULT;1.2;AES256;vault-id-label
|
||||
|
||||
The header contains the vault format id, the vault format version, the vault cipher, and a vault-id label (with format version 1.2), separated by semi-colons ';'
|
||||
The header contains up to four elements, separated by semi-colons (``;``).
|
||||
|
||||
The first field ``$ANSIBLE_VAULT`` is the format id. Currently ``$ANSIBLE_VAULT`` is the only valid file format id. This is used to identify files that are vault encrypted (via vault.is_encrypted_file()).
|
||||
1. The format ID (``$ANSIBLE_VAULT``). Currently ``$ANSIBLE_VAULT`` is the only valid format ID. The format ID identifies content that is encrypted with Ansible Vault (via vault.is_encrypted_file()).
|
||||
|
||||
The second field (``1.X``) is the vault format version. All supported versions of ansible will currently default to '1.1' or '1.2' if a labeled vault-id is supplied.
|
||||
2. The vault format version (``1.X``). All supported versions of Ansible will currently default to '1.1' or '1.2' if a labeled vault ID is supplied. The '1.0' format is supported for reading only (and will be converted automatically to the '1.1' format on write). The format version is currently used as an exact string compare only (version numbers are not currently 'compared').
|
||||
|
||||
The '1.0' format is supported for reading only (and will be converted automatically to the '1.1' format on write). The format version is currently used as an exact string compare only (version numbers are not currently 'compared').
|
||||
3. The cipher algorithm used to encrypt the data (``AES256``). Currently ``AES256`` is the only supported cipher algorithm. Vault format 1.0 used 'AES', but current code always uses 'AES256'.
|
||||
|
||||
The third field (``AES256``) identifies the cipher algorithm used to encrypt the data. Currently, the only supported cipher is 'AES256'. [vault format 1.0 used 'AES', but current code always uses 'AES256']
|
||||
4. The vault ID label used to encrypt the data (optional, ``vault-id-label``) For example, if you encrypt a file with ``--vault-id dev@prompt``, the vault-id-label is ``dev``.
|
||||
|
||||
The fourth field (``vault-id-label``) identifies the vault-id label used to encrypt the data. For example using a vault-id of ``dev@prompt`` results in a vault-id-label of 'dev' being used.
|
||||
|
||||
Note: In the future, the header could change. Anything after the vault id and version can be considered to depend on the vault format version. This includes the cipher id, and any additional fields that could be after that.
|
||||
Note: In the future, the header could change. Fields after the format ID and format version depend on the format version, and future vault format versions may add more cipher algorithm options and/or additional fields.
|
||||
|
||||
The rest of the content of the file is the 'vaulttext'. The vaulttext is a text armored version of the
|
||||
encrypted ciphertext. Each line will be 80 characters wide, except for the last line which may be shorter.
|
||||
encrypted ciphertext. Each line is 80 characters wide, except for the last line which may be shorter.
|
||||
|
||||
Vault Payload Format 1.1 - 1.2
|
||||
``````````````````````````````
|
||||
Ansible Vault payload format 1.1 - 1.2
|
||||
--------------------------------------
|
||||
|
||||
The vaulttext is a concatenation of the ciphertext and a SHA256 digest with the result 'hexlifyied'.
|
||||
|
||||
|
|
@ -537,5 +586,3 @@ hexlify()'ed result of:
|
|||
|
||||
- the original plaintext
|
||||
- padding up to the AES256 blocksize. (The data used for padding is based on `RFC5652 <https://tools.ietf.org/html/rfc5652#section-6.3>`_)
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -496,7 +496,7 @@ Setup IIS Website
|
|||
:ref:`playbooks_intro`
|
||||
An introduction to playbooks
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices advice
|
||||
Tips and tricks for playbooks
|
||||
:ref:`List of Windows Modules <windows_modules>`
|
||||
Windows specific module list, all implemented in PowerShell
|
||||
`User Mailing List <https://groups.google.com/group/ansible-project>`_
|
||||
|
|
|
|||
|
|
@ -229,7 +229,7 @@ host.
|
|||
:ref:`about_playbooks`
|
||||
An introduction to playbooks
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices advice
|
||||
Tips and tricks for playbooks
|
||||
`User Mailing List <https://groups.google.com/group/ansible-project>`_
|
||||
Have a question? Stop by the google group!
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
|
|
|
|||
|
|
@ -564,7 +564,7 @@ Here are the known ones:
|
|||
:ref:`about_playbooks`
|
||||
An introduction to playbooks
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices advice
|
||||
Tips and tricks for playbooks
|
||||
:ref:`List of Windows Modules <windows_modules>`
|
||||
Windows specific module list, all implemented in PowerShell
|
||||
`User Mailing List <https://groups.google.com/group/ansible-project>`_
|
||||
|
|
|
|||
|
|
@ -504,7 +504,7 @@ guides for Windows modules differ substantially from those for standard standard
|
|||
:ref:`playbooks_intro`
|
||||
An introduction to playbooks
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices advice
|
||||
Tips and tricks for playbooks
|
||||
:ref:`List of Windows Modules <windows_modules>`
|
||||
Windows specific module list, all implemented in PowerShell
|
||||
`User Mailing List <https://groups.google.com/group/ansible-project>`_
|
||||
|
|
|
|||
|
|
@ -904,7 +904,7 @@ Some of these limitations can be mitigated by doing one of the following:
|
|||
:ref:`playbooks_intro`
|
||||
An introduction to playbooks
|
||||
:ref:`playbooks_best_practices`
|
||||
Best practices advice
|
||||
Tips and tricks for playbooks
|
||||
:ref:`List of Windows Modules <windows_modules>`
|
||||
Windows specific module list, all implemented in PowerShell
|
||||
`User Mailing List <https://groups.google.com/group/ansible-project>`_
|
||||
|
|
|
|||
Loading…
Reference in a new issue