1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00

Docs: Clean up of 'fetch' module docs (#46330)

* Docs: Clean up of 'fetch' module docs

This is part of a series of module doc cleanups.

* Fixes as suggested by review
This commit is contained in:
Dag Wieers 2018-10-04 05:31:31 +02:00 committed by Alicia Cozine
parent 21d23829be
commit 12d688c006

View file

@ -1,66 +1,65 @@
# this is a virtual module that is entirely implemented server side
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright: (c) 2017, Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
# This is a virtual module that is entirely implemented as an action plugin and runs on the controller
from __future__ import absolute_import, division, print_function
__metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: fetch
short_description: Fetches a file from remote nodes
short_description: Fetch files from remote nodes
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 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"
version_added: '0.2'
options:
src:
description:
- The file on the remote system to fetch. This I(must) be a file, not a
directory. Recursive fetching may be supported in a later release.
required: true
- The file on the remote system to fetch.
- This I(must) be a file, not a directory.
- Recursive fetching may be supported in a later release.
required: yes
dest:
description:
- A directory to save the file into. For example, if the I(dest)
directory is C(/backup) a I(src) file named C(/etc/profile) on host
C(host.example.com), would be saved into
C(/backup/host.example.com/etc/profile)
required: true
- A directory to save the file into.
- For example, if the I(dest) directory is C(/backup) a I(src) file named C(/etc/profile) on host
C(host.example.com), would be saved into C(/backup/host.example.com/etc/profile).
required: yes
fail_on_missing:
version_added: "1.1"
version_added: '1.1'
description:
- When set to 'yes', the task will fail if the remote file cannot be
read for any reason. Prior to Ansible-2.5, setting this would only fail
if the source file was missing.
- The default was changed to "yes" in Ansible-2.5.
- When set to C(yes), the task will fail if the remote file cannot be read for any reason.
- Prior to Ansible 2.5, setting this would only fail if the source file was missing.
- The default was changed to C(yes) in Ansible 2.5.
type: bool
default: 'yes'
default: yes
validate_checksum:
version_added: "1.4"
version_added: '1.4'
description:
- Verify that the source and destination checksums match after the files are fetched.
type: bool
default: 'yes'
default: yes
flat:
version_added: "1.2"
version_added: '1.2'
description:
- Allows you to override the default behavior of appending
hostname/path/to/file to the destination. If dest ends with '/', it
will use the basename of the source file, similar to the copy module.
Obviously this is only handy if the filenames are unique.
- Allows you to override the default behavior of appending hostname/path/to/file to the destination.
- If C(dest) ends with '/', it will use the basename of the source file, similar to the copy module.
- Obviously this is only handy if the filenames are unique.
type: bool
default: 'no'
default: no
author:
- "Ansible Core Team"
- "Michael DeHaan"
- Ansible Core Team
- Michael DeHaan
notes:
- When running fetch with C(become), the M(slurp) module will also be
used to fetch the contents of the file for determining the remote
@ -68,34 +67,35 @@ notes:
depending on the file size can consume all available memory on the
remote or local hosts causing a C(MemoryError). Due to this it is
advisable to run this module without C(become) whenever possible.
- Prior to Ansible-2.5 this module would not fail if reading the remote
file was impossible unless fail_on_missing was set. In Ansible-2.5+,
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.
- Prior to Ansible 2.5 this module would not fail if reading the remote
file was impossible unless C(fail_on_missing) was set.
- In Ansible 2.5 or later, playbook authors are encouraged to use
C(fail_when) or C(ignore_errors) to get this ability. They may
also explicitly set C(fail_on_missing) to C(no) to get the
non-failing behaviour.
- This module is also supported for Windows targets.
'''
EXAMPLES = '''
# Store file into /tmp/fetched/host.example.com/tmp/somefile
- fetch:
EXAMPLES = r'''
- name: Store file into /tmp/fetched/host.example.com/tmp/somefile
fetch:
src: /tmp/somefile
dest: /tmp/fetched
# Specifying a path directly
- fetch:
- name: Specifying a path directly
fetch:
src: /tmp/somefile
dest: /tmp/prefix-{{ inventory_hostname }}
flat: yes
# Specifying a destination path
- fetch:
- name: Specifying a destination path
fetch:
src: /tmp/uniquefile
dest: /tmp/special/
flat: yes
# Storing in a path relative to the playbook
- fetch:
- name: Storing in a path relative to the playbook
fetch:
src: /tmp/uniquefile
dest: special/prefix-{{ inventory_hostname }}
flat: yes