cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

modules: fix documentation formatting (#72737) (#72850)

Browse source 
(cherry picked from commit ebd8c101fd)
This commit is contained in:
Andrew Klychkov 2021-01-11 08:25:13 +03:00 committed by GitHub
parent c4adf62220
commit 7c44c24456
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 130 additions and 111 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

60
lib/ansible/modules/cron.py
View file

@ -33,8 +33,8 @@ options:
name:
description:
- Description of a crontab entry or, if env is set, the name of environment variable.
- Required if C(state=absent).
- Note that if name is not set and C(state=present), then a
- Required if I(state=absent).
- Note that if name is not set and I(state=present), then a
new crontab entry will always be created, regardless of existing ones.
- This parameter will always be required in future releases.
type: str
@ -47,7 +47,7 @@ options:
description:
- The command to execute or, if env is set, the value of environment variable.
- The command should not contain line breaks.
- Required if C(state=present).
- Required if I(state=present).
type: str
aliases: [ value ]
state:
@ -60,10 +60,10 @@ options:
description:
- If specified, uses this file instead of an individual user's crontab.
- If this is a relative path, it is interpreted with respect to I(/etc/cron.d).
- If it is absolute, it will typically be I(/etc/crontab).
- If it is absolute, it will typically be C(/etc/crontab).
- Many linux distros expect (and some require) the filename portion to consist solely
of upper- and lower-case letters, digits, underscores, and hyphens.
- To use the C(cron_file) parameter you must specify the C(user) as well.
- To use the I(cron_file) parameter you must specify the I(user) as well.
type: str
backup:
description:
@ -73,34 +73,34 @@ options:
default: no
minute:
description:
- Minute when the job should run ( 0-59, *, */2, etc )
- Minute when the job should run (C(0-59), C(*), C(*/2), and so on).
type: str
default: "*"
hour:
description:
- Hour when the job should run ( 0-23, *, */2, etc )
- Hour when the job should run (C(0-23), C(*), C(*/2), and so on).
type: str
default: "*"
day:
description:
- Day of the month the job should run ( 1-31, *, */2, etc )
- Day of the month the job should run (C(1-31), C(*), C(*/2), and so on).
type: str
default: "*"
aliases: [ dom ]
month:
description:
- Month of the year the job should run ( 1-12, *, */2, etc )
- Month of the year the job should run (C(1-12), C(*), C(*/2), and so on).
type: str
default: "*"
weekday:
description:
- Day of the week that the job should run ( 0-6 for Sunday-Saturday, *, etc )
- Day of the week that the job should run (C(0-6) for Sunday-Saturday, C(*), and so on).
type: str
default: "*"
aliases: [ dow ]
reboot:
description:
- If the job should be run at reboot. This option is deprecated. Users should use special_time.
- If the job should be run at reboot. This option is deprecated. Users should use I(special_time).
version_added: "1.0"
type: bool
default: no
@ -113,7 +113,7 @@ options:
disabled:
description:
- If the job should be disabled (commented out) in the crontab.
- Only has effect if C(state=present).
- Only has effect if I(state=present).
type: bool
default: no
version_added: "2.0"
@ -121,66 +121,68 @@ options:
description:
- If set, manages a crontab's environment variable.
- New variables are added on top of crontab.
- C(name) and C(value) parameters are the name and the value of environment variable.
- I(name) and I(value) parameters are the name and the value of environment variable.
type: bool
default: false
version_added: "2.1"
insertafter:
description:
- Used with C(state=present) and C(env).
- Used with I(state=present) and I(env).
- If specified, the environment variable will be inserted after the declaration of specified environment variable.
type: str
version_added: "2.1"
insertbefore:
description:
- Used with C(state=present) and C(env).
- Used with I(state=present) and I(env).
- If specified, the environment variable will be inserted before the declaration of specified environment variable.
type: str
version_added: "2.1"
requirements:
- cron (or cronie on CentOS)
author:
- Dane Summers (@dsummersl)
- Mike Grozak (@rhaido)
- Patrick Callahan (@dirtyharrycallahan)
- Evan Kaufman (@EvanK)
- Luca Berruti (@lberruti)
- Dane Summers (@dsummersl)
- Mike Grozak (@rhaido)
- Patrick Callahan (@dirtyharrycallahan)
- Evan Kaufman (@EvanK)
- Luca Berruti (@lberruti)
notes:
- Supports C(check_mode).
'''
EXAMPLES = r'''
- name: Ensure a job that runs at 2 and 5 exists. Creates an entry like "0 5,2 * * ls -alh > /dev/null"
cron:
ansible.builtin.cron:
name: "check dirs"
minute: "0"
hour: "5,2"
job: "ls -alh > /dev/null"
- name: 'Ensure an old job is no longer present. Removes any job that is prefixed by "#Ansible: an old job" from the crontab'
cron:
ansible.builtin.cron:
name: "an old job"
state: absent
- name: Creates an entry like "@reboot /some/job.sh"
cron:
ansible.builtin.cron:
name: "a job for reboot"
special_time: reboot
job: "/some/job.sh"
- name: Creates an entry like "PATH=/opt/bin" on top of crontab
cron:
ansible.builtin.cron:
name: PATH
env: yes
job: /opt/bin
- name: Creates an entry like "APP_HOME=/srv/app" and insert it after PATH declaration
cron:
ansible.builtin.cron:
name: APP_HOME
env: yes
job: /srv/app
insertafter: PATH
- name: Creates a cron file under /etc/cron.d
cron:
ansible.builtin.cron:
name: yum autoupdate
weekday: "2"
minute: "0"
@ -190,18 +192,20 @@ EXAMPLES = r'''
cron_file: ansible_yum-autoupdate
- name: Removes a cron file from under /etc/cron.d
cron:
ansible.builtin.cron:
name: "yum autoupdate"
cron_file: ansible_yum-autoupdate
state: absent
- name: Removes "APP_HOME" environment variable from crontab
cron:
ansible.builtin.cron:
name: APP_HOME
env: yes
state: absent
'''
RETURN = r'''#'''
import os
import platform
import pwd

13
lib/ansible/modules/debconf.py
View file

@ -23,6 +23,7 @@ notes:
installed to see questions/settings available.
- Some distros will always record tasks involving the setting of passwords as changed. This is due to debconf-get-selections masking passwords.
- It is highly recommended to add I(no_log=True) to task while handling sensitive information using this module.
- Supports C(check_mode).
requirements:
- debconf
- debconf-utils
@ -61,32 +62,32 @@ author:
EXAMPLES = r'''
- name: Set default locale to fr_FR.UTF-8
debconf:
ansible.builtin.debconf:
name: locales
question: locales/default_environment_locale
value: fr_FR.UTF-8
vtype: select
- name: Set to generate locales
debconf:
ansible.builtin.debconf:
name: locales
question: locales/locales_to_be_generated
value: en_US.UTF-8 UTF-8, fr_FR.UTF-8 UTF-8
vtype: multiselect
- name: Accept oracle license
debconf:
ansible.builtin.debconf:
name: oracle-java7-installer
question: shared/accepted-oracle-license-v1-1
value: 'true'
vtype: select
- name: Specifying package you can register/return the list of questions and current values
debconf:
ansible.builtin.debconf:
name: tzdata
- name: Pre-configure tripwire site passphrase
debconf:
ansible.builtin.debconf:
name: tripwire
question: tripwire/site-passphrase
value: "{{ site_passphrase }}"
@ -94,6 +95,8 @@ EXAMPLES = r'''
no_log: True
'''
RETURN = r'''#'''
from ansible.module_utils._text import to_text
from ansible.module_utils.basic import AnsibleModule

20
lib/ansible/modules/debug.py
View file

@ -49,29 +49,27 @@ author:
'''
EXAMPLES = r'''
# Example that prints the loopback address and gateway for each host
- debug:
msg: System {{ inventory_hostname }} has uuid {{ ansible_product_uuid }}
- debug:
- name: Print the gateway for each host when defined
ansible.builtin.debug:
msg: System {{ inventory_hostname }} has gateway {{ ansible_default_ipv4.gateway }}
when: ansible_default_ipv4.gateway is defined
# Example that prints return information from the previous task
- shell: /usr/bin/uptime
- name: Get uptime information
ansible.builtin.shell: /usr/bin/uptime
register: result
- debug:
- name: Print return information from the previous task
ansible.builtin.debug:
var: result
verbosity: 2
- name: Display all variables/facts known for a host
debug:
ansible.builtin.debug:
var: hostvars[inventory_hostname]
verbosity: 4
# Example that prints two lines of messages, but only if there is an environment value set
- debug:
- name: Prints two lines of messages, but only if there is an environment value set
ansible.builtin.debug:
msg:
- "Provisioning based on YOUR_KEY which is: {{ lookup('env', 'YOUR_KEY') }}"
- "These servers were built using the password of '{{ password_used }}'. Please retain this for later use."

9
lib/ansible/modules/fetch.py
View file

@ -71,6 +71,7 @@ notes:
also explicitly set C(fail_on_missing) to C(no) to get the
non-failing behaviour.
- This module is also supported for Windows targets.
- Supports C(check_mode).
seealso:
- module: ansible.builtin.copy
- module: ansible.builtin.slurp
@ -81,24 +82,24 @@ author:
EXAMPLES = r'''
- name: Store file into /tmp/fetched/host.example.com/tmp/somefile
fetch:
ansible.builtin.fetch:
src: /tmp/somefile
dest: /tmp/fetched
- name: Specifying a path directly
fetch:
ansible.builtin.fetch:
src: /tmp/somefile
dest: /tmp/prefix-{{ inventory_hostname }}
flat: yes
- name: Specifying a destination path
fetch:
ansible.builtin.fetch:
src: /tmp/uniquefile
dest: /tmp/special/
flat: yes
- name: Storing in a path relative to the playbook
fetch:
ansible.builtin.fetch:
src: /tmp/uniquefile
dest: special/prefix-{{ inventory_hostname }}
flat: yes

13
lib/ansible/modules/group.py
View file

@ -62,20 +62,21 @@ seealso:
- module: ansible.windows.win_group
author:
- Stephen Fromm (@sfromm)
notes:
- Supports C(check_mode).
'''
EXAMPLES = '''
- name: Ensure group "somegroup" exists
group:
ansible.builtin.group:
name: somegroup
state: present
- name: Ensure group "docker" exists with correct gid
group:
ansible.builtin.group:
name: docker
state: present
gid: 1750
'''
RETURN = r'''
@ -85,17 +86,17 @@ gid:
type: int
sample: 1001
name:
description: Group name
description: Group name.
returned: always
type: str
sample: users
state:
description: Whether the group is present or not
description: Whether the group is present or not.
returned: always
type: str
sample: 'absent'
system:
description: Whether the group is a system group or not
description: Whether the group is a system group or not.
returned: When C(state) is 'present'
type: bool
sample: False

21
lib/ansible/modules/lineinfile.py
View file

@ -125,6 +125,7 @@ extends_documentation_fragment:
- validate
notes:
- As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well.
- Supports C(check_mode).
seealso:
- module: ansible.builtin.blockinfile
- module: ansible.builtin.copy
@ -140,19 +141,19 @@ author:
EXAMPLES = r'''
# NOTE: Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path'
- name: Ensure SELinux is set to enforcing mode
lineinfile:
ansible.builtin.lineinfile:
path: /etc/selinux/config
regexp: '^SELINUX='
line: SELINUX=enforcing
- name: Make sure group wheel is not in the sudoers configuration
lineinfile:
ansible.builtin.lineinfile:
path: /etc/sudoers
state: absent
regexp: '^%wheel'
- name: Replace a localhost entry with our own
lineinfile:
ansible.builtin.lineinfile:
path: /etc/hosts
regexp: '^127\.0\.0\.1'
line: 127.0.0.1 localhost
@ -161,28 +162,28 @@ EXAMPLES = r'''
mode: '0644'
- name: Ensure the default Apache port is 8080
lineinfile:
ansible.builtin.lineinfile:
path: /etc/httpd/conf/httpd.conf
regexp: '^Listen '
insertafter: '^#Listen '
line: Listen 8080
- name: Ensure we have our own comment added to /etc/services
lineinfile:
ansible.builtin.lineinfile:
path: /etc/services
regexp: '^# port for http'
insertbefore: '^www.*80/tcp'
line: '# port for http by default'
- name: Add a line to a file if the file does not exist, without passing regexp
lineinfile:
ansible.builtin.lineinfile:
path: /tmp/testfile
line: 192.168.1.99 foo.lab.net foo
create: yes
# NOTE: Yaml requires escaping backslashes in double quotes but not in single quotes
- name: Ensure the JBoss memory settings are exactly as needed
lineinfile:
ansible.builtin.lineinfile:
path: /opt/jboss-as/bin/standalone.conf
regexp: '^(.*)Xms(\d+)m(.*)$'
line: '\1Xms${xms}m\3'
@ -190,7 +191,7 @@ EXAMPLES = r'''
# NOTE: Fully quoted because of the ': ' on the line. See the Gotchas in the YAML docs.
- name: Validate the sudoers file before saving
lineinfile:
ansible.builtin.lineinfile:
path: /etc/sudoers
state: present
regexp: '^%ADMIN ALL='
@ -199,13 +200,15 @@ EXAMPLES = r'''
# See https://docs.python.org/3/library/re.html for further details on syntax
- name: Use backrefs with alternative group syntax to avoid conflicts with variable values
lineinfile:
ansible.builtin.lineinfile:
path: /tmp/config
regexp: ^(host=).*
line: \g<1>{{ hostname }}
backrefs: yes
'''
RETURN = r'''#'''
import os
import re
import tempfile

28
lib/ansible/modules/ping.py
View file

@ -15,12 +15,12 @@ module: ping
version_added: historical
short_description: Try to connect to host, verify a usable python and return C(pong) on success
description:
- A trivial test module, this module always returns C(pong) on successful
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 that requires Python on the remote-node.
- For Windows targets, use the M(ansible.windows.win_ping) module instead.
- For Network targets, use the M(ansible.netcommon.net_ping) module instead.
- A trivial test module, this module always returns C(pong) on successful
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 that requires Python on the remote-node.
- For Windows targets, use the M(ansible.windows.win_ping) module instead.
- For Network targets, use the M(ansible.netcommon.net_ping) module instead.
options:
data:
description:
@ -29,11 +29,13 @@ options:
type: str
default: pong
seealso:
- module: ansible.netcommon.net_ping
- module: ansible.windows.win_ping
- module: ansible.netcommon.net_ping
- module: ansible.windows.win_ping
author:
- Ansible Core Team
- Michael DeHaan
- Ansible Core Team
- Michael DeHaan
notes:
- Supports C(check_mode).
'''
EXAMPLES = '''
@ -41,16 +43,16 @@ EXAMPLES = '''
# ansible webservers -m ping
- name: Example from an Ansible Playbook
ping:
ansible.builtin.ping:
- name: Induce an exception to see what happens
ping:
ansible.builtin.ping:
data: crash
'''
RETURN = '''
ping:
description: value provided with the data parameter
description: Value provided with the data parameter.
returned: success
type: str
sample: pong

23
lib/ansible/modules/replace.py
View file

@ -95,24 +95,25 @@ notes:
previous incorrect behavior, you may be need to adjust your tasks.
See U(https://github.com/ansible/ansible/issues/31354) for details.
- Option I(follow) has been removed in Ansible 2.5, because this module modifies the contents of the file so I(follow=no) doesn't make sense.
- Supports C(check_mode).
'''
EXAMPLES = r'''
- name: Before Ansible 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path'
replace:
ansible.builtin.replace:
path: /etc/hosts
regexp: '(\s+)old\.host\.name(\s+.*)?$'
replace: '\1new.host.name\2'
- name: Replace after the expression till the end of the file (requires Ansible >= 2.4)
replace:
ansible.builtin.replace:
path: /etc/apache2/sites-available/default.conf
after: 'NameVirtualHost [*]'
regexp: '^(.+)$'
replace: '# \1'
- name: Replace before the expression till the begin of the file (requires Ansible >= 2.4)
replace:
ansible.builtin.replace:
path: /etc/apache2/sites-available/default.conf
before: '# live site config'
regexp: '^(.+)$'
@ -121,7 +122,7 @@ EXAMPLES = r'''
# Prior to Ansible 2.7.10, using before and after in combination did the opposite of what was intended.
# see https://github.com/ansible/ansible/issues/31354 for details.
- name: Replace between the expressions (requires Ansible >= 2.4)
replace:
ansible.builtin.replace:
path: /etc/hosts
after: '<VirtualHost [*]>'
before: '</VirtualHost>'
@ -129,7 +130,7 @@ EXAMPLES = r'''
replace: '# \1'
- name: Supports common file attributes
replace:
ansible.builtin.replace:
path: /home/jdoe/.ssh/known_hosts
regexp: '^old\.host\.name[^\n]*\n'
owner: jdoe
@ -137,34 +138,36 @@ EXAMPLES = r'''
mode: '0644'
- name: Supports a validate command
replace:
ansible.builtin.replace:
path: /etc/apache/ports
regexp: '^(NameVirtualHost|Listen)\s+80\s*$'
replace: '\1 127.0.0.1:8080'
validate: '/usr/sbin/apache2ctl -f %s -t'
- name: Short form task (in ansible 2+) necessitates backslash-escaped sequences
replace: path=/etc/hosts regexp='\\b(localhost)(\\d*)\\b' replace='\\1\\2.localdomain\\2 \\1\\2'
ansible.builtin.replace: path=/etc/hosts regexp='\\b(localhost)(\\d*)\\b' replace='\\1\\2.localdomain\\2 \\1\\2'
- name: Long form task does not
replace:
ansible.builtin.replace:
path: /etc/hosts
regexp: '\b(localhost)(\d*)\b'
replace: '\1\2.localdomain\2 \1\2'
- name: Explicitly specifying positional matched groups in replacement
replace:
ansible.builtin.replace:
path: /etc/ssh/sshd_config
regexp: '^(ListenAddress[ ]+)[^\n]+$'
replace: '\g<1>0.0.0.0'
- name: Explicitly specifying named matched groups
replace:
ansible.builtin.replace:
path: /etc/ssh/sshd_config
regexp: '^(?P<dctv>ListenAddress[ ]+)(?P<host>[^\n]+)$'
replace: '#\g<dctv>\g<host>\n\g<dctv>0.0.0.0'
'''
RETURN = r'''#'''
import os
import re
import tempfile

35
lib/ansible/modules/script.py
View file

@ -11,12 +11,12 @@ module: script
version_added: "0.9"
short_description: Runs a local script on a remote node after transferring it
description:
- The C(script) module takes the script name followed by a list of space-delimited arguments.
- Either a free form command or C(cmd) parameter is required, see the examples.
- The local script at path will be transferred to the remote node and then executed.
- 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(ansible.builtin.raw) module.
- This module is also supported for Windows targets.
- The C(script) module takes the script name followed by a list of space-delimited arguments.
- Either a free form command or C(cmd) parameter is required, see the examples.
- The local script at path will be transferred to the remote node and then executed.
- 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(ansible.builtin.raw) module.
- This module is also supported for Windows targets.
options:
free_form:
description:
@ -47,41 +47,42 @@ notes:
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.
- If the path to the local script contains spaces, it needs to be quoted.
- This module is also supported for Windows targets.
- Does not support C(check_mode).
seealso:
- module: ansible.builtin.shell
- module: ansible.windows.win_shell
- module: ansible.builtin.shell
- module: ansible.windows.win_shell
author:
- Ansible Core Team
- Michael DeHaan
- Ansible Core Team
- Michael DeHaan
extends_documentation_fragment:
- decrypt
- decrypt
'''
EXAMPLES = r'''
- name: Run a script with arguments (free form)
script: /some/local/script.sh --some-argument 1234
ansible.builtin.script: /some/local/script.sh --some-argument 1234
- name: Run a script with arguments (using 'cmd' parameter)
script:
ansible.builtin.script:
cmd: /some/local/script.sh --some-argument 1234
- name: Run a script only if file.txt does not exist on the remote node
script: /some/local/create_file.sh --some-argument 1234
ansible.builtin.script: /some/local/create_file.sh --some-argument 1234
args:
creates: /the/created/file.txt
- name: Run a script only if file.txt exists on the remote node
script: /some/local/remove_file.sh --some-argument 1234
ansible.builtin.script: /some/local/remove_file.sh --some-argument 1234
args:
removes: /the/removed/file.txt
- name: Run a script using an executable in a non-system path
script: /some/local/script
ansible.builtin.script: /some/local/script
args:
executable: /some/remote/executable
- name: Run a script using an executable in a system path
script: /some/local/script.py
ansible.builtin.script: /some/local/script.py
args:
executable: python3
'''

19
lib/ansible/modules/service.py
View file

@ -79,8 +79,9 @@ options:
version_added: 2.2
notes:
- For AIX, group subsystem names can be used.
- Supports C(check_mode).
seealso:
- module: ansible.windows.win_service
- module: ansible.windows.win_service
author:
- Ansible Core Team
- Michael DeHaan
@ -88,43 +89,45 @@ author:
EXAMPLES = r'''
- name: Start service httpd, if not started
service:
ansible.builtin.service:
name: httpd
state: started
- name: Stop service httpd, if started
service:
ansible.builtin.service:
name: httpd
state: stopped
- name: Restart service httpd, in all cases
service:
ansible.builtin.service:
name: httpd
state: restarted
- name: Reload service httpd, in all cases
service:
ansible.builtin.service:
name: httpd
state: reloaded
- name: Enable service httpd, and not touch the state
service:
ansible.builtin.service:
name: httpd
enabled: yes
- name: Start service foo, based on running process /usr/bin/foo
service:
ansible.builtin.service:
name: foo
pattern: /usr/bin/foo
state: started
- name: Restart network service for interface eth0
service:
ansible.builtin.service:
name: network
state: restarted
args: eth0
'''
RETURN = r'''#'''
import glob
import json
import os