a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[def]*.py: normalize docs (#9401) 

* [def]*.py: normalize docs

* Update plugins/modules/datadog_monitor.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
pull/9420/head
Alexei Znamensky 2024-12-27 09:53:20 +13:00 committed by GitHub
parent 84655b0d0f
commit df42f29e53
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
30 changed files with 1300 additions and 1431 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
plugins/modules/datadog_downtime.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = """ DOCUMENTATION = r"""
---
module: datadog_downtime module: datadog_downtime
short_description: Manages Datadog downtimes short_description: Manages Datadog downtimes
version_added: 2.0.0 version_added: 2.0.0
@ -25,105 +24,105 @@ requirements:
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
diff_mode: diff_mode:
support: none support: none
options: options:
api_key: api_key:
description: description:
- Your Datadog API key. - Your Datadog API key.
required: true required: true
type: str type: str
api_host: api_host:
description: description:
- The URL to the Datadog API. - The URL to the Datadog API.
- This value can also be set with the E(DATADOG_HOST) environment variable. - This value can also be set with the E(DATADOG_HOST) environment variable.
required: false required: false
default: https://api.datadoghq.com default: https://api.datadoghq.com
type: str type: str
app_key: app_key:
description: description:
- Your Datadog app key. - Your Datadog app key.
required: true required: true
type: str type: str
state: state:
description: description:
- The designated state of the downtime. - The designated state of the downtime.
required: false required: false
choices: ["present", "absent"] choices: ["present", "absent"]
default: present default: present
type: str type: str
id: id:
description: description:
- The identifier of the downtime. - The identifier of the downtime.
- If empty, a new downtime gets created, otherwise it is either updated or deleted depending of the O(state). - If empty, a new downtime gets created, otherwise it is either updated or deleted depending of the O(state).
- To keep your playbook idempotent, you should save the identifier in a file and read it in a lookup. - To keep your playbook idempotent, you should save the identifier in a file and read it in a lookup.
type: int type: int
monitor_tags:
description:
- A list of monitor tags to which the downtime applies.
- The resulting downtime applies to monitors that match ALL provided monitor tags.
type: list
elements: str
scope:
description:
- A list of scopes to which the downtime applies.
- The resulting downtime applies to sources that matches ALL provided scopes.
type: list
elements: str
monitor_id:
description:
- The ID of the monitor to mute. If not provided, the downtime applies to all monitors.
type: int
downtime_message:
description:
- A message to include with notifications for this downtime.
- Email notifications can be sent to specific users by using the same "@username" notation as events.
type: str
start:
type: int
description:
- POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.
end:
type: int
description:
- POSIX timestamp to end the downtime. If not provided, the downtime is in effect until you cancel it.
timezone:
description:
- The timezone for the downtime.
type: str
rrule:
description:
- The C(RRULE) standard for defining recurring events.
- For example, to have a recurring event on the first day of each month, select a type of rrule and set the C(FREQ)
to C(MONTHLY) and C(BYMONTHDAY) to C(1).
- Most common rrule options from the iCalendar Spec are supported.
- Attributes specifying the duration in C(RRULE) are not supported (for example C(DTSTART), C(DTEND), C(DURATION)).
type: str
"""
EXAMPLES = r"""
- name: Create a downtime
register: downtime_var
community.general.datadog_downtime:
state: present
monitor_tags: monitor_tags:
description: - "foo:bar"
- A list of monitor tags to which the downtime applies. downtime_message: "Downtime for foo:bar"
- The resulting downtime applies to monitors that match ALL provided monitor tags. scope: "test"
type: list api_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
elements: str app_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
scope: # Lookup the id in the file and ignore errors if the file doesn't exits, so downtime gets created
description: id: "{{ lookup('file', inventory_hostname ~ '_downtime_id.txt', errors='ignore') }}"
- A list of scopes to which the downtime applies. - name: Save downtime id to file for later updates and idempotence
- The resulting downtime applies to sources that matches ALL provided scopes. delegate_to: localhost
type: list copy:
elements: str content: "{{ downtime.downtime.id }}"
monitor_id: dest: "{{ inventory_hostname ~ '_downtime_id.txt' }}"
description:
- The ID of the monitor to mute. If not provided, the downtime applies to all monitors.
type: int
downtime_message:
description:
- A message to include with notifications for this downtime.
- Email notifications can be sent to specific users by using the same "@username" notation as events.
type: str
start:
type: int
description:
- POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.
end:
type: int
description:
- POSIX timestamp to end the downtime. If not provided, the downtime is in effect until you cancel it.
timezone:
description:
- The timezone for the downtime.
type: str
rrule:
description:
- The C(RRULE) standard for defining recurring events.
- For example, to have a recurring event on the first day of each month,
select a type of rrule and set the C(FREQ) to C(MONTHLY) and C(BYMONTHDAY) to C(1).
- Most common rrule options from the iCalendar Spec are supported.
- Attributes specifying the duration in C(RRULE) are not supported (for example C(DTSTART), C(DTEND), C(DURATION)).
type: str
""" """
EXAMPLES = """ RETURN = r"""
- name: Create a downtime
register: downtime_var
community.general.datadog_downtime:
state: present
monitor_tags:
- "foo:bar"
downtime_message: "Downtime for foo:bar"
scope: "test"
api_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
app_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
# Lookup the id in the file and ignore errors if the file doesn't exits, so downtime gets created
id: "{{ lookup('file', inventory_hostname ~ '_downtime_id.txt', errors='ignore') }}"
- name: Save downtime id to file for later updates and idempotence
delegate_to: localhost
copy:
content: "{{ downtime.downtime.id }}"
dest: "{{ inventory_hostname ~ '_downtime_id.txt' }}"
"""
RETURN = """
# Returns the downtime JSON dictionary from the API response under the C(downtime) key. # Returns the downtime JSON dictionary from the API response under the C(downtime) key.
# See https://docs.datadoghq.com/api/v1/downtimes/#schedule-a-downtime for more details. # See https://docs.datadoghq.com/api/v1/downtimes/#schedule-a-downtime for more details.
downtime: downtime:

138
plugins/modules/datadog_event.py
View File

@ -14,81 +14,88 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: datadog_event module: datadog_event
short_description: Posts events to Datadog service short_description: Posts events to Datadog service
description: description:
- "Allows to post events to Datadog (www.datadoghq.com) service." - Allows to post events to Datadog (www.datadoghq.com) service.
- "Uses http://docs.datadoghq.com/api/#events API." - Uses http://docs.datadoghq.com/api/#events API.
author: author:
- "Artūras 'arturaz' Šlajus (@arturaz)" - "Artūras 'arturaz' Šlajus (@arturaz)"
- "Naoya Nakazawa (@n0ts)" - "Naoya Nakazawa (@n0ts)"
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
diff_mode: diff_mode:
support: none support: none
options: options:
api_key: api_key:
type: str type: str
description: ["Your DataDog API key."] description:
required: true - Your DataDog API key.
app_key: required: true
type: str app_key:
description: ["Your DataDog app key."] type: str
required: true description:
title: - Your DataDog app key.
type: str required: true
description: ["The event title."] title:
required: true type: str
text: description:
type: str - The event title.
description: ["The body of the event."] required: true
required: true text:
date_happened: type: str
type: int description:
description: - The body of the event.
- POSIX timestamp of the event. required: true
- Default value is now. date_happened:
priority: type: int
type: str description:
description: ["The priority of the event."] - POSIX timestamp of the event.
default: normal - Default value is now.
choices: [normal, low] priority:
host: type: str
type: str description:
description: - The priority of the event.
- Host name to associate with the event. default: normal
- If not specified, it defaults to the remote system's hostname. choices: [normal, low]
api_host: host:
type: str type: str
description: description:
- DataDog API endpoint URL. - Host name to associate with the event.
version_added: '3.3.0' - If not specified, it defaults to the remote system's hostname.
tags: api_host:
type: list type: str
elements: str description:
description: ["Comma separated list of tags to apply to the event."] - DataDog API endpoint URL.
alert_type: version_added: '3.3.0'
type: str tags:
description: ["Type of alert."] type: list
default: info elements: str
choices: ['error', 'warning', 'info', 'success'] description:
aggregation_key: - Comma separated list of tags to apply to the event.
type: str alert_type:
description: ["An arbitrary string to use for aggregation."] type: str
validate_certs: description:
description: - Type of alert.
- If V(false), SSL certificates will not be validated. This should only be used default: info
on personally controlled sites using self-signed certificates. choices: ['error', 'warning', 'info', 'success']
type: bool aggregation_key:
default: true type: str
''' description:
- An arbitrary string to use for aggregation.
validate_certs:
description:
- If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
self-signed certificates.
type: bool
default: true
"""
EXAMPLES = ''' EXAMPLES = r"""
- name: Post an event with low priority - name: Post an event with low priority
community.general.datadog_event: community.general.datadog_event:
title: Testing from ansible title: Testing from ansible
@ -116,8 +123,7 @@ EXAMPLES = '''
- aa - aa
- b - b
- '#host:{{ inventory_hostname }}' - '#host:{{ inventory_hostname }}'
"""
'''
import platform import platform
import traceback import traceback

352
plugins/modules/datadog_monitor.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: datadog_monitor module: datadog_monitor
short_description: Manages Datadog monitors short_description: Manages Datadog monitors
description: description:
@ -21,181 +20,181 @@ requirements: [datadog]
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
diff_mode: diff_mode:
support: none support: none
options: options:
api_key: api_key:
description: description:
- Your Datadog API key. - Your Datadog API key.
required: true required: true
type: str type: str
api_host: api_host:
description: description:
- The URL to the Datadog API. Default value is V(https://api.datadoghq.com). - The URL to the Datadog API. Default value is V(https://api.datadoghq.com).
- This value can also be set with the E(DATADOG_HOST) environment variable. - This value can also be set with the E(DATADOG_HOST) environment variable.
required: false required: false
type: str type: str
version_added: '0.2.0' version_added: '0.2.0'
app_key: app_key:
description: description:
- Your Datadog app key. - Your Datadog app key.
required: true required: true
type: str type: str
state: state:
description: description:
- The designated state of the monitor. - The designated state of the monitor.
required: true required: true
choices: ['present', 'absent', 'mute', 'unmute'] choices: ['present', 'absent', 'mute', 'unmute']
type: str type: str
tags: tags:
description: description:
- A list of tags to associate with your monitor when creating or updating. - A list of tags to associate with your monitor when creating or updating.
- This can help you categorize and filter monitors. - This can help you categorize and filter monitors.
type: list type: list
elements: str elements: str
type: type:
description: description:
- The type of the monitor. - The type of the monitor.
- The types V(query alert), V(trace-analytics alert) and V(rum alert) were added in community.general 2.1.0. - The types V(query alert), V(trace-analytics alert) and V(rum alert) were added in community.general 2.1.0.
- The type V(composite) was added in community.general 3.4.0. - The type V(composite) was added in community.general 3.4.0.
- The type V(event-v2 alert) was added in community.general 4.8.0. - The type V(event-v2 alert) was added in community.general 4.8.0.
choices: choices:
- metric alert - metric alert
- service check - service check
- event alert - event alert
- event-v2 alert - event-v2 alert
- process alert - process alert
- log alert - log alert
- query alert - query alert
- trace-analytics alert - trace-analytics alert
- rum alert - rum alert
- composite - composite
type: str type: str
query: query:
description: description:
- The monitor query to notify on. - The monitor query to notify on.
- Syntax varies depending on what type of monitor you are creating. - Syntax varies depending on what type of monitor you are creating.
type: str type: str
name: name:
description: description:
- The name of the alert. - The name of the alert.
required: true required: true
type: str type: str
notification_message: notification_message:
description: description:
- A message to include with notifications for this monitor. - A message to include with notifications for this monitor.
- Email notifications can be sent to specific users by using the same '@username' notation as events. - Email notifications can be sent to specific users by using the same '@username' notation as events.
- Monitor message template variables can be accessed by using double square brackets, i.e '[[' and ']]'. - Monitor message template variables can be accessed by using double square brackets, in other words C([[) and C(]]).
type: str type: str
silenced: silenced:
type: dict type: dict
description: description:
- Dictionary of scopes to silence, with timestamps or None. - Dictionary of scopes to silence, with timestamps or None.
- Each scope will be muted until the given POSIX timestamp or forever if the value is None. - Each scope will be muted until the given POSIX timestamp or forever if the value is None.
notify_no_data: notify_no_data:
description: description:
- Whether this monitor will notify when data stops reporting. - Whether this monitor will notify when data stops reporting.
type: bool type: bool
default: false default: false
no_data_timeframe: no_data_timeframe:
description: description:
- The number of minutes before a monitor will notify when data stops reporting. - The number of minutes before a monitor will notify when data stops reporting.
- Must be at least 2x the monitor timeframe for metric alerts or 2 minutes for service checks. - Must be at least 2x the monitor timeframe for metric alerts or 2 minutes for service checks.
- If not specified, it defaults to 2x timeframe for metric, 2 minutes for service. - If not specified, it defaults to 2x timeframe for metric, 2 minutes for service.
type: str type: str
timeout_h: timeout_h:
description: description:
- The number of hours of the monitor not reporting data before it will automatically resolve from a triggered state. - The number of hours of the monitor not reporting data before it will automatically resolve from a triggered state.
type: str type: str
renotify_interval: renotify_interval:
description: description:
- The number of minutes after the last notification before a monitor will re-notify on the current status. - The number of minutes after the last notification before a monitor will re-notify on the current status.
- It will only re-notify if it is not resolved. - It will only re-notify if it is not resolved.
type: str type: str
escalation_message: escalation_message:
description: description:
- A message to include with a re-notification. Supports the '@username' notification we allow elsewhere. - A message to include with a re-notification. Supports the '@username' notification we allow elsewhere.
- Not applicable if O(renotify_interval=none). - Not applicable if O(renotify_interval=none).
type: str type: str
notify_audit: notify_audit:
description: description:
- Whether tagged users will be notified on changes to this monitor. - Whether tagged users will be notified on changes to this monitor.
type: bool type: bool
default: false default: false
thresholds: thresholds:
type: dict type: dict
description: description:
- A dictionary of thresholds by status. - A dictionary of thresholds by status.
- Only available for service checks and metric alerts. - Only available for service checks and metric alerts.
- Because each of them can have multiple thresholds, we do not define them directly in the query. - Because each of them can have multiple thresholds, we do not define them directly in the query.
- "If not specified, it defaults to: V({'ok': 1, 'critical': 1, 'warning': 1})." - "If not specified, it defaults to: V({'ok': 1, 'critical': 1, 'warning': 1})."
locked: locked:
description: description:
- Whether changes to this monitor should be restricted to the creator or admins. - Whether changes to this monitor should be restricted to the creator or admins.
type: bool type: bool
default: false default: false
require_full_window: require_full_window:
description: description:
- Whether this monitor needs a full window of data before it gets evaluated. - Whether this monitor needs a full window of data before it gets evaluated.
- We highly recommend you set this to False for sparse metrics, otherwise some evaluations will be skipped. - We highly recommend you set this to False for sparse metrics, otherwise some evaluations will be skipped.
type: bool type: bool
new_host_delay: new_host_delay:
description: description:
- A positive integer representing the number of seconds to wait before evaluating the monitor for new hosts. - A positive integer representing the number of seconds to wait before evaluating the monitor for new hosts.
- This gives the host time to fully initialize. - This gives the host time to fully initialize.
type: str type: str
evaluation_delay: evaluation_delay:
description: description:
- Time to delay evaluation (in seconds). - Time to delay evaluation (in seconds).
- Effective for sparse values. - Effective for sparse values.
type: str type: str
id: id:
description: description:
- The ID of the alert. - The ID of the alert.
- If set, will be used instead of the name to locate the alert. - If set, will be used instead of the name to locate the alert.
type: str type: str
include_tags: include_tags:
description: description:
- Whether notifications from this monitor automatically inserts its triggering tags into the title. - Whether notifications from this monitor automatically inserts its triggering tags into the title.
type: bool type: bool
default: true default: true
version_added: 1.3.0 version_added: 1.3.0
priority: priority:
description: description:
- Integer from 1 (high) to 5 (low) indicating alert severity. - Integer from V(1) (high) to V(5) (low) indicating alert severity.
type: int type: int
version_added: 4.6.0 version_added: 4.6.0
notification_preset_name: notification_preset_name:
description: description:
- Toggles the display of additional content sent in the monitor notification. - Toggles the display of additional content sent in the monitor notification.
choices: choices:
- show_all - show_all
- hide_query - hide_query
- hide_handles - hide_handles
- hide_all - hide_all
type: str type: str
version_added: 7.1.0 version_added: 7.1.0
renotify_occurrences: renotify_occurrences:
description: description:
- The number of times re-notification messages should be sent on the current status at the provided re-notification interval. - The number of times re-notification messages should be sent on the current status at the provided re-notification
type: int interval.
version_added: 7.1.0 type: int
renotify_statuses: version_added: 7.1.0
description: renotify_statuses:
- The types of monitor statuses for which re-notification messages are sent. description:
choices: - The types of monitor statuses for which re-notification messages are sent.
- alert choices:
- warn - alert
- no data - warn
type: list - no data
elements: str type: list
version_added: 7.1.0 elements: str
version_added: 7.1.0
"""
''' EXAMPLES = r"""
EXAMPLES = '''
- name: Create a metric monitor - name: Create a metric monitor
community.general.datadog_monitor: community.general.datadog_monitor:
type: "metric alert" type: "metric alert"
@ -239,7 +238,8 @@ EXAMPLES = '''
api_host: https://api.datadoghq.eu api_host: https://api.datadoghq.eu
api_key: "9775a026f1ca7d1c6c5af9d94d9595a4" api_key: "9775a026f1ca7d1c6c5af9d94d9595a4"
app_key: "87ce4a24b5553d2e482ea8a8500e71b8ad4554ff" app_key: "87ce4a24b5553d2e482ea8a8500e71b8ad4554ff"
''' """
import traceback import traceback
# Import Datadog # Import Datadog

93
plugins/modules/dconf.py
View File

@ -9,53 +9,39 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
module: dconf module: dconf
author: author:
- "Branko Majic (@azaghal)" - "Branko Majic (@azaghal)"
short_description: Modify and read dconf database short_description: Modify and read dconf database
description: description:
- This module allows modifications and reading of C(dconf) database. The module - This module allows modifications and reading of C(dconf) database. The module is implemented as a wrapper around C(dconf)
is implemented as a wrapper around C(dconf) tool. Please see the dconf(1) man tool. Please see the dconf(1) man page for more details.
page for more details. - Since C(dconf) requires a running D-Bus session to change values, the module will try to detect an existing session and
- Since C(dconf) requires a running D-Bus session to change values, the module reuse it, or run the tool using C(dbus-run-session).
will try to detect an existing session and reuse it, or run the tool via
C(dbus-run-session).
requirements: requirements:
- Optionally the C(gi.repository) Python library (usually included in the OS - Optionally the C(gi.repository) Python library (usually included in the OS on hosts which have C(dconf)); this will become
on hosts which have C(dconf)); this will become a non-optional requirement a non-optional requirement in a future major release of community.general.
in a future major release of community.general.
notes: notes:
- This module depends on C(psutil) Python library (version 4.0.0 and upwards), - This module depends on C(psutil) Python library (version 4.0.0 and upwards), C(dconf), C(dbus-send), and C(dbus-run-session)
C(dconf), C(dbus-send), and C(dbus-run-session) binaries. Depending on binaries. Depending on distribution you are using, you may need to install additional packages to have these available.
distribution you are using, you may need to install additional packages to - This module uses the C(gi.repository) Python library when available for accurate comparison of values in C(dconf) to values
have these available. specified in Ansible code. C(gi.repository) is likely to be present on most systems which have C(dconf) but may not be
- This module uses the C(gi.repository) Python library when available for present everywhere. When it is missing, a simple string comparison between values is used, and there may be false positives,
accurate comparison of values in C(dconf) to values specified in Ansible that is, Ansible may think that a value is being changed when it is not. This fallback will be removed in a future version
code. C(gi.repository) is likely to be present on most systems which have of this module, at which point the module will stop working on hosts without C(gi.repository).
C(dconf) but may not be present everywhere. When it is missing, a simple - Detection of existing, running D-Bus session, required to change settings using C(dconf), is not 100% reliable due to implementation
string comparison between values is used, and there may be false positives, details of D-Bus daemon itself. This might lead to running applications not picking-up changes on-the-fly if options are
that is, Ansible may think that a value is being changed when it is not. changed using Ansible and C(dbus-run-session).
This fallback will be removed in a future version of this module, at which - Keep in mind that the C(dconf) CLI tool, which this module wraps around, utilises an unusual syntax for the values (GVariant).
point the module will stop working on hosts without C(gi.repository). For example, if you wanted to provide a string value, the correct syntax would be O(value="'myvalue'") - with single quotes
- Detection of existing, running D-Bus session, required to change settings as part of the Ansible parameter value.
via C(dconf), is not 100% reliable due to implementation details of D-Bus - When using loops in combination with a value like V("[('xkb', 'us'\), ('xkb', 'se'\)]"), you need to be aware of possible
daemon itself. This might lead to running applications not picking-up type conversions. Applying a filter V({{ item.value | string }}) to the parameter variable can avoid potential conversion
changes on the fly if options are changed via Ansible and problems.
C(dbus-run-session). - The easiest way to figure out exact syntax/value you need to provide for a key is by making the configuration change in
- Keep in mind that the C(dconf) CLI tool, which this module wraps around, application affected by the key, and then having a look at value set using commands C(dconf dump /path/to/dir/) or C(dconf
utilises an unusual syntax for the values (GVariant). For example, if you read /path/to/key).
wanted to provide a string value, the correct syntax would be
O(value="'myvalue'") - with single quotes as part of the Ansible parameter
value.
- When using loops in combination with a value like
V("[('xkb', 'us'\), ('xkb', 'se'\)]"), you need to be aware of possible
type conversions. Applying a filter V({{ item.value | string }})
to the parameter variable can avoid potential conversion problems.
- The easiest way to figure out exact syntax/value you need to provide for a
key is by making the configuration change in application affected by the
key, and then having a look at value set via commands C(dconf dump
/path/to/dir/) or C(dconf read /path/to/key).
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -73,30 +59,27 @@ options:
type: raw type: raw
required: false required: false
description: description:
- Value to set for the specified dconf key. Value should be specified in - Value to set for the specified dconf key. Value should be specified in GVariant format. Due to complexity of this
GVariant format. Due to complexity of this format, it is best to have a format, it is best to have a look at existing values in the dconf database.
look at existing values in the dconf database.
- Required for O(state=present). - Required for O(state=present).
- Although the type is specified as "raw", it should typically be - Although the type is specified as "raw", it should typically be specified as a string. However, boolean values in
specified as a string. However, boolean values in particular are particular are handled properly even when specified as booleans rather than strings (in fact, handling booleans properly
handled properly even when specified as booleans rather than strings is why the type of this parameter is "raw").
(in fact, handling booleans properly is why the type of this parameter
is "raw").
state: state:
type: str type: str
required: false required: false
default: present default: present
choices: [ 'read', 'present', 'absent' ] choices: ['read', 'present', 'absent']
description: description:
- The action to take upon the key/value. - The action to take upon the key/value.
''' """
RETURN = r""" RETURN = r"""
value: value:
description: value associated with the requested key description: Value associated with the requested key.
returned: success, state was "read" returned: success, state was "read"
type: str type: str
sample: "'Default'" sample: "'Default'"
""" """
EXAMPLES = r""" EXAMPLES = r"""

40
plugins/modules/decompress.py
View File

@ -9,18 +9,17 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: decompress module: decompress
short_description: Decompresses compressed files short_description: Decompresses compressed files
version_added: 10.1.0 version_added: 10.1.0
description: description:
- Decompresses compressed files. - Decompresses compressed files.
- The source (compressed) file and destination (decompressed) files are on the remote host. - The source (compressed) file and destination (decompressed) files are on the remote host.
- Source file can be deleted after decompression. - Source file can be deleted after decompression.
extends_documentation_fragment: extends_documentation_fragment:
- ansible.builtin.files - ansible.builtin.files
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
@ -36,17 +35,17 @@ options:
description: description:
- The file name of the destination file where the compressed file will be decompressed. - The file name of the destination file where the compressed file will be decompressed.
- If the destination file exists, it will be truncated and overwritten. - If the destination file exists, it will be truncated and overwritten.
- If not specified, the destination filename will be derived from O(src) by removing the compression format - If not specified, the destination filename will be derived from O(src) by removing the compression format extension.
extension. For example, if O(src) is V(/path/to/file.txt.gz) and O(format) is V(gz), O(dest) will be For example, if O(src) is V(/path/to/file.txt.gz) and O(format) is V(gz), O(dest) will be V(/path/to/file.txt). If
V(/path/to/file.txt). If the O(src) file does not have an extension for the current O(format), the O(dest) the O(src) file does not have an extension for the current O(format), the O(dest) filename will be made by appending
filename will be made by appending C(_decompressed) to the O(src) filename. For instance, if O(src) is C(_decompressed) to the O(src) filename. For instance, if O(src) is V(/path/to/file.myextension), the (dest) filename
V(/path/to/file.myextension), the (dest) filename will be V(/path/to/file.myextension_decompressed). will be V(/path/to/file.myextension_decompressed).
type: path type: path
format: format:
description: description:
- The type of compression to use to decompress. - The type of compression to use to decompress.
type: str type: str
choices: [ gz, bz2, xz ] choices: [gz, bz2, xz]
default: gz default: gz
remove: remove:
description: description:
@ -54,12 +53,13 @@ options:
type: bool type: bool
default: false default: false
requirements: requirements:
- Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python 2) if using C(xz) format. - Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python
2) if using C(xz) format.
author: author:
- Stanislav Shamilov (@shamilovstas) - Stanislav Shamilov (@shamilovstas)
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Decompress file /path/to/file.txt.gz into /path/to/file.txt (gz compression is used by default) - name: Decompress file /path/to/file.txt.gz into /path/to/file.txt (gz compression is used by default)
community.general.decompress: community.general.decompress:
src: /path/to/file.txt.gz src: /path/to/file.txt.gz
@ -80,15 +80,15 @@ EXAMPLES = r'''
src: /path/to/file.txt.gz src: /path/to/file.txt.gz
dest: /path/to/file.txt dest: /path/to/file.txt
remove: true remove: true
''' """
RETURN = r''' RETURN = r"""
dest: dest:
description: Path to decompressed file description: Path to decompressed file.
type: str type: str
returned: success returned: success
sample: /path/to/file.txt sample: /path/to/file.txt
''' """
import bz2 import bz2
import filecmp import filecmp

85
plugins/modules/deploy_helper.py
View File

@ -11,27 +11,19 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: deploy_helper module: deploy_helper
author: "Ramon de la Fuente (@ramondelafuente)" author: "Ramon de la Fuente (@ramondelafuente)"
short_description: Manages some of the steps common in deploying projects short_description: Manages some of the steps common in deploying projects
description: description:
- The Deploy Helper manages some of the steps common in deploying software. - The Deploy Helper manages some of the steps common in deploying software. It creates a folder structure, manages a symlink
It creates a folder structure, manages a symlink for the current release for the current release and cleans up old releases.
and cleans up old releases. - Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact. C(project_path), whatever
# TODO: convert below to RETURN documentation! you set in the O(path) parameter, C(current_path), the path to the symlink that points to the active release, C(releases_path),
- "Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact. the path to the folder to keep releases in, C(shared_path), the path to the folder to keep shared resources in, C(unfinished_filename),
C(project_path), whatever you set in the O(path) parameter, the file to check for to recognize unfinished builds, C(previous_release), the release the 'current' symlink is pointing
C(current_path), the path to the symlink that points to the active release, to, C(previous_release_path), the full path to the 'current' symlink target, C(new_release), either the O(release) parameter
C(releases_path), the path to the folder to keep releases in, or a generated timestamp, C(new_release_path), the path to the new release folder (not created by the module).
C(shared_path), the path to the folder to keep shared resources in,
C(unfinished_filename), the file to check for to recognize unfinished builds,
C(previous_release), the release the 'current' symlink is pointing to,
C(previous_release_path), the full path to the 'current' symlink target,
C(new_release), either the 'release' parameter or a generated timestamp,
C(new_release_path), the path to the new release folder (not created by the module)."
attributes: attributes:
check_mode: check_mode:
support: full support: full
@ -44,42 +36,38 @@ options:
required: true required: true
aliases: ['dest'] aliases: ['dest']
description: description:
- The root path of the project. - The root path of the project. Returned in the C(deploy_helper.project_path) fact.
Returned in the C(deploy_helper.project_path) fact.
state: state:
type: str type: str
description: description:
- The state of the project. - The state of the project.
- V(query) will only gather facts. - V(query) will only gather facts.
- V(present) will create the project C(root) folder, and in it the C(releases) and C(shared) folders. - V(present) will create the project C(root) folder, and in it the C(releases) and C(shared) folders.
- V(finalize) will remove the unfinished_filename file, create a symlink to the newly - V(finalize) will remove the unfinished_filename file, create a symlink to the newly deployed release and optionally
deployed release and optionally clean old releases. clean old releases.
- V(clean) will remove failed & old releases. - V(clean) will remove failed & old releases.
- V(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with O(state=absent)). - V(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with O(state=absent)).
choices: [ present, finalize, absent, clean, query ] choices: [present, finalize, absent, clean, query]
default: present default: present
release: release:
type: str type: str
description: description:
- The release version that is being deployed. Defaults to a timestamp format C(%Y%m%d%H%M%S) (for example V(20141119223359)). - The release version that is being deployed. Defaults to a timestamp format C(%Y%m%d%H%M%S) (for example V(20141119223359)).
This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize). This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize). You can
You can use the generated fact C(release={{ deploy_helper.new_release }}). use the generated fact C(release={{ deploy_helper.new_release }}).
releases_path: releases_path:
type: str type: str
description: description:
- The name of the folder that will hold the releases. This can be relative to O(path) or absolute. - The name of the folder that will hold the releases. This can be relative to O(path) or absolute. Returned in the C(deploy_helper.releases_path)
Returned in the C(deploy_helper.releases_path) fact. fact.
default: releases default: releases
shared_path: shared_path:
type: path type: path
description: description:
- The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute. - The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute. If this is
If this is set to an empty string, no shared folder will be created. set to an empty string, no shared folder will be created. Returned in the C(deploy_helper.shared_path) fact.
Returned in the C(deploy_helper.shared_path) fact.
default: shared default: shared
current_path: current_path:
@ -92,9 +80,9 @@ options:
unfinished_filename: unfinished_filename:
type: str type: str
description: description:
- The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that - The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that contain this
contain this file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is automatically deleted
automatically deleted from the C(new_release_path) during O(state=finalize). from the C(new_release_path) during O(state=finalize).
default: DEPLOY_UNFINISHED default: DEPLOY_UNFINISHED
clean: clean:
@ -111,20 +99,18 @@ options:
default: 5 default: 5
notes: notes:
- Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden - Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden parameters
parameters to both calls, otherwise the second call will overwrite the facts of the first one. to both calls, otherwise the second call will overwrite the facts of the first one.
- When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a - When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a new naming
new naming strategy without problems. strategy without problems.
- Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent - Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent unless you
unless you pass your own release name with O(release). Due to the nature of deploying software, this should not pass your own release name with O(release). Due to the nature of deploying software, this should not be much of a problem.
be much of a problem.
extends_documentation_fragment: extends_documentation_fragment:
- ansible.builtin.files - ansible.builtin.files
- community.general.attributes - community.general.attributes
''' """
EXAMPLES = '''
EXAMPLES = r"""
# General explanation, starting with an example folder structure for a project: # General explanation, starting with an example folder structure for a project:
# root: # root:
@ -192,10 +178,10 @@ EXAMPLES = '''
src: '{{ deploy_helper.shared_path }}/{{ item.src }}' src: '{{ deploy_helper.shared_path }}/{{ item.src }}'
state: link state: link
with_items: with_items:
- path: app/sessions - path: app/sessions
src: sessions src: sessions
- path: web/uploads - path: web/uploads
src: uploads src: uploads
- name: Finalize the deploy, removing the unfinished file and switching the symlink - name: Finalize the deploy, removing the unfinished file and switching the symlink
community.general.deploy_helper: community.general.deploy_helper:
path: /path/to/root path: /path/to/root
@ -277,7 +263,8 @@ EXAMPLES = '''
path: /path/to/root path: /path/to/root
- ansible.builtin.debug: - ansible.builtin.debug:
var: deploy_helper var: deploy_helper
''' """
import os import os
import shutil import shutil
import time import time

