diff -Nru ansible-2.4.1.0/CHANGELOG.md ansible-2.4.2.0/CHANGELOG.md --- ansible-2.4.1.0/CHANGELOG.md 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/CHANGELOG.md 2017-11-29 21:10:31.000000000 +0000 @@ -1,9 +1,204 @@ Ansible Changes By Release ========================== + + +## 2.4.2 "Dancing Days" - 2017-11-29 + +### Bugfixes + +* Fix formatting typo in panos_security_rule.py docs. (https://github.com/ansible/ansible/commit/c0fc797a06451d2fe1ac4fc077fc64f3a1666447) +* Fix rpm spec file to build on RHEL6 without EPEL packages (https://github.com/ansible/ansible/pull/31653) +* Keep hosts in play vars if inside of a rescue task (https://github.com/ansible/ansible/pull/31710) +* Fix wait_for module to treat broken connections as unready so that the connection continues to be retried: + https://github.com/ansible/ansible/pull/28839 +* Python3 fixes: + * windows_azure, clc_firewall_policy, and ce_template modules fixed for + imports of urllib which changed between Python2 and Python3 lookup plugin + for consul_kv.py fixed for imports of urllib + (https://github.com/ansible/ansible/issues/31240) + * Make internal hashing of hostvars use bytes on both python2 and python3 + (https://github.com/ansible/ansible/pull/31788) +* Fix logging inside of KubernetesAnsibleModule() to not use + self.helper.logging. the Ansible builtin log() method will strip out + parameters marked no_log and will not log if no_log was set in the playbook. + self.helper.log() circumvents that (https://github.com/ansible/ansible/pull/31789) +* Correct task results display so that it more closely matches what was present + in 2.3.x and previous. +* Warn when a group has a bad key (Should be one of vars, children, or hosts) + https://github.com/ansible/ansible/pull/31495 +* Use controller configured ansible_shell_executable to run commands in the module + (https://github.com/ansible/ansible/pull/31361) +* Add documentation about writing unittests for Ansible +* Fix bugs in get_url/uri's SNI and TLS version handling when used on systems + that have Python-2.7.9+ and urllib3 installed. +* Have ansible-pull process inventory in its own way. Fixes issues with + ansible-pull not using the correct inventory, especially for localhost + (https://github.com/ansible/ansible/pull/32135) +* Fix for implicit localhost receiving too many variables from the all group + (https://github.com/ansible/ansible/pull/31959) +* Fix the service module to correctly detect which type of init system is + present on the host. (https://github.com/ansible/ansible/pull/32086) +* Fix inventory patterns to convert to strings before processing: + (https://github.com/ansible/ansible/issues/31978) +* Fix traceback in firewalld module instead of a nice error message: + (https://github.com/ansible/ansible/pull/31949) +* Fix for entering privileged mode using eos network modules: + (https://github.com/ansible/ansible/issues/30802) +* Validate that the destination for ansible-pull is a valid.directory: + (https://github.com/ansible/ansible/pull/31499) +* Document how to preserve strings of digits as strings in the ini inventory: + (https://github.com/ansible/ansible/pull/32047) +* Make sure we return ansible_distribution_major_version to macOS: + (https://github.com/ansible/ansible/pull/31708) +* Fix to ansible-doc -l to list custom inventory plugins: + (https://github.com/ansible/ansible/pull/31996) +* Fix win_chocolatey to respect case sensitivity in URLs: + (https://github.com/ansible/ansible/pull/31983) +* Fix config_format json in the junos_facts module: + (https://github.com/ansible/ansible/pull/31818) +* Allow the apt module's autoremove parameter to take effect in upgrades: + (https://github.com/ansible/ansible/pull/30747) +* When creating a new use via eos_user, create the user before setting the + user's privilege level: (https://github.com/ansible/ansible/pull/32162) +* Fixes nxos_portchannel idempotence failure on N1 images: + (https://github.com/ansible/ansible/pull/31057) +* Remove provider from prepare_ios_tests integration test: + (https://github.com/ansible/ansible/pull/31038) +* Fix nxos_acl change ports to non well known ports and drop time_range for N1: + (https://github.com/ansible/ansible/pull/31261) +* Fix nxos_banner removal idempotence issue in N1 images: + (https://github.com/ansible/ansible/pull/31259) +* Return error message back to the module + (https://github.com/ansible/ansible/pull/31035) +* Fix nxos_igmp_snooping idempotence: + (https://github.com/ansible/ansible/pull/31688) +* NXOS integration test nxos_file_copy, nxos_igmp, nxos_igmp_interface + nxos_igmp_snooping, nxos_ntp_auth, nxos_ntp_options: + (https://github.com/ansible/ansible/pull/29030) +* Fix elb_target_group module traceback when ports were specified inside of the targets parameter: + (https://github.com/ansible/ansible/pull/32202) +* Fix creation of empty virtual directories in aws_s3 module: + (https://github.com/ansible/ansible/pull/32169) +* Enable echo for `pause` module: (https://github.com/ansible/ansible/issues/14160) +* Fix for `hashi_vault` lookup to return all keys at a given path when no key is specified (https://github.com/ansible/ansible/pull/32182) +* Fix for `win_package` to allow TLS 1.1 and 1.2 on web requests: + (https://github.com/ansible/ansible/pull/32184) +* Remove provider from ios integration test: + (https://github.com/ansible/ansible/pull/31037) +* Fix eos_user tests + (https://github.com/ansible/ansible/pull/32261) +* Fix ansible-galaxy --force with installed roles: + (https://github.com/ansible/ansible/pull/32282) +* ios_interface testfix: + (https://github.com/ansible/ansible/pull/32335) +* Fix ios integration tests: + (https://github.com/ansible/ansible/pull/32342) +* Ensure there is always a basdir so we always pickup group/host_vars + https://github.com/ansible/ansible/pull/32269 +* Fix vars placement in ansible-inventory + https://github.com/ansible/ansible/pull/32276 +* Correct options for luseradd in user module + https://github.com/ansible/ansible/pull/32262 +* Clarified package docs on 'latest' state + https://github.com/ansible/ansible/pull/32397 +* Fix issue with user module when local is true + (https://github.com/ansible/ansible/pull/32262 and https://github.com/ansible/ansible/pull/32411) +* Fix for max_fail_percentage being inaccurate: + (https://github.com/ansible/ansible/issues/32255) +* Fix check mode when deleting ACS instance in azure_rm_acs module: + (https://github.com/ansible/ansible/pull/32063) +* Fix ios_logging smaller issues and make default size for buffered work: + (https://github.com/ansible/ansible/pull/32321) +* Fix ios_logging module issue where facility is being deleted along with host: + (https://github.com/ansible/ansible/pull/32234) +* Fix wrong prompt issue for network modules (https://github.com/ansible/ansible/pull/32426) +* Fix eos_eapi to enable non-default vrfs if the default vrf is already configured (https://github.com/ansible/ansible/pull/32112) +* Fix network parse_cli filter in case of single match is not caught when using start_block and end_block + (https://github.com/ansible/ansible/pull/31092) +* Fix win_find failing on files it can't access, change behaviour to be more + like the find module (https://github.com/ansible/ansible/issues/31898) +* Amended tracking of 'changed' + https://github.com/ansible/ansible/pull/31812 +* Fix label assignment in ovirt_host_networks + (https://github.com/ansible/ansible/pull/31973) +* Fix fencing and kuma usage in ovirt_cluster module + (https://github.com/ansible/ansible/pull/32190) +* Fix failure during upgrade due to NON_RESPONSIVE state for ovirt_hosts module + (https://github.com/ansible/ansible/pull/32192) +* ini inventory format now correclty handles group creation w/o need for specific orders + https://github.com/ansible/ansible/pull/32471 +* Fix for quoted paths in win_service + (https://github.com/ansible/ansible/issues/32368) +* Fix tracebacks for non-ascii paths when parsing inventory + (https://github.com/ansible/ansible/pull/32511) +* Fix git archive when update is set to no + (https://github.com/ansible/ansible/pull/31829) +* Fix locale when screen scraping in the yum module + (https://github.com/ansible/ansible/pull/32203) +* Fix for validating proxy results on Python3 for modules making http requests: + (https://github.com/ansible/ansible/pull/32596) +* Fix unreferenced variable in SNS topic module + (https://github.com/ansible/ansible/pull/29117) +* Handle ignore_errors in loops + (https://github.com/ansible/ansible/pull/32546) +* Fix running with closed stdin on python 3 + (https://github.com/ansible/ansible/pull/31695) +* Fix undefined variable in script inventory plugin + (https://github.com/ansible/ansible/pull/31381) +* Fix win_copy on Python 2.x to support files greater than 4GB + (https://github.com/ansible/ansible/pull/32682) +* Add extra error handling for wmare connect to correctly detect scenarios where + username does not have the required logon permissions + (https://github.com/ansible/ansible/pull/32613) +* Fix ios_config file prompt issue while using save_when + (https://github.com/ansible/ansible/pull/32744) +* Prevent host_group_vars plugin load errors when using 'path as inventory hostname' + https://github.com/ansible/ansible/issues/32764 +* Better errors when loading malformed vault envelopes + (https://github.com/ansible/ansible/issues/28038) +* nxos_interface error handling + (https://github.com/ansible/ansible/pull/32846) +* Fix snmp bugs on Nexus 3500 platform + (https://github.com/ansible/ansible/pull/32773) +* nxos_config and nxos_facts - fixes for N35 platform + (https://github.com/ansible/ansible/pull/32762) +* fix dci failure nxos + (https://github.com/ansible/ansible/pull/32877) +* Do not execute `script` tasks is check mode (https://github.com/ansible/ansible/issues/30676) +* Keep newlines when reading LXC container config file (https://github.com/ansible/ansible/pull/32219) +* Fix a traceback in os_floating_ip when required instance is already present in the cloud: + https://github.com/ansible/ansible/pull/32887 +* Fix for modifying existing application load balancers using certificates (https://github.com/ansible/ansible/pull/28217) +* Fix --ask-vault-pass with no tty and password from stdin + (https://github.com/ansible/ansible/issues/30993) +* Fix for IIS windows modules to use hashtables instead of PSCustomObject + (https://github.com/ansible/ansible/pull/32710) +* Fix nxos_snmp_host bug + (https://github.com/ansible/ansible/pull/32916) +* Make IOS devices consistent ios_logging + (https://github.com/ansible/ansible/pull/33100) +* restore error on orphan group:vars delcaration for ini inventories + https://github.com/ansible/ansible/pull/32866 +* restore host/group_vars merge order + https://github.com/ansible/ansible/pull/32963 +* use correct loop var when delegating + https://github.com/ansible/ansible/pull/32986 +* Handle sets and datetime objects in inventory sources fixing tracebacks + https://github.com/ansible/ansible/pull/32990 +* Fix for breaking change to Azure Python SDK DNS RecordSet constructor in azure-mgmt-dns==1.2.0 + https://github.com/ansible/ansible/pull/33165 +* Fix for breaking change to Azure Python SDK that prevented some members from being returned in facts modules + https://github.com/ansible/ansible/pull/33169 +* restored glob/regex host pattern matching to traverse groups and hosts and not return after first found + https://github.com/ansible/ansible/pull/33158 +* change nxos_interface module to use "show interface" to support more platforms + https://github.com/ansible/ansible/pull/33037 + + -## 2.4.1 "Dancing Days" - TBD +## 2.4.1 "Dancing Days" - 2017-10-25 ### Bugfixes @@ -139,6 +334,9 @@ https://github.com/ansible/ansible/issues/31786 * Fix ansible-doc and ansible-console module-path option (https://github.com/ansible/ansible/pull/31744) * Fix for hostname module on RHEL 7.5 (https://github.com/ansible/ansible/issues/31811) +* Fix provider password leak in logs for asa modules (https://github.com/ansible/ansible/issues/32343) +* Fix tagging for dynamodb_table if region is not explicitly passed to the module (https://github.com/ansible/ansible/pull/32557) +* Fix Python 3 decode error in `cloudflare_dns` (https://github.com/ansible/ansible/pull/32065) ### Known Bugs * Implicit localhost is getting ansible_connection from all:vars instead of @@ -178,6 +376,8 @@ * Windows modules now support the use of multiple shared module_utils files in the form of Powershell modules (.psm1), via `#Requires -Module Ansible.ModuleUtils.Whatever.psm1` * Python module argument_spec now supports custom validation logic by accepting a callable as the `type` argument. * Windows become_method: runas now works across all authtypes and will auto-elevate under UAC if WinRM user has "Act as part of the operating system" privilege +* Do not escape backslashes in the template lookup plugin to mirror what the template module does + https://github.com/ansible/ansible/issues/26397 ### Deprecations * The behaviour when specifying `--tags` (or `--skip-tags`) multiple times on the command line @@ -221,7 +421,7 @@ * Now deprecated configuration options issue warnings when set. * Removed unused and deprecated config option `pattern` * Updated the copy of six bundled for modules to use from 1.4.1 to 1.10.0 -* The `include_dir` var is not a global anymore, as we now allow multiple inventory sources, it is now host dependant. +* The `inventory_dir` var is not a global anymore, as we now allow multiple inventory sources, it is now host dependant. This means it cannot be used wherever host vars are not permitted, for example in task/handler names. * Fixed a cornercase with ini inventory vars. Previously, if an inventory var was a quoted string with hash marks ("#") in it then the parsed string @@ -772,7 +972,6 @@ ### Bugfixes * Fix alternatives module handlling of non existing options * Fix synchronize traceback with the docker connection plugin -* Do not escape backslashes in the template lookup plugin to mirror what the template module does * Fix the expires option of the postgresq_user module * Fix for win_acl when settings permissions on registry objects that use `ALL APPLICATION PACKAGES` and `ALL RESTRICTED APPLICATION PACKAGES` * Python3 fixes diff -Nru ansible-2.4.1.0/contrib/inventory/consul_io.py ansible-2.4.2.0/contrib/inventory/consul_io.py --- ansible-2.4.1.0/contrib/inventory/consul_io.py 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/contrib/inventory/consul_io.py 2017-11-29 21:10:31.000000000 +0000 @@ -473,10 +473,7 @@ scheme = 'http' if hasattr(self, 'url'): - try: - from urlparse import urlparse - except ImportError: - from urllib.parse import urlparse + from ansible.module_utils.six.moves.urllib.parse import urlparse o = urlparse(self.url) if o.hostname: host = o.hostname diff -Nru ansible-2.4.1.0/contrib/inventory/rudder.py ansible-2.4.2.0/contrib/inventory/rudder.py --- ansible-2.4.1.0/contrib/inventory/rudder.py 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/contrib/inventory/rudder.py 2017-11-29 21:10:31.000000000 +0000 @@ -56,12 +56,8 @@ import six import httplib2 as http from time import time -from six.moves import configparser - -try: - from urlparse import urlparse -except ImportError: - from urllib.parse import urlparse +from ansible.module_utils.six.moves import configparser +from ansible.module_utils.six.moves.urllib.parse import urlparse try: import json diff -Nru ansible-2.4.1.0/contrib/inventory/windows_azure.py ansible-2.4.2.0/contrib/inventory/windows_azure.py --- ansible-2.4.1.0/contrib/inventory/windows_azure.py 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/contrib/inventory/windows_azure.py 2017-11-29 21:10:31.000000000 +0000 @@ -39,7 +39,7 @@ import sys import argparse import os -from urlparse import urlparse +from ansible.module_utils.six.moves.urllib.parse import urlparse from time import time try: import json diff -Nru ansible-2.4.1.0/debian/changelog ansible-2.4.2.0/debian/changelog --- ansible-2.4.1.0/debian/changelog 2017-10-26 05:56:59.000000000 +0000 +++ ansible-2.4.2.0/debian/changelog 2017-11-29 21:11:16.000000000 +0000 @@ -1,8 +1,15 @@ -ansible (2.4.1.0-1ppa~precise) precise; urgency=low +ansible (2.4.2.0-1ppa~precise) precise; urgency=low - * 2.4.1.0 release + * 2.4.2.0 release + + -- Ansible, Inc. Wed, 29 Nov 2017 21:10:57 +0000 + +ansible (2.4.2.0) unstable; urgency=low + + * 2.4.2.0 + + -- Ansible, Inc. Wed, 29 Nov 2017 12:18:55 -0800 - -- Ansible, Inc. Thu, 26 Oct 2017 05:56:28 +0000 ansible (2.4.1.0) unstable; urgency=low diff -Nru ansible-2.4.1.0/debian/changeloge ansible-2.4.2.0/debian/changeloge --- ansible-2.4.1.0/debian/changeloge 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/debian/changeloge 2017-11-29 21:10:32.000000000 +0000 @@ -4,6 +4,13 @@ -- Ansible, Inc. %DATE% +ansible (2.4.2.0) unstable; urgency=low + + * 2.4.2.0 + + -- Ansible, Inc. Wed, 29 Nov 2017 12:18:55 -0800 + + ansible (2.4.1.0) unstable; urgency=low * 2.4.1.0 diff -Nru ansible-2.4.1.0/docs/bin/dump_keywords.py ansible-2.4.2.0/docs/bin/dump_keywords.py --- ansible-2.4.1.0/docs/bin/dump_keywords.py 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/bin/dump_keywords.py 2017-11-29 21:10:31.000000000 +0000 @@ -1,8 +1,11 @@ #!/usr/bin/env python import optparse -import yaml +import re +from distutils.version import LooseVersion +import jinja2 +import yaml from jinja2 import Environment, FileSystemLoader from ansible.playbook import Play @@ -18,7 +21,7 @@ p = optparse.OptionParser( version='%prog 1.0', usage='usage: %prog [options]', - description='Generate module documentation from metadata', + description='Generate playbook keyword documentation from code and descriptions', ) p.add_option("-T", "--template-dir", action="store", dest="template_dir", default="../templates", help="directory containing Jinja2 templates") p.add_option("-o", "--output-dir", action="store", dest="output_dir", default='/tmp/', help="Output directory for rst files") @@ -65,5 +68,10 @@ outputname = options.output_dir + template_file.replace('.j2', '') tempvars = {'oblist': oblist, 'clist': clist} +keyword_page = template.render(tempvars) +if LooseVersion(jinja2.__version__) < LooseVersion('2.10'): + # jinja2 < 2.10's indent filter indents blank lines. Cleanup + keyword_page = re.sub(' +\n', '\n', keyword_page) + with open(outputname, 'w') as f: - f.write(template.render(tempvars)) + f.write(keyword_page) diff -Nru ansible-2.4.1.0/docs/bin/plugin_formatter.py ansible-2.4.2.0/docs/bin/plugin_formatter.py --- ansible-2.4.1.0/docs/bin/plugin_formatter.py 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/bin/plugin_formatter.py 2017-11-29 21:10:31.000000000 +0000 @@ -30,6 +30,9 @@ import sys import warnings from collections import defaultdict +from distutils.version import LooseVersion +from pprint import PrettyPrinter + try: from html import escape as html_escape except ImportError: @@ -39,6 +42,7 @@ def html_escape(text, quote=True): return cgi.escape(text, quote) +import jinja2 import yaml from jinja2 import Environment, FileSystemLoader from six import iteritems @@ -382,6 +386,9 @@ doc['returndocs'] = None text = templates['plugin'].render(doc) + if LooseVersion(jinja2.__version__) < LooseVersion('2.10'): + # jinja2 < 2.10's indent filter indents blank lines. Cleanup + text = re.sub(' +\n', '\n', text) write_data(text, output_dir, outputname, module) diff -Nru ansible-2.4.1.0/docs/docsite/keyword_desc.yml ansible-2.4.2.0/docs/docsite/keyword_desc.yml --- ansible-2.4.1.0/docs/docsite/keyword_desc.yml 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/keyword_desc.yml 2017-11-29 21:10:31.000000000 +0000 @@ -1,51 +1,68 @@ -accelerate: DEPRECATED, set to True to use accelerate connection plugin. -accelerate_ipv6: "DEPRECATED, set to True to force accelerate plugin to use ipv6 for it's connection." -accelerate_port: DEPRECATED, set to override default port use for accelerate connection. +accelerate: "*DEPRECATED*, set to True to use accelerate connection plugin." +accelerate_ipv6: "*DEPRECATED*, set to True to force accelerate plugin to use ipv6 for its connection." +accelerate_port: "*DEPRECATED*, set to override default port use for accelerate connection." action: "The 'action' to execute for a task, it normally translates into a C(module) or action plugin." -args: DEPRECATED, A secondary way to add arguments into a task, it takes a dictionary in which keys map to options and values .. well you get it. +args: "*DEPRECATED*, A secondary way to add arguments into a task. Takes a dictionary in which keys map to options and values." always: List of tasks, in a block, that execute no matter if there is an error in the block or not. -always_run: DEPRECATED, forces a task to run even in check mode, use :term:`check_mode` directive instead. +always_run: "*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead." any_errors_fatal: Force any un-handled task errors on any host to propagate to all hosts and end the play. async: Run a task asyncronouslly if the C(action) supports this. become: Boolean that controls if privilege escalation is used or not on :term:`Task` execution. become_flags: A string of flag(s) to pass to the privilege escalation program when :term:`become` is True. -become_method: Which method of privilege escalation to use. i.e. sudo/su/etc. -become_user: "User that you 'become' after using privilege escalation, the remote/login user must have permissions to become this user." +become_method: Which method of privilege escalation to use (such as sudo or su). +become_user: "User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user." block: List of tasks in a block. changed_when: "Conditional expression that overrides the task's normal 'changed' status." -check_mode: "A boolean that controls if a task is executed in 'check' mode" -connection: Allows you to change the connection plugin used for tasks to execute on the target. -delay: Number of seconds to delay between retries, this setting is only used in combination with :term:`until`. -delegate_facts: Boolean that allows you to apply facts to delegated host instead of inventory_hostname. -delegate_to: Host to execute task instead of the target (inventory_hostname), connection vars from the delegated host will also be used for the task. +check_mode: | + A boolean that controls if a task is executed in 'check' mode + + .. seealso:: :ref:`check_mode_dry` + +connection: | + Allows you to change the connection plugin used for tasks to execute on the target. + + .. seealso:: :ref:`using_connection` + +delay: Number of seconds to delay between retries. This setting is only used in combination with :term:`until`. +delegate_facts: Boolean that allows you to apply facts to a delegated host instead of inventory_hostname. +delegate_to: Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task. diff: "Toggle to make tasks return 'diff' information or not." environment: A dictionary that gets converted into environment vars to be provided for the task upon execution. fact_path: Set the fact path option for the fact gathering plugin controlled by :term:`gather_facts`. failed_when: "Conditional expression that overrides the task's normal 'failed' status." -force_handlers: Will force notified handler execution for hosts even if they failed during the play, it will not trigger if the play itself fails. +force_handlers: Will force notified handler execution for hosts even if they failed during the play. Will not trigger if the play itself fails. gather_facts: "A boolean that controls if the play will automatically run the 'setup' task to gather facts for the hosts." gather_subset: Allows you to pass subset options to the fact gathering plugin controlled by :term:`gather_facts`. gather_timeout: Allows you to set the timeout for the fact gathering plugin controlled by :term:`gather_facts`. -handlers: "A section with tasks that are treated as handlers, these won't get executed normally, only when notified. After each section of tasks is complete." +handlers: "A section with tasks that are treated as handlers, these won't get executed normally, only when notified after each section of tasks is complete." hosts: "A list of groups, hosts or host pattern that translates into a list of hosts that are the play's target." ignore_errors: Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors. -loop_control: "Several keys here allow you to modify/set loop behaviour in a task see http://docs.ansible.com/ansible/latest/playbooks_loops.html#loop-control for details." +loop: "Takes a list for the task to iterate over, saving each list element into the ``item`` variable (configurable via loop_control)" +loop_control: | + Several keys here allow you to modify/set loop behaviour in a task. + + .. seealso:: :ref:`loop_control` + max_fail_percentage: can be used to abort the run after a given percentage of hosts in the current batch has failed. -name: "It's a name, works mostly for documentation, in the case of tasks/handlers it can be an identifier." +name: "Identifier. Can be used for documentation, in or tasks/handlers." no_log: Boolean that controls information disclosure. -notify: "list of handlers to notify when the task returns a 'changed=True' status." +notify: "List of handlers to notify when the task returns a 'changed=True' status." order: Controls the sorting of hosts as they are used for executing the play. Possible values are inventory (default), sorted, reverse_sorted, reverse_inventory and shuffle. poll: Sets the polling interval in seconds for async tasks (default 10s). port: Used to override the default port used in a connection. post_tasks: A list of tasks to execute after the :term:`tasks` section. pre_tasks: A list of tasks to execute before :term:`roles`. -remote_user: User used to log into the target via the connection plugin. AKA login user. +remote_user: User used to log into the target via the connection plugin. register: Name of variable that will contain task status and module return data. rescue: List of tasks in a :term:`block` that run if there is a task error in the main :term:`block` list. retries: "Number of retries before giving up in a :term:`until` loop. This setting is only used in combination with :term:`until`." roles: List of roles to be imported into the play run_once: Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts. -serial: Defines the 'batch' of hosts to execute the current play until the end. +serial: | + Explicitly define how Ansible batches the execution of the current play on the play's target + + .. seealso:: :ref:`rolling_update_batch_size` + strategy: Allows you to choose the connection plugin to use for the play. tags: Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line. tasks: Main list of tasks to execute in the play, they run after :term:`roles` and before :term:`post_tasks`. diff -Nru ansible-2.4.1.0/docs/docsite/rst/become.rst ansible-2.4.2.0/docs/docsite/rst/become.rst --- ansible-2.4.1.0/docs/docsite/rst/become.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/become.rst 2017-11-29 21:10:31.000000000 +0000 @@ -8,7 +8,7 @@ Become `````` Ansible allows you to 'become' another user, different from the user that logged into the machine (remote user). This is done using existing -privilege escalation tools, which you probably already use or have configured, like `sudo`, `su`, `pfexec`, `doas`, `pbrun`, `dzdo`, `ksu` and others. +privilege escalation tools, which you probably already use or have configured, like `sudo`, `su`, `pfexec`, `doas`, `pbrun`, `dzdo`, `ksu`, and others. .. note:: Before 1.9 Ansible mostly allowed the use of `sudo` and a limited use of `su` to allow a login/remote user to become a different user diff -Nru ansible-2.4.1.0/docs/docsite/rst/committer_guidelines.rst ansible-2.4.2.0/docs/docsite/rst/committer_guidelines.rst --- ansible-2.4.1.0/docs/docsite/rst/committer_guidelines.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/committer_guidelines.rst 2017-11-29 21:10:31.000000000 +0000 @@ -60,7 +60,7 @@ - Discuss with other committers, specially when you are unsure of something. - Document! If your PR is a new feature or a change to behavior, make sure you've updated all associated documentation or have notified the right people to do so. It also helps to add the version of Core against which this documentation is compatible (to avoid confusion with stable versus devel docs, for backwards compatibility, etc.). - Consider scope, sometimes a fix can be generalized - - Keep it simple, then things are maintainable, debuggable and intelligible. + - Keep it simple, then things are maintainable, debuggable, and intelligible. Committers are expected to continue to follow the same community and contribution guidelines followed by the rest of the Ansible community. diff -Nru ansible-2.4.1.0/docs/docsite/rst/community.rst ansible-2.4.2.0/docs/docsite/rst/community.rst --- ansible-2.4.1.0/docs/docsite/rst/community.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/community.rst 2017-11-29 21:10:31.000000000 +0000 @@ -45,7 +45,7 @@ You can help share Ansible with others by telling friends and colleagues, writing a blog post, or presenting at user groups (like DevOps groups or the local LUG). -You are also welcome to share slides on speakerdeck, sign up for a free account and tag it "Ansible". On Twitter, +You are also welcome to share slides on speakerdeck, sign up for a free account, and tag it "Ansible". On Twitter, you can also share things with #ansible and may wish to `follow us `_. I'd Like To Help Ansible Move Faster @@ -171,7 +171,7 @@ are interested in writing new modules to be included in the core Ansible distribution, please refer to the `module development documentation `_. -Ansible's aesthetic encourages simple, readable code and consistent, +Ansible's aesthetic encourages simple, readable code, and consistent, conservatively extending, backwards-compatible improvements. When contributing code to Ansible, please observe the following guidelines: @@ -182,7 +182,7 @@ - We are not strictly compliant with PEP8. See :doc:`dev_guide/testing_pep8` for more information. You can also contribute by testing and revising other requests, especially if it is one you are interested -in using. Please keep your comments clear and to the point, courteous and constructive, tickets are not a +in using. Please keep your comments clear, to the point, courteous, and constructive, tickets are not a good place to start discussions (ansible-devel and IRC exist for this). Tip: To easily run from a checkout, source ``./hacking/env-setup`` and that's it -- no install @@ -194,7 +194,7 @@ Ansible Staff ------------- -Ansible, Inc is a company supporting Ansible and building additional solutions based on +Ansible, Inc. is a company supporting Ansible and building additional solutions based on Ansible. We also do services and support for those that are interested. We also offer an enterprise web front end to Ansible (see Tower below). @@ -310,7 +310,7 @@ anti-harassment policy. We expect organizers to enforce these guidelines throughout all events, and we expect attendees, speakers, sponsors, and volunteers to help ensure a safe environment for our whole community. Specifically, this Code of Conduct covers -participation in all Ansible-related forums and mailing lists, code and documentation +participation in all Ansible-related forums, mailing lists, code, documentation contributions, public IRC channels, private correspondence, and public meetings. Ansible community members are... @@ -341,7 +341,7 @@ **Kind** Everyone should feel welcome in the Ansible community, regardless of their background. -Please be courteous, respectful and polite to fellow community members. Do not make or +Please be courteous, respectful, and polite to fellow community members. Do not make or post offensive comments related to skill level, gender, gender identity or expression, sexual orientation, disability, physical appearance, body size, race, or religion. Sexualized images or imagery, real or implied violence, intimidation, oppression, diff -Nru ansible-2.4.1.0/docs/docsite/rst/dev_guide/testing/sanity/azure-requirements.rst ansible-2.4.2.0/docs/docsite/rst/dev_guide/testing/sanity/azure-requirements.rst --- ansible-2.4.1.0/docs/docsite/rst/dev_guide/testing/sanity/azure-requirements.rst 1970-01-01 00:00:00.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/dev_guide/testing/sanity/azure-requirements.rst 2017-11-29 21:10:31.000000000 +0000 @@ -0,0 +1,10 @@ +Sanity Tests » azure-requirements +================================= + +Update the Azure integration test requirements file when changes are made to the Azure packaging requirements file: + +.. code-block:: bash + + cp packaging/requirements/requirements-azure.txt test/runner/requirements/integration.cloud.azure.txt + +This copy of the requirements file is used when building the ``ansible/ansible:default`` Docker container from ``test/runner/Dockerfile``. diff -Nru ansible-2.4.1.0/docs/docsite/rst/dev_guide/testing.rst ansible-2.4.2.0/docs/docsite/rst/dev_guide/testing.rst --- ansible-2.4.1.0/docs/docsite/rst/dev_guide/testing.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/dev_guide/testing.rst 2017-11-29 21:10:31.000000000 +0000 @@ -33,9 +33,14 @@ * Tests directly against individual parts of the code base. -If you're a developer, one of the most valuable things you can do is look at the GitHub issues list and help fix bugs. We almost always prioritize bug fixing over feature development, so helping to fix bugs is one of the best things you can do. - -Even if you're not a developer, helping to test pull requests for bug fixes and features is still immensely valuable. +If you're a developer, one of the most valuable things you can do is look at the GitHub +issues list and help fix bugs. We almost always prioritize bug fixing over feature +development. + +Even for non developers, helping to test pull requests for bug fixes and features is still +immensely valuable. Ansible users who understand writing playbooks and roles should be +able to add integration tests and so Github pull requests with integration tests that show +bugs in action will also be a great way to help. Testing within GitHub & Shippable @@ -47,7 +52,6 @@ When Pull Requests (PRs) are created they are tested using Shippable, a Continuous Integration (CI) tool. Results are shown at the end of every PR. - When Shippable detects an error and it can be linked back to a file that has been modified in the PR then the relevant lines will be added as a GitHub comment. For example:: The test `ansible-test sanity --test pep8` failed with the following errors: @@ -69,7 +73,6 @@ ansible-test sanity --test pep8 ansible-test sanity --test validate-modules - If there isn't a GitHub comment stating what's failed you can inspect the results by clicking on the "Details" button under the "checks have failed" message at the end of the PR. Rerunning a failing CI job @@ -91,10 +94,6 @@ How to test a PR ================ -If you're a developer, one of the most valuable things you can do is look at the GitHub issues list and help fix bugs. We almost always prioritize bug fixing over feature development, so helping to fix bugs is one of the best things you can do. - -Even if you're not a developer, helping to test pull requests for bug fixes and features is still immensely valuable. - Ideally, code should add tests that prove that the code works. That's not always possible and tests are not always comprehensive, especially when a user doesn't have access to a wide variety of platforms, or is using an API or web service. In these cases, live testing against real equipment can be more valuable than automation that runs against simulated interfaces. In any case, things should always be tested manually the first time as well. Thankfully, helping to test Ansible is pretty straightforward, assuming you are familiar with how Ansible works. @@ -188,8 +187,26 @@ | some other output | \``` +Code Coverage Online +```````````````````` + +`The online code coverage reports ` are a good way +to identify areas for testing improvement in Ansible. By following red colors you can +drill down through the reports to find files which have no tests at all. Adding both +integration and unit tests which show clearly how code should work, verify important +Ansible functions and increase testing coverage in areas where there is none is a valuable +way to help improve Ansible. + +The code coverage reports only cover the ``devel`` branch of Ansible where new feature +development takes place. Pull requests and new code will be missing from the codecov.io +coverage reports so local reporting is needed. Most ``ansible-test`` commands allow you +to collect code coverage, this is particularly useful to indicate where to extend +testing. See :doc:`testing_running_locally` for more information. + + Want to know more about testing? ================================ -If you'd like to know more about the plans for improving testing Ansible then why not join the `Testing Working Group `_. +If you'd like to know more about the plans for improving testing Ansible then why not join the +`Testing Working Group `_. diff -Nru ansible-2.4.1.0/docs/docsite/rst/dev_guide/testing_running_locally.rst ansible-2.4.2.0/docs/docsite/rst/dev_guide/testing_running_locally.rst --- ansible-2.4.1.0/docs/docsite/rst/dev_guide/testing_running_locally.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/dev_guide/testing_running_locally.rst 2017-11-29 21:10:31.000000000 +0000 @@ -45,7 +45,19 @@ Code Coverage ============= -Add the ``--coverage`` option to any test command to collect code coverage data. +Code coverage reports make it easy to identify untested code for which more tests should +be written. Online reports are available but only cover the ``devel`` branch (see +:doc:`testing`). For new code local reports are needed. + +Add the ``--coverage`` option to any test command to collect code coverage data. If you +aren't using the ``--tox`` or ``--docker`` options which create an isolated python +environment then you may have to use the ``--requirements`` option to ensure that the +correct version of the coverage module is installed + + ansible-test units --coverage apt + ansible-test integration --coverage aws_lambda --tox --requirements + ansible-test coverage html + Reports can be generated in several different formats: @@ -53,4 +65,7 @@ * ``ansible-test coverage html`` - HTML report. * ``ansible-test coverage xml`` - XML report. -To clear data between test runs, use the ``ansible-test coverage erase`` command. +To clear data between test runs, use the ``ansible-test coverage erase`` command. For a full list of features see the online help:: + + ansible-test coverage --help + diff -Nru ansible-2.4.1.0/docs/docsite/rst/dev_guide/testing_units_modules.rst ansible-2.4.2.0/docs/docsite/rst/dev_guide/testing_units_modules.rst --- ansible-2.4.1.0/docs/docsite/rst/dev_guide/testing_units_modules.rst 1970-01-01 00:00:00.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/dev_guide/testing_units_modules.rst 2017-11-29 21:10:31.000000000 +0000 @@ -0,0 +1,555 @@ +**************************** +Unit Testing Ansible Modules +**************************** + +.. contents:: Topics + +Introduction +============ + +This document explains why, how and when you should use unit tests for Ansible modules. +The document doesn't apply to other parts of Ansible for which the recommendations are +normally closer to the Python standard. There is basic documentation for Ansible unit +tests in the developer guide :doc:`testing_units`. This document should +be readable for a new Ansible module author. If you find it incomplete or confusing, +please open a bug or ask for help on Ansible IRC. + +What Are Unit Tests? +==================== + +Ansible includes a set of unit tests in the :file:`test/unit` directory. These tests primarily cover the +internals but can also can cover Ansible modules. The structure of the unit tests matches +the structure of the code base, so the tests that reside in the :file:`test/unit/modules/` directory +are organized by module groups. + +Integration tests can be used for most modules, but there are situations where +cases cannot be verified using integration tests. This means that Ansible unit test cases +may extend beyond testing only minimal units and in some cases will include some +level of functional testing. + + +Why Use Unit Tests? +=================== + +Ansible unit tests have advantages and disadvantages. It is important to understand these. +Advantages include: + +* Most unit tests are much faster than most Ansible integration tests. The complete suite + of unit tests can be run regularly by a developer on their local system. +* Unit tests can be run by developers who don't have access to the system which the module is + designed to work on, allowing a level of verification that changes to core functions + haven't broken module expectations. +* Unit tests can easily substitute system functions allowing testing of software that + would be impractical. For example, the ``sleep()`` function can be replaced and we check + that a ten minute sleep was called without actually waiting ten minutes. +* Unit tests are run on different Python versions. This allows us to + ensure that the code behaves in the same way on different Python versions. + +There are also some potential disadvantages of unit tests. Unit tests don't normally +directly test actual useful valuable features of software, instead just internal +implementation + +* Unit tests that test the internal, non-visible features of software may make + refactoring difficult if those internal features have to change (see also naming in How + below) +* Even if the internal feature is working correctly it is possible that there will be a + problem between the internal code tested and the actual result delivered to the user + +Normally the Ansible integration tests (which are written in Ansible YAML) provide better +testing for most module functionality. If those tests already test a feature and perform +well there may be little point in providing a unit test covering the same area as well. + +When To Use Unit Tests +====================== + +There are a number of situations where unit tests are a better choice than integration +tests. For example, testing things which are impossible, slow or very difficult to test +with integration tests, such as: + +* Forcing rare / strange / random situations that can't be forced, such as specific network + failures and exceptions +* Extensive testing of slow configuration APIs +* Situations where the integration tests cannot be run as part of the main Ansible + continuous integraiton running in Shippable. + + + +Providing quick feedback +------------------------ + +Example: + A single step of the rds_instance test cases can take up to 20 + minutes (the time to create an RDS instance in Amazon). The entire + test run can last for well over an hour. All 16 of the unit tests + complete execution in less than 2 seconds. + +The time saving provided by being able to run the code in a unit test makes it worth +creating a unit test when bug fixing a module, even if those tests do not often identify +problems later. As a basic goal, every module should have at least one unit test which +will give quick feedback in easy cases without having to wait for the integration tests to +complete. + +Ensuring correct use of external interfaces +------------------------------------------- + +Unit tests can check the way in which external services are run to ensure that they match +specifications or are as efficient as possible *even when the final output will not be changed*. + +Example: + Package managers are often far more efficient when installing multiple packages at once + rather than each package separately. The final result is the + same: the packages are all installed, so the efficiency is difficult to verify through + integration tests. By providing a mock package manager and verifying that it is called + once, we can build a valuable test for module efficiency. + +Another related use is in the situation where an API has versions which behave +differently. A programmer working on a new version may change the module to work with the +new API version and unintentially break the old version. A test case +which checks that the call happens properly for the old version can help avoid the +problem. In this situation it is very important to include version numbering in the test case +name (see `Naming unit tests`_ below). + +Providing specific design tests +-------------------------------- + +By building a requirement for a particular part of the +code and then coding to that requirement, unit tests _can_ sometimes improve the code and +help future developers understand that code. + +Unit tests that test internal implementation details of code, on the other hand, almost +always do more harm than good. Testing that your packages to install are stored in a list +would slow down and confuse a future developer who might need to change that list into a +dictionary for efficiency. This problem can be reduced somewhat with clear test naming so +that the future developer immediately knows to delete the test case, but it is often +better to simply leave out the test case altogether and test for a real valuable feature +of the code, such as installing all of the packages supplied as arguments to the module. + + +How to unit test Ansible modules +================================ + +There are a number of techniques for unit testing modules. Beware that most +modules without unit tests are structured in a way that makes testing quite difficult and +can lead to very complicated tests which need more work than the code. Effectively using unit +tests may lead you to restructure your code. This is often a good thing and leads +to better code overall. Good restructuring can make your code clearer and easier to understand. + + +Naming unit tests +----------------- + +Unit tests should have logical names. If a developer working on the module being tested +breaks the test case, it should be easy to figure what the unit test covers from the name. +If a unit test is designed to verify compatibility with a specific software or API version +then include the version in the name of the unit test. + +As an example, ``test_v2_state_present_should_call_create_server_with_name()`` would be a +good name, ``test_create_server()`` would not be. + + +Use of Mocks +------------ + +Mock objects (from https://docs.python.org/3/library/unittest.mock.html) can be very +useful in building unit tests for special / difficult cases, but they can also +lead to complex and confusing coding situations. One good use for mocks would be in +simulating an API. As for 'six', the 'mock' python package is bundled with Ansible (use +'import ansible.compat.tests.mock'). See for example + +Ensuring failure cases are visible with mock objects +---------------------------------------------------- + +Functions like module.fail_json() are normally expected to terminate execution. When you +run with a mock module object this doesn't happen since the mock always returns another mock +from a function call. You can set up the mock to raise an exception as shown above, or you can +assert that these functions have not been called in each test. For example:: + + module = MagicMock() + function_to_test(module, argument) + module.fail_json.assert_not_called() + +This applies not only to calling the main module but almost any other +function in a module which gets the module object. + + +Mocking of the actual module +---------------------------- + +The setup of an actual module is quite complex (see `Passing Arguments`_ below) and often +isn't needed for most functions which use a module. Instead you can use a mock object as +the module and create any module attributes needed by the function you are testing. If +you do this, beware that the module exit functions need special handling as mentioned +above, either by throwing an exception or ensuring that they haven't been called. For example:: + + class AnsibleExitJson(Exception): + """Exception class to be raised by module.exit_json and caught by the test case""" + pass + #you may also do the same to fail json + module=MagicMock() + module.exit_json.side_effect = AnsibleExitJson(Exception) + with self.assertRaises(AnsibleExitJson) as result: + return = my_module.test_this_function(module, argument) + module.fail_json.assert_not_called() + assert return["changed"] == True + +API definition with unit test cases +----------------------------------- + +API interaction is usually best tested with the function tests defined in Ansible's +integration testing section, which run against the actual API. There are several cases +where the unit tests are likely to work better. + +Defining a module against an API specification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This case is especially important for modules interacting with web services, which provide +an API that Ansible uses but which are beyond the control of the user. + +By writing a custom emulation of the calls that return data from the API, we can ensure +that only the features which are clearly defined in the specification of the API are +present in the message. This means that we can check that we use the correct +parameters and nothing else. + + +*Example: in rds_instance unit tests a simple instance state is defined*:: + + def simple_instance_list(status, pending): + return {u'DBInstances': [{u'DBInstanceArn': 'arn:aws:rds:us-east-1:1234567890:db:fakedb', + u'DBInstanceStatus': status, + u'PendingModifiedValues': pending, + u'DBInstanceIdentifier': 'fakedb'}]} + +This is then used to create a list of states:: + + rds_client_double = MagicMock() + rds_client_double.describe_db_instances.side_effect = [ + simple_instance_list('rebooting', {"a": "b", "c": "d"}), + simple_instance_list('available', {"c": "d", "e": "f"}), + simple_instance_list('rebooting', {"a": "b"}), + simple_instance_list('rebooting', {"e": "f", "g": "h"}), + simple_instance_list('rebooting', {}), + simple_instance_list('available', {"g": "h", "i": "j"}), + simple_instance_list('rebooting', {"i": "j", "k": "l"}), + simple_instance_list('available', {}), + simple_instance_list('available', {}), + ] + +These states are then used as returns from a mock object to ensure that the ``await`` function +waits through all of the states that would mean the RDS instance has not yet completed +configuration:: + + rds_i.await_resource(rds_client_double, "some-instance", "available", mod_mock, + await_pending=1) + assert(len(sleeper_double.mock_calls) > 5), "await_pending didn't wait enough" + +By doing this we check that the ``await`` function will keep waiting through +potentially unusual that it would be impossible to reliably trigger through the +integration tests but which happen unpredictably in reality. + +Defining a module to work against multiple API versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This case is especially important for modules interacting with many different versions of +software; for example, package installation modules that might be expected to work with +many different operating system versions. + +By using previously stored data from various versions of an API we can ensure that the +code is tested against the actual data which will be sent from that version of the system +even when the version is very obscure and unlikely to be available during testing. + +Ansible special cases for unit testing +====================================== + +There are a number of special cases for unit testing the environment of an Ansible module. +The most common are documented below, and suggestions for others can be found by looking +at the source code of the existing unit tests or asking on the Ansible IRC channel or mailing +lists. + +Module argument processing +-------------------------- + +There are two problems with running the main function of a module: + +* Since the module is supposed to accept arguments on ``STDIN`` it is a bit difficult to + set up the arguments correctly so that the module will get them as parameters. +* All modules should finish by calling either the ``module.fail_json`` or + ``module.exit_json``, but these won't work correctly in a testing environment. + +Passing Arguments +----------------- + +.. This section should be updated once https://github.com/ansible/ansible/pull/31456 is + closed since the function below will be provided in a library file. + +To pass arguments to a module correctly, use a function that stores the +parameters in a special string variable. Module creation and argument processing is +handled through the AnsibleModule object in the basic section of the utilities. Normally +this accepts input on ``STDIN``, which is not convenient for unit testing. When the special +variable is set it will be treated as if the input came on ``STDIN`` to the module.:: + + import json + from ansible.module_utils._text import to_bytes + + def set_module_args(args): + args = json.dumps({'ANSIBLE_MODULE_ARGS': args}) + basic._ANSIBLE_ARGS = to_bytes(args) + + simply call that function before setting up your module + + def test_already_registered(self): + set_module_args({ + 'activationkey': 'key', + 'username': 'user', + 'password': 'pass', + }) + +Handling exit correctly +----------------------- + +.. This section should be updated once https://github.com/ansible/ansible/pull/31456 is + closed since the exit and failure functions below will be provided in a library file. + +The ``module.exit_json()`` function won't work properly in a testing environment since it +writes error information to ``STDOUT`` upon exit, where it +is difficult to examine. This can be mitigated by replacing it (and module.fail_json) with +a function that raises an exception:: + + def exit_json(*args, **kwargs): + if 'changed' not in kwargs: + kwargs['changed'] = False + raise AnsibleExitJson(kwargs) + +Now you can ensure that the first function called is the one you expected simply by +testing for the correct exception:: + + def test_returned_value(self): + set_module_args({ + 'activationkey': 'key', + 'username': 'user', + 'password': 'pass', + }) + with self.assertRaises(AnsibleExitJson) as result: + my_module.main() + +The same technique can be used to replace ``module.fail_json()`` (which is used for failure +returns from modules) and for the ``aws_module.fail_json_aws()`` (used in modules for Amazon +Web Services). + +Running the main function +------------------------- + +If you do want to run the actual main function of a module you must import the module, set +the arguments as above, set up the appropriate exit exception and then run the module:: + + # This test is based around pytest's features for individual test functions + import pytest + import ansible.modules.module.group.my_modulle as my_module + + def test_main_function(monkeypatch): + monkeypatch.setattr(my_module.AnsibleModule, "exit_json", fake_exit_json) + set_module_args({ + 'activationkey': 'key', + 'username': 'user', + 'password': 'pass', + }) + my_module.main() + + +Handling calls to external executables +-------------------------------------- + +Module must use AnsibleModule.run_command in order to execute an external command. This +method needs to be mocked: + +Here is a simple mock of AnsibleModule.run_command (taken from test/units/modules/packaging/os/test_rhn_register.py and +test/units/modules/packaging/os/rhn_utils.py):: + + with patch.object(basic.AnsibleModule, 'run_command') as run_command: + run_command.return_value = 0, '', '' # successful execution, no output + with self.assertRaises(AnsibleExitJson) as result: + self.module.main() + self.assertFalse(result.exception.args[0]['changed']) + # Check that run_command has been called + run_command.assert_called_once_with('/usr/bin/command args') + self.assertEqual(run_command.call_count, 1) + self.assertFalse(run_command.called) + + +A Complete Example +------------------ + +The following example is a complete skeleton that reuses the mocks explained above and adds a new +mock for Ansible.get_bin_path:: + + import json + + from ansible.compat.tests import unittest + from ansible.compat.tests.mock import patch + from ansible.module_utils import basic + from ansible.module_utils._text import to_bytes + from ansible.modules.namespace import my_module + + + def set_module_args(args): + """prepare arguments so that they will be picked up during module creation""" + args = json.dumps({'ANSIBLE_MODULE_ARGS': args}) + basic._ANSIBLE_ARGS = to_bytes(args) + + + class AnsibleExitJson(Exception): + """Exception class to be raised by module.exit_json and caught by the test case""" + pass + + + class AnsibleFailJson(Exception): + """Exception class to be raised by module.fail_json and caught by the test case""" + pass + + + def exit_json(*args, **kwargs): + """function to patch over exit_json; package return data into an exception""" + if 'changed' not in kwargs: + kwargs['changed'] = False + raise AnsibleExitJson(kwargs) + + + def fail_json(*args, **kwargs): + """function to patch over fail_json; package return data into an exception""" + kwargs['failed'] = True + raise AnsibleFailJson(kwargs) + + + def get_bin_path(self, arg, required=False): + """Mock AnsibleModule.get_bin_path""" + if arg.endswith('my_command'): + return '/usr/bin/my_command' + else: + if required: + fail_json(msg='%r not found !' % arg) + + + class TestMyModule(unittest.TestCase): + + def setUp(self): + self.mock_module_helper = patch.multiple(basic.AnsibleModule, + exit_json=exit_json, + fail_json=fail_json, + get_bin_path=get_bin_path) + self.mock_module_helper.start() + self.addCleanup(self.mock_module_helper.stop) + + def test_module_fail_when_required_args_missing(self): + with self.assertRaises(AnsibleFailJson): + set_module_args({}) + self.module.main() + + + def test_ensure_command_called(self): + set_module_args({ + 'param1': 10, + 'param2': 'test', + }) + + with patch.object(basic.AnsibleModule, 'run_command') as mock_run_command: + stdout = 'configuration updated' + stderr = '' + rc = 0 + mock_run_command.return_value = rc, stdout, stderr # successful execution + + with self.assertRaises(AnsibleExitJson) as result: + my_module.main() + self.assertFalse(result.exception.args[0]['changed']) # ensure result is changed + + mock_run_command.assert_called_once_with('/usr/bin/my_command --value 10 --name test') + + +Restructuring modules to enable testing module set up and other processes +------------------------------------------------------------------------- + +Often modules have a main() function which sets up the module and then performs other +actions. This can make it difficult to check argument processing. This can be made easier by +moving module configuration and initialization into a separate function. For example:: + + argument_spec = dict( + # module function variables + state=dict(choices=['absent', 'present', 'rebooted', 'restarted'], default='present'), + apply_immediately=dict(type='bool', default=False), + wait=dict(type='bool', default=False), + wait_timeout=dict(type='int', default=600), + allocated_storage=dict(type='int', aliases=['size']), + db_instance_identifier=dict(aliases=["id"], required=True), + ) + + def setup_module_object(): + module = AnsibleAWSModule( + argument_spec=argument_spec, + required_if=required_if, + mutually_exclusive=[['old_instance_id', 'source_db_instance_identifier', + 'db_snapshot_identifier']], + ) + return module + + def main(): + module = setup_module_object() + validate_parameters(module) + conn = setup_client(module) + return_dict = run_task(module, conn) + module.exit_json(**return_dict) + +This now makes it possible to run tests against the module initiation function:: + + def test_rds_module_setup_fails_if_db_instance_identifier_parameter_missing(): + # db_instance_identifier parameter is missing + set_module_args({ + 'state': 'absent', + 'apply_immediately': 'True', + }) + + with self.assertRaises(AnsibleFailJson) as result: + self.module.setup_json + +See also ``test/units/module_utils/aws/test_rds.py`` + +Note that the argument_spec dictionary is visible in a module variable. This has +advantages, both in allowing explicit testing of the arguments and in allowing the easy +creation of module objects for testing. + +The same restructuring technique can be valuable for testing other functionality, such as the part of the module which queries the object that the module configures. + +Traps for maintaining Python 2 compatibility +============================================ + +If you use the ``mock`` library from the Python 2.6 standard library, a number of the +assert functions are missing but will return as if successful. This means that test cases should take great care *not* use +functions marked as _new_ in the Python 3 documentation, since the tests will likely always +succeed even if the code is broken when run on older versions of Python. + +A helpful development approach to this should be to ensure that all of the tests have been +run under Python 2.6 and that each assertion in the test cases has been checked to work by breaking +the code in Ansible to trigger that failure. + +.. seealso:: + + :doc:`testing_units` + Ansible unit tests documentation + :doc:`testing_running_locally` + Running tests locally including gathering and reporting coverage data + :doc:`developing_modules` + How to develop modules + `Python 3 documentation - 26.4. unittest — Unit testing framework `_ + The documentation of the unittest framework in python 3 + `Python 2 documentation - 25.3. unittest — Unit testing framework `_ + The documentation of the earliest supported unittest framework - from Python 2.6 + `pytest: helps you write better programs `_ + The documentation of pytest - the framework actually used to run Ansible unit tests + `Development Mailing List `_ + Mailing list for development topics + `Testing Your Code (from The Hitchhiker's Guide to Python!) `_ + General advice on testing Python code + `Uncle Bob's many videos on YouTube `_ + Unit testing is a part of the of various philosophies of software development, including + Extreme Programming (XP), Clean Coding. Uncle Bob talks through how to benfit from this + `"Why Most Unit Testing is Waste" http://rbcs-us.com/documents/Why-Most-Unit-Testing-is-Waste.pdf` + An article warning against the costs of unit testing + `'A Response to "Why Most Unit Testing is Waste"' https://henrikwarne.com/2014/09/04/a-response-to-why-most-unit-testing-is-waste/` + An response pointing to how to maintain the value of unit tests diff -Nru ansible-2.4.1.0/docs/docsite/rst/dev_guide/testing_units.rst ansible-2.4.2.0/docs/docsite/rst/dev_guide/testing_units.rst --- ansible-2.4.1.0/docs/docsite/rst/dev_guide/testing_units.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/dev_guide/testing_units.rst 2017-11-29 21:10:31.000000000 +0000 @@ -2,19 +2,24 @@ Unit Tests ********** -Unit tests are small isolated tests that target a specific library or module. +Unit tests are small isolated tests that target a specific library or module. Unit tests +in Ansible are currently the only way of driving tests from python within Ansible's +continuous integration process. This means that in some circumstances the tests may be a +bit wider than just units. .. contents:: Topics Available Tests =============== -Unit tests can be found in `test/units `_, notice that the directory structure matches that of ``lib/ansible/`` +Unit tests can be found in `test/units +`_. Notice that the directory +structure of the tests matches that of ``lib/ansible/``. Running Tests ============= -Unit tests can be run across the whole code base by doing: +The Ansible unit tests can be run across the whole code base by doing: .. code:: shell @@ -35,18 +40,22 @@ ansible-test units --tox --python 2.7 apt - For advanced usage see the online help:: ansible-test units --help +You can also run tests in Ansible's continuous integration system by opening a pull +request. This will automatically determine which tests to run based on the changes made +in your pull request. + Installing dependencies ======================= -``ansible-test`` has a number of dependencies , for ``units`` tests we suggest using ``tox`` +``ansible-test`` has a number of dependencies. For ``units`` tests we suggest using ``tox``. -The dependencies can be installed using the ``--requirements`` argument, which will install all the required dependencies needed for unit tests. For example: +The dependencies can be installed using the ``--requirements`` argument, which will +install all the required dependencies needed for unit tests. For example: .. code:: shell @@ -58,7 +67,11 @@ When using ``ansible-test`` with ``--tox`` requires tox >= 2.5.0 -The full list of requirements can be found at `test/runner/requirements `_. Requirements files are named after their respective commands. See also the `constraints `_ applicable to all commands. +The full list of requirements can be found at `test/runner/requirements +`_. Requirements +files are named after their respective commands. See also the `constraints +`_ +applicable to all commands. Extending unit tests @@ -67,22 +80,98 @@ .. warning:: What a unit test isn't - If you start writing a test that requires external services then you may be writing an integration test, rather than a unit test. + If you start writing a test that requires external services then + you may be writing an integration test, rather than a unit test. + + +Structuring Unit Tests +`````````````````````` + +Ansible drives unit tests through `pytest `_. This +means that tests can either be written a simple functions which are included in any file +name like ``test_.py`` or as classes. + +Here is an example of a function:: + + #this function will be called simply because it is called test_*() + + def test_add() + a = 10 + b = 23 + c = 33 + assert a + b = c + +Here is an example of a class:: + + import unittest: + + class AddTester(unittest.TestCase) + + def SetUp() + self.a = 10 + self.b = 23 + + # this function will + def test_add() + c = 33 + assert self.a + self.b = c + + # this function will + def test_subtract() + c = -13 + assert self.a - self.b = c + +Both methods work fine in most circumstances; the function-based interface is simpler and +quicker and so that's probably where you should start when you are just trying to add a +few basic tests for a module. The class-based test allows more tidy set up and tear down +of pre-requisites, so if you have many test cases for your module you may want to refactor +to use that. + +Assertions using the simple ``assert`` function inside the tests will give give full +information on the cause of the failure with a trace-back of functions called during the +assertion. This means that plain asserts are recommended over other external assertion +libraries. + +A number of the unit test suites include functions that are shared between several +modules, especially in the networking arena. In these cases a file is created in the same +directory, which is then included directly. + + +Module test case common code +```````````````````````````` + +Keep common code as specific as possible within the `test/units/` directory structure. For +example, if it's specific to testing Amazon modules, it should be in +`test/units/modules/cloud/amazon/`. Don't import common unit test code from directories +outside the current or parent directories. + +Don't import other unit tests from a unit test. Any common code should be in dedicated +files that aren't themselves tests. + Fixtures files `````````````` -To mock out fetching results from devices, you can use ``fixtures`` to read in pre-generated data. +To mock out fetching results from devices, or provide other complex datastructures that +come from external libraries, you can use ``fixtures`` to read in pre-generated data. Text files live in ``test/units/modules/network/PLATFORM/fixtures/`` Data is loaded using the ``load_fixture`` method -See `eos_banner test `_ for a practical example. +See `eos_banner test +`_ +for a practical example. + +If you are simulating APIs you may find that python placebo is useful. See +doc:`testing_units_modules` for more information. -Code Coverage -````````````` -Most ``ansible-test`` commands allow you to collect code coverage, this is particularly useful when to indicate where to extend testing. + +Code Coverage For New or Updated Unit Tests +``````````````````````````````````````````` +New code will be missing from the codecov.io coverage reports (see :doc:`testing`), so +local reporting is needed. Most ``ansible-test`` commands allow you to collect code +coverage; this is particularly useful when to indicate where to extend testing. To collect coverage data add the ``--coverage`` argument to your ``ansible-test`` command line: @@ -99,7 +188,21 @@ * ``ansible-test coverage html`` - HTML report. * ``ansible-test coverage xml`` - XML report. -To clear data between test runs, use the ``ansible-test coverage erase`` command. For a full list of features see the online help:: - - ansible-test coverage --help +To clear data between test runs, use the ``ansible-test coverage erase`` command. See +:doc:`testing_units_running_locally` for more information about generating coverage +reports. + + +.. seealso:: + + :doc:`testing_units_modules` + Special considerations for unit testing modules + :doc:`testing_running_locally` + Running tests locally including gathering and reporting coverage data + `Python 3 documentation - 26.4. unittest — Unit testing framework `_ + The documentation of the unittest framework in python 3 + `Python 2 documentation - 25.3. unittest — Unit testing framework `_ + The documentation of the earliest supported unittest framework - from Python 2.6 + `pytest: helps you write better programs `_ + The documentation of pytest - the framework actually used to run Ansible unit tests diff -Nru ansible-2.4.1.0/docs/docsite/rst/faq.rst ansible-2.4.2.0/docs/docsite/rst/faq.rst --- ansible-2.4.1.0/docs/docsite/rst/faq.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/faq.rst 2017-11-29 21:10:31.000000000 +0000 @@ -362,7 +362,7 @@ A steadfast rule is 'always use {{ }} except when `when:`'. Conditionals are always run through Jinja2 as to resolve the expression, -so `when:`, `failed_when:` and `changed_when:` are always templated and you should avoid adding `{{}}`. +so `when:`, `failed_when:`, and `changed_when:` are always templated and you should avoid adding `{{}}`. In most other cases you should always use the brackets, even if previously you could use variables without specifying (like `with_` clauses), as this made it hard to distinguish between an undefined variable and a string. diff -Nru ansible-2.4.1.0/docs/docsite/rst/galaxy.rst ansible-2.4.2.0/docs/docsite/rst/galaxy.rst --- ansible-2.4.1.0/docs/docsite/rst/galaxy.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/galaxy.rst 2017-11-29 21:10:31.000000000 +0000 @@ -274,7 +274,7 @@ Search for Roles ---------------- -Search the Galaxy database by tags, platforms, author and multiple keywords. For example: +Search the Galaxy database by tags, platforms, author, and multiple keywords. For example: :: @@ -361,7 +361,7 @@ Authenticate with Galaxy ------------------------ -Using the ``import``, ``delete`` and ``setup`` commands to manage your roles on the Galaxy website requires authentication, and the ``login`` command +Using the ``import``, ``delete``, and ``setup`` commands to manage your roles on the Galaxy website requires authentication, and the ``login`` command can be used to do just that. Before you can use the ``login`` command, you must create an account on the Galaxy website. The ``login`` command requires using your GitHub credentials. You can use your username and password, or you can create a `personal access token `_. If you choose to create a token, grant minimal access to the token, as it is used just to verify identify. @@ -382,8 +382,8 @@ Password for dsmith: Successfully logged into Galaxy as dsmith -When you choose to use your username and password, your password is not sent to Galaxy. It is used to authenticates with GitHub and create a personal access token. -It then sends the token to Galaxy, which in turn verifies that your identity and returns a Galaxy access token. After authentication completes the GitHub token is +When you choose to use your username and password, your password is not sent to Galaxy. It is used to authenticate with GitHub and create a personal access token. +It then sends the token to Galaxy, which in turn verifies your identity and returns a Galaxy access token. After authentication completes the GitHub token is destroyed. If you do not wish to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the *--github-token* option to pass a personal access token diff -Nru ansible-2.4.1.0/docs/docsite/rst/guide_azure.rst ansible-2.4.2.0/docs/docsite/rst/guide_azure.rst --- ansible-2.4.1.0/docs/docsite/rst/guide_azure.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/guide_azure.rst 2017-11-29 21:10:31.000000000 +0000 @@ -131,14 +131,14 @@ ------------------------- There are two ways to create a virtual machine, both involving the azure_rm_virtualmachine module. We can either create -a storage account, network interface, security group and public IP address and pass the names of these objects to the +a storage account, network interface, security group, and public IP address and pass the names of these objects to the module as parameters, or we can let the module do the work for us and accept the defaults it chooses. Creating Individual Components .............................. An Azure module is available to help you create a storage account, virtual network, subnet, network interface, -security group and public IP. Here is a full example of creating each of these and passing the names to the +security group, and public IP. Here is a full example of creating each of these and passing the names to the azure_rm_virtualmachine module at the end: .. code-block:: yaml @@ -315,7 +315,7 @@ NOTE: An .ini file will take precedence over environment variables. NOTE: The name of the .ini file is the basename of the inventory script (i.e. 'azure_rm') with a '.ini' -extension. This allows you to copy, rename and customize the inventory script and have matching .ini files all in +extension. This allows you to copy, rename, and customize the inventory script and have matching .ini files all in the same directory. Control grouping using the following variables defined in the environment: diff -Nru ansible-2.4.1.0/docs/docsite/rst/guide_cloudstack.rst ansible-2.4.2.0/docs/docsite/rst/guide_cloudstack.rst --- ansible-2.4.1.0/docs/docsite/rst/guide_cloudstack.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/guide_cloudstack.rst 2017-11-29 21:10:31.000000000 +0000 @@ -134,7 +134,7 @@ ````````````````````` .. versionadded:: 2.3 -Since Ansible 2.3 it is possible to use environment variables for domain (``CLOUDSTACK_DOMAIN``), account (``CLOUDSTACK_ACCOUNT``), project (``CLOUDSTACK_PROJECT``), VPC (``CLOUDSTACK_VPC``) and zone (``CLOUDSTACK_ZONE``). This simplifies the tasks by not repeating the arguments for every tasks. +Since Ansible 2.3 it is possible to use environment variables for domain (``CLOUDSTACK_DOMAIN``), account (``CLOUDSTACK_ACCOUNT``), project (``CLOUDSTACK_PROJECT``), VPC (``CLOUDSTACK_VPC``), and zone (``CLOUDSTACK_ZONE``). This simplifies the tasks by not repeating the arguments for every tasks. Below you see an example how it can be used in combination with Ansible's block feature: @@ -165,7 +165,7 @@ .. Note:: You are still able overwrite the environment variables using the module arguments, e.g. ``zone: sf-2`` -.. Note:: Unlike ``CLOUDSTACK_REGION`` these additional environment variables are ingored in the CLI ``cs``. +.. Note:: Unlike ``CLOUDSTACK_REGION`` these additional environment variables are ignored in the CLI ``cs``. Use Cases ````````` @@ -197,7 +197,7 @@ As you can see, the public IPs for our web servers and jumphost has been assigned as variable ``public_ip`` directly in the inventory. -The configure the jumphost, web servers and database servers, we use ``group_vars``. The ``group_vars`` directory contains 4 files for configuration of the groups: cloud-vm, jumphost, webserver and db-server. The cloud-vm is there for specifying the defaults of our cloud infrastructure. +To configure the jumphost, web servers, and database servers, we use ``group_vars``. The ``group_vars`` directory contains 4 files for configuration of the groups: cloud-vm, jumphost, webserver, and db-server. The cloud-vm is there for specifying the defaults of our cloud infrastructure. .. code-block:: yaml @@ -262,9 +262,9 @@ cs_staticnat: vm="{{ inventory_hostname_short }}" ip_address="{{ public_ip }}" when: public_ip is defined -In the above play we defined 3 tasks and use the group ``cloud-vm`` as target to handle all VMs in the cloud but instead SSH to these VMs, we use ``connetion=local`` to execute the API calls locally from our workstation. +In the above play we defined 3 tasks and used the group ``cloud-vm`` as target to handle all VMs in the cloud but instead SSH to these VMs, we use ``connection=local`` to execute the API calls locally from our workstation. -In the first task, we ensure we have a running VM created with the Debian template. If the VM is already created but stopped, it would just start it. If you like to change the offering on an existing VM, you must add ``force: yes`` to the task, which would stop the VM, change the offering and start the VM again. +In the first task, we ensure we have a running VM created with the Debian template. If the VM is already created but stopped, it would just start it. If you like to change the offering on an existing VM, you must add ``force: yes`` to the task, which would stop the VM, change the offering, and start the VM again. In the second task we ensure the ports are opened if we give a public IP to the VM. @@ -364,12 +364,12 @@ - name: show VM IP debug: msg="VM {{ inventory_hostname }} {{ vm.default_ip }}" - - name: assing IP to the inventory + - name: assign IP to the inventory set_fact: ansible_ssh_host={{ vm.default_ip }} - name: waiting for SSH to come up wait_for: port=22 host={{ vm.default_ip }} delay=5 -In the first play we setup the security groups, in the second play the VMs will created be assigned to these groups. Further you see, that we assign the public IP returned from the modules to the host inventory. This is needed as we do not know the IPs we will get in advance. In a next step you would configure the DNS servers with these IPs for accassing the VMs with their DNS name. +In the first play we setup the security groups, in the second play the VMs will created be assigned to these groups. Further you see, that we assign the public IP returned from the modules to the host inventory. This is needed as we do not know the IPs we will get in advance. In a next step you would configure the DNS servers with these IPs for accessing the VMs with their DNS name. In the last task we wait for SSH to be accessible, so any later play would be able to access the VM by SSH without failure. diff -Nru ansible-2.4.1.0/docs/docsite/rst/guide_docker.rst ansible-2.4.2.0/docs/docsite/rst/guide_docker.rst --- ansible-2.4.1.0/docs/docsite/rst/guide_docker.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/guide_docker.rst 2017-11-29 21:10:31.000000000 +0000 @@ -8,11 +8,11 @@ Swarm. Supports compose versions 1 and 2. docker_container - Manages the container lifecycle by providing the ability to create, update, stop, start and destroy a + Manages the container lifecycle by providing the ability to create, update, stop, start, and destroy a container. docker_image - Provides full control over images, including: build, pull, push, tag and remove. + Provides full control over images, including: build, pull, push, tag, and remove. docker_image_facts Inspects one or more images in the Docker host's image cache, providing the information as facts for making @@ -126,7 +126,7 @@ The maximum amount of time in seconds to wait on a response from the API. DOCKER_CERT_PATH - Path to the directory containing the client certificate, client key and CA certificate. + Path to the directory containing the client certificate, client key, and CA certificate. DOCKER_SSL_VERSION Provide a valid SSL version number. @@ -205,7 +205,7 @@ by docker-py. DOCKER_TIMEOUT: - The maximum amount of time in seconds to wait on a response fromm the API. Defaults to 60 seconds. + The maximum amount of time in seconds to wait on a response from the API. Defaults to 60 seconds. DOCKER_TLS: Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server. @@ -213,18 +213,18 @@ DOCKER_TLS_VERIFY: Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server. - Default is False + Defaults to False. DOCKER_TLS_HOSTNAME: When verifying the authenticity of the Docker Host server, provide the expected name of the server. Defaults to localhost. DOCKER_CERT_PATH: - Path to the directory containing the client certificate, client key and CA certificate. + Path to the directory containing the client certificate, client key, and CA certificate. DOCKER_SSL_VERSION: Provide a valid SSL version number. Default value determined by docker-py, which at the time of this writing - was 1.0 + was 1.0. In addition to the connection variables there are a couple variables used to control the execution and output of the script: diff -Nru ansible-2.4.1.0/docs/docsite/rst/guide_packet.rst ansible-2.4.2.0/docs/docsite/rst/guide_packet.rst --- ansible-2.4.1.0/docs/docsite/rst/guide_packet.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/guide_packet.rst 2017-11-29 21:10:31.000000000 +0000 @@ -8,7 +8,7 @@ `Packet.net `_ is a bare metal infrastructure host that's supported by Ansible (>=2.3) via a dynamic inventory script and two cloud modules. The two modules are: - packet_sshkey: adds a public SSH key from file or value to the Packet infrastructure. Every subsequently-created device will have this public key installed in .ssh/authorized_keys. -- packet_device: manages servers on Packet. You can use this module to create, restart and delete devices. +- packet_device: manages servers on Packet. You can use this module to create, restart, and delete devices. Note, this guide assumes you are familiar with Ansible and how it works. If you're not, have a look at their `docs `_ before getting started. @@ -183,7 +183,7 @@ As with most Ansible modules, the default states of the Packet modules are idempotent, meaning the resources in your project will remain the same after re-runs of a playbook. Thus, we can keep the ``packet_sshkey`` module call in our playbook. If the public key is already in your Packet account, the call will have no effect. -The second module call provisions 3 Packet Type 0 (specified using the 'plan' parameter) servers in the project identified via the 'project_id' parameter. The servers are all provisioned with CoresOS beta (the 'operating_system' parameter) and are customized with cloud-config user data passed to the 'user_data' parameter. +The second module call provisions 3 Packet Type 0 (specified using the 'plan' parameter) servers in the project identified via the 'project_id' parameter. The servers are all provisioned with CoreOS beta (the 'operating_system' parameter) and are customized with cloud-config user data passed to the 'user_data' parameter. The ``packet_device`` module has a boolean 'wait' parameter that defaults to 'false'. If set to 'true', Ansible will wait until the GET API call for a device will contain an Internet-routeable IP address. The 'wait' parameter allows us to use the IP address of the device as soon as it's available. diff -Nru ansible-2.4.1.0/docs/docsite/rst/guide_rax.rst ansible-2.4.2.0/docs/docsite/rst/guide_rax.rst --- ansible-2.4.1.0/docs/docsite/rst/guide_rax.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/guide_rax.rst 2017-11-29 21:10:31.000000000 +0000 @@ -457,7 +457,7 @@ Complete Environment ++++++++++++++++++++ -Build a complete webserver environment with servers, custom networks and load balancers, install nginx and create a custom index.html +Build a complete webserver environment with servers, custom networks and load balancers, install nginx, and create a custom index.html. .. code-block:: yaml diff -Nru ansible-2.4.1.0/docs/docsite/rst/guide_rolling_upgrade.rst ansible-2.4.2.0/docs/docsite/rst/guide_rolling_upgrade.rst --- ansible-2.4.1.0/docs/docsite/rst/guide_rolling_upgrade.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/guide_rolling_upgrade.rst 2017-11-29 21:10:31.000000000 +0000 @@ -176,7 +176,7 @@ {% endfor %} This loops over all of the hosts in the group called ``monitoring``, and adds an ACCEPT line for -each monitoring hosts' default IPV4 address to the current machine's iptables configuration, so that Nagios can monitor those hosts. +each monitoring hosts' default IPv4 address to the current machine's iptables configuration, so that Nagios can monitor those hosts. You can learn a lot more about Jinja2 and its capabilities `here `_, and you can read more about Ansible variables in general in the :doc:`playbooks_variables` section. @@ -220,6 +220,11 @@ delegate_to: "{{ item }}" with_items: "{{ groups.lbservers }}" + +.. note:: + - The ``serial`` keyword forces the play to be executed in 'batches'. Each batch counts as a full play with a subselection of hosts. + This has some consequences on play behavior. For example, if all hosts in a batch fails, the play fails, which in turn fails the entire run. You should consider this when combining with ``max_fail_percentage``. + The ``pre_tasks`` keyword just lets you list tasks to run before the roles are called. This will make more sense in a minute. If you look at the names of these tasks, you can see that we are disabling Nagios alerts and then removing the webserver that we are currently updating from the HAProxy load balancing pool. The ``delegate_to`` and ``with_items`` arguments, used together, cause Ansible to loop over each monitoring server and load balancer, and perform that operation (delegate that operation) on the monitoring or load balancing server, "on behalf" of the webserver. In programming terms, the outer loop is the list of web servers, and the inner loop is the list of monitoring servers. diff -Nru ansible-2.4.1.0/docs/docsite/rst/guide_vagrant.rst ansible-2.4.2.0/docs/docsite/rst/guide_vagrant.rst --- ansible-2.4.1.0/docs/docsite/rst/guide_vagrant.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/guide_vagrant.rst 2017-11-29 21:10:31.000000000 +0000 @@ -113,7 +113,7 @@ If you want to run Ansible manually, you will want to make sure to pass ``ansible`` or ``ansible-playbook`` commands the correct arguments, at least -for the *username*, the *SSH private key* and the *inventory*. +for the *username*, the *SSH private key*, and the *inventory*. Here is an example using the Vagrant global insecure key (``config.ssh.insert_key`` must be set to ``false`` in your ``Vagrantfile``): diff -Nru ansible-2.4.1.0/docs/docsite/rst/intro_bsd.rst ansible-2.4.2.0/docs/docsite/rst/intro_bsd.rst --- ansible-2.4.1.0/docs/docsite/rst/intro_bsd.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/intro_bsd.rst 2017-11-29 21:10:31.000000000 +0000 @@ -66,7 +66,7 @@ BSD Facts ````````` -Ansible gathers facts from the BSDs in a similar manner to Linux machines, but since the data, names and structures can vary for network, disks and other devices, one should expect the output to be slightly different yet still familiar to a BSD administrator. +Ansible gathers facts from the BSDs in a similar manner to Linux machines, but since the data, names, and structures can vary for network, disks, and other devices, one should expect the output to be slightly different yet still familiar to a BSD administrator. .. _bsd_contributions: diff -Nru ansible-2.4.1.0/docs/docsite/rst/intro_dynamic_inventory.rst ansible-2.4.2.0/docs/docsite/rst/intro_dynamic_inventory.rst --- ansible-2.4.1.0/docs/docsite/rst/intro_dynamic_inventory.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/intro_dynamic_inventory.rst 2017-11-29 21:10:31.000000000 +0000 @@ -185,7 +185,7 @@ ``security_group_Pete_s_Fancy_Group`` Tags - Each instance can have a variety of key/value pairs associated with it called Tags. The most common tag key is 'Name', though anything is possible. Each key/value pair is its own group of instances, again with special characters converted to underscores, in the format ``tag_KEY_VALUE`` + Each instance can have a variety of key/value pairs associated with it called Tags. The most common tag key is 'Name', though anything is possible. Each key/value pair is its own group of instances, again with special characters converted to underscores, in the format ``tag_KEY_VALUE``. e.g. ``tag_Name_Web`` can be used as is ``tag_Name_redis-master-001`` becomes ``tag_Name_redis_master_001`` @@ -265,7 +265,7 @@ .. note:: - An OpenStack RC file contains the environment variables required by the client tools to establish a connection with the cloud provider, such as the authentication URL, user name, password and region name. For more information on how to download, create or source an OpenStack RC file, please refer to `Set environment variables using the OpenStack RC file `_. + An OpenStack RC file contains the environment variables required by the client tools to establish a connection with the cloud provider, such as the authentication URL, user name, password, and region name. For more information on how to download, create or source an OpenStack RC file, please refer to `Set environment variables using the OpenStack RC file `_. You can confirm the file has been successfully sourced by running a simple command, such as `nova list` and ensuring it return no errors. @@ -286,13 +286,13 @@ Implicit use of inventory script ++++++++++++++++++++++++++++++++ -Download the latest version of the OpenStack dynamic inventory script, make it executable and copy it to `/etc/ansible/hosts`:: +Download the latest version of the OpenStack dynamic inventory script, make it executable, and copy it to `/etc/ansible/hosts`:: wget https://raw.githubusercontent.com/ansible/ansible/devel/contrib/inventory/openstack.py chmod +x openstack.py sudo cp openstack.py /etc/ansible/hosts -Download the sample configuration file, modify it to suit your needs and copy it to `/etc/ansible/openstack.yml`:: +Download the sample configuration file, modify it to suit your needs, and copy it to `/etc/ansible/openstack.yml`:: wget https://raw.githubusercontent.com/ansible/ansible/devel/contrib/inventory/openstack.yml vi openstack.yml diff -Nru ansible-2.4.1.0/docs/docsite/rst/intro_installation.rst ansible-2.4.2.0/docs/docsite/rst/intro_installation.rst --- ansible-2.4.1.0/docs/docsite/rst/intro_installation.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/intro_installation.rst 2017-11-29 21:10:31.000000000 +0000 @@ -269,7 +269,7 @@ $ sudo CFLAGS=-Qunused-arguments CPPFLAGS=-Qunused-arguments pip install ansible -Readers that use virtualenv can also install Ansible under virtualenv, though we'd recommend to not worry about it and just install Ansible globally. Do not use easy_install to install ansible directly. +Readers that use virtualenv can also install Ansible under virtualenv, though we'd recommend to not worry about it and just install Ansible globally. Do not use easy_install to install Ansible directly. .. _tagged_releases: diff -Nru ansible-2.4.1.0/docs/docsite/rst/intro_inventory.rst ansible-2.4.2.0/docs/docsite/rst/intro_inventory.rst --- ansible-2.4.1.0/docs/docsite/rst/intro_inventory.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/intro_inventory.rst 2017-11-29 21:10:31.000000000 +0000 @@ -11,7 +11,7 @@ You can specify a different inventory file using the ``-i `` option on the command line. Not only is this inventory configurable, but you can also use multiple inventory files at the same time and -pull inventory from dynamic or cloud sources or different formats (YAML, ini, etc), as described in :doc:`intro_dynamic_inventory`. +pull inventory from dynamic or cloud sources or different formats (YAML, ini, etc.), as described in :doc:`intro_dynamic_inventory`. Introduced in version 2.4, Ansible has inventory plugins to make this flexible and customizable. .. _inventoryformat: @@ -282,7 +282,7 @@ It is okay if these files do not exist, as this is an optional feature. As an advanced use case, you can create *directories* named after your groups or hosts, and -Ansible will read all the files in these directories. An example with the 'raleigh' group:: +Ansible will read all the files in these directories in lexicographical order. An example with the 'raleigh' group:: /etc/ansible/group_vars/raleigh/db_settings /etc/ansible/group_vars/raleigh/cluster_settings @@ -319,7 +319,7 @@ ansible_host The name of the host to connect to, if different from the alias you wish to give to it. ansible_port - The ssh port number, if not 22 + The ssh port number, if not 22. ansible_user The default ssh user name to use. @@ -327,7 +327,7 @@ Specific to the SSH connection: ansible_ssh_pass - The ssh password to use (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`) + The ssh password to use (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`). ansible_ssh_private_key_file Private key file used by ssh. Useful if using multiple keys and you don't want to use SSH agent. ansible_ssh_common_args @@ -349,17 +349,17 @@ Privilege escalation (see :doc:`Ansible Privilege Escalation` for further details): ansible_become - Equivalent to ``ansible_sudo`` or ``ansible_su``, allows to force privilege escalation + Equivalent to ``ansible_sudo`` or ``ansible_su``, allows to force privilege escalation. ansible_become_method - Allows to set privilege escalation method + Allows to set privilege escalation method. ansible_become_user - Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows to set the user you become through privilege escalation + Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows to set the user you become through privilege escalation. ansible_become_pass - Equivalent to ``ansible_sudo_pass`` or ``ansible_su_pass``, 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_pass`` or ``ansible_su_pass``, 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`). ansible_become_exe - Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``, allows you to set the executable for the escalation method selected + Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``, allows you to set the executable for the escalation method selected. ansible_become_flags - Equivalent to ``ansible_sudo_flags`` or ``ansible_su_flags``, allows you to set the flags passed to the selected escalation method. This can be also set globally in :file:`ansible.cfg` in the ``sudo_flags`` option + Equivalent to ``ansible_sudo_flags`` or ``ansible_su_flags``, allows you to set the flags passed to the selected escalation method. This can be also set globally in :file:`ansible.cfg` in the ``sudo_flags`` option. Remote host environment parameters: @@ -384,7 +384,7 @@ overrides ``executable`` in :file:`ansible.cfg` which defaults to :command:`/bin/sh`. You should really only change it if is not possible to use :command:`/bin/sh` (i.e. :command:`/bin/sh` is not installed on the target - machine or cannot be run from sudo.). + machine or cannot be run from sudo). Examples from an Ansible-INI host file:: @@ -449,7 +449,7 @@ :doc:`intro_adhoc` Examples of basic commands :doc:`playbooks` - Learning Ansible's configuration, deployment, and orchestration language. + Learning Ansible's configuration, deployment, and orchestration language `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups `irc.freenode.net `_ diff -Nru ansible-2.4.1.0/docs/docsite/rst/intro_networking.rst ansible-2.4.2.0/docs/docsite/rst/intro_networking.rst --- ansible-2.4.1.0/docs/docsite/rst/intro_networking.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/intro_networking.rst 2017-11-29 21:10:31.000000000 +0000 @@ -216,5 +216,5 @@ The waitfor argument must always start with result and then the command index in [], where 0 is the first command in the commands list, -1 is the second command, 2 is the third and so on. +1 is the second command, 2 is the third, and so on. diff -Nru ansible-2.4.1.0/docs/docsite/rst/intro_patterns.rst ansible-2.4.2.0/docs/docsite/rst/intro_patterns.rst --- ansible-2.4.1.0/docs/docsite/rst/intro_patterns.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/intro_patterns.rst 2017-11-29 21:10:31.000000000 +0000 @@ -58,7 +58,7 @@ webservers:!{{excluded}}:&{{required}} -You also don't have to manage by strictly defined groups. Individual host names, IPs and groups, can also be referenced using +You also don't have to manage by strictly defined groups. Individual host names, IPs, and groups, can also be referenced using wildcards .. code-block:: none diff -Nru ansible-2.4.1.0/docs/docsite/rst/intro_windows.rst ansible-2.4.2.0/docs/docsite/rst/intro_windows.rst --- ansible-2.4.1.0/docs/docsite/rst/intro_windows.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/intro_windows.rst 2017-11-29 21:10:31.000000000 +0000 @@ -59,7 +59,7 @@ # https://github.com/Microsoft/BashOnWindows/issues/816#issuecomment-301216901 for details source ~/.profile -After you've successfully run these commands, you can start to create your inventory, write example playbooks and start targeting systems using the plethora of available Windows modules. +After you've successfully run these commands, you can start to create your inventory, write example playbooks, and start targeting systems using the plethora of available Windows modules. If you want to run Ansible from source for development purposes, simply uninstall the pip-installed version (which will leave all the necessary dependencies behind), then clone the Ansible source, and run the hacking script to configure it to run from source:: @@ -94,7 +94,7 @@ Certificate +++++++++++ -Certificate authentication is similar to SSH where a certificate is assigned to a local user and instead of using a password to authenticate a certificate is used instead. +Certificate authentication is similar to SSH where a certificate is assigned to a local user and instead of using a password to authenticate a certificate is used. Kerberos @@ -142,7 +142,7 @@ Configuring Kerberos -------------------- -Edit your /etc/krb5.conf (which should be installed as a result of installing packages above) and add the following information for each domain you need to connect to: +Edit your `/etc/krb5.conf` (which should be installed as a result of installing packages above) and add the following information for each domain you need to connect to: In the section that starts with @@ -204,13 +204,13 @@ Ensure that forward and reverse DNS lookups are working properly on your domain. -To test this, ping the windows host you want to control by name then use the ip address returned with nslookup. You should get the same name back from DNS when you use nslookup on the ip address. +To test this, ping the Windows host you want to control by name then use the ip address returned with nslookup. You should get the same name back from DNS when you use nslookup on the ip address. If you get different hostnames back than the name you originally pinged, speak to your active directory administrator and get them to check that DNS Scavenging is enabled and that DNS and DHCP are updating each other. Ensure that the Ansible controller has a properly configured computer account in the domain. -Check your Ansible controller's clock is synchronised with your domain controller. Kerberos is time sensitive and a little clock drift can cause tickets not be granted. +Check your Ansible controller's clock is synchronised with your domain controller. Kerberos is time sensitive and a little clock drift can cause tickets not to be granted. Check you are using the real fully qualified domain name for the domain. Sometimes domains are commonly known to users by aliases. To check this run: @@ -242,7 +242,7 @@ CredSSP and TLS 1.2 ------------------- -CredSSP requires the remote host to have TLS 1.2 configured or else the connection will fail. TLS 1.2 is installed by default from Server 2012 and Windows 8 onwards. For Server 2008, 2008 R2 and Windows 7 you can add TLS 1.2 support by: +CredSSP requires the remote host to have TLS 1.2 configured or else the connection will fail. TLS 1.2 is installed by default from Server 2012 and Windows 8 onward. For Server 2008, 2008 R2, and Windows 7 you can add TLS 1.2 support by: * Installing the `TLS 1.2 update from Microsoft `_ * Adding the TLS 1.2 registry keys as shown on this `page `_ @@ -255,7 +255,7 @@ Inventory ````````` -Ansible's windows support relies on a few standard variables to indicate the username, password, and connection type (windows) of the remote hosts. These variables are most easily set up in inventory. This is used instead of SSH-keys or passwords as normally fed into Ansible:: +Ansible's Windows support relies on a few standard variables to indicate the username, password, and connection type (Windows) of the remote hosts. These variables are most easily set up in inventory. This is used instead of SSH-keys or passwords as normally fed into Ansible:: [windows] winserver1.example.com @@ -311,7 +311,7 @@ Windows System Prep ``````````````````` -In order for Ansible to manage your windows machines, you will have to enable and configure PowerShell remoting. +In order for Ansible to manage your Windows machines, you will have to enable and configure PowerShell remoting. To automate the setup of WinRM, you can run the `examples/scripts/ConfigureRemotingForAnsible.ps1 `_ script on the remote machine in a PowerShell console as an administrator. @@ -340,7 +340,7 @@ Management Framework 3.0, it may be necessary to install this hotfix http://support.microsoft.com/kb/2842230 to avoid receiving out of memory and stack overflow exceptions. Newly-installed Server 2008 - R2 systems which are not fully up to date with windows updates are known + R2 systems which are not fully up to date with Windows updates are known to have this issue. Windows 8.1 and Server 2012 R2 are not affected by this issue as they @@ -386,9 +386,9 @@ * template (also: win_template) * wait_for_connection -Some modules can be utilised in playbooks that target windows by delegating to localhost, depending on what you are +Some modules can be utilised in playbooks that target Windows by delegating to localhost, depending on what you are attempting to achieve. For example, ``assemble`` can be used to create a file on your ansible controller that is then -sent to your windows targets using ``win_copy``. +sent to your Windows targets using ``win_copy``. In many cases, there is no need to use or write an Ansible module. In particular, the ``script`` module can be used to run arbitrary PowerShell scripts, allowing Windows administrators familiar with PowerShell a very native way to do things, as in the following playbook:: @@ -425,7 +425,7 @@ # code goes here, reading in stdin as JSON and outputting JSON -The above magic is necessary to tell Ansible to mix in some common code and also know how to push modules out. The common code contains some nice wrappers around working with hash data structures and emitting JSON results, and possibly a few more useful things. Regular Ansible has this same concept for reusing Python code - this is just the windows equivalent. +The above magic is necessary to tell Ansible to mix in some common code and also know how to push modules out. The common code contains some nice wrappers around working with hash data structures and emitting JSON results, and possibly a few more useful things. Regular Ansible has this same concept for reusing Python code - this is just the Windows equivalent. What modules you see in ``windows/`` are just a start. Additional modules may be submitted as pull requests to github. @@ -434,7 +434,7 @@ Windows Facts ````````````` -Just as with Linux/Unix, facts can be gathered for windows hosts, which will return things such as the operating system version. To see what variables are available about a windows host, run the following:: +Just as with Linux/Unix, facts can be gathered for Windows hosts, which will return things such as the operating system version. To see what variables are available about a Windows host, run the following:: ansible winhost.example.com -m setup diff -Nru ansible-2.4.1.0/docs/docsite/rst/playbooks_filters.rst ansible-2.4.2.0/docs/docsite/rst/playbooks_filters.rst --- ansible-2.4.1.0/docs/docsite/rst/playbooks_filters.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/playbooks_filters.rst 2017-11-29 21:10:31.000000000 +0000 @@ -695,11 +695,11 @@ To use one value on true and another on false (new in version 1.9):: - {{ (name == "John") | ternary('Mr','Ms') }} + {{ (name == "John") | ternary('Mr','Ms') }} To concatenate a list into a string:: - {{ list | join(" ") }} + {{ list | join(" ") }} To get the last name of a file path, like 'foo.txt' out of '/etc/asdf/foo.txt':: @@ -735,7 +735,7 @@ To get the real path of a link (new in version 1.8):: - {{ path | realpath }} + {{ path | realpath }} To get the relative path of a link, from a start point (new in version 1.7):: diff -Nru ansible-2.4.1.0/docs/docsite/rst/playbooks_reuse_roles.rst ansible-2.4.2.0/docs/docsite/rst/playbooks_reuse_roles.rst --- ansible-2.4.1.0/docs/docsite/rst/playbooks_reuse_roles.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/playbooks_reuse_roles.rst 2017-11-29 21:10:31.000000000 +0000 @@ -198,7 +198,7 @@ 1. Pass different parameters in each role definition. 2. Add ``allow_duplicates: true`` to the ``meta/main.yml`` file for the role. -Example 1 - passing different paramters:: +Example 1 - passing different parameters:: --- - hosts: webservers diff -Nru ansible-2.4.1.0/docs/docsite/rst/playbooks_reuse.rst ansible-2.4.2.0/docs/docsite/rst/playbooks_reuse.rst --- ansible-2.4.1.0/docs/docsite/rst/playbooks_reuse.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/playbooks_reuse.rst 2017-11-29 21:10:31.000000000 +0000 @@ -52,8 +52,8 @@ Using ``include*`` does have some limitations when compared to ``import*`` statements: -* Tags which only exist inside a dynamic include will not show up in --list-tags output. -* Tasks which only exist inside a dynamic include will not show up in --list-tasks output. +* Tags which only exist inside a dynamic include will not show up in ``--list-tags`` output. +* Tasks which only exist inside a dynamic include will not show up in ``--list-tasks`` output. * You cannot use ``notify`` to trigger a handler name which comes from inside a dynamic include (see note below). * You cannot use ``--start-at-task`` to begin execution at a task inside a dynamic include. diff -Nru ansible-2.4.1.0/docs/docsite/rst/playbooks_variables.rst ansible-2.4.2.0/docs/docsite/rst/playbooks_variables.rst --- ansible-2.4.1.0/docs/docsite/rst/playbooks_variables.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/playbooks_variables.rst 2017-11-29 21:10:31.000000000 +0000 @@ -836,13 +836,16 @@ * role defaults [1]_ * inventory file or script group vars [2]_ - * inventory group_vars/all - * playbook group_vars/all - * inventory group_vars/* - * playbook group_vars/* + * inventory group_vars/all [3]_ + * playbook group_vars/all [3]_ + * inventory group_vars/* [3]_ + * playbook group_vars/* [3]_ * inventory file or script host vars [2]_ * inventory host_vars/* * playbook host_vars/* + * host facts / cached set_facts [4]_ + * inventory host_vars/* [3]_ + * playbook host_vars/* [3]_ * host facts * play vars * play vars_prompt @@ -862,6 +865,9 @@ .. [1] Tasks in each role will see their own role's defaults. Tasks defined outside of a role will see the last role's defaults. .. [2] Variables defined in inventory file or provided by dynamic inventory. +.. [3] Includes vars added by 'vars plugins' as well as host_vars and group_vars which are added by the default vars plugin shipped with Ansible. +.. [4] When created with set_facts's cacheable option, variables will have the high precedence in the play, + but will be the same as a host facts precedence when they come from the cache. .. note:: Within any section, redefining a var will overwrite the previous instance. If multiple groups have the same variable, the last one loaded wins. diff -Nru ansible-2.4.1.0/docs/docsite/rst/playbooks_vault.rst ansible-2.4.2.0/docs/docsite/rst/playbooks_vault.rst --- ansible-2.4.1.0/docs/docsite/rst/playbooks_vault.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/playbooks_vault.rst 2017-11-29 21:10:31.000000000 +0000 @@ -3,9 +3,9 @@ .. 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. +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. -To enable this feature, a command line tool, `ansible-vault` is used to edit files, and a command line flag `--ask-vault-pass` or `--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. +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. 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`. @@ -35,7 +35,7 @@ This is something you may wish to do if using Ansible from a continuous integration system like Jenkins. -(The `--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). +The :option:`--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. .. _single_encrypted_variable: @@ -66,6 +66,6 @@ ```````````````````` 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 args, or via an interactive prompt. +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`. diff -Nru ansible-2.4.1.0/docs/docsite/rst/porting_guide_2.0.rst ansible-2.4.2.0/docs/docsite/rst/porting_guide_2.0.rst --- ansible-2.4.1.0/docs/docsite/rst/porting_guide_2.0.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/porting_guide_2.0.rst 2017-11-29 21:10:31.000000000 +0000 @@ -171,7 +171,7 @@ with_items: myvar_{{rest_of_name}} - This worked 'by accident' as the errors were retemplated and ended up resolving the variable, it was never intended as valid syntax and now properly returns an error, use the following instead.:: + This worked 'by accident' as the errors were retemplated and ended up resolving the variable, it was never intended as valid syntax and now properly returns an error, use the following instead:: hostvars[inventory_hostname]['myvar_' + rest_of_name] @@ -287,7 +287,7 @@ You may find the following tips useful: -* Check whether the ansible-2.0 class(es) are available and if they are missing (ansible-1.9.x) mimic them with the needed methods (e.g. ``__init__``) +* Check whether the ansible-2.0 class(es) are available and if they are missing (ansible-1.9.x) mimic them with the needed methods (e.g. ``__init__``). * When ansible-2.0 python modules are imported, and they fail (ansible-1.9.x), catch the ``ImportError`` exception and perform the equivalent imports for ansible-1.9.x. With possible translations (e.g. importing specific methods). @@ -297,7 +297,7 @@ * When doing plugin development, it is very useful to have the ``warning()`` method during development, but it is also important to emit warnings for deadends (cases that you expect should never be triggered) or corner cases (e.g. cases where you expect misconfigurations). -* It helps to look at other plugins in ansible-1.9.x and ansible-2.0 to understand how the API works and what modules, classes and methods are available. +* It helps to look at other plugins in ansible-1.9.x and ansible-2.0 to understand how the API works and what modules, classes, and methods are available. Lookup plugins diff -Nru ansible-2.4.1.0/docs/docsite/rst/porting_guide_2.4.rst ansible-2.4.2.0/docs/docsite/rst/porting_guide_2.4.rst --- ansible-2.4.1.0/docs/docsite/rst/porting_guide_2.4.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/porting_guide_2.4.rst 2017-11-29 21:10:31.000000000 +0000 @@ -131,6 +131,57 @@ * Any callbacks inheriting from other callbacks might need to also be updated to contain the same documented options as the parent or the options won't be available. This is noted in the developer guide. +Template lookup plugin: Escaping Strings +---------------------------------------- + +Prior to Ansible 2.4, backslashes in strings passed to the template lookup plugin would be escaped +automatically. In 2.4, users are responsible for escaping backslashes themselves. This change +brings the template lookup plugin inline with the template module so that the same backslash +escaping rules apply to both. + +If you have a template lookup like this:: + + - debug: + msg: '{{ lookup("template", "template.j2") }}' + +**OLD** In Ansible 2.3 (and earlier) :file:`template.j2` would look like this: + +.. code-block:: jinja + + {{ "name surname" | regex_replace("^[^\s]+\s+(.*)", "\1") }} + +**NEW** In Ansible 2.4 it should be changed to look like this: + +.. code-block:: jinja + + {{ "name surname" | regex_replace("^[^\\s]+\\s+(.*)", "\\1") }} + +Tests +===== + +Tests succeeded/failed +----------------------- + +Prior to Ansible version 2.4, a task return code of ``rc`` would override a return code of ``failed``. In version 2.4, both ``rc`` and ``failed`` are used to calculate the state of the task. Because of this, test plugins ``succeeded``/``failed``` have also been changed. This means that overriding a task failure with ``failed_when: no`` will result in ``succeeded``/``failed`` returning ``True``/``False``. For example: + + - command: /bin/false + register: result + failed_when: no + + - debug: + msg: 'This is printed on 2.3' + when: result|failed + + - debug: + msg: 'This is printed on 2.4' + when: result|succeeded + + - debug: + msg: 'This is always printed' + when: result.rc != 0 + +As we can see from the example above, in Ansible 2.3 ``succeeded``/``failed`` only checked the value of ``rc``. + Networking ========== diff -Nru ansible-2.4.1.0/docs/docsite/rst/release_and_maintenance.rst ansible-2.4.2.0/docs/docsite/rst/release_and_maintenance.rst --- ansible-2.4.1.0/docs/docsite/rst/release_and_maintenance.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/release_and_maintenance.rst 2017-11-29 21:10:31.000000000 +0000 @@ -4,7 +4,7 @@ .. contents:: Topics :local: -.. _schedule: +.. _release_cycle: Release cycle ````````````` @@ -13,15 +13,18 @@ This cycle can be extended in order to allow for larger changes to be properly implemented and tested before a new release is made available. -Ansible supports the two most recent major stable releases. -For more information, read about the -`development and stable version maintenance workflow`_. +Ansible has a graduated support structure that extends to three major releases. +For more information, read about the `development and stable version maintenance workflow`_ or see +the chart in :ref:`schedule` for the degrees to which current releases are supported. + +.. note:: Support for three major releases began with Ansible-2.4. Ansible-2.3 and older versions + are only supported for two releases. If you are using a release of Ansible that is no longer supported, we strongly encourage you to upgrade as soon as possible in order to benefit from the latest features and security fixes. -Older unsupported versions of Ansible can contain unfixed security +Older, unsupported versions of Ansible can contain unfixed security vulnerabilities (*CVE*). You can refer to the `porting guide`_ for tips on updating your Ansible @@ -29,31 +32,30 @@ .. _porting guide: https://docs.ansible.com/ansible/porting_guide_2.0.html +.. _release_schedule: + Release status `````````````` -+-----------------+----------------------------+----------------------------------------+ -| Ansible Release | Latest Version | Status | -+=================+============================+========================================+ -| devel | `2.5`_ (unreleased, trunk) | In development | -+-----------------+----------------------------+----------------------------------------+ -| 2.4 | `2.4.1`_ (2017-10-25) | Supported (bug **and** security fixes) | -+-----------------+----------------------------+----------------------------------------+ -| 2.3 | `2.3.2`_ (2017-08-08) | Supported (bug **and** security fixes) | -+-----------------+----------------------------+----------------------------------------+ -| 2.2 | `2.2.3`_ (2017-05-09) | Supported (**only** security fixes) | -+-----------------+----------------------------+----------------------------------------+ -| 2.1 | `2.1.6`_ (2017-06-01) | Unsupported (end of life) | -+-----------------+----------------------------+----------------------------------------+ -| 2.0 | `2.0.2`_ (2016-04-19) | Unsupported (end of life) | -+-----------------+----------------------------+----------------------------------------+ -| 1.9 | `1.9.6`_ (2016-04-15) | Unsupported (end of life) | -+-----------------+----------------------------+----------------------------------------+ -| <1.9 | n/a | Unsupported (end of life) | -+-----------------+----------------------------+----------------------------------------+ +=============== ========================== ================================================= +Ansible Release Latest Version Status +=============== ========================== ================================================= +devel `2.5`_ (unreleased, trunk) In development +2.4 `2.4.2`_ (2017-11-29) Supported (security **and** general bug fixes) +2.3 `2.3.2`_ (2017-08-08) Supported (security **and** critical bug fixes) +2.2 `2.2.3`_ (2017-05-09) Unsupported (end of life) +2.1 `2.1.6`_ (2017-06-01) Unsupported (end of life) +2.0 `2.0.2`_ (2016-04-19) Unsupported (end of life) +1.9 `1.9.6`_ (2016-04-15) Unsupported (end of life) +<1.9 n/a Unsupported (end of life) +=============== ========================== ================================================= + +.. note:: Starting with Ansible-2.4, support lasts for 3 releases. Thus Ansible-2.4 will receive + security and general bug fixes when it is first released, security and critical bug fixes when + 2.5 is released, and **only** security fixes once 2.6 is released. .. _2.5: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md -.. _2.4.1: https://github.com/ansible/ansible/blob/stable-2.4/CHANGELOG.md +.. _2.4.2: https://github.com/ansible/ansible/blob/stable-2.4/CHANGELOG.md .. _2.3.2: https://github.com/ansible/ansible/blob/stable-2.3/CHANGELOG.md .. _2.2.3: https://github.com/ansible/ansible/blob/stable-2.2/CHANGELOG.md .. _2.1.6: https://github.com/ansible/ansible/blob/stable-2.1/CHANGELOG.md @@ -63,18 +65,23 @@ .. _support_life: .. _methods: + Development and stable version maintenance workflow ``````````````````````````````````````````````````` The Ansible community develops and maintains Ansible on GitHub_. -New modules, plugins, features and bugfixes will always be integrated in what -will become the next major version of Ansible. -This work is tracked on the ``devel`` git branch. - -Ansible provides bugfixes and security improvements for the most recent major -release while the previous major release will only receive security patches. -This work is tracked on the ``stable-`` git branches. +New modules, plugins, features, and bugfixes will always be integrated in what will become the next +major version of Ansible. This work is tracked on the ``devel`` git branch. + +Ansible provides bugfixes and security improvements for the most recent major release. The previous +major release will only receive fixes for security issues and critical bugs. Ansible only applies +security fixes to releases which are two releases old. This work is tracked on the +``stable-`` git branches. + +.. note:: Support for three major releases began with Ansible-2.4. Ansible-2.3 and older versions + are only supported for two releases with the first stage including both security and general bug + fixes while the second stage includes security and critical bug fixes. The fixes that land in supported stable branches will eventually be released as a new version when necessary. @@ -88,6 +95,7 @@ .. _GitHub: https://github.com/ansible/ansible .. _changelog: https://github.com/ansible/ansible/blob/devel/CHANGELOG.md + Release candidates ~~~~~~~~~~~~~~~~~~ @@ -111,7 +119,7 @@ bugs that the Ansible core maintainers consider should be fixed before the final release. -.. _freezing: +.. _release_freezing: Feature freeze ~~~~~~~~~~~~~~ diff -Nru ansible-2.4.1.0/docs/docsite/rst/vault.rst ansible-2.4.2.0/docs/docsite/rst/vault.rst --- ansible-2.4.1.0/docs/docsite/rst/vault.rst 2017-10-26 05:55:44.000000000 +0000 +++ ansible-2.4.2.0/docs/docsite/rst/vault.rst 2017-11-29 21:10:31.000000000 +0000 @@ -14,12 +14,12 @@ 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! +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 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. However, that might be a little too much and could annoy your coworkers :) +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 -given as the 'src' argument to the :ref:`copy `, :ref:`template