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