79
plugins/modules/dimensiondata_network.py
View File

@ -14,8 +14,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: dimensiondata_network module: dimensiondata_network
short_description: Create, update, and delete MCP 1.0 & 2.0 networks short_description: Create, update, and delete MCP 1.0 & 2.0 networks
extends_documentation_fragment: extends_documentation_fragment:
@ -24,7 +23,7 @@ extends_documentation_fragment:
- community.general.attributes - community.general.attributes
description: description:
- Create, update, and delete MCP 1.0 & 2.0 networks - Create, update, and delete MCP 1.0 & 2.0 networks.
author: 'Aimon Bustardo (@aimonb)' author: 'Aimon Bustardo (@aimonb)'
attributes: attributes:
check_mode: check_mode:
@ -55,9 +54,9 @@ options:
choices: [present, absent] choices: [present, absent]
default: present default: present
type: str type: str
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Create an MCP 1.0 network - name: Create an MCP 1.0 network
community.general.dimensiondata_network: community.general.dimensiondata_network:
region: na region: na
@ -79,43 +78,43 @@ EXAMPLES = '''
location: NA1 location: NA1
name: mynet name: mynet
state: absent state: absent
''' """
RETURN = ''' RETURN = r"""
network: network:
description: Dictionary describing the network. description: Dictionary describing the network.
returned: On success when O(state=present). returned: On success when O(state=present).
type: complex type: complex
contains: contains:
id: id:
description: Network ID. description: Network ID.
type: str type: str
sample: "8c787000-a000-4050-a215-280893411a7d" sample: "8c787000-a000-4050-a215-280893411a7d"
name: name:
description: Network name. description: Network name.
type: str type: str
sample: "My network" sample: "My network"
description: description:
description: Network description. description: Network description.
type: str type: str
sample: "My network description" sample: "My network description"
location: location:
description: Datacenter location. description: Datacenter location.
type: str type: str
sample: NA3 sample: NA3
status: status:
description: Network status. (MCP 2.0 only) description: Network status. (MCP 2.0 only).
type: str type: str
sample: NORMAL sample: NORMAL
private_net: private_net:
description: Private network subnet. (MCP 1.0 only) description: Private network subnet. (MCP 1.0 only).
type: str type: str
sample: "10.2.3.0" sample: "10.2.3.0"
multicast: multicast:
description: Multicast enabled? (MCP 1.0 only) description: Multicast enabled? (MCP 1.0 only).
type: bool type: bool
sample: false sample: false
''' """
import traceback import traceback
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

121
plugins/modules/dimensiondata_vlan.py
View File

@ -10,8 +10,7 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: dimensiondata_vlan module: dimensiondata_vlan
short_description: Manage a VLAN in a Cloud Control network domain short_description: Manage a VLAN in a Cloud Control network domain
extends_documentation_fragment: extends_documentation_fragment:
@ -45,32 +44,34 @@ options:
type: str type: str
private_ipv4_base_address: private_ipv4_base_address:
description: description:
- The base address for the VLAN's IPv4 network (e.g. 192.168.1.0). - The base address for the VLAN's IPv4 network (for example V(192.168.1.0)).
type: str type: str
default: '' default: ''
private_ipv4_prefix_size: private_ipv4_prefix_size:
description: description:
- The size of the IPv4 address space, e.g 24. - The size of the IPv4 address space, for example V(24).
- Required, if O(private_ipv4_base_address) is specified. - Required, if O(private_ipv4_base_address) is specified.
type: int type: int
default: 0 default: 0
state: state:
description: description:
- The desired state for the target VLAN. - The desired state for the target VLAN.
- V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not exist). - V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not
exist).
choices: [present, absent, readonly] choices: [present, absent, readonly]
default: present default: present
type: str type: str
allow_expand: allow_expand:
description: description:
- Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently possesses. - Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently
possesses.
- If V(false), the module will fail under these conditions. - If V(false), the module will fail under these conditions.
- This is intended to prevent accidental expansion of a VLAN's network (since this operation is not reversible). - This is intended to prevent accidental expansion of a VLAN's network (since this operation is not reversible).
type: bool type: bool
default: false default: false
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Add or update VLAN - name: Add or update VLAN
community.general.dimensiondata_vlan: community.general.dimensiondata_vlan:
region: na region: na
@ -100,59 +101,59 @@ EXAMPLES = '''
name: my_vlan_1 name: my_vlan_1
state: absent state: absent
wait: true wait: true
''' """
RETURN = ''' RETURN = r"""
vlan: vlan:
description: Dictionary describing the VLAN. description: Dictionary describing the VLAN.
returned: On success when O(state=present) returned: On success when O(state=present)
type: complex type: complex
contains: contains:
id: id:
description: VLAN ID. description: VLAN ID.
type: str type: str
sample: "aaaaa000-a000-4050-a215-2808934ccccc" sample: "aaaaa000-a000-4050-a215-2808934ccccc"
name: name:
description: VLAN name. description: VLAN name.
type: str type: str
sample: "My VLAN" sample: "My VLAN"
description: description:
description: VLAN description. description: VLAN description.
type: str type: str
sample: "My VLAN description" sample: "My VLAN description"
location: location:
description: Datacenter location. description: Datacenter location.
type: str type: str
sample: NA3 sample: NA3
private_ipv4_base_address: private_ipv4_base_address:
description: The base address for the VLAN's private IPV4 network. description: The base address for the VLAN's private IPV4 network.
type: str type: str
sample: 192.168.23.0 sample: 192.168.23.0
private_ipv4_prefix_size: private_ipv4_prefix_size:
description: The prefix size for the VLAN's private IPV4 network. description: The prefix size for the VLAN's private IPV4 network.
type: int type: int
sample: 24 sample: 24
private_ipv4_gateway_address: private_ipv4_gateway_address:
description: The gateway address for the VLAN's private IPV4 network. description: The gateway address for the VLAN's private IPV4 network.
type: str type: str
sample: 192.168.23.1 sample: 192.168.23.1
private_ipv6_base_address: private_ipv6_base_address:
description: The base address for the VLAN's IPV6 network. description: The base address for the VLAN's IPV6 network.
type: str type: str
sample: 2402:9900:111:1195:0:0:0:0 sample: 2402:9900:111:1195:0:0:0:0
private_ipv6_prefix_size: private_ipv6_prefix_size:
description: The prefix size for the VLAN's IPV6 network. description: The prefix size for the VLAN's IPV6 network.
type: int type: int
sample: 64 sample: 64
private_ipv6_gateway_address: private_ipv6_gateway_address:
description: The gateway address for the VLAN's IPV6 network. description: The gateway address for the VLAN's IPV6 network.
type: str type: str
sample: 2402:9900:111:1195:0:0:0:1 sample: 2402:9900:111:1195:0:0:0:1
status: status:
description: VLAN status. description: VLAN status.
type: str type: str
sample: NORMAL sample: NORMAL
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.dimensiondata import DimensionDataModule, UnknownNetworkError from ansible_collections.community.general.plugins.module_utils.dimensiondata import DimensionDataModule, UnknownNetworkError

17
plugins/modules/discord.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: discord module: discord
short_description: Send Discord messages short_description: Send Discord messages
version_added: 3.1.0 version_added: 3.1.0
@ -18,7 +17,7 @@ description:
author: Christian Wollinger (@cwollinger) author: Christian Wollinger (@cwollinger)
seealso: seealso:
- name: API documentation - name: API documentation
description: Documentation for Discord API description: Documentation for Discord API.
link: https://discord.com/developers/docs/resources/webhook#execute-webhook link: https://discord.com/developers/docs/resources/webhook#execute-webhook
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
@ -31,13 +30,13 @@ options:
webhook_id: webhook_id:
description: description:
- The webhook ID. - The webhook ID.
- "Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token})." - 'Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token}).'
required: true required: true
type: str type: str
webhook_token: webhook_token:
description: description:
- The webhook token. - The webhook token.
- "Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token})." - 'Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token}).'
required: true required: true
type: str type: str
content: content:
@ -62,13 +61,13 @@ options:
description: description:
- Send messages as Embeds to the Discord channel. - Send messages as Embeds to the Discord channel.
- Embeds can have a colored border, embedded images, text fields and more. - Embeds can have a colored border, embedded images, text fields and more.
- "Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object)" - 'Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object).'
- At least one of O(content) and O(embeds) must be specified. - At least one of O(content) and O(embeds) must be specified.
type: list type: list
elements: dict elements: dict
''' """
EXAMPLES = """ EXAMPLES = r"""
- name: Send a message to the Discord channel - name: Send a message to the Discord channel
community.general.discord: community.general.discord:
webhook_id: "00000" webhook_id: "00000"
@ -119,7 +118,7 @@ EXAMPLES = """
timestamp: "{{ ansible_date_time.iso8601 }}" timestamp: "{{ ansible_date_time.iso8601 }}"
""" """
RETURN = """ RETURN = r"""
http_code: http_code:
description: description:
- Response Code returned by Discord API. - Response Code returned by Discord API.

41
plugins/modules/django_check.py
View File

@ -7,50 +7,49 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = """ DOCUMENTATION = r"""
---
module: django_check module: django_check
author: author:
- Alexei Znamensky (@russoz) - Alexei Znamensky (@russoz)
short_description: Wrapper for C(django-admin check) short_description: Wrapper for C(django-admin check)
version_added: 9.1.0 version_added: 9.1.0
description: description:
- This module is a wrapper for the execution of C(django-admin check). - This module is a wrapper for the execution of C(django-admin check).
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
- community.general.django - community.general.django
options: options:
database: database:
description: description:
- Specify databases to run checks against. - Specify databases to run checks against.
- If not specified, Django will not run database tests. - If not specified, Django will not run database tests.
type: list type: list
elements: str elements: str
deploy: deploy:
description: description:
- Include additional checks relevant in a deployment setting. - Include additional checks relevant in a deployment setting.
type: bool type: bool
default: false default: false
fail_level: fail_level:
description: description:
- Message level that will trigger failure. - Message level that will trigger failure.
- Default is the Django default value. Check the documentation for the version being used. - Default is the Django default value. Check the documentation for the version being used.
type: str type: str
choices: [CRITICAL, ERROR, WARNING, INFO, DEBUG] choices: [CRITICAL, ERROR, WARNING, INFO, DEBUG]
tags: tags:
description: description:
- Restrict checks to specific tags. - Restrict checks to specific tags.
type: list type: list
elements: str elements: str
apps: apps:
description: description:
- Restrict checks to specific applications. - Restrict checks to specific applications.
- Default is to check all applications. - Default is to check all applications.
type: list type: list
elements: str elements: str
notes: notes:
- The outcome of the module is found in the common return values RV(ignore:stdout), RV(ignore:stderr), RV(ignore:rc). - The outcome of the module is found in the common return values RV(ignore:stdout), RV(ignore:stderr), RV(ignore:rc).
- The module will fail if RV(ignore:rc) is not zero. - The module will fail if RV(ignore:rc) is not zero.
attributes: attributes:
check_mode: check_mode:
support: full support: full
@ -58,8 +57,7 @@ attributes:
support: none support: none
""" """
EXAMPLES = """ EXAMPLES = r"""
---
- name: Check the entire project - name: Check the entire project
community.general.django_check: community.general.django_check:
settings: myproject.settings settings: myproject.settings
@ -67,15 +65,14 @@ EXAMPLES = """
- name: Create the project using specific databases - name: Create the project using specific databases
community.general.django_check: community.general.django_check:
database: database:
- somedb - somedb
- myotherdb - myotherdb
settings: fancysite.settings settings: fancysite.settings
pythonpath: /home/joedoe/project/fancysite pythonpath: /home/joedoe/project/fancysite
venv: /home/joedoe/project/fancysite/venv venv: /home/joedoe/project/fancysite/venv
""" """
RETURN = """ RETURN = r"""
---
run_info: run_info:
description: Command-line execution information. description: Command-line execution information.
type: dict type: dict

