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

l*.py: normalize docs (#9390)

pull/9101/merge
Alexei Znamensky 2024-12-26 21:12:05 +13:00 committed by GitHub
parent 6b7ea3443d
commit cea6eeef37
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
25 changed files with 1194 additions and 1350 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
plugins/modules/launchd.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: launchd
author:
- Martin Migasiewicz (@martinm82)
@ -38,39 +37,34 @@ options:
version_added: 10.1.0
state:
description:
- V(started)/V(stopped) are idempotent actions that will not run
commands unless necessary.
- Launchd does not support V(restarted) nor V(reloaded) natively.
These will trigger a stop/start (restarted) or an unload/load
(reloaded).
- V(restarted) unloads and loads the service before start to ensure
that the latest job definition (plist) is used.
- V(reloaded) unloads and loads the service to ensure that the latest
job definition (plist) is used. Whether a service is started or
stopped depends on the content of the definition file.
- V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
- Launchd does not support V(restarted) nor V(reloaded) natively. These will trigger a stop/start (restarted) or an unload/load (reloaded).
- V(restarted) unloads and loads the service before start to ensure that the latest job definition (plist) is used.
- V(reloaded) unloads and loads the service to ensure that the latest job definition (plist) is used. Whether a service is started or stopped
depends on the content of the definition file.
type: str
choices: [reloaded, restarted, started, stopped, unloaded]
enabled:
description:
- Whether the service should start on boot.
- B(At least one of state and enabled are required.)
- B(At least one of state and enabled are required).
type: bool
force_stop:
description:
- Whether the service should not be restarted automatically by launchd.
- Services might have the 'KeepAlive' attribute set to true in a launchd configuration.
In case this is set to true, stopping a service will cause that launchd starts the service again.
- Set this option to V(true) to let this module change the 'KeepAlive' attribute to V(false).
- Services might have the 'KeepAlive' attribute set to true in a launchd configuration. In case this is set to true, stopping a service
will cause that launchd starts the service again.
- Set this option to V(true) to let this module change the C(KeepAlive) attribute to V(false).
type: bool
default: false
notes:
- A user must privileged to manage services using this module.
requirements:
- A system managed by launchd
- The plistlib python library
'''
- The plistlib Python library
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Make sure spotify webhelper is started
community.general.launchd:
name: com.spotify.webhelper
@ -112,11 +106,11 @@ EXAMPLES = r'''
name: com.openssh.sshd
plist: ssh.plist
state: restarted
'''
"""
RETURN = r'''
RETURN = r"""
status:
description: Metadata about service status
description: Metadata about service status.
returned: always
type: dict
sample:
@ -126,7 +120,7 @@ status:
"previous_pid": "82636",
"previous_state": "running"
}
'''
"""
import os
import plistlib

26
plugins/modules/layman.py
View File

@ -10,14 +10,13 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: layman
author: "Jakub Jirutka (@jirutka)"
short_description: Manage Gentoo overlays
description:
- Uses Layman to manage an additional repositories for the Portage package manager on Gentoo Linux.
Please note that Layman must be installed on a managed node prior using this module.
- Uses Layman to manage an additional repositories for the Portage package manager on Gentoo Linux. Please note that Layman must be installed
on a managed node prior using this module.
requirements:
- layman python module
extends_documentation_fragment:
@ -30,15 +29,13 @@ attributes:
options:
name:
description:
- The overlay id to install, synchronize, or uninstall.
Use 'ALL' to sync all of the installed overlays (can be used only when O(state=updated)).
- The overlay id to install, synchronize, or uninstall. Use V(ALL) to sync all of the installed overlays (can be used only when O(state=updated)).
required: true
type: str
list_url:
description:
- An URL of the alternative overlays list that defines the overlay to install.
This list will be fetched and saved under C(${overlay_defs}/${name}.xml), where
C(overlay_defs) is read from the Layman's configuration.
- An URL of the alternative overlays list that defines the overlay to install. This list will be fetched and saved under C(${overlay_defs}/${name}.xml),
where C(overlay_defs) is read from the Layman's configuration.
aliases: [url]
type: str
state:
@ -49,14 +46,13 @@ options:
type: str
validate_certs:
description:
- If V(false), SSL certificates will not be validated. This should only be
set to V(false) when no other option exists. Prior to 1.9.3 the code
defaulted to V(false).
- If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists. Prior to 1.9.3 the
code defaulted to V(false).
type: bool
default: true
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Install the overlay mozilla which is on the central overlays list
community.general.layman:
name: mozilla
@ -81,7 +77,7 @@ EXAMPLES = '''
community.general.layman:
name: cvut
state: absent
'''
"""
import shutil
import traceback

18
plugins/modules/lbu.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: lbu
short_description: Local Backup Utility for Alpine Linux
@ -17,8 +16,7 @@ short_description: Local Backup Utility for Alpine Linux
version_added: '0.2.0'
description:
- Manage Local Backup Utility of Alpine Linux in run-from-RAM mode
- Manage Local Backup Utility of Alpine Linux in run-from-RAM mode.
extends_documentation_fragment:
- community.general.attributes
@ -46,9 +44,9 @@ options:
author:
- Kaarle Ritvanen (@kunkku)
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# Commit changed files (if any)
- name: Commit
community.general.lbu:
@ -67,14 +65,14 @@ EXAMPLES = '''
include:
- /root/.ssh/authorized_keys
- /var/lib/misc
'''
"""
RETURN = '''
RETURN = r"""
msg:
description: Error message
description: Error message.
type: str
returned: on failure
'''
"""
from ansible.module_utils.basic import AnsibleModule

62
plugins/modules/ldap_attrs.py
View File

@ -12,27 +12,19 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: ldap_attrs
short_description: Add or remove multiple LDAP attribute values
description:
- Add or remove multiple LDAP attribute values.
notes:
- This only deals with attributes on existing entries. To add or remove
whole entries, see M(community.general.ldap_entry).
- The default authentication settings will attempt to use a SASL EXTERNAL
bind over a UNIX domain socket. This works well with the default Ubuntu
install for example, which includes a cn=peercred,cn=external,cn=auth ACL
rule allowing root to modify the server configuration. If you need to use
a simple bind to access your server, pass the credentials in O(bind_dn)
and O(bind_pw).
- For O(state=present) and O(state=absent), all value comparisons are
performed on the server for maximum accuracy. For O(state=exact), values
have to be compared in Python, which obviously ignores LDAP matching
rules. This should work out in most cases, but it is theoretically
possible to see spurious changes when target and actual values are
semantically identical but lexically distinct.
- This only deals with attributes on existing entries. To add or remove whole entries, see M(community.general.ldap_entry).
- The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu
install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you need
to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw).
- For O(state=present) and O(state=absent), all value comparisons are performed on the server for maximum accuracy. For O(state=exact), values
have to be compared in Python, which obviously ignores LDAP matching rules. This should work out in most cases, but it is theoretically possible
to see spurious changes when target and actual values are semantically identical but lexically distinct.
version_added: '0.2.0'
author:
- Jiri Tyr (@jtyr)
@ -53,41 +45,33 @@ options:
choices: [present, absent, exact]
default: present
description:
- The state of the attribute values. If V(present), all given attribute
values will be added if they're missing. If V(absent), all given
attribute values will be removed if present. If V(exact), the set of
attribute values will be forced to exactly those provided and no others.
If O(state=exact) and the attribute value is empty, all values for
this attribute will be removed.
- The state of the attribute values. If V(present), all given attribute values will be added if they are missing. If V(absent), all given
attribute values will be removed if present. If V(exact), the set of attribute values will be forced to exactly those provided and no
others. If O(state=exact) and the attribute value is empty, all values for this attribute will be removed.
attributes:
required: true
type: dict
description:
- The attribute(s) and value(s) to add or remove.
- Each attribute value can be a string for single-valued attributes or
a list of strings for multi-valued attributes.
- If you specify values for this option in YAML, please note that you can improve
readability for long string values by using YAML block modifiers as seen in the
examples for this module.
- Note that when using values that YAML/ansible-core interprets as other types,
like V(yes), V(no) (booleans), or V(2.10) (float), make sure to quote them if
these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
- Each attribute value can be a string for single-valued attributes or a list of strings for multi-valued attributes.
- If you specify values for this option in YAML, please note that you can improve readability for long string values by using YAML block
modifiers as seen in the examples for this module.
- Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10) (float), make
sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
ordered:
required: false
type: bool
default: false
description:
- If V(true), prepend list values with X-ORDERED index numbers in all
attributes specified in the current task. This is useful mostly with
- If V(true), prepend list values with X-ORDERED index numbers in all attributes specified in the current task. This is useful mostly with
C(olcAccess) attribute to easily manage LDAP Access Control Lists.
extends_documentation_fragment:
- community.general.ldap.documentation
- community.general.attributes
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Configure directory number 1 for example.com
community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config
@ -167,17 +151,17 @@ EXAMPLES = r'''
server_uri: ldap://localhost/
bind_dn: cn=admin,dc=example,dc=com
bind_pw: password
'''
"""
RETURN = r'''
RETURN = r"""
modlist:
description: list of modified parameters
description: List of modified parameters.
returned: success
type: list
sample:
- [2, "olcRootDN", ["cn=root,dc=example,dc=com"]]
'''
"""
import traceback

49
plugins/modules/ldap_entry.py
View File

@ -11,21 +11,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: ldap_entry
short_description: Add or remove LDAP entries
description:
- Add or remove LDAP entries. This module only asserts the existence or
non-existence of an LDAP entry, not its attributes. To assert the
attribute values of an entry, see M(community.general.ldap_attrs).
- Add or remove LDAP entries. This module only asserts the existence or non-existence of an LDAP entry, not its attributes. To assert the attribute
values of an entry, see M(community.general.ldap_attrs).
notes:
- The default authentication settings will attempt to use a SASL EXTERNAL
bind over a UNIX domain socket. This works well with the default Ubuntu
install for example, which includes a cn=peercred,cn=external,cn=auth ACL
rule allowing root to modify the server configuration. If you need to use
a simple bind to access your server, pass the credentials in O(bind_dn)
and O(bind_pw).
- The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu
install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you need
to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw).
author:
- Jiri Tyr (@jtyr)
requirements:
@ -38,24 +33,18 @@ attributes:
options:
attributes:
description:
- If O(state=present), attributes necessary to create an entry. Existing
entries are never modified. To assert specific attribute values on an
existing entry, use M(community.general.ldap_attrs) module instead.
- Each attribute value can be a string for single-valued attributes or
a list of strings for multi-valued attributes.
- If you specify values for this option in YAML, please note that you can improve
readability for long string values by using YAML block modifiers as seen in the
examples for this module.
- Note that when using values that YAML/ansible-core interprets as other types,
like V(yes), V(no) (booleans), or V(2.10) (float), make sure to quote them if
these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
- If O(state=present), attributes necessary to create an entry. Existing entries are never modified. To assert specific attribute values
on an existing entry, use M(community.general.ldap_attrs) module instead.
- Each attribute value can be a string for single-valued attributes or a list of strings for multi-valued attributes.
- If you specify values for this option in YAML, please note that you can improve readability for long string values by using YAML block
modifiers as seen in the examples for this module.
- Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10) (float), make
sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
type: dict
default: {}
objectClass:
description:
- If O(state=present), value or list of values to use when creating
the entry. It can either be a string or an actual list of
strings.
- If O(state=present), value or list of values to use when creating the entry. It can either be a string or an actual list of strings.
type: list
elements: str
state:
@ -66,19 +55,17 @@ options:
type: str
recursive:
description:
- If O(state=delete), a flag indicating whether a single entry or the
whole branch must be deleted.
- If O(state=delete), a flag indicating whether a single entry or the whole branch must be deleted.
type: bool
default: false
version_added: 4.6.0
extends_documentation_fragment:
- community.general.ldap.documentation
- community.general.attributes
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Make sure we have a parent entry for users
community.general.ldap_entry:
dn: ou=users,dc=example,dc=com
@ -143,7 +130,7 @@ EXAMPLES = """
"""
RETURN = """
RETURN = r"""
# Default return values
"""

26
plugins/modules/ldap_passwd.py
View File

@ -9,21 +9,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: ldap_passwd
short_description: Set passwords in LDAP
description:
- Set a password for an LDAP entry. This module only asserts that
a given password is valid for a given entry. To assert the
existence of an entry, see M(community.general.ldap_entry).
- Set a password for an LDAP entry. This module only asserts that a given password is valid for a given entry. To assert the existence of an
entry, see M(community.general.ldap_entry).
notes:
- The default authentication settings will attempt to use a SASL EXTERNAL
bind over a UNIX domain socket. This works well with the default Ubuntu
install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL
rule allowing root to modify the server configuration. If you need to use
a simple bind to access your server, pass the credentials in O(bind_dn)
and O(bind_pw).
- The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu
install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you
need to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw).
author:
- Keller Fuchs (@KellerFuchs)
requirements:
@ -41,10 +36,9 @@ options:
extends_documentation_fragment:
- community.general.ldap.documentation
- community.general.attributes
"""
'''
EXAMPLES = """
EXAMPLES = r"""
- name: Set a password for the admin user
community.general.ldap_passwd:
dn: cn=admin,dc=example,dc=com
@ -60,9 +54,9 @@ EXAMPLES = """
admin: "{{ vault_secret }}"
"""
RETURN = """
RETURN = r"""
modlist:
description: list of modified parameters
description: List of modified parameters.
returned: success
type: list
sample:

30
plugins/modules/ldap_search.py
View File

@ -10,19 +10,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r"""
---
module: ldap_search
version_added: '0.2.0'
short_description: Search for entries in a LDAP server
description:
- Return the results of an LDAP search.
notes:
- The default authentication settings will attempt to use a SASL EXTERNAL
bind over a UNIX domain socket. This works well with the default Ubuntu
install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL
rule allowing root to modify the server configuration. If you need to use
a simple bind to access your server, pass the credentials in O(bind_dn)
and O(bind_pw).
- The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu
install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you
need to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw).
author:
- Sebastian Pfahl (@eryx12o45)
requirements:
@ -55,30 +51,26 @@ options:
type: list
elements: str
description:
- A list of attributes for limiting the result. Use an
actual list or a comma-separated string.
- A list of attributes for limiting the result. Use an actual list or a comma-separated string.
schema:
default: false
type: bool
description:
- Set to V(true) to return the full attribute schema of entries, not
their attribute values. Overrides O(attrs) when provided.
- Set to V(true) to return the full attribute schema of entries, not their attribute values. Overrides O(attrs) when provided.
page_size:
default: 0
type: int
description:
- The page size when performing a simple paged result search (RFC 2696).
This setting can be tuned to reduce issues with timeouts and server limits.
- The page size when performing a simple paged result search (RFC 2696). This setting can be tuned to reduce issues with timeouts and server
limits.
- Setting the page size to V(0) (default) disables paged searching.
version_added: 7.1.0
base64_attributes:
description:
- If provided, all attribute values returned that are listed in this option
will be Base64 encoded.
- If the special value V(*) appears in this list, all attributes will be
Base64 encoded.
- All other attribute values will be converted to UTF-8 strings. If they
contain binary data, please note that invalid UTF-8 bytes will be omitted.
- If provided, all attribute values returned that are listed in this option will be Base64 encoded.
- If the special value V(*) appears in this list, all attributes will be Base64 encoded.
- All other attribute values will be converted to UTF-8 strings. If they contain binary data, please note that invalid UTF-8 bytes will
be omitted.
type: list
elements: str
version_added: 7.0.0

