Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[prox ... pyth]*: normalize docs #9364

Merged
merged 4 commits into from
Dec 26, 2024
Merged

[prox ... pyth]*: normalize docs #9364

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cdf5a84
[prox ... pyth]*: normalize docs
russoz Dec 24, 2024
53bda89
Apply suggestions from code review
russoz Dec 25, 2024
3af1788
Update plugins/modules/pushbullet.py
russoz Dec 25, 2024
b7168cd
Update plugins/modules/pushbullet.py
russoz Dec 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 34 additions & 37 deletions plugins/modules/proxmox.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type

DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: proxmox
short_description: Management of instances in Proxmox VE cluster
description:
Expand All @@ -26,28 +25,26 @@
options:
password:
description:
- the instance root password
- The instance root password.
type: str
hostname:
description:
- the instance hostname
- required only for O(state=present)
- must be unique if vmid is not passed
- The instance hostname.
- Required only for O(state=present).
- Must be unique if vmid is not passed.
type: str
ostemplate:
description:
- the template for VM creating
- required only for O(state=present)
- The template for VM creating.
- Required only for O(state=present).
type: str
disk:
description:
- This option was previously described as "hard disk size in GB for instance" however several formats describing
a lxc mount are permitted.
- Older versions of Proxmox will accept a numeric value for size using the O(storage) parameter to automatically
choose which storage to allocate from, however new versions enforce the C(<STORAGE>:<SIZE>) syntax.
- "Additional options are available by using some combination of the following key-value pairs as a
comma-delimited list C([volume=]<volume> [,acl=<1|0>] [,mountoptions=<opt[;opt...]>] [,quota=<1|0>]
[,replicate=<1|0>] [,ro=<1|0>] [,shared=<1|0>] [,size=<DiskSize>])."
- This option was previously described as "hard disk size in GB for instance" however several formats describing a lxc mount are permitted.
- Older versions of Proxmox will accept a numeric value for size using the O(storage) parameter to automatically choose which storage to
allocate from, however new versions enforce the C(<STORAGE>:<SIZE>) syntax.
- Additional options are available by using some combination of the following key-value pairs as a comma-delimited list C([volume=]<volume>
[,acl=<1|0>] [,mountoptions=<opt[;opt...]>] [,quota=<1|0>] [,replicate=<1|0>] [,ro=<1|0>] [,shared=<1|0>] [,size=<DiskSize>]).
- See U(https://pve.proxmox.com/wiki/Linux_Container) for a full description.
- This option is mutually exclusive with O(storage) and O(disk_volume).
type: str
Expand Down Expand Up @@ -93,19 +90,19 @@
type: int
cpus:
description:
- numbers of allocated cpus for instance
- Number of allocated cpus for instance.
type: int
memory:
description:
- memory size in MB for instance
- Memory size in MB for instance.
type: int
swap:
description:
- swap memory size in MB for instance
- Swap memory size in MB for instance.
type: int
netif:
description:
- specifies network interfaces for the container. As a hash/dictionary defining interfaces.
- Specifies network interfaces for the container. As a hash/dictionary defining interfaces.
type: dict
features:
description:
Expand Down Expand Up @@ -177,11 +174,11 @@
type: dict
ip_address:
description:
- specifies the address the container will be assigned
- Specifies the address the container will be assigned.
type: str
onboot:
description:
- specifies whether a VM will be started during system bootup
- Specifies whether a VM will be started during system bootup.
type: bool
storage:
description:
Expand All @@ -199,15 +196,15 @@
version_added: 8.1.0
cpuunits:
description:
- CPU weight for a VM
- CPU weight for a VM.
type: int
nameserver:
description:
- sets DNS server IP address for a container
- Sets DNS server IP address for a container.
type: str
searchdomain:
description:
- sets DNS search domain for a container
- Sets DNS search domain for a container.
type: str
tags:
description:
Expand All @@ -219,7 +216,7 @@
version_added: 6.2.0
timeout:
description:
- timeout for operations
- Timeout for operations.
type: int
default: 30
update:
Expand All @@ -232,8 +229,8 @@
description:
- Forcing operations.
- Can be used only with states V(present), V(stopped), V(restarted).
- with O(state=present) force option allow to overwrite existing container.
- with states V(stopped), V(restarted) allow to force stop instance.
- With O(state=present) force option allow to overwrite existing container.
- With states V(stopped), V(restarted) allow to force stop instance.
type: bool
default: false
purge:
Expand All @@ -247,14 +244,14 @@
version_added: 2.3.0
state:
description:
- Indicate desired state of the instance
- V(template) was added in community.general 8.1.0.
- Indicate desired state of the instance.
- V(template) was added in community.general 8.1.0.
type: str
choices: ['present', 'started', 'absent', 'stopped', 'restarted', 'template']
default: present
pubkey:
description:
- Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions
- Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions.
type: str
unprivileged:
description:
Expand Down Expand Up @@ -292,8 +289,8 @@
- Type of the clone created.
- V(full) creates a full clone, and O(storage) must be specified.
- V(linked) creates a linked clone, and the cloned container must be a template container.
- V(opportunistic) creates a linked clone if the cloned container is a template container, and a full clone if not.
O(storage) may be specified, if not it will fall back to the default.
- V(opportunistic) creates a linked clone if the cloned container is a template container, and a full clone if not. O(storage) may be specified,
if not it will fall back to the default.
type: str
choices: ['full', 'linked', 'opportunistic']
default: opportunistic
Expand All @@ -306,9 +303,9 @@
- community.general.proxmox.documentation
- community.general.proxmox.selection
- community.general.attributes
'''
"""

EXAMPLES = r'''
EXAMPLES = r"""
- name: Create new container with minimal options
community.general.proxmox:
vmid: 100
Expand Down Expand Up @@ -494,8 +491,8 @@
hostname: example.org
ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
features:
- nesting=1
- mount=cifs,nfs
- nesting=1
- mount=cifs,nfs

- name: >
Create a linked clone of the template container with id 100. The newly created container with be a
Expand Down Expand Up @@ -599,7 +596,7 @@
api_password: 1q2w3e
api_host: node1
state: absent
'''
"""

import re
import time
Expand Down
53 changes: 20 additions & 33 deletions plugins/modules/proxmox_backup.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,7 @@
__metaclass__ = type


DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: proxmox_backup
author: "Raphael Grieger (@IamLunchbox) <r.grieger@hotmail.com>"
short_description: Start a VM backup in Proxmox VE cluster
Expand Down Expand Up @@ -42,11 +41,9 @@
change_detection_mode:
description:
- Set the change detection mode (available from Proxmox VE 8.3).
- >
Is only used when backing up containers,
Proxmox silently ignores this option when applied to kvm guests.
- It is only used when backing up containers, Proxmox silently ignores this option when applied to kvm guests.
type: str
choices: ["legacy", "data", "metadata"]
choices: ["legacy", "data", "metadata"]
compress:
description:
- Enable additional compression of the backup archive.
Expand All @@ -63,13 +60,9 @@
description:
- Specify the description of the backup.
- Needs to be a single line, newline and backslash need to be escaped as V(\\n) and V(\\\\) respectively.
- >
If you need variable interpolation, you can set the content as usual
through ansible jinja templating and/or let Proxmox substitute templates.
- >
Proxmox currently supports V({{cluster}}), V({{guestname}}),
V({{node}}), and V({{vmid}}) as templating variables.
Since this is also a jinja delimiter, you need to set these values as raw jinja.
- If you need variable interpolation, you can set the content as usual through ansible jinja templating and/or let Proxmox substitute templates.
- Proxmox currently supports V({{cluster}}), V({{guestname}}), V({{node}}), and V({{vmid}}) as templating variables. Since this is also
a jinja delimiter, you need to set these values as raw jinja.
default: "{{guestname}}"
type: str
fleecing:
Expand All @@ -93,13 +86,13 @@
description:
- Determine which notification system to use.
type: str
choices: ["auto","legacy-sendmail", "notification-system"]
choices: ["auto", "legacy-sendmail", "notification-system"]
default: auto
performance_tweaks:
description:
- Enable other performance-related settings.
- Must be entered as a string, containing comma separated key-value pairs.
- "For example: V(max-workers=2,pbs-entries-max=2)."
- 'For example: V(max-workers=2,pbs-entries-max=2).'
type: str
pool:
description:
Expand All @@ -110,19 +103,14 @@
protected:
description:
- Marks backups as protected.
- >
"Might fail, when the PBS backend has verify enabled
due to this bug: U(https://bugzilla.proxmox.com/show_bug.cgi?id=4289)"
- '"Might fail, when the PBS backend has verify enabled due to this bug: U(https://bugzilla.proxmox.com/show_bug.cgi?id=4289)".'
type: bool
retention:
description:
- >
Use custom retention options instead of those from the default cluster
configuration (which is usually V("keep-all")).
- Use custom retention options instead of those from the default cluster configuration (which is usually V("keep-all=1")).
- Always requires Datastore.Allocate permission at the storage endpoint.
- >
Specifying a retention time other than V(keep-all=1) might trigger pruning on the datastore,
if an existing backup should be deleted target due to your specified timeframe.
- Specifying a retention time other than V(keep-all=1) might trigger pruning on the datastore, if an existing backup should be deleted
due to your specified timeframe.
- Deleting requires C(Datastore.Modify) or C(Datastore.Prune) permissions on the backup storage.
type: str
storage:
Expand Down Expand Up @@ -153,9 +141,9 @@
- community.general.proxmox.actiongroup_proxmox
- community.general.proxmox.documentation
- community.general.attributes
'''
"""

EXAMPLES = r'''
EXAMPLES = r"""
- name: Backup all vms in the Proxmox cluster to storage mypbs
community.general.proxmox_backup:
api_user: root@pam
Expand Down Expand Up @@ -204,9 +192,9 @@
vmids:
- 100
- 101
'''
"""

RETURN = r'''
RETURN = r"""
backups:
description: List of nodes and their task IDs.
returned: on success
Expand All @@ -223,13 +211,12 @@
type: str
choices: ["unknown", "success", "failed"]
upid:
description: >
Proxmox cluster UPID, which is needed to lookup task info.
Returns OK, when a cluster node did not create a task after being called,
e.g. due to no matching targets.
description: >-
Proxmox cluster UPID, which is needed to lookup task info. Returns OK, when a cluster node did not create a task after being called, for
example due to no matching targets.
returned: on success
type: str
'''
"""

import time

Expand Down
Loading
Loading