21
plugins/modules/django_command.py
View File

@ -7,18 +7,17 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = """ DOCUMENTATION = r"""
---
module: django_command module: django_command
author: author:
- Alexei Znamensky (@russoz) - Alexei Znamensky (@russoz)
short_description: Run Django admin commands short_description: Run Django admin commands
version_added: 9.0.0 version_added: 9.0.0
description: description:
- This module allows the execution of arbitrary Django admin commands. - This module allows the execution of arbitrary Django admin commands.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
- community.general.django - community.general.django
attributes: attributes:
check_mode: check_mode:
support: none support: none
@ -27,18 +26,17 @@ attributes:
options: options:
command: command:
description: description:
- Django admin command. It must be a valid command accepted by C(python -m django) at the target system. - Django admin command. It must be a valid command accepted by C(python -m django) at the target system.
type: str type: str
required: true required: true
extra_args: extra_args:
type: list type: list
elements: str elements: str
description: description:
- List of extra arguments passed to the django admin command. - List of extra arguments passed to the django admin command.
""" """
EXAMPLES = """ EXAMPLES = r"""
---
- name: Check the project - name: Check the project
community.general.django_command: community.general.django_command:
command: check command: check
@ -52,8 +50,7 @@ EXAMPLES = """
venv: /home/joedoe/project/fancysite/venv venv: /home/joedoe/project/fancysite/venv
""" """
RETURN = """ RETURN = r"""
---
run_info: run_info:
description: Command-line execution information. description: Command-line execution information.
type: dict type: dict

19
plugins/modules/django_createcachetable.py
View File

@ -7,19 +7,18 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = """ DOCUMENTATION = r"""
---
module: django_createcachetable module: django_createcachetable
author: author:
- Alexei Znamensky (@russoz) - Alexei Znamensky (@russoz)
short_description: Wrapper for C(django-admin createcachetable) short_description: Wrapper for C(django-admin createcachetable)
version_added: 9.1.0 version_added: 9.1.0
description: description:
- This module is a wrapper for the execution of C(django-admin createcachetable). - This module is a wrapper for the execution of C(django-admin createcachetable).
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
- community.general.django - community.general.django
- community.general.django.database - community.general.django.database
attributes: attributes:
check_mode: check_mode:
support: full support: full
@ -27,8 +26,7 @@ attributes:
support: none support: none
""" """
EXAMPLES = """ EXAMPLES = r"""
---
- name: Create cache table in the default database - name: Create cache table in the default database
community.general.django_createcachetable: community.general.django_createcachetable:
settings: myproject.settings settings: myproject.settings
@ -41,8 +39,7 @@ EXAMPLES = """
venv: /home/joedoe/project/fancysite/venv venv: /home/joedoe/project/fancysite/venv
""" """
RETURN = """ RETURN = r"""
---
run_info: run_info:
description: Command-line execution information. description: Command-line execution information.
type: dict type: dict

