[PR #9281/1b6c0517 backport][stable-9] zfs modules: adjust docs (#9304)
zfs modules: adjust docs (#9281)
* zfs modules: adjust docs
* Apply suggestions from code review
* fix examples indentation
* Update plugins/modules/zfs.py
Co-authored-by: Felix Fontein <felix@fontein.de>
---------
Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit 1b6c05176b)
Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
pull/9313/head
patchback[bot]
GitHub
parent
3f5445274c
commit
861cbc29be
|
|
@ -9,23 +9,20 @@
|
|||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: zfs
|
||||
short_description: Manage zfs
|
||||
short_description: Manage ZFS
|
||||
description:
|
||||
- Manages ZFS file systems, volumes, clones and snapshots
|
||||
- Manages ZFS file systems, volumes, clones and snapshots.
|
||||
extends_documentation_fragment:
|
||||
- community.general.attributes
|
||||
attributes:
|
||||
check_mode:
|
||||
support: partial
|
||||
details:
|
||||
- In certain situations it may report a task as changed that will not be reported
|
||||
as changed when C(check_mode) is disabled.
|
||||
- For example, this might occur when the zpool C(altroot) option is set or when
|
||||
a size is written using human-readable notation, such as V(1M) or V(1024K),
|
||||
instead of as an unqualified byte count, such as V(1048576).
|
||||
- In certain situations it may report a task as changed that will not be reported as changed when C(check_mode) is disabled.
|
||||
- For example, this might occur when the zpool C(altroot) option is set or when a size is written using human-readable notation, such as
|
||||
V(1M) or V(1024K), instead of as an unqualified byte count, such as V(1048576).
|
||||
diff_mode:
|
||||
support: full
|
||||
options:
|
||||
|
|
@ -36,10 +33,9 @@ options:
|
|||
type: str
|
||||
state:
|
||||
description:
|
||||
- Whether to create (V(present)), or remove (V(absent)) a
|
||||
file system, snapshot or volume. All parents/children
|
||||
will be created/destroyed as needed to reach the desired state.
|
||||
choices: [ absent, present ]
|
||||
- Whether to create (V(present)), or remove (V(absent)) a file system, snapshot or volume. All parents/children will be created/destroyed
|
||||
as needed to reach the desired state.
|
||||
choices: [absent, present]
|
||||
required: true
|
||||
type: str
|
||||
origin:
|
||||
|
|
@ -53,10 +49,10 @@ options:
|
|||
type: dict
|
||||
default: {}
|
||||
author:
|
||||
- Johan Wiren (@johanwiren)
|
||||
'''
|
||||
- Johan Wiren (@johanwiren)
|
||||
"""
|
||||
|
||||
EXAMPLES = '''
|
||||
EXAMPLES = r"""
|
||||
- name: Create a new file system called myfs in pool rpool with the setuid property turned off
|
||||
community.general.zfs:
|
||||
name: rpool/myfs
|
||||
|
|
@ -93,7 +89,7 @@ EXAMPLES = '''
|
|||
community.general.zfs:
|
||||
name: rpool/myfs
|
||||
state: absent
|
||||
'''
|
||||
"""
|
||||
|
||||
import os
|
||||
|
||||
|
|
|
|||
|
|
@ -8,18 +8,17 @@
|
|||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
DOCUMENTATION = r'''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: zfs_delegate_admin
|
||||
short_description: Manage ZFS delegated administration (user admin privileges)
|
||||
description:
|
||||
- Manages ZFS file system delegated administration permissions, which allow unprivileged users to perform ZFS
|
||||
operations normally restricted to the superuser.
|
||||
- Manages ZFS file system delegated administration permissions, which allow unprivileged users to perform ZFS operations normally restricted
|
||||
to the superuser.
|
||||
- See the C(zfs allow) section of V(zfs(1M\)) for detailed explanations of options.
|
||||
- This module attempts to adhere to the behavior of the command line tool as much as possible.
|
||||
requirements:
|
||||
- "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all
|
||||
versions), FreeBSD >= 8.0R, ZFS on Linux >= 0.7.0."
|
||||
- "A ZFS/OpenZFS implementation that supports delegation with C(zfs allow), including: Solaris >= 10, illumos (all versions), FreeBSD >= 8.0R,
|
||||
ZFS on Linux >= 0.7.0."
|
||||
extends_documentation_fragment:
|
||||
- community.general.attributes
|
||||
attributes:
|
||||
|
|
@ -38,7 +37,7 @@ options:
|
|||
- Whether to allow (V(present)), or unallow (V(absent)) a permission.
|
||||
- When set to V(present), at least one "entity" param of O(users), O(groups), or O(everyone) are required.
|
||||
- When set to V(absent), removes permissions from the specified entities, or removes all permissions if no entity params are specified.
|
||||
choices: [ absent, present ]
|
||||
choices: [absent, present]
|
||||
default: present
|
||||
type: str
|
||||
users:
|
||||
|
|
@ -59,8 +58,8 @@ options:
|
|||
permissions:
|
||||
description:
|
||||
- The list of permission(s) to delegate (required if O(state=present)).
|
||||
- Supported permissions depend on the ZFS version in use. See for example
|
||||
U(https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html) for OpenZFS.
|
||||
- Supported permissions depend on the ZFS version in use. See for example U(https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html)
|
||||
for OpenZFS.
|
||||
type: list
|
||||
elements: str
|
||||
local:
|
||||
|
|
@ -77,10 +76,10 @@ options:
|
|||
type: bool
|
||||
default: false
|
||||
author:
|
||||
- Nate Coraor (@natefoo)
|
||||
'''
|
||||
- Nate Coraor (@natefoo)
|
||||
"""
|
||||
|
||||
EXAMPLES = r'''
|
||||
EXAMPLES = r"""
|
||||
- name: Grant `zfs allow` and `unallow` permission to the `adm` user with the default local+descendents scope
|
||||
community.general.zfs_delegate_admin:
|
||||
name: rpool/myfs
|
||||
|
|
@ -106,12 +105,12 @@ EXAMPLES = r'''
|
|||
name: rpool/myfs
|
||||
everyone: true
|
||||
state: absent
|
||||
'''
|
||||
"""
|
||||
|
||||
# This module does not return anything other than the standard
|
||||
# changed/state/msg/stdout
|
||||
RETURN = '''
|
||||
'''
|
||||
RETURN = r"""
|
||||
"""
|
||||
|
||||
from itertools import product
|
||||
|
||||
|
|
|
|||
|
|
@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
|
|||
__metaclass__ = type
|
||||
|
||||
|
||||
DOCUMENTATION = '''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: zfs_facts
|
||||
short_description: Gather facts about ZFS datasets
|
||||
description:
|
||||
|
|
@ -21,45 +20,42 @@ extends_documentation_fragment:
|
|||
- community.general.attributes.facts
|
||||
- community.general.attributes.facts_module
|
||||
options:
|
||||
name:
|
||||
description:
|
||||
- ZFS dataset name.
|
||||
required: true
|
||||
aliases: [ "ds", "dataset" ]
|
||||
type: str
|
||||
recurse:
|
||||
description:
|
||||
- Specifies if properties for any children should be recursively
|
||||
displayed.
|
||||
type: bool
|
||||
default: false
|
||||
parsable:
|
||||
description:
|
||||
- Specifies if property values should be displayed in machine
|
||||
friendly format.
|
||||
type: bool
|
||||
default: false
|
||||
properties:
|
||||
description:
|
||||
- Specifies which dataset properties should be queried in comma-separated format.
|
||||
For more information about dataset properties, check zfs(1M) man page.
|
||||
default: all
|
||||
type: str
|
||||
type:
|
||||
description:
|
||||
- Specifies which datasets types to display. Multiple values have to be
|
||||
provided in comma-separated form.
|
||||
choices: [ 'all', 'filesystem', 'volume', 'snapshot', 'bookmark' ]
|
||||
default: all
|
||||
type: str
|
||||
depth:
|
||||
description:
|
||||
- Specifies recursion depth.
|
||||
type: int
|
||||
default: 0
|
||||
'''
|
||||
name:
|
||||
description:
|
||||
- ZFS dataset name.
|
||||
required: true
|
||||
aliases: ["ds", "dataset"]
|
||||
type: str
|
||||
recurse:
|
||||
description:
|
||||
- Specifies if properties for any children should be recursively displayed.
|
||||
type: bool
|
||||
default: false
|
||||
parsable:
|
||||
description:
|
||||
- Specifies if property values should be displayed in machine friendly format.
|
||||
type: bool
|
||||
default: false
|
||||
properties:
|
||||
description:
|
||||
- Specifies which dataset properties should be queried in comma-separated format. For more information about dataset properties, check zfs(1M)
|
||||
man page.
|
||||
default: all
|
||||
type: str
|
||||
type:
|
||||
description:
|
||||
- Specifies which datasets types to display. Multiple values have to be provided in comma-separated form.
|
||||
choices: ['all', 'filesystem', 'volume', 'snapshot', 'bookmark']
|
||||
default: all
|
||||
type: str
|
||||
depth:
|
||||
description:
|
||||
- Specifies recursion depth.
|
||||
type: int
|
||||
default: 0
|
||||
"""
|
||||
|
||||
EXAMPLES = '''
|
||||
EXAMPLES = r"""
|
||||
- name: Gather facts about ZFS dataset rpool/export/home
|
||||
community.general.zfs_facts:
|
||||
dataset: rpool/export/home
|
||||
|
|
@ -73,88 +69,88 @@ EXAMPLES = '''
|
|||
- ansible.builtin.debug:
|
||||
msg: 'ZFS dataset {{ item.name }} consumes {{ item.used }} of disk space.'
|
||||
with_items: '{{ ansible_zfs_datasets }}'
|
||||
'''
|
||||
"""
|
||||
|
||||
RETURN = '''
|
||||
RETURN = r"""
|
||||
name:
|
||||
description: ZFS dataset name
|
||||
returned: always
|
||||
type: str
|
||||
sample: rpool/var/spool
|
||||
description: ZFS dataset name
|
||||
returned: always
|
||||
type: str
|
||||
sample: rpool/var/spool
|
||||
parsable:
|
||||
description: if parsable output should be provided in machine friendly format.
|
||||
returned: if 'parsable' is set to True
|
||||
type: bool
|
||||
sample: true
|
||||
description: if parsable output should be provided in machine friendly format.
|
||||
returned: if O(parsable=True)
|
||||
type: bool
|
||||
sample: true
|
||||
recurse:
|
||||
description: if we should recurse over ZFS dataset
|
||||
returned: if 'recurse' is set to True
|
||||
type: bool
|
||||
sample: true
|
||||
description: if we should recurse over ZFS dataset
|
||||
returned: if O(recurse=True)
|
||||
type: bool
|
||||
sample: true
|
||||
zfs_datasets:
|
||||
description: ZFS dataset facts
|
||||
returned: always
|
||||
type: str
|
||||
sample:
|
||||
{
|
||||
"aclinherit": "restricted",
|
||||
"aclmode": "discard",
|
||||
"atime": "on",
|
||||
"available": "43.8G",
|
||||
"canmount": "on",
|
||||
"casesensitivity": "sensitive",
|
||||
"checksum": "on",
|
||||
"compression": "off",
|
||||
"compressratio": "1.00x",
|
||||
"copies": "1",
|
||||
"creation": "Thu Jun 16 11:37 2016",
|
||||
"dedup": "off",
|
||||
"devices": "on",
|
||||
"exec": "on",
|
||||
"filesystem_count": "none",
|
||||
"filesystem_limit": "none",
|
||||
"logbias": "latency",
|
||||
"logicalreferenced": "18.5K",
|
||||
"logicalused": "3.45G",
|
||||
"mlslabel": "none",
|
||||
"mounted": "yes",
|
||||
"mountpoint": "/rpool",
|
||||
"name": "rpool",
|
||||
"nbmand": "off",
|
||||
"normalization": "none",
|
||||
"org.openindiana.caiman:install": "ready",
|
||||
"primarycache": "all",
|
||||
"quota": "none",
|
||||
"readonly": "off",
|
||||
"recordsize": "128K",
|
||||
"redundant_metadata": "all",
|
||||
"refcompressratio": "1.00x",
|
||||
"referenced": "29.5K",
|
||||
"refquota": "none",
|
||||
"refreservation": "none",
|
||||
"reservation": "none",
|
||||
"secondarycache": "all",
|
||||
"setuid": "on",
|
||||
"sharenfs": "off",
|
||||
"sharesmb": "off",
|
||||
"snapdir": "hidden",
|
||||
"snapshot_count": "none",
|
||||
"snapshot_limit": "none",
|
||||
"sync": "standard",
|
||||
"type": "filesystem",
|
||||
"used": "4.41G",
|
||||
"usedbychildren": "4.41G",
|
||||
"usedbydataset": "29.5K",
|
||||
"usedbyrefreservation": "0",
|
||||
"usedbysnapshots": "0",
|
||||
"utf8only": "off",
|
||||
"version": "5",
|
||||
"vscan": "off",
|
||||
"written": "29.5K",
|
||||
"xattr": "on",
|
||||
"zoned": "off"
|
||||
}
|
||||
'''
|
||||
description: ZFS dataset facts
|
||||
returned: always
|
||||
type: str
|
||||
sample:
|
||||
{
|
||||
"aclinherit": "restricted",
|
||||
"aclmode": "discard",
|
||||
"atime": "on",
|
||||
"available": "43.8G",
|
||||
"canmount": "on",
|
||||
"casesensitivity": "sensitive",
|
||||
"checksum": "on",
|
||||
"compression": "off",
|
||||
"compressratio": "1.00x",
|
||||
"copies": "1",
|
||||
"creation": "Thu Jun 16 11:37 2016",
|
||||
"dedup": "off",
|
||||
"devices": "on",
|
||||
"exec": "on",
|
||||
"filesystem_count": "none",
|
||||
"filesystem_limit": "none",
|
||||
"logbias": "latency",
|
||||
"logicalreferenced": "18.5K",
|
||||
"logicalused": "3.45G",
|
||||
"mlslabel": "none",
|
||||
"mounted": "yes",
|
||||
"mountpoint": "/rpool",
|
||||
"name": "rpool",
|
||||
"nbmand": "off",
|
||||
"normalization": "none",
|
||||
"org.openindiana.caiman:install": "ready",
|
||||
"primarycache": "all",
|
||||
"quota": "none",
|
||||
"readonly": "off",
|
||||
"recordsize": "128K",
|
||||
"redundant_metadata": "all",
|
||||
"refcompressratio": "1.00x",
|
||||
"referenced": "29.5K",
|
||||
"refquota": "none",
|
||||
"refreservation": "none",
|
||||
"reservation": "none",
|
||||
"secondarycache": "all",
|
||||
"setuid": "on",
|
||||
"sharenfs": "off",
|
||||
"sharesmb": "off",
|
||||
"snapdir": "hidden",
|
||||
"snapshot_count": "none",
|
||||
"snapshot_limit": "none",
|
||||
"sync": "standard",
|
||||
"type": "filesystem",
|
||||
"used": "4.41G",
|
||||
"usedbychildren": "4.41G",
|
||||
"usedbydataset": "29.5K",
|
||||
"usedbyrefreservation": "0",
|
||||
"usedbysnapshots": "0",
|
||||
"utf8only": "off",
|
||||
"version": "5",
|
||||
"vscan": "off",
|
||||
"written": "29.5K",
|
||||
"xattr": "on",
|
||||
"zoned": "off"
|
||||
}
|
||||
"""
|
||||
|
||||
from collections import defaultdict
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue