From 7d7051fc546087151826ce5170f12056bbe8fe37 Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Mon, 26 Jun 2017 16:26:53 +0100 Subject: [PATCH] Mutually reference Windows and non-Windows modules (#25482) * Mutually reference Windows and non-Windows modules To make it easier for Windows or non-Windows users to find the relevant module information, we are mutually referencing both variants in their documentation. We are also adding a special note if a module works on both Windows and non-Windows targets. * Mutually reference Windows and non-Windows modules To make it easier for Windows or non-Windows users to find the relevant module information, we are mutually referencing both variants in their documentation. We are also adding a special note if a module works on both Windows and non-Windows targets. * Replace 'look at' with 'use', as requested ci_complete --- lib/ansible/modules/commands/command.py | 2 ++ lib/ansible/modules/commands/raw.py | 2 ++ lib/ansible/modules/commands/script.py | 2 ++ lib/ansible/modules/commands/shell.py | 3 ++- lib/ansible/modules/files/copy.py | 2 ++ lib/ansible/modules/files/fetch.py | 2 ++ lib/ansible/modules/files/file.py | 2 ++ lib/ansible/modules/files/find.py | 3 +++ lib/ansible/modules/files/stat.py | 3 +++ lib/ansible/modules/files/tempfile.py | 3 +++ lib/ansible/modules/files/unarchive.py | 4 +++- lib/ansible/modules/inventory/add_host.py | 2 ++ lib/ansible/modules/inventory/group_by.py | 2 ++ lib/ansible/modules/net_tools/basics/get_url.py | 3 +++ lib/ansible/modules/net_tools/basics/slurp.py | 2 ++ lib/ansible/modules/net_tools/basics/uri.py | 2 ++ lib/ansible/modules/packaging/os/package.py | 2 ++ lib/ansible/modules/system/group.py | 4 +++- lib/ansible/modules/system/ping.py | 3 +++ lib/ansible/modules/system/service.py | 3 +++ lib/ansible/modules/system/setup.py | 2 ++ lib/ansible/modules/system/user.py | 2 ++ lib/ansible/modules/utilities/helper/meta.py | 5 +++-- lib/ansible/modules/utilities/logic/assert.py | 4 +++- lib/ansible/modules/utilities/logic/async_status.py | 8 +++----- lib/ansible/modules/utilities/logic/debug.py | 4 +++- lib/ansible/modules/utilities/logic/fail.py | 3 +++ lib/ansible/modules/utilities/logic/include.py | 2 ++ lib/ansible/modules/utilities/logic/include_role.py | 4 +++- lib/ansible/modules/utilities/logic/include_vars.py | 3 +++ lib/ansible/modules/utilities/logic/pause.py | 2 ++ lib/ansible/modules/utilities/logic/set_fact.py | 2 ++ lib/ansible/modules/utilities/logic/set_stats.py | 3 +++ lib/ansible/modules/utilities/logic/wait_for.py | 4 +++- .../modules/utilities/logic/wait_for_connection.py | 3 +++ lib/ansible/modules/windows/win_command.py | 2 ++ lib/ansible/modules/windows/win_copy.py | 3 +++ lib/ansible/modules/windows/win_file.py | 2 ++ lib/ansible/modules/windows/win_find.py | 3 +++ lib/ansible/modules/windows/win_get_url.py | 3 +++ lib/ansible/modules/windows/win_group.py | 5 ++++- lib/ansible/modules/windows/win_package.py | 3 +++ lib/ansible/modules/windows/win_ping.py | 8 ++++++-- lib/ansible/modules/windows/win_service.py | 5 ++++- lib/ansible/modules/windows/win_shell.py | 5 ++++- lib/ansible/modules/windows/win_stat.py | 5 ++++- lib/ansible/modules/windows/win_tempfile.py | 3 +++ lib/ansible/modules/windows/win_unzip.py | 2 ++ lib/ansible/modules/windows/win_uri.py | 3 +++ lib/ansible/modules/windows/win_user.py | 3 +++ 50 files changed, 137 insertions(+), 20 deletions(-) diff --git a/lib/ansible/modules/commands/command.py b/lib/ansible/modules/commands/command.py index 01a83982bf..0b99201155 100644 --- a/lib/ansible/modules/commands/command.py +++ b/lib/ansible/modules/commands/command.py @@ -35,6 +35,7 @@ description: processed through the shell, so variables like C($HOME) and operations like C("<"), C(">"), C("|"), C(";") and C("&") will not work (use the M(shell) module if you need these features). + - For Windows targets, use the M(win_command) module instead. options: free_form: description: @@ -76,6 +77,7 @@ notes: The C(command) module is much more secure as it's not affected by the user's environment. - " C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this." + - For Windows targets, use the M(win_command) module instead. author: - Ansible Core Team - Michael DeHaan diff --git a/lib/ansible/modules/commands/raw.py b/lib/ansible/modules/commands/raw.py index 7b6fb1e1ee..208ffa429d 100644 --- a/lib/ansible/modules/commands/raw.py +++ b/lib/ansible/modules/commands/raw.py @@ -50,6 +50,7 @@ description: available. There is no change handler support for this module. - This module does not require python on the remote system, much like the M(script) module. + - This module is also supported for Windows targets. notes: - "If using raw from a playbook, you may need to disable fact gathering using C(gather_facts: no) if you're using C(raw) to bootstrap python @@ -59,6 +60,7 @@ notes: - the C(environment) keyword does not work with raw normally, it requires a shell which means it only works if C(executable) is set or using the module with privilege escalation (C(become)). + - This module is also supported for Windows targets. author: - Ansible Core Team - Michael DeHaan diff --git a/lib/ansible/modules/commands/script.py b/lib/ansible/modules/commands/script.py index 875b073148..755792f6e5 100644 --- a/lib/ansible/modules/commands/script.py +++ b/lib/ansible/modules/commands/script.py @@ -30,6 +30,7 @@ description: - "The given script will be processed through the shell environment on the remote node. " - "This module does not require python on the remote system, much like the M(raw) module. " + - This module is also supported for Windows targets. options: free_form: description: @@ -53,6 +54,7 @@ notes: - It is usually preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points! - The ssh connection plugin will force pseudo-tty allocation via -tt when scripts are executed. pseudo-ttys do not have a stderr channel and all stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a copy+command set of tasks instead of using script. + - This module is also supported for Windows targets. author: - Ansible Core Team - Michael DeHaan diff --git a/lib/ansible/modules/commands/shell.py b/lib/ansible/modules/commands/shell.py index 2a048c6c7e..dbed1ff238 100644 --- a/lib/ansible/modules/commands/shell.py +++ b/lib/ansible/modules/commands/shell.py @@ -30,6 +30,7 @@ description: - The C(shell) module takes the command name followed by a list of space-delimited arguments. It is almost exactly like the M(command) module but runs the command through a shell (C(/bin/sh)) on the remote node. + - For Windows targets, use the M(win_shell) module instead. version_added: "0.2" options: free_form: @@ -75,7 +76,7 @@ notes: judgement. - To sanitize any variables passed to the shell module, you should use "{{ var | quote }}" instead of just "{{ var }}" to make sure they don't include evil things like semicolons. - + - For Windows targets, use the M(win_shell) module instead. requirements: [ ] author: - Ansible Core Team diff --git a/lib/ansible/modules/files/copy.py b/lib/ansible/modules/files/copy.py index d6ec226d69..7187571057 100644 --- a/lib/ansible/modules/files/copy.py +++ b/lib/ansible/modules/files/copy.py @@ -32,6 +32,7 @@ description: - The C(copy) module copies a file from the local or remote machine to a location on the remote machine. Use the M(fetch) module to copy files from remote locations to the local box. If you need variable interpolation in copied files, use the M(template) module. + - For Windows targets, use the M(win_copy) module instead. options: src: description: @@ -106,6 +107,7 @@ author: notes: - The "copy" module recursively copy facility does not scale to lots (>hundreds) of files. For alternative, see synchronize module, which is a wrapper around rsync. + - For Windows targets, use the M(win_copy) module instead. ''' EXAMPLES = ''' diff --git a/lib/ansible/modules/files/fetch.py b/lib/ansible/modules/files/fetch.py index c3fc43d3e8..2be8b209cc 100644 --- a/lib/ansible/modules/files/fetch.py +++ b/lib/ansible/modules/files/fetch.py @@ -28,6 +28,7 @@ description: - This module works like M(copy), but in reverse. It is used for fetching files from remote machines and storing them locally in a file tree, organized by hostname. + - This module is also supported for Windows targets. version_added: "0.2" options: src: @@ -86,6 +87,7 @@ notes: playbook authors are encouraged to use fail_when or ignore_errors to get this ability. They may also explicitly set fail_on_missing to False to get the non-failing behaviour. + - This module is also supported for Windows targets. ''' EXAMPLES = ''' diff --git a/lib/ansible/modules/files/file.py b/lib/ansible/modules/files/file.py index 4c10b0550f..db68dc9c30 100644 --- a/lib/ansible/modules/files/file.py +++ b/lib/ansible/modules/files/file.py @@ -33,7 +33,9 @@ description: - Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories. Many other modules support the same options as the C(file) module - including M(copy), M(template), and M(assemble). + - For Windows targets, use the M(win_file) module instead. notes: + - For Windows targets, use the M(win_file) module instead. - See also M(copy), M(template), M(assemble) requirements: [ ] author: diff --git a/lib/ansible/modules/files/find.py b/lib/ansible/modules/files/find.py index cf8ae2991a..4ce478e1b7 100644 --- a/lib/ansible/modules/files/find.py +++ b/lib/ansible/modules/files/find.py @@ -31,6 +31,7 @@ version_added: "2.0" short_description: Return a list of files based on specific criteria description: - Return a list of files based on specific criteria. Multiple criteria are AND'd together. + - For Windows targets, use the M(win_find) module instead. options: age: description: @@ -96,6 +97,8 @@ options: choices: [ 'no', 'yes' ] description: - If false the patterns are file globs (shell) if true they are python regexes. +notes: + - For Windows targets, use the M(win_find) module instead. ''' diff --git a/lib/ansible/modules/files/stat.py b/lib/ansible/modules/files/stat.py index 33c55905d3..3133272329 100644 --- a/lib/ansible/modules/files/stat.py +++ b/lib/ansible/modules/files/stat.py @@ -25,6 +25,7 @@ version_added: "1.3" short_description: Retrieve file or file system status description: - Retrieves facts for a file similar to the linux/unix 'stat' command. + - For Windows targets, use the M(win_stat) module instead. options: path: description: @@ -73,6 +74,8 @@ options: default: 'yes' version_added: "2.3" aliases: [ attr, attributes ] +notes: + - For Windows targets, use the M(win_stat) module instead. author: Bruce Pennypacker (@bpennypacker) ''' diff --git a/lib/ansible/modules/files/tempfile.py b/lib/ansible/modules/files/tempfile.py index 050ee3b192..7ed92a73d8 100644 --- a/lib/ansible/modules/files/tempfile.py +++ b/lib/ansible/modules/files/tempfile.py @@ -34,6 +34,7 @@ description: - The C(tempfile) module creates temporary files and directories. C(mktemp) command takes different parameters on various systems, this module helps to avoid troubles related to that. Files/directories created by module are accessible only by creator. In case you need to make them world-accessible you need to use M(file) module. + - For Windows targets, use the M(win_tempfile) module instead. options: state: description: @@ -56,6 +57,8 @@ options: - Suffix of file/directory name created by module. required: false default: "" +notes: + - For Windows targets, use the M(win_tempfile) module instead. ''' EXAMPLES = """ diff --git a/lib/ansible/modules/files/unarchive.py b/lib/ansible/modules/files/unarchive.py index 02db2e19d9..20202979e5 100644 --- a/lib/ansible/modules/files/unarchive.py +++ b/lib/ansible/modules/files/unarchive.py @@ -35,13 +35,14 @@ description: - The C(unarchive) module unpacks an archive. - By default, it will copy the source file from the local system to the target before unpacking. - Set C(remote_src=yes) to unpack an archive which already exists on the target. + - For Windows targets, use the M(win_unzip) module instead. options: src: description: - If C(remote_src=no) (default), local path to archive file to copy to the target server; can be absolute or relative. If C(remote_src=yes), path on the target server to existing archive file to unpack. - If C(remote_src=yes) and C(src) contains C(://), the remote machine will download the file from the URL first. (version_added 2.0). This is only for - simple cases, for full download support look at the M(get_url) module. + simple cases, for full download support use the M(get_url) module. required: true dest: description: @@ -107,6 +108,7 @@ notes: are not touched. This is the same behavior as a normal archive extraction. - Existing files/directories in the destination which are not in the archive are ignored for purposes of deciding if the archive should be unpacked or not. + - For Windows targets, use the M(win_unzip) module instead. ''' EXAMPLES = r''' diff --git a/lib/ansible/modules/inventory/add_host.py b/lib/ansible/modules/inventory/add_host.py index e48cbf4837..1e2c8398c9 100644 --- a/lib/ansible/modules/inventory/add_host.py +++ b/lib/ansible/modules/inventory/add_host.py @@ -27,6 +27,7 @@ short_description: add a host (and alternatively a group) to the ansible-playboo description: - Use variables to create new hosts and groups in inventory for use in later plays of the same playbook. Takes variables so you can define the new hosts more fully. + - This module is also supported for Windows targets. version_added: "0.9" options: name: @@ -42,6 +43,7 @@ options: notes: - This module bypasses the play host loop and only runs once for all the hosts in the play, if you need it to iterate use a with\_ directive. + - This module is also supported for Windows targets. author: - "Ansible Core Team" - "Seth Vidal" diff --git a/lib/ansible/modules/inventory/group_by.py b/lib/ansible/modules/inventory/group_by.py index 724c01a902..73e67625d7 100644 --- a/lib/ansible/modules/inventory/group_by.py +++ b/lib/ansible/modules/inventory/group_by.py @@ -26,6 +26,7 @@ module: group_by short_description: Create Ansible groups based on facts description: - Use facts to create ad-hoc groups that can be used later in a playbook. + - This module is also supported for Windows targets. version_added: "0.9" options: key: @@ -35,6 +36,7 @@ options: author: "Jeroen Hoekx (@jhoekx)" notes: - Spaces in group names are converted to dashes '-'. + - This module is also supported for Windows targets. ''' EXAMPLES = ''' diff --git a/lib/ansible/modules/net_tools/basics/get_url.py b/lib/ansible/modules/net_tools/basics/get_url.py index 00129413af..009573894d 100644 --- a/lib/ansible/modules/net_tools/basics/get_url.py +++ b/lib/ansible/modules/net_tools/basics/get_url.py @@ -41,6 +41,7 @@ description: your proxy environment for both protocols is correct. - From Ansible 2.4 when run with C(--check), it will do a HEAD request to validate the URL but will not download the entire file or verify it against hashes. + - For Windows targets, use the M(win_get_url) module instead. version_added: '0.6' options: url: @@ -162,6 +163,8 @@ options: # informational: requirements for nodes extends_documentation_fragment: - files +notes: + - For Windows targets, use the M(win_get_url) module instead. author: Jan-Piet Mens (@jpmens) ''' diff --git a/lib/ansible/modules/net_tools/basics/slurp.py b/lib/ansible/modules/net_tools/basics/slurp.py index 298b065d4f..21e1a8e93b 100644 --- a/lib/ansible/modules/net_tools/basics/slurp.py +++ b/lib/ansible/modules/net_tools/basics/slurp.py @@ -30,6 +30,7 @@ short_description: Slurps a file from remote nodes description: - This module works like M(fetch). It is used for fetching a base64- encoded blob containing the data in a remote file. + - This module is also supported for Windows targets. options: src: description: @@ -39,6 +40,7 @@ options: notes: - This module returns an 'in memory' base64 encoded version of the file, take into account that this will require at least twice the RAM as the original file size. + - This module is also supported for Windows targets. - "See also: M(fetch)" author: - Ansible Core Team diff --git a/lib/ansible/modules/net_tools/basics/uri.py b/lib/ansible/modules/net_tools/basics/uri.py index 71b9707b5a..e33aed776d 100644 --- a/lib/ansible/modules/net_tools/basics/uri.py +++ b/lib/ansible/modules/net_tools/basics/uri.py @@ -32,6 +32,7 @@ short_description: Interacts with webservices description: - Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE HTTP authentication mechanisms. + - For Windows targets, use the M(win_uri) module instead. version_added: "1.1" options: url: @@ -174,6 +175,7 @@ options: version_added: 2.4 notes: - The dependency on httplib2 was removed in Ansible 2.1 + - For Windows targets, use the M(win_uri) module instead. author: "Romeo Theriault (@romeotheriault)" ''' diff --git a/lib/ansible/modules/packaging/os/package.py b/lib/ansible/modules/packaging/os/package.py index ea09f4f2b1..5b88e1e096 100644 --- a/lib/ansible/modules/packaging/os/package.py +++ b/lib/ansible/modules/packaging/os/package.py @@ -33,6 +33,7 @@ author: short_description: Generic OS package manager description: - Installs, upgrade and removes packages using the underlying OS package manager. + - For Windows targets, use the M(win_package) module instead. options: name: description: @@ -53,6 +54,7 @@ requirements: - Whatever is required for the package plugins specific for each system. notes: - This module actually calls the pertinent package modules for each system (apt, yum, etc). + - For Windows targets, use the M(win_package) module instead. ''' EXAMPLES = ''' - name: install the latest version of ntpdate diff --git a/lib/ansible/modules/system/group.py b/lib/ansible/modules/system/group.py index 3619903ed9..0e68a65321 100644 --- a/lib/ansible/modules/system/group.py +++ b/lib/ansible/modules/system/group.py @@ -32,6 +32,7 @@ short_description: Add or remove groups requirements: [ groupadd, groupdel, groupmod ] description: - Manage presence of groups on a host. + - For Windows targets, use the M(win_group) module instead. options: name: required: true @@ -53,7 +54,8 @@ options: choices: [ "yes", "no" ] description: - If I(yes), indicates that the group created is a system group. - +notes: + - For Windows targets, use the M(win_group) module instead. ''' EXAMPLES = ''' diff --git a/lib/ansible/modules/system/ping.py b/lib/ansible/modules/system/ping.py index bd6d707604..e59901f0bd 100644 --- a/lib/ansible/modules/system/ping.py +++ b/lib/ansible/modules/system/ping.py @@ -35,6 +35,9 @@ description: contact. It does not make sense in playbooks, but it is useful from C(/usr/bin/ansible) to verify the ability to login and that a usable python is configured. - This is NOT ICMP ping, this is just a trivial test module. + - For Windows targets, use the M(ping) module instead. +notes: + - For Windows targets, use the M(ping) module instead. options: {} author: - "Ansible Core Team" diff --git a/lib/ansible/modules/system/service.py b/lib/ansible/modules/system/service.py index 18478e6919..a7175a4014 100644 --- a/lib/ansible/modules/system/service.py +++ b/lib/ansible/modules/system/service.py @@ -34,6 +34,7 @@ short_description: Manage services. description: - Controls services on remote hosts. Supported init systems include BSD init, OpenRC, SysV, Solaris SMF, systemd, upstart. + - For Windows targets, use the M(win_service) module instead. options: name: required: true @@ -87,6 +88,8 @@ options: - Normally it uses the value of the 'ansible_service_mgr' fact and falls back to the old 'service' module when none matching is found. default: 'auto' version_added: 2.2 +notes: + - For Windows targets, use the M(win_service) module instead. ''' EXAMPLES = ''' diff --git a/lib/ansible/modules/system/setup.py b/lib/ansible/modules/system/setup.py index 3b2455024c..930c4eaa7f 100644 --- a/lib/ansible/modules/system/setup.py +++ b/lib/ansible/modules/system/setup.py @@ -69,6 +69,7 @@ description: executed directly by C(/usr/bin/ansible) to check what variables are available to a host. Ansible provides many I(facts) about the system, automatically. + - This module is also supported for Windows targets. notes: - More ansible facts will be added with successive releases. If I(facter) or I(ohai) are installed, variables from these programs will also be snapshotted @@ -85,6 +86,7 @@ notes: their output must be formattable in JSON (Ansible will take care of this). Test the output of your scripts. This option was added in Ansible 2.1. + - This module is also supported for Windows targets. author: - "Ansible Core Team" - "Michael DeHaan" diff --git a/lib/ansible/modules/system/user.py b/lib/ansible/modules/system/user.py index 5142274e32..6158ad3bbe 100644 --- a/lib/ansible/modules/system/user.py +++ b/lib/ansible/modules/system/user.py @@ -33,8 +33,10 @@ notes: - There are specific requirements per platform on user management utilities. However they generally come pre-installed with the system and Ansible will require they are present at runtime. If they are not, a descriptive error message will be shown. + - For Windows targets, use the M(win_user) module instead. description: - Manage user accounts and user attributes. + - For Windows targets, use the M(win_user) module instead. options: name: required: true diff --git a/lib/ansible/modules/utilities/helper/meta.py b/lib/ansible/modules/utilities/helper/meta.py index 607ba8b665..00ed8943d6 100644 --- a/lib/ansible/modules/utilities/helper/meta.py +++ b/lib/ansible/modules/utilities/helper/meta.py @@ -31,6 +31,7 @@ description: - Meta tasks are a special kind of task which can influence Ansible internal execution or state. Prior to Ansible 2.0, the only meta option available was `flush_handlers`. As of 2.2, there are five meta tasks which can be used. Meta tasks can be used anywhere within your playbook. + - This module is also supported for Windows targets. options: free_form: description: @@ -48,9 +49,9 @@ options: - "C(reset_connection) (added in 2.3) interrupts a persistent connection (i.e. ssh + control persist)" choices: ['noop', 'flush_handlers', 'refresh_inventory', 'clear_facts', 'clear_host_errors', 'end_play', 'reset_connection'] required: true - default: null notes: - - meta is not really a module nor action_plugin as such it cannot be overwritten. + - C(meta) is not really a module nor action_plugin as such it cannot be overwritten. + - This module is also supported for Windows targets. author: - "Ansible Core Team" ''' diff --git a/lib/ansible/modules/utilities/logic/assert.py b/lib/ansible/modules/utilities/logic/assert.py index 46a53ec067..3aceaf1e32 100644 --- a/lib/ansible/modules/utilities/logic/assert.py +++ b/lib/ansible/modules/utilities/logic/assert.py @@ -29,6 +29,7 @@ module: assert short_description: Asserts given expressions are true description: - This module asserts that given expressions are true with an optional custom message. + - This module is also supported for Windows targets. version_added: "1.5" options: that: @@ -39,7 +40,8 @@ options: msg: description: - "The customized message used for a failing assertion" - required: false +notes: + - This module is also supported for Windows targets. author: - "Ansible Core Team" - "Michael DeHaan" diff --git a/lib/ansible/modules/utilities/logic/async_status.py b/lib/ansible/modules/utilities/logic/async_status.py index 267aa11143..409b212d24 100644 --- a/lib/ansible/modules/utilities/logic/async_status.py +++ b/lib/ansible/modules/utilities/logic/async_status.py @@ -29,25 +29,23 @@ DOCUMENTATION = ''' module: async_status short_description: Obtain status of asynchronous task description: - - "This module gets the status of an asynchronous task." + - This module gets the status of an asynchronous task. + - This module is also supported for Windows targets. version_added: "0.5" options: jid: description: - Job or task identifier required: true - default: null - aliases: [] mode: description: - if C(status), obtain the status; if C(cleanup), clean up the async job cache located in C(~/.ansible_async/) for the specified job I(jid). - required: false choices: [ "status", "cleanup" ] default: "status" notes: - See also U(http://docs.ansible.com/playbooks_async.html) -requirements: [] + - This module is also supported for Windows targets. author: - "Ansible Core Team" - "Michael DeHaan" diff --git a/lib/ansible/modules/utilities/logic/debug.py b/lib/ansible/modules/utilities/logic/debug.py index 2c36f79409..ba79138062 100644 --- a/lib/ansible/modules/utilities/logic/debug.py +++ b/lib/ansible/modules/utilities/logic/debug.py @@ -31,7 +31,7 @@ description: - This module prints statements during execution and can be useful for debugging variables or expressions without necessarily halting the playbook. Useful for debugging together with the 'when:' directive. - + - This module is also supported for Windows targets. version_added: "0.8" options: msg: @@ -49,6 +49,8 @@ options: required: False default: 0 version_added: "2.1" +notes: + - This module is also supported for Windows targets. author: - "Dag Wieers (@dagwieers)" - "Michael DeHaan" diff --git a/lib/ansible/modules/utilities/logic/fail.py b/lib/ansible/modules/utilities/logic/fail.py index 093099b7d3..09d60c75ab 100644 --- a/lib/ansible/modules/utilities/logic/fail.py +++ b/lib/ansible/modules/utilities/logic/fail.py @@ -30,6 +30,7 @@ short_description: Fail with custom message description: - This module fails the progress with a custom message. It can be useful for bailing out when a certain condition is met using C(when). + - This module is also supported for Windows targets. version_added: "0.8" options: msg: @@ -38,6 +39,8 @@ options: fail will simply bail out with a generic message. required: false default: "'Failed as requested from task'" +notes: + - This module is also supported for Windows targets. author: "Dag Wieers (@dagwieers)" ''' diff --git a/lib/ansible/modules/utilities/logic/include.py b/lib/ansible/modules/utilities/logic/include.py index 7e7b13418b..9010809cc8 100644 --- a/lib/ansible/modules/utilities/logic/include.py +++ b/lib/ansible/modules/utilities/logic/include.py @@ -26,6 +26,7 @@ description: - Static includes are not subject to most directives, for example, loops or conditionals, they are applied instead to each inherited task. - Since 2.0 task includes are dynamic and behave more like real tasks. This means they can be looped, skipped and use variables from any source. Ansible tries to auto detect this, use the `static` directive (new in 2.1) to bypass autodetection. + - This module is also supported for Windows targets. version_added: "0.6" options: free-form: @@ -34,6 +35,7 @@ options: notes: - This is really not a module, though it appears as such, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can. + - This module is also supported for Windows targets. ''' EXAMPLES = """ diff --git a/lib/ansible/modules/utilities/logic/include_role.py b/lib/ansible/modules/utilities/logic/include_role.py index 5e4d52a23f..01ae3bcf8d 100644 --- a/lib/ansible/modules/utilities/logic/include_role.py +++ b/lib/ansible/modules/utilities/logic/include_role.py @@ -20,7 +20,8 @@ author: module: include_role short_description: Load and execute a role description: - - "Loads and executes a role as a task, this frees roles from the `role:` directive and allows them to be treated more as tasks." + - Loads and executes a role as a task, this frees roles from the `role:` directive and allows them to be treated more as tasks. + - This module is also supported for Windows targets. version_added: "2.2" options: name: @@ -57,6 +58,7 @@ notes: - As with C(include) this task can be static or dynamic, If static it implies that it won't need templating nor loops nor conditionals and will show included tasks in the --list options. Ansible will try to autodetect what is needed, but you can set `static` to `yes` or `no` at task level to control this. + - This module is also supported for Windows targets. ''' EXAMPLES = """ diff --git a/lib/ansible/modules/utilities/logic/include_vars.py b/lib/ansible/modules/utilities/logic/include_vars.py index da7977bd93..5ba6237829 100644 --- a/lib/ansible/modules/utilities/logic/include_vars.py +++ b/lib/ansible/modules/utilities/logic/include_vars.py @@ -21,6 +21,7 @@ short_description: Load variables from files, dynamically within a task. description: - Loads variables from a YAML/JSON files dynamically from within a file or from a directory recursively during task runtime. If loading a directory, the files are sorted alphabetically before being loaded. + - This module is also supported for Windows targets. version_added: "1.4" options: file: @@ -65,6 +66,8 @@ options: description: - This module allows you to specify the 'file' option directly w/o any other options. There is no 'free-form' option, this is just an indicator, see example below. +notes: + - This module is also supported for Windows targets. ''' EXAMPLES = """ diff --git a/lib/ansible/modules/utilities/logic/pause.py b/lib/ansible/modules/utilities/logic/pause.py index c01503afe9..7e577faba9 100644 --- a/lib/ansible/modules/utilities/logic/pause.py +++ b/lib/ansible/modules/utilities/logic/pause.py @@ -33,6 +33,7 @@ description: - > The pause module integrates into async/parallelized playbooks without any special considerations (see also: Rolling Updates). When using pauses with the C(serial) playbook parameter (as in rolling updates) you are only prompted once for the current group of hosts. + - This module is also supported for Windows targets. version_added: "0.8" options: minutes: @@ -53,6 +54,7 @@ options: author: "Tim Bielawa (@tbielawa)" notes: - Starting in 2.2, if you specify 0 or negative for minutes or seconds, it will wait for 1 second, previously it would wait indefinitely. + - This module is also supported for Windows targets. ''' EXAMPLES = ''' diff --git a/lib/ansible/modules/utilities/logic/set_fact.py b/lib/ansible/modules/utilities/logic/set_fact.py index 86042e5ae7..3c7f4b300d 100644 --- a/lib/ansible/modules/utilities/logic/set_fact.py +++ b/lib/ansible/modules/utilities/logic/set_fact.py @@ -34,6 +34,7 @@ description: a fact cache. - Per the standard Ansible variable precedence rules, many other types of variables have a higher priority, so this value may be overridden. See U(http://docs.ansible.com/ansible/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable) for more information. + - This module is also supported for Windows targets. options: key_value: description: @@ -46,6 +47,7 @@ version_added: "1.2" notes: - "The `var=value` notation can only create strings or booleans. If you want to create lists/arrays or dictionary/hashes use `var: [val1, val2]`" + - This module is also supported for Windows targets. ''' EXAMPLES = ''' diff --git a/lib/ansible/modules/utilities/logic/set_stats.py b/lib/ansible/modules/utilities/logic/set_stats.py index 59da69d5db..fad27b8c6d 100644 --- a/lib/ansible/modules/utilities/logic/set_stats.py +++ b/lib/ansible/modules/utilities/logic/set_stats.py @@ -29,6 +29,7 @@ module: set_stats short_description: Set stats for the current ansible run description: - This module allows setting/accumulating stats on the current ansible run, either per host of for all hosts in the run. + - This module is also supported for Windows targets. options: data: description: @@ -44,6 +45,8 @@ options: - boolean that indicates if the provided value is aggregated to the existing stat C(yes) or will replace it C(no) required: no default: yes +notes: + - This module is also supported for Windows targets. version_added: "2.3" ''' diff --git a/lib/ansible/modules/utilities/logic/wait_for.py b/lib/ansible/modules/utilities/logic/wait_for.py index 119085f4a1..cc2ee219de 100644 --- a/lib/ansible/modules/utilities/logic/wait_for.py +++ b/lib/ansible/modules/utilities/logic/wait_for.py @@ -39,6 +39,7 @@ description: - In 1.8 and later, this module can also be used to wait for active connections to be closed before continuing, useful if a node is being rotated out of a load balancer pool. + - This module is also supported for Windows targets. version_added: "0.7" options: host: @@ -99,6 +100,8 @@ options: - This overrides the normal error message from a failure to meet the required conditions. notes: - The ability to use search_regex with a port connection was added in 1.7. + - This module is also supported for Windows targets. + - See also M(wait_for_connection) author: - Jeroen Hoekx (@jhoekx) - John Jarvis (@jarv) @@ -106,7 +109,6 @@ author: ''' EXAMPLES = r''' - - name: Wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds wait_for: port: 8000 diff --git a/lib/ansible/modules/utilities/logic/wait_for_connection.py b/lib/ansible/modules/utilities/logic/wait_for_connection.py index cd2a681419..8d0a57bb0c 100644 --- a/lib/ansible/modules/utilities/logic/wait_for_connection.py +++ b/lib/ansible/modules/utilities/logic/wait_for_connection.py @@ -32,6 +32,7 @@ description: - Retries the transport connection after a timeout of C(connect_timeout). - Tests the transport connection every C(sleep) seconds. - This module makes use of internal ansible transport (and configuration) and the ping/win_ping module to guarantee correct end-to-end functioning. +- This module is also supported for Windows targets. version_added: "2.3" options: connect_timeout: @@ -50,6 +51,8 @@ options: description: - Maximum number of seconds to wait for. default: 600 +notes: +- This module is also supported for Windows targets. author: "Dag Wieers (@dagwieers)" ''' diff --git a/lib/ansible/modules/windows/win_command.py b/lib/ansible/modules/windows/win_command.py index da25a100ea..12b200d179 100644 --- a/lib/ansible/modules/windows/win_command.py +++ b/lib/ansible/modules/windows/win_command.py @@ -35,6 +35,7 @@ description: processed through the shell, so variables like C($env:HOME) and operations like C("<"), C(">"), C("|"), and C(";") will not work (use the M(win_shell) module if you need these features). + - For non-Windows targets, use the M(command) module instead. options: free_form: description: @@ -57,6 +58,7 @@ notes: environment. - C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this. + - For non-Windows targets, use the M(command) module instead. author: - Matt Davis ''' diff --git a/lib/ansible/modules/windows/win_copy.py b/lib/ansible/modules/windows/win_copy.py index e5075cf035..59f5d9ac83 100644 --- a/lib/ansible/modules/windows/win_copy.py +++ b/lib/ansible/modules/windows/win_copy.py @@ -31,6 +31,7 @@ version_added: "1.9.2" short_description: Copies files to remote locations on windows hosts. description: - The C(win_copy) module copies a file on the local box to remote windows locations. +- For non-Windows targets, use the M(copy) module instead. options: content: description: @@ -72,6 +73,8 @@ options: to destination. Otherwise, if it does not end with "/", the directory itself with all contents is copied. This behavior is similar to Rsync. required: true +notes: +- For non-Windows targets, use the M(copy) module instead. author: "Jon Hawkesworth (@jhawkesworth)" ''' diff --git a/lib/ansible/modules/windows/win_file.py b/lib/ansible/modules/windows/win_file.py index 206b3286dd..0e6a507c71 100644 --- a/lib/ansible/modules/windows/win_file.py +++ b/lib/ansible/modules/windows/win_file.py @@ -33,7 +33,9 @@ description: - Creates (empty) files, updates file modification stamps of existing files, and can create or remove directories. - Unlike M(file), does not modify ownership, permissions or manipulate links. + - For non-Windows targets, use the M(file) module instead. notes: + - For non-Windows targets, use the M(file) module instead. - See also M(win_copy), M(win_template), M(copy), M(template), M(assemble) requirements: [ ] author: "Jon Hawkesworth (@jhawkesworth)" diff --git a/lib/ansible/modules/windows/win_find.py b/lib/ansible/modules/windows/win_find.py index d275c79251..646640d491 100644 --- a/lib/ansible/modules/windows/win_find.py +++ b/lib/ansible/modules/windows/win_find.py @@ -31,6 +31,7 @@ short_description: return a list of files based on specific criteria description: - Return a list of files based on specified criteria. - Multiple criteria are AND'd together. + - For non-Windows targets, use the M(find) module instead. options: age: description: @@ -113,6 +114,8 @@ options: required: false default: false choices: ['true', 'false'] +notes: + - For non-Windows targets, use the M(find) module instead. author: "Jordan Borean (@jborean93)" ''' diff --git a/lib/ansible/modules/windows/win_get_url.py b/lib/ansible/modules/windows/win_get_url.py index e688501722..a0e4f30fb6 100644 --- a/lib/ansible/modules/windows/win_get_url.py +++ b/lib/ansible/modules/windows/win_get_url.py @@ -33,6 +33,7 @@ version_added: "1.7" short_description: Fetches a file from a given URL description: - Fetches a file from a URL and saves to locally + - For non-Windows targets, use the M(get_url) module instead. author: - "Paul Durivage (@angstwad)" - "Takeshi Kuramochi (tksarah)" @@ -90,6 +91,8 @@ options: - Proxy authentication password version_added: "2.0" required: false +notes: + - For non-Windows targets, use the M(get_url) module instead. ''' EXAMPLES = r''' diff --git a/lib/ansible/modules/windows/win_group.py b/lib/ansible/modules/windows/win_group.py index 213e953fc2..d08ebc66a9 100644 --- a/lib/ansible/modules/windows/win_group.py +++ b/lib/ansible/modules/windows/win_group.py @@ -32,7 +32,8 @@ module: win_group version_added: "1.7" short_description: Add and remove local groups description: - - Add and remove local groups + - Add and remove local groups. + - For non-Windows targets, please use the M(group) module instead. options: name: description: @@ -55,6 +56,8 @@ options: - absent default: present aliases: [] +notes: + - For non-Windows targets, please use the M(group) module instead. author: "Chris Hoffman (@chrishoffman)" ''' diff --git a/lib/ansible/modules/windows/win_package.py b/lib/ansible/modules/windows/win_package.py index d0638d2d7a..30a14c878f 100644 --- a/lib/ansible/modules/windows/win_package.py +++ b/lib/ansible/modules/windows/win_package.py @@ -38,6 +38,7 @@ description: Use a product_id to check if the package needs installing. You can find product ids for installed programs in the windows registry either in C(HKLM:Software\Microsoft\Windows\CurrentVersion\Uninstall) or for 32 bit programs C(HKLM:Software\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall) + - For non-Windows targets, use the M(package) module instead. options: path: description: @@ -88,6 +89,8 @@ options: - If not provided, defaults to 0 required: no default: 0 +notes: + - For non-Windows targets, use the M(package) module instead. ''' EXAMPLES = r''' diff --git a/lib/ansible/modules/windows/win_ping.py b/lib/ansible/modules/windows/win_ping.py index 188c2fcbd3..1a2f0a7f71 100644 --- a/lib/ansible/modules/windows/win_ping.py +++ b/lib/ansible/modules/windows/win_ping.py @@ -30,14 +30,18 @@ DOCUMENTATION = r''' --- module: win_ping version_added: "1.7" -short_description: A windows version of the classic ping module. +short_description: A windows version of the classic ping module description: - - Checks management connectivity of a windows host + - Checks management connectivity of a windows host. + - This is NOT ICMP ping, this is just a trivial test module. + - For non-Windows targets, use the M(ping) module instead. options: data: description: - Alternate data to return instead of 'pong' default: 'pong' +notes: + - For non-Windows targets, use the M(ping) module instead. author: "Chris Church (@cchurch)" ''' diff --git a/lib/ansible/modules/windows/win_service.py b/lib/ansible/modules/windows/win_service.py index 8860a02234..6be0bdefec 100644 --- a/lib/ansible/modules/windows/win_service.py +++ b/lib/ansible/modules/windows/win_service.py @@ -32,7 +32,8 @@ module: win_service version_added: "1.7" short_description: Manages Windows services description: - - Manages Windows services + - Manages Windows services. + - For non-Windows targets, use the M(service) module instead. options: dependencies: description: @@ -117,6 +118,8 @@ options: - The username to set the service to start as. - This and the C(password) argument must be supplied together. version_added: "2.3" +notes: + - For non-Windows targets, use the M(service) module instead. author: "Chris Hoffman (@chrishoffman)" ''' diff --git a/lib/ansible/modules/windows/win_shell.py b/lib/ansible/modules/windows/win_shell.py index 1fa72deab9..0a942cc90c 100644 --- a/lib/ansible/modules/windows/win_shell.py +++ b/lib/ansible/modules/windows/win_shell.py @@ -33,6 +33,7 @@ description: - The C(win_shell) module takes the command name followed by a list of space-delimited arguments. It is similar to the M(win_command) module, but runs the command via a shell (defaults to PowerShell) on the target host. + - For non-Windows targets, use the M(shell) module instead. options: free_form: description: @@ -60,8 +61,10 @@ notes: - WinRM will not return from a command execution until all child processes created have exited. Thus, it is not possible to use C(win_shell) to spawn long-running child or background processes. Consider creating a Windows service for managing background processes. + - For non-Windows targets, use the M(shell) module instead. + - See also M(win_command), M(raw) author: - - Matt Davis + - Matt Davis (@nitzmahone) ''' EXAMPLES = r''' diff --git a/lib/ansible/modules/windows/win_stat.py b/lib/ansible/modules/windows/win_stat.py index 0238c70a48..6e805e4087 100644 --- a/lib/ansible/modules/windows/win_stat.py +++ b/lib/ansible/modules/windows/win_stat.py @@ -28,7 +28,8 @@ module: win_stat version_added: "1.7" short_description: returns information about a Windows file description: - - Returns information about a Windows file + - Returns information about a Windows file. + - For non-Windows targets, use the M(stat) module instead. options: path: description: @@ -59,6 +60,8 @@ options: default: sha1 choices: ['md5', 'sha1', 'sha256', 'sha384', 'sha512'] version_added: "2.3" +notes: + - For non-Windows targets, use the M(stat) module instead. author: "Chris Church (@cchurch)" ''' diff --git a/lib/ansible/modules/windows/win_tempfile.py b/lib/ansible/modules/windows/win_tempfile.py index a85279c66f..bd98d66ca8 100644 --- a/lib/ansible/modules/windows/win_tempfile.py +++ b/lib/ansible/modules/windows/win_tempfile.py @@ -31,6 +31,7 @@ author: Dag Wieers (@dagwieers) short_description: Creates temporary files and directories. description: - Creates temporary files and directories. + - For non-Windows targets, please use the M(tempfile) module instead. options: state: description: @@ -50,6 +51,8 @@ options: description: - Suffix of file/directory name created by module. default: '' +notes: + - For non-Windows targets, please use the M(tempfile) module instead. ''' EXAMPLES = r""" diff --git a/lib/ansible/modules/windows/win_unzip.py b/lib/ansible/modules/windows/win_unzip.py index f720d6c78d..684390a75b 100644 --- a/lib/ansible/modules/windows/win_unzip.py +++ b/lib/ansible/modules/windows/win_unzip.py @@ -35,6 +35,7 @@ description: - Unzips compressed files and archives. - Supports .zip files natively - Supports other formats supported by the Powershell Community Extensions (PSCX) module (basically everything 7zip supports) +- For non-Windows targets, use the M(unarchive) module instead. requirements: - PSCX options: @@ -75,6 +76,7 @@ notes: - For extracting any compression types other than .zip, the PowerShellCommunityExtensions (PSCX) Module is required. This module (in conjunction with PSCX) has the ability to recursively unzip files within the src zip file provided and also functionality for many other compression types. If the destination directory does not exist, it will be created before unzipping the file. Specifying rm parameter will force removal of the src file after extraction. +- For non-Windows targets, use the M(unarchive) module instead. author: Phil Schwartz ''' diff --git a/lib/ansible/modules/windows/win_uri.py b/lib/ansible/modules/windows/win_uri.py index 6b86b88d44..7d1bb15d63 100644 --- a/lib/ansible/modules/windows/win_uri.py +++ b/lib/ansible/modules/windows/win_uri.py @@ -34,6 +34,7 @@ short_description: Interacts with webservices description: - Interacts with FTP, HTTP and HTTPS web services. - Supports Digest, Basic and WSSE HTTP authentication mechanisms. +- For non-Windows targets, use the M(uri) module instead. options: url: description: @@ -138,6 +139,8 @@ options: description: - Specifies the client certificate(.pfx) that is used for a secure web request. version_added: '2.4' +notes: +- For non-Windows targets, use the M(uri) module instead. author: - Corwin Brown (@blakfeld) - Dag Wieers (@dagwieers) diff --git a/lib/ansible/modules/windows/win_user.py b/lib/ansible/modules/windows/win_user.py index 19a6de9cd6..d6a48e755e 100644 --- a/lib/ansible/modules/windows/win_user.py +++ b/lib/ansible/modules/windows/win_user.py @@ -33,6 +33,7 @@ version_added: "1.7" short_description: Manages local Windows user accounts description: - Manages local Windows user accounts + - For non-Windows targets, use the M(user) module instead. options: name: description: @@ -132,6 +133,8 @@ options: - query default: present aliases: [] +notes: + - For non-Windows targets, use the M(user) module instead. author: - "Paul Durivage (@angstwad)" - "Chris Church (@cchurch)"