57
plugins/modules/django_manage.py
View File

@ -10,13 +10,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: django_manage module: django_manage
short_description: Manages a Django application short_description: Manages a Django application
description: description:
- Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the - Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the O(virtualenv) parameter,
O(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation. all management commands will be executed by the given C(virtualenv) installation.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -27,17 +26,18 @@ attributes:
options: options:
command: command:
description: description:
- The name of the Django management command to run. The commands listed below are built in this module and have some basic parameter validation. - The name of the Django management command to run. The commands listed below are built in this module and have some
basic parameter validation.
- V(collectstatic) - Collects the static files into C(STATIC_ROOT). - V(collectstatic) - Collects the static files into C(STATIC_ROOT).
- V(createcachetable) - Creates the cache tables for use with the database cache backend. - V(createcachetable) - Creates the cache tables for use with the database cache backend.
- V(flush) - Removes all data from the database. - V(flush) - Removes all data from the database.
- V(loaddata) - Searches for and loads the contents of the named O(fixtures) into the database. - V(loaddata) - Searches for and loads the contents of the named O(fixtures) into the database.
- V(migrate) - Synchronizes the database state with models and migrations. - V(migrate) - Synchronizes the database state with models and migrations.
- V(test) - Runs tests for all installed apps. - V(test) - Runs tests for all installed apps.
- Other commands can be entered, but will fail if they are unknown to Django. Other commands that may - Other commands can be entered, but will fail if they are unknown to Django. Other commands that may prompt for user
prompt for user input should be run with the C(--noinput) flag. input should be run with the C(--noinput) flag.
- Support for the values V(cleanup), V(syncdb), V(validate) was removed in community.general 9.0.0. - Support for the values V(cleanup), V(syncdb), V(validate) was removed in community.general 9.0.0. See note about supported
See note about supported versions of Django. versions of Django.
type: str type: str
required: true required: true
project_path: project_path:
@ -53,8 +53,8 @@ options:
required: false required: false
pythonpath: pythonpath:
description: description:
- A directory to add to the Python path. Typically used to include the settings module if it is located - A directory to add to the Python path. Typically used to include the settings module if it is located external to
external to the application directory. the application directory.
- This would be equivalent to adding O(pythonpath)'s value to the E(PYTHONPATH) environment variable. - This would be equivalent to adding O(pythonpath)'s value to the E(PYTHONPATH) environment variable.
type: path type: path
required: false required: false
@ -84,8 +84,7 @@ options:
type: bool type: bool
database: database:
description: description:
- The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb), - The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb), and V(migrate) commands.
and V(migrate) commands.
type: str type: str
required: false required: false
failfast: failfast:
@ -107,14 +106,13 @@ options:
type: bool type: bool
merge: merge:
description: description:
- Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this - Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this parameter with
parameter with V(migrate) command. V(migrate) command.
required: false required: false
type: bool type: bool
link: link:
description: description:
- Will create links to the files instead of copying them, you can only use this parameter with - Will create links to the files instead of copying them, you can only use this parameter with V(collectstatic) command.
V(collectstatic) command.
required: false required: false
type: bool type: bool
testrunner: testrunner:
@ -132,20 +130,17 @@ options:
version_added: 5.8.0 version_added: 5.8.0
notes: notes:
- > - 'B(ATTENTION): Support for Django releases older than 4.1 has been removed in community.general version 9.0.0. While the
B(ATTENTION): Support for Django releases older than 4.1 has been removed in module allows for free-form commands, not verifying the version of Django being used, it is B(strongly recommended) to
community.general version 9.0.0. While the module allows for free-form commands use a more recent version of the framework.'
does not verify the version of Django being used, it is B(strongly recommended)
to use a more recent version of Django.
- Please notice that Django 4.1 requires Python 3.8 or greater. - Please notice that Django 4.1 requires Python 3.8 or greater.
- This module will not create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment - This module will not create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment does not
does not already exist at the given location. This behavior changed in community.general version 9.0.0. already exist at the given location. This behavior changed in community.general version 9.0.0.
- The recommended way to create a virtual environment in Ansible is by using M(ansible.builtin.pip). - The recommended way to create a virtual environment in Ansible is by using M(ansible.builtin.pip).
- This module assumes English error messages for the V(createcachetable) command to detect table existence, - This module assumes English error messages for the V(createcachetable) command to detect table existence, unfortunately.
unfortunately.
- To be able to use the V(collectstatic) command, you must have enabled C(staticfiles) in your settings. - To be able to use the V(collectstatic) command, you must have enabled C(staticfiles) in your settings.
- Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang, - Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang, for example C(#!/usr/bin/env
for example C(#!/usr/bin/env python), for invoking the appropriate Python interpreter. python), for invoking the appropriate Python interpreter.
seealso: seealso:
- name: django-admin and manage.py Reference - name: django-admin and manage.py Reference
description: Reference for C(django-admin) or C(manage.py) commands. description: Reference for C(django-admin) or C(manage.py) commands.
@ -156,13 +151,13 @@ seealso:
- name: What Python version can I use with Django? - name: What Python version can I use with Django?
description: From the Django FAQ, the response to Python requirements for the framework. description: From the Django FAQ, the response to Python requirements for the framework.
link: https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django link: https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django
requirements: [ "django >= 4.1" ] requirements: ["django >= 4.1"]
author: author:
- Alexei Znamensky (@russoz) - Alexei Znamensky (@russoz)
- Scott Anderson (@tastychutney) - Scott Anderson (@tastychutney)
''' """
EXAMPLES = """ EXAMPLES = r"""
- name: Run cleanup on the application installed in django_dir - name: Run cleanup on the application installed in django_dir
community.general.django_manage: community.general.django_manage:
command: clearsessions command: clearsessions

23
plugins/modules/dnf_config_manager.py
View File

@ -7,8 +7,7 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: dnf_config_manager module: dnf_config_manager
short_description: Enable or disable dnf repositories using config-manager short_description: Enable or disable dnf repositories using config-manager
version_added: 8.2.0 version_added: 8.2.0
@ -43,9 +42,9 @@ options:
seealso: seealso:
- module: ansible.builtin.dnf - module: ansible.builtin.dnf
- module: ansible.builtin.yum_repository - module: ansible.builtin.yum_repository
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Ensure the crb repository is enabled - name: Ensure the crb repository is enabled
community.general.dnf_config_manager: community.general.dnf_config_manager:
name: crb name: crb
@ -57,9 +56,9 @@ EXAMPLES = r'''
- appstream - appstream
- zfs - zfs
state: disabled state: disabled
''' """
RETURN = r''' RETURN = r"""
repo_states_pre: repo_states_pre:
description: Repo IDs before action taken. description: Repo IDs before action taken.
returned: success returned: success
@ -115,12 +114,12 @@ repo_states_post:
- crb-debug - crb-debug
- crb-source - crb-source
changed_repos: changed_repos:
description: Repositories changed. description: Repositories changed.
returned: success returned: success
type: list type: list
elements: str elements: str
sample: [ 'crb' ] sample: ['crb']
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
import os import os

112
plugins/modules/dnf_versionlock.py
View File

@ -7,37 +7,32 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: dnf_versionlock module: dnf_versionlock
version_added: '4.0.0' version_added: '4.0.0'
short_description: Locks package versions in C(dnf) based systems short_description: Locks package versions in C(dnf) based systems
description: description:
- Locks package versions using the C(versionlock) plugin in C(dnf) based - Locks package versions using the C(versionlock) plugin in C(dnf) based systems. This plugin takes a set of name and versions
systems. This plugin takes a set of name and versions for packages and for packages and excludes all other versions of those packages. This allows you to for example protect packages from being
excludes all other versions of those packages. This allows you to for example updated by newer versions. The state of the plugin that reflects locking of packages is the C(locklist).
protect packages from being updated by newer versions. The state of the
plugin that reflects locking of packages is the C(locklist).
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: partial support: partial
details: details:
- The logics of the C(versionlock) plugin for corner cases could be - The logics of the C(versionlock) plugin for corner cases could be confusing, so please take in account that this module
confusing, so please take in account that this module will do its best to will do its best to give a C(check_mode) prediction on what is going to happen. In case of doubt, check the documentation
give a C(check_mode) prediction on what is going to happen. In case of of the plugin.
doubt, check the documentation of the plugin. - Sometimes the module could predict changes in C(check_mode) that will not be such because C(versionlock) concludes
- Sometimes the module could predict changes in C(check_mode) that will not that there is already a entry in C(locklist) that already matches.
be such because C(versionlock) concludes that there is already a entry in
C(locklist) that already matches.
diff_mode: diff_mode:
support: none support: none
options: options:
name: name:
description: description:
- Package name spec to add or exclude to or delete from the C(locklist) - Package name spec to add or exclude to or delete from the C(locklist) using the format expected by the C(dnf repoquery)
using the format expected by the C(dnf repoquery) command. command.
- This parameter is mutually exclusive with O(state=clean). - This parameter is mutually exclusive with O(state=clean).
type: list type: list
required: false required: false
@ -45,43 +40,34 @@ options:
default: [] default: []
raw: raw:
description: description:
- Do not resolve package name specs to NEVRAs to find specific version - Do not resolve package name specs to NEVRAs to find specific version to lock to. Instead the package name specs are
to lock to. Instead the package name specs are used as they are. This used as they are. This enables locking to not yet available versions of the package.
enables locking to not yet available versions of the package.
type: bool type: bool
default: false default: false
state: state:
description: description:
- Whether to add (V(present) or V(excluded)) to or remove (V(absent) or - Whether to add (V(present) or V(excluded)) to or remove (V(absent) or V(clean)) from the C(locklist).
V(clean)) from the C(locklist). - V(present) will add a package name spec to the C(locklist). If there is a installed package that matches, then only
- V(present) will add a package name spec to the C(locklist). If there is a that version will be added. Otherwise, all available package versions will be added.
installed package that matches, then only that version will be added. - V(excluded) will add a package name spec as excluded to the C(locklist). It means that packages represented by the
Otherwise, all available package versions will be added. package name spec will be excluded from transaction operations. All available package versions will be added.
- V(excluded) will add a package name spec as excluded to the - V(absent) will delete entries in the C(locklist) that match the package name spec.
C(locklist). It means that packages represented by the package name - V(clean) will delete all entries in the C(locklist). This option is mutually exclusive with O(name).
spec will be excluded from transaction operations. All available choices: ['absent', 'clean', 'excluded', 'present']
package versions will be added.
- V(absent) will delete entries in the C(locklist) that match the
package name spec.
- V(clean) will delete all entries in the C(locklist). This option is
mutually exclusive with O(name).
choices: [ 'absent', 'clean', 'excluded', 'present' ]
type: str type: str
default: present default: present
notes: notes:
- In an ideal world, the C(versionlock) plugin would have a dry-run option to - In an ideal world, the C(versionlock) plugin would have a dry-run option to know for sure what is going to happen. So
know for sure what is going to happen. So far we have to work with a best far we have to work with a best guess as close as possible to the behaviour inferred from its code.
guess as close as possible to the behaviour inferred from its code. - For most of cases where you want to lock and unlock specific versions of a package, this works fairly well.
- For most of cases where you want to lock and unlock specific versions of a
package, this works fairly well.
requirements: requirements:
- dnf - dnf
- dnf-plugin-versionlock - dnf-plugin-versionlock
author: author:
- Roberto Moreda (@moreda) <moreda@allenta.com> - Roberto Moreda (@moreda) <moreda@allenta.com>
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Prevent installed nginx from being updated - name: Prevent installed nginx from being updated
community.general.dnf_versionlock: community.general.dnf_versionlock:
name: nginx name: nginx
@ -113,34 +99,34 @@ EXAMPLES = r'''
- name: Delete all entries in the locklist of versionlock - name: Delete all entries in the locklist of versionlock
community.general.dnf_versionlock: community.general.dnf_versionlock:
state: clean state: clean
''' """
RETURN = r''' RETURN = r"""
locklist_pre: locklist_pre:
description: Locklist before module execution. description: Locklist before module execution.
returned: success returned: success
type: list type: list
elements: str elements: str
sample: [ 'bash-0:4.4.20-1.el8_4.*', '!bind-32:9.11.26-4.el8_4.*' ] sample: ['bash-0:4.4.20-1.el8_4.*', '!bind-32:9.11.26-4.el8_4.*']
locklist_post: locklist_post:
description: Locklist after module execution. description: Locklist after module execution.
returned: success and (not check mode or state is clean) returned: success and (not check mode or state is clean)
type: list type: list
elements: str elements: str
sample: [ 'bash-0:4.4.20-1.el8_4.*' ] sample: ['bash-0:4.4.20-1.el8_4.*']
specs_toadd: specs_toadd:
description: Package name specs meant to be added by versionlock. description: Package name specs meant to be added by versionlock.
returned: success returned: success
type: list type: list
elements: str elements: str
sample: [ 'bash' ] sample: ['bash']
specs_todelete: specs_todelete:
description: Package name specs meant to be deleted by versionlock. description: Package name specs meant to be deleted by versionlock.
returned: success returned: success
type: list type: list
elements: str elements: str
sample: [ 'bind' ] sample: ['bind']
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
import fnmatch import fnmatch

26
plugins/modules/dnsimple.py
View File

@ -10,12 +10,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: dnsimple module: dnsimple
short_description: Interface with dnsimple.com (a DNS hosting service) short_description: Interface with dnsimple.com (a DNS hosting service)
description: description:
- "Manages domains and records via the DNSimple API, see the docs: U(http://developer.dnsimple.com/)." - 'Manages domains and records using the DNSimple API, see the docs: U(http://developer.dnsimple.com/).'
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -27,8 +26,8 @@ options:
account_email: account_email:
description: description:
- Account email. If omitted, the environment variables E(DNSIMPLE_EMAIL) and E(DNSIMPLE_API_TOKEN) will be looked for. - Account email. If omitted, the environment variables E(DNSIMPLE_EMAIL) and E(DNSIMPLE_API_TOKEN) will be looked for.
- "If those aren't found, a C(.dnsimple) file will be looked for, see: U(https://github.com/mikemaccana/dnsimple-python#getting-started)." - "If those variables are not found, a C(.dnsimple) file will be looked for, see: U(https://github.com/mikemaccana/dnsimple-python#getting-started)."
- "C(.dnsimple) config files are only supported in dnsimple-python<2.0.0" - C(.dnsimple) config files are only supported in dnsimple-python<2.0.0.
type: str type: str
account_api_token: account_api_token:
description: description:
@ -36,9 +35,9 @@ options:
type: str type: str
domain: domain:
description: description:
- Domain to work with. Can be the domain name (e.g. "mydomain.com") or the numeric ID of the domain in DNSimple. - Domain to work with. Can be the domain name (for example V(mydomain.com)) or the numeric ID of the domain in DNSimple.
- If omitted, a list of domains will be returned. - If omitted, a list of domains will be returned.
- If domain is present but the domain doesn't exist, it will be created. - If domain is present but the domain does not exist, it will be created.
type: str type: str
record: record:
description: description:
@ -52,7 +51,8 @@ options:
type: type:
description: description:
- The type of DNS record to create. - The type of DNS record to create.
choices: [ 'A', 'ALIAS', 'CNAME', 'MX', 'SPF', 'URL', 'TXT', 'NS', 'SRV', 'NAPTR', 'PTR', 'AAAA', 'SSHFP', 'HINFO', 'POOL', 'CAA' ] choices: ['A', 'ALIAS', 'CNAME', 'MX', 'SPF', 'URL', 'TXT', 'NS', 'SRV', 'NAPTR', 'PTR', 'AAAA', 'SSHFP', 'HINFO', 'POOL',
'CAA']
type: str type: str
ttl: ttl:
description: description:
@ -70,8 +70,8 @@ options:
type: int type: int
state: state:
description: description:
- whether the record should exist or not. - Whether the record should exist or not.
choices: [ 'present', 'absent' ] choices: ['present', 'absent']
default: present default: present
type: str type: str
solo: solo:
@ -91,9 +91,9 @@ options:
requirements: requirements:
- "dnsimple >= 2.0.0" - "dnsimple >= 2.0.0"
author: "Alex Coomans (@drcapulet)" author: "Alex Coomans (@drcapulet)"
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Authenticate using email and API token and fetch all domains - name: Authenticate using email and API token and fetch all domains
community.general.dnsimple: community.general.dnsimple:
account_email: test@example.com account_email: test@example.com
@ -149,7 +149,7 @@ EXAMPLES = '''
value: example.com value: example.com
state: absent state: absent
delegate_to: localhost delegate_to: localhost
''' """
RETURN = r"""# """ RETURN = r"""# """

299
plugins/modules/dnsimple_info.py
View File

@ -9,8 +9,7 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: dnsimple_info module: dnsimple_info
short_description: Pull basic info from DNSimple API short_description: Pull basic info from DNSimple API
@ -20,45 +19,45 @@ version_added: "4.2.0"
description: Retrieve existing records and domains from DNSimple API. description: Retrieve existing records and domains from DNSimple API.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
- community.general.attributes.info_module - community.general.attributes.info_module
options: options:
name: name:
description: description:
- The domain name to retrieve info from. - The domain name to retrieve info from.
- Will return all associated records for this domain if specified. - Will return all associated records for this domain if specified.
- If not specified, will return all domains associated with the account ID. - If not specified, will return all domains associated with the account ID.
type: str type: str
account_id: account_id:
description: The account ID to query. description: The account ID to query.
required: true required: true
type: str type: str
api_key: api_key:
description: The API key to use. description: The API key to use.
required: true required: true
type: str type: str
record: record:
description: description:
- The record to find. - The record to find.
- If specified, only this record will be returned instead of all records. - If specified, only this record will be returned instead of all records.
required: false required: false
type: str type: str
sandbox: sandbox:
description: Whether or not to use sandbox environment. description: Whether or not to use sandbox environment.
required: false required: false
default: false default: false
type: bool type: bool
author: author:
- Edward Hilgendorf (@edhilgendorf) - Edward Hilgendorf (@edhilgendorf)
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Get all domains from an account - name: Get all domains from an account
community.general.dnsimple_info: community.general.dnsimple_info:
account_id: "1234" account_id: "1234"
@ -76,15 +75,15 @@ EXAMPLES = r'''
record: "subdomain" record: "subdomain"
account_id: "1234" account_id: "1234"
api_key: "1234" api_key: "1234"
''' """
RETURN = r''' RETURN = r"""
dnsimple_domain_info: dnsimple_domain_info:
description: Returns a list of dictionaries of all domains associated with the supplied account ID. description: Returns a list of dictionaries of all domains associated with the supplied account ID.
type: list type: list
elements: dict elements: dict
returned: success when O(name) is not specified returned: success when O(name) is not specified
sample: sample:
- account_id: 1234 - account_id: 1234
created_at: '2021-10-16T21:25:42Z' created_at: '2021-10-16T21:25:42Z'
id: 123456 id: 123456
@ -93,41 +92,41 @@ dnsimple_domain_info:
reverse: false reverse: false
secondary: false secondary: false
updated_at: '2021-11-10T20:22:50Z' updated_at: '2021-11-10T20:22:50Z'
contains: contains:
account_id: account_id:
description: The account ID. description: The account ID.
type: int type: int
created_at: created_at:
description: When the domain entry was created. description: When the domain entry was created.
type: str type: str
id: id:
description: ID of the entry. description: ID of the entry.
type: int type: int
last_transferred_at: last_transferred_at:
description: Date the domain was transferred, or empty if not. description: Date the domain was transferred, or empty if not.
type: str type: str
name: name:
description: Name of the record. description: Name of the record.
type: str type: str
reverse: reverse:
description: Whether or not it is a reverse zone record. description: Whether or not it is a reverse zone record.
type: bool type: bool
updated_at: updated_at:
description: When the domain entry was updated. description: When the domain entry was updated.
type: str type: str
dnsimple_records_info: dnsimple_records_info:
description: Returns a list of dictionaries with all records for the domain supplied. description: Returns a list of dictionaries with all records for the domain supplied.
type: list type: list
elements: dict elements: dict
returned: success when O(name) is specified, but O(record) is not returned: success when O(name) is specified, but O(record) is not
sample: sample:
- content: ns1.dnsimple.com admin.dnsimple.com - content: ns1.dnsimple.com admin.dnsimple.com
created_at: '2021-10-16T19:07:34Z' created_at: '2021-10-16T19:07:34Z'
id: 12345 id: 12345
name: 'catheadbiscuit' name: 'catheadbiscuit'
parent_id: null parent_id:
priority: null priority:
regions: regions:
- global - global
system_record: true system_record: true
@ -135,55 +134,55 @@ dnsimple_records_info:
type: SOA type: SOA
updated_at: '2021-11-15T23:55:51Z' updated_at: '2021-11-15T23:55:51Z'
zone_id: example.com zone_id: example.com
contains: contains:
content: content:
description: Content of the returned record. description: Content of the returned record.
type: str type: str
created_at: created_at:
description: When the domain entry was created. description: When the domain entry was created.
type: str type: str
id: id:
description: ID of the entry. description: ID of the entry.
type: int type: int
name: name:
description: Name of the record. description: Name of the record.
type: str type: str
parent_id: parent_id:
description: Parent record or null. description: Parent record or null.
type: int type: int
priority: priority:
description: Priority setting of the record. description: Priority setting of the record.
type: str type: str
regions: regions:
description: List of regions where the record is available. description: List of regions where the record is available.
type: list type: list
system_record: system_record:
description: Whether or not it is a system record. description: Whether or not it is a system record.
type: bool type: bool
ttl: ttl:
description: Record TTL. description: Record TTL.
type: int type: int
type: type:
description: Record type. description: Record type.
type: str type: str
updated_at: updated_at:
description: When the domain entry was updated. description: When the domain entry was updated.
type: str type: str
zone_id: zone_id:
description: ID of the zone that the record is associated with. description: ID of the zone that the record is associated with.
type: str type: str
dnsimple_record_info: dnsimple_record_info:
description: Returns a list of dictionaries that match the record supplied. description: Returns a list of dictionaries that match the record supplied.
returned: success when O(name) and O(record) are specified returned: success when O(name) and O(record) are specified
type: list type: list
elements: dict elements: dict
sample: sample:
- content: 1.2.3.4 - content: 1.2.3.4
created_at: '2021-11-15T23:55:51Z' created_at: '2021-11-15T23:55:51Z'
id: 123456 id: 123456
name: catheadbiscuit name: catheadbiscuit
parent_id: null parent_id:
priority: null priority:
regions: regions:
- global - global
system_record: false system_record: false
@ -191,44 +190,44 @@ dnsimple_record_info:
type: A type: A
updated_at: '2021-11-15T23:55:51Z' updated_at: '2021-11-15T23:55:51Z'
zone_id: example.com zone_id: example.com
contains: contains:
content: content:
description: Content of the returned record. description: Content of the returned record.
type: str type: str
created_at: created_at:
description: When the domain entry was created. description: When the domain entry was created.
type: str type: str
id: id:
description: ID of the entry. description: ID of the entry.
type: int type: int
name: name:
description: Name of the record. description: Name of the record.
type: str type: str
parent_id: parent_id:
description: Parent record or null. description: Parent record or null.
type: int type: int
priority: priority:
description: Priority setting of the record. description: Priority setting of the record.
type: str type: str
regions: regions:
description: List of regions where the record is available. description: List of regions where the record is available.
type: list type: list
system_record: system_record:
description: Whether or not it is a system record. description: Whether or not it is a system record.
type: bool type: bool
ttl: ttl:
description: Record TTL. description: Record TTL.
type: int type: int
type: type:
description: Record type. description: Record type.
type: str type: str
updated_at: updated_at:
description: When the domain entry was updated. description: When the domain entry was updated.
type: str type: str
zone_id: zone_id:
description: ID of the zone that the record is associated with. description: ID of the zone that the record is associated with.
type: str type: str
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils import deps from ansible_collections.community.general.plugins.module_utils import deps

75
plugins/modules/dnsmadeeasy.py
View File

@ -9,14 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: dnsmadeeasy module: dnsmadeeasy
short_description: Interface with dnsmadeeasy.com (a DNS hosting service) short_description: Interface with dnsmadeeasy.com (a DNS hosting service)
description: description:
- > - 'Manages DNS records using the v2 REST API of the DNS Made Easy service. It handles records only; there is no manipulation
Manages DNS records via the v2 REST API of the DNS Made Easy service. It handles records only; there is no manipulation of domains or of domains or monitor/account support yet. See: U(https://www.dnsmadeeasy.com/integration/restapi/).'
monitor/account support yet. See: U(https://www.dnsmadeeasy.com/integration/restapi/)
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -39,8 +37,8 @@ options:
domain: domain:
description: description:
- Domain to work with. Can be the domain name (e.g. "mydomain.com") or the numeric ID of the domain in DNS Made Easy (e.g. "839989") for faster - Domain to work with. Can be the domain name (for example V(mydomain.com)) or the numeric ID of the domain in DNS Made Easy
resolution (for example V(839989)) for faster resolution.
required: true required: true
type: str type: str
@ -52,49 +50,47 @@ options:
record_name: record_name:
description: description:
- Record name to get/create/delete/update. If record_name is not specified; all records for the domain will be returned in "result" regardless - Record name to get/create/delete/update. If record_name is not specified; all records for the domain will be returned
of the state argument. in "result" regardless of the state argument.
type: str type: str
record_type: record_type:
description: description:
- Record type. - Record type.
choices: [ 'A', 'AAAA', 'CNAME', 'ANAME', 'HTTPRED', 'MX', 'NS', 'PTR', 'SRV', 'TXT' ] choices: ['A', 'AAAA', 'CNAME', 'ANAME', 'HTTPRED', 'MX', 'NS', 'PTR', 'SRV', 'TXT']
type: str type: str
record_value: record_value:
description: description:
- > - 'Record value. HTTPRED: <redirection URL>, MX: <priority> <target name>, NS: <name server>, PTR: <target name>, SRV:
Record value. HTTPRED: <redirection URL>, MX: <priority> <target name>, NS: <name server>, PTR: <target name>, <priority> <weight> <port> <target name>, TXT: <text value>".'
SRV: <priority> <weight> <port> <target name>, TXT: <text value>" - If record_value is not specified; no changes will be made and the record will be returned in 'result' (in other words,
- > this module can be used to fetch a record's current id, type, and ttl).
If record_value is not specified; no changes will be made and the record will be returned in 'result'
(in other words, this module can be used to fetch a record's current id, type, and ttl)
type: str type: str
record_ttl: record_ttl:
description: description:
- record's "Time to live". Number of seconds the record remains cached in DNS servers. - Record's "Time-To-Live". Number of seconds the record remains cached in DNS servers.
default: 1800 default: 1800
type: int type: int
state: state:
description: description:
- whether the record should exist or not - Whether the record should exist or not.
required: true required: true
choices: [ 'present', 'absent' ] choices: ['present', 'absent']
type: str type: str
validate_certs: validate_certs:
description: description:
- If V(false), SSL certificates will not be validated. This should only be used - If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
on personally controlled sites using self-signed certificates. self-signed certificates.
type: bool type: bool
default: true default: true
monitor: monitor:
description: description:
- If V(true), add or change the monitor. This is applicable only for A records. - If V(true), add or change the monitor. This is applicable only for A records.
type: bool type: bool
default: false default: false
@ -153,7 +149,7 @@ options:
failover: failover:
description: description:
- If V(true), add or change the failover. This is applicable only for A records. - If V(true), add or change the failover. This is applicable only for A records.
type: bool type: bool
default: false default: false
@ -192,20 +188,19 @@ options:
type: str type: str
notes: notes:
- The DNS Made Easy service requires that machines interacting with the API have the proper time and timezone set. Be sure you are within a few - The DNS Made Easy service requires that machines interacting with the API have the proper time and timezone set. Be sure
seconds of actual time by using NTP. you are within a few seconds of actual time by using NTP.
- This module returns record(s) and monitor(s) in the "result" element when 'state' is set to 'present'. - This module returns record(s) and monitor(s) in the "result" element when O(state=present). These values can
These values can be be registered and used in your playbooks. be be registered and used in your playbooks.
- Only A records can have a monitor or failover. - Only A records can have a monitor or failover.
- To add failover, the 'failover', 'autoFailover', 'port', 'protocol', 'ip1', and 'ip2' options are required. - To add failover, the O(failover), O(autoFailover), O(port), O(protocol), O(ip1), and O(ip2) options are required.
- To add monitor, the 'monitor', 'port', 'protocol', 'maxEmails', 'systemDescription', and 'ip1' options are required. - To add monitor, the O(monitor), O(port), O(protocol), O(maxEmails), O(systemDescription), and O(ip1) options are required.
- The monitor and the failover will share 'port', 'protocol', and 'ip1' options. - The monitor and the failover will share O(port), O(protocol), and O(ip1) options.
requirements: [hashlib, hmac]
requirements: [ hashlib, hmac ]
author: "Brice Burgess (@briceburg)" author: "Brice Burgess (@briceburg)"
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Fetch my.com domain records - name: Fetch my.com domain records
community.general.dnsmadeeasy: community.general.dnsmadeeasy:
account_key: key account_key: key
@ -291,8 +286,8 @@ EXAMPLES = '''
record_value: 127.0.0.1 record_value: 127.0.0.1
monitor: true monitor: true
ip1: 127.0.0.2 ip1: 127.0.0.2
protocol: HTTP # default protocol: HTTP # default
port: 80 # default port: 80 # default
maxEmails: 1 maxEmails: 1
systemDescription: Monitor Test A record systemDescription: Monitor Test A record
contactList: my contact list contactList: my contact list
@ -308,11 +303,11 @@ EXAMPLES = '''
record_value: 127.0.0.1 record_value: 127.0.0.1
monitor: true monitor: true
ip1: 127.0.0.2 ip1: 127.0.0.2
protocol: HTTP # default protocol: HTTP # default
port: 80 # default port: 80 # default
maxEmails: 1 maxEmails: 1
systemDescription: Monitor Test A record systemDescription: Monitor Test A record
contactList: 1174 # contact list id contactList: 1174 # contact list id
httpFqdn: http://my.com httpFqdn: http://my.com
httpFile: example httpFile: example
httpQueryString: some string httpQueryString: some string
@ -357,7 +352,7 @@ EXAMPLES = '''
record_type: A record_type: A
record_value: 127.0.0.1 record_value: 127.0.0.1
monitor: false monitor: false
''' """
# ============================================ # ============================================
# DNSMadeEasy module specific support methods. # DNSMadeEasy module specific support methods.

68
plugins/modules/dpkg_divert.py
View File

@ -9,24 +9,20 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: dpkg_divert module: dpkg_divert
short_description: Override a debian package's version of a file short_description: Override a debian package's version of a file
version_added: '0.2.0' version_added: '0.2.0'
author: author:
- quidame (@quidame) - quidame (@quidame)
description: description:
- A diversion is for C(dpkg) the knowledge that only a given package - A diversion is for C(dpkg) the knowledge that only a given package (or the local administrator) is allowed to install
(or the local administrator) is allowed to install a file at a given a file at a given location. Other packages shipping their own version of this file will be forced to O(divert) it, that
location. Other packages shipping their own version of this file will is to install it at another location. It allows one to keep changes in a file provided by a debian package by preventing
be forced to O(divert) it, that is to install it at another location. It its overwrite at package upgrade.
allows one to keep changes in a file provided by a debian package by - This module manages diversions of debian packages files using the C(dpkg-divert) commandline tool. It can either create
preventing its overwrite at package upgrade. or remove a diversion for a given file, but also update an existing diversion to modify its O(holder) and/or its O(divert)
- This module manages diversions of debian packages files using the location.
C(dpkg-divert) commandline tool. It can either create or remove a
diversion for a given file, but also update an existing diversion
to modify its O(holder) and/or its O(divert) location.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -37,28 +33,23 @@ attributes:
options: options:
path: path:
description: description:
- The original and absolute path of the file to be diverted or - The original and absolute path of the file to be diverted or undiverted. This path is unique, in other words it is not possible
undiverted. This path is unique, i.e. it is not possible to get to get two diversions for the same O(path).
two diversions for the same O(path).
required: true required: true
type: path type: path
state: state:
description: description:
- When O(state=absent), remove the diversion of the specified - When O(state=absent), remove the diversion of the specified O(path); when O(state=present), create the diversion if
O(path); when O(state=present), create the diversion if it does it does not exist, or update its package O(holder) or O(divert) location, if it already exists.
not exist, or update its package O(holder) or O(divert) location,
if it already exists.
type: str type: str
default: present default: present
choices: [absent, present] choices: [absent, present]
holder: holder:
description: description:
- The name of the package whose copy of file is not diverted, also - The name of the package whose copy of file is not diverted, also known as the diversion holder or the package the
known as the diversion holder or the package the diversion belongs diversion belongs to.
to. - The actual package does not have to be installed or even to exist for its name to be valid. If not specified, the
- The actual package does not have to be installed or even to exist diversion is hold by 'LOCAL', that is reserved by/for dpkg for local diversions.
for its name to be valid. If not specified, the diversion is hold
by 'LOCAL', that is reserved by/for dpkg for local diversions.
- This parameter is ignored when O(state=absent). - This parameter is ignored when O(state=absent).
type: str type: str
divert: divert:
@ -69,28 +60,25 @@ options:
type: path type: path
rename: rename:
description: description:
- Actually move the file aside (when O(state=present)) or back (when - Actually move the file aside (when O(state=present)) or back (when O(state=absent)), but only when changing the state
O(state=absent)), but only when changing the state of the diversion. of the diversion. This parameter has no effect when attempting to add a diversion that already exists or when removing
This parameter has no effect when attempting to add a diversion that an unexisting one.
already exists or when removing an unexisting one. - Unless O(force=true), renaming fails if the destination file already exists (this lock being a dpkg-divert feature,
- Unless O(force=true), renaming fails if the destination file already and bypassing it being a module feature).
exists (this lock being a dpkg-divert feature, and bypassing it being
a module feature).
type: bool type: bool
default: false default: false
force: force:
description: description:
- When O(rename=true) and O(force=true), renaming is performed even if - When O(rename=true) and O(force=true), renaming is performed even if the target of the renaming exists, in other words the existing
the target of the renaming exists, i.e. the existing contents of the contents of the file at this location will be lost.
file at this location will be lost.
- This parameter is ignored when O(rename=false). - This parameter is ignored when O(rename=false).
type: bool type: bool
default: false default: false
requirements: requirements:
- dpkg-divert >= 1.15.0 (Debian family) - dpkg-divert >= 1.15.0 (Debian family)
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Divert /usr/bin/busybox to /usr/bin/busybox.distrib and keep file in place - name: Divert /usr/bin/busybox to /usr/bin/busybox.distrib and keep file in place
community.general.dpkg_divert: community.general.dpkg_divert:
path: /usr/bin/busybox path: /usr/bin/busybox
@ -112,9 +100,9 @@ EXAMPLES = r'''
state: absent state: absent
rename: true rename: true
force: true force: true
''' """
RETURN = r''' RETURN = r"""
commands: commands:
description: The dpkg-divert commands ran internally by the module. description: The dpkg-divert commands ran internally by the module.
type: list type: list
@ -151,7 +139,7 @@ diversion:
"path": "/etc/foobarrc", "path": "/etc/foobarrc",
"state": "present" "state": "present"
} }
''' """
import re import re

46
plugins/modules/easy_install.py
View File

@ -9,14 +9,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: easy_install module: easy_install
short_description: Installs Python libraries short_description: Installs Python libraries
description: description:
- Installs Python libraries, optionally in a C(virtualenv) - Installs Python libraries, optionally in a C(virtualenv).
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
@ -31,31 +30,25 @@ options:
virtualenv: virtualenv:
type: str type: str
description: description:
- An optional O(virtualenv) directory path to install into. If the - An optional O(virtualenv) directory path to install into. If the O(virtualenv) does not exist, it is created automatically.
O(virtualenv) does not exist, it is created automatically.
virtualenv_site_packages: virtualenv_site_packages:
description: description:
- Whether the virtual environment will inherit packages from the - Whether the virtual environment will inherit packages from the global site-packages directory. Note that if this setting
global site-packages directory. Note that if this setting is is changed on an already existing virtual environment it will not have any effect, the environment must be deleted
changed on an already existing virtual environment it will not and newly created.
have any effect, the environment must be deleted and newly
created.
type: bool type: bool
default: false default: false
virtualenv_command: virtualenv_command:
type: str type: str
description: description:
- The command to create the virtual environment with. For example - The command to create the virtual environment with. For example V(pyvenv), V(virtualenv), V(virtualenv2).
V(pyvenv), V(virtualenv), V(virtualenv2).
default: virtualenv default: virtualenv
executable: executable:
type: str type: str
description: description:
- The explicit executable or a pathname to the executable to be used to - The explicit executable or a pathname to the executable to be used to run easy_install for a specific version of Python
run easy_install for a specific version of Python installed in the installed in the system. For example V(easy_install-3.3), if there are both Python 2.7 and 3.3 installations in the
system. For example V(easy_install-3.3), if there are both Python 2.7 system and you want to run easy_install for the Python 3.3 installation.
and 3.3 installations in the system and you want to run easy_install
for the Python 3.3 installation.
default: easy_install default: easy_install
state: state:
type: str type: str
@ -64,17 +57,14 @@ options:
choices: [present, latest] choices: [present, latest]
default: present default: present
notes: notes:
- Please note that the C(easy_install) module can only install Python - Please note that the C(easy_install) module can only install Python libraries. Thus this module is not able to remove
libraries. Thus this module is not able to remove libraries. It is libraries. It is generally recommended to use the M(ansible.builtin.pip) module which you can first install using M(community.general.easy_install).
generally recommended to use the M(ansible.builtin.pip) module which you can first install - Also note that C(virtualenv) must be installed on the remote host if the O(virtualenv) parameter is specified.
using M(community.general.easy_install). requirements: ["virtualenv"]
- Also note that C(virtualenv) must be installed on the remote host if the
O(virtualenv) parameter is specified.
requirements: [ "virtualenv" ]
author: "Matt Wright (@mattupstate)" author: "Matt Wright (@mattupstate)"
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Install or update pip - name: Install or update pip
community.general.easy_install: community.general.easy_install:
name: pip name: pip
@ -84,7 +74,7 @@ EXAMPLES = '''
community.general.easy_install: community.general.easy_install:
name: bottle name: bottle
virtualenv: /webapps/myapp/venv virtualenv: /webapps/myapp/venv
''' """
import os import os
import os.path import os.path

73
plugins/modules/ejabberd_user.py
View File

@ -9,51 +9,50 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: ejabberd_user module: ejabberd_user
author: "Peter Sprygada (@privateip)" author: "Peter Sprygada (@privateip)"
short_description: Manages users for ejabberd servers short_description: Manages users for ejabberd servers
requirements: requirements:
- ejabberd with mod_admin_extra - ejabberd with mod_admin_extra
description: description:
- This module provides user management for ejabberd servers - This module provides user management for ejabberd servers.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
diff_mode: diff_mode:
support: none support: none
options: options:
username: username:
type: str type: str
description: description:
- the name of the user to manage - The name of the user to manage.
required: true required: true
host: host:
type: str type: str
description: description:
- the ejabberd host associated with this username - The ejabberd host associated with this username.
required: true required: true
password: password:
type: str type: str
description: description:
- the password to assign to the username - The password to assign to the username.
required: false required: false
state: state:
type: str type: str
description: description:
- describe the desired state of the user to be managed - Describe the desired state of the user to be managed.
required: false required: false
default: 'present' default: 'present'
choices: [ 'present', 'absent' ] choices: ['present', 'absent']
notes: notes:
- Password parameter is required for state == present only - Password parameter is required for O(state=present) only.
- Passwords must be stored in clear text for this release - Passwords must be stored in clear text for this release.
- The ejabberd configuration file must include mod_admin_extra as a module. - The ejabberd configuration file must include mod_admin_extra as a module.
''' """
EXAMPLES = ''' EXAMPLES = r"""
# Example playbook entries using the ejabberd_user module to manage users state. # Example playbook entries using the ejabberd_user module to manage users state.
- name: Create a user if it does not exist - name: Create a user if it does not exist
@ -67,7 +66,7 @@ EXAMPLES = '''
username: test username: test
host: server host: server
state: absent state: absent
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt

147
plugins/modules/elasticsearch_plugin.py
View File

@ -9,88 +9,85 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: elasticsearch_plugin module: elasticsearch_plugin
short_description: Manage Elasticsearch plugins short_description: Manage Elasticsearch plugins
description: description:
- Manages Elasticsearch plugins. - Manages Elasticsearch plugins.
author: author:
- Mathew Davies (@ThePixelDeveloper) - Mathew Davies (@ThePixelDeveloper)
- Sam Doran (@samdoran) - Sam Doran (@samdoran)
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
diff_mode: diff_mode:
support: none support: none
options: options:
name: name:
description: description:
- Name of the plugin to install. - Name of the plugin to install.
required: true required: true
type: str type: str
state: state:
description: description:
- Desired state of a plugin. - Desired state of a plugin.
choices: ["present", "absent"] choices: ["present", "absent"]
default: present default: present
type: str type: str
src: src:
description: description:
- Optionally set the source location to retrieve the plugin from. This can be a file:// - Optionally set the source location to retrieve the plugin from. This can be a C(file://) URL to install from a local
URL to install from a local file, or a remote URL. If this is not set, the plugin file, or a remote URL. If this is not set, the plugin location is just based on the name.
location is just based on the name. - The name parameter must match the descriptor in the plugin ZIP specified.
- The name parameter must match the descriptor in the plugin ZIP specified. - Is only used if the state would change, which is solely checked based on the name parameter. If, for example, the
- Is only used if the state would change, which is solely checked based on the name plugin is already installed, changing this has no effect.
parameter. If, for example, the plugin is already installed, changing this has no - For ES 1.x use O(url).
effect. required: false
- For ES 1.x use url. type: str
required: false url:
type: str description:
url: - Set exact URL to download the plugin from (Only works for ES 1.x).
description: - For ES 2.x and higher, use src.
- Set exact URL to download the plugin from (Only works for ES 1.x). required: false
- For ES 2.x and higher, use src. type: str
required: false timeout:
type: str description:
timeout: - 'Timeout setting: V(30s), V(1m), V(1h)...'
description: - Only valid for Elasticsearch < 5.0. This option is ignored for Elasticsearch > 5.0.
- "Timeout setting: 30s, 1m, 1h..." default: 1m
- Only valid for Elasticsearch < 5.0. This option is ignored for Elasticsearch > 5.0. type: str
default: 1m force:
type: str description:
force: - Force batch mode when installing plugins. This is only necessary if a plugin requires additional permissions and console
description: detection fails.
- "Force batch mode when installing plugins. This is only necessary if a plugin requires additional permissions and console detection fails." default: false
default: false type: bool
type: bool plugin_bin:
plugin_bin: description:
description: - Location of the plugin binary. If this file is not found, the default plugin binaries will be used.
- Location of the plugin binary. If this file is not found, the default plugin binaries will be used. type: path
type: path plugin_dir:
plugin_dir: description:
description: - Your configured plugin directory specified in Elasticsearch.
- Your configured plugin directory specified in Elasticsearch default: /usr/share/elasticsearch/plugins/
default: /usr/share/elasticsearch/plugins/ type: path
type: path proxy_host:
proxy_host: description:
description: - Proxy host to use during plugin installation.
- Proxy host to use during plugin installation type: str
type: str proxy_port:
proxy_port: description:
description: - Proxy port to use during plugin installation.
- Proxy port to use during plugin installation type: str
type: str version:
version: description:
description: - Version of the plugin to be installed. If plugin exists with previous version, it will NOT be updated.
- Version of the plugin to be installed. type: str
If plugin exists with previous version, it will NOT be updated """
type: str
'''
EXAMPLES = ''' EXAMPLES = r"""
- name: Install Elasticsearch Head plugin in Elasticsearch 2.x - name: Install Elasticsearch Head plugin in Elasticsearch 2.x
community.general.elasticsearch_plugin: community.general.elasticsearch_plugin:
name: mobz/elasticsearch-head name: mobz/elasticsearch-head
@ -116,7 +113,7 @@ EXAMPLES = '''
name: ingest-geoip name: ingest-geoip
state: present state: present
force: true force: true
''' """
import os import os

72
plugins/modules/emc_vnx_sg_member.py
View File

@ -12,52 +12,50 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: emc_vnx_sg_member module: emc_vnx_sg_member
short_description: Manage storage group member on EMC VNX short_description: Manage storage group member on EMC VNX
description: description:
- "This module manages the members of an existing storage group." - This module manages the members of an existing storage group.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.emc.emc_vnx - community.general.emc.emc_vnx
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
diff_mode: diff_mode:
support: none support: none
options: options:
name: name:
description: description:
- Name of the Storage group to manage. - Name of the Storage group to manage.
required: true required: true
type: str type: str
lunid: lunid:
description: description:
- Lun id to be added. - Lun id to be added.
required: true required: true
type: int type: int
state: state:
description: description:
- Indicates the desired lunid state. - Indicates the desired lunid state.
- V(present) ensures specified lunid is present in the Storage Group. - V(present) ensures specified O(lunid) is present in the Storage Group.
- V(absent) ensures specified lunid is absent from Storage Group. - V(absent) ensures specified O(lunid) is absent from Storage Group.
default: present default: present
choices: [ "present", "absent"] choices: ["present", "absent"]
type: str type: str
author: author:
- Luca 'remix_tj' Lorenzetto (@remixtj) - Luca 'remix_tj' Lorenzetto (@remixtj)
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Add lun to storage group - name: Add lun to storage group
community.general.emc_vnx_sg_member: community.general.emc_vnx_sg_member:
name: sg01 name: sg01
@ -75,14 +73,14 @@ EXAMPLES = '''
sp_password: sysadmin sp_password: sysadmin
lunid: 100 lunid: 100
state: absent state: absent
''' """
RETURN = ''' RETURN = r"""
hluid: hluid:
description: LUNID that hosts attached to the storage group will see. description: LUNID that hosts attached to the storage group will see.
type: int type: int
returned: success returned: success
''' """
import traceback import traceback

