mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
Removing obsolete version behavior callout notes - initial pass. (#33172)
* Removing obsolete version behavior callout notes - initial pass. * Fixed example text punctuation. * Removed old version callout. * Typo fix * Updated example * Fixed awkward sentence * Fixed incorrect feature name * Reinstated current version callout
This commit is contained in:
scottb
GitHub
parent
b6c401ccc8
commit
6ac9d05de6
21 changed files with 61 additions and 108 deletions
|
|
@ -67,7 +67,7 @@ for new users.
|
|||
How do I configure a jump host to access servers that I have no direct access to?
|
||||
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
With Ansible 2, you can set a `ProxyCommand` in the
|
||||
You can set a `ProxyCommand` in the
|
||||
`ansible_ssh_common_args` inventory variable. Any arguments specified in
|
||||
this variable are added to the sftp/scp/ssh command line when connecting
|
||||
to the relevant host(s). Consider the following inventory group:
|
||||
|
|
@ -269,7 +269,7 @@ environment variable on the management machine::
|
|||
|
||||
If you need to set environment variables, see the Advanced Playbooks section about environments.
|
||||
|
||||
Starting with Ansible 1.4, remote environment variables are available via facts in the 'ansible_env' variable:
|
||||
Remote environment variables are available via facts in the 'ansible_env' variable:
|
||||
|
||||
.. code-block:: jinja
|
||||
|
||||
|
|
@ -348,7 +348,7 @@ How do I keep secret data in my playbook?
|
|||
|
||||
If you would like to keep secret data in your Ansible content and still share it publicly or keep things in source control, see :doc:`playbooks_vault`.
|
||||
|
||||
In Ansible 1.8 and later, if you have a task that you don't want to show the results or command given to it when using -v (verbose) mode, the following task or playbook attribute can be useful::
|
||||
If you have a task that you don't want to show the results or command given to it when using -v (verbose) mode, the following task or playbook attribute can be useful::
|
||||
|
||||
- name: secret task
|
||||
shell: /usr/bin/do_something --value={{ secret_value }}
|
||||
|
|
|
|||
|
|
@ -24,12 +24,10 @@ Remote Connection Information
|
|||
Before we get started, it's important to understand how Ansible communicates with remote
|
||||
machines over SSH.
|
||||
|
||||
By default, Ansible 1.3 and later will try to use native
|
||||
By default, Ansible will try to use native
|
||||
OpenSSH for remote communication when possible. This enables ControlPersist (a performance feature), Kerberos, and options in ``~/.ssh/config`` such as Jump Host setup. However, when using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), the version of OpenSSH may be too old to support ControlPersist. On these operating systems, Ansible will fallback into using a high-quality Python implementation of
|
||||
OpenSSH called 'paramiko'. If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform.
|
||||
|
||||
In releases up to and including Ansible 1.2, the default was strictly paramiko. Native SSH had to be explicitly selected with the ``-c`` ssh option or set in the configuration file.
|
||||
|
||||
Occasionally you'll encounter a device that doesn't support SFTP. This is rare, but should it occur, you can switch to SCP mode in :doc:`intro_configuration`.
|
||||
|
||||
When speaking with remote machines, Ansible by default assumes you are using SSH keys. SSH keys are encouraged but password authentication can also be used where needed by supplying the option ``--ask-pass``. If using sudo features and when sudo requires a password, also supply ``--ask-become-pass`` (previously ``--ask-sudo-pass`` which has been deprecated).
|
||||
|
|
@ -126,7 +124,7 @@ You can specify localhost explicitly by adding this to your inventory file::
|
|||
Host Key Checking
|
||||
`````````````````
|
||||
|
||||
Ansible 1.2.1 and later have host key checking enabled by default.
|
||||
Ansible has host key checking enabled by default.
|
||||
|
||||
If a host is reinstalled and has a different key in 'known_hosts', this will result in an error message until corrected. If a host is not initially in 'known_hosts' this will result in prompting for confirmation of the key, which results in an interactive experience if using Ansible, from say, cron. You might not want this.
|
||||
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ This includes Red Hat, Debian, CentOS, OS X, any of the BSDs, and so on.
|
|||
|
||||
.. note::
|
||||
|
||||
As of version 2.0, Ansible uses a few more file handles to manage its forks. Mac OS X by default is configured for a small amount of file handles, so if you want to use 15 or more forks you'll need to raise the ulimit with ``sudo launchctl limit maxfiles unlimited``. This command can also fix any "Too many open files" error.
|
||||
Mac OS X by default is configured for a small number of file handles, so if you want to use 15 or more forks you'll need to raise the ulimit with ``sudo launchctl limit maxfiles unlimited``. This command can also fix any "Too many open files" error.
|
||||
|
||||
|
||||
.. warning::
|
||||
|
|
|
|||
|
|
@ -291,9 +291,9 @@ Ansible will read all the files in these directories in lexicographical order. A
|
|||
All hosts that are in the 'raleigh' group will have the variables defined in these files
|
||||
available to them. This can be very useful to keep your variables organized when a single
|
||||
file starts to be too big, or when you want to use :doc:`Ansible Vault<playbooks_vault>` on a part of a group's
|
||||
variables. Note that this only works on Ansible 1.4 or later.
|
||||
variables.
|
||||
|
||||
Tip: In Ansible 1.2 or later the ``group_vars/`` and ``host_vars/`` directories can exist in
|
||||
Tip: The ``group_vars/`` and ``host_vars/`` directories can exist in
|
||||
the playbook directory OR the inventory directory. If both paths exist, variables in the playbook
|
||||
directory will override variables set in the inventory directory.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Networking Support
|
|||
Working with Networking Devices
|
||||
```````````````````````````````
|
||||
|
||||
Starting with Ansible version 2.1, you can now use the familiar Ansible models of playbook authoring and module development to manage heterogenous networking devices. Ansible supports a growing number of network devices using both CLI over SSH and API (when available) transports.
|
||||
You can use the familiar Ansible models of playbook authoring and module development to manage heterogenous networking devices. Ansible supports a growing number of network devices using both CLI over SSH and API (when available) transports.
|
||||
|
||||
.. _networking_installation:
|
||||
|
||||
|
|
|
|||
|
|
@ -99,8 +99,7 @@ And if you want to read the list of hosts from a file, prefix the file name with
|
|||
|
||||
Easy enough. See :doc:`intro_adhoc` and then :doc:`playbooks` for how to apply this knowledge.
|
||||
|
||||
.. note:: With the exception of version 1.9, you can use ',' instead of ':' as a host list separator. The ',' is preferred specially when dealing with ranges and ipv6.
|
||||
.. note:: As of 2.0 the ';' is deprecated as a host list separator.
|
||||
.. note:: You can use ',' instead of ':' as a host list separator. The ',' is preferred specially when dealing with ranges and ipv6.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ The documentation covered here is an extension of the documentation that can be
|
|||
Unsafe or Raw Strings
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
As of Ansible 2.0, there is an internal data type for declaring variable values as "unsafe". This means that the data held within the variables value should be treated as unsafe preventing unsafe character subsitition and information disclosure.
|
||||
Ansible provides an internal data type for declaring variable values as "unsafe". This means that the data held within the variables value should be treated as unsafe preventing unsafe character subsitition and information disclosure.
|
||||
|
||||
Jinja2 contains functionality for escaping, or telling Jinja2 to not template data by means of functionality such as ``{% raw %} ... {% endraw %}``, however this uses a more comprehensive implementation to ensure that the value is never templated.
|
||||
|
||||
|
|
|
|||
|
|
@ -285,29 +285,29 @@ Now what sort of use cases does this layout enable? Lots! If I want to reconfi
|
|||
|
||||
ansible-playbook -i production site.yml
|
||||
|
||||
What about just reconfiguring NTP on everything? Easy.::
|
||||
To reconfigure NTP on everything::
|
||||
|
||||
ansible-playbook -i production site.yml --tags ntp
|
||||
|
||||
What about just reconfiguring my webservers?::
|
||||
To reconfigure just my webservers::
|
||||
|
||||
ansible-playbook -i production webservers.yml
|
||||
|
||||
What about just my webservers in Boston?::
|
||||
For just my webservers in Boston::
|
||||
|
||||
ansible-playbook -i production webservers.yml --limit boston
|
||||
|
||||
What about just the first 10, and then the next 10?::
|
||||
Forjust the first 10, and then the next 10::
|
||||
|
||||
ansible-playbook -i production webservers.yml --limit boston[1:10]
|
||||
ansible-playbook -i production webservers.yml --limit boston[11:20]
|
||||
|
||||
And of course just basic ad-hoc stuff is also possible.::
|
||||
And of course just basic ad-hoc stuff is also possible::
|
||||
|
||||
ansible boston -i production -m ping
|
||||
ansible boston -i production -m command -a '/sbin/reboot'
|
||||
|
||||
And there are some useful commands to know (at least in 1.1 and higher)::
|
||||
And there are some useful commands to know::
|
||||
|
||||
# confirm what task names would be run if I ran this command and said "just ntp tasks"
|
||||
ansible-playbook -i production webservers.yml --tags ntp --list-tasks
|
||||
|
|
|
|||
|
|
@ -1,11 +1,7 @@
|
|||
Blocks
|
||||
======
|
||||
|
||||
In 2.0 we added a block feature to allow for logical grouping of tasks and even
|
||||
in play error handling. Most of what you can apply to a single task can be applied
|
||||
at the block level, which also makes it much easier to set data or directives common
|
||||
to the tasks. This does not mean the directive affects the block itself, but is inherited
|
||||
by the tasks enclosed by a block. i.e. a `when` will be applied to the tasks, not the block itself.
|
||||
Blocks allow for logical grouping of tasks and in play error handling. Most of what you can apply to a single task can be applied at the block level, which also makes it much easier to set data or directives common to the tasks. This does not mean the directive affects the block itself, but is inherited by the tasks enclosed by a block. i.e. a `when` will be applied to the tasks, not the block itself.
|
||||
|
||||
|
||||
.. code-block:: YAML
|
||||
|
|
|
|||
|
|
@ -6,11 +6,10 @@ Conditionals
|
|||
|
||||
Often the result of a play may depend on the value of a variable, fact (something learned about the remote system), or previous task result.
|
||||
In some cases, the values of variables may depend on other variables.
|
||||
Further, additional groups can be created to manage hosts based on whether the hosts match other criteria.
|
||||
There are many options to control execution flow in Ansible.
|
||||
More examples of supported conditionals can be located here: http://jinja.pocoo.org/docs/dev/templates/#comparisons
|
||||
Further, additional groups can be created to manage hosts based on whether the hosts match other criteria. This topic covers how conditionals are used in playbooks.
|
||||
|
||||
.. note:: There are many options to control execution flow in Ansible. More examples of supported conditionals can be located here: http://jinja.pocoo.org/docs/dev/templates/#comparisons.
|
||||
|
||||
Let's dig into what they are.
|
||||
|
||||
.. _the_when_statement:
|
||||
|
||||
|
|
@ -68,11 +67,10 @@ decide to do something conditionally based on success or failure::
|
|||
when: result|skipped
|
||||
|
||||
|
||||
.. note:: the filters have been updated in 2.1 so both `success` and `succeeded` work (`fail`/`failed`, etc).
|
||||
.. note:: both `success` and `succeeded` work (`fail`/`failed`, etc).
|
||||
|
||||
Note that was a little bit of foreshadowing on the 'register' statement. We'll get to it a bit later in this chapter.
|
||||
|
||||
As a reminder, to see what facts are available on a particular system, you can do::
|
||||
As a reminder, to see what facts are available on a particular system, you can do the following::
|
||||
|
||||
ansible hostname.example.com -m setup
|
||||
|
||||
|
|
@ -197,7 +195,7 @@ instead, the tasks are executed as expected because the conditional is not appli
|
|||
Conditional Imports
|
||||
```````````````````
|
||||
|
||||
.. note:: This is an advanced topic that is infrequently used. You can probably skip this section.
|
||||
.. note:: This is an advanced topic that is infrequently used.
|
||||
|
||||
Sometimes you will want to do certain things differently in a playbook based on certain criteria.
|
||||
Having one playbook that works on multiple platforms and OS versions is a good example.
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ Playbook Debugger
|
|||
|
||||
.. contents:: Topics
|
||||
|
||||
In 2.1 we added a ``debug`` strategy. This strategy enables you to invoke a debugger when a task has
|
||||
Ansible includes a ``debug`` strategy. This strategy enables you to invoke a debugger when a task has
|
||||
failed. You have access to all of the features of the debugger in the context of the failed task. You can then, for example, check or set the value of variables, update module arguments, and re-run the failed task with the new variables and arguments to help resolve the cause of the failure.
|
||||
|
||||
To use the ``debug`` strategy, change the ``strategy`` attribute like this::
|
||||
|
|
|
|||
|
|
@ -22,10 +22,8 @@ Be aware that certain tasks are impossible to delegate, i.e. `include`, `add_hos
|
|||
Rolling Update Batch Size
|
||||
`````````````````````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
By default, Ansible will try to manage all of the machines referenced in a play in parallel. For a rolling updates
|
||||
use case, you can define how many hosts Ansible should manage at a single time by using the ''serial'' keyword::
|
||||
By default, Ansible will try to manage all of the machines referenced in a play in parallel. For a rolling update use case, you can define how many hosts Ansible should manage at a single time by using the ''serial'' keyword::
|
||||
|
||||
|
||||
- name: test play
|
||||
|
|
@ -82,8 +80,6 @@ You can also mix and match the values::
|
|||
Maximum Failure Percentage
|
||||
``````````````````````````
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
By default, Ansible will continue executing actions as long as there are hosts in the group that have not yet failed.
|
||||
In some situations, such as with the rolling updates described above, it may be desirable to abort the play when a
|
||||
certain threshold of failures have been reached. To achieve this, as of version 1.3 you can set a maximum failure
|
||||
|
|
@ -105,7 +101,6 @@ In the above example, if more than 3 of the 10 servers in the group were to fail
|
|||
Delegation
|
||||
``````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
This isn't actually rolling update specific but comes up frequently in those cases.
|
||||
|
||||
|
|
@ -183,10 +178,8 @@ The `ansible_host` variable (`ansible_ssh_host` in 1.x or specific to ssh/parami
|
|||
Delegated facts
|
||||
```````````````
|
||||
|
||||
.. versionadded:: 2.0
|
||||
|
||||
By default, any fact gathered by a delegated task are assigned to the `inventory_hostname` (the current host) instead of the host which actually produced the facts (the delegated to host).
|
||||
In 2.0, the directive `delegate_facts` may be set to `True` to assign the task's gathered facts to the delegated host instead of the current one.::
|
||||
The directive `delegate_facts` may be set to `True` to assign the task's gathered facts to the delegated host instead of the current one.::
|
||||
|
||||
|
||||
- hosts: app_servers
|
||||
|
|
@ -206,8 +199,6 @@ This way you can lookup `hostvars['dbhost1']['default_ipv4']['address']` even th
|
|||
Run Once
|
||||
````````
|
||||
|
||||
.. versionadded:: 1.7
|
||||
|
||||
In some cases there may be a need to only run a task one time and only on one host. This can be achieved
|
||||
by configuring "run_once" on a task::
|
||||
|
||||
|
|
|
|||
|
|
@ -16,8 +16,6 @@ as desired.
|
|||
Ignoring Failed Commands
|
||||
````````````````````````
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
Generally playbooks will stop executing any more steps on a host that has a task fail.
|
||||
Sometimes, though, you want to continue on. To do so, write a task that looks like this::
|
||||
|
||||
|
|
@ -47,8 +45,6 @@ so subsequent tasks can try to use them again.
|
|||
Handlers and Failure
|
||||
````````````````````
|
||||
|
||||
.. versionadded:: 1.9.1
|
||||
|
||||
When a task fails on a host, handlers which were previously notified
|
||||
will *not* be run on that host. This can lead to cases where an unrelated failure
|
||||
can leave a host in an unexpected state. For example, a task could update
|
||||
|
|
@ -67,13 +63,11 @@ the handler from running, such as a host becoming unreachable.)
|
|||
Controlling What Defines Failure
|
||||
````````````````````````````````
|
||||
|
||||
.. versionadded:: 1.4
|
||||
|
||||
Suppose the error code of a command is meaningless and to tell if there
|
||||
is a failure what really matters is the output of the command, for instance
|
||||
if the string "FAILED" is in the output.
|
||||
|
||||
Ansible in 1.4 and later provides a way to specify this behavior as follows::
|
||||
Ansible provides a way to specify this behavior as follows::
|
||||
|
||||
- name: Fail task when the command error output prints FAILED
|
||||
command: /usr/bin/example-command -x -y -z
|
||||
|
|
@ -103,8 +97,6 @@ In previous version of Ansible, this can still be accomplished as follows::
|
|||
Overriding The Changed Result
|
||||
`````````````````````````````
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
When a shell/command or other module runs it will typically report
|
||||
"changed" status based on whether it thinks it affected machine state.
|
||||
|
||||
|
|
|
|||
|
|
@ -177,11 +177,6 @@ Remote users can also be defined per task::
|
|||
ping:
|
||||
remote_user: yourname
|
||||
|
||||
.. note::
|
||||
|
||||
The ``remote_user`` parameter for tasks was added in 1.4.
|
||||
|
||||
|
||||
Support for running things as another user is also available (see :doc:`become`)::
|
||||
|
||||
---
|
||||
|
|
@ -201,9 +196,6 @@ You can also use become on a particular task instead of the whole play::
|
|||
become: yes
|
||||
become_method: sudo
|
||||
|
||||
.. note::
|
||||
|
||||
The become syntax deprecates the old sudo/su specific syntax beginning in 1.9.
|
||||
|
||||
You can also login as you, and then become a user different than root::
|
||||
|
||||
|
|
@ -368,15 +360,16 @@ Action Shorthand
|
|||
|
||||
.. versionadded:: 0.8
|
||||
|
||||
Ansible prefers listing modules like this in 0.8 and later::
|
||||
Ansible prefers listing modules like this::
|
||||
|
||||
template: src=templates/foo.j2 dest=/etc/foo.conf
|
||||
template:
|
||||
src: templates/foo.j2
|
||||
dest: /etc/foo.conf
|
||||
|
||||
You will notice in earlier versions, this was only available as::
|
||||
Early versions of Ansible used the following format, which still works::
|
||||
|
||||
action: template src=templates/foo.j2 dest=/etc/foo.conf
|
||||
|
||||
The old form continues to work in newer versions without any plan of deprecation.
|
||||
|
||||
.. _handlers:
|
||||
|
||||
|
|
@ -461,7 +454,7 @@ Roles are described later on, but it's worthwhile to point out that:
|
|||
* handlers notified within ``pre_tasks``, ``tasks``, and ``post_tasks`` sections are automatically flushed in the end of section where they were notified;
|
||||
* handlers notified within ``roles`` section are automatically flushed in the end of ``tasks`` section, but before any ``tasks`` handlers.
|
||||
|
||||
If you ever want to flush all the handler commands immediately though, in 1.2 and later, you can::
|
||||
If you ever want to flush all the handler commands immediately you can do this::
|
||||
|
||||
tasks:
|
||||
- shell: some tasks go here
|
||||
|
|
@ -514,8 +507,6 @@ kept separate in the counts.
|
|||
If you ever want to see detailed output from successful modules as well as unsuccessful ones,
|
||||
use the ``--verbose`` flag. This is available in Ansible 0.5 and later.
|
||||
|
||||
Ansible playbook output is vastly upgraded if the cowsay
|
||||
package is installed. Try it!
|
||||
|
||||
To see what hosts would be affected by a playbook before you run it, you
|
||||
can do this::
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ Lookup plugins allow access to outside data sources. Like all templating, these
|
|||
.. note::
|
||||
- Lookups occur on the local computer, not on the remote computer.
|
||||
- They are executed with in the directory containing the role or play, as opposed to local tasks which are executed with the directory of the executed script.
|
||||
- Since Ansible version 1.9, you can pass wantlist=True to lookups to use in jinja2 template "for" loops.
|
||||
- You can pass wantlist=True to lookups to use in jinja2 template "for" loops.
|
||||
- Lookups are an advanced feature. You should have a good working knowledge of Ansible plays before incorporating them.
|
||||
|
||||
.. warning:: Some lookups pass arguments to a shell. When using variables from a remote/untrusted source, use the `|quote` filter to ensure safe usage.
|
||||
|
|
@ -20,8 +20,7 @@ Lookups and loops
|
|||
|
||||
*lookup plugins* are a way to query external data sources, such as shell commands or even key value stores.
|
||||
|
||||
Before Ansible 2.5, lookups were mostly used indirectly in ``with_<lookup`` constructes for looping, begining in 2.5
|
||||
we use them more explicitly as part of Jinja2 expressions fed into the ``loop`` keyword.
|
||||
Before Ansible 2.5, lookups were mostly used indirectly in ``with_<lookup`` constructs for looping. Starting with Ansible version 2.5, lookups are used more explicitly as part of Jinja2 expressions fed into the ``loop`` keyword.
|
||||
|
||||
|
||||
.. _lookups_and_variables:
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Creating Reusable Playbooks
|
|||
|
||||
While it is possible to write a playbook in one very large file (and you might start out learning playbooks this way), eventually you'll want to reuse files and start to organize things. In Ansible, there are three ways to do this: includes, imports, and roles.
|
||||
|
||||
Includes and imports (added in 2.4) allow users to break up large playbooks into smaller files, which can be used across multiple parent playbooks or even multiple times within the same Playbook.
|
||||
Includes and imports (added in Ansible version 2.4) allow users to break up large playbooks into smaller files, which can be used across multiple parent playbooks or even multiple times within the same Playbook.
|
||||
|
||||
Roles allow more than just tasks to be packaged together and can include variables, handlers, or even modules and other plugins. Unlike includes and imports, roles can also be uploaded and shared via Ansible Galaxy.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,14 +1,12 @@
|
|||
Strategies
|
||||
===========
|
||||
|
||||
In 2.0 we added a new way to control play execution, ``strategy``, by default plays will
|
||||
still run as they used to, with what we call the ``linear`` strategy. All hosts will run each
|
||||
task before any host starts the next task, using the number of forks (default 5) to parallelize.
|
||||
Strategies are a way to control play execution. By default, plays run with a ``linear`` strategy, in which all hosts will run each task before any host starts the next task, using the number of forks (default 5) to parallelize.
|
||||
|
||||
The ``serial`` directive can 'batch' this behaviour to a subset of the hosts, which then run to
|
||||
completion of the play before the next 'batch' starts.
|
||||
|
||||
A second ``strategy`` ships with ansible ``free``, which allows each host to run until the end of
|
||||
A second ``strategy`` ships with Ansible - ``free`` - which allows each host to run until the end of
|
||||
the play as fast as it can.::
|
||||
|
||||
- hosts: all
|
||||
|
|
@ -22,8 +20,8 @@ the play as fast as it can.::
|
|||
Strategy Plugins
|
||||
`````````````````
|
||||
|
||||
The strategies are implemented via a new type of plugin, this means that in the future new
|
||||
execution types can be added, either locally by users or to Ansible itself by
|
||||
The strategies are implemented as plugins. In the future, new
|
||||
execution strategies can be added, either locally by users or to Ansible itself by
|
||||
a code contribution.
|
||||
|
||||
One example is ``debug`` strategy. See :doc:`playbooks_debugger` for details.
|
||||
|
|
|
|||
|
|
@ -171,13 +171,13 @@ There are other places where variables can come from, but these are a type of va
|
|||
|
||||
Facts are information derived from speaking with your remote systems.
|
||||
|
||||
An example of this might be the ip address of the remote host, or what the operating system is.
|
||||
An example of this might be the IP address of the remote host, or what the operating system is.
|
||||
|
||||
To see what information is available, try the following::
|
||||
|
||||
ansible hostname -m setup
|
||||
|
||||
This will return a ginormous amount of variable data, which may look like this, as taken from Ansible 1.4 on a Ubuntu 12.04 system
|
||||
This will return a large amount of variable data, which may look like this, as taken from Ansible 1.4 running on a Ubuntu 12.04 system
|
||||
|
||||
.. code-block: json
|
||||
|
||||
|
|
@ -850,11 +850,7 @@ In 1.x, the precedence is as follows (with the last listed variables winning pri
|
|||
* connection variables (``ansible_user``, etc.)
|
||||
* extra vars (``-e`` in the command line) always win
|
||||
|
||||
.. note::
|
||||
|
||||
In versions prior to 1.5.4, facts discovered about a system were in the "most everything else" category above.
|
||||
|
||||
In 2.x, we have made the order of precedence more specific (with the last listed variables winning prioritization):
|
||||
In Ansible version 2.x, we have made the order of precedence more specific (with the last listed variables winning prioritization):
|
||||
|
||||
* role defaults [1]_
|
||||
* inventory file or script group vars [2]_
|
||||
|
|
@ -929,7 +925,7 @@ You can also override as a normal variable in a play::
|
|||
Variable Scopes
|
||||
````````````````
|
||||
|
||||
Ansible has 3 main scopes:
|
||||
Ansible has three main scopes:
|
||||
|
||||
* Global: this is set by config, environment variables and the command line
|
||||
* Play: each play and contained structures, vars entries (vars; vars_files; vars_prompt), role defaults and vars.
|
||||
|
|
@ -940,9 +936,9 @@ Ansible has 3 main scopes:
|
|||
Variable Examples
|
||||
`````````````````
|
||||
|
||||
That seems a little theoretical. Let's show some examples and where you would choose to put what based on the kind of control you might want over values.
|
||||
Let's show some examples and where you would choose to put what based on the kind of control you might want over values.
|
||||
|
||||
First off, group variables are super powerful.
|
||||
First off, group variables are powerful.
|
||||
|
||||
Site wide defaults should be defined as a ``group_vars/all`` setting. Group variables are generally placed alongside
|
||||
your inventory file. They can also be returned by a dynamic inventory script (see :doc:`intro_dynamic_inventory`) or defined
|
||||
|
|
@ -974,8 +970,8 @@ Next up: learning about role variable precedence.
|
|||
We'll pretty much assume you are using roles at this point. You should be using roles for sure. Roles are great. You are using
|
||||
roles aren't you? Hint hint.
|
||||
|
||||
Ok, so if you are writing a redistributable role with reasonable defaults, put those in the ``roles/x/defaults/main.yml`` file. This means
|
||||
the role will bring along a default value but ANYTHING in Ansible will override it. It's just a default. That's why it says "defaults" :)
|
||||
If you are writing a redistributable role with reasonable defaults, put those in the ``roles/x/defaults/main.yml`` file. This means
|
||||
the role will bring along a default value but ANYTHING in Ansible will override it.
|
||||
See :doc:`playbooks_reuse_roles` for more info about this::
|
||||
|
||||
---
|
||||
|
|
@ -991,7 +987,7 @@ by inventory, you should put it in ``roles/x/vars/main.yml`` like so, and invent
|
|||
# this will absolutely be used in this role
|
||||
http_port: 80
|
||||
|
||||
So the above is a great way to plug in constants about the role that are always true. If you are not sharing your role with others,
|
||||
This is one way to plug in constants about the role that are always true. If you are not sharing your role with others,
|
||||
app specific behaviors like ports is fine to put in here. But if you are sharing roles with others, putting variables in here might
|
||||
be bad. Nobody will be able to override them with inventory, but they still can by passing a parameter to the role.
|
||||
|
||||
|
|
@ -1006,8 +1002,7 @@ This makes it clear to the playbook reader that you've made a conscious choice t
|
|||
configuration that the role can't assume by itself. It also allows you to pass something site-specific that isn't really part of the
|
||||
role you are sharing with others.
|
||||
|
||||
This can often be used for things that might apply to some hosts multiple times,
|
||||
like so::
|
||||
This can often be used for things that might apply to some hosts multiple times. For example::
|
||||
|
||||
roles:
|
||||
- { role: app_user, name: Ian }
|
||||
|
|
@ -1015,12 +1010,10 @@ like so::
|
|||
- { role: app_user, name: Graham }
|
||||
- { role: app_user, name: John }
|
||||
|
||||
That's a bit arbitrary, but you can see how the same role was invoked multiple times. In that example it's quite likely there was
|
||||
no default for 'name' supplied at all. Ansible can yell at you when variables aren't defined -- it's the default behavior in fact.
|
||||
In this example, the same role was invoked multiple times. It's quite likely there was
|
||||
no default for 'name' supplied at all. Ansible can warn you when variables aren't defined -- it's the default behavior in fact.
|
||||
|
||||
So that's a bit about roles.
|
||||
|
||||
There are a few bonus things that go on with roles.
|
||||
There are a few other things that go on with roles.
|
||||
|
||||
Generally speaking, variables set in one role are available to others. This means if you have a ``roles/common/vars/main.yml`` you
|
||||
can set variables in there and make use of them in other roles and elsewhere in your playbook::
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ Using Vault in playbooks
|
|||
|
||||
.. contents:: Topics
|
||||
|
||||
Added in Ansible 1.5, "Vault" is a feature of ansible that allows keeping sensitive data such as passwords or keys in encrypted files, rather than as plaintext in your playbooks or roles. These vault files can then be distributed or placed in source control.
|
||||
The "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.
|
||||
|
||||
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 --ask-vault-pass>` or :option:`--vault-password-file <ansible-vault --vault-password-file>` 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.
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ To run a playbook that contains vault-encrypted data files, you must pass one of
|
|||
|
||||
This prompt will then be used to decrypt (in memory only) any vault encrypted files that are accessed. Currently this requires that all files be encrypted with the same password.
|
||||
|
||||
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::
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ Ansible Vault
|
|||
|
||||
.. contents:: Topics
|
||||
|
||||
New in Ansible 1.5, "Vault" is a feature of ansible that allows keeping sensitive data such as passwords or keys in encrypted files, rather than as plaintext in your playbooks or roles. These vault files can then be distributed or placed in source control.
|
||||
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.
|
||||
|
||||
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>` or :option:`--vault-password-file <ansible-playbook --vault-password-file>`) 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.
|
||||
|
||||
|
|
@ -14,15 +14,15 @@ For best practices advice, refer to :ref:`best_practices_for_variables_and_vault
|
|||
What Can Be Encrypted With Vault
|
||||
````````````````````````````````
|
||||
|
||||
The vault feature can encrypt any structured data file used by Ansible. 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 Vault can encrypt any structured data file used by Ansible. 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.
|
||||
|
||||
The vault feature can also encrypt arbitrary files, even binary files. If a vault-encrypted file is
|
||||
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>`, :ref:`template <template>`,
|
||||
:ref:`unarchive <unarchive>`, :ref:`script <script>` or :ref:`assemble <assemble>` 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).
|
||||
|
||||
As of version 2.3, 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 details below.
|
||||
As of version 2.3, Ansible 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 details below.
|
||||
|
||||
|
||||
.. _creating_files:
|
||||
|
|
@ -104,8 +104,6 @@ to the disk, so be sure you do not want :ref:`ansible-vault edit <ansible_vault_
|
|||
Viewing Encrypted Files
|
||||
```````````````````````
|
||||
|
||||
*Available since Ansible 1.8*
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
|
|
|||
|
|
@ -597,7 +597,7 @@ authentication through HTTPS. If ``ansible_user`` has a UPN value like
|
|||
to use Kerberos unless ``ansible_winrm_transport`` has been set to something other than
|
||||
``kerberos``.
|
||||
|
||||
As of Ansible 2.0, the following custom inventory variables are also supported
|
||||
The following custom inventory variables are also supported
|
||||
for additional configuration of WinRM connections:
|
||||
|
||||
* ``ansible_port``: The port WinRM will run over, HTTPS is ``5986`` which is
|
||||
|
|
|
|||
Loading…
Reference in a new issue