37
plugins/modules/librato_annotation.py
View File

@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: librato_annotation
short_description: Create an annotation in librato
description:
- Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created automatically
- Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created automatically.
author: "Seth Edwards (@Sedward)"
requirements: []
extends_documentation_fragment:
@ -28,55 +27,55 @@ options:
user:
type: str
description:
- Librato account username
- Librato account username.
required: true
api_key:
type: str
description:
- Librato account api key
- Librato account api key.
required: true
name:
type: str
description:
- The annotation stream name
- If the annotation stream does not exist, it will be created automatically
- The annotation stream name.
- If the annotation stream does not exist, it will be created automatically.
required: false
title:
type: str
description:
- The title of an annotation is a string and may contain spaces
- The title should be a short, high-level summary of the annotation e.g. v45 Deployment
- The title of an annotation is a string and may contain spaces.
- The title should be a short, high-level summary of the annotation for example V(v45 Deployment).
required: true
source:
type: str
description:
- A string which describes the originating source of an annotation when that annotation is tracked across multiple members of a population
- A string which describes the originating source of an annotation when that annotation is tracked across multiple members of a population.
required: false
description:
type: str
description:
- The description contains extra metadata about a particular annotation
- The description should contain specifics on the individual annotation e.g. Deployed 9b562b2 shipped new feature foo!
- The description contains extra metadata about a particular annotation.
- The description should contain specifics on the individual annotation for example V(Deployed 9b562b2 shipped new feature foo!).
required: false
start_time:
type: int
description:
- The unix timestamp indicating the time at which the event referenced by this annotation started
- The unix timestamp indicating the time at which the event referenced by this annotation started.
required: false
end_time:
type: int
description:
- The unix timestamp indicating the time at which the event referenced by this annotation ended
- For events that have a duration, this is a useful way to annotate the duration of the event
- The unix timestamp indicating the time at which the event referenced by this annotation ended.
- For events that have a duration, this is a useful way to annotate the duration of the event.
required: false
links:
type: list
elements: dict
description:
- See examples
'''
- See examples.
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create a simple annotation event with a source
community.general.librato_annotation:
user: user@example.com
@ -105,7 +104,7 @@ EXAMPLES = '''
description: This is a detailed description of maintenance
start_time: 1395940006
end_time: 1395954406
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url

38
plugins/modules/linode.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: linode
short_description: Manage instances on the Linode Public Cloud
description:
@ -24,7 +23,7 @@ attributes:
options:
state:
description:
- Indicate desired state of the resource
- Indicate desired state of the resource.
choices: [absent, active, deleted, present, restarted, started, stopped]
default: present
type: str
@ -47,10 +46,8 @@ options:
default: ''
linode_id:
description:
- Unique ID of a linode server. This value is read-only in the sense that
if you specify it on creation of a Linode it will not be used. The
Linode API generates these IDs and we can those generated value here to
reference a Linode more specifically. This is useful for idempotence.
- Unique ID of a linode server. This value is read-only in the sense that if you specify it on creation of a Linode it will not be used.
The Linode API generates these IDs and we can those generated value here to reference a Linode more specifically. This is useful for idempotence.
aliases: [lid]
type: int
additional_disks:
@ -109,17 +106,17 @@ options:
type: int
plan:
description:
- plan to use for the instance (Linode plan)
- Plan to use for the instance (Linode plan).
type: int
payment_term:
description:
- payment term to use for the instance (payment term in months)
- Payment term to use for the instance (payment term in months).
default: 1
choices: [1, 12, 24]
type: int
password:
description:
- root password to apply to a new server (auto generated if missing)
- Root password to apply to a new server (auto generated if missing).
type: str
private_ip:
description:
@ -128,33 +125,33 @@ options:
type: bool
ssh_pub_key:
description:
- SSH public key applied to root user
- SSH public key applied to root user.
type: str
swap:
description:
- swap size in MB
- Swap size in MB.
default: 512
type: int
distribution:
description:
- distribution to use for the instance (Linode Distribution)
- Distribution to use for the instance (Linode Distribution).
type: int
datacenter:
description:
- datacenter to create an instance in (Linode Datacenter)
- Datacenter to create an instance in (Linode Datacenter).
type: int
kernel_id:
description:
- kernel to use for the instance (Linode Kernel)
- Kernel to use for the instance (Linode Kernel).
type: int
wait:
description:
- wait for the instance to be in state V(running) before returning
- Wait for the instance to be in state V(running) before returning.
type: bool
default: true
wait_timeout:
description:
- how long before wait gives up, in seconds
- How long before wait gives up, in seconds.
default: 300
type: int
watchdog:
@ -170,10 +167,9 @@ notes:
- Please note, linode-python does not have python 3 support.
- This module uses the now deprecated v3 of the Linode API.
- Please review U(https://www.linode.com/api/linode) for determining the required parameters.
'''
EXAMPLES = '''
"""
EXAMPLES = r"""
- name: Create a new Linode
community.general.linode:
name: linode-test1
@ -275,7 +271,7 @@ EXAMPLES = '''
linode_id: "{{ linode_creation.instance.id }}"
state: restarted
delegate_to: localhost
'''
"""
import time
import traceback

60
plugins/modules/linode_v4.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: linode_v4
short_description: Manage instances on the Linode cloud
description: Manage instances on the Linode cloud.
@ -18,9 +17,8 @@ requirements:
author:
- Luke Murphy (@decentral1se)
notes:
- No Linode resizing is currently implemented. This module will, in time,
replace the current Linode module which uses deprecated API bindings on the
Linode side.
- No Linode resizing is currently implemented. This module will, in time, replace the current Linode module which uses deprecated API bindings
on the Linode side.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -31,52 +29,44 @@ attributes:
options:
region:
description:
- The region of the instance. This is a required parameter only when
creating Linode instances. See
U(https://www.linode.com/docs/api/regions/).
- The region of the instance. This is a required parameter only when creating Linode instances. See U(https://www.linode.com/docs/api/regions/).
type: str
image:
description:
- The image of the instance. This is a required parameter only when
creating Linode instances. See
U(https://www.linode.com/docs/api/images/).
- The image of the instance. This is a required parameter only when creating Linode instances.
- See U(https://www.linode.com/docs/api/images/).
type: str
type:
description:
- The type of the instance. This is a required parameter only when
creating Linode instances. See
U(https://www.linode.com/docs/api/linode-types/).
- The type of the instance. This is a required parameter only when creating Linode instances.
- See U(https://www.linode.com/docs/api/linode-types/).
type: str
label:
description:
- The instance label. This label is used as the main determiner for
idempotence for the module and is therefore mandatory.
- The instance label. This label is used as the main determiner for idempotence for the module and is therefore mandatory.
type: str
required: true
group:
description:
- The group that the instance should be marked under. Please note, that
group labelling is deprecated but still supported. The encouraged
- The group that the instance should be marked under. Please note, that group labelling is deprecated but still supported. The encouraged
method for marking instances is to use tags.
type: str
private_ip:
description:
- If V(true), the created Linode will have private networking enabled and
assigned a private IPv4 address.
- If V(true), the created Linode will have private networking enabled and assigned a private IPv4 address.
type: bool
default: false
version_added: 3.0.0
tags:
description:
- The tags that the instance should be marked under. See
U(https://www.linode.com/docs/api/tags/).
- The tags that the instance should be marked under.
- See U(https://www.linode.com/docs/api/tags/).
type: list
elements: str
root_pass:
description:
- The password for the root user. If not specified, one will be
generated. This generated password will be available in the task
success JSON.
- The password for the root user. If not specified, one will be generated. This generated password will be available in the task success
JSON.
type: str
authorized_keys:
description:
@ -93,28 +83,26 @@ options:
required: true
access_token:
description:
- The Linode API v4 access token. It may also be specified by exposing
the E(LINODE_ACCESS_TOKEN) environment variable. See
U(https://www.linode.com/docs/api#access-and-authentication).
- The Linode API v4 access token. It may also be specified by exposing the E(LINODE_ACCESS_TOKEN) environment variable.
- See U(https://www.linode.com/docs/api#access-and-authentication).
required: true
type: str
stackscript_id:
description:
- The numeric ID of the StackScript to use when creating the instance.
See U(https://www.linode.com/docs/api/stackscripts/).
- See U(https://www.linode.com/docs/api/stackscripts/).
type: int
version_added: 1.3.0
stackscript_data:
description:
- An object containing arguments to any User Defined Fields present in
the StackScript used when creating the instance.
Only valid when a stackscript_id is provided.
See U(https://www.linode.com/docs/api/stackscripts/).
- An object containing arguments to any User Defined Fields present in the StackScript used when creating the instance. Only valid when
a O(stackscript_id) is provided.
- See U(https://www.linode.com/docs/api/stackscripts/).
type: dict
version_added: 1.3.0
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Create a new Linode.
community.general.linode_v4:
label: new-linode
@ -135,7 +123,7 @@ EXAMPLES = """
state: absent
"""
RETURN = """
RETURN = r"""
instance:
description: The instance description in JSON serialized form.
returned: Always.

26
plugins/modules/listen_ports_facts.py
View File

@ -8,8 +8,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: listen_ports_facts
author:
- Nathan Davison (@ndavison)
@ -20,9 +19,8 @@ requirements:
- netstat or ss
short_description: Gather facts on processes listening on TCP and UDP ports
notes:
- |
C(ss) returns all processes for each listen address and port.
This plugin will return each of them, so multiple entries for the same listen address and port are likely in results.
- C(ss) returns all processes for each listen address and port.
- This plugin will return each of them, so multiple entries for the same listen address and port are likely in results.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.facts
@ -31,7 +29,7 @@ options:
command:
description:
- Override which command to use for fetching listen ports.
- 'By default module will use first found supported command on the system (in alphanumerical order).'
- By default module will use first found supported command on the system (in alphanumerical order).
type: str
choices:
- netstat
@ -40,14 +38,14 @@ options:
include_non_listening:
description:
- Show both listening and non-listening sockets (for TCP this means established connections).
- Adds the return values RV(ansible_facts.tcp_listen[].state), RV(ansible_facts.udp_listen[].state),
RV(ansible_facts.tcp_listen[].foreign_address), and RV(ansible_facts.udp_listen[].foreign_address) to the returned facts.
- Adds the return values RV(ansible_facts.tcp_listen[].state), RV(ansible_facts.udp_listen[].state), RV(ansible_facts.tcp_listen[].foreign_address),
and RV(ansible_facts.udp_listen[].foreign_address) to the returned facts.
type: bool
default: false
version_added: 5.4.0
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Gather facts on listening ports
community.general.listen_ports_facts:
@ -77,11 +75,11 @@ EXAMPLES = r'''
community.general.listen_ports_facts:
command: 'netstat'
include_non_listening: true
'''
"""
RETURN = r'''
RETURN = r"""
ansible_facts:
description: Dictionary containing details of TCP and UDP ports with listening servers
description: Dictionary containing details of TCP and UDP ports with listening servers.
returned: always
type: complex
contains:
@ -189,7 +187,7 @@ ansible_facts:
returned: always
type: str
sample: "root"
'''
"""
import re
import platform

18
plugins/modules/lldp.py
View File

@ -9,13 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: lldp
requirements: [lldpctl]
short_description: Get details reported by lldp
short_description: Get details reported by LLDP
description:
- Reads data out of lldpctl
- Reads data out of C(lldpctl).
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -26,12 +25,12 @@ attributes:
options: {}
author: "Andy Hill (@andyhky)"
notes:
- Requires lldpd running and lldp enabled on switches
'''
- Requires C(lldpd) running and LLDP enabled on switches.
"""
EXAMPLES = '''
EXAMPLES = r"""
# Retrieve switch/port information
- name: Gather information from lldp
- name: Gather information from LLDP
community.general.lldp:
- name: Print each switch/port
@ -43,8 +42,7 @@ EXAMPLES = '''
# ok: [10.13.0.22] => (item=eth2) => {"item": "eth2", "msg": "switch1.example.com / Gi0/24"}
# ok: [10.13.0.22] => (item=eth1) => {"item": "eth1", "msg": "switch2.example.com / Gi0/3"}
# ok: [10.13.0.22] => (item=eth0) => {"item": "eth0", "msg": "switch3.example.com / Gi0/3"}
'''
"""
from ansible.module_utils.basic import AnsibleModule

11
plugins/modules/locale_gen.py
View File

@ -8,12 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: locale_gen
short_description: Creates or removes locales
description:
- Manages locales by editing /etc/locale.gen and invoking locale-gen.
- Manages locales by editing /etc/locale.gen and invoking C(locale-gen).
author:
- Augustus Kling (@AugustusKling)
extends_documentation_fragment:
@ -39,9 +38,9 @@ options:
default: present
notes:
- This module does not support RHEL-based systems.
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Ensure a locale exists
community.general.locale_gen:
name: de_CH.UTF-8
@ -53,7 +52,7 @@ EXAMPLES = '''
- en_GB.UTF-8
- nl_NL.UTF-8
state: present
'''
"""
import os
import re

24
plugins/modules/logentries.py
View File

@ -9,13 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: logentries
author: "Ivan Vanderbyl (@ivanvanderbyl)"
short_description: Module for tracking logs via logentries.com
short_description: Module for tracking logs using U(logentries.com)
description:
- Sends logs to LogEntries in realtime
- Sends logs to LogEntries in realtime.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -27,31 +26,32 @@ options:
path:
type: str
description:
- path to a log file
- Path to a log file.
required: true
state:
type: str
description:
- following state of the log
- Following state of the log.
choices: ['present', 'absent', 'followed', 'unfollowed']
required: false
default: present
name:
type: str
description:
- name of the log
- Name of the log.
required: false
logtype:
type: str
description:
- type of the log
- Type of the log.
required: false
aliases: [type]
notes:
- Requires the LogEntries agent which can be installed following the instructions at logentries.com
'''
EXAMPLES = '''
- Requires the LogEntries agent which can be installed following the instructions at U(logentries.com).
"""
EXAMPLES = r"""
- name: Track nginx logs
community.general.logentries:
path: /var/log/nginx/access.log
@ -62,7 +62,7 @@ EXAMPLES = '''
community.general.logentries:
path: /var/log/nginx/error.log
state: absent
'''
"""
from ansible.module_utils.basic import AnsibleModule

21
plugins/modules/logentries_msg.py
View File

@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: logentries_msg
short_description: Send a message to logentries
description:
- Send a message to logentries
- Send a message to logentries.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -36,24 +35,24 @@ options:
api:
type: str
description:
- API endpoint
- API endpoint.
default: data.logentries.com
port:
type: int
description:
- API endpoint port
- API endpoint port.
default: 80
author: "Jimmy Tang (@jcftang) <jimmy_tang@rapid7.com>"
'''
"""
RETURN = '''# '''
RETURN = """# """
EXAMPLES = '''
EXAMPLES = r"""
- name: Send a message to logentries
community.general.logentries_msg:
token=00000000-0000-0000-0000-000000000000
msg="{{ ansible_hostname }}"
'''
token: 00000000-0000-0000-0000-000000000000
msg: "{{ ansible_hostname }}"
"""
import socket

12
plugins/modules/logstash_plugin.py
View File

@ -8,8 +8,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: logstash_plugin
short_description: Manage Logstash plugins
description:
@ -50,11 +49,10 @@ options:
version:
type: str
description:
- Specify plugin Version of the plugin to install.
If plugin exists with previous version, it will NOT be updated.
'''
- Specify plugin Version of the plugin to install. If plugin exists with previous version, it will NOT be updated.
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Install Logstash beats input plugin
community.general.logstash_plugin:
state: present
@ -77,7 +75,7 @@ EXAMPLES = '''
name: logstash-input-beats
environment:
LS_JAVA_OPTS: "-Xms256m -Xmx256m"
'''
"""
from ansible.module_utils.basic import AnsibleModule

21
plugins/modules/lvg.py
View File

@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
author:
- Alexander Bulimov (@abulimov)
module: lvg
@ -39,9 +38,8 @@ options:
elements: str
pesize:
description:
- "The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector
(where the sector size is the largest sector size of the PVs currently used in the VG),
or at least 128KiB."
- The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector (where the sector size is the largest sector size
of the PVs currently used in the VG), or at least 128KiB.
- O(pesize) can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte.
type: str
default: "4"
@ -64,10 +62,9 @@ options:
state:
description:
- Control if the volume group exists and it's state.
- The states V(active) and V(inactive) implies V(present) state. Added in 7.1.0
- "If V(active) or V(inactive), the module manages the VG's logical volumes current state.
The module also handles the VG's autoactivation state if supported
unless when creating a volume group and the autoactivation option specified in O(vg_options)."
- The states V(active) and V(inactive) implies V(present) state. Added in 7.1.0.
- If V(active) or V(inactive), the module manages the VG's logical volumes current state. The module also handles the VG's autoactivation
state if supported unless when creating a volume group and the autoactivation option specified in O(vg_options).
type: str
choices: [absent, present, active, inactive]
default: present
@ -96,9 +93,9 @@ seealso:
- module: community.general.parted
notes:
- This module does not modify PE size for already present volume group.
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Create a volume group on top of /dev/sda1 with physical extent size = 32MB
community.general.lvg:
vg: vg.services
@ -154,7 +151,7 @@ EXAMPLES = r'''
pvs: /dev/sdb1,/dev/sdc5
reset_vg_uuid: true
reset_pv_uuid: true
'''
"""
import itertools
import os

9
plugins/modules/lvg_rename.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
author:
- Laszlo Szomor (@lszomor)
module: lvg_rename
@ -41,9 +40,9 @@ seealso:
- module: community.general.lvg
notes:
- This module does not modify VG renaming-related configurations like C(fstab) entries or boot parameters.
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Rename a VG by name
community.general.lvg_rename:
vg: vg_orig_name
@ -53,7 +52,7 @@ EXAMPLES = r'''
community.general.lvg_rename:
vg_uuid: SNgd0Q-rPYa-dPB8-U1g6-4WZI-qHID-N7y9Vj
vg_new: vg_new_name
'''
"""
from ansible.module_utils.basic import AnsibleModule

29
plugins/modules/lvol.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
author:
- Jeroen Hoekx (@jhoekx)
- Alexander Bulimov (@abulimov)
@ -39,20 +38,16 @@ options:
size:
type: str
description:
- The size of the logical volume, according to lvcreate(8) --size, by
default in megabytes or optionally with one of [bBsSkKmMgGtTpPeE] units; or
according to lvcreate(8) --extents as a percentage of [VG|PVS|FREE|ORIGIN];
Float values must begin with a digit.
- When resizing, apart from specifying an absolute size you may, according to
lvextend(8)|lvreduce(8) C(--size), specify the amount to extend the logical volume with
the prefix V(+) or the amount to reduce the logical volume by with prefix V(-).
- The size of the logical volume, according to lvcreate(8) C(--size), by default in megabytes or optionally with one of [bBsSkKmMgGtTpPeE]
units; or according to lvcreate(8) --extents as a percentage of [VG|PVS|FREE|ORIGIN]; Float values must begin with a digit.
- When resizing, apart from specifying an absolute size you may, according to lvextend(8)|lvreduce(8) C(--size), specify the amount to extend
the logical volume with the prefix V(+) or the amount to reduce the logical volume by with prefix V(-).
- Resizing using V(+) or V(-) was not supported prior to community.general 3.0.0.
- Please note that when using V(+), V(-), or percentage of FREE, the module is B(not idempotent).
state:
type: str
description:
- Control if the logical volume exists. If V(present) and the
volume does not already exist then the O(size) option is required.
- Control if the logical volume exists. If V(present) and the volume does not already exist then the O(size) option is required.
choices: [absent, present]
default: present
active:
@ -62,8 +57,7 @@ options:
default: true
force:
description:
- Shrink or remove operations of volumes requires this switch. Ensures that
that filesystems get never corrupted/destroyed by mistake.
- Shrink or remove operations of volumes requires this switch. Ensures that that filesystems get never corrupted/destroyed by mistake.
type: bool
default: false
opts:
@ -91,15 +85,14 @@ options:
resizefs:
description:
- Resize the underlying filesystem together with the logical volume.
- Supported for C(ext2), C(ext3), C(ext4), C(reiserfs) and C(XFS) filesystems.
Attempts to resize other filesystem types will fail.
- Supported for C(ext2), C(ext3), C(ext4), C(reiserfs) and C(XFS) filesystems. Attempts to resize other filesystem types will fail.
type: bool
default: false
notes:
- You must specify lv (when managing the state of logical volumes) or thinpool (when managing a thin provisioned volume).
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create a logical volume of 512m
community.general.lvol:
vg: firefly
@ -233,7 +226,7 @@ EXAMPLES = '''
lv: test
thinpool: testpool
size: 128g
'''
"""
import re
import shlex

65
plugins/modules/lxc_container.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: lxc_container
short_description: Manage LXC Containers
description:
@ -57,7 +56,7 @@ options:
lv_name:
description:
- Name of the logical volume, defaults to the container name.
- If not specified, it defaults to C($CONTAINER_NAME).
- If not specified, it defaults to E(CONTAINER_NAME).
type: str
vg_name:
description:
@ -144,8 +143,7 @@ options:
- bzip2
- none
description:
- Type of compression to use when creating an archive of a running
container.
- Type of compression to use when creating an archive of a running container.
type: str
default: gzip
state:
@ -158,11 +156,9 @@ options:
- clone
description:
- Define the state of a container.
- If you clone a container using O(clone_name) the newly cloned
container created in a stopped state.
- The running container will be stopped while the clone operation is
happening and upon completion of the clone the original container
state will be restored.
- If you clone a container using O(clone_name) the newly cloned container created in a stopped state.
- The running container will be stopped while the clone operation is happening and upon completion of the clone the original container state
will be restored.
type: str
default: started
container_config:
@ -175,27 +171,18 @@ requirements:
- 'python3 >= 3.5 # OS Package'
- 'python3-lxc # OS Package'
notes:
- Containers must have a unique name. If you attempt to create a container
with a name that already exists in the users namespace the module will
simply return as "unchanged".
- The O(container_command) can be used with any state except V(absent). If
used with state V(stopped) the container will be V(started), the command
executed, and then the container V(stopped) again. Likewise if O(state=stopped)
and the container does not exist it will be first created,
V(started), the command executed, and then V(stopped). If you use a "|"
in the variable you can use common script formatting within the variable
itself. The O(container_command) option will always execute as BASH.
When using O(container_command), a log file is created in the C(/tmp/) directory
which contains both C(stdout) and C(stderr) of any command executed.
- If O(archive=true) the system will attempt to create a compressed
tarball of the running container. The O(archive) option supports LVM backed
containers and will create a snapshot of the running container when
creating the archive.
- If your distro does not have a package for C(python3-lxc), which is a
requirement for this module, it can be installed from source at
U(https://github.com/lxc/python3-lxc) or installed via pip using the
package name C(lxc).
'''
- Containers must have a unique name. If you attempt to create a container with a name that already exists in the users namespace the module
will simply return as "unchanged".
- The O(container_command) can be used with any state except V(absent). If used with state V(stopped) the container will be V(started), the
command executed, and then the container V(stopped) again. Likewise if O(state=stopped) and the container does not exist it will be first
created, V(started), the command executed, and then V(stopped). If you use a C(|) in the variable you can use common script formatting within
the variable itself. The O(container_command) option will always execute as C(bash). When using O(container_command), a log file is created in
the C(/tmp/) directory which contains both C(stdout) and C(stderr) of any command executed.
- If O(archive=true) the system will attempt to create a compressed tarball of the running container. The O(archive) option supports LVM backed
containers and will create a snapshot of the running container when creating the archive.
- If your distro does not have a package for C(python3-lxc), which is a requirement for this module, it can be installed from source at
U(https://github.com/lxc/python3-lxc) or installed using C(pip install lxc).
"""
EXAMPLES = r"""
- name: Create a started container
@ -382,42 +369,42 @@ EXAMPLES = r"""
RETURN = r"""
lxc_container:
description: container information
description: Container information.
returned: success
type: complex
contains:
name:
description: name of the lxc container
description: Name of the lxc container.
returned: success
type: str
sample: test_host
init_pid:
description: pid of the lxc init process
description: Pid of the lxc init process.
returned: success
type: int
sample: 19786
interfaces:
description: list of the container's network interfaces
description: List of the container's network interfaces.
returned: success
type: list
sample: ["eth0", "lo"]
ips:
description: list of ips
description: List of ips.
returned: success
type: list
sample: ["10.0.3.3"]
state:
description: resulting state of the container
description: Resulting state of the container.
returned: success
type: str
sample: "running"
archive:
description: resulting state of the container
description: Resulting state of the container.
returned: success, when archive is true
type: str
sample: "/tmp/test-container-config.tar"
clone:
description: if the container was cloned
description: If the container was cloned.
returned: success, when clone_name is specified
type: bool
sample: true

29
plugins/modules/lxca_cmms.py
View File

@ -8,16 +8,14 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
author:
- Naval Patel (@navalkp)
- Prashant Bhosale (@prabhosa)
module: lxca_cmms
short_description: Custom module for lxca cmms inventory utility
description:
- This module returns/displays a inventory details of cmms
- This module returns/displays a inventory details of cmms.
attributes:
check_mode:
support: none
@ -26,13 +24,11 @@ attributes:
options:
uuid:
description:
uuid of device, this is string with length greater than 16.
description: UUID of device, this is string with length greater than 16.
type: str
command_options:
description:
options to filter nodes information
description: Options to filter nodes information.
default: cmms
choices:
- cmms
@ -41,17 +37,15 @@ options:
type: str
chassis:
description:
uuid of chassis, this is string with length greater than 16.
description: UUID of chassis, this is string with length greater than 16.
type: str
extends_documentation_fragment:
- community.general.lxca_common
- community.general.attributes
"""
'''
EXAMPLES = '''
EXAMPLES = r"""
# get all cmms info
- name: Get nodes data from LXCA
community.general.lxca_cmms:
@ -76,12 +70,11 @@ EXAMPLES = '''
auth_url: "https://10.243.15.168"
chassis: "3C737AA5E31640CE949B10C129A8B01F"
command_options: cmms_by_chassis_uuid
"""
'''
RETURN = r'''
RETURN = r"""
result:
description: cmms detail from lxca
description: Cmms detail from lxca.
returned: success
type: dict
sample:
@ -97,7 +90,7 @@ result:
uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF'
# bunch of properties
# Multiple cmms details
'''
"""
import traceback
from ansible.module_utils.basic import AnsibleModule

29
plugins/modules/lxca_nodes.py
View File

@ -8,16 +8,14 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
author:
- Naval Patel (@navalkp)
- Prashant Bhosale (@prabhosa)
module: lxca_nodes
short_description: Custom module for lxca nodes inventory utility
description:
- This module returns/displays a inventory details of nodes
- This module returns/displays a inventory details of nodes.
attributes:
check_mode:
support: none
@ -26,13 +24,11 @@ attributes:
options:
uuid:
description:
uuid of device, this is string with length greater than 16.
description: UUID of device, this is string with length greater than 16.
type: str
command_options:
description:
options to filter nodes information
description: Options to filter nodes information.
default: nodes
choices:
- nodes
@ -43,17 +39,15 @@ options:
type: str
chassis:
description:
uuid of chassis, this is string with length greater than 16.
description: UUID of chassis, this is string with length greater than 16.
type: str
extends_documentation_fragment:
- community.general.lxca_common
- community.general.attributes
"""
'''
EXAMPLES = '''
EXAMPLES = r"""
# get all nodes info
- name: Get nodes data from LXCA
community.general.lxca_nodes:
@ -95,12 +89,11 @@ EXAMPLES = '''
login_password: Password
auth_url: "https://10.243.15.168"
command_options: nodes_status_unmanaged
"""
'''
RETURN = r'''
RETURN = r"""
result:
description: nodes detail from lxca
description: Nodes detail from lxca.
returned: always
type: dict
sample:
@ -116,7 +109,7 @@ result:
uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF'
# bunch of properties
# Multiple nodes details
'''
"""
import traceback
from ansible.module_utils.basic import AnsibleModule

102
plugins/modules/lxd_container.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: lxd_container
short_description: Manage LXD instances
description:
@ -33,32 +32,30 @@ options:
required: true
project:
description:
- 'Project of an instance.
See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).'
- Project of an instance.
- See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).
required: false
type: str
version_added: 4.8.0
architecture:
description:
- 'The architecture for the instance (for example V(x86_64) or V(i686)).
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- The architecture for the instance (for example V(x86_64) or V(i686)).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
type: str
required: false
config:
description:
- 'The config for the instance (for example V({"limits.cpu": "2"})).
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- If the instance already exists and its "config" values in metadata
obtained from the LXD API U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get)
are different, then this module tries to apply the configurations
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- If the instance already exists and its "config" values in metadata obtained from the LXD API
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get)
are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put).
- The keys starting with C(volatile.) are ignored for this comparison when O(ignore_volatile_options=true).
type: dict
required: false
ignore_volatile_options:
description:
- If set to V(true), options starting with C(volatile.) are ignored. As a result,
they are reapplied for each execution.
- If set to V(true), options starting with C(volatile.) are ignored. As a result, they are reapplied for each execution.
- This default behavior can be changed by setting this option to V(false).
- The default value changed from V(true) to V(false) in community.general 6.0.0.
type: bool
@ -72,23 +69,21 @@ options:
elements: str
devices:
description:
- 'The devices for the instance
(for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})).
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- 'The devices for the instance (for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
type: dict
required: false
ephemeral:
description:
- Whether or not the instance is ephemeral (for example V(true) or V(false)).
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
required: false
type: bool
source:
description:
- 'The source for the instance
(for example V({ "type": "image", "mode": "pull", "server": "https://cloud-images.ubuntu.com/releases/",
- 'The source for the instance (for example V({ "type": "image", "mode": "pull", "server": "https://cloud-images.ubuntu.com/releases/",
"protocol": "simplestreams", "alias": "22.04" })).'
- 'See U(https://documentation.ubuntu.com/lxd/en/latest/api/) for complete API documentation.'
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/) for complete API documentation.
- 'Note that C(protocol) accepts two choices: V(lxd) or V(simplestreams).'
required: false
type: dict
@ -106,18 +101,16 @@ options:
type: str
target:
description:
- For cluster deployments. Will attempt to create an instance on a target node.
If the instance exists elsewhere in a cluster, then it will not be replaced or moved.
The name should respond to same name of the node you see in C(lxc cluster list).
- For cluster deployments. Will attempt to create an instance on a target node. If the instance exists elsewhere in a cluster, then it will
not be replaced or moved. The name should respond to same name of the node you see in C(lxc cluster list).
type: str
required: false
version_added: 1.0.0
timeout:
description:
- A timeout for changing the state of the instance.
- This is also used as a timeout for waiting until IPv4 addresses
are set to the all network interfaces in the instance after
starting or restarting.
- This is also used as a timeout for waiting until IPv4 addresses are set to the all network interfaces in the instance after starting or
restarting.
required: false
default: 30
type: int
@ -133,23 +126,20 @@ options:
version_added: 4.1.0
wait_for_ipv4_addresses:
description:
- If this is V(true), the C(lxd_container) waits until IPv4 addresses
are set to the all network interfaces in the instance after
starting or restarting.
- If this is V(true), the C(lxd_container) waits until IPv4 addresses are set to the all network interfaces in the instance after starting
or restarting.
required: false
default: false
type: bool
wait_for_container:
description:
- If set to V(true), the tasks will wait till the task reports a
success status when performing container operations.
- If set to V(true), the tasks will wait till the task reports a success status when performing container operations.
default: false
type: bool
version_added: 4.4.0
force_stop:
description:
- If this is V(true), the C(lxd_container) forces to stop the instance
when it stops or restarts the instance.
- If this is V(true), the C(lxd_container) forces to stop the instance when it stops or restarts the instance.
required: false
default: false
type: bool
@ -182,35 +172,26 @@ options:
trust_password:
description:
- The client trusted password.
- 'You need to set this password on the LXD server before
running this module using the following command:
C(lxc config set core.trust_password <some random password>).
See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- If trust_password is set, this module send a request for
authentication before sending any requests.
- 'You need to set this password on the LXD server before running this module using the following command: C(lxc config set core.trust_password
<some random password>). See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- If trust_password is set, this module send a request for authentication before sending any requests.
required: false
type: str
notes:
- Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance
with a name that already existed in the users namespace the module will
simply return as "unchanged".
- There are two ways to run commands inside a container or virtual machine, using the command
module or using the ansible lxd connection plugin bundled in Ansible >=
2.1, the later requires python to be installed in the instance which can
be done with the command module.
- You can copy a file from the host to the instance
with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module
and the P(community.general.lxd#connection) connection plugin.
See the example below.
- You can copy a file in the created instance to the localhost
with C(command=lxc file pull instance_name/dir/filename filename).
See the first example below.
- linuxcontainers.org has phased out LXC/LXD support with March 2024
- Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance with a name that
already existed in the users namespace the module will simply return as "unchanged".
- There are two ways to run commands inside a container or virtual machine, using the command module or using the ansible lxd connection plugin
bundled in Ansible >= 2.1, the later requires python to be installed in the instance which can be done with the command module.
- You can copy a file from the host to the instance with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module and the
P(community.general.lxd#connection) connection plugin. See the example below.
- You can copy a file in the created instance to the localhost with C(command=lxc file pull instance_name/dir/filename filename). See the first
example below.
- Linuxcontainers.org has phased out LXC/LXD support with March 2024
(U(https://discuss.linuxcontainers.org/t/important-notice-for-lxd-users-image-server/18479)).
Currently only Ubuntu is still providing images.
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# An example for creating a Ubuntu container and install python
- hosts: localhost
connection: local
@ -400,12 +381,12 @@ EXAMPLES = '''
protocol: simplestreams
type: image
mode: pull
server: [...] # URL to the image server
server: ['...'] # URL to the image server
alias: debian/11
timeout: 600
'''
"""
RETURN = '''
RETURN = r"""
addresses:
description: Mapping from the network device name to a list of IPv4 addresses in the instance.
returned: when state is started or restarted
@ -426,7 +407,8 @@ actions:
returned: success
type: list
sample: ["create", "start"]
'''
"""
import copy
import datetime
import os

56
plugins/modules/lxd_profile.py
View File

@ -9,12 +9,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: lxd_profile
short_description: Manage LXD profiles
description:
- Management of LXD profiles
- Management of LXD profiles.
author: "Hiroaki Nakamura (@hnakamur)"
extends_documentation_fragment:
- community.general.attributes
@ -31,8 +30,7 @@ options:
type: str
project:
description:
- 'Project of a profile.
See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).'
- Project of a profile. See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).
type: str
required: false
version_added: 4.8.0
@ -42,36 +40,30 @@ options:
type: str
config:
description:
- 'The config for the instance (e.g. {"limits.memory": "4GB"}).
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).'
- If the profile already exists and its "config" value in metadata
obtained from
GET /1.0/profiles/<name>
- 'The config for the instance (for example V({"limits.memory": "4GB"})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).'
- If the profile already exists and its C(config) value in metadata obtained from GET /1.0/profiles/<name>
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get)
are different, then this module tries to apply the configurations
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_put).
- Not all config values are supported to apply the existing profile.
Maybe you need to delete and recreate a profile.
are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_put).
- Not all config values are supported to apply the existing profile. Maybe you need to delete and recreate a profile.
required: false
type: dict
devices:
description:
- 'The devices for the profile
(e.g. {"rootfs": {"path": "/dev/kvm", "type": "unix-char"}).
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).'
- 'The devices for the profile (for example V({"rootfs": {"path": "/dev/kvm", "type": "unix-char"})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).'
required: false
type: dict
new_name:
description:
- A new name of a profile.
- If this parameter is specified a profile will be renamed to this name.
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_post).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_post).
required: false
type: str
merge_profile:
description:
- Merge the configuration of the present profile with the new desired configuration,
instead of replacing it.
- Merge the configuration of the present profile with the new desired configuration, instead of replacing it.
required: false
default: false
type: bool
@ -114,21 +106,17 @@ options:
trust_password:
description:
- The client trusted password.
- You need to set this password on the LXD server before
running this module using the following command.
lxc config set core.trust_password <some random password>
See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/)
- If trust_password is set, this module send a request for
authentication before sending any requests.
- You need to set this password on the LXD server before running this module using the following command. lxc config set core.trust_password
<some random password> See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).
- If trust_password is set, this module send a request for authentication before sending any requests.
required: false
type: str
notes:
- Profiles must have a unique name. If you attempt to create a profile
with a name that already existed in the users namespace the module will
- Profiles must have a unique name. If you attempt to create a profile with a name that already existed in the users namespace the module will
simply return as "unchanged".
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# An example for creating a profile
- hosts: localhost
connection: local
@ -214,11 +202,11 @@ EXAMPLES = '''
name: macvlan
new_name: macvlan2
state: present
'''
"""
RETURN = '''
RETURN = r"""
old_state:
description: The old state of the profile
description: The old state of the profile.
returned: success
type: str
sample: "absent"
@ -232,7 +220,7 @@ actions:
returned: success
type: list
sample: ["create"]
'''
"""
import os
from ansible.module_utils.basic import AnsibleModule

40
plugins/modules/lxd_project.py
View File

@ -7,8 +7,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: lxd_project
short_description: Manage LXD projects
version_added: 4.8.0
@ -35,25 +34,22 @@ options:
config:
description:
- 'The config for the project (for example V({"features.profiles": "true"})).
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get).'
- If the project already exists and its "config" value in metadata
obtained from
C(GET /1.0/projects/<name>)
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get).'
- If the project already exists and its "config" value in metadata obtained from C(GET /1.0/projects/<name>)
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get)
are different, then this module tries to apply the configurations
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_put).
are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_put).
type: dict
new_name:
description:
- A new name of a project.
- If this parameter is specified a project will be renamed to this name.
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_post).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_post).
required: false
type: str
merge_project:
description:
- Merge the configuration of the present project with the new desired configuration,
instead of replacing it. If configuration is the same after merged, no change will be made.
- Merge the configuration of the present project with the new desired configuration, instead of replacing it. If configuration is the same
after merged, no change will be made.
required: false
default: false
type: bool
@ -95,21 +91,17 @@ options:
trust_password:
description:
- The client trusted password.
- 'You need to set this password on the LXD server before
running this module using the following command:
C(lxc config set core.trust_password <some random password>)
See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- If O(trust_password) is set, this module send a request for
authentication before sending any requests.
- 'You need to set this password on the LXD server before running this module using the following command: C(lxc config set core.trust_password
<some random password>) See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- If O(trust_password) is set, this module send a request for authentication before sending any requests.
required: false
type: str
notes:
- Projects must have a unique name. If you attempt to create a project
with a name that already existed in the users namespace the module will
- Projects must have a unique name. If you attempt to create a project with a name that already existed in the users namespace the module will
simply return as "unchanged".
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# An example for creating a project
- hosts: localhost
connection: local
@ -132,9 +124,9 @@ EXAMPLES = '''
state: present
config: {}
description: my new project
'''
"""
RETURN = '''
RETURN = r"""
old_state:
description: The old state of the project.
returned: success
@ -184,7 +176,7 @@ actions:
type: list
elements: str
sample: ["create"]
'''
"""
from ansible_collections.community.general.plugins.module_utils.lxd import (
LXDClient, LXDClientException, default_key_file, default_cert_file