147
plugins/modules/etcd3.py
View File

@ -9,84 +9,83 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: etcd3 module: etcd3
short_description: Set or delete key value pairs from an etcd3 cluster short_description: Set or delete key value pairs from an etcd3 cluster
requirements: requirements:
- etcd3 - etcd3
description: description:
- Sets or deletes values in etcd3 cluster using its v3 api. - Sets or deletes values in etcd3 cluster using its v3 api.
- Needs python etcd3 lib to work - Needs python etcd3 lib to work.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
diff_mode: diff_mode:
support: none support: none
options: options:
key: key:
type: str type: str
description: description:
- the key where the information is stored in the cluster - The key where the information is stored in the cluster.
required: true required: true
value: value:
type: str type: str
description: description:
- the information stored - The information stored.
required: true required: true
host: host:
type: str type: str
description: description:
- the IP address of the cluster - The IP address of the cluster.
default: 'localhost' default: 'localhost'
port: port:
type: int type: int
description: description:
- the port number used to connect to the cluster - The port number used to connect to the cluster.
default: 2379 default: 2379
state: state:
type: str type: str
description: description:
- the state of the value for the key. - The state of the value for the key.
- can be present or absent - Can be present or absent.
required: true required: true
choices: [ present, absent ] choices: [present, absent]
user: user:
type: str type: str
description: description:
- The etcd user to authenticate with. - The etcd user to authenticate with.
password: password:
type: str type: str
description: description:
- The password to use for authentication. - The password to use for authentication.
- Required if O(user) is defined. - Required if O(user) is defined.
ca_cert: ca_cert:
type: path type: path
description: description:
- The Certificate Authority to use to verify the etcd host. - The Certificate Authority to use to verify the etcd host.
- Required if O(client_cert) and O(client_key) are defined. - Required if O(client_cert) and O(client_key) are defined.
client_cert: client_cert:
type: path type: path
description: description:
- PEM formatted certificate chain file to be used for SSL client authentication. - PEM formatted certificate chain file to be used for SSL client authentication.
- Required if O(client_key) is defined. - Required if O(client_key) is defined.
client_key: client_key:
type: path type: path
description: description:
- PEM formatted file that contains your private key to be used for SSL client authentication. - PEM formatted file that contains your private key to be used for SSL client authentication.
- Required if O(client_cert) is defined. - Required if O(client_cert) is defined.
timeout: timeout:
type: int type: int
description: description:
- The socket level timeout in seconds. - The socket level timeout in seconds.
author: author:
- Jean-Philippe Evrard (@evrardjp) - Jean-Philippe Evrard (@evrardjp)
- Victor Fauth (@vfauth) - Victor Fauth (@vfauth)
''' """
EXAMPLES = """ EXAMPLES = r"""
- name: Store a value "bar" under the key "foo" for a cluster located "http://localhost:2379" - name: Store a value "bar" under the key "foo" for a cluster located "http://localhost:2379"
community.general.etcd3: community.general.etcd3:
key: "foo" key: "foo"
@ -114,16 +113,16 @@ EXAMPLES = """
client_key: "/etc/ssl/private/key.pem" client_key: "/etc/ssl/private/key.pem"
""" """
RETURN = ''' RETURN = r"""
key: key:
description: The key that was queried description: The key that was queried.
returned: always returned: always
type: str type: str
old_value: old_value:
description: The previous value in the cluster description: The previous value in the cluster.
returned: always returned: always
type: str type: str
''' """
import traceback import traceback

