diff --git a/docs/docsite/rst/faq.rst b/docs/docsite/rst/faq.rst index fcf4883161c..a0cbce9ed58 100644 --- a/docs/docsite/rst/faq.rst +++ b/docs/docsite/rst/faq.rst @@ -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 }} diff --git a/docs/docsite/rst/intro_getting_started.rst b/docs/docsite/rst/intro_getting_started.rst index b7dca1fee83..9dc2dab5ddf 100644 --- a/docs/docsite/rst/intro_getting_started.rst +++ b/docs/docsite/rst/intro_getting_started.rst @@ -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. diff --git a/docs/docsite/rst/intro_installation.rst b/docs/docsite/rst/intro_installation.rst index 97ada971be2..f025748364b 100644 --- a/docs/docsite/rst/intro_installation.rst +++ b/docs/docsite/rst/intro_installation.rst @@ -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:: diff --git a/docs/docsite/rst/intro_inventory.rst b/docs/docsite/rst/intro_inventory.rst index 5f319c457cb..6591d3a793b 100644 --- a/docs/docsite/rst/intro_inventory.rst +++ b/docs/docsite/rst/intro_inventory.rst @@ -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` 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. diff --git a/docs/docsite/rst/intro_networking.rst b/docs/docsite/rst/intro_networking.rst index cd301504f6b..e619073dceb 100644 --- a/docs/docsite/rst/intro_networking.rst +++ b/docs/docsite/rst/intro_networking.rst @@ -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: diff --git a/docs/docsite/rst/intro_patterns.rst b/docs/docsite/rst/intro_patterns.rst index b2a2fff273f..7e65d531026 100644 --- a/docs/docsite/rst/intro_patterns.rst +++ b/docs/docsite/rst/intro_patterns.rst @@ -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:: diff --git a/docs/docsite/rst/playbooks_advanced_syntax.rst b/docs/docsite/rst/playbooks_advanced_syntax.rst index be79e3a4c28..e2af84bee0a 100644 --- a/docs/docsite/rst/playbooks_advanced_syntax.rst +++ b/docs/docsite/rst/playbooks_advanced_syntax.rst @@ -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. diff --git a/docs/docsite/rst/playbooks_best_practices.rst b/docs/docsite/rst/playbooks_best_practices.rst index 7fccf23c3b7..354b97325fa 100644 --- a/docs/docsite/rst/playbooks_best_practices.rst +++ b/docs/docsite/rst/playbooks_best_practices.rst @@ -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 diff --git a/docs/docsite/rst/playbooks_blocks.rst b/docs/docsite/rst/playbooks_blocks.rst index 1da95ea23b4..86674a40c1d 100644 --- a/docs/docsite/rst/playbooks_blocks.rst +++ b/docs/docsite/rst/playbooks_blocks.rst @@ -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 diff --git a/docs/docsite/rst/playbooks_conditionals.rst b/docs/docsite/rst/playbooks_conditionals.rst index dec421aa9e1..49a32f46f99 100644 --- a/docs/docsite/rst/playbooks_conditionals.rst +++ b/docs/docsite/rst/playbooks_conditionals.rst @@ -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. diff --git a/docs/docsite/rst/playbooks_debugger.rst b/docs/docsite/rst/playbooks_debugger.rst index 7694914d952..f71c431f2de 100644 --- a/docs/docsite/rst/playbooks_debugger.rst +++ b/docs/docsite/rst/playbooks_debugger.rst @@ -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:: diff --git a/docs/docsite/rst/playbooks_delegation.rst b/docs/docsite/rst/playbooks_delegation.rst index e4967dc56dd..fe8394836b5 100644 --- a/docs/docsite/rst/playbooks_delegation.rst +++ b/docs/docsite/rst/playbooks_delegation.rst @@ -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:: diff --git a/docs/docsite/rst/playbooks_error_handling.rst b/docs/docsite/rst/playbooks_error_handling.rst index 6e9796ad21d..473adb5fa3c 100644 --- a/docs/docsite/rst/playbooks_error_handling.rst +++ b/docs/docsite/rst/playbooks_error_handling.rst @@ -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. diff --git a/docs/docsite/rst/playbooks_intro.rst b/docs/docsite/rst/playbooks_intro.rst index 15b8e55022a..d811b83f3ea 100644 --- a/docs/docsite/rst/playbooks_intro.rst +++ b/docs/docsite/rst/playbooks_intro.rst @@ -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:: diff --git a/docs/docsite/rst/playbooks_lookups.rst b/docs/docsite/rst/playbooks_lookups.rst index e1e355b9e1e..ceb62c7f951 100644 --- a/docs/docsite/rst/playbooks_lookups.rst +++ b/docs/docsite/rst/playbooks_lookups.rst @@ -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_` or :option:`--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 diff --git a/docs/docsite/rst/vault.rst b/docs/docsite/rst/vault.rst index a3896e4a394..6e20c554870 100644 --- a/docs/docsite/rst/vault.rst +++ b/docs/docsite/rst/vault.rst @@ -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 ` or :option:`--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 `, :ref:`template