diff --git a/Makefile b/Makefile index 475c69dd..0c0e0517 100644 --- a/Makefile +++ b/Makefile @@ -12,6 +12,11 @@ build: install: clean build ansible-galaxy collection install *.tar.gz --force -p $(COLLECTIONS_PATH) +gendocs: + mkdir -p docs + rm -f docs/* + ansible-doc-extractor --template=template/module.rst.j2 docs plugins/modules/*.py + integration-test: $(INTEGRATION_CONFIG) ansible-test integration $(TEST_ARGS) diff --git a/README.md b/README.md index 260fc0dc..8ecb3291 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,21 @@ A collection may contain metadata that identifies these versions. PEP440 is the schema used to describe the versions of Ansible. + +### Modules +Name | Description +--- | --- +[linode.cloud.instance](https://github.com/linode/ansible_linode/blob/master/docs/instance.rst)|Create and destroy Linodes. +[linode.cloud.instance_info](https://github.com/linode/ansible_linode/blob/master/docs/instance_info.rst)|Gather info about an existing Linode instance. +[linode.cloud.nodebalancer](https://github.com/linode/ansible_linode/blob/master/docs/nodebalancer.rst)|Create, destroy, and configure NodeBalancers. +[linode.cloud.nodebalancer_info](https://github.com/linode/ansible_linode/blob/master/docs/nodebalancer_info.rst)|Gather info about an existing NodeBalancer. +[linode.cloud.object_cluster_info](https://github.com/linode/ansible_linode/blob/master/docs/object_cluster_info.rst)|Gather info about Object Storage clusters. +[linode.cloud.object_keys](https://github.com/linode/ansible_linode/blob/master/docs/object_keys.rst)|Create and destroy Object Storage keys. +[linode.cloud.volume](https://github.com/linode/ansible_linode/blob/master/docs/volume.rst)|Create, destroy, and attach Linode volumes. +[linode.cloud.volume_info](https://github.com/linode/ansible_linode/blob/master/docs/volume_info.rst)|Gather info about an existing Linode volume. + + + ## Installation You can install the Linode collection with the Ansible Galaxy CLI: diff --git a/docs/instance.rst b/docs/instance.rst new file mode 100644 index 00000000..e6ff8f85 --- /dev/null +++ b/docs/instance.rst @@ -0,0 +1,200 @@ +.. _instance_module: + + +instance +======== + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- + +Manage Linode instances. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- linode_api4 >= 3.0 + + + +Parameters +---------- + + label (True, string, None) + The unique label to give this instance. + + + type (optional, any, None) + The type or plan of this instance. + + See https://api.linode.com/v4/linode/types + + + region (True, str, None) + The location to deploy the instance in. + + See https://api.linode.com/v4/regions + + + image (True, str, None) + The image ID to deploy the instance disk from. + + + group (False, str, None) + 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. + + + tags (False, list, None) + The tags that the instance should be marked under. + + See https://www.linode.com/docs/api/tags/. + + + root_pass (False, str, None) + The password for the root user. If not specified, one will be generated. This generated password will be available in the task success JSON. + + + private_ip (False, bool, None) + If true, the created Linode will have private networking enabled. + + + authorized_keys (False, list, None) + A list of SSH public key parts to deploy for the root user. + + + stackscript_id (False, int, None) + The ID of the StackScript to use when creating the instance. See https://www.linode.com/docs/api/stackscripts/. + + + stackscript_data (False, dict, None) + 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 https://www.linode.com/docs/api/stackscripts/. + + + state (optional, str, None) + The desired instance state. + + + + + + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + - name: Create a new Linode instance. + linode.cloud.instance: + label: my-linode + type: g6-nanode-1 + region: us-east + image: linode/ubuntu20.04 + root_pass: verysecurepassword!!! + private_ip: false + authorized_keys: + - "ssh-rsa ..." + stackscript_id: 1337 + stackscript_data: + variable: value + group: app + tags: + - env=prod + state: present + + - name: Delete that new Linode instance. + linode.cloud.instance: + label: my-linode + state: absent + + + + +Return Values +------------- + +**instance (always, dict):** + +The instance description in JSON serialized form. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + { + "alerts": { + "cpu": 90, + "io": 10000, + "network_in": 10, + "network_out": 10, + "transfer_quota": 80 + }, + "backups": { + "enabled": false, + "schedule": { + "day": null, + "window": null + } + }, + "created": "2018-09-26T08:12:33", + "group": "app", + "hypervisor": "kvm", + "id": "xxxxxx", + "image": "linode/ubuntu20.04", + "ipv4": [ + "xxx.xxx.xxx.xxx" + ], + "ipv6": "xxxx:xxxx::xxxx:xxxx:xxxx:xxxx/64", + "label": "my-linode", + "region": "us-east", + "root_pass": "foobar", + "specs": { + "disk": 25600, + "memory": 1024, + "transfer": 1000, + "vcpus": 1 + }, + "status": "running", + "tags": [ + "env=prod" + ], + "type": "g6-nanode-1", + "updated": "2018-09-26T10:10:14", + "watchdog_enabled": true + } + + + + + +Status +------ + + + + +- This module is maintained by Linode. + + + +Authors +~~~~~~~ + +- Luke Murphy (@decentral1se) +- Charles Kenney (@charliekenney23) +- Phillip Campbell (@phillc) +- Lena Garber (@lbgarber) + diff --git a/docs/instance_info.rst b/docs/instance_info.rst new file mode 100644 index 00000000..a1417260 --- /dev/null +++ b/docs/instance_info.rst @@ -0,0 +1,138 @@ +.. _instance_info_module: + + +instance_info +============= + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- + +Get info about a Linode instance. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- linode_api4 >= 3.0 + + + +Parameters +---------- + + label (optional, string, None) + The instance’s label. + + + id (optional, int, None) + The unique id of the instance. + + + + + + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + - name: Get info about an instance by label + linode.cloud.instance_info: + label: 'my-instance' + + - name: Get info about an instance by id + linode.cloud.instance_info: + id: 12345 + + + + +Return Values +------------- + +**instance (always, dict):** + +The instance description in JSON serialized form. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + { + "alerts": { + "cpu": 90, + "io": 10000, + "network_in": 10, + "network_out": 10, + "transfer_quota": 80 + }, + "backups": { + "enabled": false, + "schedule": { + "day": null, + "window": null + } + }, + "created": "xxxx-xx-xxTxx:xx:xx", + "group": "app", + "hypervisor": "kvm", + "id": "xxxxxx", + "image": "linode/ubuntu20.04", + "ipv4": [ + "xxx.xxx.xxx.xxx" + ], + "ipv6": "xxxx:xxxx::xxxx:xxxx:xxxx:xxxx/64", + "label": "my-linode", + "region": "us-east", + "specs": { + "disk": 25600, + "memory": 1024, + "transfer": 1000, + "vcpus": 1 + }, + "status": "running", + "tags": [ + "env=prod" + ], + "type": "g6-nanode-1", + "updated": "xxxx-xx-xxTxx:xx:xx", + "watchdog_enabled": true + } + + + + + +Status +------ + + + + +- This module is maintained by Linode. + + + +Authors +~~~~~~~ + +- Luke Murphy (@decentral1se) +- Charles Kenney (@charliekenney23) +- Phillip Campbell (@phillc) +- Lena Garber (@lbgarber) + diff --git a/docs/nodebalancer.rst b/docs/nodebalancer.rst new file mode 100644 index 00000000..dbdeb259 --- /dev/null +++ b/docs/nodebalancer.rst @@ -0,0 +1,284 @@ +.. _nodebalancer_module: + + +nodebalancer +============ + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- + +Manage Linode NodeBalancers. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- linode_api4 >= 3.0 + + + +Parameters +---------- + + label (True, string, None) + The unique label to give this NodeBalancer + + + region (True, str, None) + The location to deploy the instance in. + + See https://api.linode.com/v4/regions + + + configs (False, list, None) + A list of configs to be added to the NodeBalancer. + + + algorithm (optional, str, None) + What algorithm this NodeBalancer should use for routing traffic to backends. + + + check (optional, str, None) + The type of check to perform against backends to ensure they are serving requests. + + This is used to determine if backends are up or down. + + + check_attempts (optional, int, None) + How many times to attempt a check before considering a backend to be down. + + + check_body (optional, str, None) + This value must be present in the response body of the check in order for it to pass. + + If this value is not present in the response body of a check request, the backend is considered to be down. + + + check_interval (optional, int, None) + How often, in seconds, to check that backends are up and serving requests. + + + check_passive (optional, bool, None) + If true, any response from this backend with a 5xx status code will be enough for it to be considered unhealthy and taken out of rotation. + + + check_path (optional, str, None) + The URL path to check on each backend. If the backend does not respond to this request it is considered to be down. + + + check_timeout (optional, int, None) + How long, in seconds, to wait for a check attempt before considering it failed. + + + cipher_suite (optional, str, recommended) + What ciphers to use for SSL connections served by this NodeBalancer. + + ``legacy`` is considered insecure and should only be used if necessary. + + + port (optional, int, None) + The port for the Config to listen on. + + + protocol (optional, str, None) + The protocol this port is configured to serve. + + + proxy_protocol (optional, str, None) + ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. + + + ssl_cert (optional, str, None) + The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL certificate and Certificate Authority chain) that should be served on this NodeBalancerConfig’s port. + + + ssl_key (optional, str, None) + The PEM-formatted private key for the SSL certificate set in the ssl_cert field. + + + stickiness (optional, str, None) + Controls how session stickiness is handled on this port. + + + nodes (optional, list, None) + A list of Nodes to be created with the parent Config. + + + label (True, str, None) + The label to give to this Node. + + + address (True, str, None) + The private IP Address where this backend can be reached. + + + mode (optional, str, None) + The mode this NodeBalancer should use when sending traffic to this backend. + + + weight (optional, int, None) + Nodes with a higher weight will receive more traffic. + + + + + + + + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + - name: Create a Linode NodeBalancer + linode.cloud.nodebalancer: + label: my-loadbalancer + region: us-east + tags: [ prod-env ] + state: present + configs: + - port: 80 + protocol: http + algorithm: roundrobin + nodes: + - label: node1 + address: 0.0.0.0:80 + + - name: Delete the NodeBalancer + linode.cloud.nodebalancer: + label: my-loadbalancer + region: us-east + state: absent + + + + +Return Values +------------- + +**nodebalancer (always, dict):** + +The NodeBalancer in JSON serialized form. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + { + "client_conn_throttle": 0, + "created": "", + "hostname": "xxxx.newark.nodebalancer.linode.com", + "id": "xxxxxx", + "ipv4": "xxx.xxx.xxx.xxx", + "ipv6": "xxxx:xxxx::xxxx:xxxx:xxxx:xxxx", + "label": "my-loadbalancer", + "region": "us-east", + "tags": [], + "transfer": { + "in": 0, + "out": 0, + "total": 0 + }, + "updated": "" + } + + +**configs (always, list):** + +A list of configs applied to the NodeBalancer. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + [ + { + "algorithm": "roundrobin", + "check": "none", + "check_attempts": 3, + "check_body": "", + "check_interval": 0, + "check_passive": true, + "check_path": "", + "check_timeout": 30, + "cipher_suite": "recommended", + "id": "xxxxxx", + "nodebalancer_id": "xxxxxx", + "nodes_status": { + "down": 1, + "up": 0 + }, + "port": 80, + "protocol": "http", + "proxy_protocol": "none", + "ssl_cert": null, + "ssl_commonname": "", + "ssl_fingerprint": "", + "ssl_key": null, + "stickiness": "none" + } + ] + + +**nodes (always, list):** + +A list of all nodes associated with the NodeBalancer. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + [ + { + "address": "xxx.xxx.xxx.xx:80", + "config_id": "xxxxxx", + "id": "xxxxxx", + "label": "node1", + "mode": "accept", + "nodebalancer_id": "xxxxxx", + "status": "Unknown", + "weight": 1 + } + ] + + + + + +Status +------ + + + + +- This module is maintained by Linode. + + + +Authors +~~~~~~~ + +- Luke Murphy (@decentral1se) +- Charles Kenney (@charliekenney23) +- Phillip Campbell (@phillc) +- Lena Garber (@lbgarber) + diff --git a/docs/nodebalancer_info.rst b/docs/nodebalancer_info.rst new file mode 100644 index 00000000..35c529bd --- /dev/null +++ b/docs/nodebalancer_info.rst @@ -0,0 +1,178 @@ +.. _nodebalancer_info_module: + + +nodebalancer_info +================= + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- + +Get info about a NodeBalancer. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- linode_api4 >= 3.0 + + + +Parameters +---------- + + label (optional, string, None) + The label of this NodeBalancer + + + id (optional, int, None) + The unique id of this NodeBalancer + + + + + + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + - name: Get a NodeBalancer by its id + linode.cloud.nodebalancer_info: + id: 12345 + + - name: Get a NodeBalancer by its label + linode.cloud.nodebalancer_info: + label: cool_nodebalancer + + + + +Return Values +------------- + +**nodebalancer (always, dict):** + +The NodeBalancer in JSON serialized form. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + { + "client_conn_throttle": 0, + "created": "", + "hostname": "xxxx.newark.nodebalancer.linode.com", + "id": "xxxxxx", + "ipv4": "xxx.xxx.xxx.xxx", + "ipv6": "xxxx:xxxx::xxxx:xxxx:xxxx:xxxx", + "label": "my-loadbalancer", + "region": "us-east", + "tags": [], + "transfer": { + "in": 0, + "out": 0, + "total": 0 + }, + "updated": "" + } + + +**configs (always, list):** + +A list of configs applied to the NodeBalancer. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + [ + { + "algorithm": "roundrobin", + "check": "none", + "check_attempts": 3, + "check_body": "", + "check_interval": 0, + "check_passive": true, + "check_path": "", + "check_timeout": 30, + "cipher_suite": "recommended", + "id": "xxxxxx", + "nodebalancer_id": "xxxxxx", + "nodes_status": { + "down": 1, + "up": 0 + }, + "port": 80, + "protocol": "http", + "proxy_protocol": "none", + "ssl_cert": null, + "ssl_commonname": "", + "ssl_fingerprint": "", + "ssl_key": null, + "stickiness": "none" + } + ] + + +**nodes (always, list):** + +A list of all nodes associated with the NodeBalancer. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + [ + { + "address": "xxx.xxx.xxx.xx:80", + "config_id": "xxxxxx", + "id": "xxxxxx", + "label": "node1", + "mode": "accept", + "nodebalancer_id": "xxxxxx", + "status": "Unknown", + "weight": 1 + } + ] + + + + + +Status +------ + + + + +- This module is maintained by Linode. + + + +Authors +~~~~~~~ + +- Luke Murphy (@decentral1se) +- Charles Kenney (@charliekenney23) +- Phillip Campbell (@phillc) +- Lena Garber (@lbgarber) + diff --git a/docs/object_cluster_info.rst b/docs/object_cluster_info.rst new file mode 100644 index 00000000..b1474e24 --- /dev/null +++ b/docs/object_cluster_info.rst @@ -0,0 +1,115 @@ +.. _object_cluster_info_module: + + +object_cluster_info +=================== + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- + +Get information about an Object Storage cluster. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- linode_api4 >= 3.0 + + + +Parameters +---------- + + id (optional, string, None) + The unique id given to the clusters + + + region (optional, string, None) + The region the clusters are in + + + domain (optional, string, None) + The domain of the clusters + + + static_site_domain (optional, string, None) + The static-site domain of the clusters + + + + + + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + - name: Get info about clusters in us-east + linode.cloud.object_cluster_info: + region: us-east + + - name: Get info about the cluster with id us-east-1 + linode.cloud.object_cluster_info: + id: us-east-1 + + + + +Return Values +------------- + +**clusters (always, list):** + +The Object Storage clusters in JSON serialized form. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + [ + { + "domain": "us-east-1.linodeobjects.com", + "id": "us-east-1", + "region": "us-east", + "static_site_domain": "website-us-east-1.linodeobjects.com", + "status": "available" + } + ] + + + + + +Status +------ + + + + +- This module is maintained by Linode. + + + +Authors +~~~~~~~ + +- Luke Murphy (@decentral1se) +- Charles Kenney (@charliekenney23) +- Phillip Campbell (@phillc) +- Lena Garber (@lbgarber) + diff --git a/docs/object_keys.rst b/docs/object_keys.rst new file mode 100644 index 00000000..e872be07 --- /dev/null +++ b/docs/object_keys.rst @@ -0,0 +1,136 @@ +.. _object_keys_module: + + +object_keys +=========== + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- + +Manage Linode Object Storage Keys. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- linode_api4 >= 3.0 + + + +Parameters +---------- + + label (True, string, None) + The unique label to give this key + + + access (False, list, None) + A list of access permissions to give the key. + + + cluster (True, str, None) + The id of the cluster that the provided bucket exists under. + + + bucket_name (True, str, None) + The name of the bucket to set the key's permissions for. + + + permissions (True, str, None) + The permissions to give the key. + + + + + + + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + - name: Create an Object Storage key + linode.cloud.object_keys: + label: 'my-fullaccess-key' + state: present + + - name: Create a limited Object Storage key + linode.cloud.object_keys: + label: 'my-limited-key' + access: + - cluster: us-east-1 + bucket_name: my-bucket + permissions: read_write + state: present + + - name: Remove an object storage key + linode.cloud.object_keys: + label: 'my-key' + state: absent + + + + +Return Values +------------- + +**key (always, dict):** + +The Object Storage key in JSON serialized form. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + { + "access_key": "xxxxxxxxxxxxxxxxx", + "bucket_access": [ + { + "bucket_name": "my-bucket", + "cluster": "us-east-1", + "permissions": "read_write" + } + ], + "id": "xxxxx", + "label": "my-key", + "limited": true, + "secret_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxx" + } + + + + + +Status +------ + + + + +- This module is maintained by Linode. + + + +Authors +~~~~~~~ + +- Luke Murphy (@decentral1se) +- Charles Kenney (@charliekenney23) +- Phillip Campbell (@phillc) +- Lena Garber (@lbgarber) + diff --git a/docs/volume.rst b/docs/volume.rst new file mode 100644 index 00000000..84bf58c3 --- /dev/null +++ b/docs/volume.rst @@ -0,0 +1,157 @@ +.. _volume_module: + + +volume +====== + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- + +Manage Linode volumes. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- linode_api4 >= 3.0 + + + +Parameters +---------- + + label (True, string, None) + The Volume’s label, which is also used in the filesystem_path of the resulting volume. + + + region (optional, str, None) + The location to deploy the volume in. + + See https://api.linode.com/v4/regions + + + size (optional, int, None) + The size of this volume, in GB. + + Be aware that volumes may only be resized up after creation. + + + linode_id (optional, int, None) + The Linode this volume should be attached to upon creation. + + If not given, the volume will be created without an attachment. + + + config_id (optional, int, None) + When creating a Volume attached to a Linode, the ID of the Linode Config to include the new Volume in. + + + attached (optional, bool, None) + If true, the volume will be attached to a Linode. Otherwise, the volume will be detached. + + + + + + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + - name: Create a volume attached to an instance + linode.cloud.volume: + label: example-volume + region: us-east + size: 30 + linode_id: 12345 + state: present + + - name: Create an unattached volume + linode.cloud.volume: + label: example-volume + region: us-east + size: 30 + state: present + + - name: Resize a volume + linode.cloud.volume: + label: example-volume + size: 50 + state: present + + - name: Detach a volume + linode.cloud.volume: + label: example-volume + attached: false + state: present + + - name: Delete a volume + linode.cloud.volume: + label: example-volume + state: absent + + + + +Return Values +------------- + +**volume (always, dict):** + +The volume in JSON serialized form. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + { + "created": "", + "filesystem_path": "/dev/disk/by-id/xxxxxx", + "id": "xxxxxx", + "label": "xxxxxx", + "linode_id": "xxxxxx", + "linode_label": "xxxxxx", + "region": "us-east", + "size": 30, + "status": "creating", + "tags": [], + "updated": "2021-03-05T19:05:33" + } + + + + + +Status +------ + + + + +- This module is maintained by Linode. + + + +Authors +~~~~~~~ + +- Luke Murphy (@decentral1se) +- Charles Kenney (@charliekenney23) +- Phillip Campbell (@phillc) +- Lena Garber (@lbgarber) + diff --git a/docs/volume_info.rst b/docs/volume_info.rst new file mode 100644 index 00000000..e6a87071 --- /dev/null +++ b/docs/volume_info.rst @@ -0,0 +1,111 @@ +.. _volume_info_module: + + +volume_info +=========== + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- + +Get info about a Linode volume. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 2.7 +- linode_api4 >= 3.0 + + + +Parameters +---------- + + label (optional, string, None) + The Volume’s label. + + + id (optional, int, None) + The unique id of the volume. + + + + + + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + - name: Get info about a volume by label + linode.cloud.volume_info: + label: example-volume + + - name: Get info about a volume by id + linode.cloud.volume_info: + id: 12345 + + + + +Return Values +------------- + +**volume (always, dict):** + +The volume in JSON serialized form. + +`Linode Response Object Documentation `_ + +Sample Response: + +.. code-block:: JSON + + { + "created": "", + "filesystem_path": "/dev/disk/by-id/xxxxxx", + "id": "xxxxxx", + "label": "xxxxxx", + "linode_id": "xxxxxx", + "linode_label": "xxxxxx", + "region": "us-east", + "size": 30, + "status": "creating", + "tags": [], + "updated": "2021-03-05T19:05:33" + } + + + + + +Status +------ + + + + +- This module is maintained by Linode. + + + +Authors +~~~~~~~ + +- Luke Murphy (@decentral1se) +- Charles Kenney (@charliekenney23) +- Phillip Campbell (@phillc) +- Lena Garber (@lbgarber) + diff --git a/plugins/modules/instance.py b/plugins/modules/instance.py index 31d2e858..25f8311c 100644 --- a/plugins/modules/instance.py +++ b/plugins/modules/instance.py @@ -126,6 +126,7 @@ RETURN = ''' instance: description: The instance description in JSON serialized form. + linode_api_docs: "https://www.linode.com/docs/api/linode-instances/#linode-view__responses" returned: always type: dict sample: { diff --git a/plugins/modules/instance_info.py b/plugins/modules/instance_info.py index 61c1d2aa..77085e7e 100644 --- a/plugins/modules/instance_info.py +++ b/plugins/modules/instance_info.py @@ -52,6 +52,7 @@ RETURN = ''' instance: description: The instance description in JSON serialized form. + linode_api_docs: "https://www.linode.com/docs/api/linode-instances/#linode-view__responses" returned: always type: dict sample: { diff --git a/plugins/modules/nodebalancer.py b/plugins/modules/nodebalancer.py index f995565e..34bb38c4 100644 --- a/plugins/modules/nodebalancer.py +++ b/plugins/modules/nodebalancer.py @@ -212,6 +212,7 @@ RETURN = ''' nodebalancer: description: The NodeBalancer in JSON serialized form. + linode_api_docs: "https://www.linode.com/docs/api/nodebalancers/#nodebalancer-view__responses" returned: always type: dict sample: { @@ -236,6 +237,7 @@ configs: description: A list of configs applied to the NodeBalancer. + linode_api_docs: "https://www.linode.com/docs/api/nodebalancers/#config-view__responses" returned: always type: list sample: [ @@ -268,6 +270,7 @@ nodes: description: A list of all nodes associated with the NodeBalancer. + linode_api_docs: "https://www.linode.com/docs/api/nodebalancers/#node-view__responses" returned: always type: list sample: [ diff --git a/plugins/modules/nodebalancer_info.py b/plugins/modules/nodebalancer_info.py index 56bf6bb0..dc1df258 100644 --- a/plugins/modules/nodebalancer_info.py +++ b/plugins/modules/nodebalancer_info.py @@ -55,6 +55,7 @@ nodebalancer: description: The NodeBalancer in JSON serialized form. + linode_api_docs: "https://www.linode.com/docs/api/nodebalancers/#nodebalancer-view__responses" returned: always type: dict sample: { @@ -79,6 +80,7 @@ configs: description: A list of configs applied to the NodeBalancer. + linode_api_docs: "https://www.linode.com/docs/api/nodebalancers/#config-view__responses" returned: always type: list sample: [ @@ -111,6 +113,7 @@ nodes: description: A list of all nodes associated with the NodeBalancer. + linode_api_docs: "https://www.linode.com/docs/api/nodebalancers/#node-view__responses" returned: always type: list sample: [ diff --git a/plugins/modules/object_cluster_info.py b/plugins/modules/object_cluster_info.py index 1df408f8..dfc76af2 100644 --- a/plugins/modules/object_cluster_info.py +++ b/plugins/modules/object_cluster_info.py @@ -59,6 +59,7 @@ RETURN = ''' clusters: description: The Object Storage clusters in JSON serialized form. + linode_api_docs: "https://www.linode.com/docs/api/object-storage/#cluster-view__responses" returned: always type: list elements: dict diff --git a/plugins/modules/object_keys.py b/plugins/modules/object_keys.py index aa3a068b..06bcd04c 100644 --- a/plugins/modules/object_keys.py +++ b/plugins/modules/object_keys.py @@ -84,6 +84,7 @@ RETURN = ''' key: description: The Object Storage key in JSON serialized form. + linode_api_docs: "https://www.linode.com/docs/api/object-storage/#object-storage-key-view__responses" returned: always type: dict sample: { diff --git a/plugins/modules/volume.py b/plugins/modules/volume.py index 887cfc46..fdf7c9ed 100644 --- a/plugins/modules/volume.py +++ b/plugins/modules/volume.py @@ -95,6 +95,7 @@ RETURN = ''' volume: description: The volume in JSON serialized form. + linode_api_docs: "https://www.linode.com/docs/api/volumes/#volume-view__responses" returned: always type: dict sample: { diff --git a/plugins/modules/volume_info.py b/plugins/modules/volume_info.py index 82974dec..cd47891c 100644 --- a/plugins/modules/volume_info.py +++ b/plugins/modules/volume_info.py @@ -52,6 +52,7 @@ RETURN = ''' volume: description: The volume in JSON serialized form. + linode_api_docs: "https://www.linode.com/docs/api/volumes/#volume-view__responses" returned: always type: dict sample: { diff --git a/requirements-dev.txt b/requirements-dev.txt index 8097b6ec..9c24b676 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,3 +1,4 @@ boto3==1.17.23 botocore==1.20.23 -pylint==2.7.2 \ No newline at end of file +pylint==2.7.2 +ansible-doc-extractor==0.1.6 \ No newline at end of file diff --git a/template/module.rst.j2 b/template/module.rst.j2 new file mode 100644 index 00000000..89cb2700 --- /dev/null +++ b/template/module.rst.j2 @@ -0,0 +1,186 @@ +.. _{{ module }}_module: + +{% if short_description %} +{% set title = module + ' -- ' + short_description | rst_ify %} +{% else %} +{% set title = module %} +{% endif %} + +{{ title }} +{{ '=' * title|length }} + +.. contents:: + :local: + :depth: 1 + + +{% if description -%} +Synopsis +-------- + +{% for desc in description %} +{{ desc | rst_ify }} + +{% endfor %} +{% endif %} + + +{% if requirements -%} +Requirements +------------ +The below requirements are needed on the host that executes this module. + +{% for req in requirements %} +- {{ req | rst_ify }} +{% endfor %} +{% endif %} + + +{% macro option_desc(opts, level) %} +{% for name, spec in opts.items() %} +{% set req = spec.required | default("optional") %} +{% set typ = spec.type | default("any") %} +{% set def_val = spec.default | default("None") %} + {{ " " * level }}{{ name }} ({{ req }}, {{ typ }}, {{ def_val }}) +{% for para in spec.description %} + {{ " " * level }}{{ para | rst_ify }} + +{% endfor %} + +{% if spec.suboptions %} +{{ option_desc(spec.suboptions, level + 1) }} +{% endif %} +{% endfor %} +{% endmacro %} + +{% if options -%} +Parameters +---------- + +{{ option_desc(options, 0) }} +{% endif %} + + +{% if notes -%} +Notes +----- + +.. note:: +{% for note in notes %} + - {{ note | rst_ify }} +{% endfor %} +{% endif %} + + +{% if seealso -%} +See Also +-------- + +.. seealso:: + +{% for item in seealso %} +{% if item.module is defined and item.description is defined %} + :ref:`{{ item.module }}_module` + {{ item.description | rst_ify }} +{% elif item.module is defined %} + :ref:`{{ item.module }}_module` + The official documentation on the **{{ item.module }}** module. +{% elif item.name is defined and item.link is defined and item.description is defined %} + `{{ item.name }} <{{ item.link }}>`_ + {{ item.description | rst_ify }} +{% elif item.ref is defined and item.description is defined %} + :ref:`{{ item.ref }}` + {{ item.description | rst_ify }} +{% endif %} +{% endfor %} +{% endif %} + + +{% if examples -%} +Examples +-------- + +.. code-block:: yaml+jinja + +{{ examples | indent(4, True) }} +{% endif %} + +{% macro result_desc(results, level) %} +{% for name, spec in results.items() %} +{% set ret = spec.returned %} +{% set typ = spec.type | default("any") %} +{% set sample = spec.sample %} +{% set api_docs = spec.linode_api_docs %} +{{ " " * level }}**{{ name }} ({{ ret }}, {{ typ }}):** + +{% for para in spec.description %} +{{ " " * level }}{{ para | rst_ify }} +{% endfor %} + +`Linode Response Object Documentation <{{ api_docs }}>`_ + +Sample Response: + +.. code-block:: JSON + +{{ sample | tojson(indent=True) | indent(4, True) }} + + +{% if spec.contains %} +{{ result_desc(spec.contains, level + 1) }} +{% endif %} +{% endfor %} +{% endmacro %} + + +{% if returndocs -%} +Return Values +------------- + +{{ result_desc(returndocs, 0) }} +{% endif %} + + +Status +------ + +{% if deprecated %} + +- This {{ plugin_type }} will be removed in version + {{ deprecated['removed_in'] | default('') | string | rst_ify }}. + *[deprecated]* + +{% else %} + +{% set module_states = { + "preview": "not guaranteed to have a backwards compatible interface", + "stableinterface": "guaranteed to have backward compatible interface changes going forward", + } +%} + +{% if metadata %} +{% if metadata.status %} + +{% for cur_state in metadata.status %} +- This {{ plugin_type }} is {{ module_states[cur_state] }}. *[{{ cur_state }}]* +{% endfor %} + +{% endif %} + +{% if metadata.supported_by %} +- This {{ plugin_type }} is maintained by {{ metadata.supported_by }}. +{% endif %} + +{% endif %} + +{% endif %} + +{% if author is defined -%} +Authors +~~~~~~~ + +{% for author_name in author %} +- {{ author_name }} +{% endfor %} + +{% endif %} \ No newline at end of file