50
plugins/modules/facter.py
View File

@ -8,36 +8,34 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: facter module: facter
short_description: Runs the discovery program C(facter) on the remote system short_description: Runs the discovery program C(facter) on the remote system
description: description:
- Runs the C(facter) discovery program - Runs the C(facter) discovery program (U(https://github.com/puppetlabs/facter)) on the remote system, returning JSON data
(U(https://github.com/puppetlabs/facter)) on the remote system, returning that can be useful for inventory purposes.
JSON data that can be useful for inventory purposes.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
diff_mode: diff_mode:
support: none support: none
options: options:
arguments: arguments:
description: description:
- Specifies arguments for facter. - Specifies arguments for facter.
type: list type: list
elements: str elements: str
requirements: requirements:
- facter - facter
- ruby-json - ruby-json
author: author:
- Ansible Core Team - Ansible Core Team
- Michael DeHaan - Michael DeHaan
''' """
EXAMPLES = ''' EXAMPLES = r"""
# Example command-line invocation # Example command-line invocation
# ansible www.example.net -m facter # ansible www.example.net -m facter
@ -47,11 +45,11 @@ EXAMPLES = '''
- name: Execute facter with arguments - name: Execute facter with arguments
community.general.facter: community.general.facter:
arguments: arguments:
- -p - -p
- system_uptime - system_uptime
- timezone - timezone
- is_virtual - is_virtual
''' """
import json import json
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

50
plugins/modules/facter_facts.py
View File

@ -9,47 +9,45 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: facter_facts module: facter_facts
short_description: Runs the discovery program C(facter) on the remote system and return Ansible facts short_description: Runs the discovery program C(facter) on the remote system and return Ansible facts
version_added: 8.0.0 version_added: 8.0.0
description: description:
- Runs the C(facter) discovery program - Runs the C(facter) discovery program (U(https://github.com/puppetlabs/facter)) on the remote system, returning Ansible
(U(https://github.com/puppetlabs/facter)) on the remote system, returning Ansible facts from the facts from the JSON data that can be useful for inventory purposes.
JSON data that can be useful for inventory purposes.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
- community.general.attributes.facts - community.general.attributes.facts
- community.general.attributes.facts_module - community.general.attributes.facts_module
options: options:
arguments: arguments:
description: description:
- Specifies arguments for facter. - Specifies arguments for facter.
type: list type: list
elements: str elements: str
requirements: requirements:
- facter - facter
- ruby-json - ruby-json
author: author:
- Ansible Core Team - Ansible Core Team
- Michael DeHaan - Michael DeHaan
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Execute facter no arguments - name: Execute facter no arguments
community.general.facter_facts: community.general.facter_facts:
- name: Execute facter with arguments - name: Execute facter with arguments
community.general.facter_facts: community.general.facter_facts:
arguments: arguments:
- -p - -p
- system_uptime - system_uptime
- timezone - timezone
- is_virtual - is_virtual
''' """
RETURN = r''' RETURN = r"""
ansible_facts: ansible_facts:
description: Dictionary with one key C(facter). description: Dictionary with one key C(facter).
returned: always returned: always
@ -59,7 +57,7 @@ ansible_facts:
description: Dictionary containing facts discovered in the remote system. description: Dictionary containing facts discovered in the remote system.
returned: always returned: always
type: dict type: dict
''' """
import json import json

68
plugins/modules/filesize.py
View File

@ -9,17 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: filesize module: filesize
short_description: Create a file with a given size, or resize it if it exists short_description: Create a file with a given size, or resize it if it exists
description: description:
- This module is a simple wrapper around C(dd) to create, extend or truncate - This module is a simple wrapper around C(dd) to create, extend or truncate a file, given its size. It can be used to manage
a file, given its size. It can be used to manage swap files (that require swap files (that require contiguous blocks) or alternatively, huge sparse files.
contiguous blocks) or alternatively, huge sparse files.
author: author:
- quidame (@quidame) - quidame (@quidame)
@ -40,36 +37,27 @@ options:
size: size:
description: description:
- Requested size of the file. - Requested size of the file.
- The value is a number (either C(int) or C(float)) optionally followed - The value is a number (either C(int) or C(float)) optionally followed by a multiplicative suffix, that can be one
by a multiplicative suffix, that can be one of V(B) (bytes), V(KB) or of V(B) (bytes), V(KB) or V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB), and so on for V(T),
V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB), V(P), V(E), V(Z) and V(Y); or alternatively one of V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB);
and so on for V(T), V(P), V(E), V(Z) and V(Y); or alternatively one of
V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB);
V(G), V(g) or V(GiB) (= 1024MiB); and so on. V(G), V(g) or V(GiB) (= 1024MiB); and so on.
- If the multiplicative suffix is not provided, the value is treated as - If the multiplicative suffix is not provided, the value is treated as an integer number of blocks of O(blocksize)
an integer number of blocks of O(blocksize) bytes each (float values bytes each (float values are rounded to the closest integer).
are rounded to the closest integer).
- When the O(size) value is equal to the current file size, does nothing. - When the O(size) value is equal to the current file size, does nothing.
- When the O(size) value is bigger than the current file size, bytes from - When the O(size) value is bigger than the current file size, bytes from O(source) (if O(sparse) is not V(false)) are
O(source) (if O(sparse) is not V(false)) are appended to the file appended to the file without truncating it, in other words, without modifying the existing bytes of the file.
without truncating it, in other words, without modifying the existing - When the O(size) value is smaller than the current file size, it is truncated to the requested value without modifying
bytes of the file. bytes before this value.
- When the O(size) value is smaller than the current file size, it is - That means that a file of any arbitrary size can be grown to any other arbitrary size, and then resized down to its
truncated to the requested value without modifying bytes before this initial size without modifying its initial content.
value.
- That means that a file of any arbitrary size can be grown to any other
arbitrary size, and then resized down to its initial size without
modifying its initial content.
type: raw type: raw
required: true required: true
blocksize: blocksize:
description: description:
- Size of blocks, in bytes if not followed by a multiplicative suffix. - Size of blocks, in bytes if not followed by a multiplicative suffix.
- The numeric value (before the unit) B(MUST) be an integer (or a C(float) - The numeric value (before the unit) B(MUST) be an integer (or a C(float) if it equals an integer).
if it equals an integer). - If not set, the size of blocks is guessed from the OS and commonly results in V(512) or V(4096) bytes, that is used
- If not set, the size of blocks is guessed from the OS and commonly internally by the module or when O(size) has no unit.
results in V(512) or V(4096) bytes, that is used internally by the
module or when O(size) has no unit.
type: raw type: raw
source: source:
description: description:
@ -79,26 +67,22 @@ options:
default: /dev/zero default: /dev/zero
force: force:
description: description:
- Whether or not to overwrite the file if it exists, in other words, to - Whether or not to overwrite the file if it exists, in other words, to truncate it from 0. When V(true), the module
truncate it from 0. When V(true), the module is not idempotent, that is not idempotent, that means it always reports C(changed=true).
means it always reports C(changed=true).
- O(force=true) and O(sparse=true) are mutually exclusive. - O(force=true) and O(sparse=true) are mutually exclusive.
type: bool type: bool
default: false default: false
sparse: sparse:
description: description:
- Whether or not the file to create should be a sparse file. - Whether or not the file to create should be a sparse file.
- This option is effective only on newly created files, or when growing a - This option is effective only on newly created files, or when growing a file, only for the bytes to append.
file, only for the bytes to append.
- This option is not supported on OSes or filesystems not supporting sparse files. - This option is not supported on OSes or filesystems not supporting sparse files.
- O(force=true) and O(sparse=true) are mutually exclusive. - O(force=true) and O(sparse=true) are mutually exclusive.
type: bool type: bool
default: false default: false
unsafe_writes: unsafe_writes:
description: description:
- This option is silently ignored. This module always modifies file - This option is silently ignored. This module always modifies file size in-place.
size in-place.
requirements: requirements:
- dd (Data Duplicator) in PATH - dd (Data Duplicator) in PATH
@ -138,9 +122,9 @@ seealso:
- name: busybox(1) manpage for Linux - name: busybox(1) manpage for Linux
description: Manual page of the GNU/Linux's busybox, that provides its own dd implementation. description: Manual page of the GNU/Linux's busybox, that provides its own dd implementation.
link: https://www.unix.com/man-page/linux/1/busybox link: https://www.unix.com/man-page/linux/1/busybox
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Create a file of 1G filled with null bytes - name: Create a file of 1G filled with null bytes
community.general.filesize: community.general.filesize:
path: /var/bigfile path: /var/bigfile
@ -183,9 +167,9 @@ EXAMPLES = r'''
mode: u=rw,go= mode: u=rw,go=
owner: root owner: root
group: root group: root
''' """
RETURN = r''' RETURN = r"""
cmd: cmd:
description: Command executed to create or resize the file. description: Command executed to create or resize the file.
type: str type: str
@ -229,7 +213,7 @@ path:
type: str type: str
sample: /var/swap0 sample: /var/swap0
returned: always returned: always
''' """
import re import re

76
plugins/modules/filesystem.py
View File

@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
author: author:
- Alexander Bulimov (@abulimov) - Alexander Bulimov (@abulimov)
- quidame (@quidame) - quidame (@quidame)
@ -29,33 +28,29 @@ attributes:
options: options:
state: state:
description: description:
- If O(state=present), the filesystem is created if it doesn't already - If O(state=present), the filesystem is created if it does not already exist, that is the default behaviour if O(state)
exist, that is the default behaviour if O(state) is omitted. is omitted.
- If O(state=absent), filesystem signatures on O(dev) are wiped if it - If O(state=absent), filesystem signatures on O(dev) are wiped if it contains a filesystem (as known by C(blkid)).
contains a filesystem (as known by C(blkid)). - When O(state=absent), all other options but O(dev) are ignored, and the module does not fail if the device O(dev)
- When O(state=absent), all other options but O(dev) are ignored, and the does not actually exist.
module does not fail if the device O(dev) doesn't actually exist.
type: str type: str
choices: [ present, absent ] choices: [present, absent]
default: present default: present
version_added: 1.3.0 version_added: 1.3.0
fstype: fstype:
choices: [ bcachefs, btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs ] choices: [bcachefs, btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs]
description: description:
- Filesystem type to be created. This option is required with - Filesystem type to be created. This option is required with O(state=present) (or if O(state) is omitted).
O(state=present) (or if O(state) is omitted). - Ufs support has been added in community.general 3.4.0.
- ufs support has been added in community.general 3.4.0. - Bcachefs support has been added in community.general 8.6.0.
- bcachefs support has been added in community.general 8.6.0.
type: str type: str
aliases: [type] aliases: [type]
dev: dev:
description: description:
- Target path to block device (Linux) or character device (FreeBSD) or - Target path to block device (Linux) or character device (FreeBSD) or regular file (both).
regular file (both). - When setting Linux-specific filesystem types on FreeBSD, this module only works when applying to regular files, aka
- When setting Linux-specific filesystem types on FreeBSD, this module disk images.
only works when applying to regular files, aka disk images. - Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support a regular file as their target O(dev).
- Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support
a regular file as their target O(dev).
- Support for character devices on FreeBSD has been added in community.general 3.4.0. - Support for character devices on FreeBSD has been added in community.general 3.4.0.
type: path type: path
required: true required: true
@ -68,12 +63,11 @@ options:
resizefs: resizefs:
description: description:
- If V(true), if the block device and filesystem size differ, grow the filesystem into the space. - If V(true), if the block device and filesystem size differ, grow the filesystem into the space.
- Supported for C(bcachefs), C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat) filesystems. - Supported for C(bcachefs), C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat)
Attempts to resize other filesystem types will fail. filesystems. Attempts to resize other filesystem types will fail.
- XFS Will only grow if mounted. Currently, the module is based on commands - XFS Will only grow if mounted. Currently, the module is based on commands from C(util-linux) package to perform operations,
from C(util-linux) package to perform operations, so resizing of XFS is so resizing of XFS is not supported on FreeBSD systems.
not supported on FreeBSD systems. - VFAT will likely fail if C(fatresize < 1.04).
- vFAT will likely fail if C(fatresize < 1.04).
- Mutually exclusive with O(uuid). - Mutually exclusive with O(uuid).
type: bool type: bool
default: false default: false
@ -93,32 +87,28 @@ options:
type: str type: str
version_added: 7.1.0 version_added: 7.1.0
requirements: requirements:
- Uses specific tools related to the O(fstype) for creating or resizing a - Uses specific tools related to the O(fstype) for creating or resizing a filesystem (from packages e2fsprogs, xfsprogs,
filesystem (from packages e2fsprogs, xfsprogs, dosfstools, and so on). dosfstools, and so on).
- Uses generic tools mostly related to the Operating System (Linux or - Uses generic tools mostly related to the Operating System (Linux or FreeBSD) or available on both, as C(blkid).
FreeBSD) or available on both, as C(blkid).
- On FreeBSD, either C(util-linux) or C(e2fsprogs) package is required. - On FreeBSD, either C(util-linux) or C(e2fsprogs) package is required.
notes: notes:
- Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid) - Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid) is unable to detect a filesystem (and in
is unable to detect a filesystem (and in case C(fstyp) on FreeBSD is also case C(fstyp) on FreeBSD is also unable to detect a filesystem), this filesystem is overwritten even if O(force) is V(false).
unable to detect a filesystem), this filesystem is overwritten even if - On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide a C(blkid) command that is compatible with this
O(force) is V(false). module. However, these packages conflict with each other, and only the C(util-linux) package provides the command required
- On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide to not fail when O(state=absent).
a C(blkid) command that is compatible with this module. However, these
packages conflict with each other, and only the C(util-linux) package
provides the command required to not fail when O(state=absent).
seealso: seealso:
- module: community.general.filesize - module: community.general.filesize
- module: ansible.posix.mount - module: ansible.posix.mount
- name: xfs_admin(8) manpage for Linux - name: xfs_admin(8) manpage for Linux
description: Manual page of the GNU/Linux's xfs_admin implementation description: Manual page of the GNU/Linux's xfs_admin implementation.
link: https://man7.org/linux/man-pages/man8/xfs_admin.8.html link: https://man7.org/linux/man-pages/man8/xfs_admin.8.html
- name: tune2fs(8) manpage for Linux - name: tune2fs(8) manpage for Linux
description: Manual page of the GNU/Linux's tune2fs implementation description: Manual page of the GNU/Linux's tune2fs implementation.
link: https://man7.org/linux/man-pages/man8/tune2fs.8.html link: https://man7.org/linux/man-pages/man8/tune2fs.8.html
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Create a ext2 filesystem on /dev/sdb1 - name: Create a ext2 filesystem on /dev/sdb1
community.general.filesystem: community.general.filesystem:
fstype: ext2 fstype: ext2
@ -157,7 +147,7 @@ EXAMPLES = '''
fstype: lvm fstype: lvm
dev: /dev/sdc dev: /dev/sdc
uuid: random uuid: random
''' """
import os import os
import platform import platform

81
plugins/modules/flatpak.py
View File

@ -10,8 +10,7 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: flatpak module: flatpak
short_description: Manage flatpaks short_description: Manage flatpaks
description: description:
@ -34,66 +33,60 @@ attributes:
options: options:
executable: executable:
description: description:
- The path to the C(flatpak) executable to use. - The path to the C(flatpak) executable to use.
- By default, this module looks for the C(flatpak) executable on the path. - By default, this module looks for the C(flatpak) executable on the path.
type: path type: path
default: flatpak default: flatpak
method: method:
description: description:
- The installation method to use. - The installation method to use.
- Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) or only for the current V(user).
or only for the current V(user).
type: str type: str
choices: [ system, user ] choices: [system, user]
default: system default: system
name: name:
description: description:
- The name of the flatpak to manage. To operate on several packages this - The name of the flatpak to manage. To operate on several packages this can accept a list of packages.
can accept a list of packages. - When used with O(state=present), O(name) can be specified as a URL to a C(flatpakref) file or the unique reverse DNS
- When used with O(state=present), O(name) can be specified as a URL to a name that identifies a flatpak.
C(flatpakref) file or the unique reverse DNS name that identifies a flatpak. - Both C(https://) and C(http://) URLs are supported.
- Both C(https://) and C(http://) URLs are supported. - When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote to look for the flatpak.
- When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote An example for a reverse DNS name is C(org.gnome.gedit).
to look for the flatpak. An example for a reverse DNS name is C(org.gnome.gedit). - When used with O(state=absent) or O(state=latest), it is recommended to specify the name in the reverse DNS format.
- When used with O(state=absent) or O(state=latest), it is recommended to specify the name in - When supplying a URL with O(state=absent) or O(state=latest), the module will try to match the installed flatpak based
the reverse DNS format. on the name of the flatpakref to remove or update it. However, there is no guarantee that the names of the flatpakref
- When supplying a URL with O(state=absent) or O(state=latest), the module will try to match the file and the reverse DNS name of the installed flatpak do match.
installed flatpak based on the name of the flatpakref to remove or update it. However, there
is no guarantee that the names of the flatpakref file and the reverse DNS name of the
installed flatpak do match.
type: list type: list
elements: str elements: str
required: true required: true
no_dependencies: no_dependencies:
description: description:
- If installing runtime dependencies should be omitted or not - If installing runtime dependencies should be omitted or not.
- This parameter is primarily implemented for integration testing this module. - This parameter is primarily implemented for integration testing this module. There might however be some use cases
There might however be some use cases where you would want to have this, like when you are where you would want to have this, like when you are packaging your own flatpaks.
packaging your own flatpaks.
type: bool type: bool
default: false default: false
version_added: 3.2.0 version_added: 3.2.0
remote: remote:
description: description:
- The flatpak remote (repository) to install the flatpak from. - The flatpak remote (repository) to install the flatpak from.
- By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before - By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before you can use this.
you can use this. - See the M(community.general.flatpak_remote) module for managing flatpak remotes.
- See the M(community.general.flatpak_remote) module for managing flatpak remotes.
type: str type: str
default: flathub default: flathub
state: state:
description: description:
- Indicates the desired package state. - Indicates the desired package state.
- The value V(latest) is supported since community.general 8.6.0. - The value V(latest) is supported since community.general 8.6.0.
choices: [ absent, present, latest ] choices: [absent, present, latest]
type: str type: str
default: present default: present
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Install the spotify flatpak - name: Install the spotify flatpak
community.general.flatpak: community.general.flatpak:
name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref
state: present state: present
- name: Install the gedit flatpak package without dependencies (not recommended) - name: Install the gedit flatpak package without dependencies (not recommended)
@ -123,7 +116,7 @@ EXAMPLES = r'''
- name: Update the spotify flatpak - name: Update the spotify flatpak
community.general.flatpak: community.general.flatpak:
name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref
state: latest state: latest
- name: Update the gedit flatpak package without dependencies (not recommended) - name: Update the gedit flatpak package without dependencies (not recommended)
@ -164,35 +157,35 @@ EXAMPLES = r'''
- org.inkscape.Inkscape - org.inkscape.Inkscape
- org.mozilla.firefox - org.mozilla.firefox
state: absent state: absent
''' """
RETURN = r''' RETURN = r"""
command: command:
description: The exact flatpak command that was executed description: The exact flatpak command that was executed.
returned: When a flatpak command has been executed returned: When a flatpak command has been executed
type: str type: str
sample: "/usr/bin/flatpak install --user --nontinteractive flathub org.gnome.Calculator" sample: "/usr/bin/flatpak install --user --nontinteractive flathub org.gnome.Calculator"
msg: msg:
description: Module error message description: Module error message.
returned: failure returned: failure
type: str type: str
sample: "Executable '/usr/local/bin/flatpak' was not found on the system." sample: "Executable '/usr/local/bin/flatpak' was not found on the system."
rc: rc:
description: Return code from flatpak binary description: Return code from flatpak binary.
returned: When a flatpak command has been executed returned: When a flatpak command has been executed
type: int type: int
sample: 0 sample: 0
stderr: stderr:
description: Error output from flatpak binary description: Error output from flatpak binary.
returned: When a flatpak command has been executed returned: When a flatpak command has been executed
type: str type: str
sample: "error: Error searching remote flathub: Can't find ref org.gnome.KDE" sample: "error: Error searching remote flathub: Can't find ref org.gnome.KDE"
stdout: stdout:
description: Output from flatpak binary description: Output from flatpak binary.
returned: When a flatpak command has been executed returned: When a flatpak command has been executed
type: str type: str
sample: "org.gnome.Calendar/x86_64/stable\tcurrent\norg.gnome.gitg/x86_64/stable\tcurrent\n" sample: "org.gnome.Calendar/x86_64/stable\tcurrent\norg.gnome.gitg/x86_64/stable\tcurrent\n"
''' """
from ansible.module_utils.six.moves.urllib.parse import urlparse from ansible.module_utils.six.moves.urllib.parse import urlparse
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

62
plugins/modules/flatpak_remote.py
View File

@ -10,15 +10,13 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: flatpak_remote module: flatpak_remote
short_description: Manage flatpak repository remotes short_description: Manage flatpak repository remotes
description: description:
- Allows users to add or remove flatpak remotes. - Allows users to add or remove flatpak remotes.
- The flatpak remotes concept is comparable to what is called repositories in other packaging - The flatpak remotes concept is comparable to what is called repositories in other packaging formats.
formats. - Currently, remote addition is only supported using C(flatpakrepo) file URLs.
- Currently, remote addition is only supported via C(flatpakrepo) file URLs.
- Existing remotes will not be updated. - Existing remotes will not be updated.
- See the M(community.general.flatpak) module for managing flatpaks. - See the M(community.general.flatpak) module for managing flatpaks.
author: author:
@ -36,49 +34,47 @@ attributes:
options: options:
executable: executable:
description: description:
- The path to the C(flatpak) executable to use. - The path to the C(flatpak) executable to use.
- By default, this module looks for the C(flatpak) executable on the path. - By default, this module looks for the C(flatpak) executable on the path.
type: str type: str
default: flatpak default: flatpak
flatpakrepo_url: flatpakrepo_url:
description: description:
- The URL to the C(flatpakrepo) file representing the repository remote to add. - The URL to the C(flatpakrepo) file representing the repository remote to add.
- When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url) - When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url) is added using the specified
is added using the specified installation O(method). installation O(method).
- When used with O(state=absent), this is not required. - When used with O(state=absent), this is not required.
- Required when O(state=present). - Required when O(state=present).
type: str type: str
method: method:
description: description:
- The installation method to use. - The installation method to use.
- Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) - Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) or only for the current V(user).
or only for the current V(user).
type: str type: str
choices: [ system, user ] choices: [system, user]
default: system default: system
name: name:
description: description:
- The desired name for the flatpak remote to be registered under on the managed host. - The desired name for the flatpak remote to be registered under on the managed host.
- When used with O(state=present), the remote will be added to the managed host under - When used with O(state=present), the remote will be added to the managed host under the specified O(name).
the specified O(name). - When used with O(state=absent) the remote with that name will be removed.
- When used with O(state=absent) the remote with that name will be removed.
type: str type: str
required: true required: true
state: state:
description: description:
- Indicates the desired package state. - Indicates the desired package state.
type: str type: str
choices: [ absent, present ] choices: [absent, present]
default: present default: present
enabled: enabled:
description: description:
- Indicates whether this remote is enabled. - Indicates whether this remote is enabled.
type: bool type: bool
default: true default: true
version_added: 6.4.0 version_added: 6.4.0
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Add the Gnome flatpak remote to the system installation - name: Add the Gnome flatpak remote to the system installation
community.general.flatpak_remote: community.general.flatpak_remote:
name: gnome name: gnome
@ -108,35 +104,35 @@ EXAMPLES = r'''
name: flathub name: flathub
state: present state: present
enabled: false enabled: false
''' """
RETURN = r''' RETURN = r"""
command: command:
description: The exact flatpak command that was executed description: The exact flatpak command that was executed.
returned: When a flatpak command has been executed returned: When a flatpak command has been executed
type: str type: str
sample: "/usr/bin/flatpak remote-add --system flatpak-test https://dl.flathub.org/repo/flathub.flatpakrepo" sample: "/usr/bin/flatpak remote-add --system flatpak-test https://dl.flathub.org/repo/flathub.flatpakrepo"
msg: msg:
description: Module error message description: Module error message.
returned: failure returned: failure
type: str type: str
sample: "Executable '/usr/local/bin/flatpak' was not found on the system." sample: "Executable '/usr/local/bin/flatpak' was not found on the system."
rc: rc:
description: Return code from flatpak binary description: Return code from flatpak binary.
returned: When a flatpak command has been executed returned: When a flatpak command has been executed
type: int type: int
sample: 0 sample: 0
stderr: stderr:
description: Error output from flatpak binary description: Error output from flatpak binary.
returned: When a flatpak command has been executed returned: When a flatpak command has been executed
type: str type: str
sample: "error: GPG verification enabled, but no summary found (check that the configured URL in remote config is correct)\n" sample: "error: GPG verification enabled, but no summary found (check that the configured URL in remote config is correct)\n"
stdout: stdout:
description: Output from flatpak binary description: Output from flatpak binary.
returned: When a flatpak command has been executed returned: When a flatpak command has been executed
type: str type: str
sample: "flathub\tFlathub\thttps://dl.flathub.org/repo/\t1\t\n" sample: "flathub\tFlathub\thttps://dl.flathub.org/repo/\t1\t\n"
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_bytes, to_native from ansible.module_utils.common.text.converters import to_bytes, to_native