From 520c03b1a58ab63b9cc355d79413812beaccb694 Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 11:12:34 -0500 Subject: [PATCH 01/13] bruh --- docs/inventory/instance.rst | 178 -------- docs/modules/account_info.md | 76 ---- docs/modules/api_request.md | 86 ---- docs/modules/database_list.md | 108 ----- docs/modules/database_mysql.md | 172 -------- docs/modules/database_mysql_info.md | 124 ------ docs/modules/database_postgresql.md | 175 -------- docs/modules/database_postgresql_info.md | 125 ------ docs/modules/domain.md | 112 ----- docs/modules/domain_info.md | 98 ----- docs/modules/domain_record.md | 89 ---- docs/modules/domain_record_info.md | 75 ---- docs/modules/event_list.md | 104 ----- docs/modules/firewall.md | 223 ---------- docs/modules/firewall_device.md | 81 ---- docs/modules/firewall_info.md | 124 ------ docs/modules/image.md | 90 ---- docs/modules/image_info.md | 70 ---- docs/modules/image_list.md | 94 ----- docs/modules/instance.md | 513 ----------------------- docs/modules/instance_info.md | 279 ------------ docs/modules/ip_info.md | 58 --- docs/modules/ipv6_range_info.md | 56 --- docs/modules/lke_cluster.md | 169 -------- docs/modules/lke_cluster_info.md | 114 ----- docs/modules/lke_node_pool.md | 132 ------ docs/modules/nodebalancer.md | 183 -------- docs/modules/nodebalancer_info.md | 129 ------ docs/modules/nodebalancer_node.md | 91 ---- docs/modules/object_cluster_info.md | 65 --- docs/modules/object_keys.md | 94 ----- docs/modules/profile_info.md | 59 --- docs/modules/ssh_key.md | 63 --- docs/modules/ssh_key_info.md | 60 --- docs/modules/ssh_key_list.md | 96 ----- docs/modules/stackscript.md | 96 ----- docs/modules/stackscript_info.md | 83 ---- docs/modules/stackscript_list.md | 107 ----- docs/modules/token.md | 77 ---- docs/modules/token_info.md | 62 --- docs/modules/type_list.md | 95 ----- docs/modules/user.md | 203 --------- docs/modules/user_info.md | 130 ------ docs/modules/vlan_info.md | 56 --- docs/modules/vlan_list.md | 80 ---- docs/modules/volume.md | 107 ----- docs/modules/volume_info.md | 69 --- plugins/modules/account_info.py | 15 +- requirements-dev.txt | 2 +- 49 files changed, 9 insertions(+), 5538 deletions(-) delete mode 100644 docs/inventory/instance.rst delete mode 100644 docs/modules/account_info.md delete mode 100644 docs/modules/api_request.md delete mode 100644 docs/modules/database_list.md delete mode 100644 docs/modules/database_mysql.md delete mode 100644 docs/modules/database_mysql_info.md delete mode 100644 docs/modules/database_postgresql.md delete mode 100644 docs/modules/database_postgresql_info.md delete mode 100644 docs/modules/domain.md delete mode 100644 docs/modules/domain_info.md delete mode 100644 docs/modules/domain_record.md delete mode 100644 docs/modules/domain_record_info.md delete mode 100644 docs/modules/event_list.md delete mode 100644 docs/modules/firewall.md delete mode 100644 docs/modules/firewall_device.md delete mode 100644 docs/modules/firewall_info.md delete mode 100644 docs/modules/image.md delete mode 100644 docs/modules/image_info.md delete mode 100644 docs/modules/image_list.md delete mode 100644 docs/modules/instance.md delete mode 100644 docs/modules/instance_info.md delete mode 100644 docs/modules/ip_info.md delete mode 100644 docs/modules/ipv6_range_info.md delete mode 100644 docs/modules/lke_cluster.md delete mode 100644 docs/modules/lke_cluster_info.md delete mode 100644 docs/modules/lke_node_pool.md delete mode 100644 docs/modules/nodebalancer.md delete mode 100644 docs/modules/nodebalancer_info.md delete mode 100644 docs/modules/nodebalancer_node.md delete mode 100644 docs/modules/object_cluster_info.md delete mode 100644 docs/modules/object_keys.md delete mode 100644 docs/modules/profile_info.md delete mode 100644 docs/modules/ssh_key.md delete mode 100644 docs/modules/ssh_key_info.md delete mode 100644 docs/modules/ssh_key_list.md delete mode 100644 docs/modules/stackscript.md delete mode 100644 docs/modules/stackscript_info.md delete mode 100644 docs/modules/stackscript_list.md delete mode 100644 docs/modules/token.md delete mode 100644 docs/modules/token_info.md delete mode 100644 docs/modules/type_list.md delete mode 100644 docs/modules/user.md delete mode 100644 docs/modules/user_info.md delete mode 100644 docs/modules/vlan_info.md delete mode 100644 docs/modules/vlan_list.md delete mode 100644 docs/modules/volume.md delete mode 100644 docs/modules/volume_info.md diff --git a/docs/inventory/instance.rst b/docs/inventory/instance.rst deleted file mode 100644 index 65ce04f0..00000000 --- a/docs/inventory/instance.rst +++ /dev/null @@ -1,178 +0,0 @@ -.. _instance_module: - - -instance -======== - -.. contents:: - :local: - :depth: 1 - - -Synopsis --------- - -Reads instance inventories from Linode. - -Uses a YAML configuration file that ends with linode.(yml|yaml). - -Linode labels are used by default as the hostnames. - -The default inventory groups are built from groups (deprecated by Linode) and not tags. - - - -Requirements ------------- -The below requirements are needed on the host that executes this module. - -- python >= 3 -- linode_api4 >= 2.0.0 - - - -Parameters ----------- - - **plugin (Required, type=any):** - \• Marks this as an instance of the 'linode' plugin - - \• Options: `linode`, `linode.cloud.instance` - - - **api_token (Required, type=any):** - \• The Linode account personal access token. - - - - **regions (type=list):** - \• Populate inventory with instances in this region. - - - **tags (type=list):** - \• Populate inventory only with instances which have at least one of the tags listed here. - - - **types (type=list):** - \• Populate inventory with instances with this type. - - - **strict (type=bool):** - \• If ``yes`` make invalid entries a fatal error, otherwise skip and continue. - - \• Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default. - - - **compose (type=dict):** - \• Create vars from jinja2 expressions. - - - **groups (type=dict):** - \• Add hosts to group based on Jinja2 conditionals. - - - **keyed_groups (type=list):** - \• Add hosts to group based on the values of a variable. - - - **parent_group (type=str):** - \• parent group for keyed group - - - **prefix (type=str):** - \• A keyed group name will start with this prefix - - - **separator (type=str, default=_):** - \• separator used to build the keyed group name - - - **key (type=str):** - \• The key from input dictionary used to generate groups - - - **default_value (type=str):** - \• The default value when the host variable's value is an empty string. - - \• This option is mutually exclusive with ``trailing_separator``. - - - **trailing_separator (type=bool, default=True):** - \• Set this option to *False* to omit the ``separator`` after the host variable when the value is an empty string. - - \• This option is mutually exclusive with ``default_value``. - - - - **use_extra_vars (type=bool):** - \• Merge extra vars into the available variables for composition (highest precedence). - - - **leading_separator (type=boolean, default=True):** - \• Use in conjunction with keyed_groups. - - \• By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore. - - \• This is because the default prefix is "" and the default separator is "_". - - \• Set this option to False to omit the leading underscore (or other separator) if no prefix is given. - - \• If the group name is derived from a mapping the separator is still used to concatenate the items. - - \• To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead. - - - - - - - -Examples --------- - -.. code-block:: yaml+jinja - - - # Minimal example. `LINODE_API_TOKEN` is exposed in environment. - plugin: linode.cloud.instance - - # Example with regions, types, groups and access token - plugin: linode.cloud.instance - api_token: foobar - regions: - - eu-west - types: - - g5-standard-2 - - # Example with keyed_groups, groups, and compose - plugin: linode.cloud.instance - api_token: foobar - keyed_groups: - - key: tags - separator: '' - - key: region - prefix: region - groups: - webservers: "'web' in (tags|list)" - mailservers: "'mail' in (tags|list)" - compose: - ansible_port: 2222 - - - - - - -Status ------- - - - - - -Authors -~~~~~~~ - -- Luke Murphy (@decentral1se) -- Lena Garber (@LBGarber) - diff --git a/docs/modules/account_info.md b/docs/modules/account_info.md deleted file mode 100644 index 5ddf403c..00000000 --- a/docs/modules/account_info.md +++ /dev/null @@ -1,76 +0,0 @@ -# account_info - -Get info about a Linode Account. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about the current Linode account - linode.cloud.account_info: {} -``` - - - - - - - - - - -## Return Values - -- `account` - The account info in JSON serialized form. - - - Sample Response: - ```json - { - "active_promotions": [ - { - "credit_monthly_cap": "10.00", - "credit_remaining": "50.00", - "description": "Receive up to $10 off your services every month for 6 months! Unused credits will expire once this promotion period ends.", - "expire_dt": "2018-01-31T23:59:59", - "image_url": "https://linode.com/10_a_month_promotion.svg", - "service_type": "all", - "summary": "$10 off your Linode a month!", - "this_month_credit_remaining": "10.00" - } - ], - "active_since": "2018-01-01T00:01:01", - "address_1": "123 Main Street", - "address_2": "Suite A", - "balance": 200, - "balance_uninvoiced": 145, - "billing_source": "akamai", - "capabilities": [ - "Linodes", - "NodeBalancers", - "Block Storage", - "Object Storage" - ], - "city": "Philadelphia", - "company": "Linode LLC", - "country": "US", - "credit_card": { - "expiry": "11/2022", - "last_four": 1111 - }, - "email": "john.smith@linode.com", - "euuid": "E1AF5EEC-526F-487D-B317EBEB34C87D71", - "first_name": "John", - "last_name": "Smith", - "phone": "215-555-1212", - "state": "PA", - "tax_id": "ATU99999999", - "zip": "19102-1234" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#account-view__response-samples) for a list of returned fields - - diff --git a/docs/modules/api_request.md b/docs/modules/api_request.md deleted file mode 100644 index dcb17835..00000000 --- a/docs/modules/api_request.md +++ /dev/null @@ -1,86 +0,0 @@ -# api_request - -Make an arbitrary Linode API request. - -The Linode API documentation can be found here: https://www.linode.com/docs/api - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get all available LKE versions - linode.cloud.api_request: - path: lke/versions - method: GET -``` - -```yaml -- name: Manually create a domain - linode.cloud.api_request: - path: domains - method: POST - body: - domain: my-domain.com - type: master - soa_email: myemail@example.com -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `path` |
`str`
|
**Required**
| The relative path to the endpoint to make a request to. e.g. "linode/instances" | -| `method` |
`str`
|
**Required**
| The HTTP method of the request or response. **(Choices: `POST`, `PUT`, `GET`, `DELETE`)** | -| `body` |
`dict`
|
Optional
| The body of the request. This is a YAML structure that will be marshalled to JSON. | -| `body_json` |
`str`
|
Optional
| The body of the request in JSON format. | -| `filters` |
`dict`
|
Optional
| A YAML structure corresponding to the X-Filter request header. See: https://www.linode.com/docs/api/#filtering-and-sorting | - - - - - - -## Return Values - -- `body` - The deserialized response body. - - - Sample Response: - ```json - { - "axfr_ips": [], - "description": null, - "domain": "example.org", - "expire_sec": 300, - "group": null, - "id": 1234, - "master_ips": [], - "refresh_sec": 300, - "retry_sec": 300, - "soa_email": "admin@example.org", - "status": "active", - "tags": [ - "example tag", - "another example" - ], - "ttl_sec": 300, - "type": "master" - } - ``` - - -- `status` - The response status code. - - diff --git a/docs/modules/database_list.md b/docs/modules/database_list.md deleted file mode 100644 index 946aea67..00000000 --- a/docs/modules/database_list.md +++ /dev/null @@ -1,108 +0,0 @@ -# database_list - -List and filter on Linode Managed Databases. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: List all of the databases for the current Linode Account - linode.cloud.database_list: {} -``` - -```yaml -- name: Resolve all MySQL databases for the current Linode Account - linode.cloud.database_list: - filter: - - name: engine - values: mysql -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `order` |
`str`
|
Optional
| The order to list databases in. **(Choices: `desc`, `asc`; Default: `asc`)** | -| `order_by` |
`str`
|
Optional
| The attribute to order databases by. | -| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting databases. | -| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | - - - - - -### filters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/databases/#managed-mongodb-databases-list__responses | -| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | - - - - - - -## Return Values - -- `databases` - The returned database. - - - Sample Response: - ```json - [ - { - "allow_list":[ - "203.0.113.1/32", - "192.0.1.0/24" - ], - "cluster_size":3, - "compression_type":"none", - "created":"2022-01-01T00:01:01", - "encrypted":false, - "engine":"mongodb", - "hosts":{ - "primary":"lin-0000-0000.servers.linodedb.net", - "secondary":null - }, - "id":123, - "label":"example-db", - "peers":[ - "lin-0000-0000.servers.linodedb.net", - "lin-0000-0001.servers.linodedb.net", - "lin-0000-0002.servers.linodedb.net" - ], - "port":27017, - "region":"us-east", - "replica_set":null, - "ssl_connection":true, - "status":"active", - "storage_engine":"wiredtiger", - "type":"g6-dedicated-2", - "updated":"2022-01-01T00:01:01", - "updates":{ - "day_of_week":1, - "duration":3, - "frequency":"weekly", - "hour_of_day":0, - "week_of_month":null - }, - "version":"4.4.10" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-databases-list-all__response-samples) for a list of returned fields - - diff --git a/docs/modules/database_mysql.md b/docs/modules/database_mysql.md deleted file mode 100644 index b34101d4..00000000 --- a/docs/modules/database_mysql.md +++ /dev/null @@ -1,172 +0,0 @@ -# database_mysql - -Manage a Linode MySQL database. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a basic MySQL database - linode.cloud.database_mysql: - label: my-db - region: us-east - engine: mysql/8.0.26 - type: g6-standard-1 - allow_list: - - 0.0.0.0/0 - state: present -``` - -```yaml -- name: Create a complex 3 node MySQL database - linode.cloud.database_mysql: - label: my-db - region: us-east - engine: mysql/8.0.26 - type: g6-standard-1 - allow_list: - - 0.0.0.0/0 - encrypted: true - cluster_size: 3 - replication_type: semi_synch - ssl_connection: true - state: present -``` - -```yaml -- name: Delete a MySQL database - linode.cloud.database_mysql: - label: my-db - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| This database's unique label. | -| `state` |
`str`
|
**Required**
| The state of this database. **(Choices: `present`, `absent`)** | -| `allow_list` |
`list`
|
Optional
| A list of IP addresses that can access the Managed Database. Each item must be a range in CIDR format. **(Updatable)** | -| `cluster_size` |
`int`
|
Optional
| The number of Linode Instance nodes deployed to the Managed Database. **(Choices: `1`, `3`; Default: `1`)** | -| `encrypted` |
`bool`
|
Optional
| Whether the Managed Databases is encrypted. | -| `engine` |
`str`
|
Optional
| The Managed Database engine in engine/version format. | -| `region` |
`str`
|
Optional
| The Region ID for the Managed Database. | -| `replication_type` |
`str`
|
Optional
| The replication method used for the Managed Database. Defaults to none for a single cluster and semi_synch for a high availability cluster. Must be none for a single node cluster. Must be asynch or semi_synch for a high availability cluster. **(Choices: `none`, `asynch`, `semi_synch`; Default: `none`)** | -| `ssl_connection` |
`bool`
|
Optional
| Whether to require SSL credentials to establish a connection to the Managed Database. **(Default: `True`)** | -| `type` |
`str`
|
Optional
| The Linode Instance type used by the Managed Database for its nodes. | -| [`updates` (sub-options)](#updates) |
`dict`
|
Optional
| Configuration settings for automated patch update maintenance for the Managed Database. **(Updatable)** | -| `wait` |
`bool`
|
Optional
| Wait for the database to have status `available` before returning. **(Default: `True`)** | -| `wait_timeout` |
`int`
|
Optional
| The amount of time, in seconds, to wait for an image to have status `available`. **(Default: `3600`)** | - - - - - -### updates - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `day_of_week` |
`int`
|
**Required**
| The day to perform maintenance. 1=Monday, 2=Tuesday, etc. **(Choices: `1`, `2`, `3`, `4`, `5`, `6`, `7`)** | -| `duration` |
`int`
|
**Required**
| The maximum maintenance window time in hours. **(Choices: `1`, `3`)** | -| `hour_of_day` |
`int`
|
**Required**
| The hour to begin maintenance based in UTC time. | -| `frequency` |
`str`
|
Optional
| Whether maintenance occurs on a weekly or monthly basis. **(Choices: `weekly`, `monthly`; Default: `weekly`)** | -| `week_of_month` |
`int`
|
Optional
| The week of the month to perform monthly frequency updates. Defaults to None. Required for monthly frequency updates. Must be null for weekly frequency updates. | - - - - - - -## Return Values - -- `database` - The database in JSON serialized form. - - - Sample Response: - ```json - { - "allow_list": [ - "203.0.113.1/32", - "192.0.1.0/24" - ], - "cluster_size": 3, - "created": "2022-01-01T00:01:01", - "encrypted": false, - "engine": "mysql", - "hosts": { - "primary": "lin-123-456-mysql-mysql-primary.servers.linodedb.net", - "secondary": "lin-123-456-mysql-primary-private.servers.linodedb.net" - }, - "id": 123, - "label": "example-db", - "port": 3306, - "region": "us-east", - "replication_type": "semi_synch", - "ssl_connection": true, - "status": "active", - "type": "g6-dedicated-2", - "updated": "2022-01-01T00:01:01", - "updates": { - "day_of_week": 1, - "duration": 3, - "frequency": "weekly", - "hour_of_day": 0, - "week_of_month": null - }, - "version": "8.0.26" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-view__response-samples) for a list of returned fields - - -- `backups` - The database backups in JSON serialized form. - - - Sample Response: - ```json - [ - { - "created":"2022-01-01T00:01:01", - "id":123, - "label":"Scheduled - 02/04/22 11:11 UTC-XcCRmI", - "type":"auto" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-backup-view__responses) for a list of returned fields - - -- `ssl_cert` - The SSL CA certificate for an accessible Managed MySQL Database. - - - Sample Response: - ```json - { - "ca_certificate": "LS0tLS1CRUdJ...==" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-ssl-certificate-view__responses) for a list of returned fields - - -- `credentials` - The root username and password for an accessible Managed MySQL Database. - - - Sample Response: - ```json - { - "password": "s3cur3P@ssw0rd", - "username": "linroot" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-credentials-view__responses) for a list of returned fields - - diff --git a/docs/modules/database_mysql_info.md b/docs/modules/database_mysql_info.md deleted file mode 100644 index af4dc4d1..00000000 --- a/docs/modules/database_mysql_info.md +++ /dev/null @@ -1,124 +0,0 @@ -# database_mysql_info - -Get info about a Linode MySQL Managed Database. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about a Managed MySQL Database by label - linode.cloud.database_mysql_info: - label: my-db -``` - -```yaml -- name: Get info about a Managed MySQL Database by ID - linode.cloud.database_mysql_info: - id: 12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`str`
|
Optional
| The ID of the MySQL Database. | -| `label` |
`str`
|
Optional
| The label of the MySQL Database. | - - - - - - -## Return Values - -- `database` - The database in JSON serialized form. - - - Sample Response: - ```json - { - "allow_list": [ - "203.0.113.1/32", - "192.0.1.0/24" - ], - "cluster_size": 3, - "created": "2022-01-01T00:01:01", - "encrypted": false, - "engine": "mysql", - "hosts": { - "primary": "lin-123-456-mysql-mysql-primary.servers.linodedb.net", - "secondary": "lin-123-456-mysql-primary-private.servers.linodedb.net" - }, - "id": 123, - "label": "example-db", - "port": 3306, - "region": "us-east", - "replication_type": "semi_synch", - "ssl_connection": true, - "status": "active", - "type": "g6-dedicated-2", - "updated": "2022-01-01T00:01:01", - "updates": { - "day_of_week": 1, - "duration": 3, - "frequency": "weekly", - "hour_of_day": 0, - "week_of_month": null - }, - "version": "8.0.26" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-view__response-samples) for a list of returned fields - - -- `backups` - The database backups in JSON serialized form. - - - Sample Response: - ```json - [ - { - "created":"2022-01-01T00:01:01", - "id":123, - "label":"Scheduled - 02/04/22 11:11 UTC-XcCRmI", - "type":"auto" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-backup-view__responses) for a list of returned fields - - -- `ssl_cert` - The SSL CA certificate for an accessible Managed MySQL Database. - - - Sample Response: - ```json - { - "ca_certificate": "LS0tLS1CRUdJ...==" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-ssl-certificate-view__responses) for a list of returned fields - - -- `credentials` - The root username and password for an accessible Managed MySQL Database. - - - Sample Response: - ```json - { - "password": "s3cur3P@ssw0rd", - "username": "linroot" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-credentials-view__responses) for a list of returned fields - - diff --git a/docs/modules/database_postgresql.md b/docs/modules/database_postgresql.md deleted file mode 100644 index e5cff1de..00000000 --- a/docs/modules/database_postgresql.md +++ /dev/null @@ -1,175 +0,0 @@ -# database_postgresql - -Manage a Linode PostgreSQL database. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a basic PostgreSQL database - linode.cloud.database_postgresql: - label: my-db - region: us-east - engine: postgresql/13.2 - type: g6-standard-1 - allow_list: - - 0.0.0.0/0 - state: present -``` - -```yaml -- name: Create a complex 3 node PostgreSQL database - linode.cloud.database_postgresql: - label: my-db - region: us-east - engine: postgresql/13.2 - type: g6-standard-1 - allow_list: - - 0.0.0.0/0 - encrypted: true - cluster_size: 3 - replication_type: semi_synch - replication_commit_type: remote_apply - ssl_connection: true - state: present -``` - -```yaml -- name: Delete a PostgreSQL database - linode.cloud.database_postgresql: - label: my-db - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| This database's unique label. | -| `state` |
`str`
|
**Required**
| The state of this database. **(Choices: `present`, `absent`)** | -| `allow_list` |
`list`
|
Optional
| A list of IP addresses that can access the Managed Database. Each item must be a range in CIDR format. **(Updatable)** | -| `cluster_size` |
`int`
|
Optional
| The number of Linode Instance nodes deployed to the Managed Database. **(Choices: `1`, `3`; Default: `1`)** | -| `encrypted` |
`bool`
|
Optional
| Whether the Managed Databases is encrypted. | -| `engine` |
`str`
|
Optional
| The Managed Database engine in engine/version format. | -| `region` |
`str`
|
Optional
| The Region ID for the Managed Database. | -| `replication_type` |
`str`
|
Optional
| The replication method used for the Managed Database. Defaults to none for a single cluster and semi_synch for a high availability cluster. Must be none for a single node cluster. Must be asynch or semi_synch for a high availability cluster. **(Choices: `none`, `asynch`, `semi_synch`; Default: `none`)** | -| `replication_commit_type` |
`str`
|
Optional
| The synchronization level of the replicating server. Must be local or off for the asynch replication type. Must be on, remote_write, or remote_apply for the semi_synch replication type. **(Choices: `off`, `on`, `local`, `remote_write`, `remote_apply`; Default: `local`)** | -| `ssl_connection` |
`bool`
|
Optional
| Whether to require SSL credentials to establish a connection to the Managed Database. **(Default: `True`)** | -| `type` |
`str`
|
Optional
| The Linode Instance type used by the Managed Database for its nodes. | -| [`updates` (sub-options)](#updates) |
`dict`
|
Optional
| Configuration settings for automated patch update maintenance for the Managed Database. **(Updatable)** | -| `wait` |
`bool`
|
Optional
| Wait for the database to have status `available` before returning. **(Default: `True`)** | -| `wait_timeout` |
`int`
|
Optional
| The amount of time, in seconds, to wait for an image to have status `available`. **(Default: `3600`)** | - - - - - -### updates - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `day_of_week` |
`int`
|
**Required**
| The day to perform maintenance. 1=Monday, 2=Tuesday, etc. **(Choices: `1`, `2`, `3`, `4`, `5`, `6`, `7`)** | -| `duration` |
`int`
|
**Required**
| The maximum maintenance window time in hours. **(Choices: `1`, `3`)** | -| `hour_of_day` |
`int`
|
**Required**
| The hour to begin maintenance based in UTC time. | -| `frequency` |
`str`
|
Optional
| Whether maintenance occurs on a weekly or monthly basis. **(Choices: `weekly`, `monthly`; Default: `weekly`)** | -| `week_of_month` |
`int`
|
Optional
| The week of the month to perform monthly frequency updates. Defaults to None. Required for monthly frequency updates. Must be null for weekly frequency updates. | - - - - - - -## Return Values - -- `database` - The database in JSON serialized form. - - - Sample Response: - ```json - { - "allow_list": [ - "203.0.113.1/32", - "192.0.1.0/24" - ], - "cluster_size": 3, - "created": "2022-01-01T00:01:01", - "encrypted": false, - "engine": "postgresql", - "hosts": { - "primary": "lin-0000-000-pgsql-primary.servers.linodedb.net", - "secondary": "lin-0000-000-pgsql-primary-private.servers.linodedb.net" - }, - "id": 123, - "label": "example-db", - "port": 3306, - "region": "us-east", - "replication_commit_type": "local", - "replication_type": "semi_synch", - "ssl_connection": true, - "status": "active", - "type": "g6-dedicated-2", - "updated": "2022-01-01T00:01:01", - "updates": { - "day_of_week": 1, - "duration": 3, - "frequency": "weekly", - "hour_of_day": 0, - "week_of_month": null - }, - "version": "13.2" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-view__response-samples) for a list of returned fields - - -- `backups` - The database backups in JSON serialized form. - - - Sample Response: - ```json - [ - { - "created":"2022-01-01T00:01:01", - "id":123, - "label":"Scheduled - 02/04/22 11:11 UTC-XcCRmI", - "type":"auto" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-backups-list) for a list of returned fields - - -- `ssl_cert` - The SSL CA certificate for an accessible Managed PostgreSQL Database. - - - Sample Response: - ```json - { - "ca_certificate": "LS0tLS1CRUdJ...==" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-ssl-certificate-view__responses) for a list of returned fields - - -- `credentials` - The root username and password for an accessible Managed PostgreSQL Database. - - - Sample Response: - ```json - { - "password": "s3cur3P@ssw0rd", - "username": "linroot" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-credentials-view__responses) for a list of returned fields - - diff --git a/docs/modules/database_postgresql_info.md b/docs/modules/database_postgresql_info.md deleted file mode 100644 index af3537b1..00000000 --- a/docs/modules/database_postgresql_info.md +++ /dev/null @@ -1,125 +0,0 @@ -# database_postgresql_info - -Get info about a Linode PostgreSQL Managed Database. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about a Managed PostgreSQL Database by label - linode.cloud.database_postgresql_info: - label: my-db -``` - -```yaml -- name: Get info about a Managed PostgreSQL Database by ID - linode.cloud.database_postgresql_info: - id: 12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`str`
|
Optional
| The ID of the PostgreSQL Database. | -| `label` |
`str`
|
Optional
| The label of the PostgreSQL Database. | - - - - - - -## Return Values - -- `database` - The database in JSON serialized form. - - - Sample Response: - ```json - { - "allow_list": [ - "203.0.113.1/32", - "192.0.1.0/24" - ], - "cluster_size": 3, - "created": "2022-01-01T00:01:01", - "encrypted": false, - "engine": "postgresql", - "hosts": { - "primary": "lin-0000-000-pgsql-primary.servers.linodedb.net", - "secondary": "lin-0000-000-pgsql-primary-private.servers.linodedb.net" - }, - "id": 123, - "label": "example-db", - "port": 3306, - "region": "us-east", - "replication_commit_type": "local", - "replication_type": "semi_synch", - "ssl_connection": true, - "status": "active", - "type": "g6-dedicated-2", - "updated": "2022-01-01T00:01:01", - "updates": { - "day_of_week": 1, - "duration": 3, - "frequency": "weekly", - "hour_of_day": 0, - "week_of_month": null - }, - "version": "13.2" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-view__response-samples) for a list of returned fields - - -- `backups` - The database backups in JSON serialized form. - - - Sample Response: - ```json - [ - { - "created":"2022-01-01T00:01:01", - "id":123, - "label":"Scheduled - 02/04/22 11:11 UTC-XcCRmI", - "type":"auto" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-backups-list__response-samples) for a list of returned fields - - -- `ssl_cert` - The SSL CA certificate for an accessible Managed PostgreSQL Database. - - - Sample Response: - ```json - { - "ca_certificate": "LS0tLS1CRUdJ...==" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-ssl-certificate-view) for a list of returned fields - - -- `credentials` - The root username and password for an accessible Managed PostgreSQL Database. - - - Sample Response: - ```json - { - "password": "s3cur3P@ssw0rd", - "username": "linroot" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-credentials-view__request-samples) for a list of returned fields - - diff --git a/docs/modules/domain.md b/docs/modules/domain.md deleted file mode 100644 index 71e46dd7..00000000 --- a/docs/modules/domain.md +++ /dev/null @@ -1,112 +0,0 @@ -# domain - -Manage Linode Domains. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a domain - linode.cloud.domain: - domain: my-domain.com - type: master - state: present -``` - -```yaml -- name: Delete a domain - linode.cloud.domain: - domain: my-domain.com - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `domain` |
`str`
|
**Required**
| The domain this Domain represents. | -| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | -| `axfr_ips` |
`list`
|
Optional
| The list of IPs that may perform a zone transfer for this Domain. **(Updatable)** | -| `description` |
`str`
|
Optional
| The list of IPs that may perform a zone transfer for this Domain. **(Updatable)** | -| `expire_sec` |
`int`
|
Optional
| The amount of time in seconds that may pass before this Domain is no longer authoritative. **(Updatable)** | -| `master_ips` |
`list`
|
Optional
| The IP addresses representing the master DNS for this Domain. **(Updatable)** | -| `refresh_sec` |
`int`
|
Optional
| The amount of time in seconds before this Domain should be refreshed. **(Updatable)** | -| `retry_sec` |
`int`
|
Optional
| The interval, in seconds, at which a failed refresh should be retried. **(Updatable)** | -| `soa_email` |
`str`
|
Optional
| The Start of Authority email address. **(Updatable)** | -| `status` |
`str`
|
Optional
| Used to control whether this Domain is currently being rendered. **(Updatable)** | -| `tags` |
`list`
|
Optional
| An array of tags applied to this object. **(Updatable)** | -| `ttl_sec` |
`int`
|
Optional
| the amount of time in seconds that this Domain’s records may be cached by resolvers or other domain servers. **(Updatable)** | -| `type` |
`str`
|
Optional
| Whether this Domain represents the authoritative source of information for the domain it describes (master), or whether it is a read-only copy of a master (slave). **(Updatable)** | - - - - - - -## Return Values - -- `domain` - The domain in JSON serialized form. - - - Sample Response: - ```json - { - "axfr_ips": [], - "description": null, - "domain": "example.org", - "expire_sec": 300, - "group": null, - "id": 1234, - "master_ips": [], - "refresh_sec": 300, - "retry_sec": 300, - "soa_email": "admin@example.org", - "status": "active", - "tags": [ - "example tag", - "another example" - ], - "ttl_sec": 300, - "type": "master" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-view) for a list of returned fields - - -- `records` - The domain record in JSON serialized form. - - - Sample Response: - ```json - [ - { - "created": "2018-01-01T00:01:01", - "id": 123456, - "name": "test", - "port": 80, - "priority": 50, - "protocol": null, - "service": null, - "tag": null, - "target": "192.0.2.0", - "ttl_sec": 604800, - "type": "A", - "updated": "2018-01-01T00:01:01", - "weight": 50 - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-record-view) for a list of returned fields - - diff --git a/docs/modules/domain_info.md b/docs/modules/domain_info.md deleted file mode 100644 index fea6eb1c..00000000 --- a/docs/modules/domain_info.md +++ /dev/null @@ -1,98 +0,0 @@ -# domain_info - -Get info about a Linode Domain. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about a domain by domain - linode.cloud.domain_info: - domain: my-domain.com -``` - -```yaml -- name: Get info about a domain by id - linode.cloud.domain_info: - id: 12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`int`
|
Optional
| The unique domain name of the Domain. Optional if `domain` is defined. | -| `domain` |
`str`
|
Optional
| The unique id of the Domain. Optional if `id` is defined. | - - - - - - -## Return Values - -- `domain` - The domain in JSON serialized form. - - - Sample Response: - ```json - { - "axfr_ips": [], - "description": null, - "domain": "example.org", - "expire_sec": 300, - "group": null, - "id": 1234, - "master_ips": [], - "refresh_sec": 300, - "retry_sec": 300, - "soa_email": "admin@example.org", - "status": "active", - "tags": [ - "example tag", - "another example" - ], - "ttl_sec": 300, - "type": "master" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-view) for a list of returned fields - - -- `records` - The domain record in JSON serialized form. - - - Sample Response: - ```json - [ - { - "created": "2018-01-01T00:01:01", - "id": 123456, - "name": "test", - "port": 80, - "priority": 50, - "protocol": null, - "service": null, - "tag": null, - "target": "192.0.2.0", - "ttl_sec": 604800, - "type": "A", - "updated": "2018-01-01T00:01:01", - "weight": 50 - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-record-view) for a list of returned fields - - diff --git a/docs/modules/domain_record.md b/docs/modules/domain_record.md deleted file mode 100644 index 0aa6515f..00000000 --- a/docs/modules/domain_record.md +++ /dev/null @@ -1,89 +0,0 @@ -# domain_record - -Manage Linode Domain Records. - -NOTE: Domain records are identified by their name, target, and type. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create an A record - linode.cloud.domain_record: - domain: my-domain.com - name: my-subdomain - type: 'A' - target: '127.0.0.1' - state: present -``` - -```yaml -- name: Delete a domain record - linode.cloud.domain: - domain: my-domain.com - name: my-subdomain - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | -| `domain_id` |
`int`
|
Optional
| The ID of the parent Domain. | -| `domain` |
`str`
|
Optional
| The name of the parent Domain. | -| `record_id` |
`int`
|
Optional
| The id of the record to modify. | -| `name` |
`str`
|
Optional
| The name of this Record. NOTE: If the name of the record ends with the domain, it will be dropped from the resulting record's name. | -| `port` |
`int`
|
Optional
| The port this Record points to. Only valid and required for SRV record requests. **(Updatable)** | -| `priority` |
`int`
|
Optional
| The priority of the target host for this Record. Lower values are preferred. Only valid for MX and SRV record requests. Required for SRV record requests. **(Updatable)** | -| `protocol` |
`str`
|
Optional
| The protocol this Record’s service communicates with. An underscore (_) is prepended automatically to the submitted value for this property. **(Updatable)** | -| `service` |
`str`
|
Optional
| An underscore (_) is prepended and a period (.) is appended automatically to the submitted value for this property. Only valid and required for SRV record requests. The name of the service. **(Updatable)** | -| `tag` |
`str`
|
Optional
| The tag portion of a CAA record. Only valid and required for CAA record requests. **(Updatable)** | -| `target` |
`str`
|
Optional
| The target for this Record. | -| `ttl_sec` |
`int`
|
Optional
| The amount of time in seconds that this Domain’s records may be cached by resolvers or other domain servers. **(Updatable)** | -| `type` |
`str`
|
Optional
| The type of Record this is in the DNS system. | -| `weight` |
`int`
|
Optional
| The relative weight of this Record used in the case of identical priority. **(Updatable)** | - - - - - - -## Return Values - -- `record` - View a single Record on this Domain. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "id": 123456, - "name": "test", - "port": 80, - "priority": 50, - "protocol": null, - "service": null, - "tag": null, - "target": "192.0.2.0", - "ttl_sec": 604800, - "type": "A", - "updated": "2018-01-01T00:01:01", - "weight": 50 - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-record-view) for a list of returned fields - - diff --git a/docs/modules/domain_record_info.md b/docs/modules/domain_record_info.md deleted file mode 100644 index 17a2978e..00000000 --- a/docs/modules/domain_record_info.md +++ /dev/null @@ -1,75 +0,0 @@ -# domain_record_info - -Get info about a Linode Domain Record. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about domain records by name - linode.cloud.domain_record_info: - domain: my-domain.com - name: my-subdomain - type: A - target: 0.0.0.0 -``` - -```yaml -- name: Get info about a domain record by id - linode.cloud.domain_info: - domain: my-domain.com - id: 12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `domain_id` |
`int`
|
Optional
| The ID of the parent Domain. Optional if `domain` is defined. | -| `domain` |
`str`
|
Optional
| The name of the parent Domain. Optional if `domain_id` is defined. | -| `id` |
`int`
|
Optional
| The unique id of the subdomain. Optional if `name` is defined. | -| `name` |
`str`
|
Optional
| The name of the domain record. Optional if `id` is defined. | - - - - - - -## Return Values - -- `record` - View a single Record on this Domain. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "id": 123456, - "name": "test", - "port": 80, - "priority": 50, - "protocol": null, - "service": null, - "tag": null, - "target": "192.0.2.0", - "ttl_sec": 604800, - "type": "A", - "updated": "2018-01-01T00:01:01", - "weight": 50 - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-record-view) for a list of returned fields - - diff --git a/docs/modules/event_list.md b/docs/modules/event_list.md deleted file mode 100644 index 4e77362b..00000000 --- a/docs/modules/event_list.md +++ /dev/null @@ -1,104 +0,0 @@ -# event_list - -List and filter on Linode events. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: List all of the events for the current Linode Account - linode.cloud.event_list: {} -``` - -```yaml -- name: List the latest 5 events for the current Linode Account - linode.cloud.event_list: - count: 5 - order_by: created - order: desc -``` - -```yaml -- name: List all Linode Instance creation events for the current Linode Account - linode.cloud.event_list: - filter: - - name: action - values: linode_create -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `order` |
`str`
|
Optional
| The order to list events in. **(Choices: `desc`, `asc`; Default: `asc`)** | -| `order_by` |
`str`
|
Optional
| The attribute to order events by. | -| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting events. | -| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | - - - - - -### filters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/account/#events-list__responses | -| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | - - - - - - -## Return Values - -- `events` - The returned events. - - - Sample Response: - ```json - [ - { - "action":"ticket_create", - "created":"2018-01-01T00:01:01", - "duration":300.56, - "entity":{ - "id":11111, - "label":"Problem booting my Linode", - "type":"ticket", - "url":"/v4/support/tickets/11111" - }, - "id":123, - "message":"None", - "percent_complete":null, - "rate":null, - "read":true, - "secondary_entity":{ - "id":"linode/debian9", - "label":"linode1234", - "type":"linode", - "url":"/v4/linode/instances/1234" - }, - "seen":true, - "status":null, - "time_remaining":null, - "username":"exampleUser" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#events-list__responses) for a list of returned fields - - diff --git a/docs/modules/firewall.md b/docs/modules/firewall.md deleted file mode 100644 index 57f81dba..00000000 --- a/docs/modules/firewall.md +++ /dev/null @@ -1,223 +0,0 @@ -# firewall - -Manage Linode Firewalls. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a Linode Firewall - linode.cloud.firewall: - label: 'my-firewall' - devices: - - id: 123 - type: linode - rules: - inbound_policy: DROP - inbound: - - label: allow-http-in - addresses: - ipv4: - - 0.0.0.0/0 - ipv6: - - 'ff00::/8' - description: Allow inbound HTTP and HTTPS connections. - ports: '80,443' - protocol: TCP - action: ACCEPT - - outbound_policy: DROP - outbound: - - label: allow-http-out - addresses: - ipv4: - - 0.0.0.0/0 - ipv6: - - 'ff00::/8' - description: Allow outbound HTTP and HTTPS connections. - ports: '80,443' - protocol: TCP - action: ACCEPT - state: present -``` - -```yaml -- name: Delete a Linode Firewall - linode.cloud.firewall: - label: 'my-firewall' - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`, `update`)** | -| `label` |
`str`
|
Optional
| The unique label to give this Firewall. | -| [`devices` (sub-options)](#devices) |
`list`
|
Optional
| The devices that are attached to this Firewall. **(Updatable)** | -| [`rules` (sub-options)](#rules) |
`dict`
|
Optional
| The inbound and outbound access rules to apply to this Firewall. **(Updatable)** | -| `status` |
`str`
|
Optional
| The status of this Firewall. **(Updatable)** | - - - - - -### devices - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`int`
|
**Required**
| The unique ID of the device to attach to this Firewall. | -| `type` |
`str`
|
Optional
| The type of device to be attached to this Firewall. **(Default: `linode`)** | - - - - - -### rules - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| [`inbound` (sub-options)](#inbound) |
`list`
|
Optional
| A list of rules for inbound traffic. | -| `inbound_policy` |
`str`
|
Optional
| The default behavior for inbound traffic. | -| [`outbound` (sub-options)](#outbound) |
`list`
|
Optional
| A list of rules for outbound traffic. | -| `outbound_policy` |
`str`
|
Optional
| The default behavior for outbound traffic. | - - - - - -### inbound - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| The label of this rule. | -| `action` |
`str`
|
**Required**
| Controls whether traffic is accepted or dropped by this rule. **(Choices: `ACCEPT`, `DROP`)** | -| [`addresses` (sub-options)](#addresses) |
`dict`
|
Optional
| Allowed IPv4 or IPv6 addresses. | -| `description` |
`str`
|
Optional
| A description for this rule. | -| `ports` |
`str`
|
Optional
| A string representing the port or ports on which traffic will be allowed. See U(https://www.linode.com/docs/api/networking/#firewall-create) | -| `protocol` |
`str`
|
Optional
| The type of network traffic to allow. | - - - - - -### addresses - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `ipv4` |
`list`
|
Optional
| A list of IPv4 addresses or networks. Must be in IP/mask format. | -| `ipv6` |
`list`
|
Optional
| A list of IPv4 addresses or networks. Must be in IP/mask format. | - - - - - -### outbound - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| The label of this rule. | -| `action` |
`str`
|
**Required**
| Controls whether traffic is accepted or dropped by this rule. **(Choices: `ACCEPT`, `DROP`)** | -| [`addresses` (sub-options)](#addresses) |
`dict`
|
Optional
| Allowed IPv4 or IPv6 addresses. | -| `description` |
`str`
|
Optional
| A description for this rule. | -| `ports` |
`str`
|
Optional
| A string representing the port or ports on which traffic will be allowed. See U(https://www.linode.com/docs/api/networking/#firewall-create) | -| `protocol` |
`str`
|
Optional
| The type of network traffic to allow. | - - - - - - -## Return Values - -- `firewall` - The Firewall description in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "id": 123, - "label": "firewall123", - "rules": { - "inbound": [ - { - "action": "ACCEPT", - "addresses": { - "ipv4": [ - "192.0.2.0/24" - ], - "ipv6": [ - "2001:DB8::/32" - ] - }, - "description": "An example firewall rule description.", - "label": "firewallrule123", - "ports": "22-24, 80, 443", - "protocol": "TCP" - } - ], - "inbound_policy": "DROP", - "outbound": [ - { - "action": "ACCEPT", - "addresses": { - "ipv4": [ - "192.0.2.0/24" - ], - "ipv6": [ - "2001:DB8::/32" - ] - }, - "description": "An example firewall rule description.", - "label": "firewallrule123", - "ports": "22-24, 80, 443", - "protocol": "TCP" - } - ], - "outbound_policy": "DROP" - }, - "status": "enabled", - "tags": [ - "example tag", - "another example" - ], - "updated": "2018-01-02T00:01:01" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#firewall-view) for a list of returned fields - - -- `devices` - A list of Firewall devices JSON serialized form. - - - Sample Response: - ```json - [ - { - "created": "2018-01-01T00:01:01", - "entity": { - "id": 123, - "label": "my-linode", - "type": "linode", - "url": "/v4/linode/instances/123" - }, - "id": 123, - "updated": "2018-01-02T00:01:01" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#firewall-device-view) for a list of returned fields - - diff --git a/docs/modules/firewall_device.md b/docs/modules/firewall_device.md deleted file mode 100644 index fb5315fa..00000000 --- a/docs/modules/firewall_device.md +++ /dev/null @@ -1,81 +0,0 @@ -# firewall_device - -Manage Linode Firewall Devices. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a Firewall - linode.cloud.firewall: - label: my-firewall - rules: - inbound_policy: DROP - state: present - register: firewall_result - -- name: Create an Instance - linode.cloud.instance: - label: my-instance - region: us-east - private_ip: true - type: g6-standard-1 - state: present - register: instance_result - -- name: Attach the instance to the Firewall - linode.cloud.firewall_device: - firewall_id: '{{ firewall_result.firewall.id }}' - entity_id: '{{ instance_result.instance.id }}' - entity_type: 'linode' - state: present -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `firewall_id` |
`int`
|
**Required**
| The ID of the Firewall that contains this device. | -| `entity_id` |
`int`
|
**Required**
| The ID for this Firewall Device. This will be the ID of the Linode Entity. | -| `entity_type` |
`str`
|
**Required**
| The type of Linode Entity. Currently only supports linode. **(Choices: `linode`)** | -| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | - - - - - - -## Return Values - -- `device` - The Firewall Device in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "entity": { - "id": 123, - "label": "my-linode", - "type": "linode", - "url": "/v4/linode/instances/123" - }, - "id": 123, - "updated": "2018-01-02T00:01:01" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#firewall-device-view__responses) for a list of returned fields - - diff --git a/docs/modules/firewall_info.md b/docs/modules/firewall_info.md deleted file mode 100644 index 8684097f..00000000 --- a/docs/modules/firewall_info.md +++ /dev/null @@ -1,124 +0,0 @@ -# firewall_info - -Get info about a Linode Firewall. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about a Firewall by label - linode.cloud.firewall_info: - label: 'my-firewall' -``` - -```yaml -- name: Get info about a Firewall by id - linode.cloud.firewall_info: - id: 12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`int`
|
Optional
| The unique id of the Firewall. Optional if `label` is defined. | -| `label` |
`str`
|
Optional
| The Firewall’s label. Optional if `id` is defined. | - - - - - - -## Return Values - -- `firewall` - The Firewall description in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "id": 123, - "label": "firewall123", - "rules": { - "inbound": [ - { - "action": "ACCEPT", - "addresses": { - "ipv4": [ - "192.0.2.0/24" - ], - "ipv6": [ - "2001:DB8::/32" - ] - }, - "description": "An example firewall rule description.", - "label": "firewallrule123", - "ports": "22-24, 80, 443", - "protocol": "TCP" - } - ], - "inbound_policy": "DROP", - "outbound": [ - { - "action": "ACCEPT", - "addresses": { - "ipv4": [ - "192.0.2.0/24" - ], - "ipv6": [ - "2001:DB8::/32" - ] - }, - "description": "An example firewall rule description.", - "label": "firewallrule123", - "ports": "22-24, 80, 443", - "protocol": "TCP" - } - ], - "outbound_policy": "DROP" - }, - "status": "enabled", - "tags": [ - "example tag", - "another example" - ], - "updated": "2018-01-02T00:01:01" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#firewall-view) for a list of returned fields - - -- `devices` - A list of Firewall devices JSON serialized form. - - - Sample Response: - ```json - [ - { - "created": "2018-01-01T00:01:01", - "entity": { - "id": 123, - "label": "my-linode", - "type": "linode", - "url": "/v4/linode/instances/123" - }, - "id": 123, - "updated": "2018-01-02T00:01:01" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#firewall-device-view) for a list of returned fields - - diff --git a/docs/modules/image.md b/docs/modules/image.md deleted file mode 100644 index 6a99fbdc..00000000 --- a/docs/modules/image.md +++ /dev/null @@ -1,90 +0,0 @@ -# image - -Manage a Linode Image. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a basic image from an existing disk - linode.cloud.image: - label: my-image - description: Created using Ansible! - disk_id: 12345 - state: present -``` - -```yaml -- name: Create a basic image from a file - linode.cloud.image: - label: my-image - description: Created using Ansible! - source_file: myimage.img.gz - state: present -``` - -```yaml -- name: Delete an image - linode.cloud.image: - label: my-image - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| This Image's unique label. | -| `state` |
`str`
|
**Required**
| The state of this Image. **(Choices: `present`, `absent`)** | -| `description` |
`str`
|
Optional
| A description for the Image. **(Updatable)** | -| `disk_id` |
`int`
|
Optional
| The ID of the disk to clone this image from. | -| `recreate` |
`bool`
|
Optional
| If true, the image with the given label will be deleted and recreated **(Default: `False`)** | -| `region` |
`str`
|
Optional
| The Linode region to upload this image to. **(Default: `us-east`)** | -| `source_file` |
`str`
|
Optional
| An image file to create this image with. | -| `wait` |
`bool`
|
Optional
| Wait for the image to have status `available` before returning. **(Default: `True`)** | -| `wait_timeout` |
`int`
|
Optional
| The amount of time, in seconds, to wait for an image to have status `available`. **(Default: `600`)** | - - - - - - -## Return Values - -- `image` - The Image in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2021-08-14T22:44:02", - "created_by": "linode", - "deprecated": false, - "description": "Example Image description.", - "eol": "2026-07-01T04:00:00", - "expiry": null, - "id": "linode/debian11", - "is_public": true, - "label": "Debian 11", - "size": 2500, - "status": null, - "type": "manual", - "updated": "2021-08-14T22:44:02", - "vendor": "Debian" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/images/#image-view__response-samples) for a list of returned fields - - diff --git a/docs/modules/image_info.md b/docs/modules/image_info.md deleted file mode 100644 index 671f370c..00000000 --- a/docs/modules/image_info.md +++ /dev/null @@ -1,70 +0,0 @@ -# image_info - -Get info about a Linode Image. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about an image by label - linode.cloud.image_info: - label: my-image -``` - -```yaml -- name: Get info about an image by ID - linode.cloud.image_info: - id: private/12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`str`
|
Optional
| The ID of the image. | -| `label` |
`str`
|
Optional
| The label of the image. | - - - - - - -## Return Values - -- `image` - The image in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2021-08-14T22:44:02", - "created_by": "linode", - "deprecated": false, - "description": "Example Image description.", - "eol": "2026-07-01T04:00:00", - "expiry": null, - "id": "linode/debian11", - "is_public": true, - "label": "Debian 11", - "size": 2500, - "status": null, - "type": "manual", - "updated": "2021-08-14T22:44:02", - "vendor": "Debian" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/images/#image-view__responses) for a list of returned fields - - diff --git a/docs/modules/image_list.md b/docs/modules/image_list.md deleted file mode 100644 index 21b549ad..00000000 --- a/docs/modules/image_list.md +++ /dev/null @@ -1,94 +0,0 @@ -# image_list - -List and filter on Linode images. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: List all of the images for the current Linode Account - linode.cloud.image_list: {} -``` - -```yaml -- name: List the latest 5 images for the current Linode Account - linode.cloud.image_list: - count: 5 - order_by: created - order: desc -``` - -```yaml -- name: Resolve all Alpine Linux images - linode.cloud.image_list: - filter: - - name: vendor - values: Alpine -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `order` |
`str`
|
Optional
| The order to list events in. **(Choices: `desc`, `asc`; Default: `asc`)** | -| `order_by` |
`str`
|
Optional
| The attribute to order events by. | -| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting events. | -| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | - - - - - -### filters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/images/#images-list__responses | -| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | - - - - - - -## Return Values - -- `images` - The returned images. - - - Sample Response: - ```json - [ - { - "created":"2021-08-14T22:44:02", - "created_by":"linode", - "deprecated":false, - "description":"Example Image description.", - "eol":"2026-07-01T04:00:00", - "expiry":null, - "id":"linode/debian11", - "is_public":true, - "label":"Debian 11", - "size":2500, - "status":null, - "type":"manual", - "updated":"2021-08-14T22:44:02", - "vendor":"Debian" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/images/#images-list__response-samples) for a list of returned fields - - diff --git a/docs/modules/instance.md b/docs/modules/instance.md deleted file mode 100644 index 839b877d..00000000 --- a/docs/modules/instance.md +++ /dev/null @@ -1,513 +0,0 @@ -# instance - -Manage Linode Instances, Configs, and Disks. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- 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 -``` - -```yaml -- name: Create a Linode Instance with explicit configs and disks. - linode.cloud.instance: - label: 'my-complex-instance' - region: us-southeast - type: g6-standard-1 - booted: true - boot_config_label: boot-config - disks: - - label: boot - image: linode/ubuntu18.04 - size: 3000 - root_pass: ans1ble-test! - - label: swap - filesystem: swap - size: 512 - configs: - - label: boot-config - root_device: /dev/sda - devices: - sda: - disk_label: boot - sdb: - disk_label: swap - state: present -``` - -```yaml -- name: Delete a Linode instance. - linode.cloud.instance: - label: my-linode - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | -| `type` |
`str`
|
Optional
| The unique label to give this instance. | -| `region` |
`str`
|
Optional
| The location to deploy the instance in. See the [Linode API documentation](https://api.linode.com/v4/regions). | -| `image` |
`str`
|
Optional
| The image ID to deploy the instance disk from. | -| `authorized_keys` |
`list`
|
Optional
| A list of SSH public key parts to deploy for the root user. | -| `root_pass` |
`str`
|
Optional
| The password for the root user. If not specified, one will be generated. This generated password will be available in the task success JSON. | -| `stackscript_id` |
`int`
|
Optional
| The ID of the StackScript to use when creating the instance. See the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/). | -| `stackscript_data` |
`dict`
|
Optional
| 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 the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/). | -| `private_ip` |
`bool`
|
Optional
| If true, the created Linode will have private networking enabled. | -| `group` |
`str`
|
Optional
| 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. **(Updatable)** | -| `boot_config_label` |
`str`
|
Optional
| The label of the config to boot from. | -| [`configs` (sub-options)](#configs) |
`list`
|
Optional
| A list of Instance configs to apply to the Linode. See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/#configuration-profile-create). **(Updatable)** | -| [`disks` (sub-options)](#disks) |
`list`
|
Optional
| A list of Disks to create on the Linode. See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/#disk-create). **(Updatable)** | -| [`interfaces` (sub-options)](#interfaces) |
`list`
|
Optional
| A list of network interfaces to apply to the Linode. See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/#linode-create__request-body-schema). | -| `booted` |
`bool`
|
Optional
| Whether the new Instance should be booted. This will default to True if the Instance is deployed from an Image or Backup. | -| `backup_id` |
`int`
|
Optional
| The id of the Backup to restore to the new Instance. May not be provided if “image” is given. | -| `wait` |
`bool`
|
Optional
| Wait for the instance to have status `running` before returning. **(Default: `True`)** | -| `wait_timeout` |
`int`
|
Optional
| The amount of time, in seconds, to wait for an instance to have status `running`. **(Default: `240`)** | - - - - - -### configs - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| [`devices` (sub-options)](#devices) |
`dict`
|
**Required**
| The devices to map to this configuration. | -| `label` |
`str`
|
**Required**
| The label to assign to this config. | -| `comments` |
`str`
|
Optional
| Arbitrary User comments on this Config. **(Updatable)** | -| [`helpers` (sub-options)](#helpers) |
`dict`
|
Optional
| Helpers enabled when booting to this Linode Config. | -| `kernel` |
`str`
|
Optional
| A Kernel ID to boot a Linode with. Defaults to “linode/latest-64bit”. **(Updatable)** | -| `memory_limit` |
`int`
|
Optional
| Defaults to the total RAM of the Linode. **(Updatable)** | -| `root_device` |
`str`
|
Optional
| The root device to boot. **(Updatable)** | -| `run_level` |
`str`
|
Optional
| Defines the state of your Linode after booting. **(Updatable)** | -| `virt_mode` |
`str`
|
Optional
| Controls the virtualization mode. **(Choices: `paravirt`, `fullvirt`; Updatable)** | -| [`interfaces` (sub-options)](#interfaces) |
`list`
|
Optional
| A list of network interfaces to apply to the Linode. See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/#configuration-profile-create__request-body-schema). **(Updatable)** | - - - - - -### devices - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| [`sda` (sub-options)](#sda) |
`dict`
|
Optional
| | -| [`sdb` (sub-options)](#sdb) |
`dict`
|
Optional
| | -| [`sdc` (sub-options)](#sdc) |
`dict`
|
Optional
| | -| [`sdd` (sub-options)](#sdd) |
`dict`
|
Optional
| | -| [`sde` (sub-options)](#sde) |
`dict`
|
Optional
| | -| [`sdf` (sub-options)](#sdf) |
`dict`
|
Optional
| | -| [`sdg` (sub-options)](#sdg) |
`dict`
|
Optional
| | -| [`sdh` (sub-options)](#sdh) |
`dict`
|
Optional
| | - - - - - -### sda - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | -| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | -| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | - - - - - -### sdb - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | -| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | -| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | - - - - - -### sdc - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | -| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | -| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | - - - - - -### sdd - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | -| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | -| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | - - - - - -### sde - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | -| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | -| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | - - - - - -### sdf - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | -| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | -| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | - - - - - -### sdg - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | -| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | -| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | - - - - - -### sdh - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | -| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | -| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | - - - - - -### helpers - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `devtmpfs_automount` |
`bool`
|
Optional
| Populates the /dev directory early during boot without udev. | -| `distro` |
`bool`
|
Optional
| Helps maintain correct inittab/upstart console device. | -| `modules_dep` |
`bool`
|
Optional
| Creates a modules dependency file for the Kernel you run. | -| `network` |
`bool`
|
Optional
| Automatically configures static networking. | -| `updatedb_disabled` |
`bool`
|
Optional
| Disables updatedb cron job to avoid disk thrashing. | - - - - - -### interfaces - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `purpose` |
`str`
|
**Required**
| The type of interface. **(Choices: `public`, `vlan`)** | -| `label` |
`str`
|
Optional
| The name of this interface. Required for vlan purpose interfaces. Must be an empty string or null for public purpose interfaces. | -| `ipam_address` |
`str`
|
Optional
| This Network Interface’s private IP address in Classless Inter-Domain Routing (CIDR) notation. | - - - - - -### disks - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| The label to give this Disk. | -| `size` |
`int`
|
**Required**
| The size of the Disk in MB. **(Updatable)** | -| `authorized_keys` |
`list`
|
Optional
| A list of SSH public key parts to deploy for the root user. | -| `authorized_users` |
`list`
|
Optional
| A list of usernames. | -| `filesystem` |
`str`
|
Optional
| The filesystem to create this disk with. | -| `image` |
`str`
|
Optional
| An Image ID to deploy the Disk from. | -| `root_pass` |
`str`
|
Optional
| The root user’s password on the newly-created Linode. | -| `stackscript_id` |
`int`
|
Optional
| The ID of the StackScript to use when creating the instance. See the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/). | -| `stackscript_data` |
`dict`
|
Optional
| 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 the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/). | - - - - - - -## Return Values - -- `instance` - The instance description in JSON serialized form. - - - Sample Response: - ```json - { - "alerts": { - "cpu": 180, - "io": 10000, - "network_in": 10, - "network_out": 10, - "transfer_quota": 80 - }, - "backups": { - "enabled": true, - "last_successful": "2018-01-01T00:01:01", - "schedule": { - "day": "Saturday", - "window": "W22" - } - }, - "created": "2018-01-01T00:01:01", - "group": "Linode-Group", - "hypervisor": "kvm", - "id": 123, - "image": "linode/debian10", - "ipv4": [ - "203.0.113.1", - "192.0.2.1" - ], - "ipv6": "c001:d00d::1337/128", - "label": "linode123", - "region": "us-east", - "specs": { - "disk": 81920, - "memory": 4096, - "transfer": 4000, - "vcpus": 2 - }, - "status": "running", - "tags": [ - "example tag", - "another example" - ], - "type": "g6-standard-1", - "updated": "2018-01-01T00:01:01", - "watchdog_enabled": true - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#linode-view__responses) for a list of returned fields - - -- `configs` - A list of configs tied to this Linode Instance. - - - Sample Response: - ```json - [ - { - "comments": "This is my main Config", - "devices": { - "sda": { - "disk_id": 124458, - "volume_id": null - }, - "sdb": { - "disk_id": 124458, - "volume_id": null - }, - "sdc": { - "disk_id": 124458, - "volume_id": null - }, - "sdd": { - "disk_id": 124458, - "volume_id": null - }, - "sde": { - "disk_id": 124458, - "volume_id": null - }, - "sdf": { - "disk_id": 124458, - "volume_id": null - }, - "sdg": { - "disk_id": 124458, - "volume_id": null - }, - "sdh": { - "disk_id": 124458, - "volume_id": null - } - }, - "helpers": { - "devtmpfs_automount": false, - "distro": true, - "modules_dep": true, - "network": true, - "updatedb_disabled": true - }, - "id": 23456, - "interfaces": [ - { - "ipam_address": "10.0.0.1/24", - "label": "example-interface", - "purpose": "vlan" - } - ], - "kernel": "linode/latest-64bit", - "label": "My Config", - "memory_limit": 2048, - "root_device": "/dev/sda", - "run_level": "default", - "virt_mode": "paravirt" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#configuration-profile-view__responses) for a list of returned fields - - -- `disks` - A list of disks tied to this Linode Instance. - - - Sample Response: - ```json - [ - { - "created": "2018-01-01T00:01:01", - "filesystem": "ext4", - "id": 25674, - "label": "Debian 9 Disk", - "size": 48640, - "status": "ready", - "updated": "2018-01-01T00:01:01" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#disk-view__responses) for a list of returned fields - - -- `networking` - Networking information about this Linode Instance. - - - Sample Response: - ```json - - { - "ipv4": { - "private": [ - { - "address": "192.168.133.234", - "gateway": null, - "linode_id": 123, - "prefix": 17, - "public": false, - "rdns": null, - "region": "us-east", - "subnet_mask": "255.255.128.0", - "type": "ipv4" - } - ], - "public": [ - { - "address": "97.107.143.141", - "gateway": "97.107.143.1", - "linode_id": 123, - "prefix": 24, - "public": true, - "rdns": "test.example.org", - "region": "us-east", - "subnet_mask": "255.255.255.0", - "type": "ipv4" - } - ], - "reserved": [ - { - "address": "97.107.143.141", - "gateway": "97.107.143.1", - "linode_id": 123, - "prefix": 24, - "public": true, - "rdns": "test.example.org", - "region": "us-east", - "subnet_mask": "255.255.255.0", - "type": "ipv4" - } - ], - "shared": [ - { - "address": "97.107.143.141", - "gateway": "97.107.143.1", - "linode_id": 123, - "prefix": 24, - "public": true, - "rdns": "test.example.org", - "region": "us-east", - "subnet_mask": "255.255.255.0", - "type": "ipv4" - } - ] - }, - "ipv6": { - "global": { - "prefix": 124, - "range": "2600:3c01::2:5000:0", - "region": "us-east", - "route_target": "2600:3c01::2:5000:f" - }, - "link_local": { - "address": "fe80::f03c:91ff:fe24:3a2f", - "gateway": "fe80::1", - "linode_id": 123, - "prefix": 64, - "public": false, - "rdns": null, - "region": "us-east", - "subnet_mask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff", - "type": "ipv6" - }, - "slaac": { - "address": "2600:3c03::f03c:91ff:fe24:3a2f", - "gateway": "fe80::1", - "linode_id": 123, - "prefix": 64, - "public": true, - "rdns": null, - "region": "us-east", - "subnet_mask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff", - "type": "ipv6" - } - } - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#networking-information-list__responses) for a list of returned fields - - diff --git a/docs/modules/instance_info.md b/docs/modules/instance_info.md deleted file mode 100644 index fc5cc6cf..00000000 --- a/docs/modules/instance_info.md +++ /dev/null @@ -1,279 +0,0 @@ -# instance_info - -Get info about a Linode Instance. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about an instance by label - linode.cloud.instance_info: - label: 'my-instance' -``` - -```yaml -- name: Get info about an instance by id - linode.cloud.instance_info: - id: 12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`int`
|
Optional
| The instance’s label. Optional if `label` is defined. | -| `label` |
`str`
|
Optional
| The unique ID of the Instance. Optional if `id` is defined. | - - - - - - -## Return Values - -- `instance` - The instance description in JSON serialized form. - - - Sample Response: - ```json - { - "alerts": { - "cpu": 180, - "io": 10000, - "network_in": 10, - "network_out": 10, - "transfer_quota": 80 - }, - "backups": { - "enabled": true, - "last_successful": "2018-01-01T00:01:01", - "schedule": { - "day": "Saturday", - "window": "W22" - } - }, - "created": "2018-01-01T00:01:01", - "group": "Linode-Group", - "hypervisor": "kvm", - "id": 123, - "image": "linode/debian10", - "ipv4": [ - "203.0.113.1", - "192.0.2.1" - ], - "ipv6": "c001:d00d::1337/128", - "label": "linode123", - "region": "us-east", - "specs": { - "disk": 81920, - "memory": 4096, - "transfer": 4000, - "vcpus": 2 - }, - "status": "running", - "tags": [ - "example tag", - "another example" - ], - "type": "g6-standard-1", - "updated": "2018-01-01T00:01:01", - "watchdog_enabled": true - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#linode-view__responses) for a list of returned fields - - -- `configs` - A list of configs tied to this Linode Instance. - - - Sample Response: - ```json - [ - { - "comments": "This is my main Config", - "devices": { - "sda": { - "disk_id": 124458, - "volume_id": null - }, - "sdb": { - "disk_id": 124458, - "volume_id": null - }, - "sdc": { - "disk_id": 124458, - "volume_id": null - }, - "sdd": { - "disk_id": 124458, - "volume_id": null - }, - "sde": { - "disk_id": 124458, - "volume_id": null - }, - "sdf": { - "disk_id": 124458, - "volume_id": null - }, - "sdg": { - "disk_id": 124458, - "volume_id": null - }, - "sdh": { - "disk_id": 124458, - "volume_id": null - } - }, - "helpers": { - "devtmpfs_automount": false, - "distro": true, - "modules_dep": true, - "network": true, - "updatedb_disabled": true - }, - "id": 23456, - "interfaces": [ - { - "ipam_address": "10.0.0.1/24", - "label": "example-interface", - "purpose": "vlan" - } - ], - "kernel": "linode/latest-64bit", - "label": "My Config", - "memory_limit": 2048, - "root_device": "/dev/sda", - "run_level": "default", - "virt_mode": "paravirt" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#configuration-profile-view__responses) for a list of returned fields - - -- `disks` - A list of disks tied to this Linode Instance. - - - Sample Response: - ```json - [ - { - "created": "2018-01-01T00:01:01", - "filesystem": "ext4", - "id": 25674, - "label": "Debian 9 Disk", - "size": 48640, - "status": "ready", - "updated": "2018-01-01T00:01:01" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#disk-view__responses) for a list of returned fields - - -- `networking` - Networking information about this Linode Instance. - - - Sample Response: - ```json - - { - "ipv4": { - "private": [ - { - "address": "192.168.133.234", - "gateway": null, - "linode_id": 123, - "prefix": 17, - "public": false, - "rdns": null, - "region": "us-east", - "subnet_mask": "255.255.128.0", - "type": "ipv4" - } - ], - "public": [ - { - "address": "97.107.143.141", - "gateway": "97.107.143.1", - "linode_id": 123, - "prefix": 24, - "public": true, - "rdns": "test.example.org", - "region": "us-east", - "subnet_mask": "255.255.255.0", - "type": "ipv4" - } - ], - "reserved": [ - { - "address": "97.107.143.141", - "gateway": "97.107.143.1", - "linode_id": 123, - "prefix": 24, - "public": true, - "rdns": "test.example.org", - "region": "us-east", - "subnet_mask": "255.255.255.0", - "type": "ipv4" - } - ], - "shared": [ - { - "address": "97.107.143.141", - "gateway": "97.107.143.1", - "linode_id": 123, - "prefix": 24, - "public": true, - "rdns": "test.example.org", - "region": "us-east", - "subnet_mask": "255.255.255.0", - "type": "ipv4" - } - ] - }, - "ipv6": { - "global": { - "prefix": 124, - "range": "2600:3c01::2:5000:0", - "region": "us-east", - "route_target": "2600:3c01::2:5000:f" - }, - "link_local": { - "address": "fe80::f03c:91ff:fe24:3a2f", - "gateway": "fe80::1", - "linode_id": 123, - "prefix": 64, - "public": false, - "rdns": null, - "region": "us-east", - "subnet_mask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff", - "type": "ipv6" - }, - "slaac": { - "address": "2600:3c03::f03c:91ff:fe24:3a2f", - "gateway": "fe80::1", - "linode_id": 123, - "prefix": 64, - "public": true, - "rdns": null, - "region": "us-east", - "subnet_mask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff", - "type": "ipv6" - } - } - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#networking-information-list__responses) for a list of returned fields - - diff --git a/docs/modules/ip_info.md b/docs/modules/ip_info.md deleted file mode 100644 index b91d29be..00000000 --- a/docs/modules/ip_info.md +++ /dev/null @@ -1,58 +0,0 @@ -# ip_info - -Get info about a Linode IP. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about an IP address - linode.cloud.ip_info: - address: 97.107.143.141 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `address` |
`str`
|
**Required**
| The IP address to operate on. | - - - - - - -## Return Values - -- `ip` - The IP in JSON serialized form. - - - Sample Response: - ```json - { - "address": "97.107.143.141", - "gateway": "97.107.143.1", - "linode_id": 123, - "prefix": 24, - "public": true, - "rdns": "test.example.org", - "region": "us-east", - "subnet_mask": "255.255.255.0", - "type": "ipv4" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#ip-address-view__responses) for a list of returned fields - - diff --git a/docs/modules/ipv6_range_info.md b/docs/modules/ipv6_range_info.md deleted file mode 100644 index 5c8f37d2..00000000 --- a/docs/modules/ipv6_range_info.md +++ /dev/null @@ -1,56 +0,0 @@ -# ipv6_range_info - -Get info about a Linode IPv6 range. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about an IPv6 range - linode.cloud.ipv6_range_info: - range: 2600:3c01:: -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `range` |
`str`
|
Optional
| The IPv6 range to access. | - - - - - - -## Return Values - -- `range` - The IPv6 range in JSON serialized form. - - - Sample Response: - ```json - { - "is_bgp": false, - "linodes": [ - 123 - ], - "prefix": 64, - "range": "2600:3c01::", - "region": "us-east" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#ipv6-range-view__response-samples) for a list of returned fields - - diff --git a/docs/modules/lke_cluster.md b/docs/modules/lke_cluster.md deleted file mode 100644 index de87e878..00000000 --- a/docs/modules/lke_cluster.md +++ /dev/null @@ -1,169 +0,0 @@ -# lke_cluster - -Manage Linode LKE clusters. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a Linode LKE cluster - linode.cloud.lke_cluster: - label: 'my-cluster' - region: us-southeast - k8s_version: 1.23 - node_pools: - - type: g6-standard-1 - count: 3 - - type: g6-standard-2 - count: 2 - state: present -``` - -```yaml -- name: Create a Linode LKE cluster with autoscaler - linode.cloud.lke_cluster: - label: 'my-cluster' - region: us-southeast - k8s_version: 1.23 - node_pools: - - type: g6-standard-1 - count: 2 - autoscaler: - enable: true - min: 2 - max: 5 - state: present -``` - -```yaml -- name: Delete a Linode LKE cluster - linode.cloud.lke_cluster: - label: 'my-cluster' - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| This Kubernetes cluster’s unique label. | -| `k8s_version` |
`str`
|
Optional
| The desired Kubernetes version for this Kubernetes cluster in the format of ., and the latest supported patch version will be deployed. A version upgrade requires that you manually recycle the nodes in your cluster. **(Updatable)** | -| `region` |
`str`
|
Optional
| This Kubernetes cluster’s location. | -| `tags` |
`list`
|
Optional
| An array of tags applied to the Kubernetes cluster. | -| `high_availability` |
`bool`
|
Optional
| Defines whether High Availability is enabled for the Control Plane Components of the cluster. **(Default: `False`; Updatable)** | -| [`node_pools` (sub-options)](#node_pools) |
`list`
|
Optional
| A list of node pools to configure the cluster with **(Updatable)** | -| `skip_polling` |
`bool`
|
Optional
| If true, the module will not wait for all nodes in the cluster to be ready. **(Default: `False`)** | -| `wait_timeout` |
`int`
|
Optional
| The period to wait for the cluster to be ready in seconds. **(Default: `600`)** | - - - - - -### node_pools - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `count` |
`int`
|
**Required**
| The number of nodes in the Node Pool. **(Updatable)** | -| `type` |
`str`
|
**Required**
| The Linode Type for all of the nodes in the Node Pool. | -| [`autoscaler` (sub-options)](#autoscaler) |
`dict`
|
Optional
| When enabled, the number of nodes autoscales within the defined minimum and maximum values. **(Updatable)** | - - - - - -### autoscaler - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `enabled` |
`bool`
|
Optional
| Whether autoscaling is enabled for this Node Pool. NOTE: Subsequent playbook runs will override nodes created by the cluster autoscaler. **(Updatable)** | -| `max` |
`int`
|
Optional
| The maximum number of nodes to autoscale to. Defaults to the value provided by the count field. **(Updatable)** | -| `min` |
`int`
|
Optional
| The minimum number of nodes to autoscale to. Defaults to the Node Pool’s count. **(Updatable)** | - - - - - - -## Return Values - -- `cluster` - The LKE cluster in JSON serialized form. - - - Sample Response: - ```json - { - "control_plane": { - "high_availability": true - }, - "created": "2019-09-12T21:25:30Z", - "id": 1234, - "k8s_version": "1.23", - "label": "lkecluster12345", - "region": "us-central", - "tags": [ - "ecomm", - "blogs" - ], - "updated": "2019-09-13T21:24:16Z" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-cluster-view__response-samples) for a list of returned fields - - -- `node_pools` - A list of node pools in JSON serialized form. - - - Sample Response: - ```json - [ - { - "autoscaler": { - "enabled": true, - "max": 12, - "min": 3 - }, - "count": 6, - "disks": [ - { - "size": 1024, - "type": "ext-4" - } - ], - "id": 456, - "nodes": [ - { - "id": "123456", - "instance_id": 123458, - "status": "ready" - } - ], - "tags": [ - "example tag", - "another example" - ], - "type": "g6-standard-4" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#node-pools-list__response-samples) for a list of returned fields - - -- `kubeconfig` - The Base64-encoded kubeconfig used to access this cluster.NOTE: This value may be unavailable if `skip_polling` is true. - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubeconfig-view__responses) for a list of returned fields - - -- `dashboard_url` - The Cluster Dashboard access URL. - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-cluster-dashboard-url-view__responses) for a list of returned fields - - diff --git a/docs/modules/lke_cluster_info.md b/docs/modules/lke_cluster_info.md deleted file mode 100644 index 3d963e19..00000000 --- a/docs/modules/lke_cluster_info.md +++ /dev/null @@ -1,114 +0,0 @@ -# lke_cluster_info - -Get info about a Linode LKE cluster. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about an LKE cluster by label - linode.cloud.lke_cluster_info: - label: 'my-cluster' -``` - -```yaml -- name: Get info about an LKE cluster by ID - linode.cloud.lke_cluster_info: - id: 12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`int`
|
Optional
| The ID of the LKE cluster. Optional if `label` is defined. | -| `label` |
`str`
|
Optional
| The label of the LKE cluster. Optional if `id` is defined. | - - - - - - -## Return Values - -- `cluster` - The LKE cluster in JSON serialized form. - - - Sample Response: - ```json - { - "control_plane": { - "high_availability": true - }, - "created": "2019-09-12T21:25:30Z", - "id": 1234, - "k8s_version": "1.23", - "label": "lkecluster12345", - "region": "us-central", - "tags": [ - "ecomm", - "blogs" - ], - "updated": "2019-09-13T21:24:16Z" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-cluster-view__response-samples) for a list of returned fields - - -- `node_pools` - A list of node pools in JSON serialized form. - - - Sample Response: - ```json - [ - { - "autoscaler": { - "enabled": true, - "max": 12, - "min": 3 - }, - "count": 6, - "disks": [ - { - "size": 1024, - "type": "ext-4" - } - ], - "id": 456, - "nodes": [ - { - "id": "123456", - "instance_id": 123458, - "status": "ready" - } - ], - "tags": [ - "example tag", - "another example" - ], - "type": "g6-standard-4" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#node-pools-list__response-samples) for a list of returned fields - - -- `kubeconfig` - The Base64-encoded kubeconfig used to access this cluster.NOTE: This value may be unavailable if the cluster is not fully provisioned. - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubeconfig-view__responses) for a list of returned fields - - -- `dashboard_url` - The Cluster Dashboard access URL. - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-cluster-dashboard-url-view__responses) for a list of returned fields - - diff --git a/docs/modules/lke_node_pool.md b/docs/modules/lke_node_pool.md deleted file mode 100644 index 5ae7aa99..00000000 --- a/docs/modules/lke_node_pool.md +++ /dev/null @@ -1,132 +0,0 @@ -# lke_node_pool - -Manage Linode LKE cluster node pools. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a Linode LKE node pool - linode.cloud.lke_node_pool: - cluster_id: 12345 - - tags: ['my-pool'] - count: 3 - type: g6-standard-2 - state: present -``` - -```yaml -- name: Create a Linode LKE node pool with autoscaler - linode.cloud.lke_node_pool: - cluster_id: 12345 - - tags: ['my-pool'] - count: 3 - type: g6-standard-2 - - autoscaler: - enabled: true - min: 1 - max: 3 - - state: present -- name: Delete a Linode LKE node pool - linode.cloud.lke_node_pool: - cluster_id: 12345 - tags: ['my-pool'] - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `cluster_id` |
`int`
|
**Required**
| The ID of the LKE cluster that contains this node pool. | -| `tags` |
`list`
|
**Required**
| An array of tags applied to this object. Tags must be unique as they are used by the `lke_node_pool` module to uniquely identify node pools. **(Updatable)** | -| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | -| [`autoscaler` (sub-options)](#autoscaler) |
`dict`
|
Optional
| When enabled, the number of nodes autoscales within the defined minimum and maximum values. **(Updatable)** | -| `count` |
`int`
|
Optional
| The number of nodes in the Node Pool. **(Updatable)** | -| [`disks` (sub-options)](#disks) |
`list`
|
Optional
| This Node Pool’s custom disk layout. Each item in this array will create a new disk partition for each node in this Node Pool. | -| `type` |
`str`
|
Optional
| The Linode Type for all of the nodes in the Node Pool. Required if `state` == `present`. | -| `skip_polling` |
`bool`
|
Optional
| If true, the module will not wait for all nodes in the node pool to be ready. **(Default: `False`)** | -| `wait_timeout` |
`int`
|
Optional
| The period to wait for the node pool to be ready in seconds. **(Default: `600`)** | - - - - - -### autoscaler - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `enabled` |
`bool`
|
Optional
| Whether autoscaling is enabled for this Node Pool. NOTE: Subsequent playbook runs will override nodes created by the cluster autoscaler. **(Updatable)** | -| `max` |
`int`
|
Optional
| The maximum number of nodes to autoscale to. Defaults to the value provided by the count field. **(Updatable)** | -| `min` |
`int`
|
Optional
| The minimum number of nodes to autoscale to. Defaults to the Node Pool’s count. **(Updatable)** | - - - - - -### disks - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `type` |
`str`
|
**Required**
| This custom disk partition’s filesystem type. **(Choices: `raw`, `ext4`)** | -| `size` |
`int`
|
**Required**
| The size of this custom disk partition in MB. | - - - - - - -## Return Values - -- `node_pool` - The Node Pool in JSON serialized form. - - - Sample Response: - ```json - { - "autoscaler": { - "enabled": true, - "max": 12, - "min": 3 - }, - "count": 6, - "disks": [ - { - "size": 1024, - "type": "ext-4" - } - ], - "id": 456, - "nodes": [ - { - "id": "123456", - "instance_id": 123458, - "status": "ready" - } - ], - "tags": [ - "example tag", - "another example" - ], - "type": "g6-standard-4" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#node-pool-view__response-samples) for a list of returned fields - - diff --git a/docs/modules/nodebalancer.md b/docs/modules/nodebalancer.md deleted file mode 100644 index 7462278b..00000000 --- a/docs/modules/nodebalancer.md +++ /dev/null @@ -1,183 +0,0 @@ -# nodebalancer - -Manage a Linode NodeBalancer. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- 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 -``` - -```yaml -- name: Delete the NodeBalancer - linode.cloud.nodebalancer: - label: my-loadbalancer - region: us-east - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| The unique label to give this NodeBalancer. | -| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | -| `client_conn_throttle` |
`int`
|
Optional
| Throttle connections per second. Set to 0 (zero) to disable throttling. **(Updatable)** | -| `region` |
`str`
|
Optional
| The ID of the Region to create this NodeBalancer in. | -| [`configs` (sub-options)](#configs) |
`list`
|
Optional
| A list of configs to apply to the NodeBalancer. **(Updatable)** | - - - - - -### configs - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `algorithm` |
`str`
|
Optional
| What algorithm this NodeBalancer should use for routing traffic to backends. **(Choices: `roundrobin`, `leastconn`, `source`; Updatable)** | -| `check` |
`str`
|
Optional
| The type of check to perform against backends to ensure they are serving requests. **(Choices: `none`, `connection`, `http`, `http_body`; Updatable)** | -| `check_attempts` |
`int`
|
Optional
| How many times to attempt a check before considering a backend to be down. **(Updatable)** | -| `check_body` |
`str`
|
Optional
| 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. **(Updatable)** | -| `check_interval` |
`int`
|
Optional
| How often, in seconds, to check that backends are up and serving requests. **(Updatable)** | -| `check_passive` |
`bool`
|
Optional
| 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. **(Updatable)** | -| `check_path` |
`str`
|
Optional
| The URL path to check on each backend. If the backend does not respond to this request it is considered to be down. **(Updatable)** | -| `check_timeout` |
`int`
|
Optional
| How long, in seconds, to wait for a check attempt before considering it failed. **(Updatable)** | -| `cipher_suite` |
`str`
|
Optional
| What ciphers to use for SSL connections served by this NodeBalancer. **(Choices: `recommended`, `legacy`; Default: `recommended`; Updatable)** | -| `port` |
`int`
|
Optional
| The port this Config is for. **(Updatable)** | -| `protocol` |
`str`
|
Optional
| The protocol this port is configured to serve. **(Choices: `http`, `https`, `tcp`; Updatable)** | -| `proxy_protocol` |
`str`
|
Optional
| ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. **(Choices: `none`, `v1`, `v2`; Updatable)** | -| `recreate` |
`bool`
|
Optional
| If true, the config will be forcibly recreated on every run. This is useful for updates to redacted fields (`ssl_cert`, `ssl_key`) **(Default: `False`)** | -| `ssl_cert` |
`str`
|
Optional
| 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. **(Updatable)** | -| `ssl_key` |
`str`
|
Optional
| The PEM-formatted private key for the SSL certificate set in the ssl_cert field. **(Updatable)** | -| `stickiness` |
`str`
|
Optional
| Controls how session stickiness is handled on this port. **(Choices: `none`, `table`, `http_cookie`; Updatable)** | -| [`nodes` (sub-options)](#nodes) |
`list`
|
Optional
| A list of nodes to apply to this config. These can alternatively be configured through the nodebalancer_node module. **(Updatable)** | - - - - - -### nodes - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| The label for this node. | -| `address` |
`str`
|
**Required**
| The private IP Address where this backend can be reached. This must be a private IP address. **(Updatable)** | -| `weight` |
`int`
|
Optional
| Nodes with a higher weight will receive more traffic. **(Updatable)** | -| `mode` |
`str`
|
Optional
| The mode this NodeBalancer should use when sending traffic to this backend. **(Choices: `accept`, `reject`, `drain`, `backup`; Updatable)** | - - - - - - -## Return Values - -- `node_balancer` - The NodeBalancer in JSON serialized form. - - - Sample Response: - ```json - { - "client_conn_throttle": 0, - "created": "2018-01-01T00:01:01", - "hostname": "192.0.2.1.ip.linodeusercontent.com", - "id": 12345, - "ipv4": "12.34.56.78", - "ipv6": null, - "label": "balancer12345", - "region": "us-east", - "tags": [ - "example tag", - "another example" - ], - "transfer": { - "in": 28.91200828552246, - "out": 3.5487728118896484, - "total": 32.46078109741211 - }, - "updated": "2018-03-01T00:01:01" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#nodebalancer-view__responses) for a list of returned fields - - -- `configs` - A list of configs applied to the NodeBalancer. - - - Sample Response: - ```json - [ - { - "algorithm": "roundrobin", - "check": "http_body", - "check_attempts": 3, - "check_body": "it works", - "check_interval": 90, - "check_passive": true, - "check_path": "/test", - "check_timeout": 10, - "cipher_suite": "recommended", - "id": 4567, - "nodebalancer_id": 12345, - "nodes_status": { - "down": 0, - "up": 4 - }, - "port": 80, - "protocol": "http", - "proxy_protocol": "none", - "ssl_cert": null, - "ssl_commonname": null, - "ssl_fingerprint": null, - "ssl_key": null, - "stickiness": "http_cookie" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#config-view__responses) for a list of returned fields - - -- `nodes` - A list of configs applied to the NodeBalancer. - - - Sample Response: - ```json - [ - { - "address": "192.168.210.120:80", - "config_id": 4567, - "id": 54321, - "label": "node54321", - "mode": "accept", - "nodebalancer_id": 12345, - "status": "UP", - "weight": 50 - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#node-view) for a list of returned fields - - diff --git a/docs/modules/nodebalancer_info.md b/docs/modules/nodebalancer_info.md deleted file mode 100644 index 67930687..00000000 --- a/docs/modules/nodebalancer_info.md +++ /dev/null @@ -1,129 +0,0 @@ -# nodebalancer_info - -Get info about a Linode NodeBalancer. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get a NodeBalancer by its id - linode.cloud.nodebalancer_info: - id: 12345 -``` - -```yaml -- name: Get a NodeBalancer by its label - linode.cloud.nodebalancer_info: - label: cool_nodebalancer -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`int`
|
Optional
| The ID of this NodeBalancer. Optional if `label` is defined. | -| `label` |
`str`
|
Optional
| The label of this NodeBalancer. Optional if `id` is defined. | - - - - - - -## Return Values - -- `node_balancer` - The NodeBalancer in JSON serialized form. - - - Sample Response: - ```json - { - "client_conn_throttle": 0, - "created": "2018-01-01T00:01:01", - "hostname": "192.0.2.1.ip.linodeusercontent.com", - "id": 12345, - "ipv4": "12.34.56.78", - "ipv6": null, - "label": "balancer12345", - "region": "us-east", - "tags": [ - "example tag", - "another example" - ], - "transfer": { - "in": 28.91200828552246, - "out": 3.5487728118896484, - "total": 32.46078109741211 - }, - "updated": "2018-03-01T00:01:01" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#nodebalancer-view__responses) for a list of returned fields - - -- `configs` - A list of configs applied to the NodeBalancer. - - - Sample Response: - ```json - [ - { - "algorithm": "roundrobin", - "check": "http_body", - "check_attempts": 3, - "check_body": "it works", - "check_interval": 90, - "check_passive": true, - "check_path": "/test", - "check_timeout": 10, - "cipher_suite": "recommended", - "id": 4567, - "nodebalancer_id": 12345, - "nodes_status": { - "down": 0, - "up": 4 - }, - "port": 80, - "protocol": "http", - "proxy_protocol": "none", - "ssl_cert": null, - "ssl_commonname": null, - "ssl_fingerprint": null, - "ssl_key": null, - "stickiness": "http_cookie" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#config-view__responses) for a list of returned fields - - -- `nodes` - A list of configs applied to the NodeBalancer. - - - Sample Response: - ```json - [ - { - "address": "192.168.210.120:80", - "config_id": 4567, - "id": 54321, - "label": "node54321", - "mode": "accept", - "nodebalancer_id": 12345, - "status": "UP", - "weight": 50 - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#node-view) for a list of returned fields - - diff --git a/docs/modules/nodebalancer_node.md b/docs/modules/nodebalancer_node.md deleted file mode 100644 index b0d63a01..00000000 --- a/docs/modules/nodebalancer_node.md +++ /dev/null @@ -1,91 +0,0 @@ -# nodebalancer_node - -Manage Linode NodeBalancer Nodes. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a NodeBalancer - linode.cloud.nodebalancer: - label: my-nodebalancer - region: us-east - state: present - configs: - - port: 80 - protocol: http - algorithm: roundrobin - register: nodebalancer_result - -- name: Create an Instance - linode.cloud.instance: - label: my-instance - region: us-east - private_ip: true - type: g6-standard-1 - state: present - register: instance_result - -- name: Attach the Instance to the NodeBalancer - linode.cloud.nodebalancer_node: - nodebalancer_id: nodebalancer_result.node_balancer.id - config_id: nodebalancer_result.configs[0].id - - label: my-node - - # Use the private ip address of the instance - address: '{{ instance_result.instance.ipv4[1] }}:80' - - state: present -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `nodebalancer_id` |
`int`
|
**Required**
| The ID of the NodeBalancer that contains this node. | -| `config_id` |
`int`
|
**Required**
| The ID of the NodeBalancer Config that contains this node. | -| `label` |
`str`
|
**Required**
| The label for this node. This is used to identify nodes within a config. | -| `state` |
`str`
|
**Required**
| Whether the NodeBalancer node should be present or absent. **(Choices: `present`, `absent`)** | -| `address` |
`str`
|
Optional
| The private IP Address where this backend can be reached. This must be a private IP address. **(Updatable)** | -| `mode` |
`str`
|
Optional
| The mode this NodeBalancer should use when sending traffic to this backend. **(Choices: `accept`, `reject`, `drain`, `backup`; Updatable)** | -| `weight` |
`int`
|
Optional
| Nodes with a higher weight will receive more traffic. **(Updatable)** | - - - - - - -## Return Values - -- `node` - The NodeBalancer Node in JSON serialized form. - - - Sample Response: - ```json - { - "address": "123.123.123.123:80", - "config_id": 12345, - "id": 12345, - "label": "mynode", - "mode": "accept", - "nodebalancer_id": 12345, - "status": "Unknown", - "weight": 10 - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#node-view__responses) for a list of returned fields - - diff --git a/docs/modules/object_cluster_info.md b/docs/modules/object_cluster_info.md deleted file mode 100644 index f85ea1e1..00000000 --- a/docs/modules/object_cluster_info.md +++ /dev/null @@ -1,65 +0,0 @@ -# object_cluster_info - -Get info about a Linode Object Storage Cluster. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about clusters in us-east - linode.cloud.object_cluster_info: - region: us-east -``` - -```yaml -- name: Get info about the cluster with id us-east-1 - linode.cloud.object_cluster_info: - id: us-east-1 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`str`
|
Optional
| The unique id given to the clusters. | -| `region` |
`str`
|
Optional
| The region the clusters are in. | -| `domain` |
`str`
|
Optional
| The domain of the clusters. | -| `static_site_domain` |
`str`
|
Optional
| The static-site domain of the clusters. | - - - - - - -## Return Values - -- `clusters` - The Object Storage clusters in JSON serialized form. - - - Sample Response: - ```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" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/object-storage/#cluster-view__responses) for a list of returned fields - - diff --git a/docs/modules/object_keys.md b/docs/modules/object_keys.md deleted file mode 100644 index 020aa27b..00000000 --- a/docs/modules/object_keys.md +++ /dev/null @@ -1,94 +0,0 @@ -# object_keys - -Manage Linode Object Storage Keys. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create an Object Storage key - linode.cloud.object_keys: - label: 'my-fullaccess-key' - state: present -``` - -```yaml -- 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 -``` - -```yaml -- name: Remove an object storage key - linode.cloud.object_keys: - label: 'my-key' - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | -| `label` |
`str`
|
Optional
| The unique label to give this key. | -| [`access` (sub-options)](#access) |
`list`
|
Optional
| A list of access permissions to give the key. | - - - - - -### access - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `cluster` |
`str`
|
**Required**
| The id of the cluster that the provided bucket exists under. | -| `bucket_name` |
`str`
|
**Required**
| The name of the bucket to set the key's permissions for. | -| `permissions` |
`str`
|
**Required**
| The permissions to give the key. **(Choices: `read_only`, `write_only`, `read_write`)** | - - - - - - -## Return Values - -- `key` - The Object Storage key in JSON serialized form. - - - Sample Response: - ```json - { - "access_key": "ACCESSKEY", - "bucket_access": [ - { - "bucket_name": "example-bucket", - "cluster": "ap-south-1", - "permissions": "read_only" - } - ], - "id": 123, - "label": "my-key", - "limited": true, - "secret_key": "SECRETKEY" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/object-storage/#object-storage-key-view__responses) for a list of returned fields - - diff --git a/docs/modules/profile_info.md b/docs/modules/profile_info.md deleted file mode 100644 index 61551448..00000000 --- a/docs/modules/profile_info.md +++ /dev/null @@ -1,59 +0,0 @@ -# profile_info - -Get info about a Linode Profile. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about the current Linode profile - linode.cloud.profile_info: {} -``` - - - - - - - - - - -## Return Values - -- `profile` - The profile info in JSON serialized form. - - - Sample Response: - ```json - { - "authentication_type": "password", - "authorized_keys": [ - null - ], - "email": "example-user@gmail.com", - "email_notifications": true, - "ip_whitelist_enabled": false, - "lish_auth_method": "keys_only", - "referrals": { - "code": "871be32f49c1411b14f29f618aaf0c14637fb8d3", - "completed": 0, - "credit": 0, - "pending": 0, - "total": 0, - "url": "https://www.linode.com/?r=871be32f49c1411b14f29f618aaf0c14637fb8d3" - }, - "restricted": false, - "timezone": "US/Eastern", - "two_factor_auth": true, - "uid": 1234, - "username": "exampleUser", - "verified_phone_number": "+5555555555" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#profile-view__response-samples) for a list of returned fields - - diff --git a/docs/modules/ssh_key.md b/docs/modules/ssh_key.md deleted file mode 100644 index 820f6833..00000000 --- a/docs/modules/ssh_key.md +++ /dev/null @@ -1,63 +0,0 @@ -# ssh_key - -Manage a Linode SSH key. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a basic SSH key - linode.cloud.ssh_key: - label: my-ssh-key - state: present -``` - -```yaml -- name: Delete a SSH key - linode.cloud.ssh_key: - label: my-ssh-key - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| This SSH key's unique label. | -| `state` |
`str`
|
**Required**
| The state of this SSH key. **(Choices: `present`, `absent`)** | -| `ssh_key` |
`str`
|
Optional
| The SSH public key value. **(Updatable)** | - - - - - - -## Return Values - -- `ssh_key` - The created SSH key in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "id": 42, - "label": "My SSH Key", - "ssh_key": "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#ssh-key-add__response-samples) for a list of returned fields - - diff --git a/docs/modules/ssh_key_info.md b/docs/modules/ssh_key_info.md deleted file mode 100644 index 40930331..00000000 --- a/docs/modules/ssh_key_info.md +++ /dev/null @@ -1,60 +0,0 @@ -# ssh_key_info - -Get info about the Linode SSH public key. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about a SSH key by label - linode.cloud.ssh_key_info: - label: my-ssh-key -``` - -```yaml -- name: Get info about a SSH key by ID - linode.cloud.ssh_key_info: - id: 12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`int`
|
Optional
| The ID of the SSH key. | -| `label` |
`str`
|
Optional
| The label of the SSH key. | - - - - - - -## Return Values - -- `ssh_key` - The SSH key in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "id": 42, - "label": "My SSH Key", - "ssh_key": "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#ssh-key-view__response-samples) for a list of returned fields - - diff --git a/docs/modules/ssh_key_list.md b/docs/modules/ssh_key_list.md deleted file mode 100644 index 99e05dff..00000000 --- a/docs/modules/ssh_key_list.md +++ /dev/null @@ -1,96 +0,0 @@ -# ssh_key_list - -List and filter on SSH keys in the Linode profile. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: List all of the SSH keys for the current Linode Account - linode.cloud.ssh_key_list: {} -``` - -```yaml -- name: List the latest 5 SSH keys for the current Linode Account - linode.cloud.ssh_key_list: - - count: 5 - order_by: created - order: desc -``` - -```yaml -- name: List filtered personal SSH keys for the current Linode Account - linode.cloud.ssh_key_list: - - filters: - - name: label-or-some-other-field - values: MySSHKey1 -``` - -```yaml -- name: List filtered personal SSH keys for the current Linode Account - linode.cloud.ssh_key_list: - filters: - - name: label-or-some-other-field - values: - - MySSHKey1 - - MySSHKey2 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `order` |
`str`
|
Optional
| The order to list ssh keys in. **(Choices: `desc`, `asc`; Default: `asc`)** | -| `order_by` |
`str`
|
Optional
| The attribute to order ssh keys by. | -| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting ssh keys. | -| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | - - - - - -### filters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/profile/#ssh-keys-list | -| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | - - - - - - -## Return Values - -- `ssh_keys` - The returned SSH keys. - - - Sample Response: - ```json - [ - { - "created": "2018-01-01T00:01:01", - "id": 42, - "label": "MySSHKey1", - "ssh_key": "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#ssh-keys-list) for a list of returned fields - - diff --git a/docs/modules/stackscript.md b/docs/modules/stackscript.md deleted file mode 100644 index 3b02852f..00000000 --- a/docs/modules/stackscript.md +++ /dev/null @@ -1,96 +0,0 @@ -# stackscript - -Manage a Linode StackScript. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a basic StackScript - linode.cloud.stackscript: - label: my-stackscript - images: ['linode/ubuntu20.04'] - description: Install a system package - script: | - #!/bin/bash - # - apt-get -q update && apt-get -q -y install $PACKAGE - state: present -``` - -```yaml -- name: Delete a StackScript - linode.cloud.stackscript: - label: my-stackscript - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| This StackScript's unique label. | -| `state` |
`str`
|
**Required**
| The state of this StackScript. **(Choices: `present`, `absent`)** | -| `description` |
`str`
|
Optional
| A description for the StackScript. **(Updatable)** | -| `images` |
`list`
|
Optional
| Images that can be deployed using this StackScript. **(Updatable)** | -| `is_public` |
`bool`
|
Optional
| This determines whether other users can use your StackScript. **(Updatable)** | -| `rev_note` |
`str`
|
Optional
| This field allows you to add notes for the set of revisions made to this StackScript. **(Updatable)** | -| `script` |
`str`
|
Optional
| The script to execute when provisioning a new Linode with this StackScript. **(Updatable)** | - - - - - - -## Return Values - -- `stackscript` - The StackScript in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "deployments_active": 1, - "deployments_total": 12, - "description": "This StackScript installs and configures MySQL", - "id": 10079, - "images": [ - "linode/debian9", - "linode/debian8" - ], - "is_public": true, - "label": "a-stackscript", - "mine": true, - "rev_note": "Set up MySQL", - "script": "#!/bin/bash", - "updated": "2018-01-01T00:01:01", - "user_defined_fields": [ - { - "default": null, - "example": "hunter2", - "label": "Enter the password", - "manyOf": "avalue,anothervalue,thirdvalue", - "name": "DB_PASSWORD", - "oneOf": "avalue,anothervalue,thirdvalue" - } - ], - "user_gravatar_id": "a445b305abda30ebc766bc7fda037c37", - "username": "myuser" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/stackscripts/#stackscript-create__response-samples) for a list of returned fields - - diff --git a/docs/modules/stackscript_info.md b/docs/modules/stackscript_info.md deleted file mode 100644 index 7bf11310..00000000 --- a/docs/modules/stackscript_info.md +++ /dev/null @@ -1,83 +0,0 @@ -# stackscript_info - -Get info about a Linode StackScript. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about a StackScript by label - linode.cloud.stackscript_info: - label: my-stackscript -``` - -```yaml -- name: Get info about a StackScript by ID - linode.cloud.stackscript_info: - id: 12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`int`
|
Optional
| The ID of the StackScript. | -| `label` |
`str`
|
Optional
| The label of the StackScript. | - - - - - - -## Return Values - -- `stackscript` - The StackScript in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "deployments_active": 1, - "deployments_total": 12, - "description": "This StackScript installs and configures MySQL", - "id": 10079, - "images": [ - "linode/debian9", - "linode/debian8" - ], - "is_public": true, - "label": "a-stackscript", - "mine": true, - "rev_note": "Set up MySQL", - "script": "#!/bin/bash", - "updated": "2018-01-01T00:01:01", - "user_defined_fields": [ - { - "default": null, - "example": "hunter2", - "label": "Enter the password", - "manyOf": "avalue,anothervalue,thirdvalue", - "name": "DB_PASSWORD", - "oneOf": "avalue,anothervalue,thirdvalue" - } - ], - "user_gravatar_id": "a445b305abda30ebc766bc7fda037c37", - "username": "myuser" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/stackscripts/#stackscript-view__response-samples) for a list of returned fields - - diff --git a/docs/modules/stackscript_list.md b/docs/modules/stackscript_list.md deleted file mode 100644 index 4b2f8a56..00000000 --- a/docs/modules/stackscript_list.md +++ /dev/null @@ -1,107 +0,0 @@ -# stackscript_list - -List and filter on Linode stackscripts. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: List all of the stackscripts for the current Linode Account - linode.cloud.stackscript_list: {} -``` - -```yaml -- name: List the latest 5 stackscripts for the current Linode Account - linode.cloud.stackscript_list: - count: 5 - order_by: created - order: desc -``` - -```yaml -- name: List all personal stackscripts for the current Linode Account - linode.cloud.stackscript_list: - filter: - - name: mine - values: true -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `order` |
`str`
|
Optional
| The order to list events in. **(Choices: `desc`, `asc`; Default: `asc`)** | -| `order_by` |
`str`
|
Optional
| The attribute to order events by. | -| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting events. | -| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | - - - - - -### filters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/stackscripts/#stackscripts-list__response-samples | -| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | - - - - - - -## Return Values - -- `stackscripts` - The returned stackscripts. - - - Sample Response: - ```json - [ - { - "created": "2018-01-01T00:01:01", - "deployments_active": 1, - "deployments_total": 12, - "description": "This StackScript installs and configures MySQL\n", - "id": 10079, - "images": [ - "linode/debian9", - "linode/debian8" - ], - "is_public": true, - "label": "a-stackscript", - "mine": true, - "rev_note": "Set up MySQL", - "script": ""#!/bin/bash"\n", - "updated": "2018-01-01T00:01:01", - "user_defined_fields": [ - { - "default": null, - "example": "hunter2", - "label": "Enter the password", - "manyOf": "avalue,anothervalue,thirdvalue", - "name": "DB_PASSWORD", - "oneOf": "avalue,anothervalue,thirdvalue" - } - ], - "user_gravatar_id": "a445b305abda30ebc766bc7fda037c37", - "username": "myuser" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/stackscripts/#stackscripts-list__response-samples) for a list of returned fields - - diff --git a/docs/modules/token.md b/docs/modules/token.md deleted file mode 100644 index 2e7bf416..00000000 --- a/docs/modules/token.md +++ /dev/null @@ -1,77 +0,0 @@ -# token - -Manage a Linode Token. - -NOTE: The full Personal Access Token is only returned when a new token has been created. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a simple token - linode.cloud.token: - label: my-token - state: present -``` - -```yaml -- name: Create a token with expiry date and scopes - linode.cloud.token: - label: my-token - expiry: 2022-07-09T16:59:26 - scope: '*' - state: present -``` - -```yaml -- name: Delete a token - linode.cloud.token: - domain: my-token - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| This token's unique label. | -| `state` |
`str`
|
**Required**
| The state of this token. **(Choices: `present`, `absent`)** | -| `expiry` |
`str`
|
Optional
| When this token should be valid until. | -| `scopes` |
`str`
|
Optional
| The OAuth scopes to create the token with. | - - - - - - -## Return Values - -- `token` - The token in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "expiry": "2018-01-01T13:46:32", - "id": 123, - "label": "linode-cli", - "scopes": "*", - "token": "abcdefghijklmnop" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#personal-access-token-create__responses) for a list of returned fields - - diff --git a/docs/modules/token_info.md b/docs/modules/token_info.md deleted file mode 100644 index dfabc4ac..00000000 --- a/docs/modules/token_info.md +++ /dev/null @@ -1,62 +0,0 @@ -# token_info - -Get info about a Linode Personal Access Token. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about a token by label - linode.cloud.token_info: - label: my-token -``` - -```yaml -- name: Get info about a token by ID - linode.cloud.token_info: - id: 12345 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`int`
|
Optional
| The ID of the token. | -| `label` |
`str`
|
Optional
| The label of the token. | - - - - - - -## Return Values - -- `token` - The token in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "expiry": "2018-01-01T13:46:32", - "id": 123, - "label": "linode-cli", - "scopes": "*", - "token": "abcdefghijklmnop" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#personal-access-token-create__response-samples) for a list of returned fields - - diff --git a/docs/modules/type_list.md b/docs/modules/type_list.md deleted file mode 100644 index b31ae893..00000000 --- a/docs/modules/type_list.md +++ /dev/null @@ -1,95 +0,0 @@ -# type_list - -List and filter on Linode Instance Types. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: List all of the Linode Instance Types - linode.cloud.type_list: {} -``` - -```yaml -- name: List a Linode Instance Type named Nanode 1GB - linode.cloud.type_list: - filter: - - name: label - values: Nanode 1GB - -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `order` |
`str`
|
Optional
| The order to list Instance Types in. **(Choices: `desc`, `asc`; Default: `asc`)** | -| `order_by` |
`str`
|
Optional
| The attribute to order Instance Types by. | -| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting Instance Types. | -| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | - - - - - -### filters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/linode-types/#types-list__response-samples | -| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | - - - - - - -## Return Values - -- `types` - The returned Instance Types. - - - Sample Response: - ```json - [ - { - "addons": { - "backups": { - "price": { - "hourly": 0.008, - "monthly": 5 - } - } - }, - "class": "standard", - "disk": 81920, - "gpus": 0, - "id": "g6-standard-2", - "label": "Linode 4GB", - "memory": 4096, - "network_out": 1000, - "price": { - "hourly": 0.03, - "monthly": 20 - }, - "successor": null, - "transfer": 4000, - "vcpus": 2 - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-types/#types-list__response-samples) for a list of returned fields - - diff --git a/docs/modules/user.md b/docs/modules/user.md deleted file mode 100644 index 34503aa5..00000000 --- a/docs/modules/user.md +++ /dev/null @@ -1,203 +0,0 @@ -# user - -Manage a Linode User. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a basic user - linode.cloud.user: - username: my-cool-user - email: user@linode.com - restricted: false - state: present -``` - -```yaml -- name: Create a user that can only access Linodes - linode.cloud.user: - username: my-cool-user - email: user@linode.com - grants: - global: - add_linodes: true - resources: - - type: linode - id: 12345 - permissions: read_write - state: present -``` - -```yaml -- name: Delete a user - linode.cloud.user: - username: my-cool-user - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `username` |
`str`
|
**Required**
| The username of this user. | -| `state` |
`str`
|
**Required**
| The state of this user. **(Choices: `present`, `absent`)** | -| `restricted` |
`bool`
|
Optional
| If true, the User must be granted access to perform actions or access entities on this Account. **(Default: `True`; Updatable)** | -| `email` |
`str`
|
Optional
| The email address for the User. Linode sends emails to this address for account management communications. May be used for other communications as configured. | -| [`grants` (sub-options)](#grants) |
`dict`
|
Optional
| Update the grants a User has. **(Updatable)** | - - - - - -### grants - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| [`global` (sub-options)](#global) |
`dict`
|
Optional
| A structure containing the Account-level grants a User has. **(Updatable)** | -| [`resources` (sub-options)](#resources) |
`list`
|
Optional
| A list of resource grants to give to the user. **(Updatable)** | - - - - - -### global - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `account_access` |
|
Optional
| The level of access this User has to Account-level actions, like billing information. A restricted User will never be able to manage users. **(Choices: `read_only`, `read_write`; Updatable)** | -| `add_databases` |
`bool`
|
Optional
| If true, this User may add Managed Databases. **(Default: `False`; Updatable)** | -| `add_domains` |
`bool`
|
Optional
| If true, this User may add Domains. **(Default: `False`; Updatable)** | -| `add_firewalls` |
`bool`
|
Optional
| If true, this User may add firewalls. **(Default: `False`; Updatable)** | -| `add_images` |
`bool`
|
Optional
| If true, this User may add images. **(Default: `False`; Updatable)** | -| `add_linodes` |
`bool`
|
Optional
| If true, this User may add Linodes. **(Default: `False`; Updatable)** | -| `add_longview` |
`bool`
|
Optional
| If true, this User may add LongView. **(Default: `False`; Updatable)** | -| `add_nodebalancers` |
`bool`
|
Optional
| If true, this User may add NodeBalancers. **(Default: `False`; Updatable)** | -| `add_stackscripts` |
`bool`
|
Optional
| If true, this User may add StackScripts. **(Default: `False`; Updatable)** | -| `add_volumes` |
`bool`
|
Optional
| If true, this User may add volumes. **(Default: `False`; Updatable)** | -| `cancel_account` |
`bool`
|
Optional
| If true, this User may add cancel the entire account. **(Default: `False`; Updatable)** | -| `longview_subscription` |
`bool`
|
Optional
| If true, this User may manage the Account’s Longview subscription. **(Default: `False`; Updatable)** | - - - - - -### resources - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `type` |
|
**Required**
| The type of resource to grant access to. **(Choices: `domain`, `image`, `linode`, `longview`, `nodebalancer`, `stackscript`, `volume`; Updatable)** | -| `id` |
`int`
|
**Required**
| The ID of the resource to grant access to. **(Updatable)** | -| `permissions` |
`str`
|
**Required**
| The level of access this User has to this entity. If null, this User has no access. **(Choices: `read_only`, `read_write`; Updatable)** | - - - - - - -## Return Values - -- `user` - The user in JSON serialized form. - - - Sample Response: - ```json - { - "email": "example_user@linode.com", - "restricted": true, - "ssh_keys": [ - "home-pc", - "laptop" - ], - "tfa_enabled": null, - "username": "example_user" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#user-view__response-samples) for a list of returned fields - - -- `grants` - The grants info in JSON serialized form. - - - Sample Response: - ```json - { - "domain": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "global": { - "account_access": "read_only", - "add_databases": true, - "add_domains": true, - "add_firewalls": true, - "add_images": true, - "add_linodes": true, - "add_longview": true, - "add_nodebalancers": true, - "add_stackscripts": true, - "add_volumes": true, - "cancel_account": false, - "longview_subscription": true - }, - "image": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "linode": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "longview": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "nodebalancer": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "stackscript": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "volume": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ] - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#users-grants-view__response-samples) for a list of returned fields - - diff --git a/docs/modules/user_info.md b/docs/modules/user_info.md deleted file mode 100644 index b51a0fa7..00000000 --- a/docs/modules/user_info.md +++ /dev/null @@ -1,130 +0,0 @@ -# user_info - -Get info about a Linode User. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about a user - linode.cloud.user_info: - username: my-cool-user -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `username` |
`str`
|
**Required**
| The username of the user. | - - - - - - -## Return Values - -- `user` - The user info in JSON serialized form. - - - Sample Response: - ```json - { - "email": "example_user@linode.com", - "restricted": true, - "ssh_keys": [ - "home-pc", - "laptop" - ], - "tfa_enabled": null, - "username": "example_user" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#user-view) for a list of returned fields - - -- `grants` - The grants info in JSON serialized form. - - - Sample Response: - ```json - { - "domain": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "global": { - "account_access": "read_only", - "add_databases": true, - "add_domains": true, - "add_firewalls": true, - "add_images": true, - "add_linodes": true, - "add_longview": true, - "add_nodebalancers": true, - "add_stackscripts": true, - "add_volumes": true, - "cancel_account": false, - "longview_subscription": true - }, - "image": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "linode": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "longview": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "nodebalancer": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "stackscript": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ], - "volume": [ - { - "id": 123, - "label": "example-entity", - "permissions": "read_only" - } - ] - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#users-grants-view__response-samples) for a list of returned fields - - diff --git a/docs/modules/vlan_info.md b/docs/modules/vlan_info.md deleted file mode 100644 index 99da7804..00000000 --- a/docs/modules/vlan_info.md +++ /dev/null @@ -1,56 +0,0 @@ -# vlan_info - -Get info about a Linode VLAN. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Get info about a VLAN by label - linode.cloud.vlan_info: - label: example-vlan -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `label` |
`str`
|
**Required**
| The VLAN’s label. | - - - - - - -## Return Values - -- `vlan` - The VLAN in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2020-01-01T00:01:01", - "label": "vlan-example", - "linodes": [ - 111, - 222 - ], - "region": "ap-west" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#vlans-list__response-samples) for a list of returned fields - - diff --git a/docs/modules/vlan_list.md b/docs/modules/vlan_list.md deleted file mode 100644 index 0a43cd97..00000000 --- a/docs/modules/vlan_list.md +++ /dev/null @@ -1,80 +0,0 @@ -# vlan_list - -List and filter on Linode VLANs. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: List all of the VLANs for the current Linode Account - linode.cloud.vlan_list: {} -``` - -```yaml -- name: List all VLANs in the us-southeast region - linode.cloud.vlan_list: - filter: - - name: region - values: us-southeast - -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `order` |
`str`
|
Optional
| The order to list VLANs in. **(Choices: `desc`, `asc`; Default: `asc`)** | -| `order_by` |
`str`
|
Optional
| The attribute to order VLANs by. | -| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting VLANs. | -| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | - - - - - -### filters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/networking/#vlans-list__response-samples | -| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | - - - - - - -## Return Values - -- `vlans` - The returned VLANs. - - - Sample Response: - ```json - [ - { - "created": "2020-01-01T00:01:01", - "label": "vlan-example", - "linodes": [ - 111, - 222 - ], - "region": "ap-west" - } - ] - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#vlans-list__response-samples) for a list of returned fields - - diff --git a/docs/modules/volume.md b/docs/modules/volume.md deleted file mode 100644 index 718ebee9..00000000 --- a/docs/modules/volume.md +++ /dev/null @@ -1,107 +0,0 @@ -# volume - -Manage a Linode Volume. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- name: Create a volume attached to an instance - linode.cloud.volume: - label: example-volume - region: us-east - size: 30 - linode_id: 12345 - state: present -``` - -```yaml -- name: Create an unattached volume - linode.cloud.volume: - label: example-volume - region: us-east - size: 30 - state: present -``` - -```yaml -- name: Resize a volume - linode.cloud.volume: - label: example-volume - size: 50 - state: present -``` - -```yaml -- name: Detach a volume - linode.cloud.volume: - label: example-volume - attached: false - state: present -``` - -```yaml -- name: Delete a volume - linode.cloud.volume: - label: example-volume - state: absent -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | -| `label` |
`str`
|
Optional
| The Volume’s label, which is also used in the filesystem_path of the resulting volume. | -| `config_id` |
`int`
|
Optional
| When creating a Volume attached to a Linode, the ID of the Linode Config to include the new Volume in. | -| `linode_id` |
`int`
|
Optional
| The Linode this volume should be attached to upon creation. If not given, the volume will be created without an attachment. **(Updatable)** | -| `region` |
`str`
|
Optional
| The location to deploy the volume in. See U(https://api.linode.com/v4/regions) | -| `size` |
`int`
|
Optional
| The size of this volume, in GB. Be aware that volumes may only be resized up after creation. **(Updatable)** | -| `attached` |
`bool`
|
Optional
| If true, the volume will be attached to a Linode. Otherwise, the volume will be detached. **(Default: `True`; Updatable)** | -| `wait_timeout` |
`int`
|
Optional
| The amount of time, in seconds, to wait for a volume to have the active status. **(Default: `240`)** | - - - - - - -## Return Values - -- `volume` - The volume in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "filesystem_path": "/dev/disk/by-id/scsi-0Linode_Volume_my-volume", - "hardware_type": "nvme", - "id": 12345, - "label": "my-volume", - "linode_id": 12346, - "linode_label": "linode123", - "region": "us-east", - "size": 30, - "status": "active", - "tags": [ - "example tag", - "another example" - ], - "updated": "2018-01-01T00:01:01" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/volumes/#volume-view__responses) for a list of returned fields - - diff --git a/docs/modules/volume_info.md b/docs/modules/volume_info.md deleted file mode 100644 index 8c7e52d5..00000000 --- a/docs/modules/volume_info.md +++ /dev/null @@ -1,69 +0,0 @@ -# volume_info - -Get info about a Linode Volume. - - -- [Examples](#examples) -- [Parameters](#parameters) -- [Return Values](#return-values) - -## Examples - -```yaml -- 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 -``` - - - - - - - - - - -## Parameters - -| Field | Type | Required | Description | -|-----------|------|----------|------------------------------------------------------------------------------| -| `id` |
`int`
|
Optional
| The ID of the Volume. Optional if `label` is defined. | -| `label` |
`str`
|
Optional
| The label of the Volume. Optional if `id` is defined. | - - - - - - -## Return Values - -- `volume` - The volume in JSON serialized form. - - - Sample Response: - ```json - { - "created": "2018-01-01T00:01:01", - "filesystem_path": "/dev/disk/by-id/scsi-0Linode_Volume_my-volume", - "hardware_type": "nvme", - "id": 12345, - "label": "my-volume", - "linode_id": 12346, - "linode_label": "linode123", - "region": "us-east", - "size": 30, - "status": "active", - "tags": [ - "example tag", - "another example" - ], - "updated": "2018-01-01T00:01:01" - } - ``` - - See the [Linode API response documentation](https://www.linode.com/docs/api/volumes/#volume-view__responses) for a list of returned fields - - diff --git a/plugins/modules/account_info.py b/plugins/modules/account_info.py index 7a3e06df..69d00225 100644 --- a/plugins/modules/account_info.py +++ b/plugins/modules/account_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Any, Optional +from ansible_specdoc.objects import SpecDocMeta, SpecReturnValue, FieldType, SpecField from linode_api4 import Volume from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -19,23 +20,23 @@ spec = dict( # Disable the default values - label=dict(type='str', required=False, doc_hide=True), - state=dict(type='str', required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode Account.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - account=dict( + account=SpecReturnValue( description='The account info in JSON serialized form.', docs_url='https://www.linode.com/docs/api/account/#account-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_account_samples ) ) @@ -51,7 +52,7 @@ def __init__(self) -> None: account=None, ) - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec super().__init__(module_arg_spec=self.module_arg_spec, required_one_of=self.required_one_of) diff --git a/requirements-dev.txt b/requirements-dev.txt index e42ae2bd..c69e80cf 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -3,6 +3,6 @@ botocore==1.20.23 pylint==2.15.5 ansible-doc-extractor==0.1.8 mypy==0.991 -ansible-specdoc==0.0.10 +ansible-specdoc==0.0.11 ansible==7.1.0 Jinja2==3.0.1 \ No newline at end of file From 4100fcf2d7c5f51b4519c43af9b432cc43d796b9 Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 11:58:20 -0500 Subject: [PATCH 02/13] SDF --- docs/modules/account_info.md | 76 ++++++++ docs/modules/api_request.md | 86 +++++++++ docs/modules/database_list.md | 108 +++++++++++ docs/modules/database_mysql.md | 172 +++++++++++++++++ docs/modules/database_mysql_info.md | 124 +++++++++++++ docs/modules/database_postgresql.md | 175 ++++++++++++++++++ .../module_utils/linode_database_shared.py | 32 ++-- plugins/modules/api_request.py | 41 ++-- plugins/modules/database_list.py | 62 ++++--- plugins/modules/database_mysql.py | 111 +++++------ plugins/modules/database_mysql_info.py | 29 +-- plugins/modules/database_postgresql.py | 115 ++++++------ plugins/modules/database_postgresql_info.py | 27 +-- plugins/modules/domain.py | 93 +++++----- 14 files changed, 1001 insertions(+), 250 deletions(-) create mode 100644 docs/modules/account_info.md create mode 100644 docs/modules/api_request.md create mode 100644 docs/modules/database_list.md create mode 100644 docs/modules/database_mysql.md create mode 100644 docs/modules/database_mysql_info.md create mode 100644 docs/modules/database_postgresql.md diff --git a/docs/modules/account_info.md b/docs/modules/account_info.md new file mode 100644 index 00000000..5ddf403c --- /dev/null +++ b/docs/modules/account_info.md @@ -0,0 +1,76 @@ +# account_info + +Get info about a Linode Account. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about the current Linode account + linode.cloud.account_info: {} +``` + + + + + + + + + + +## Return Values + +- `account` - The account info in JSON serialized form. + + - Sample Response: + ```json + { + "active_promotions": [ + { + "credit_monthly_cap": "10.00", + "credit_remaining": "50.00", + "description": "Receive up to $10 off your services every month for 6 months! Unused credits will expire once this promotion period ends.", + "expire_dt": "2018-01-31T23:59:59", + "image_url": "https://linode.com/10_a_month_promotion.svg", + "service_type": "all", + "summary": "$10 off your Linode a month!", + "this_month_credit_remaining": "10.00" + } + ], + "active_since": "2018-01-01T00:01:01", + "address_1": "123 Main Street", + "address_2": "Suite A", + "balance": 200, + "balance_uninvoiced": 145, + "billing_source": "akamai", + "capabilities": [ + "Linodes", + "NodeBalancers", + "Block Storage", + "Object Storage" + ], + "city": "Philadelphia", + "company": "Linode LLC", + "country": "US", + "credit_card": { + "expiry": "11/2022", + "last_four": 1111 + }, + "email": "john.smith@linode.com", + "euuid": "E1AF5EEC-526F-487D-B317EBEB34C87D71", + "first_name": "John", + "last_name": "Smith", + "phone": "215-555-1212", + "state": "PA", + "tax_id": "ATU99999999", + "zip": "19102-1234" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#account-view__response-samples) for a list of returned fields + + diff --git a/docs/modules/api_request.md b/docs/modules/api_request.md new file mode 100644 index 00000000..dcb17835 --- /dev/null +++ b/docs/modules/api_request.md @@ -0,0 +1,86 @@ +# api_request + +Make an arbitrary Linode API request. + +The Linode API documentation can be found here: https://www.linode.com/docs/api + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get all available LKE versions + linode.cloud.api_request: + path: lke/versions + method: GET +``` + +```yaml +- name: Manually create a domain + linode.cloud.api_request: + path: domains + method: POST + body: + domain: my-domain.com + type: master + soa_email: myemail@example.com +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `path` |
`str`
|
**Required**
| The relative path to the endpoint to make a request to. e.g. "linode/instances" | +| `method` |
`str`
|
**Required**
| The HTTP method of the request or response. **(Choices: `POST`, `PUT`, `GET`, `DELETE`)** | +| `body` |
`dict`
|
Optional
| The body of the request. This is a YAML structure that will be marshalled to JSON. | +| `body_json` |
`str`
|
Optional
| The body of the request in JSON format. | +| `filters` |
`dict`
|
Optional
| A YAML structure corresponding to the X-Filter request header. See: https://www.linode.com/docs/api/#filtering-and-sorting | + + + + + + +## Return Values + +- `body` - The deserialized response body. + + - Sample Response: + ```json + { + "axfr_ips": [], + "description": null, + "domain": "example.org", + "expire_sec": 300, + "group": null, + "id": 1234, + "master_ips": [], + "refresh_sec": 300, + "retry_sec": 300, + "soa_email": "admin@example.org", + "status": "active", + "tags": [ + "example tag", + "another example" + ], + "ttl_sec": 300, + "type": "master" + } + ``` + + +- `status` - The response status code. + + diff --git a/docs/modules/database_list.md b/docs/modules/database_list.md new file mode 100644 index 00000000..946aea67 --- /dev/null +++ b/docs/modules/database_list.md @@ -0,0 +1,108 @@ +# database_list + +List and filter on Linode Managed Databases. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: List all of the databases for the current Linode Account + linode.cloud.database_list: {} +``` + +```yaml +- name: Resolve all MySQL databases for the current Linode Account + linode.cloud.database_list: + filter: + - name: engine + values: mysql +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `order` |
`str`
|
Optional
| The order to list databases in. **(Choices: `desc`, `asc`; Default: `asc`)** | +| `order_by` |
`str`
|
Optional
| The attribute to order databases by. | +| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting databases. | +| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | + + + + + +### filters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/databases/#managed-mongodb-databases-list__responses | +| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | + + + + + + +## Return Values + +- `databases` - The returned database. + + - Sample Response: + ```json + [ + { + "allow_list":[ + "203.0.113.1/32", + "192.0.1.0/24" + ], + "cluster_size":3, + "compression_type":"none", + "created":"2022-01-01T00:01:01", + "encrypted":false, + "engine":"mongodb", + "hosts":{ + "primary":"lin-0000-0000.servers.linodedb.net", + "secondary":null + }, + "id":123, + "label":"example-db", + "peers":[ + "lin-0000-0000.servers.linodedb.net", + "lin-0000-0001.servers.linodedb.net", + "lin-0000-0002.servers.linodedb.net" + ], + "port":27017, + "region":"us-east", + "replica_set":null, + "ssl_connection":true, + "status":"active", + "storage_engine":"wiredtiger", + "type":"g6-dedicated-2", + "updated":"2022-01-01T00:01:01", + "updates":{ + "day_of_week":1, + "duration":3, + "frequency":"weekly", + "hour_of_day":0, + "week_of_month":null + }, + "version":"4.4.10" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-databases-list-all__response-samples) for a list of returned fields + + diff --git a/docs/modules/database_mysql.md b/docs/modules/database_mysql.md new file mode 100644 index 00000000..b34101d4 --- /dev/null +++ b/docs/modules/database_mysql.md @@ -0,0 +1,172 @@ +# database_mysql + +Manage a Linode MySQL database. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a basic MySQL database + linode.cloud.database_mysql: + label: my-db + region: us-east + engine: mysql/8.0.26 + type: g6-standard-1 + allow_list: + - 0.0.0.0/0 + state: present +``` + +```yaml +- name: Create a complex 3 node MySQL database + linode.cloud.database_mysql: + label: my-db + region: us-east + engine: mysql/8.0.26 + type: g6-standard-1 + allow_list: + - 0.0.0.0/0 + encrypted: true + cluster_size: 3 + replication_type: semi_synch + ssl_connection: true + state: present +``` + +```yaml +- name: Delete a MySQL database + linode.cloud.database_mysql: + label: my-db + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| This database's unique label. | +| `state` |
`str`
|
**Required**
| The state of this database. **(Choices: `present`, `absent`)** | +| `allow_list` |
`list`
|
Optional
| A list of IP addresses that can access the Managed Database. Each item must be a range in CIDR format. **(Updatable)** | +| `cluster_size` |
`int`
|
Optional
| The number of Linode Instance nodes deployed to the Managed Database. **(Choices: `1`, `3`; Default: `1`)** | +| `encrypted` |
`bool`
|
Optional
| Whether the Managed Databases is encrypted. | +| `engine` |
`str`
|
Optional
| The Managed Database engine in engine/version format. | +| `region` |
`str`
|
Optional
| The Region ID for the Managed Database. | +| `replication_type` |
`str`
|
Optional
| The replication method used for the Managed Database. Defaults to none for a single cluster and semi_synch for a high availability cluster. Must be none for a single node cluster. Must be asynch or semi_synch for a high availability cluster. **(Choices: `none`, `asynch`, `semi_synch`; Default: `none`)** | +| `ssl_connection` |
`bool`
|
Optional
| Whether to require SSL credentials to establish a connection to the Managed Database. **(Default: `True`)** | +| `type` |
`str`
|
Optional
| The Linode Instance type used by the Managed Database for its nodes. | +| [`updates` (sub-options)](#updates) |
`dict`
|
Optional
| Configuration settings for automated patch update maintenance for the Managed Database. **(Updatable)** | +| `wait` |
`bool`
|
Optional
| Wait for the database to have status `available` before returning. **(Default: `True`)** | +| `wait_timeout` |
`int`
|
Optional
| The amount of time, in seconds, to wait for an image to have status `available`. **(Default: `3600`)** | + + + + + +### updates + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `day_of_week` |
`int`
|
**Required**
| The day to perform maintenance. 1=Monday, 2=Tuesday, etc. **(Choices: `1`, `2`, `3`, `4`, `5`, `6`, `7`)** | +| `duration` |
`int`
|
**Required**
| The maximum maintenance window time in hours. **(Choices: `1`, `3`)** | +| `hour_of_day` |
`int`
|
**Required**
| The hour to begin maintenance based in UTC time. | +| `frequency` |
`str`
|
Optional
| Whether maintenance occurs on a weekly or monthly basis. **(Choices: `weekly`, `monthly`; Default: `weekly`)** | +| `week_of_month` |
`int`
|
Optional
| The week of the month to perform monthly frequency updates. Defaults to None. Required for monthly frequency updates. Must be null for weekly frequency updates. | + + + + + + +## Return Values + +- `database` - The database in JSON serialized form. + + - Sample Response: + ```json + { + "allow_list": [ + "203.0.113.1/32", + "192.0.1.0/24" + ], + "cluster_size": 3, + "created": "2022-01-01T00:01:01", + "encrypted": false, + "engine": "mysql", + "hosts": { + "primary": "lin-123-456-mysql-mysql-primary.servers.linodedb.net", + "secondary": "lin-123-456-mysql-primary-private.servers.linodedb.net" + }, + "id": 123, + "label": "example-db", + "port": 3306, + "region": "us-east", + "replication_type": "semi_synch", + "ssl_connection": true, + "status": "active", + "type": "g6-dedicated-2", + "updated": "2022-01-01T00:01:01", + "updates": { + "day_of_week": 1, + "duration": 3, + "frequency": "weekly", + "hour_of_day": 0, + "week_of_month": null + }, + "version": "8.0.26" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-view__response-samples) for a list of returned fields + + +- `backups` - The database backups in JSON serialized form. + + - Sample Response: + ```json + [ + { + "created":"2022-01-01T00:01:01", + "id":123, + "label":"Scheduled - 02/04/22 11:11 UTC-XcCRmI", + "type":"auto" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-backup-view__responses) for a list of returned fields + + +- `ssl_cert` - The SSL CA certificate for an accessible Managed MySQL Database. + + - Sample Response: + ```json + { + "ca_certificate": "LS0tLS1CRUdJ...==" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-ssl-certificate-view__responses) for a list of returned fields + + +- `credentials` - The root username and password for an accessible Managed MySQL Database. + + - Sample Response: + ```json + { + "password": "s3cur3P@ssw0rd", + "username": "linroot" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-credentials-view__responses) for a list of returned fields + + diff --git a/docs/modules/database_mysql_info.md b/docs/modules/database_mysql_info.md new file mode 100644 index 00000000..af4dc4d1 --- /dev/null +++ b/docs/modules/database_mysql_info.md @@ -0,0 +1,124 @@ +# database_mysql_info + +Get info about a Linode MySQL Managed Database. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about a Managed MySQL Database by label + linode.cloud.database_mysql_info: + label: my-db +``` + +```yaml +- name: Get info about a Managed MySQL Database by ID + linode.cloud.database_mysql_info: + id: 12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`str`
|
Optional
| The ID of the MySQL Database. | +| `label` |
`str`
|
Optional
| The label of the MySQL Database. | + + + + + + +## Return Values + +- `database` - The database in JSON serialized form. + + - Sample Response: + ```json + { + "allow_list": [ + "203.0.113.1/32", + "192.0.1.0/24" + ], + "cluster_size": 3, + "created": "2022-01-01T00:01:01", + "encrypted": false, + "engine": "mysql", + "hosts": { + "primary": "lin-123-456-mysql-mysql-primary.servers.linodedb.net", + "secondary": "lin-123-456-mysql-primary-private.servers.linodedb.net" + }, + "id": 123, + "label": "example-db", + "port": 3306, + "region": "us-east", + "replication_type": "semi_synch", + "ssl_connection": true, + "status": "active", + "type": "g6-dedicated-2", + "updated": "2022-01-01T00:01:01", + "updates": { + "day_of_week": 1, + "duration": 3, + "frequency": "weekly", + "hour_of_day": 0, + "week_of_month": null + }, + "version": "8.0.26" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-view__response-samples) for a list of returned fields + + +- `backups` - The database backups in JSON serialized form. + + - Sample Response: + ```json + [ + { + "created":"2022-01-01T00:01:01", + "id":123, + "label":"Scheduled - 02/04/22 11:11 UTC-XcCRmI", + "type":"auto" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-backup-view__responses) for a list of returned fields + + +- `ssl_cert` - The SSL CA certificate for an accessible Managed MySQL Database. + + - Sample Response: + ```json + { + "ca_certificate": "LS0tLS1CRUdJ...==" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-ssl-certificate-view__responses) for a list of returned fields + + +- `credentials` - The root username and password for an accessible Managed MySQL Database. + + - Sample Response: + ```json + { + "password": "s3cur3P@ssw0rd", + "username": "linroot" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-mysql-database-credentials-view__responses) for a list of returned fields + + diff --git a/docs/modules/database_postgresql.md b/docs/modules/database_postgresql.md new file mode 100644 index 00000000..32da9f8a --- /dev/null +++ b/docs/modules/database_postgresql.md @@ -0,0 +1,175 @@ +# database_postgresql + +Manage a Linode PostgreSQL database. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a basic PostgreSQL database + linode.cloud.database_postgresql: + label: my-db + region: us-east + engine: postgresql/13.2 + type: g6-standard-1 + allow_list: + - 0.0.0.0/0 + state: present +``` + +```yaml +- name: Create a complex 3 node PostgreSQL database + linode.cloud.database_postgresql: + label: my-db + region: us-east + engine: postgresql/13.2 + type: g6-standard-1 + allow_list: + - 0.0.0.0/0 + encrypted: true + cluster_size: 3 + replication_type: semi_synch + replication_commit_type: remote_apply + ssl_connection: true + state: present +``` + +```yaml +- name: Delete a PostgreSQL database + linode.cloud.database_postgresql: + label: my-db + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| This database's unique label. | +| `state` |
`str`
|
**Required**
| The state of this database. **(Choices: `present`, `absent`)** | +| `allow_list` |
`list`
|
Optional
| A list of IP addresses that can access the Managed Database. Each item must be a range in CIDR format. **(Updatable)** | +| `cluster_size` |
`str`
|
Optional
| The number of Linode Instance nodes deployed to the Managed Database. **(Choices: `1`, `3`; Default: `1`)** | +| `encrypted` |
`str`
|
Optional
| Whether the Managed Databases is encrypted. | +| `engine` |
`str`
|
Optional
| The Managed Database engine in engine/version format. | +| `region` |
`str`
|
Optional
| The Region ID for the Managed Database. | +| `replication_type` |
`str`
|
Optional
| The replication method used for the Managed Database. Defaults to none for a single cluster and semi_synch for a high availability cluster. Must be none for a single node cluster. Must be asynch or semi_synch for a high availability cluster. **(Choices: `none`, `asynch`, `semi_synch`; Default: `none`)** | +| `replication_commit_type` |
`str`
|
Optional
| The synchronization level of the replicating server. Must be local or off for the asynch replication type. Must be on, remote_write, or remote_apply for the semi_synch replication type. **(Choices: `off`, `on`, `local`, `remote_write`, `remote_apply`; Default: `local`)** | +| `ssl_connection` |
`bool`
|
Optional
| Whether to require SSL credentials to establish a connection to the Managed Database. **(Default: `True`)** | +| `type` |
`str`
|
Optional
| The Linode Instance type used by the Managed Database for its nodes. | +| [`updates` (sub-options)](#updates) |
`dict`
|
Optional
| Configuration settings for automated patch update maintenance for the Managed Database. **(Updatable)** | +| `wait` |
`bool`
|
Optional
| Wait for the database to have status `available` before returning. **(Default: `True`)** | +| `wait_timeout` |
`int`
|
Optional
| The amount of time, in seconds, to wait for an image to have status `available`. **(Default: `3600`)** | + + + + + +### updates + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `day_of_week` |
`int`
|
**Required**
| The day to perform maintenance. 1=Monday, 2=Tuesday, etc. **(Choices: `1`, `2`, `3`, `4`, `5`, `6`, `7`)** | +| `duration` |
`int`
|
**Required**
| The maximum maintenance window time in hours. **(Choices: `1`, `3`)** | +| `hour_of_day` |
`int`
|
**Required**
| The hour to begin maintenance based in UTC time. | +| `frequency` |
`str`
|
Optional
| Whether maintenance occurs on a weekly or monthly basis. **(Choices: `weekly`, `monthly`; Default: `weekly`)** | +| `week_of_month` |
`int`
|
Optional
| The week of the month to perform monthly frequency updates. Defaults to None. Required for monthly frequency updates. Must be null for weekly frequency updates. | + + + + + + +## Return Values + +- `database` - The database in JSON serialized form. + + - Sample Response: + ```json + { + "allow_list": [ + "203.0.113.1/32", + "192.0.1.0/24" + ], + "cluster_size": 3, + "created": "2022-01-01T00:01:01", + "encrypted": false, + "engine": "postgresql", + "hosts": { + "primary": "lin-0000-000-pgsql-primary.servers.linodedb.net", + "secondary": "lin-0000-000-pgsql-primary-private.servers.linodedb.net" + }, + "id": 123, + "label": "example-db", + "port": 3306, + "region": "us-east", + "replication_commit_type": "local", + "replication_type": "semi_synch", + "ssl_connection": true, + "status": "active", + "type": "g6-dedicated-2", + "updated": "2022-01-01T00:01:01", + "updates": { + "day_of_week": 1, + "duration": 3, + "frequency": "weekly", + "hour_of_day": 0, + "week_of_month": null + }, + "version": "13.2" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-view__response-samples) for a list of returned fields + + +- `backups` - The database backups in JSON serialized form. + + - Sample Response: + ```json + [ + { + "created":"2022-01-01T00:01:01", + "id":123, + "label":"Scheduled - 02/04/22 11:11 UTC-XcCRmI", + "type":"auto" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-backups-list) for a list of returned fields + + +- `ssl_cert` - The SSL CA certificate for an accessible Managed PostgreSQL Database. + + - Sample Response: + ```json + { + "ca_certificate": "LS0tLS1CRUdJ...==" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-ssl-certificate-view__responses) for a list of returned fields + + +- `credentials` - The root username and password for an accessible Managed PostgreSQL Database. + + - Sample Response: + ```json + { + "password": "s3cur3P@ssw0rd", + "username": "linroot" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-credentials-view__responses) for a list of returned fields + + diff --git a/plugins/module_utils/linode_database_shared.py b/plugins/module_utils/linode_database_shared.py index 48b7dc4a..99e916ac 100644 --- a/plugins/module_utils/linode_database_shared.py +++ b/plugins/module_utils/linode_database_shared.py @@ -4,34 +4,35 @@ from typing import Set, Dict, Any, Callable, Optional +from ansible_specdoc.objects import SpecField, FieldType from linode_api4 import ApiError SPEC_UPDATE_WINDOW = dict( - day_of_week=dict( - type='int', + day_of_week=SpecField( + type=FieldType.integer, required=True, - choices=range(1, 8), - description='The day to perform maintenance. 1=Monday, 2=Tuesday, etc.' + choices=list(range(1, 8)), + description=['The day to perform maintenance. 1=Monday, 2=Tuesday, etc.'] ), - duration=dict( - type='int', + duration=SpecField( + type=FieldType.integer, required=True, choices=[1, 3], - description='The maximum maintenance window time in hours.' + description=['The maximum maintenance window time in hours.'] ), - frequency=dict( - type='str', + frequency=SpecField( + type=FieldType.string, choices=['weekly', 'monthly'], default='weekly', - description='Whether maintenance occurs on a weekly or monthly basis.' + description=['Whether maintenance occurs on a weekly or monthly basis.'] ), - hour_of_day=dict( - type='int', + hour_of_day=SpecField( + type=FieldType.integer, required=True, - description='The hour to begin maintenance based in UTC time.', + description=['The hour to begin maintenance based in UTC time.'], ), - week_of_month=dict( - type='int', + week_of_month=SpecField( + type=FieldType.integer, description=[ 'The week of the month to perform monthly frequency updates.', 'Defaults to None.', @@ -41,6 +42,7 @@ ) ) + def validate_allow_list(allow_list: Set[str]) -> None: """Validates the allow_list field params.""" diff --git a/plugins/modules/api_request.py b/plugins/modules/api_request.py index 07581766..a9d1fe82 100644 --- a/plugins/modules/api_request.py +++ b/plugins/modules/api_request.py @@ -11,6 +11,7 @@ from typing import Optional, cast, Any, Set, Tuple import polling +from ansible_specdoc.objects import SpecDocMeta, SpecReturnValue, FieldType, SpecField from linode_api4 import StackScript, ApiError from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -21,38 +22,38 @@ import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.api_request as docs SPEC = dict( - label=dict(type='str', doc_hide=True), - state=dict(type='str', doc_hide=True), + label=SpecField(type=FieldType.string, doc_hide=True), + state=SpecField(type=FieldType.string, doc_hide=True), - path=dict( - type='str', + path=SpecField( + type=FieldType.string, required=True, description=[ 'The relative path to the endpoint to make a request to.', 'e.g. "linode/instances"' ] ), - method=dict( - type='str', + method=SpecField( + type=FieldType.string, required=True, - description='The HTTP method of the request or response.', + description=['The HTTP method of the request or response.'], choices=['POST', 'PUT', 'GET', 'DELETE'] ), - body=dict( - type='dict', + body=SpecField( + type=FieldType.dict, description=[ 'The body of the request.', 'This is a YAML structure that will be marshalled to JSON.' ] ), - body_json=dict( - type='str', + body_json=SpecField( + type=FieldType.string, description=[ 'The body of the request in JSON format.' ] ), - filters=dict( - type='dict', + filters=SpecField( + type=FieldType.dict, description=[ 'A YAML structure corresponding to the X-Filter request header.', 'See: https://www.linode.com/docs/api/#filtering-and-sorting' @@ -60,7 +61,7 @@ ) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Make an arbitrary Linode API request.', 'The Linode API documentation can be found here: ' @@ -68,17 +69,17 @@ ], requirements=global_requirements, author=global_authors, - spec=SPEC, + options=SPEC, examples=docs.specdoc_examples, return_values=dict( - body=dict( + body=SpecReturnValue( description='The deserialized response body.', - type='dict', + type=FieldType.dict, sample=docs.result_body_samples ), - status=dict( + status=SpecReturnValue( description='The response status code.', - type='int' + type=FieldType.integer ) ) ) @@ -88,7 +89,7 @@ class Module(LinodeModuleBase): """Module for running arbitrary Linode API requests""" def __init__(self) -> None: - self.module_arg_spec = SPEC + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = dict( body={}, status=0, diff --git a/plugins/modules/database_list.py b/plugins/modules/database_list.py index 1d49b808..425ab6f4 100644 --- a/plugins/modules/database_list.py +++ b/plugins/modules/database_list.py @@ -8,6 +8,8 @@ # pylint: disable=unused-import from typing import Any, Optional, Dict +from ansible_specdoc.objects import SpecDocMeta, SpecReturnValue, FieldType, SpecField + from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ filter_null_values, construct_api_filter, get_all_paginated @@ -17,51 +19,51 @@ import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_list as docs spec_filter = dict( - name=dict(type='str', required=True, - description=[ - 'The name of the field to filter on.', - 'Valid filterable attributes can be found here: ' - 'https://www.linode.com/docs/api/databases/' - '#managed-mongodb-databases-list__responses', - ]), - values=dict(type='list', elements='str', required=True, - description=[ - 'A list of values to allow for this field.', - 'Fields will pass this filter if at least one of these values matches.' - ]) + name=SpecField(type=FieldType.string, required=True, + description=[ + 'The name of the field to filter on.', + 'Valid filterable attributes can be found here: ' + 'https://www.linode.com/docs/api/databases/' + '#managed-mongodb-databases-list__responses', + ]), + values=SpecField(type=FieldType.list, element_type=FieldType.string, required=True, + description=[ + 'A list of values to allow for this field.', + 'Fields will pass this filter if at least one of these values matches.' + ]) ) spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), - - order=dict(type='str', description='The order to list databases in.', - default='asc', choices=['desc', 'asc']), - order_by=dict(type='str', description='The attribute to order databases by.'), - filters=dict(type='list', elements='dict', options=spec_filter, - description='A list of filters to apply to the resulting databases.'), - count=dict(type='int', - description=[ - 'The number of results to return.', - 'If undefined, all results will be returned.']) + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + + order=SpecField(type=FieldType.string, description=['The order to list databases in.'], + default='asc', choices=['desc', 'asc']), + order_by=SpecField(type=FieldType.string, description=['The attribute to order databases by.']), + filters=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=spec_filter, + description=['A list of filters to apply to the resulting databases.']), + count=SpecField(type=FieldType.integer, + description=[ + 'The number of results to return.', + 'If undefined, all results will be returned.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'List and filter on Linode Managed Databases.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - databases=dict( + databases=SpecReturnValue( description='The returned database.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-databases-list-all__response-samples', - type='list', - elements='dict', + type=FieldType.list, + elements=FieldType.dict, sample=docs.result_images_samples ) ) @@ -72,7 +74,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode databases""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results: Dict[str, Any] = { 'databases': [] } diff --git a/plugins/modules/database_mysql.py b/plugins/modules/database_mysql.py index 009e471c..a068e105 100644 --- a/plugins/modules/database_mysql.py +++ b/plugins/modules/database_mysql.py @@ -12,6 +12,7 @@ import polling import requests +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import LinodeClient, ApiError from linode_api4.objects import MySQLDatabase @@ -28,20 +29,20 @@ import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_mysql as docs SPEC = dict( - label=dict( - type='str', + label=SpecField( + type=FieldType.string, required=True, - description='This database\'s unique label.'), - state=dict( - type='str', + description=['This database\'s unique label.']), + state=SpecField( + type=FieldType.string, choices=['present', 'absent'], required=True, - description='The state of this database.', + description=['The state of this database.'], ), - allow_list=dict( - type='list', - elements='str', + allow_list=SpecField( + type=FieldType.list, + element_type=FieldType.string, description=[ 'A list of IP addresses that can access the Managed Database.', 'Each item must be a range in CIDR format.' @@ -49,26 +50,26 @@ default=[], editable=True, ), - cluster_size=dict( - type='int', - description='The number of Linode Instance nodes deployed to the Managed Database.', + cluster_size=SpecField( + type=FieldType.integer, + description=['The number of Linode Instance nodes deployed to the Managed Database.'], choices=[1, 3], default=1 ), - encrypted=dict( - type='bool', - description='Whether the Managed Databases is encrypted.', + encrypted=SpecField( + type=FieldType.bool, + description=['Whether the Managed Databases is encrypted.'], ), - engine=dict( - type='str', - description='The Managed Database engine in engine/version format.', + engine=SpecField( + type=FieldType.string, + description=['The Managed Database engine in engine/version format.'], ), - region=dict( - type='str', - description='The Region ID for the Managed Database.' + region=SpecField( + type=FieldType.string, + description=['The Region ID for the Managed Database.'] ), - replication_type=dict( - type='str', + replication_type=SpecField( + type=FieldType.string, description=[ 'The replication method used for the Managed Database.', 'Defaults to none for a single cluster and ' @@ -79,70 +80,70 @@ choices=['none', 'asynch', 'semi_synch'], default='none' ), - ssl_connection=dict( - type='bool', - description='Whether to require SSL credentials to ' - 'establish a connection to the Managed Database.', + ssl_connection=SpecField( + type=FieldType.bool, + description=['Whether to require SSL credentials to ' + 'establish a connection to the Managed Database.'], default=True, ), - type=dict( - type='str', - description='The Linode Instance type used by the ' - 'Managed Database for its nodes.', + type=SpecField( + type=FieldType.string, + description=['The Linode Instance type used by the ' + 'Managed Database for its nodes.'], ), - updates=dict( - type='dict', - options=SPEC_UPDATE_WINDOW, - description='Configuration settings for automated patch ' - 'update maintenance for the Managed Database.', + updates=SpecField( + type=FieldType.dict, + suboptions=SPEC_UPDATE_WINDOW, + description=['Configuration settings for automated patch ' + 'update maintenance for the Managed Database.'], editable=True ), - wait=dict( - type='bool', default=True, - description='Wait for the database to have status `available` before returning.'), - - wait_timeout=dict( - type='int', default=3600, - description='The amount of time, in seconds, to wait for an image to ' - 'have status `available`.' + wait=SpecField( + type=FieldType.bool, default=True, + description=['Wait for the database to have status `available` before returning.']), + + wait_timeout=SpecField( + type=FieldType.integer, default=3600, + description=['The amount of time, in seconds, to wait for an image to ' + 'have status `available`.'] ), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage a Linode MySQL database.' ], requirements=global_requirements, author=global_authors, - spec=SPEC, + options=SPEC, examples=docs.specdoc_examples, return_values=dict( - database=dict( + database=SpecReturnValue( description='The database in JSON serialized form.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-mysql-database-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_database_samples ), - backups=dict( + backups=SpecReturnValue( description='The database backups in JSON serialized form.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-mysql-database-backup-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_backups_samples ), - ssl_cert=dict( + ssl_cert=SpecReturnValue( description='The SSL CA certificate for an accessible Managed MySQL Database.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-mysql-database-ssl-certificate-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_ssl_cert_samples ), - credentials=dict( + credentials=SpecReturnValue( description='The root username and password for an accessible Managed MySQL Database.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-mysql-database-credentials-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_credentials_samples ), ) @@ -158,7 +159,7 @@ class Module(LinodeModuleBase): """Module for creating and destroying Linode Databases""" def __init__(self) -> None: - self.module_arg_spec = SPEC + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = dict( changed=False, actions=[], diff --git a/plugins/modules/database_mysql_info.py b/plugins/modules/database_mysql_info.py index a163826c..2f20b678 100644 --- a/plugins/modules/database_mysql_info.py +++ b/plugins/modules/database_mysql_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import MySQLDatabase from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -25,48 +26,48 @@ spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict(type='str', description='The ID of the MySQL Database.'), - label=dict(type='str', description='The label of the MySQL Database.'), + id=SpecField(type=FieldType.string, description=['The ID of the MySQL Database.']), + label=SpecField(type=FieldType.string, description=['The label of the MySQL Database.']), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode MySQL Managed Database.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - database=dict( + database=SpecReturnValue( description='The database in JSON serialized form.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-mysql-database-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs_parent.result_database_samples ), - backups=dict( + backups=SpecReturnValue( description='The database backups in JSON serialized form.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-mysql-database-backup-view__responses', - type='dict', + type=FieldType.dict, sample=docs_parent.result_backups_samples ), - ssl_cert=dict( + ssl_cert=SpecReturnValue( description='The SSL CA certificate for an accessible Managed MySQL Database.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-mysql-database-ssl-certificate-view__responses', - type='dict', + type=FieldType.dict, sample=docs_parent.result_ssl_cert_samples ), - credentials=dict( + credentials=SpecReturnValue( description='The root username and password for an accessible Managed MySQL Database.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-mysql-database-credenti' 'als-view__responses', - type='dict', + type=FieldType.dict, sample=docs_parent.result_credentials_samples ), ) @@ -77,7 +78,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode user""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = { 'database': None, 'backups': None, diff --git a/plugins/modules/database_postgresql.py b/plugins/modules/database_postgresql.py index 0757a227..b274a567 100644 --- a/plugins/modules/database_postgresql.py +++ b/plugins/modules/database_postgresql.py @@ -9,6 +9,7 @@ from typing import Optional, cast, Any, Set, Dict, Callable import polling +from ansible_specdoc.objects import SpecField, SpecDocMeta, SpecReturnValue, FieldType from linode_api4 import LinodeClient, ApiError, PostgreSQLDatabase from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -25,20 +26,20 @@ as docs SPEC = dict( - label=dict( - type='str', + label=SpecField( + type=FieldType.string, required=True, - description='This database\'s unique label.'), - state=dict( - type='str', + description=['This database\'s unique label.']), + state=SpecField( + type=FieldType.string, choices=['present', 'absent'], required=True, - description='The state of this database.', + description=['The state of this database.'], ), - allow_list=dict( - type='list', - elements='str', + allow_list=SpecField( + type=FieldType.list, + element_type=FieldType.string, description=[ 'A list of IP addresses that can access the Managed Database.', 'Each item must be a range in CIDR format.' @@ -46,26 +47,26 @@ default=[], editable=True, ), - cluster_size=dict( - type='int', - description='The number of Linode Instance nodes deployed to the Managed Database.', + cluster_size=SpecField( + type=FieldType.string, + description=['The number of Linode Instance nodes deployed to the Managed Database.'], choices=[1, 3], default=1 ), - encrypted=dict( - type='bool', - description='Whether the Managed Databases is encrypted.', + encrypted=SpecField( + type=FieldType.string, + description=['Whether the Managed Databases is encrypted.'], ), - engine=dict( - type='str', - description='The Managed Database engine in engine/version format.', + engine=SpecField( + type=FieldType.string, + description=['The Managed Database engine in engine/version format.'], ), - region=dict( - type='str', - description='The Region ID for the Managed Database.' + region=SpecField( + type=FieldType.string, + description=['The Region ID for the Managed Database.'] ), - replication_type=dict( - type='str', + replication_type=SpecField( + type=FieldType.string, description=[ 'The replication method used for the Managed Database.', 'Defaults to none for a single cluster and ' @@ -76,8 +77,8 @@ choices=['none', 'asynch', 'semi_synch'], default='none' ), - replication_commit_type=dict( - type='str', + replication_commit_type=SpecField( + type=FieldType.string, description=[ 'The synchronization level of the replicating server.', 'Must be local or off for the asynch replication type.', @@ -86,71 +87,71 @@ choices=['off', 'on', 'local', 'remote_write', 'remote_apply'], default='local' ), - ssl_connection=dict( - type='bool', - description='Whether to require SSL credentials to ' - 'establish a connection to the Managed Database.', + ssl_connection=SpecField( + type=FieldType.bool, + description=['Whether to require SSL credentials to ' + 'establish a connection to the Managed Database.'], default=True, ), - type=dict( - type='str', - description='The Linode Instance type used by the ' - 'Managed Database for its nodes.', + type=SpecField( + type=FieldType.string, + description=['The Linode Instance type used by the ' + 'Managed Database for its nodes.'], ), - updates=dict( - type='dict', - options=SPEC_UPDATE_WINDOW, - description='Configuration settings for automated patch ' - 'update maintenance for the Managed Database.', + updates=SpecField( + type=FieldType.dict, + suboptions=SPEC_UPDATE_WINDOW, + description=['Configuration settings for automated patch ' + 'update maintenance for the Managed Database.'], editable=True ), - wait=dict( - type='bool', default=True, - description='Wait for the database to have status `available` before returning.'), - - wait_timeout=dict( - type='int', default=3600, - description='The amount of time, in seconds, to wait for an image to ' - 'have status `available`.' + wait=SpecField( + type=FieldType.bool, default=True, + description=['Wait for the database to have status `available` before returning.']), + + wait_timeout=SpecField( + type=FieldType.integer, default=3600, + description=['The amount of time, in seconds, to wait for an image to ' + 'have status `available`.'] ), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage a Linode PostgreSQL database.' ], requirements=global_requirements, author=global_authors, - spec=SPEC, + options=SPEC, examples=docs.specdoc_examples, return_values=dict( - database=dict( + database=SpecReturnValue( description='The database in JSON serialized form.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-postgresql-database-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_database_samples ), - backups=dict( + backups=SpecReturnValue( description='The database backups in JSON serialized form.', docs_url='https://www.linode.com/docs/api/databases/#' 'managed-postgresql-database-backups-list', - type='dict', + type=FieldType.dict, sample=docs.result_backups_samples ), - ssl_cert=dict( + ssl_cert=SpecReturnValue( description='The SSL CA certificate for an accessible Managed PostgreSQL Database.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-postgresql-database-ssl-certificate-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_ssl_cert_samples ), - credentials=dict( + credentials=SpecReturnValue( description='The root username and password for an ' 'accessible Managed PostgreSQL Database.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-postgresql-database-credentials-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_credentials_samples ), ) @@ -166,7 +167,7 @@ class Module(LinodeModuleBase): """Module for creating and destroying Linode Databases""" def __init__(self) -> None: - self.module_arg_spec = SPEC + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = dict( changed=False, actions=[], diff --git a/plugins/modules/database_postgresql_info.py b/plugins/modules/database_postgresql_info.py index 634cdc7e..e188a0af 100644 --- a/plugins/modules/database_postgresql_info.py +++ b/plugins/modules/database_postgresql_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import PostgreSQLDatabase from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -25,48 +26,48 @@ spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict(type='str', description='The ID of the PostgreSQL Database.'), - label=dict(type='str', description='The label of the PostgreSQL Database.'), + id=SpecField(type=FieldType.string, description=['The ID of the PostgreSQL Database.']), + label=SpecField(type=FieldType.string, description=['The label of the PostgreSQL Database.']), ) -specdoc_meta = dict( +specdoc_meta = SpecDocMeta( description=[ 'Get info about a Linode PostgreSQL Managed Database.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - database=dict( + database=SpecReturnValue( description='The database in JSON serialized form.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-postgresql-database-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs_parent.result_database_samples ), - backups=dict( + backups=SpecReturnValue( description='The database backups in JSON serialized form.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-postgresql-database-backups-list__response-samples', - type='dict', + type=FieldType.dict, sample=docs_parent.result_backups_samples ), - ssl_cert=dict( + ssl_cert=SpecReturnValue( description='The SSL CA certificate for an accessible Managed PostgreSQL Database.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-postgresql-database-ssl-certificate-view', - type='dict', + type=FieldType.dict, sample=docs_parent.result_ssl_cert_samples ), - credentials=dict( + credentials=SpecReturnValue( description='The root username and password for an accessible Managed ' 'PostgreSQL Database.', docs_url='https://www.linode.com/docs/api/databases/' '#managed-postgresql-database-credentials-view__request-samples', - type='dict', + type=FieldType.dict, sample=docs_parent.result_credentials_samples ), ) diff --git a/plugins/modules/domain.py b/plugins/modules/domain.py index 4b98ca09..f78b275d 100644 --- a/plugins/modules/domain.py +++ b/plugins/modules/domain.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import Optional, cast, Any, Set, List +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Domain from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -20,73 +21,73 @@ linode_domain_spec = dict( # Unused for domain objects - label=dict(type='str', required=False, doc_hide=True), - - axfr_ips=dict(type='list', elements='str', editable=True, - description='The list of IPs that may perform a zone transfer for this Domain.'), - description=dict(type='str', editable=True, - description='The list of IPs that may perform a ' - 'zone transfer for this Domain.'), - domain=dict(type='str', required=True, - description='The domain this Domain represents.'), - expire_sec=dict(type='int', editable=True, - description='The amount of time in seconds that may pass' - ' before this Domain is no longer authoritative.'), - master_ips=dict(type='list', elements='str', editable=True, - description='The IP addresses representing the ' - 'master DNS for this Domain.'), - refresh_sec=dict(type='int', editable=True, - description='The amount of time in seconds before ' - 'this Domain should be refreshed.'), - retry_sec=dict(type='int', editable=True, - description='The interval, in seconds, at which a ' - 'failed refresh should be retried.'), - soa_email=dict(type='str', - description='The Start of Authority email address.', + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + + axfr_ips=SpecField(type=FieldType.list, element_type=FieldType.string, editable=True, + description=['The list of IPs that may perform a zone transfer for this Domain.']), + description=SpecField(type=FieldType.string, editable=True, + description=['The list of IPs that may perform a ' + 'zone transfer for this Domain.']), + domain=SpecField(type=FieldType.string, required=True, + description=['The domain this Domain represents.']), + expire_sec=SpecField(type=FieldType.integer, editable=True, + description=['The amount of time in seconds that may pass' + ' before this Domain is no longer authoritative.']), + master_ips=SpecField(type=FieldType.list, element_type=FieldType.string, editable=True, + description=['The IP addresses representing the ' + 'master DNS for this Domain.']), + refresh_sec=SpecField(type=FieldType.integer, editable=True, + description=['The amount of time in seconds before ' + 'this Domain should be refreshed.']), + retry_sec=SpecField(type=FieldType.integer, editable=True, + description=['The interval, in seconds, at which a ' + 'failed refresh should be retried.']), + soa_email=SpecField(type=FieldType.string, + description=['The Start of Authority email address.'], editable=True), - status=dict(type='str', - description='Used to control whether this Domain is currently being rendered.', + status=SpecField(type=FieldType.string, + description=['Used to control whether this Domain is currently being rendered.'], editable=True), - state=dict(type='str', - description='The desired state of the target.', + state=SpecField(type=FieldType.string, + description=['The desired state of the target.'], choices=['present', 'absent'], required=True), - tags=dict(type='list', elements='str', editable=True, - description='An array of tags applied to this object.'), - ttl_sec=dict(type='int', editable=True, - description='the amount of time in seconds that this ' - 'Domain’s records may be cached by resolvers ' - 'or other domain servers.' + tags=SpecField(type=FieldType.list, element_type=FieldType.string, editable=True, + description=['An array of tags applied to this object.']), + ttl_sec=SpecField(type=FieldType.integer, editable=True, + description=['The amount of time in seconds that this ' + 'Domain’s records may be cached by resolvers ' + 'or other domain servers.'] ), - type=dict(type='str', + type=SpecField(type=FieldType.string, editable=True, - description='Whether this Domain represents the authoritative ' - 'source of information for the domain' - ' it describes (master), or whether it is a ' - 'read-only copy of a master (slave).'), + description=['Whether this Domain represents the authoritative ' + 'source of information for the domain' + ' it describes (master), or whether it is a ' + 'read-only copy of a master (slave).']), # Deprecated - group=dict(type='str', doc_hide=True) + group=SpecField(type=FieldType.string, doc_hide=True) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage Linode Domains.' ], requirements=global_requirements, author=global_authors, - spec=linode_domain_spec, + options=linode_domain_spec, examples=docs.specdoc_examples, return_values=dict( - domain=dict( + domain=SpecReturnValue( description='The domain in JSON serialized form.', docs_url='https://www.linode.com/docs/api/domains/#domain-view', - type='dict', + type=FieldType.dict, sample=docs.result_domain_samples ), - records=dict( + records=SpecReturnValue( description='The domain record in JSON serialized form.', docs_url='https://www.linode.com/docs/api/domains/#domain-record-view', - type='list', + type=FieldType.list, sample=docs.result_records_samples ) ) @@ -112,7 +113,7 @@ class LinodeDomain(LinodeModuleBase): """Module for creating and destroying Linode Domains""" def __init__(self) -> None: - self.module_arg_spec = linode_domain_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results = dict( changed=False, From 72b8ac4f9f67163e62eaf15bced70b6440a26235 Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 12:10:02 -0500 Subject: [PATCH 03/13] progress --- docs/modules/domain.md | 112 +++++++++++++++++++++ docs/modules/domain_info.md | 98 ++++++++++++++++++ docs/modules/domain_record.md | 89 +++++++++++++++++ docs/modules/domain_record_info.md | 75 ++++++++++++++ docs/modules/event_list.md | 104 +++++++++++++++++++ plugins/modules/domain_info.py | 41 ++++---- plugins/modules/domain_record.py | 137 +++++++++++++------------- plugins/modules/domain_record_info.py | 57 +++++------ plugins/modules/event_list.py | 59 +++++------ 9 files changed, 627 insertions(+), 145 deletions(-) create mode 100644 docs/modules/domain.md create mode 100644 docs/modules/domain_info.md create mode 100644 docs/modules/domain_record.md create mode 100644 docs/modules/domain_record_info.md create mode 100644 docs/modules/event_list.md diff --git a/docs/modules/domain.md b/docs/modules/domain.md new file mode 100644 index 00000000..597ff5c9 --- /dev/null +++ b/docs/modules/domain.md @@ -0,0 +1,112 @@ +# domain + +Manage Linode Domains. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a domain + linode.cloud.domain: + domain: my-domain.com + type: master + state: present +``` + +```yaml +- name: Delete a domain + linode.cloud.domain: + domain: my-domain.com + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `domain` |
`str`
|
**Required**
| The domain this Domain represents. | +| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | +| `axfr_ips` |
`list`
|
Optional
| The list of IPs that may perform a zone transfer for this Domain. **(Updatable)** | +| `description` |
`str`
|
Optional
| The list of IPs that may perform a zone transfer for this Domain. **(Updatable)** | +| `expire_sec` |
`int`
|
Optional
| The amount of time in seconds that may pass before this Domain is no longer authoritative. **(Updatable)** | +| `master_ips` |
`list`
|
Optional
| The IP addresses representing the master DNS for this Domain. **(Updatable)** | +| `refresh_sec` |
`int`
|
Optional
| The amount of time in seconds before this Domain should be refreshed. **(Updatable)** | +| `retry_sec` |
`int`
|
Optional
| The interval, in seconds, at which a failed refresh should be retried. **(Updatable)** | +| `soa_email` |
`str`
|
Optional
| The Start of Authority email address. **(Updatable)** | +| `status` |
`str`
|
Optional
| Used to control whether this Domain is currently being rendered. **(Updatable)** | +| `tags` |
`list`
|
Optional
| An array of tags applied to this object. **(Updatable)** | +| `ttl_sec` |
`int`
|
Optional
| The amount of time in seconds that this Domain’s records may be cached by resolvers or other domain servers. **(Updatable)** | +| `type` |
`str`
|
Optional
| Whether this Domain represents the authoritative source of information for the domain it describes (master), or whether it is a read-only copy of a master (slave). **(Updatable)** | + + + + + + +## Return Values + +- `domain` - The domain in JSON serialized form. + + - Sample Response: + ```json + { + "axfr_ips": [], + "description": null, + "domain": "example.org", + "expire_sec": 300, + "group": null, + "id": 1234, + "master_ips": [], + "refresh_sec": 300, + "retry_sec": 300, + "soa_email": "admin@example.org", + "status": "active", + "tags": [ + "example tag", + "another example" + ], + "ttl_sec": 300, + "type": "master" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-view) for a list of returned fields + + +- `records` - The domain record in JSON serialized form. + + - Sample Response: + ```json + [ + { + "created": "2018-01-01T00:01:01", + "id": 123456, + "name": "test", + "port": 80, + "priority": 50, + "protocol": null, + "service": null, + "tag": null, + "target": "192.0.2.0", + "ttl_sec": 604800, + "type": "A", + "updated": "2018-01-01T00:01:01", + "weight": 50 + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-record-view) for a list of returned fields + + diff --git a/docs/modules/domain_info.md b/docs/modules/domain_info.md new file mode 100644 index 00000000..fea6eb1c --- /dev/null +++ b/docs/modules/domain_info.md @@ -0,0 +1,98 @@ +# domain_info + +Get info about a Linode Domain. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about a domain by domain + linode.cloud.domain_info: + domain: my-domain.com +``` + +```yaml +- name: Get info about a domain by id + linode.cloud.domain_info: + id: 12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`int`
|
Optional
| The unique domain name of the Domain. Optional if `domain` is defined. | +| `domain` |
`str`
|
Optional
| The unique id of the Domain. Optional if `id` is defined. | + + + + + + +## Return Values + +- `domain` - The domain in JSON serialized form. + + - Sample Response: + ```json + { + "axfr_ips": [], + "description": null, + "domain": "example.org", + "expire_sec": 300, + "group": null, + "id": 1234, + "master_ips": [], + "refresh_sec": 300, + "retry_sec": 300, + "soa_email": "admin@example.org", + "status": "active", + "tags": [ + "example tag", + "another example" + ], + "ttl_sec": 300, + "type": "master" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-view) for a list of returned fields + + +- `records` - The domain record in JSON serialized form. + + - Sample Response: + ```json + [ + { + "created": "2018-01-01T00:01:01", + "id": 123456, + "name": "test", + "port": 80, + "priority": 50, + "protocol": null, + "service": null, + "tag": null, + "target": "192.0.2.0", + "ttl_sec": 604800, + "type": "A", + "updated": "2018-01-01T00:01:01", + "weight": 50 + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-record-view) for a list of returned fields + + diff --git a/docs/modules/domain_record.md b/docs/modules/domain_record.md new file mode 100644 index 00000000..0aa6515f --- /dev/null +++ b/docs/modules/domain_record.md @@ -0,0 +1,89 @@ +# domain_record + +Manage Linode Domain Records. + +NOTE: Domain records are identified by their name, target, and type. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create an A record + linode.cloud.domain_record: + domain: my-domain.com + name: my-subdomain + type: 'A' + target: '127.0.0.1' + state: present +``` + +```yaml +- name: Delete a domain record + linode.cloud.domain: + domain: my-domain.com + name: my-subdomain + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | +| `domain_id` |
`int`
|
Optional
| The ID of the parent Domain. | +| `domain` |
`str`
|
Optional
| The name of the parent Domain. | +| `record_id` |
`int`
|
Optional
| The id of the record to modify. | +| `name` |
`str`
|
Optional
| The name of this Record. NOTE: If the name of the record ends with the domain, it will be dropped from the resulting record's name. | +| `port` |
`int`
|
Optional
| The port this Record points to. Only valid and required for SRV record requests. **(Updatable)** | +| `priority` |
`int`
|
Optional
| The priority of the target host for this Record. Lower values are preferred. Only valid for MX and SRV record requests. Required for SRV record requests. **(Updatable)** | +| `protocol` |
`str`
|
Optional
| The protocol this Record’s service communicates with. An underscore (_) is prepended automatically to the submitted value for this property. **(Updatable)** | +| `service` |
`str`
|
Optional
| An underscore (_) is prepended and a period (.) is appended automatically to the submitted value for this property. Only valid and required for SRV record requests. The name of the service. **(Updatable)** | +| `tag` |
`str`
|
Optional
| The tag portion of a CAA record. Only valid and required for CAA record requests. **(Updatable)** | +| `target` |
`str`
|
Optional
| The target for this Record. | +| `ttl_sec` |
`int`
|
Optional
| The amount of time in seconds that this Domain’s records may be cached by resolvers or other domain servers. **(Updatable)** | +| `type` |
`str`
|
Optional
| The type of Record this is in the DNS system. | +| `weight` |
`int`
|
Optional
| The relative weight of this Record used in the case of identical priority. **(Updatable)** | + + + + + + +## Return Values + +- `record` - View a single Record on this Domain. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "id": 123456, + "name": "test", + "port": 80, + "priority": 50, + "protocol": null, + "service": null, + "tag": null, + "target": "192.0.2.0", + "ttl_sec": 604800, + "type": "A", + "updated": "2018-01-01T00:01:01", + "weight": 50 + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-record-view) for a list of returned fields + + diff --git a/docs/modules/domain_record_info.md b/docs/modules/domain_record_info.md new file mode 100644 index 00000000..17a2978e --- /dev/null +++ b/docs/modules/domain_record_info.md @@ -0,0 +1,75 @@ +# domain_record_info + +Get info about a Linode Domain Record. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about domain records by name + linode.cloud.domain_record_info: + domain: my-domain.com + name: my-subdomain + type: A + target: 0.0.0.0 +``` + +```yaml +- name: Get info about a domain record by id + linode.cloud.domain_info: + domain: my-domain.com + id: 12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `domain_id` |
`int`
|
Optional
| The ID of the parent Domain. Optional if `domain` is defined. | +| `domain` |
`str`
|
Optional
| The name of the parent Domain. Optional if `domain_id` is defined. | +| `id` |
`int`
|
Optional
| The unique id of the subdomain. Optional if `name` is defined. | +| `name` |
`str`
|
Optional
| The name of the domain record. Optional if `id` is defined. | + + + + + + +## Return Values + +- `record` - View a single Record on this Domain. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "id": 123456, + "name": "test", + "port": 80, + "priority": 50, + "protocol": null, + "service": null, + "tag": null, + "target": "192.0.2.0", + "ttl_sec": 604800, + "type": "A", + "updated": "2018-01-01T00:01:01", + "weight": 50 + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/domains/#domain-record-view) for a list of returned fields + + diff --git a/docs/modules/event_list.md b/docs/modules/event_list.md new file mode 100644 index 00000000..4e77362b --- /dev/null +++ b/docs/modules/event_list.md @@ -0,0 +1,104 @@ +# event_list + +List and filter on Linode events. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: List all of the events for the current Linode Account + linode.cloud.event_list: {} +``` + +```yaml +- name: List the latest 5 events for the current Linode Account + linode.cloud.event_list: + count: 5 + order_by: created + order: desc +``` + +```yaml +- name: List all Linode Instance creation events for the current Linode Account + linode.cloud.event_list: + filter: + - name: action + values: linode_create +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `order` |
`str`
|
Optional
| The order to list events in. **(Choices: `desc`, `asc`; Default: `asc`)** | +| `order_by` |
`str`
|
Optional
| The attribute to order events by. | +| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting events. | +| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | + + + + + +### filters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/account/#events-list__responses | +| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | + + + + + + +## Return Values + +- `events` - The returned events. + + - Sample Response: + ```json + [ + { + "action":"ticket_create", + "created":"2018-01-01T00:01:01", + "duration":300.56, + "entity":{ + "id":11111, + "label":"Problem booting my Linode", + "type":"ticket", + "url":"/v4/support/tickets/11111" + }, + "id":123, + "message":"None", + "percent_complete":null, + "rate":null, + "read":true, + "secondary_entity":{ + "id":"linode/debian9", + "label":"linode1234", + "type":"linode", + "url":"/v4/linode/instances/1234" + }, + "seen":true, + "status":null, + "time_remaining":null, + "username":"exampleUser" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#events-list__responses) for a list of returned fields + + diff --git a/plugins/modules/domain_info.py b/plugins/modules/domain_info.py index f748ac30..d9a93390 100644 --- a/plugins/modules/domain_info.py +++ b/plugins/modules/domain_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Domain from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -21,40 +22,40 @@ linode_domain_info_spec = dict( # We need to overwrite attributes to exclude them as requirements - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), - - id=dict(type='int', required=False, - description=[ - 'The unique domain name of the Domain.', - 'Optional if `domain` is defined.' - ]), - domain=dict(type='str', required=False, - description=[ - 'The unique id of the Domain.', - 'Optional if `id` is defined.' - ]) + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + + id=SpecField(type=FieldType.integer, required=False, + description=[ + 'The unique domain name of the Domain.', + 'Optional if `domain` is defined.' + ]), + domain=SpecField(type=FieldType.string, required=False, + description=[ + 'The unique id of the Domain.', + 'Optional if `id` is defined.' + ]) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode Domain.' ], requirements=global_requirements, author=global_authors, - spec=linode_domain_info_spec, + options=linode_domain_info_spec, examples=docs.specdoc_examples, return_values=dict( - domain=dict( + domain=SpecReturnValue( description='The domain in JSON serialized form.', docs_url='https://www.linode.com/docs/api/domains/#domain-view', - type='dict', + type=FieldType.dict, sample=docs_parent.result_domain_samples ), - records=dict( + records=SpecReturnValue( description='The domain record in JSON serialized form.', docs_url='https://www.linode.com/docs/api/domains/#domain-record-view', - type='list', + type=FieldType.list, sample=docs_parent.result_records_samples ) ) @@ -69,7 +70,7 @@ class LinodeDomainInfo(LinodeModuleBase): """Module for getting info about a Linode Domain""" def __init__(self) -> None: - self.module_arg_spec = linode_domain_info_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results = dict( domain=None, diff --git a/plugins/modules/domain_record.py b/plugins/modules/domain_record.py index e2274b0e..9c894531 100644 --- a/plugins/modules/domain_record.py +++ b/plugins/modules/domain_record.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import Optional, cast, Any, Set, List +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Domain, DomainRecord from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -20,86 +21,86 @@ linode_domain_record_spec = dict( # Unused for domain record objects - label=dict(type='str', required=False, doc_hide=True), - - domain_id=dict(type='int', - description='The ID of the parent Domain.'), - domain=dict(type='str', - description='The name of the parent Domain.'), - - record_id=dict(type='int', - description='The id of the record to modify.'), - - name=dict(type='str', - description=[ - 'The name of this Record.', - 'NOTE: If the name of the record ends with the domain, ' - 'it will be dropped from the resulting record\'s name.' - ]), - port=dict(type='int', editable=True, - description=[ - 'The port this Record points to.', - 'Only valid and required for SRV record requests.' - ]), - priority=dict(type='int', editable=True, + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + + domain_id=SpecField(type=FieldType.integer, + description=['The ID of the parent Domain.']), + domain=SpecField(type=FieldType.string, + description=['The name of the parent Domain.']), + + record_id=SpecField(type=FieldType.integer, + description=['The id of the record to modify.']), + + name=SpecField(type=FieldType.string, + description=[ + 'The name of this Record.', + 'NOTE: If the name of the record ends with the domain, ' + 'it will be dropped from the resulting record\'s name.' + ]), + port=SpecField(type=FieldType.integer, editable=True, + description=[ + 'The port this Record points to.', + 'Only valid and required for SRV record requests.' + ]), + priority=SpecField(type=FieldType.integer, editable=True, + description=[ + 'The priority of the target host for this Record.', + 'Lower values are preferred.', + 'Only valid for MX and SRV record requests.', + 'Required for SRV record requests.' + ]), + protocol=SpecField(type=FieldType.string, editable=True, + description=[ + 'The protocol this Record’s service communicates with.', + 'An underscore (_) is prepended automatically to ' + 'the submitted value for this property.' + ]), + service=SpecField(type=FieldType.string, editable=True, + description=[ + 'An underscore (_) is prepended and a period (.) ' + 'is appended automatically to the submitted value for this property.', + 'Only valid and required for SRV record requests.', + 'The name of the service.' + ]), + state=SpecField(type=FieldType.string, + description=['The desired state of the target.'], + choices=['present', 'absent'], required=True), + tag=SpecField(type=FieldType.string, editable=True, description=[ - 'The priority of the target host for this Record.', - 'Lower values are preferred.', - 'Only valid for MX and SRV record requests.', - 'Required for SRV record requests.' + 'The tag portion of a CAA record.', + 'Only valid and required for CAA record requests.' ]), - protocol=dict(type='str', editable=True, - description=[ - 'The protocol this Record’s service communicates with.', - 'An underscore (_) is prepended automatically to ' - 'the submitted value for this property.' - ]), - service=dict(type='str', editable=True, - description=[ - 'An underscore (_) is prepended and a period (.) ' - 'is appended automatically to the submitted value for this property.', - 'Only valid and required for SRV record requests.', - 'The name of the service.' - ]), - state=dict(type='str', - description='The desired state of the target.', - choices=['present', 'absent'], required=True), - tag=dict(type='str', editable=True, - description=[ - 'The tag portion of a CAA record.', - 'Only valid and required for CAA record requests.' - ]), - target=dict(type='str', - description=[ - 'The target for this Record.' - ], default=''), - ttl_sec=dict(type='int', editable=True, - description=[ - 'The amount of time in seconds that this Domain’s ' - 'records may be cached by resolvers ' - 'or other domain servers.' - ]), - type=dict(type='str', - description='The type of Record this is in the DNS system.'), - weight=dict(type='int', editable=True, - description='The relative weight of this Record ' - 'used in the case of identical priority.') + target=SpecField(type=FieldType.string, + description=[ + 'The target for this Record.' + ], default=''), + ttl_sec=SpecField(type=FieldType.integer, editable=True, + description=[ + 'The amount of time in seconds that this Domain’s ' + 'records may be cached by resolvers ' + 'or other domain servers.' + ]), + type=SpecField(type=FieldType.string, + description=['The type of Record this is in the DNS system.']), + weight=SpecField(type=FieldType.integer, editable=True, + description=['The relative weight of this Record ' + 'used in the case of identical priority.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage Linode Domain Records.', 'NOTE: Domain records are identified by their name, target, and type.' ], requirements=global_requirements, author=global_authors, - spec=linode_domain_record_spec, + options=linode_domain_record_spec, examples=docs.specdoc_examples, return_values=dict( - record=dict( + record=SpecReturnValue( description='View a single Record on this Domain.', docs_url='https://www.linode.com/docs/api/domains/#domain-record-view', - type='dict', + type=FieldType.dict, sample=docs.result_record_samples ) ) @@ -120,7 +121,7 @@ class LinodeDomainRecord(LinodeModuleBase): """Module for creating and destroying Linode Domain records""" def __init__(self) -> None: - self.module_arg_spec = linode_domain_record_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[List[str]] = [['domain', 'domain_id'], ['name', 'record_id']] self.mutually_exclusive: List[List[str]] = [['name', 'record_id']] self.required_together: List[List[str]] = [['name', 'type']] @@ -241,7 +242,7 @@ def _update_record(self) -> None: self.fail( 'failed to update domain record {0}: {1} is a non-updatable field' - .format(self._record.name, key)) + .format(self._record.name, key)) if should_update: self._record.save() diff --git a/plugins/modules/domain_record_info.py b/plugins/modules/domain_record_info.py index a04c861b..ca19a9cd 100644 --- a/plugins/modules/domain_record_info.py +++ b/plugins/modules/domain_record_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Any, Optional, Dict +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Domain, DomainRecord from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -23,46 +24,46 @@ linode_domain_record_info_spec = dict( # We need to overwrite attributes to exclude them as requirements - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), - - domain_id=dict(type='int', + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + + domain_id=SpecField(type=FieldType.integer, + description=[ + 'The ID of the parent Domain.', + 'Optional if `domain` is defined.' + ]), + domain=SpecField(type=FieldType.string, + description=[ + 'The name of the parent Domain.', + 'Optional if `domain_id` is defined.' + ]), + + id=SpecField(type=FieldType.integer, + description=[ + 'The unique id of the subdomain.', + 'Optional if `name` is defined.' + ]), + + name=SpecField(type=FieldType.string, description=[ - 'The ID of the parent Domain.', - 'Optional if `domain` is defined.' + 'The name of the domain record.', + 'Optional if `id` is defined.' ]), - domain=dict(type='str', - description=[ - 'The name of the parent Domain.', - 'Optional if `domain_id` is defined.' - ]), - - id=dict(type='int', - description=[ - 'The unique id of the subdomain.', - 'Optional if `name` is defined.' - ]), - - name=dict(type='str', - description=[ - 'The name of the domain record.', - 'Optional if `id` is defined.' - ]), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode Domain Record.' ], requirements=global_requirements, author=global_authors, - spec=linode_domain_record_info_spec, + options=linode_domain_record_info_spec, examples=docs.specdoc_examples, return_values=dict( - record=dict( + record=SpecReturnValue( description='View a single Record on this Domain.', docs_url='https://www.linode.com/docs/api/domains/#domain-record-view', - type='dict', + type=FieldType.dict, sample=docs_parent.result_record_samples ) ) @@ -73,7 +74,7 @@ class LinodeDomainRecordInfo(LinodeModuleBase): """Module for getting info about a Linode Domain record""" def __init__(self) -> None: - self.module_arg_spec = linode_domain_record_info_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[List[str]] = [['domain_id', 'domain'], ['id', 'name']] self.results: Dict[Any, Any] = dict( records=[] diff --git a/plugins/modules/event_list.py b/plugins/modules/event_list.py index 423605c7..d05478ee 100644 --- a/plugins/modules/event_list.py +++ b/plugins/modules/event_list.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Any, Optional, Dict +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Image from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -19,49 +20,49 @@ import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.event_list as docs spec_filter = dict( - name=dict(type='str', required=True, - description=[ - 'The name of the field to filter on.', - 'Valid filterable attributes can be found here: ' - 'https://www.linode.com/docs/api/account/#events-list__responses', - ]), - values=dict(type='list', elements='str', required=True, - description=[ - 'A list of values to allow for this field.', - 'Fields will pass this filter if at least one of these values matches.' - ]) + name=SpecField(type=FieldType.string, required=True, + description=[ + 'The name of the field to filter on.', + 'Valid filterable attributes can be found here: ' + 'https://www.linode.com/docs/api/account/#events-list__responses', + ]), + values=SpecField(type=FieldType.list, element_type=FieldType.string, required=True, + description=[ + 'A list of values to allow for this field.', + 'Fields will pass this filter if at least one of these values matches.' + ]) ) spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), - - order=dict(type='str', description='The order to list events in.', - default='asc', choices=['desc', 'asc']), - order_by=dict(type='str', description='The attribute to order events by.'), - filters=dict(type='list', elements='dict', options=spec_filter, - description='A list of filters to apply to the resulting events.'), - count=dict(type='int', - description=[ - 'The number of results to return.', - 'If undefined, all results will be returned.']) + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + + order=SpecField(type=FieldType.string, description=['The order to list events in.'], + default='asc', choices=['desc', 'asc']), + order_by=SpecField(type=FieldType.string, description=['The attribute to order events by.']), + filters=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=spec_filter, + description=['A list of filters to apply to the resulting events.']), + count=SpecField(type=FieldType.integer, + description=[ + 'The number of results to return.', + 'If undefined, all results will be returned.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'List and filter on Linode events.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - events=dict( + events=SpecReturnValue( description='The returned events.', docs_url='https://www.linode.com/docs/api/account/#events-list__responses', - type='list', - elements='dict', + type=FieldType.list, + elements=FieldType.dict, sample=docs.result_events_samples ) ) @@ -72,7 +73,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode events""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results: Dict[str, Any] = { 'events': [] } From 669e31a5481947f24e99d950e7cea627dd19472c Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 12:12:20 -0500 Subject: [PATCH 04/13] oops --- docs/modules/database_postgresql.md | 4 +- docs/modules/database_postgresql_info.md | 125 ++++++++++++++++++++ plugins/modules/database_postgresql.py | 4 +- plugins/modules/database_postgresql_info.py | 4 +- 4 files changed, 131 insertions(+), 6 deletions(-) create mode 100644 docs/modules/database_postgresql_info.md diff --git a/docs/modules/database_postgresql.md b/docs/modules/database_postgresql.md index 32da9f8a..e5cff1de 100644 --- a/docs/modules/database_postgresql.md +++ b/docs/modules/database_postgresql.md @@ -61,8 +61,8 @@ Manage a Linode PostgreSQL database. | `label` |
`str`
|
**Required**
| This database's unique label. | | `state` |
`str`
|
**Required**
| The state of this database. **(Choices: `present`, `absent`)** | | `allow_list` |
`list`
|
Optional
| A list of IP addresses that can access the Managed Database. Each item must be a range in CIDR format. **(Updatable)** | -| `cluster_size` |
`str`
|
Optional
| The number of Linode Instance nodes deployed to the Managed Database. **(Choices: `1`, `3`; Default: `1`)** | -| `encrypted` |
`str`
|
Optional
| Whether the Managed Databases is encrypted. | +| `cluster_size` |
`int`
|
Optional
| The number of Linode Instance nodes deployed to the Managed Database. **(Choices: `1`, `3`; Default: `1`)** | +| `encrypted` |
`bool`
|
Optional
| Whether the Managed Databases is encrypted. | | `engine` |
`str`
|
Optional
| The Managed Database engine in engine/version format. | | `region` |
`str`
|
Optional
| The Region ID for the Managed Database. | | `replication_type` |
`str`
|
Optional
| The replication method used for the Managed Database. Defaults to none for a single cluster and semi_synch for a high availability cluster. Must be none for a single node cluster. Must be asynch or semi_synch for a high availability cluster. **(Choices: `none`, `asynch`, `semi_synch`; Default: `none`)** | diff --git a/docs/modules/database_postgresql_info.md b/docs/modules/database_postgresql_info.md new file mode 100644 index 00000000..af3537b1 --- /dev/null +++ b/docs/modules/database_postgresql_info.md @@ -0,0 +1,125 @@ +# database_postgresql_info + +Get info about a Linode PostgreSQL Managed Database. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about a Managed PostgreSQL Database by label + linode.cloud.database_postgresql_info: + label: my-db +``` + +```yaml +- name: Get info about a Managed PostgreSQL Database by ID + linode.cloud.database_postgresql_info: + id: 12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`str`
|
Optional
| The ID of the PostgreSQL Database. | +| `label` |
`str`
|
Optional
| The label of the PostgreSQL Database. | + + + + + + +## Return Values + +- `database` - The database in JSON serialized form. + + - Sample Response: + ```json + { + "allow_list": [ + "203.0.113.1/32", + "192.0.1.0/24" + ], + "cluster_size": 3, + "created": "2022-01-01T00:01:01", + "encrypted": false, + "engine": "postgresql", + "hosts": { + "primary": "lin-0000-000-pgsql-primary.servers.linodedb.net", + "secondary": "lin-0000-000-pgsql-primary-private.servers.linodedb.net" + }, + "id": 123, + "label": "example-db", + "port": 3306, + "region": "us-east", + "replication_commit_type": "local", + "replication_type": "semi_synch", + "ssl_connection": true, + "status": "active", + "type": "g6-dedicated-2", + "updated": "2022-01-01T00:01:01", + "updates": { + "day_of_week": 1, + "duration": 3, + "frequency": "weekly", + "hour_of_day": 0, + "week_of_month": null + }, + "version": "13.2" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-view__response-samples) for a list of returned fields + + +- `backups` - The database backups in JSON serialized form. + + - Sample Response: + ```json + [ + { + "created":"2022-01-01T00:01:01", + "id":123, + "label":"Scheduled - 02/04/22 11:11 UTC-XcCRmI", + "type":"auto" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-backups-list__response-samples) for a list of returned fields + + +- `ssl_cert` - The SSL CA certificate for an accessible Managed PostgreSQL Database. + + - Sample Response: + ```json + { + "ca_certificate": "LS0tLS1CRUdJ...==" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-ssl-certificate-view) for a list of returned fields + + +- `credentials` - The root username and password for an accessible Managed PostgreSQL Database. + + - Sample Response: + ```json + { + "password": "s3cur3P@ssw0rd", + "username": "linroot" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/databases/#managed-postgresql-database-credentials-view__request-samples) for a list of returned fields + + diff --git a/plugins/modules/database_postgresql.py b/plugins/modules/database_postgresql.py index b274a567..42d5abbb 100644 --- a/plugins/modules/database_postgresql.py +++ b/plugins/modules/database_postgresql.py @@ -48,13 +48,13 @@ editable=True, ), cluster_size=SpecField( - type=FieldType.string, + type=FieldType.integer, description=['The number of Linode Instance nodes deployed to the Managed Database.'], choices=[1, 3], default=1 ), encrypted=SpecField( - type=FieldType.string, + type=FieldType.bool, description=['Whether the Managed Databases is encrypted.'], ), engine=SpecField( diff --git a/plugins/modules/database_postgresql_info.py b/plugins/modules/database_postgresql_info.py index e188a0af..b061357d 100644 --- a/plugins/modules/database_postgresql_info.py +++ b/plugins/modules/database_postgresql_info.py @@ -32,7 +32,7 @@ label=SpecField(type=FieldType.string, description=['The label of the PostgreSQL Database.']), ) -specdoc_meta = SpecDocMeta( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode PostgreSQL Managed Database.' ], @@ -78,7 +78,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode PostgreSQL database""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = { 'database': None, 'backups': None, From e2e474a0aef996d826f1cadbe0fa9370e9741b7a Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 13:45:32 -0500 Subject: [PATCH 05/13] progress --- docs/modules/firewall.md | 223 +++++++++++++++++++++++++++++ docs/modules/firewall_device.md | 81 +++++++++++ docs/modules/firewall_info.md | 124 ++++++++++++++++ docs/modules/image.md | 90 ++++++++++++ docs/modules/image_info.md | 70 +++++++++ docs/modules/image_list.md | 94 ++++++++++++ plugins/modules/firewall.py | 192 +++++++++++++------------ plugins/modules/firewall_device.py | 47 +++--- plugins/modules/firewall_info.py | 39 ++--- plugins/modules/image.py | 69 ++++----- plugins/modules/image_info.py | 17 +-- plugins/modules/image_list.py | 32 +++-- 12 files changed, 884 insertions(+), 194 deletions(-) create mode 100644 docs/modules/firewall.md create mode 100644 docs/modules/firewall_device.md create mode 100644 docs/modules/firewall_info.md create mode 100644 docs/modules/image.md create mode 100644 docs/modules/image_info.md create mode 100644 docs/modules/image_list.md diff --git a/docs/modules/firewall.md b/docs/modules/firewall.md new file mode 100644 index 00000000..1ebfe8ee --- /dev/null +++ b/docs/modules/firewall.md @@ -0,0 +1,223 @@ +# firewall + +Manage Linode Firewalls. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a Linode Firewall + linode.cloud.firewall: + label: 'my-firewall' + devices: + - id: 123 + type: linode + rules: + inbound_policy: DROP + inbound: + - label: allow-http-in + addresses: + ipv4: + - 0.0.0.0/0 + ipv6: + - 'ff00::/8' + description: Allow inbound HTTP and HTTPS connections. + ports: '80,443' + protocol: TCP + action: ACCEPT + + outbound_policy: DROP + outbound: + - label: allow-http-out + addresses: + ipv4: + - 0.0.0.0/0 + ipv6: + - 'ff00::/8' + description: Allow outbound HTTP and HTTPS connections. + ports: '80,443' + protocol: TCP + action: ACCEPT + state: present +``` + +```yaml +- name: Delete a Linode Firewall + linode.cloud.firewall: + label: 'my-firewall' + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`, `update`)** | +| `label` |
`str`
|
Optional
| The unique label to give this Firewall. | +| [`devices` (sub-options)](#devices) |
`list`
|
Optional
| The devices that are attached to this Firewall. **(Updatable)** | +| [`rules` (sub-options)](#rules) |
`dict`
|
Optional
| The inbound and outbound access rules to apply to this Firewall. **(Updatable)** | +| `status` |
`str`
|
Optional
| The status of this Firewall. **(Updatable)** | + + + + + +### devices + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`int`
|
**Required**
| The unique ID of the device to attach to this Firewall. | +| `type` |
`str`
|
Optional
| The type of device to be attached to this Firewall. **(Default: `linode`)** | + + + + + +### rules + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| [`inbound` (sub-options)](#inbound) |
`list`
|
Optional
| A list of rules for inbound traffic. | +| `inbound_policy` |
`str`
|
Optional
| The default behavior for inbound traffic. | +| [`outbound` (sub-options)](#outbound) |
`list`
|
Optional
| A list of rules for outbound traffic. | +| `outbound_policy` |
`str`
|
Optional
| The default behavior for outbound traffic. | + + + + + +### inbound + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| The label of this rule. | +| `action` |
`str`
|
**Required**
| Controls whether traffic is accepted or dropped by this rule. **(Choices: `ACCEPT`, `DROP`)** | +| [`addresses` (sub-options)](#addresses) |
`dict`
|
Optional
| Allowed IPv4 or IPv6 addresses. | +| `description` |
`str`
|
Optional
| A description for this rule. | +| `ports` |
`str`
|
Optional
| A string representing the port or ports on which traffic will be allowed. See U(https://www.linode.com/docs/api/networking/#firewall-create) | +| `protocol` |
`str`
|
Optional
| The type of network traffic to allow. | + + + + + +### addresses + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `ipv4` |
`list`
|
Optional
| A list of IPv4 addresses or networks. Must be in IP/mask format. | +| `ipv6` |
`list`
|
Optional
| A list of IPv6 addresses or networks. Must be in IP/mask format. | + + + + + +### outbound + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| The label of this rule. | +| `action` |
`str`
|
**Required**
| Controls whether traffic is accepted or dropped by this rule. **(Choices: `ACCEPT`, `DROP`)** | +| [`addresses` (sub-options)](#addresses) |
`dict`
|
Optional
| Allowed IPv4 or IPv6 addresses. | +| `description` |
`str`
|
Optional
| A description for this rule. | +| `ports` |
`str`
|
Optional
| A string representing the port or ports on which traffic will be allowed. See U(https://www.linode.com/docs/api/networking/#firewall-create) | +| `protocol` |
`str`
|
Optional
| The type of network traffic to allow. | + + + + + + +## Return Values + +- `firewall` - The Firewall description in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "id": 123, + "label": "firewall123", + "rules": { + "inbound": [ + { + "action": "ACCEPT", + "addresses": { + "ipv4": [ + "192.0.2.0/24" + ], + "ipv6": [ + "2001:DB8::/32" + ] + }, + "description": "An example firewall rule description.", + "label": "firewallrule123", + "ports": "22-24, 80, 443", + "protocol": "TCP" + } + ], + "inbound_policy": "DROP", + "outbound": [ + { + "action": "ACCEPT", + "addresses": { + "ipv4": [ + "192.0.2.0/24" + ], + "ipv6": [ + "2001:DB8::/32" + ] + }, + "description": "An example firewall rule description.", + "label": "firewallrule123", + "ports": "22-24, 80, 443", + "protocol": "TCP" + } + ], + "outbound_policy": "DROP" + }, + "status": "enabled", + "tags": [ + "example tag", + "another example" + ], + "updated": "2018-01-02T00:01:01" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#firewall-view) for a list of returned fields + + +- `devices` - A list of Firewall devices JSON serialized form. + + - Sample Response: + ```json + [ + { + "created": "2018-01-01T00:01:01", + "entity": { + "id": 123, + "label": "my-linode", + "type": "linode", + "url": "/v4/linode/instances/123" + }, + "id": 123, + "updated": "2018-01-02T00:01:01" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#firewall-device-view) for a list of returned fields + + diff --git a/docs/modules/firewall_device.md b/docs/modules/firewall_device.md new file mode 100644 index 00000000..fb5315fa --- /dev/null +++ b/docs/modules/firewall_device.md @@ -0,0 +1,81 @@ +# firewall_device + +Manage Linode Firewall Devices. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a Firewall + linode.cloud.firewall: + label: my-firewall + rules: + inbound_policy: DROP + state: present + register: firewall_result + +- name: Create an Instance + linode.cloud.instance: + label: my-instance + region: us-east + private_ip: true + type: g6-standard-1 + state: present + register: instance_result + +- name: Attach the instance to the Firewall + linode.cloud.firewall_device: + firewall_id: '{{ firewall_result.firewall.id }}' + entity_id: '{{ instance_result.instance.id }}' + entity_type: 'linode' + state: present +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `firewall_id` |
`int`
|
**Required**
| The ID of the Firewall that contains this device. | +| `entity_id` |
`int`
|
**Required**
| The ID for this Firewall Device. This will be the ID of the Linode Entity. | +| `entity_type` |
`str`
|
**Required**
| The type of Linode Entity. Currently only supports linode. **(Choices: `linode`)** | +| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | + + + + + + +## Return Values + +- `device` - The Firewall Device in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "entity": { + "id": 123, + "label": "my-linode", + "type": "linode", + "url": "/v4/linode/instances/123" + }, + "id": 123, + "updated": "2018-01-02T00:01:01" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#firewall-device-view__responses) for a list of returned fields + + diff --git a/docs/modules/firewall_info.md b/docs/modules/firewall_info.md new file mode 100644 index 00000000..8684097f --- /dev/null +++ b/docs/modules/firewall_info.md @@ -0,0 +1,124 @@ +# firewall_info + +Get info about a Linode Firewall. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about a Firewall by label + linode.cloud.firewall_info: + label: 'my-firewall' +``` + +```yaml +- name: Get info about a Firewall by id + linode.cloud.firewall_info: + id: 12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`int`
|
Optional
| The unique id of the Firewall. Optional if `label` is defined. | +| `label` |
`str`
|
Optional
| The Firewall’s label. Optional if `id` is defined. | + + + + + + +## Return Values + +- `firewall` - The Firewall description in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "id": 123, + "label": "firewall123", + "rules": { + "inbound": [ + { + "action": "ACCEPT", + "addresses": { + "ipv4": [ + "192.0.2.0/24" + ], + "ipv6": [ + "2001:DB8::/32" + ] + }, + "description": "An example firewall rule description.", + "label": "firewallrule123", + "ports": "22-24, 80, 443", + "protocol": "TCP" + } + ], + "inbound_policy": "DROP", + "outbound": [ + { + "action": "ACCEPT", + "addresses": { + "ipv4": [ + "192.0.2.0/24" + ], + "ipv6": [ + "2001:DB8::/32" + ] + }, + "description": "An example firewall rule description.", + "label": "firewallrule123", + "ports": "22-24, 80, 443", + "protocol": "TCP" + } + ], + "outbound_policy": "DROP" + }, + "status": "enabled", + "tags": [ + "example tag", + "another example" + ], + "updated": "2018-01-02T00:01:01" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#firewall-view) for a list of returned fields + + +- `devices` - A list of Firewall devices JSON serialized form. + + - Sample Response: + ```json + [ + { + "created": "2018-01-01T00:01:01", + "entity": { + "id": 123, + "label": "my-linode", + "type": "linode", + "url": "/v4/linode/instances/123" + }, + "id": 123, + "updated": "2018-01-02T00:01:01" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#firewall-device-view) for a list of returned fields + + diff --git a/docs/modules/image.md b/docs/modules/image.md new file mode 100644 index 00000000..6a99fbdc --- /dev/null +++ b/docs/modules/image.md @@ -0,0 +1,90 @@ +# image + +Manage a Linode Image. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a basic image from an existing disk + linode.cloud.image: + label: my-image + description: Created using Ansible! + disk_id: 12345 + state: present +``` + +```yaml +- name: Create a basic image from a file + linode.cloud.image: + label: my-image + description: Created using Ansible! + source_file: myimage.img.gz + state: present +``` + +```yaml +- name: Delete an image + linode.cloud.image: + label: my-image + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| This Image's unique label. | +| `state` |
`str`
|
**Required**
| The state of this Image. **(Choices: `present`, `absent`)** | +| `description` |
`str`
|
Optional
| A description for the Image. **(Updatable)** | +| `disk_id` |
`int`
|
Optional
| The ID of the disk to clone this image from. | +| `recreate` |
`bool`
|
Optional
| If true, the image with the given label will be deleted and recreated **(Default: `False`)** | +| `region` |
`str`
|
Optional
| The Linode region to upload this image to. **(Default: `us-east`)** | +| `source_file` |
`str`
|
Optional
| An image file to create this image with. | +| `wait` |
`bool`
|
Optional
| Wait for the image to have status `available` before returning. **(Default: `True`)** | +| `wait_timeout` |
`int`
|
Optional
| The amount of time, in seconds, to wait for an image to have status `available`. **(Default: `600`)** | + + + + + + +## Return Values + +- `image` - The Image in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2021-08-14T22:44:02", + "created_by": "linode", + "deprecated": false, + "description": "Example Image description.", + "eol": "2026-07-01T04:00:00", + "expiry": null, + "id": "linode/debian11", + "is_public": true, + "label": "Debian 11", + "size": 2500, + "status": null, + "type": "manual", + "updated": "2021-08-14T22:44:02", + "vendor": "Debian" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/images/#image-view__response-samples) for a list of returned fields + + diff --git a/docs/modules/image_info.md b/docs/modules/image_info.md new file mode 100644 index 00000000..671f370c --- /dev/null +++ b/docs/modules/image_info.md @@ -0,0 +1,70 @@ +# image_info + +Get info about a Linode Image. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about an image by label + linode.cloud.image_info: + label: my-image +``` + +```yaml +- name: Get info about an image by ID + linode.cloud.image_info: + id: private/12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`str`
|
Optional
| The ID of the image. | +| `label` |
`str`
|
Optional
| The label of the image. | + + + + + + +## Return Values + +- `image` - The image in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2021-08-14T22:44:02", + "created_by": "linode", + "deprecated": false, + "description": "Example Image description.", + "eol": "2026-07-01T04:00:00", + "expiry": null, + "id": "linode/debian11", + "is_public": true, + "label": "Debian 11", + "size": 2500, + "status": null, + "type": "manual", + "updated": "2021-08-14T22:44:02", + "vendor": "Debian" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/images/#image-view__responses) for a list of returned fields + + diff --git a/docs/modules/image_list.md b/docs/modules/image_list.md new file mode 100644 index 00000000..21b549ad --- /dev/null +++ b/docs/modules/image_list.md @@ -0,0 +1,94 @@ +# image_list + +List and filter on Linode images. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: List all of the images for the current Linode Account + linode.cloud.image_list: {} +``` + +```yaml +- name: List the latest 5 images for the current Linode Account + linode.cloud.image_list: + count: 5 + order_by: created + order: desc +``` + +```yaml +- name: Resolve all Alpine Linux images + linode.cloud.image_list: + filter: + - name: vendor + values: Alpine +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `order` |
`str`
|
Optional
| The order to list events in. **(Choices: `desc`, `asc`; Default: `asc`)** | +| `order_by` |
`str`
|
Optional
| The attribute to order events by. | +| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting events. | +| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | + + + + + +### filters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/images/#images-list__responses | +| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | + + + + + + +## Return Values + +- `images` - The returned images. + + - Sample Response: + ```json + [ + { + "created":"2021-08-14T22:44:02", + "created_by":"linode", + "deprecated":false, + "description":"Example Image description.", + "eol":"2026-07-01T04:00:00", + "expiry":null, + "id":"linode/debian11", + "is_public":true, + "label":"Debian 11", + "size":2500, + "status":null, + "type":"manual", + "updated":"2021-08-14T22:44:02", + "vendor":"Debian" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/images/#images-list__response-samples) for a list of returned fields + + diff --git a/plugins/modules/firewall.py b/plugins/modules/firewall.py index 99aea2fb..e6aca13a 100644 --- a/plugins/modules/firewall.py +++ b/plugins/modules/firewall.py @@ -9,6 +9,9 @@ from typing import Optional, List, Any import ipaddress + +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue + from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ filter_null_values, mapping_to_dict, paginated_list_to_json, filter_null_values_recursive @@ -23,124 +26,123 @@ pass linode_firewall_addresses_spec: dict = dict( - ipv4=dict(type='list', elements='str', - description=[ - 'A list of IPv4 addresses or networks.', - 'Must be in IP/mask format.' - ]), - ipv6=dict(type='list', elements='str', - description=[ - 'A list of IPv4 addresses or networks.', - 'Must be in IP/mask format.' - ]) + ipv4=SpecField(type=FieldType.list, element_type=FieldType.string, + description=[ + 'A list of IPv4 addresses or networks.', + 'Must be in IP/mask format.' + ]), + ipv6=SpecField(type=FieldType.list, element_type=FieldType.string, + description=[ + 'A list of IPv6 addresses or networks.', + 'Must be in IP/mask format.' + ]) ) linode_firewall_rule_spec: dict = dict( - label=dict(type='str', required=True, - description=[ - 'The label of this rule.' - ]), - action=dict(type='str', choices=['ACCEPT', 'DROP'], required=True, - description=[ - 'Controls whether traffic is accepted or dropped by this rule.' - ]), - addresses=dict(type='dict', options=linode_firewall_addresses_spec, - description=[ - 'Allowed IPv4 or IPv6 addresses.' - ]), - description=dict(type='str', + label=SpecField(type=FieldType.string, required=True, + description=[ + 'The label of this rule.' + ]), + action=SpecField(type=FieldType.string, choices=['ACCEPT', 'DROP'], required=True, description=[ - 'A description for this rule.' + 'Controls whether traffic is accepted or dropped by this rule.' ]), - ports=dict(type='str', - description=[ - 'A string representing the port or ports on which traffic will be allowed.', - 'See U(https://www.linode.com/docs/api/networking/#firewall-create)' - ]), - protocol=dict(type='str', - description=[ - 'The type of network traffic to allow.' - ]) -) - -linode_firewall_rules_spec: dict = dict( - inbound=dict(type='list', elements='dict', options=linode_firewall_rule_spec, - description=[ - 'A list of rules for inbound traffic.' - ]), - inbound_policy=dict(type='str', + addresses=SpecField(type=FieldType.dict, suboptions=linode_firewall_addresses_spec, description=[ - 'The default behavior for inbound traffic.' + 'Allowed IPv4 or IPv6 addresses.' ]), - outbound=dict(type='list', elements='dict', options=linode_firewall_rule_spec, - description=[ - 'A list of rules for outbound traffic.' - ]), - outbound_policy=dict(type='str', - description=[ - 'The default behavior for outbound traffic.' - ]), + description=SpecField(type=FieldType.string, + description=[ + 'A description for this rule.' + ]), + ports=SpecField(type=FieldType.string, + description=[ + 'A string representing the port or ports on which traffic will be allowed.', + 'See U(https://www.linode.com/docs/api/networking/#firewall-create)' + ]), + protocol=SpecField(type=FieldType.string, + description=[ + 'The type of network traffic to allow.' + ]) ) -linode_firewall_device_spec: dict = dict( - id=dict(type='int', required=True, - description=[ - 'The unique ID of the device to attach to this Firewall.' - ]), - type=dict(type='str', default='linode', - description=[ - 'The type of device to be attached to this Firewall.' - ]) +linode_firewall_rules_spec: dict = dict( + inbound=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=linode_firewall_rule_spec, + description=[ + 'A list of rules for inbound traffic.' + ]), + inbound_policy=SpecField(type=FieldType.string, + description=[ + 'The default behavior for inbound traffic.' + ]), + outbound=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=linode_firewall_rule_spec, + description=[ + 'A list of rules for outbound traffic.' + ]), + outbound_policy=SpecField(type=FieldType.string, + description=[ + 'The default behavior for outbound traffic.' + ]), ) -linode_firewall_spec: dict = dict( - label=dict(type='str', - description=[ - 'The unique label to give this Firewall.' - ]), - devices=dict(type='list', elements='dict', options=linode_firewall_device_spec, editable=True, +linode_firewall_device_spec: dict = dict( + id=SpecField(type=FieldType.integer, required=True, description=[ - 'The devices that are attached to this Firewall.' + 'The unique ID of the device to attach to this Firewall.' ]), - rules=dict(type='dict', options=linode_firewall_rules_spec, editable=True, - description=[ - 'The inbound and outbound access rules to apply to this Firewall.' - ]), - status=dict(type='str', editable=True, - description=[ - 'The status of this Firewall.' - ]), - state=dict(type='str', - description='The desired state of the target.', - choices=['present', 'absent', 'update'], required=True), + type=SpecField(type=FieldType.string, default='linode', + description=[ + 'The type of device to be attached to this Firewall.' + ]) ) +linode_firewall_spec: dict = dict( + label=SpecField(type=FieldType.string, + description=[ + 'The unique label to give this Firewall.' + ]), + devices=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=linode_firewall_device_spec, + editable=True, + description=[ + 'The devices that are attached to this Firewall.' + ]), + rules=SpecField(type=FieldType.dict, suboptions=linode_firewall_rules_spec, editable=True, + description=[ + 'The inbound and outbound access rules to apply to this Firewall.' + ]), + status=SpecField(type=FieldType.string, editable=True, + description=[ + 'The status of this Firewall.' + ]), + state=SpecField(type=FieldType.string, + description=['The desired state of the target.'], + choices=['present', 'absent', 'update'], required=True), +) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage Linode Firewalls.' ], requirements=global_requirements, author=global_authors, - spec=linode_firewall_spec, + options=linode_firewall_spec, examples=docs.specdoc_examples, return_values=dict( - firewall=dict( + firewall=SpecReturnValue( description='The Firewall description in JSON serialized form.', docs_url='https://www.linode.com/docs/api/networking/#firewall-view', - type='dict', + type=FieldType.dict, sample=docs.result_firewall_samples ), - devices=dict( + devices=SpecReturnValue( description='A list of Firewall devices JSON serialized form.', docs_url='https://www.linode.com/docs/api/networking/#firewall-device-view', - type='list', + type=FieldType.list, sample=docs.result_devices_samples ) ) ) - # Fields that can be updated on an existing Firewall linode_firewall_mutable: List[str] = [ 'status', @@ -152,7 +154,7 @@ class LinodeFirewall(LinodeModuleBase): """Module for creating and destroying Linode Firewalls""" def __init__(self) -> None: - self.module_arg_spec = linode_firewall_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results: dict = dict( changed=False, @@ -230,7 +232,7 @@ def _normalize_ips(rules: list) -> list: for rule in rules: item = copy.deepcopy(rule) - addresses = rule.get('addresses',[]) + addresses = rule.get('addresses', []) if 'ipv6' in addresses: item['addresses']['ipv6'] = [str(ipaddress.IPv6Network(v)) @@ -249,8 +251,8 @@ def _amend_rules(remote_rules: list, local_rules: list) -> list: # produce a result list in the same order as remote_rules # amended by the updates from the local_rules - local_labeled_rules = { r['label']:r for r in local_rules } - result=[] + local_labeled_rules = {r['label']: r for r in local_rules} + result = [] for remote_rule in remote_rules: # copy remote_rule as is if not being updated by local_rules if remote_rule['label'] not in local_labeled_rules: @@ -261,16 +263,16 @@ def _amend_rules(remote_rules: list, local_rules: list) -> list: local_rule = local_labeled_rules[remote_rule['label']] for field in linode_firewall_rule_spec: if field not in local_rule and field in remote_rule: - local_rule[field]=remote_rule[field] + local_rule[field] = remote_rule[field] for ip_version in ['ipv6', 'ipv4']: if ip_version in local_rule.get('addresses', {}): continue - remote_addresses=remote_rule.get('addresses',{}) - local_addresses=local_rule.get('addresses',{}) - local_addresses[ip_version]=remote_addresses.get(ip_version,[]) - local_rule['addresses']=local_addresses + remote_addresses = remote_rule.get('addresses', {}) + local_addresses = local_rule.get('addresses', {}) + local_addresses[ip_version] = remote_addresses.get(ip_version, []) + local_rule['addresses'] = local_addresses result.append(local_rule) return result @@ -282,8 +284,8 @@ def _update_rules(self, remote_rules: dict, local_rules: dict) -> dict: # Add new local rules to remote rules if they don't exist for direction in ['inbound', 'outbound']: - rlr = { remote_rule['label'] for remote_rule in remote_rules.get(direction,{}) } - for local_rule in local_rules.get(direction,{}): + rlr = {remote_rule['label'] for remote_rule in remote_rules.get(direction, {})} + for local_rule in local_rules.get(direction, {}): if local_rule['label'] not in rlr: remote_rules[direction].append(local_rule) diff --git a/plugins/modules/firewall_device.py b/plugins/modules/firewall_device.py index 5bf96b4d..cc6752a5 100644 --- a/plugins/modules/firewall_device.py +++ b/plugins/modules/firewall_device.py @@ -8,6 +8,7 @@ from typing import Optional, Any, List import linode_api4 +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Domain from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -17,48 +18,47 @@ import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.firewall_device as docs MODULE_SPEC = dict( - firewall_id=dict( - type='int', required=True, - description='The ID of the Firewall that contains this device.', - ), - - entity_id=dict( - type='int', required=True, - description='The ID for this Firewall Device. This will be the ID of the Linode Entity.', + firewall_id=SpecField( + type=FieldType.integer, required=True, + description=['The ID of the Firewall that contains this device.'], ), - entity_type=dict( - type='str', required=True, - description='The type of Linode Entity. Currently only supports linode.', + entity_id=SpecField( + type=FieldType.integer, required=True, + description=['The ID for this Firewall Device. This will be the ID of the Linode Entity.'], + ), + + entity_type=SpecField( + type=FieldType.string, required=True, + description=['The type of Linode Entity. Currently only supports linode.'], choices=['linode'], ), - label=dict( - type='str', + label=SpecField( + type=FieldType.string, required=False, doc_hide=True, ), - state=dict(type='str', - description='The desired state of the target.', - choices=['present', 'absent'], required=True), + state=SpecField( + type=FieldType.string, + description=['The desired state of the target.'], + choices=['present', 'absent'], required=True), ) - - -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage Linode Firewall Devices.' ], requirements=global_requirements, author=global_authors, - spec=MODULE_SPEC, + options=MODULE_SPEC, examples=docs.specdoc_examples, return_values=dict( - device=dict( + device=SpecReturnValue( description='The Firewall Device in JSON serialized form.', docs_url='https://www.linode.com/docs/api/networking/#firewall-device-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_device_samples ) ) @@ -69,7 +69,7 @@ class LinodeFirewallDevice(LinodeModuleBase): """Module for managing Linode Firewall devices""" def __init__(self) -> None: - self.module_arg_spec = MODULE_SPEC + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results = dict( changed=False, @@ -149,6 +149,7 @@ def exec_module(self, **kwargs: Any) -> Optional[dict]: return self.results + def main() -> None: """Constructs and calls the Linode Domain module""" LinodeFirewallDevice() diff --git a/plugins/modules/firewall_info.py b/plugins/modules/firewall_info.py index 8e75bb38..283c6717 100644 --- a/plugins/modules/firewall_info.py +++ b/plugins/modules/firewall_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import Optional, List, Any, Dict +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Firewall from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -21,39 +22,39 @@ linode_firewall_info_spec = dict( # We need to overwrite attributes to exclude them as requirements - state=dict(type='str', required=False, doc_hide=True), - - id=dict(type='int', required=False, - description=[ - 'The unique id of the Firewall.', - 'Optional if `label` is defined.' - ]), - label=dict(type='str', required=False, - description=[ - 'The Firewall’s label.', - 'Optional if `id` is defined.' - ]) + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + + id=SpecField(type=FieldType.integer, required=False, + description=[ + 'The unique id of the Firewall.', + 'Optional if `label` is defined.' + ]), + label=SpecField(type=FieldType.string, required=False, + description=[ + 'The Firewall’s label.', + 'Optional if `id` is defined.' + ]) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode Firewall.' ], requirements=global_requirements, author=global_authors, - spec=linode_firewall_info_spec, + options=linode_firewall_info_spec, examples=docs.specdoc_examples, return_values=dict( - firewall=dict( + firewall=SpecReturnValue( description='The Firewall description in JSON serialized form.', docs_url='https://www.linode.com/docs/api/networking/#firewall-view', - type='dict', + type=FieldType.dict, sample=docs_parent.result_firewall_samples ), - devices=dict( + devices=SpecReturnValue( description='A list of Firewall devices JSON serialized form.', docs_url='https://www.linode.com/docs/api/networking/#firewall-device-view', - type='list', + type=FieldType.list, sample=docs_parent.result_devices_samples ) ) @@ -68,7 +69,7 @@ class LinodeFirewallInfo(LinodeModuleBase): """Module for viewing info about a Linode Firewall""" def __init__(self) -> None: - self.module_arg_spec = linode_firewall_info_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results: Dict[str, Any] = dict( firewall=None, diff --git a/plugins/modules/image.py b/plugins/modules/image.py index 5bc4ab9b..72402c0c 100644 --- a/plugins/modules/image.py +++ b/plugins/modules/image.py @@ -12,6 +12,7 @@ import polling import requests +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Image from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -25,63 +26,63 @@ import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.image as docs SPEC = dict( - label=dict( - type='str', + label=SpecField( + type=FieldType.string, required=True, - description='This Image\'s unique label.'), - state=dict( - type='str', + description=['This Image\'s unique label.']), + state=SpecField( + type=FieldType.string, choices=['present', 'absent'], required=True, - description='The state of this Image.', + description=['The state of this Image.'], ), - description=dict( - type='str', + description=SpecField( + type=FieldType.string, editable=True, - description='A description for the Image.', + description=['A description for the Image.'], ), - disk_id=dict( - type='int', - description='The ID of the disk to clone this image from.', + disk_id=SpecField( + type=FieldType.integer, + description=['The ID of the disk to clone this image from.'], ), - recreate=dict( - type='bool', default=False, - description='If true, the image with the given label will be deleted and recreated', + recreate=SpecField( + type=FieldType.bool, default=False, + description=['If true, the image with the given label will be deleted and recreated'], ), - region=dict( - type='str', - description='The Linode region to upload this image to.', + region=SpecField( + type=FieldType.string, + description=['The Linode region to upload this image to.'], default='us-east', ), - source_file=dict( - type='str', - description='An image file to create this image with.' + source_file=SpecField( + type=FieldType.string, + description=['An image file to create this image with.'] ), - wait=dict( - type='bool', default=True, - description='Wait for the image to have status `available` before returning.'), - - wait_timeout=dict( - type='int', default=600, - description='The amount of time, in seconds, to wait for an image to ' - 'have status `available`.' + wait=SpecField( + type=FieldType.bool, default=True, + description=['Wait for the image to have status `available` before returning.']), + + wait_timeout=SpecField( + type=FieldType.integer, default=600, + description=['The amount of time, in seconds, to wait for an image to ' + 'have status `available`.'] ), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage a Linode Image.' ], requirements=global_requirements, author=global_authors, - spec=SPEC, + options=SPEC, examples=docs.specdoc_examples, return_values=dict( - image=dict( + image=SpecReturnValue( description='The Image in JSON serialized form.', docs_url='https://www.linode.com/docs/api/images/' '#image-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_image_samples ) ) @@ -96,7 +97,7 @@ class Module(LinodeModuleBase): """Module for creating and destroying Linode Images""" def __init__(self) -> None: - self.module_arg_spec = SPEC + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = dict( changed=False, actions=[], diff --git a/plugins/modules/image_info.py b/plugins/modules/image_info.py index 0d706d11..5212049b 100644 --- a/plugins/modules/image_info.py +++ b/plugins/modules/image_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Image from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -21,25 +22,25 @@ spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict(type='str', description='The ID of the image.'), - label=dict(type='str', description='The label of the image.'), + id=SpecField(type=FieldType.string, description=['The ID of the image.']), + label=SpecField(type=FieldType.string, description=['The label of the image.']), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode Image.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - image=dict( + image=SpecReturnValue( description='The image in JSON serialized form.', docs_url='https://www.linode.com/docs/api/images/#image-view__responses', - type='dict', + type=FieldType.dict, sample=docs_parent.result_image_samples ) ) @@ -50,7 +51,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode user""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = { 'image': None } diff --git a/plugins/modules/image_list.py b/plugins/modules/image_list.py index a0c1819b..d9bed6f2 100644 --- a/plugins/modules/image_list.py +++ b/plugins/modules/image_list.py @@ -8,6 +8,8 @@ # pylint: disable=unused-import from typing import Any, Optional, Dict +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue + from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ filter_null_values, construct_api_filter, get_all_paginated @@ -17,13 +19,13 @@ import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.image_list as docs spec_filter = dict( - name=dict(type='str', required=True, + name=SpecField(type=FieldType.string, required=True, description=[ 'The name of the field to filter on.', 'Valid filterable attributes can be found here: ' 'https://www.linode.com/docs/api/images/#images-list__responses', ]), - values=dict(type='list', elements='str', required=True, + values=SpecField(type=FieldType.list, element_type=FieldType.string, required=True, description=[ 'A list of values to allow for this field.', 'Fields will pass this filter if at least one of these values matches.' @@ -32,34 +34,34 @@ spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), - order=dict(type='str', description='The order to list events in.', + order=SpecField(type=FieldType.string, description=['The order to list events in.'], default='asc', choices=['desc', 'asc']), - order_by=dict(type='str', description='The attribute to order events by.'), - filters=dict(type='list', elements='dict', options=spec_filter, - description='A list of filters to apply to the resulting events.'), - count=dict(type='int', + order_by=SpecField(type=FieldType.string, description=['The attribute to order events by.']), + filters=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=spec_filter, + description=['A list of filters to apply to the resulting events.']), + count=SpecField(type=FieldType.integer, description=[ 'The number of results to return.', 'If undefined, all results will be returned.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'List and filter on Linode images.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - images=dict( + images=SpecReturnValue( description='The returned images.', docs_url='https://www.linode.com/docs/api/images/#images-list__response-samples', - type='list', - elements='dict', + type=FieldType.list, + elements=FieldType.dict, sample=docs.result_images_samples ) ) @@ -70,7 +72,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode images""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results: Dict[str, Any] = { 'images': [] } From b683ef92f49c232146a447b4005f47dbe7e634df Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 14:52:16 -0500 Subject: [PATCH 06/13] Fix --- docs/modules/instance.md | 513 ++++++++++++++++++++++++++++++++++++ plugins/modules/instance.py | 311 +++++++++++----------- 2 files changed, 668 insertions(+), 156 deletions(-) create mode 100644 docs/modules/instance.md diff --git a/docs/modules/instance.md b/docs/modules/instance.md new file mode 100644 index 00000000..5f9b526f --- /dev/null +++ b/docs/modules/instance.md @@ -0,0 +1,513 @@ +# instance + +Manage Linode Instances, Configs, and Disks. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- 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 +``` + +```yaml +- name: Create a Linode Instance with explicit configs and disks. + linode.cloud.instance: + label: 'my-complex-instance' + region: us-southeast + type: g6-standard-1 + booted: true + boot_config_label: boot-config + disks: + - label: boot + image: linode/ubuntu18.04 + size: 3000 + root_pass: ans1ble-test! + - label: swap + filesystem: swap + size: 512 + configs: + - label: boot-config + root_device: /dev/sda + devices: + sda: + disk_label: boot + sdb: + disk_label: swap + state: present +``` + +```yaml +- name: Delete a Linode instance. + linode.cloud.instance: + label: my-linode + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | +| `type` |
`str`
|
Optional
| The unique label to give this instance. | +| `region` |
`str`
|
Optional
| The location to deploy the instance in. See the [Linode API documentation](https://api.linode.com/v4/regions). | +| `image` |
`str`
|
Optional
| The image ID to deploy the instance disk from. | +| `authorized_keys` |
`list`
|
Optional
| A list of SSH public key parts to deploy for the root user. | +| `root_pass` |
`str`
|
Optional
| The password for the root user. If not specified, one will be generated. This generated password will be available in the task success JSON. | +| `stackscript_id` |
`int`
|
Optional
| The ID of the StackScript to use when creating the instance. See the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/). | +| `stackscript_data` |
`dict`
|
Optional
| 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 the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/). | +| `private_ip` |
`bool`
|
Optional
| If true, the created Linode will have private networking enabled. | +| `group` |
`str`
|
Optional
| 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. **(Updatable)** | +| `boot_config_label` |
`str`
|
Optional
| The label of the config to boot from. | +| [`configs` (sub-options)](#configs) |
`list`
|
Optional
| A list of Instance configs to apply to the Linode. See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/#configuration-profile-create). **(Updatable)** | +| [`disks` (sub-options)](#disks) |
`list`
|
Optional
| A list of Disks to create on the Linode. See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/#disk-create). **(Updatable)** | +| [`interfaces` (sub-options)](#interfaces) |
`list`
|
Optional
| A list of network interfaces to apply to the Linode. See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/#linode-create__request-body-schema). | +| `booted` |
`bool`
|
Optional
| Whether the new Instance should be booted. This will default to True if the Instance is deployed from an Image or Backup. | +| `backup_id` |
`int`
|
Optional
| The id of the Backup to restore to the new Instance. May not be provided if "image" is given. | +| `wait` |
`bool`
|
Optional
| Wait for the instance to have status "running" before returning. **(Default: `True`)** | +| `wait_timeout` |
`int`
|
Optional
| The amount of time, in seconds, to wait for an instance to have status "running". **(Default: `240`)** | + + + + + +### configs + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| [`devices` (sub-options)](#devices) |
`dict`
|
**Required**
| The devices to map to this configuration. | +| `label` |
`str`
|
**Required**
| The label to assign to this config. | +| `comments` |
`str`
|
Optional
| Arbitrary User comments on this Config. **(Updatable)** | +| [`helpers` (sub-options)](#helpers) |
`dict`
|
Optional
| Helpers enabled when booting to this Linode Config. | +| `kernel` |
`str`
|
Optional
| A Kernel ID to boot a Linode with. Defaults to "linode/latest-64bit". **(Updatable)** | +| `memory_limit` |
`int`
|
Optional
| Defaults to the total RAM of the Linode. **(Updatable)** | +| `root_device` |
`str`
|
Optional
| The root device to boot. **(Updatable)** | +| `run_level` |
`str`
|
Optional
| Defines the state of your Linode after booting. **(Updatable)** | +| `virt_mode` |
`str`
|
Optional
| Controls the virtualization mode. **(Choices: `paravirt`, `fullvirt`; Updatable)** | +| [`interfaces` (sub-options)](#interfaces) |
`list`
|
Optional
| A list of network interfaces to apply to the Linode. See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/#configuration-profile-create__request-body-schema). **(Updatable)** | + + + + + +### devices + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| [`sda` (sub-options)](#sda) |
`dict`
|
Optional
| The device to be mapped to /dev/sda | +| [`sdb` (sub-options)](#sdb) |
`dict`
|
Optional
| The device to be mapped to /dev/sdb | +| [`sdc` (sub-options)](#sdc) |
`dict`
|
Optional
| The device to be mapped to /dev/sdc | +| [`sdd` (sub-options)](#sdd) |
`dict`
|
Optional
| The device to be mapped to /dev/sdd | +| [`sde` (sub-options)](#sde) |
`dict`
|
Optional
| The device to be mapped to /dev/sde | +| [`sdf` (sub-options)](#sdf) |
`dict`
|
Optional
| The device to be mapped to /dev/sdf | +| [`sdg` (sub-options)](#sdg) |
`dict`
|
Optional
| The device to be mapped to /dev/sdg | +| [`sdh` (sub-options)](#sdh) |
`dict`
|
Optional
| The device to be mapped to /dev/sdh | + + + + + +### sda + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | +| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | +| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | + + + + + +### sdb + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | +| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | +| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | + + + + + +### sdc + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | +| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | +| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | + + + + + +### sdd + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | +| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | +| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | + + + + + +### sde + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | +| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | +| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | + + + + + +### sdf + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | +| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | +| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | + + + + + +### sdg + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | +| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | +| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | + + + + + +### sdh + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `disk_label` |
`str`
|
Optional
| The label of the disk to attach to this Linode. | +| `disk_id` |
`int`
|
Optional
| The ID of the disk to attach to this Linode. | +| `volume_id` |
`int`
|
Optional
| The ID of the volume to attach to this Linode. | + + + + + +### helpers + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `devtmpfs_automount` |
`bool`
|
Optional
| Populates the /dev directory early during boot without udev. | +| `distro` |
`bool`
|
Optional
| Helps maintain correct inittab/upstart console device. | +| `modules_dep` |
`bool`
|
Optional
| Creates a modules dependency file for the Kernel you run. | +| `network` |
`bool`
|
Optional
| Automatically configures static networking. | +| `updatedb_disabled` |
`bool`
|
Optional
| Disables updatedb cron job to avoid disk thrashing. | + + + + + +### interfaces + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `purpose` |
`str`
|
**Required**
| The type of interface. **(Choices: `public`, `vlan`)** | +| `label` |
`str`
|
Optional
| The name of this interface. Required for vlan purpose interfaces. Must be an empty string or null for public purpose interfaces. | +| `ipam_address` |
`str`
|
Optional
| This Network Interface’s private IP address in Classless Inter-Domain Routing (CIDR) notation. | + + + + + +### disks + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| The label to give this Disk. | +| `size` |
`int`
|
**Required**
| The size of the Disk in MB. **(Updatable)** | +| `authorized_keys` |
`list`
|
Optional
| A list of SSH public key parts to deploy for the root user. | +| `authorized_users` |
`list`
|
Optional
| A list of usernames. | +| `filesystem` |
`str`
|
Optional
| The filesystem to create this disk with. | +| `image` |
`str`
|
Optional
| An Image ID to deploy the Disk from. | +| `root_pass` |
`str`
|
Optional
| The root user’s password on the newly-created Linode. | +| `stackscript_id` |
`int`
|
Optional
| The ID of the StackScript to use when creating the instance. See the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/). | +| `stackscript_data` |
`dict`
|
Optional
| 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 the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/). | + + + + + + +## Return Values + +- `instance` - The instance description in JSON serialized form. + + - Sample Response: + ```json + { + "alerts": { + "cpu": 180, + "io": 10000, + "network_in": 10, + "network_out": 10, + "transfer_quota": 80 + }, + "backups": { + "enabled": true, + "last_successful": "2018-01-01T00:01:01", + "schedule": { + "day": "Saturday", + "window": "W22" + } + }, + "created": "2018-01-01T00:01:01", + "group": "Linode-Group", + "hypervisor": "kvm", + "id": 123, + "image": "linode/debian10", + "ipv4": [ + "203.0.113.1", + "192.0.2.1" + ], + "ipv6": "c001:d00d::1337/128", + "label": "linode123", + "region": "us-east", + "specs": { + "disk": 81920, + "memory": 4096, + "transfer": 4000, + "vcpus": 2 + }, + "status": "running", + "tags": [ + "example tag", + "another example" + ], + "type": "g6-standard-1", + "updated": "2018-01-01T00:01:01", + "watchdog_enabled": true + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#linode-view__responses) for a list of returned fields + + +- `configs` - A list of configs tied to this Linode Instance. + + - Sample Response: + ```json + [ + { + "comments": "This is my main Config", + "devices": { + "sda": { + "disk_id": 124458, + "volume_id": null + }, + "sdb": { + "disk_id": 124458, + "volume_id": null + }, + "sdc": { + "disk_id": 124458, + "volume_id": null + }, + "sdd": { + "disk_id": 124458, + "volume_id": null + }, + "sde": { + "disk_id": 124458, + "volume_id": null + }, + "sdf": { + "disk_id": 124458, + "volume_id": null + }, + "sdg": { + "disk_id": 124458, + "volume_id": null + }, + "sdh": { + "disk_id": 124458, + "volume_id": null + } + }, + "helpers": { + "devtmpfs_automount": false, + "distro": true, + "modules_dep": true, + "network": true, + "updatedb_disabled": true + }, + "id": 23456, + "interfaces": [ + { + "ipam_address": "10.0.0.1/24", + "label": "example-interface", + "purpose": "vlan" + } + ], + "kernel": "linode/latest-64bit", + "label": "My Config", + "memory_limit": 2048, + "root_device": "/dev/sda", + "run_level": "default", + "virt_mode": "paravirt" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#configuration-profile-view__responses) for a list of returned fields + + +- `disks` - A list of disks tied to this Linode Instance. + + - Sample Response: + ```json + [ + { + "created": "2018-01-01T00:01:01", + "filesystem": "ext4", + "id": 25674, + "label": "Debian 9 Disk", + "size": 48640, + "status": "ready", + "updated": "2018-01-01T00:01:01" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#disk-view__responses) for a list of returned fields + + +- `networking` - Networking information about this Linode Instance. + + - Sample Response: + ```json + + { + "ipv4": { + "private": [ + { + "address": "192.168.133.234", + "gateway": null, + "linode_id": 123, + "prefix": 17, + "public": false, + "rdns": null, + "region": "us-east", + "subnet_mask": "255.255.128.0", + "type": "ipv4" + } + ], + "public": [ + { + "address": "97.107.143.141", + "gateway": "97.107.143.1", + "linode_id": 123, + "prefix": 24, + "public": true, + "rdns": "test.example.org", + "region": "us-east", + "subnet_mask": "255.255.255.0", + "type": "ipv4" + } + ], + "reserved": [ + { + "address": "97.107.143.141", + "gateway": "97.107.143.1", + "linode_id": 123, + "prefix": 24, + "public": true, + "rdns": "test.example.org", + "region": "us-east", + "subnet_mask": "255.255.255.0", + "type": "ipv4" + } + ], + "shared": [ + { + "address": "97.107.143.141", + "gateway": "97.107.143.1", + "linode_id": 123, + "prefix": 24, + "public": true, + "rdns": "test.example.org", + "region": "us-east", + "subnet_mask": "255.255.255.0", + "type": "ipv4" + } + ] + }, + "ipv6": { + "global": { + "prefix": 124, + "range": "2600:3c01::2:5000:0", + "region": "us-east", + "route_target": "2600:3c01::2:5000:f" + }, + "link_local": { + "address": "fe80::f03c:91ff:fe24:3a2f", + "gateway": "fe80::1", + "linode_id": 123, + "prefix": 64, + "public": false, + "rdns": null, + "region": "us-east", + "subnet_mask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff", + "type": "ipv6" + }, + "slaac": { + "address": "2600:3c03::f03c:91ff:fe24:3a2f", + "gateway": "fe80::1", + "linode_id": 123, + "prefix": 64, + "public": true, + "rdns": null, + "region": "us-east", + "subnet_mask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff", + "type": "ipv6" + } + } + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#networking-information-list__responses) for a list of returned fields + + diff --git a/plugins/modules/instance.py b/plugins/modules/instance.py index f87ac0a2..37d20436 100644 --- a/plugins/modules/instance.py +++ b/plugins/modules/instance.py @@ -10,6 +10,7 @@ from typing import Optional, Any, cast, Set, List, Dict, Union import linode_api4 import polling +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from ansible_collections.linode.cloud.plugins.module_utils.linode_common import \ LinodeModuleBase @@ -28,43 +29,43 @@ pass linode_instance_disk_spec = dict( - authorized_keys=dict( - type='list', elements='str', - description='A list of SSH public key parts to deploy for the root user.'), + authorized_keys=SpecField( + type=FieldType.list, element_type=FieldType.string, + description=['A list of SSH public key parts to deploy for the root user.']), - authorized_users=dict( - type='list', elements='str', - description='A list of usernames.'), + authorized_users=SpecField( + type=FieldType.list, element_type=FieldType.string, + description=['A list of usernames.']), - filesystem=dict( - type='str', - description='The filesystem to create this disk with.'), + filesystem=SpecField( + type=FieldType.string, + description=['The filesystem to create this disk with.']), - image=dict( - type='str', - description='An Image ID to deploy the Disk from.'), + image=SpecField( + type=FieldType.string, + description=['An Image ID to deploy the Disk from.']), - label=dict( - type='str', required=True, - description='The label to give this Disk.'), + label=SpecField( + type=FieldType.string, required=True, + description=['The label to give this Disk.']), - root_pass=dict( - type='str', - description='The root user’s password on the newly-created Linode.'), + root_pass=SpecField( + type=FieldType.string, + description=['The root user’s password on the newly-created Linode.']), - size=dict( - type='int', required=True, editable=True, - description='The size of the Disk in MB.'), + size=SpecField( + type=FieldType.integer, required=True, editable=True, + description=['The size of the Disk in MB.']), - stackscript_id=dict( - type='int', + stackscript_id=SpecField( + type=FieldType.integer, description=[ 'The ID of the StackScript to use when creating the instance.', 'See the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/).' ]), - stackscript_data=dict( - type='dict', + stackscript_data=SpecField( + type=FieldType.dict, description=[ 'An object containing arguments to any User Defined Fields present in ' 'the StackScript used when creating the instance.', @@ -74,118 +75,114 @@ ) linode_instance_device_spec = dict( - disk_label=dict( - type='str', - description='The label of the disk to attach to this Linode.'), + disk_label=SpecField( + type=FieldType.string, + description=['The label of the disk to attach to this Linode.']), - disk_id=dict( - type='int', - description='The ID of the disk to attach to this Linode.'), + disk_id=SpecField( + type=FieldType.integer, + description=['The ID of the disk to attach to this Linode.']), - volume_id=dict( - type='int', - description='The ID of the volume to attach to this Linode.') + volume_id=SpecField( + type=FieldType.integer, + description=['The ID of the volume to attach to this Linode.']) ) -linode_instance_devices_spec = dict( - sda=dict(type='dict', options=linode_instance_device_spec), - sdb=dict(type='dict', options=linode_instance_device_spec), - sdc=dict(type='dict', options=linode_instance_device_spec), - sdd=dict(type='dict', options=linode_instance_device_spec), - sde=dict(type='dict', options=linode_instance_device_spec), - sdf=dict(type='dict', options=linode_instance_device_spec), - sdg=dict(type='dict', options=linode_instance_device_spec), - sdh=dict(type='dict', options=linode_instance_device_spec), -) +linode_instance_devices_spec = { + f'sd{k}': SpecField( + type=FieldType.dict, + description=[f'The device to be mapped to /dev/sd{k}'], + suboptions=linode_instance_device_spec) for k in 'abcdefgh' +} linode_instance_helpers_spec = dict( - devtmpfs_automount=dict( - type='bool', - description='Populates the /dev directory early during boot without udev.'), + devtmpfs_automount=SpecField( + type=FieldType.bool, + description=['Populates the /dev directory early during boot without udev.']), - distro=dict( - type='bool', - description='Helps maintain correct inittab/upstart console device.'), + distro=SpecField( + type=FieldType.bool, + description=['Helps maintain correct inittab/upstart console device.']), - modules_dep=dict( - type='bool', - description='Creates a modules dependency file for the Kernel you run.'), + modules_dep=SpecField( + type=FieldType.bool, + description=['Creates a modules dependency file for the Kernel you run.']), - network=dict( - type='bool', - description='Automatically configures static networking.'), + network=SpecField( + type=FieldType.bool, + description=['Automatically configures static networking.']), - updatedb_disabled=dict( - type='bool', - description='Disables updatedb cron job to avoid disk thrashing.') + updatedb_disabled=SpecField( + type=FieldType.bool, + description=['Disables updatedb cron job to avoid disk thrashing.']) ) linode_instance_interface_spec = dict( - purpose=dict( - type='str', required=True, - description='The type of interface.', + purpose=SpecField( + type=FieldType.string, required=True, + description=['The type of interface.'], choices=[ 'public', 'vlan' ]), - label=dict( - type='str', + label=SpecField( + type=FieldType.string, description=[ 'The name of this interface.', 'Required for vlan purpose interfaces.', 'Must be an empty string or null for public purpose interfaces.' ]), - ipam_address=dict( - type='str', - description='This Network Interface’s private IP address in Classless ' - 'Inter-Domain Routing (CIDR) notation.' + ipam_address=SpecField( + type=FieldType.string, + description=['This Network Interface’s private IP address in Classless ' + 'Inter-Domain Routing (CIDR) notation.'] ) ) linode_instance_config_spec = dict( - comments=dict( - type='str', editable=True, - description='Arbitrary User comments on this Config.'), + comments=SpecField( + type=FieldType.string, editable=True, + description=['Arbitrary User comments on this Config.']), - devices=dict( - type='dict', required=True, options=linode_instance_devices_spec, - description='The devices to map to this configuration.'), + devices=SpecField( + type=FieldType.dict, required=True, suboptions=linode_instance_devices_spec, + description=['The devices to map to this configuration.']), - helpers=dict( - type='dict', options=linode_instance_helpers_spec, - description='Helpers enabled when booting to this Linode Config.'), + helpers=SpecField( + type=FieldType.dict, suboptions=linode_instance_helpers_spec, + description=['Helpers enabled when booting to this Linode Config.']), - kernel=dict( - type='str', editable=True, - description='A Kernel ID to boot a Linode with. Defaults to “linode/latest-64bit”.'), + kernel=SpecField( + type=FieldType.string, editable=True, + description=['A Kernel ID to boot a Linode with. Defaults to "linode/latest-64bit".']), - label=dict( - type='str', required=True, - description='The label to assign to this config.'), + label=SpecField( + type=FieldType.string, required=True, + description=['The label to assign to this config.']), - memory_limit=dict( - type='int', editable=True, - description='Defaults to the total RAM of the Linode.'), + memory_limit=SpecField( + type=FieldType.integer, editable=True, + description=['Defaults to the total RAM of the Linode.']), - root_device=dict( - type='str', editable=True, - description='The root device to boot.'), + root_device=SpecField( + type=FieldType.string, editable=True, + description=['The root device to boot.']), - run_level=dict( - type='str', editable=True, - description='Defines the state of your Linode after booting.'), + run_level=SpecField( + type=FieldType.string, editable=True, + description=['Defines the state of your Linode after booting.']), - virt_mode=dict( - type='str', editable=True, - description='Controls the virtualization mode.', + virt_mode=SpecField( + type=FieldType.string, editable=True, + description=['Controls the virtualization mode.'], choices=[ 'paravirt', 'fullvirt' ]), - interfaces=dict( - type='list', elements='dict', options=linode_instance_interface_spec, + interfaces=SpecField( + type=FieldType.list, element_type=FieldType.dict, suboptions=linode_instance_interface_spec, editable=True, description=[ 'A list of network interfaces to apply to the Linode.', @@ -195,38 +192,38 @@ ) linode_instance_spec = dict( - type=dict(type='str', description=['The unique label to give this instance.']), - region=dict( - type='str', + type=SpecField(type=FieldType.string, description=['The unique label to give this instance.']), + region=SpecField( + type=FieldType.string, description=[ 'The location to deploy the instance in.', 'See the [Linode API documentation](https://api.linode.com/v4/regions).']), - image=dict( - type='str', - description='The image ID to deploy the instance disk from.'), + image=SpecField( + type=FieldType.string, + description=['The image ID to deploy the instance disk from.']), - authorized_keys=dict( - type='list', elements='str', - description='A list of SSH public key parts to deploy for the root user.'), + authorized_keys=SpecField( + type=FieldType.list, element_type=FieldType.string, + description=['A list of SSH public key parts to deploy for the root user.']), - root_pass=dict( - type='str', no_log=True, + root_pass=SpecField( + type=FieldType.string, no_log=True, 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.' ]), - stackscript_id=dict( - type='int', + stackscript_id=SpecField( + type=FieldType.integer, description=[ 'The ID of the StackScript to use when creating the instance.', 'See the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/).' ]), - stackscript_data=dict( - type='dict', + stackscript_data=SpecField( + type=FieldType.dict, description=[ 'An object containing arguments to any User Defined Fields present in ' 'the StackScript used when creating the instance.', @@ -234,25 +231,27 @@ 'See the [Linode API documentation](https://www.linode.com/docs/api/stackscripts/).' ]), - state=dict(type='str', - description='The desired state of the target.', - choices=['present', 'absent'], required=True), + state=SpecField(type=FieldType.string, + description=['The desired state of the target.'], + choices=['present', 'absent'], required=True), - private_ip=dict( - type='bool', - description='If true, the created Linode will have private networking enabled.'), + private_ip=SpecField( + type=FieldType.bool, + description=['If true, the created Linode will have private networking enabled.']), - group=dict( - type='str', editable=True, + group=SpecField( + type=FieldType.string, editable=True, description=[ '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.']), - boot_config_label=dict(type='str', description='The label of the config to boot from.'), + boot_config_label=SpecField( + type=FieldType.string, + description=['The label of the config to boot from.']), - configs=dict( - type='list', elements='dict', options=linode_instance_config_spec, + configs=SpecField( + type=FieldType.list, element_type=FieldType.dict, suboptions=linode_instance_config_spec, editable=True, description=[ 'A list of Instance configs to apply to the Linode.', @@ -260,8 +259,8 @@ '/api/linode-instances/#configuration-profile-create).' ]), - disks=dict( - type='list', elements='dict', options=linode_instance_disk_spec, + disks=SpecField( + type=FieldType.list, element_type=FieldType.dict, suboptions=linode_instance_disk_spec, editable=True, description=[ 'A list of Disks to create on the Linode.', @@ -269,71 +268,71 @@ 'docs/api/linode-instances/#disk-create).' ]), - interfaces=dict( - type='list', elements='dict', options=linode_instance_interface_spec, + interfaces=SpecField( + type=FieldType.list, element_type=FieldType.dict, suboptions=linode_instance_interface_spec, description=[ 'A list of network interfaces to apply to the Linode.', 'See the [Linode API documentation](https://www.linode.com/docs/api/linode-instances/' '#linode-create__request-body-schema).' ]), - booted=dict( - type='bool', + booted=SpecField( + type=FieldType.bool, description=[ 'Whether the new Instance should be booted.', 'This will default to True if the Instance is deployed from an Image or Backup.' ]), - backup_id=dict( - type='int', + backup_id=SpecField( + type=FieldType.integer, description=[ 'The id of the Backup to restore to the new Instance.', - 'May not be provided if “image” is given.']), + 'May not be provided if "image" is given.']), - wait=dict( - type='bool', default=True, - description='Wait for the instance to have status `running` before returning.'), + wait=SpecField( + type=FieldType.bool, default=True, + description=['Wait for the instance to have status "running" before returning.']), - wait_timeout=dict( - type='int', default=240, - description='The amount of time, in seconds, to wait for an instance to ' - 'have status `running`.' - ) + wait_timeout=SpecField( + type=FieldType.integer, default=240, + description=['The amount of time, in seconds, to wait for an instance to ' + 'have status "running".'] + ) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage Linode Instances, Configs, and Disks.' ], requirements=global_requirements, author=global_authors, - spec=linode_instance_spec, + options=linode_instance_spec, examples=docs.specdoc_examples, return_values=dict( - instance=dict( - description=['The instance description in JSON serialized form.'], + instance=SpecReturnValue( + description='The instance description in JSON serialized form.', docs_url='https://www.linode.com/docs/api/linode-instances/#linode-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_instance_samples ), - configs=dict( - description=['A list of configs tied to this Linode Instance.'], + configs=SpecReturnValue( + description='A list of configs tied to this Linode Instance.', docs_url='https://www.linode.com/docs/api/linode-instances/' '#configuration-profile-view__responses', - type='list', + type=FieldType.list, sample=docs.result_configs_samples ), - disks=dict( - description=['A list of disks tied to this Linode Instance.'], + disks=SpecReturnValue( + description='A list of disks tied to this Linode Instance.', docs_url='https://www.linode.com/docs/api/linode-instances/#disk-view__responses', - type='list', + type=FieldType.list, sample=docs.result_disks_samples ), - networking=dict( - description=['Networking information about this Linode Instance.'], + networking=SpecReturnValue( + description='Networking information about this Linode Instance.', docs_url='https://www.linode.com/docs/api/linode-instances/' '#networking-information-list__responses', - type='dict', + type=FieldType.dict, sample=docs.result_networking_samples ) ) @@ -360,7 +359,7 @@ class LinodeInstance(LinodeModuleBase): """Module for creating and destroying Linode Instances""" def __init__(self) -> None: - self.module_arg_spec = linode_instance_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.mutually_exclusive = [ ('image', 'disks'), @@ -748,7 +747,7 @@ def _update_instance(self) -> None: self.fail( 'failed to update instance {0}: {1} is a non-updatable field' - .format(self._instance.label, key)) + .format(self._instance.label, key)) if should_update: self._instance.save() From 30c1b5c9a626db1a4b1eba4fde5a9c4ac46ae522 Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 15:15:31 -0500 Subject: [PATCH 07/13] progress --- docs/modules/instance_info.md | 279 ++++++++++++++++++++++++++++ docs/modules/ip_info.md | 58 ++++++ docs/modules/ipv6_range_info.md | 56 ++++++ docs/modules/lke_cluster.md | 170 +++++++++++++++++ docs/modules/lke_cluster_info.md | 115 ++++++++++++ docs/modules/lke_node_pool.md | 132 +++++++++++++ plugins/modules/instance_info.py | 41 ++-- plugins/modules/ip_info.py | 19 +- plugins/modules/ipv6_range_info.py | 17 +- plugins/modules/lke_cluster.py | 135 +++++++------- plugins/modules/lke_cluster_info.py | 41 ++-- plugins/modules/lke_node_pool.py | 113 ++++++----- 12 files changed, 993 insertions(+), 183 deletions(-) create mode 100644 docs/modules/instance_info.md create mode 100644 docs/modules/ip_info.md create mode 100644 docs/modules/ipv6_range_info.md create mode 100644 docs/modules/lke_cluster.md create mode 100644 docs/modules/lke_cluster_info.md create mode 100644 docs/modules/lke_node_pool.md diff --git a/docs/modules/instance_info.md b/docs/modules/instance_info.md new file mode 100644 index 00000000..fc5cc6cf --- /dev/null +++ b/docs/modules/instance_info.md @@ -0,0 +1,279 @@ +# instance_info + +Get info about a Linode Instance. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about an instance by label + linode.cloud.instance_info: + label: 'my-instance' +``` + +```yaml +- name: Get info about an instance by id + linode.cloud.instance_info: + id: 12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`int`
|
Optional
| The instance’s label. Optional if `label` is defined. | +| `label` |
`str`
|
Optional
| The unique ID of the Instance. Optional if `id` is defined. | + + + + + + +## Return Values + +- `instance` - The instance description in JSON serialized form. + + - Sample Response: + ```json + { + "alerts": { + "cpu": 180, + "io": 10000, + "network_in": 10, + "network_out": 10, + "transfer_quota": 80 + }, + "backups": { + "enabled": true, + "last_successful": "2018-01-01T00:01:01", + "schedule": { + "day": "Saturday", + "window": "W22" + } + }, + "created": "2018-01-01T00:01:01", + "group": "Linode-Group", + "hypervisor": "kvm", + "id": 123, + "image": "linode/debian10", + "ipv4": [ + "203.0.113.1", + "192.0.2.1" + ], + "ipv6": "c001:d00d::1337/128", + "label": "linode123", + "region": "us-east", + "specs": { + "disk": 81920, + "memory": 4096, + "transfer": 4000, + "vcpus": 2 + }, + "status": "running", + "tags": [ + "example tag", + "another example" + ], + "type": "g6-standard-1", + "updated": "2018-01-01T00:01:01", + "watchdog_enabled": true + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#linode-view__responses) for a list of returned fields + + +- `configs` - A list of configs tied to this Linode Instance. + + - Sample Response: + ```json + [ + { + "comments": "This is my main Config", + "devices": { + "sda": { + "disk_id": 124458, + "volume_id": null + }, + "sdb": { + "disk_id": 124458, + "volume_id": null + }, + "sdc": { + "disk_id": 124458, + "volume_id": null + }, + "sdd": { + "disk_id": 124458, + "volume_id": null + }, + "sde": { + "disk_id": 124458, + "volume_id": null + }, + "sdf": { + "disk_id": 124458, + "volume_id": null + }, + "sdg": { + "disk_id": 124458, + "volume_id": null + }, + "sdh": { + "disk_id": 124458, + "volume_id": null + } + }, + "helpers": { + "devtmpfs_automount": false, + "distro": true, + "modules_dep": true, + "network": true, + "updatedb_disabled": true + }, + "id": 23456, + "interfaces": [ + { + "ipam_address": "10.0.0.1/24", + "label": "example-interface", + "purpose": "vlan" + } + ], + "kernel": "linode/latest-64bit", + "label": "My Config", + "memory_limit": 2048, + "root_device": "/dev/sda", + "run_level": "default", + "virt_mode": "paravirt" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#configuration-profile-view__responses) for a list of returned fields + + +- `disks` - A list of disks tied to this Linode Instance. + + - Sample Response: + ```json + [ + { + "created": "2018-01-01T00:01:01", + "filesystem": "ext4", + "id": 25674, + "label": "Debian 9 Disk", + "size": 48640, + "status": "ready", + "updated": "2018-01-01T00:01:01" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#disk-view__responses) for a list of returned fields + + +- `networking` - Networking information about this Linode Instance. + + - Sample Response: + ```json + + { + "ipv4": { + "private": [ + { + "address": "192.168.133.234", + "gateway": null, + "linode_id": 123, + "prefix": 17, + "public": false, + "rdns": null, + "region": "us-east", + "subnet_mask": "255.255.128.0", + "type": "ipv4" + } + ], + "public": [ + { + "address": "97.107.143.141", + "gateway": "97.107.143.1", + "linode_id": 123, + "prefix": 24, + "public": true, + "rdns": "test.example.org", + "region": "us-east", + "subnet_mask": "255.255.255.0", + "type": "ipv4" + } + ], + "reserved": [ + { + "address": "97.107.143.141", + "gateway": "97.107.143.1", + "linode_id": 123, + "prefix": 24, + "public": true, + "rdns": "test.example.org", + "region": "us-east", + "subnet_mask": "255.255.255.0", + "type": "ipv4" + } + ], + "shared": [ + { + "address": "97.107.143.141", + "gateway": "97.107.143.1", + "linode_id": 123, + "prefix": 24, + "public": true, + "rdns": "test.example.org", + "region": "us-east", + "subnet_mask": "255.255.255.0", + "type": "ipv4" + } + ] + }, + "ipv6": { + "global": { + "prefix": 124, + "range": "2600:3c01::2:5000:0", + "region": "us-east", + "route_target": "2600:3c01::2:5000:f" + }, + "link_local": { + "address": "fe80::f03c:91ff:fe24:3a2f", + "gateway": "fe80::1", + "linode_id": 123, + "prefix": 64, + "public": false, + "rdns": null, + "region": "us-east", + "subnet_mask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff", + "type": "ipv6" + }, + "slaac": { + "address": "2600:3c03::f03c:91ff:fe24:3a2f", + "gateway": "fe80::1", + "linode_id": 123, + "prefix": 64, + "public": true, + "rdns": null, + "region": "us-east", + "subnet_mask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff", + "type": "ipv6" + } + } + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-instances/#networking-information-list__responses) for a list of returned fields + + diff --git a/docs/modules/ip_info.md b/docs/modules/ip_info.md new file mode 100644 index 00000000..b91d29be --- /dev/null +++ b/docs/modules/ip_info.md @@ -0,0 +1,58 @@ +# ip_info + +Get info about a Linode IP. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about an IP address + linode.cloud.ip_info: + address: 97.107.143.141 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `address` |
`str`
|
**Required**
| The IP address to operate on. | + + + + + + +## Return Values + +- `ip` - The IP in JSON serialized form. + + - Sample Response: + ```json + { + "address": "97.107.143.141", + "gateway": "97.107.143.1", + "linode_id": 123, + "prefix": 24, + "public": true, + "rdns": "test.example.org", + "region": "us-east", + "subnet_mask": "255.255.255.0", + "type": "ipv4" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#ip-address-view__responses) for a list of returned fields + + diff --git a/docs/modules/ipv6_range_info.md b/docs/modules/ipv6_range_info.md new file mode 100644 index 00000000..5c8f37d2 --- /dev/null +++ b/docs/modules/ipv6_range_info.md @@ -0,0 +1,56 @@ +# ipv6_range_info + +Get info about a Linode IPv6 range. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about an IPv6 range + linode.cloud.ipv6_range_info: + range: 2600:3c01:: +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `range` |
`str`
|
Optional
| The IPv6 range to access. | + + + + + + +## Return Values + +- `range` - The IPv6 range in JSON serialized form. + + - Sample Response: + ```json + { + "is_bgp": false, + "linodes": [ + 123 + ], + "prefix": 64, + "range": "2600:3c01::", + "region": "us-east" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#ipv6-range-view__response-samples) for a list of returned fields + + diff --git a/docs/modules/lke_cluster.md b/docs/modules/lke_cluster.md new file mode 100644 index 00000000..2bdafb50 --- /dev/null +++ b/docs/modules/lke_cluster.md @@ -0,0 +1,170 @@ +# lke_cluster + +Manage Linode LKE clusters. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a Linode LKE cluster + linode.cloud.lke_cluster: + label: 'my-cluster' + region: us-southeast + k8s_version: 1.23 + node_pools: + - type: g6-standard-1 + count: 3 + - type: g6-standard-2 + count: 2 + state: present +``` + +```yaml +- name: Create a Linode LKE cluster with autoscaler + linode.cloud.lke_cluster: + label: 'my-cluster' + region: us-southeast + k8s_version: 1.23 + node_pools: + - type: g6-standard-1 + count: 2 + autoscaler: + enable: true + min: 2 + max: 5 + state: present +``` + +```yaml +- name: Delete a Linode LKE cluster + linode.cloud.lke_cluster: + label: 'my-cluster' + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| This Kubernetes cluster’s unique label. | +| `k8s_version` |
`str`
|
Optional
| The desired Kubernetes version for this Kubernetes cluster in the format of ., and the latest supported patch version will be deployed. A version upgrade requires that you manually recycle the nodes in your cluster. **(Updatable)** | +| `region` |
`str`
|
Optional
| This Kubernetes cluster’s location. | +| `tags` |
`list`
|
Optional
| An array of tags applied to the Kubernetes cluster. | +| `high_availability` |
`bool`
|
Optional
| Defines whether High Availability is enabled for the Control Plane Components of the cluster. **(Default: `False`; Updatable)** | +| [`node_pools` (sub-options)](#node_pools) |
`list`
|
Optional
| A list of node pools to configure the cluster with **(Updatable)** | +| `skip_polling` |
`bool`
|
Optional
| If true, the module will not wait for all nodes in the cluster to be ready. **(Default: `False`)** | +| `wait_timeout` |
`int`
|
Optional
| The period to wait for the cluster to be ready in seconds. **(Default: `600`)** | + + + + + +### node_pools + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `count` |
`int`
|
**Required**
| The number of nodes in the Node Pool. **(Updatable)** | +| `type` |
`str`
|
**Required**
| The Linode Type for all of the nodes in the Node Pool. | +| [`autoscaler` (sub-options)](#autoscaler) |
`dict`
|
Optional
| When enabled, the number of nodes autoscales within the defined minimum and maximum values. **(Updatable)** | + + + + + +### autoscaler + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `enabled` |
`bool`
|
Optional
| Whether autoscaling is enabled for this Node Pool. NOTE: Subsequent playbook runs will override nodes created by the cluster autoscaler. **(Updatable)** | +| `max` |
`int`
|
Optional
| The maximum number of nodes to autoscale to. Defaults to the value provided by the count field. **(Updatable)** | +| `min` |
`int`
|
Optional
| The minimum number of nodes to autoscale to. Defaults to the Node Pool’s count. **(Updatable)** | + + + + + + +## Return Values + +- `cluster` - The LKE cluster in JSON serialized form. + + - Sample Response: + ```json + { + "control_plane": { + "high_availability": true + }, + "created": "2019-09-12T21:25:30Z", + "id": 1234, + "k8s_version": "1.23", + "label": "lkecluster12345", + "region": "us-central", + "tags": [ + "ecomm", + "blogs" + ], + "updated": "2019-09-13T21:24:16Z" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-cluster-view__response-samples) for a list of returned fields + + +- `node_pools` - A list of node pools in JSON serialized form. + + - Sample Response: + ```json + [ + { + "autoscaler": { + "enabled": true, + "max": 12, + "min": 3 + }, + "count": 6, + "disks": [ + { + "size": 1024, + "type": "ext-4" + } + ], + "id": 456, + "nodes": [ + { + "id": "123456", + "instance_id": 123458, + "status": "ready" + } + ], + "tags": [ + "example tag", + "another example" + ], + "type": "g6-standard-4" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#node-pools-list__response-samples) for a list of returned fields + + +- `kubeconfig` - The Base64-encoded kubeconfig used to access this cluster. +NOTE: This value may be unavailable if `skip_polling` is true. + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubeconfig-view__responses) for a list of returned fields + + +- `dashboard_url` - The Cluster Dashboard access URL. + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-cluster-dashboard-url-view__responses) for a list of returned fields + + diff --git a/docs/modules/lke_cluster_info.md b/docs/modules/lke_cluster_info.md new file mode 100644 index 00000000..63c8d71f --- /dev/null +++ b/docs/modules/lke_cluster_info.md @@ -0,0 +1,115 @@ +# lke_cluster_info + +Get info about a Linode LKE cluster. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about an LKE cluster by label + linode.cloud.lke_cluster_info: + label: 'my-cluster' +``` + +```yaml +- name: Get info about an LKE cluster by ID + linode.cloud.lke_cluster_info: + id: 12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`int`
|
Optional
| The ID of the LKE cluster. Optional if `label` is defined. | +| `label` |
`str`
|
Optional
| The label of the LKE cluster. Optional if `id` is defined. | + + + + + + +## Return Values + +- `cluster` - The LKE cluster in JSON serialized form. + + - Sample Response: + ```json + { + "control_plane": { + "high_availability": true + }, + "created": "2019-09-12T21:25:30Z", + "id": 1234, + "k8s_version": "1.23", + "label": "lkecluster12345", + "region": "us-central", + "tags": [ + "ecomm", + "blogs" + ], + "updated": "2019-09-13T21:24:16Z" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-cluster-view__response-samples) for a list of returned fields + + +- `node_pools` - A list of node pools in JSON serialized form. + + - Sample Response: + ```json + [ + { + "autoscaler": { + "enabled": true, + "max": 12, + "min": 3 + }, + "count": 6, + "disks": [ + { + "size": 1024, + "type": "ext-4" + } + ], + "id": 456, + "nodes": [ + { + "id": "123456", + "instance_id": 123458, + "status": "ready" + } + ], + "tags": [ + "example tag", + "another example" + ], + "type": "g6-standard-4" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#node-pools-list__response-samples) for a list of returned fields + + +- `kubeconfig` - The Base64-encoded kubeconfig used to access this cluster. +NOTE: This value may be unavailable if the cluster is not fully provisioned. + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubeconfig-view__responses) for a list of returned fields + + +- `dashboard_url` - The Cluster Dashboard access URL. + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#kubernetes-cluster-dashboard-url-view__responses) for a list of returned fields + + diff --git a/docs/modules/lke_node_pool.md b/docs/modules/lke_node_pool.md new file mode 100644 index 00000000..5ae7aa99 --- /dev/null +++ b/docs/modules/lke_node_pool.md @@ -0,0 +1,132 @@ +# lke_node_pool + +Manage Linode LKE cluster node pools. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a Linode LKE node pool + linode.cloud.lke_node_pool: + cluster_id: 12345 + + tags: ['my-pool'] + count: 3 + type: g6-standard-2 + state: present +``` + +```yaml +- name: Create a Linode LKE node pool with autoscaler + linode.cloud.lke_node_pool: + cluster_id: 12345 + + tags: ['my-pool'] + count: 3 + type: g6-standard-2 + + autoscaler: + enabled: true + min: 1 + max: 3 + + state: present +- name: Delete a Linode LKE node pool + linode.cloud.lke_node_pool: + cluster_id: 12345 + tags: ['my-pool'] + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `cluster_id` |
`int`
|
**Required**
| The ID of the LKE cluster that contains this node pool. | +| `tags` |
`list`
|
**Required**
| An array of tags applied to this object. Tags must be unique as they are used by the `lke_node_pool` module to uniquely identify node pools. **(Updatable)** | +| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | +| [`autoscaler` (sub-options)](#autoscaler) |
`dict`
|
Optional
| When enabled, the number of nodes autoscales within the defined minimum and maximum values. **(Updatable)** | +| `count` |
`int`
|
Optional
| The number of nodes in the Node Pool. **(Updatable)** | +| [`disks` (sub-options)](#disks) |
`list`
|
Optional
| This Node Pool’s custom disk layout. Each item in this array will create a new disk partition for each node in this Node Pool. | +| `type` |
`str`
|
Optional
| The Linode Type for all of the nodes in the Node Pool. Required if `state` == `present`. | +| `skip_polling` |
`bool`
|
Optional
| If true, the module will not wait for all nodes in the node pool to be ready. **(Default: `False`)** | +| `wait_timeout` |
`int`
|
Optional
| The period to wait for the node pool to be ready in seconds. **(Default: `600`)** | + + + + + +### autoscaler + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `enabled` |
`bool`
|
Optional
| Whether autoscaling is enabled for this Node Pool. NOTE: Subsequent playbook runs will override nodes created by the cluster autoscaler. **(Updatable)** | +| `max` |
`int`
|
Optional
| The maximum number of nodes to autoscale to. Defaults to the value provided by the count field. **(Updatable)** | +| `min` |
`int`
|
Optional
| The minimum number of nodes to autoscale to. Defaults to the Node Pool’s count. **(Updatable)** | + + + + + +### disks + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `type` |
`str`
|
**Required**
| This custom disk partition’s filesystem type. **(Choices: `raw`, `ext4`)** | +| `size` |
`int`
|
**Required**
| The size of this custom disk partition in MB. | + + + + + + +## Return Values + +- `node_pool` - The Node Pool in JSON serialized form. + + - Sample Response: + ```json + { + "autoscaler": { + "enabled": true, + "max": 12, + "min": 3 + }, + "count": 6, + "disks": [ + { + "size": 1024, + "type": "ext-4" + } + ], + "id": 456, + "nodes": [ + { + "id": "123456", + "instance_id": 123458, + "status": "ready" + } + ], + "tags": [ + "example tag", + "another example" + ], + "type": "g6-standard-4" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-kubernetes-engine-lke/#node-pool-view__response-samples) for a list of returned fields + + diff --git a/plugins/modules/instance_info.py b/plugins/modules/instance_info.py index d2869f01..a371383d 100644 --- a/plugins/modules/instance_info.py +++ b/plugins/modules/instance_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Optional, Any, Dict +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Instance from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -21,56 +22,56 @@ linode_instance_info_spec = dict( # We need to overwrite attributes to exclude them as requirements - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict( - type='int', required=False, + id=SpecField( + type=FieldType.integer, required=False, description=[ 'The instance’s label.', 'Optional if `label` is defined.' ]), - label=dict( - type='str', required=False, + label=SpecField( + type=FieldType.string, required=False, description=[ 'The unique ID of the Instance.', 'Optional if `id` is defined.' ]) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode Instance.' ], requirements=global_requirements, author=global_authors, - spec=linode_instance_info_spec, + options=linode_instance_info_spec, examples=docs.specdoc_examples, return_values=dict( - instance=dict( - description=['The instance description in JSON serialized form.'], + instance=SpecReturnValue( + description='The instance description in JSON serialized form.', docs_url='https://www.linode.com/docs/api/linode-instances/#linode-view__responses', - type='dict', + type=FieldType.dict, sample=docs_parent.result_instance_samples ), - configs=dict( - description=['A list of configs tied to this Linode Instance.'], + configs=SpecReturnValue( + description='A list of configs tied to this Linode Instance.', docs_url='https://www.linode.com/docs/api/linode-instances/' '#configuration-profile-view__responses', - type='list', + type=FieldType.list, sample=docs_parent.result_configs_samples ), - disks=dict( - description=['A list of disks tied to this Linode Instance.'], + disks=SpecReturnValue( + description='A list of disks tied to this Linode Instance.', docs_url='https://www.linode.com/docs/api/linode-instances/#disk-view__responses', - type='list', + type=FieldType.list, sample=docs_parent.result_disks_samples ), - networking=dict( - description=['Networking information about this Linode Instance.'], + networking=SpecReturnValue( + description='Networking information about this Linode Instance.', docs_url='https://www.linode.com/docs/api/linode-instances/' '#networking-information-list__responses', - type='dict', + type=FieldType.dict, sample=docs_parent.result_networking_samples ) ) @@ -85,7 +86,7 @@ class LinodeInstanceInfo(LinodeModuleBase): """Module for getting info about a Linode Instance""" def __init__(self) -> None: - self.module_arg_spec = linode_instance_info_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results: Dict[str, Any] = dict( instance=None, diff --git a/plugins/modules/ip_info.py b/plugins/modules/ip_info.py index 457d4386..972d0f43 100644 --- a/plugins/modules/ip_info.py +++ b/plugins/modules/ip_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Image, IPAddress from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -20,26 +21,26 @@ spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), - address=dict(type='str', required=True, - description='The IP address to operate on.'), + address=SpecField(type=FieldType.string, required=True, + description=['The IP address to operate on.']), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode IP.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - ip=dict( + ip=SpecReturnValue( description='The IP in JSON serialized form.', docs_url='https://www.linode.com/docs/api/networking/#ip-address-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_ip_samples ) ) @@ -50,7 +51,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode user""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = { 'ip': None } diff --git a/plugins/modules/ipv6_range_info.py b/plugins/modules/ipv6_range_info.py index fc201e97..54f3ddf2 100644 --- a/plugins/modules/ipv6_range_info.py +++ b/plugins/modules/ipv6_range_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecReturnValue, SpecDocMeta from linode_api4 import IPv6Range from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -19,26 +20,26 @@ spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), - range=dict(type='str', description='The IPv6 range to access.'), + range=SpecField(type=FieldType.string, description=['The IPv6 range to access.']), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode IPv6 range.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - range=dict( + range=SpecReturnValue( description='The IPv6 range in JSON serialized form.', docs_url='https://www.linode.com/docs/api/networking/' '#ipv6-range-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_range_samples ) ) @@ -49,7 +50,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode IPv6 range""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = { 'range': None } diff --git a/plugins/modules/lke_cluster.py b/plugins/modules/lke_cluster.py index d4fb6a53..4bf34d92 100644 --- a/plugins/modules/lke_cluster.py +++ b/plugins/modules/lke_cluster.py @@ -9,6 +9,7 @@ import copy from typing import Optional, cast, Any, Set, List, Dict +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import LKECluster, LKENodePool, ApiError import polling @@ -24,65 +25,65 @@ from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import handle_updates linode_lke_cluster_autoscaler = dict( - enabled=dict( - type='bool', editable=True, + enabled=SpecField( + type=FieldType.bool, editable=True, description=[ 'Whether autoscaling is enabled for this Node Pool.', 'NOTE: Subsequent playbook runs will override nodes created by the cluster autoscaler.' ], ), - max=dict( - type='int', editable=True, - description='The maximum number of nodes to autoscale to. ' - 'Defaults to the value provided by the count field.', + max=SpecField( + type=FieldType.integer, editable=True, + description=['The maximum number of nodes to autoscale to. ' + 'Defaults to the value provided by the count field.'], ), - min=dict( - type='int', editable=True, - description='The minimum number of nodes to autoscale to. ' - 'Defaults to the Node Pool’s count.', + min=SpecField( + type=FieldType.integer, editable=True, + description=['The minimum number of nodes to autoscale to. ' + 'Defaults to the Node Pool’s count.'], ), ) linode_lke_cluster_disk = dict( - size=dict( - type='int', - description='This Node Pool’s custom disk layout.', + size=SpecField( + type=FieldType.integer, + description=['This Node Pool’s custom disk layout.'], required=True ), - type=dict( - type='str', - description='This custom disk partition’s filesystem type.', + type=SpecField( + type=FieldType.string, + description=['This custom disk partition’s filesystem type.'], choices=['raw', 'ext4'] ) ) linode_lke_cluster_node_pool_spec = dict( - count=dict( - type='int', editable=True, - description='The number of nodes in the Node Pool.', + count=SpecField( + type=FieldType.integer, editable=True, + description=['The number of nodes in the Node Pool.'], required=True, ), - type=dict( - type='str', - description='The Linode Type for all of the nodes in the Node Pool.', + type=SpecField( + type=FieldType.string, + description=['The Linode Type for all of the nodes in the Node Pool.'], required=True, ), - autoscaler=dict( - type='dict', editable=True, - description='When enabled, the number of nodes autoscales within the ' - 'defined minimum and maximum values.', + autoscaler=SpecField( + type=FieldType.dict, editable=True, + description=['When enabled, the number of nodes autoscales within the ' + 'defined minimum and maximum values.'], suboptions=linode_lke_cluster_autoscaler, ), ) linode_lke_cluster_spec = dict( - label=dict( - type='str', + label=SpecField( + type=FieldType.string, required=True, - description='This Kubernetes cluster’s unique label.' + description=['This Kubernetes cluster’s unique label.'] ), - k8s_version=dict( - type='str', editable=True, + k8s_version=SpecField( + type=FieldType.string, editable=True, description=[ 'The desired Kubernetes version for this Kubernetes ' 'cluster in the format of ., and the ' @@ -90,82 +91,80 @@ 'A version upgrade requires that you manually recycle the nodes in your cluster.'] ), - region=dict( - type='str', - description='This Kubernetes cluster’s location.', + region=SpecField( + type=FieldType.string, + description=['This Kubernetes cluster’s location.'], ), - tags=dict( - type='list', - elements='str', - description='An array of tags applied to the Kubernetes cluster.', + tags=SpecField( + type=FieldType.list, + element_type=FieldType.string, + description=['An array of tags applied to the Kubernetes cluster.'], ), - high_availability=dict( - type='bool', editable=True, - description='Defines whether High Availability is enabled for the ' - 'Control Plane Components of the cluster. ', + high_availability=SpecField( + type=FieldType.bool, editable=True, + description=['Defines whether High Availability is enabled for the ' + 'Control Plane Components of the cluster. '], default=False ), - node_pools=dict( + node_pools=SpecField( editable=True, - type='list', - elements='dict', + type=FieldType.list, + element_type=FieldType.dict, suboptions=linode_lke_cluster_node_pool_spec, - description='A list of node pools to configure the cluster with' + description=['A list of node pools to configure the cluster with'] ), - skip_polling=dict( - type='bool', - description='If true, the module will not wait for all nodes in the cluster to be ready.', + skip_polling=SpecField( + type=FieldType.bool, + description=['If true, the module will not wait for all nodes in the cluster to be ready.'], default=False ), - wait_timeout=dict( - type='int', - description='The period to wait for the cluster to be ready in seconds.', + wait_timeout=SpecField( + type=FieldType.integer, + description=['The period to wait for the cluster to be ready in seconds.'], default=600 ) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage Linode LKE clusters.' ], requirements=global_requirements, author=global_authors, - spec=linode_lke_cluster_spec, + options=linode_lke_cluster_spec, examples=docs.examples, return_values=dict( - cluster=dict( + cluster=SpecReturnValue( description='The LKE cluster in JSON serialized form.', docs_url='https://www.linode.com/docs/api/linode-kubernetes-engine-lke/' '#kubernetes-cluster-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_cluster ), - node_pools=dict( + node_pools=SpecReturnValue( description='A list of node pools in JSON serialized form.', docs_url='https://www.linode.com/docs/api/linode-kubernetes-engine-lke/' '#node-pools-list__response-samples', - type='list', + type=FieldType.list, sample=docs.result_node_pools ), - kubeconfig=dict( - description=[ - 'The Base64-encoded kubeconfig used to access this cluster.', - 'NOTE: This value may be unavailable if `skip_polling` is true.' - ], + kubeconfig=SpecReturnValue( + description='The Base64-encoded kubeconfig used to access this cluster. \n' + 'NOTE: This value may be unavailable if `skip_polling` is true.', docs_url='https://www.linode.com/docs/api/linode-kubernetes-engine-lke/' \ '#kubeconfig-view__responses', - type='str' + type=FieldType.string ), - dashboard_url=dict( + dashboard_url=SpecReturnValue( description='The Cluster Dashboard access URL.', docs_url='https://www.linode.com/docs/api/linode-kubernetes-engine-lke/' '#kubernetes-cluster-dashboard-url-view__responses', - type='str' + type=FieldType.string ) ) ) @@ -186,7 +185,7 @@ class LinodeLKECluster(LinodeModuleBase): """Module for creating and destroying Linode LKE clusters""" def __init__(self) -> None: - self.module_arg_spec = linode_lke_cluster_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results = dict( changed=False, @@ -240,7 +239,7 @@ def _create_cluster(self) -> Optional[LKECluster]: high_avail = params.pop('high_availability') params['control_plane'] = { - 'high_availability': high_avail + 'high_availability': high_avail } try: diff --git a/plugins/modules/lke_cluster_info.py b/plugins/modules/lke_cluster_info.py index 0af73a77..933065e1 100644 --- a/plugins/modules/lke_cluster_info.py +++ b/plugins/modules/lke_cluster_info.py @@ -8,10 +8,11 @@ # pylint: disable=unused-import from typing import List, Any, Optional, Dict +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import LKECluster, ApiError from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and,\ +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ jsonify_node_pool, filter_null_values from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements @@ -22,60 +23,58 @@ linode_lke_cluster_info_spec = dict( # We need to overwrite attributes to exclude them as requirements - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict( - type='int', required=False, + id=SpecField( + type=FieldType.integer, required=False, description=[ 'The ID of the LKE cluster.', 'Optional if `label` is defined.' ]), - label=dict( - type='str', required=False, + label=SpecField( + type=FieldType.string, required=False, description=[ 'The label of the LKE cluster.', 'Optional if `id` is defined.' ]) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode LKE cluster.' ], requirements=global_requirements, author=global_authors, - spec=linode_lke_cluster_info_spec, + options=linode_lke_cluster_info_spec, examples=docs.examples, return_values=dict( - cluster=dict( + cluster=SpecReturnValue( description='The LKE cluster in JSON serialized form.', docs_url='https://www.linode.com/docs/api/linode-kubernetes-engine-lke/' '#kubernetes-cluster-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs_parent.result_cluster ), - node_pools=dict( + node_pools=SpecReturnValue( description='A list of node pools in JSON serialized form.', docs_url='https://www.linode.com/docs/api/linode-kubernetes-engine-lke/' '#node-pools-list__response-samples', - type='list', + type=FieldType.list, sample=docs_parent.result_node_pools ), - kubeconfig=dict( - description=[ - 'The Base64-encoded kubeconfig used to access this cluster.', - 'NOTE: This value may be unavailable if the cluster is not fully provisioned.' - ], + kubeconfig=SpecReturnValue( + description='The Base64-encoded kubeconfig used to access this cluster. \n' + 'NOTE: This value may be unavailable if the cluster is not fully provisioned.', docs_url='https://www.linode.com/docs/api/linode-kubernetes-engine-lke/' '#kubeconfig-view__responses', - type='str' + type=FieldType.string ), - dashboard_url=dict( + dashboard_url=SpecReturnValue( description='The Cluster Dashboard access URL.', docs_url='https://www.linode.com/docs/api/linode-kubernetes-engine-lke/' '#kubernetes-cluster-dashboard-url-view__responses', - type='str' + type=FieldType.string ) ) ) @@ -89,7 +88,7 @@ class LinodeLKEClusterInfo(LinodeModuleBase): """Module for getting info about a Linode Volume""" def __init__(self) -> None: - self.module_arg_spec = linode_lke_cluster_info_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results: Dict[str, Any] = dict( cluster=None, diff --git a/plugins/modules/lke_node_pool.py b/plugins/modules/lke_node_pool.py index c9f0b384..1034362b 100644 --- a/plugins/modules/lke_node_pool.py +++ b/plugins/modules/lke_node_pool.py @@ -10,6 +10,7 @@ import polling import linode_api4 +from ansible_specdoc.objects import FieldType, SpecField, SpecDocMeta, SpecReturnValue from linode_api4 import LKENodePool, LKECluster, ApiError from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -21,72 +22,71 @@ import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.lke_node_pool as docs linode_lke_pool_autoscaler = dict( - enabled=dict( - type='bool', editable=True, + enabled=SpecField( + type=FieldType.bool, editable=True, description=[ 'Whether autoscaling is enabled for this Node Pool.', 'NOTE: Subsequent playbook runs will override nodes created by the cluster autoscaler.' ], ), - max=dict( - type='int', editable=True, - description='The maximum number of nodes to autoscale to. ' - 'Defaults to the value provided by the count field.', + max=SpecField( + type=FieldType.integer, editable=True, + description=['The maximum number of nodes to autoscale to. ' + 'Defaults to the value provided by the count field.'], ), - min=dict( - type='int', editable=True, - description='The minimum number of nodes to autoscale to. ' - 'Defaults to the Node Pool’s count.', + min=SpecField( + type=FieldType.integer, editable=True, + description=['The minimum number of nodes to autoscale to. ' + 'Defaults to the Node Pool’s count.'], ), ) linode_lke_pool_disks = dict( - type=dict( - type='str', + type=SpecField( + type=FieldType.string, required=True, - description='This custom disk partition’s filesystem type.', + description=['This custom disk partition’s filesystem type.'], choices=['raw', 'ext4'] ), - size=dict( - type='int', required=True, - description='The size of this custom disk partition in MB.', + size=SpecField( + type=FieldType.integer, required=True, + description=['The size of this custom disk partition in MB.'], ), ) - MODULE_SPEC = dict( - label=dict( - type='str', required=False, doc_hide=True + label=SpecField( + type=FieldType.string, required=False, doc_hide=True ), - cluster_id=dict( - type='int', required=True, - description='The ID of the LKE cluster that contains this node pool.', - ), + cluster_id=SpecField( + type=FieldType.integer, required=True, + description=['The ID of the LKE cluster that contains this node pool.'], + ), - autoscaler=dict( - type='dict', editable=True, - description='When enabled, the number of nodes autoscales within the ' - 'defined minimum and maximum values.', + autoscaler=SpecField( + type=FieldType.dict, editable=True, + description=['When enabled, the number of nodes autoscales within the ' + 'defined minimum and maximum values.'], suboptions=linode_lke_pool_autoscaler, ), - count=dict( - type='int', editable=True, - description='The number of nodes in the Node Pool.', + count=SpecField( + type=FieldType.integer, editable=True, + description=['The number of nodes in the Node Pool.'], ), - disks=dict( - type='list', elements='dict', - description='This Node Pool’s custom disk layout. ' - 'Each item in this array will create a ' - 'new disk partition for each node in this ' - 'Node Pool.', + disks=SpecField( + type=FieldType.list, element_type=FieldType.dict, + description=['This Node Pool’s custom disk layout. ' + 'Each item in this array will create a ' + 'new disk partition for each node in this ' + 'Node Pool.'], suboptions=linode_lke_pool_disks, ), - tags=dict( - type='list', elements='str', editable=True, + tags=SpecField( + type=FieldType.list, element_type=FieldType.string, editable=True, required=True, description=[ 'An array of tags applied to this object.', @@ -95,46 +95,45 @@ ], ), - type=dict( - type='str', + type=SpecField( + type=FieldType.string, description=[ 'The Linode Type for all of the nodes in the Node Pool.', 'Required if `state` == `present`.' ] ), - state=dict(type='str', - description='The desired state of the target.', - choices=['present', 'absent'], required=True), + state=SpecField(type=FieldType.string, + description=['The desired state of the target.'], + choices=['present', 'absent'], required=True), - skip_polling=dict( - type='bool', - description='If true, the module will not wait for all nodes in the node pool to be ready.', + skip_polling=SpecField( + type=FieldType.bool, + description=['If true, the module will not wait for all nodes in the node pool to be ready.'], default=False ), - wait_timeout=dict( - type='int', - description='The period to wait for the node pool to be ready in seconds.', + wait_timeout=SpecField( + type=FieldType.integer, + description=['The period to wait for the node pool to be ready in seconds.'], default=600 ) ) - -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage Linode LKE cluster node pools.' ], requirements=global_requirements, author=global_authors, - spec=MODULE_SPEC, + options=MODULE_SPEC, examples=docs.examples, return_values=dict( - node_pool=dict( + node_pool=SpecReturnValue( description='The Node Pool in JSON serialized form.', docs_url='https://www.linode.com/docs/api/linode-kubernetes-engine-lke/' '#node-pool-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_node_pool ) ) @@ -145,7 +144,7 @@ class LinodeLKENodePool(LinodeModuleBase): """Module for managing Linode Firewall devices""" def __init__(self) -> None: - self.module_arg_spec = MODULE_SPEC + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results = dict( changed=False, @@ -204,7 +203,6 @@ def _create_pool(self) -> LKENodePool: self.register_action('Created node pool {}'.format(pool_obj.id)) - return pool_obj except Exception as exception: return self.fail(msg='failed to create lke cluster node pool for cluster {0}: {1}' @@ -237,7 +235,7 @@ def _update_pool(self, pool: LKENodePool) -> LKENodePool: if len(put_data) > 0: try: self.client.put('/lke/clusters/{0}/pools/{1}' - .format(cluster_id, pool.id), data=put_data) + .format(cluster_id, pool.id), data=put_data) except Exception as exception: return self.fail(msg='failed to update node pool for cluster {0}: {1}' .format(cluster_id, exception)) @@ -283,6 +281,7 @@ def exec_module(self, **kwargs: Any) -> Optional[dict]: return self.results + def main() -> None: """Constructs and calls the Linode LKE Node Pool module""" LinodeLKENodePool() From 4332e50abbf1b6cdb0239bd3008833e97db4f0d0 Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 15:44:36 -0500 Subject: [PATCH 08/13] progress --- docs/modules/nodebalancer.md | 183 ++++++++++++++++++++++++ docs/modules/nodebalancer_info.md | 129 +++++++++++++++++ docs/modules/nodebalancer_node.md | 91 ++++++++++++ docs/modules/object_cluster_info.md | 65 +++++++++ docs/modules/object_keys.md | 94 ++++++++++++ plugins/modules/nodebalancer.py | 189 +++++++++++++------------ plugins/modules/nodebalancer_info.py | 28 ++-- plugins/modules/nodebalancer_node.py | 55 +++---- plugins/modules/object_cluster_info.py | 39 ++--- plugins/modules/object_keys.py | 45 +++--- 10 files changed, 743 insertions(+), 175 deletions(-) create mode 100644 docs/modules/nodebalancer.md create mode 100644 docs/modules/nodebalancer_info.md create mode 100644 docs/modules/nodebalancer_node.md create mode 100644 docs/modules/object_cluster_info.md create mode 100644 docs/modules/object_keys.md diff --git a/docs/modules/nodebalancer.md b/docs/modules/nodebalancer.md new file mode 100644 index 00000000..7462278b --- /dev/null +++ b/docs/modules/nodebalancer.md @@ -0,0 +1,183 @@ +# nodebalancer + +Manage a Linode NodeBalancer. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- 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 +``` + +```yaml +- name: Delete the NodeBalancer + linode.cloud.nodebalancer: + label: my-loadbalancer + region: us-east + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| The unique label to give this NodeBalancer. | +| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | +| `client_conn_throttle` |
`int`
|
Optional
| Throttle connections per second. Set to 0 (zero) to disable throttling. **(Updatable)** | +| `region` |
`str`
|
Optional
| The ID of the Region to create this NodeBalancer in. | +| [`configs` (sub-options)](#configs) |
`list`
|
Optional
| A list of configs to apply to the NodeBalancer. **(Updatable)** | + + + + + +### configs + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `algorithm` |
`str`
|
Optional
| What algorithm this NodeBalancer should use for routing traffic to backends. **(Choices: `roundrobin`, `leastconn`, `source`; Updatable)** | +| `check` |
`str`
|
Optional
| The type of check to perform against backends to ensure they are serving requests. **(Choices: `none`, `connection`, `http`, `http_body`; Updatable)** | +| `check_attempts` |
`int`
|
Optional
| How many times to attempt a check before considering a backend to be down. **(Updatable)** | +| `check_body` |
`str`
|
Optional
| 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. **(Updatable)** | +| `check_interval` |
`int`
|
Optional
| How often, in seconds, to check that backends are up and serving requests. **(Updatable)** | +| `check_passive` |
`bool`
|
Optional
| 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. **(Updatable)** | +| `check_path` |
`str`
|
Optional
| The URL path to check on each backend. If the backend does not respond to this request it is considered to be down. **(Updatable)** | +| `check_timeout` |
`int`
|
Optional
| How long, in seconds, to wait for a check attempt before considering it failed. **(Updatable)** | +| `cipher_suite` |
`str`
|
Optional
| What ciphers to use for SSL connections served by this NodeBalancer. **(Choices: `recommended`, `legacy`; Default: `recommended`; Updatable)** | +| `port` |
`int`
|
Optional
| The port this Config is for. **(Updatable)** | +| `protocol` |
`str`
|
Optional
| The protocol this port is configured to serve. **(Choices: `http`, `https`, `tcp`; Updatable)** | +| `proxy_protocol` |
`str`
|
Optional
| ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. **(Choices: `none`, `v1`, `v2`; Updatable)** | +| `recreate` |
`bool`
|
Optional
| If true, the config will be forcibly recreated on every run. This is useful for updates to redacted fields (`ssl_cert`, `ssl_key`) **(Default: `False`)** | +| `ssl_cert` |
`str`
|
Optional
| 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. **(Updatable)** | +| `ssl_key` |
`str`
|
Optional
| The PEM-formatted private key for the SSL certificate set in the ssl_cert field. **(Updatable)** | +| `stickiness` |
`str`
|
Optional
| Controls how session stickiness is handled on this port. **(Choices: `none`, `table`, `http_cookie`; Updatable)** | +| [`nodes` (sub-options)](#nodes) |
`list`
|
Optional
| A list of nodes to apply to this config. These can alternatively be configured through the nodebalancer_node module. **(Updatable)** | + + + + + +### nodes + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| The label for this node. | +| `address` |
`str`
|
**Required**
| The private IP Address where this backend can be reached. This must be a private IP address. **(Updatable)** | +| `weight` |
`int`
|
Optional
| Nodes with a higher weight will receive more traffic. **(Updatable)** | +| `mode` |
`str`
|
Optional
| The mode this NodeBalancer should use when sending traffic to this backend. **(Choices: `accept`, `reject`, `drain`, `backup`; Updatable)** | + + + + + + +## Return Values + +- `node_balancer` - The NodeBalancer in JSON serialized form. + + - Sample Response: + ```json + { + "client_conn_throttle": 0, + "created": "2018-01-01T00:01:01", + "hostname": "192.0.2.1.ip.linodeusercontent.com", + "id": 12345, + "ipv4": "12.34.56.78", + "ipv6": null, + "label": "balancer12345", + "region": "us-east", + "tags": [ + "example tag", + "another example" + ], + "transfer": { + "in": 28.91200828552246, + "out": 3.5487728118896484, + "total": 32.46078109741211 + }, + "updated": "2018-03-01T00:01:01" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#nodebalancer-view__responses) for a list of returned fields + + +- `configs` - A list of configs applied to the NodeBalancer. + + - Sample Response: + ```json + [ + { + "algorithm": "roundrobin", + "check": "http_body", + "check_attempts": 3, + "check_body": "it works", + "check_interval": 90, + "check_passive": true, + "check_path": "/test", + "check_timeout": 10, + "cipher_suite": "recommended", + "id": 4567, + "nodebalancer_id": 12345, + "nodes_status": { + "down": 0, + "up": 4 + }, + "port": 80, + "protocol": "http", + "proxy_protocol": "none", + "ssl_cert": null, + "ssl_commonname": null, + "ssl_fingerprint": null, + "ssl_key": null, + "stickiness": "http_cookie" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#config-view__responses) for a list of returned fields + + +- `nodes` - A list of configs applied to the NodeBalancer. + + - Sample Response: + ```json + [ + { + "address": "192.168.210.120:80", + "config_id": 4567, + "id": 54321, + "label": "node54321", + "mode": "accept", + "nodebalancer_id": 12345, + "status": "UP", + "weight": 50 + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#node-view) for a list of returned fields + + diff --git a/docs/modules/nodebalancer_info.md b/docs/modules/nodebalancer_info.md new file mode 100644 index 00000000..67930687 --- /dev/null +++ b/docs/modules/nodebalancer_info.md @@ -0,0 +1,129 @@ +# nodebalancer_info + +Get info about a Linode NodeBalancer. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get a NodeBalancer by its id + linode.cloud.nodebalancer_info: + id: 12345 +``` + +```yaml +- name: Get a NodeBalancer by its label + linode.cloud.nodebalancer_info: + label: cool_nodebalancer +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`int`
|
Optional
| The ID of this NodeBalancer. Optional if `label` is defined. | +| `label` |
`str`
|
Optional
| The label of this NodeBalancer. Optional if `id` is defined. | + + + + + + +## Return Values + +- `node_balancer` - The NodeBalancer in JSON serialized form. + + - Sample Response: + ```json + { + "client_conn_throttle": 0, + "created": "2018-01-01T00:01:01", + "hostname": "192.0.2.1.ip.linodeusercontent.com", + "id": 12345, + "ipv4": "12.34.56.78", + "ipv6": null, + "label": "balancer12345", + "region": "us-east", + "tags": [ + "example tag", + "another example" + ], + "transfer": { + "in": 28.91200828552246, + "out": 3.5487728118896484, + "total": 32.46078109741211 + }, + "updated": "2018-03-01T00:01:01" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#nodebalancer-view__responses) for a list of returned fields + + +- `configs` - A list of configs applied to the NodeBalancer. + + - Sample Response: + ```json + [ + { + "algorithm": "roundrobin", + "check": "http_body", + "check_attempts": 3, + "check_body": "it works", + "check_interval": 90, + "check_passive": true, + "check_path": "/test", + "check_timeout": 10, + "cipher_suite": "recommended", + "id": 4567, + "nodebalancer_id": 12345, + "nodes_status": { + "down": 0, + "up": 4 + }, + "port": 80, + "protocol": "http", + "proxy_protocol": "none", + "ssl_cert": null, + "ssl_commonname": null, + "ssl_fingerprint": null, + "ssl_key": null, + "stickiness": "http_cookie" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#config-view__responses) for a list of returned fields + + +- `nodes` - A list of configs applied to the NodeBalancer. + + - Sample Response: + ```json + [ + { + "address": "192.168.210.120:80", + "config_id": 4567, + "id": 54321, + "label": "node54321", + "mode": "accept", + "nodebalancer_id": 12345, + "status": "UP", + "weight": 50 + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#node-view) for a list of returned fields + + diff --git a/docs/modules/nodebalancer_node.md b/docs/modules/nodebalancer_node.md new file mode 100644 index 00000000..b0d63a01 --- /dev/null +++ b/docs/modules/nodebalancer_node.md @@ -0,0 +1,91 @@ +# nodebalancer_node + +Manage Linode NodeBalancer Nodes. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a NodeBalancer + linode.cloud.nodebalancer: + label: my-nodebalancer + region: us-east + state: present + configs: + - port: 80 + protocol: http + algorithm: roundrobin + register: nodebalancer_result + +- name: Create an Instance + linode.cloud.instance: + label: my-instance + region: us-east + private_ip: true + type: g6-standard-1 + state: present + register: instance_result + +- name: Attach the Instance to the NodeBalancer + linode.cloud.nodebalancer_node: + nodebalancer_id: nodebalancer_result.node_balancer.id + config_id: nodebalancer_result.configs[0].id + + label: my-node + + # Use the private ip address of the instance + address: '{{ instance_result.instance.ipv4[1] }}:80' + + state: present +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `nodebalancer_id` |
`int`
|
**Required**
| The ID of the NodeBalancer that contains this node. | +| `config_id` |
`int`
|
**Required**
| The ID of the NodeBalancer Config that contains this node. | +| `label` |
`str`
|
**Required**
| The label for this node. This is used to identify nodes within a config. | +| `state` |
`str`
|
**Required**
| Whether the NodeBalancer node should be present or absent. **(Choices: `present`, `absent`)** | +| `address` |
`str`
|
Optional
| The private IP Address where this backend can be reached. This must be a private IP address. **(Updatable)** | +| `mode` |
`str`
|
Optional
| The mode this NodeBalancer should use when sending traffic to this backend. **(Choices: `accept`, `reject`, `drain`, `backup`; Updatable)** | +| `weight` |
`int`
|
Optional
| Nodes with a higher weight will receive more traffic. **(Updatable)** | + + + + + + +## Return Values + +- `node` - The NodeBalancer Node in JSON serialized form. + + - Sample Response: + ```json + { + "address": "123.123.123.123:80", + "config_id": 12345, + "id": 12345, + "label": "mynode", + "mode": "accept", + "nodebalancer_id": 12345, + "status": "Unknown", + "weight": 10 + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/nodebalancers/#node-view__responses) for a list of returned fields + + diff --git a/docs/modules/object_cluster_info.md b/docs/modules/object_cluster_info.md new file mode 100644 index 00000000..f85ea1e1 --- /dev/null +++ b/docs/modules/object_cluster_info.md @@ -0,0 +1,65 @@ +# object_cluster_info + +Get info about a Linode Object Storage Cluster. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about clusters in us-east + linode.cloud.object_cluster_info: + region: us-east +``` + +```yaml +- name: Get info about the cluster with id us-east-1 + linode.cloud.object_cluster_info: + id: us-east-1 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`str`
|
Optional
| The unique id given to the clusters. | +| `region` |
`str`
|
Optional
| The region the clusters are in. | +| `domain` |
`str`
|
Optional
| The domain of the clusters. | +| `static_site_domain` |
`str`
|
Optional
| The static-site domain of the clusters. | + + + + + + +## Return Values + +- `clusters` - The Object Storage clusters in JSON serialized form. + + - Sample Response: + ```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" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/object-storage/#cluster-view__responses) for a list of returned fields + + diff --git a/docs/modules/object_keys.md b/docs/modules/object_keys.md new file mode 100644 index 00000000..020aa27b --- /dev/null +++ b/docs/modules/object_keys.md @@ -0,0 +1,94 @@ +# object_keys + +Manage Linode Object Storage Keys. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create an Object Storage key + linode.cloud.object_keys: + label: 'my-fullaccess-key' + state: present +``` + +```yaml +- 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 +``` + +```yaml +- name: Remove an object storage key + linode.cloud.object_keys: + label: 'my-key' + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | +| `label` |
`str`
|
Optional
| The unique label to give this key. | +| [`access` (sub-options)](#access) |
`list`
|
Optional
| A list of access permissions to give the key. | + + + + + +### access + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `cluster` |
`str`
|
**Required**
| The id of the cluster that the provided bucket exists under. | +| `bucket_name` |
`str`
|
**Required**
| The name of the bucket to set the key's permissions for. | +| `permissions` |
`str`
|
**Required**
| The permissions to give the key. **(Choices: `read_only`, `write_only`, `read_write`)** | + + + + + + +## Return Values + +- `key` - The Object Storage key in JSON serialized form. + + - Sample Response: + ```json + { + "access_key": "ACCESSKEY", + "bucket_access": [ + { + "bucket_name": "example-bucket", + "cluster": "ap-south-1", + "permissions": "read_only" + } + ], + "id": 123, + "label": "my-key", + "limited": true, + "secret_key": "SECRETKEY" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/object-storage/#object-storage-key-view__responses) for a list of returned fields + + diff --git a/plugins/modules/nodebalancer.py b/plugins/modules/nodebalancer.py index ee2a5e6a..bf2ab61a 100644 --- a/plugins/modules/nodebalancer.py +++ b/plugins/modules/nodebalancer.py @@ -9,6 +9,7 @@ from typing import Optional, cast, Any, List, Set, Tuple import linode_api4 +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ paginated_list_to_json, dict_select_matching, filter_null_values @@ -26,174 +27,174 @@ from linode_api4 import NodeBalancer, NodeBalancerConfig, NodeBalancerNode, PaginatedList linode_nodes_spec = dict( - label=dict( - type='str', required=True, - description='The label for this node.'), + label=SpecField( + type=FieldType.string, required=True, + description=['The label for this node.']), - address=dict( - type='str', required=True, editable=True, + address=SpecField( + type=FieldType.string, required=True, editable=True, description=[ 'The private IP Address where this backend can be reached.', 'This must be a private IP address.' ]), - weight=dict( - type='int', required=False, editable=True, - description='Nodes with a higher weight will receive more traffic.', + weight=SpecField( + type=FieldType.integer, required=False, editable=True, + description=['Nodes with a higher weight will receive more traffic.'], ), - mode=dict( - type='str', required=False, editable=True, - description='The mode this NodeBalancer should use when sending traffic to this backend.', + mode=SpecField( + type=FieldType.string, required=False, editable=True, + description=['The mode this NodeBalancer should use when sending traffic to this backend.'], choices=['accept', 'reject', 'drain', 'backup']), ) linode_configs_spec = dict( - algorithm=dict( - type='str', required=False, editable=True, - description='What algorithm this NodeBalancer should use for routing traffic to backends.', + algorithm=SpecField( + type=FieldType.string, required=False, editable=True, + description=['What algorithm this NodeBalancer should use for routing traffic to backends.'], choices=['roundrobin', 'leastconn', 'source']), - check=dict( - type='str', required=False, editable=True, - description='The type of check to perform against backends to ensure they are ' - 'serving requests.', + check=SpecField( + type=FieldType.string, required=False, editable=True, + description=['The type of check to perform against backends to ensure they are ' + 'serving requests.'], choices=['none', 'connection', 'http', 'http_body']), - check_attempts=dict( - type='int', required=False, editable=True, - description='How many times to attempt a check before considering a backend to be down.'), + check_attempts=SpecField( + type=FieldType.integer, required=False, editable=True, + description=['How many times to attempt a check before considering a backend to be down.']), - check_body=dict( - type='str', required=False, default='', editable=True, + check_body=SpecField( + type=FieldType.string, required=False, default='', editable=True, description=[ '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=dict( - type='int', required=False, editable=True, - description='How often, in seconds, to check that backends are up and serving requests.'), + check_interval=SpecField( + type=FieldType.integer, required=False, editable=True, + description=['How often, in seconds, to check that backends are up and serving requests.']), - check_passive=dict( + check_passive=SpecField( type='bool', required=False, editable=True, - description='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=dict( - type='str', required=False, editable=True, - description='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=dict( - type='int', required=False, editable=True, - description='How long, in seconds, to wait for a check attempt before considering it ' - 'failed.'), - - cipher_suite=dict( - type='str', required=False, default='recommended', editable=True, - description='What ciphers to use for SSL connections served by this NodeBalancer.', + description=['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=SpecField( + type=FieldType.string, required=False, editable=True, + description=['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=SpecField( + type=FieldType.integer, required=False, editable=True, + description=['How long, in seconds, to wait for a check attempt before considering it ' + 'failed.']), + + cipher_suite=SpecField( + type=FieldType.string, required=False, default='recommended', editable=True, + description=['What ciphers to use for SSL connections served by this NodeBalancer.'], choices=['recommended', 'legacy']), - port=dict( - type='int', required=False, editable=True, - description='The port this Config is for.'), + port=SpecField( + type=FieldType.integer, required=False, editable=True, + description=['The port this Config is for.']), - protocol=dict( - type='str', required=False, editable=True, - description='The protocol this port is configured to serve.', + protocol=SpecField( + type=FieldType.string, required=False, editable=True, + description=['The protocol this port is configured to serve.'], choices=['http', 'https', 'tcp']), - proxy_protocol=dict( - type='str', required=False, editable=True, - description='ProxyProtocol is a TCP extension that sends initial TCP connection ' - 'information such as source/destination IPs and ports to backend devices.', + proxy_protocol=SpecField( + type=FieldType.string, required=False, editable=True, + description=['ProxyProtocol is a TCP extension that sends initial TCP connection ' + 'information such as source/destination IPs and ports to backend devices.'], choices=['none', 'v1', 'v2']), - recreate=dict( - type='bool', required=False, default=False, - description='If true, the config will be forcibly recreated on every run. ' - 'This is useful for updates to redacted fields (`ssl_cert`, `ssl_key`)' + recreate=SpecField( + type=FieldType.bool, required=False, default=False, + description=['If true, the config will be forcibly recreated on every run. ' + 'This is useful for updates to redacted fields (`ssl_cert`, `ssl_key`)'] ), - ssl_cert=dict( - type='str', required=False, editable=True, - description='The PEM-formatted public SSL certificate (or the combined ' + ssl_cert=SpecField( + type=FieldType.string, required=False, editable=True, + description=['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.'), + 'that should be served on this NodeBalancerConfig’s port.']), - ssl_key=dict( - type='str', required=False, editable=True, - description='The PEM-formatted private key for the SSL certificate ' - 'set in the ssl_cert field.'), + ssl_key=SpecField( + type=FieldType.string, required=False, editable=True, + description=['The PEM-formatted private key for the SSL certificate ' + 'set in the ssl_cert field.']), - stickiness=dict( - type='str', required=False, editable=True, - description='Controls how session stickiness is handled on this port.', + stickiness=SpecField( + type=FieldType.string, required=False, editable=True, + description=['Controls how session stickiness is handled on this port.'], choices=['none', 'table', 'http_cookie']), - nodes=dict( - type='list', required=False, elements='dict', options=linode_nodes_spec, editable=True, - description='A list of nodes to apply to this config. ' - 'These can alternatively be configured through the nodebalancer_node module.') + nodes=SpecField( + type=FieldType.list, required=False, element_type=FieldType.dict, suboptions=linode_nodes_spec, editable=True, + description=['A list of nodes to apply to this config. ' + 'These can alternatively be configured through the nodebalancer_node module.']) ) linode_nodebalancer_spec = dict( - label=dict( - type='str', - description='The unique label to give this NodeBalancer.', + label=SpecField( + type=FieldType.string, + description=['The unique label to give this NodeBalancer.'], required=True, ), - client_conn_throttle=dict( - type='int', editable=True, + client_conn_throttle=SpecField( + type=FieldType.integer, editable=True, description=[ 'Throttle connections per second.', 'Set to 0 (zero) to disable throttling.' ]), - region=dict( - type='str', - description='The ID of the Region to create this NodeBalancer in.', + region=SpecField( + type=FieldType.string, + description=['The ID of the Region to create this NodeBalancer in.'], ), - state=dict(type='str', - description='The desired state of the target.', + state=SpecField(type=FieldType.string, + description=['The desired state of the target.'], choices=['present', 'absent'], required=True), - configs=dict( - type='list', elements='dict', options=linode_configs_spec, editable=True, - description='A list of configs to apply to the NodeBalancer.') + configs=SpecField( + type=FieldType.list, element_type=FieldType.dict, suboptions=linode_configs_spec, editable=True, + description=['A list of configs to apply to the NodeBalancer.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage a Linode NodeBalancer.' ], requirements=global_requirements, author=global_authors, - spec=linode_nodebalancer_spec, + options=linode_nodebalancer_spec, examples=docs.specdoc_examples, return_values=dict( - node_balancer=dict( + node_balancer=SpecReturnValue( description='The NodeBalancer in JSON serialized form.', docs_url='https://www.linode.com/docs/api/nodebalancers/#nodebalancer-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_node_balancer_samples ), - configs=dict( + configs=SpecReturnValue( description='A list of configs applied to the NodeBalancer.', docs_url='https://www.linode.com/docs/api/nodebalancers/#config-view__responses', - type='list', + type=FieldType.list, sample=docs.result_configs_samples ), - nodes=dict( + nodes=SpecReturnValue( description='A list of configs applied to the NodeBalancer.', docs_url='https://www.linode.com/docs/api/nodebalancers/#node-view', - type='list', + type=FieldType.list, sample=docs.result_nodes_samples ) ) @@ -209,7 +210,7 @@ class LinodeNodeBalancer(LinodeModuleBase): """Configuration class for Linode NodeBalancer resource""" def __init__(self) -> None: - self.module_arg_spec = linode_nodebalancer_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of = ['state', 'label'] self.results = dict( changed=False, diff --git a/plugins/modules/nodebalancer_info.py b/plugins/modules/nodebalancer_info.py index 6ea4a9ba..bd6ec41c 100644 --- a/plugins/modules/nodebalancer_info.py +++ b/plugins/modules/nodebalancer_info.py @@ -7,6 +7,8 @@ from typing import List, Optional, Any +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue + from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ create_filter_and from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -23,48 +25,48 @@ linode_nodebalancer_info_spec = dict( # We need to overwrite attributes to exclude them as requirements - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict( - type='int', required=False, + id=SpecField( + type=FieldType.integer, required=False, description=[ 'The ID of this NodeBalancer.', 'Optional if `label` is defined.' ]), - label=dict( - type='str', required=False, + label=SpecField( + type=FieldType.string, required=False, description=[ 'The label of this NodeBalancer.', 'Optional if `id` is defined.' ]) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode NodeBalancer.' ], requirements=global_requirements, author=global_authors, - spec=linode_nodebalancer_info_spec, + options=linode_nodebalancer_info_spec, examples=docs.specdoc_examples, return_values=dict( - node_balancer=dict( + node_balancer=SpecReturnValue( description='The NodeBalancer in JSON serialized form.', docs_url='https://www.linode.com/docs/api/nodebalancers/#nodebalancer-view__responses', type='dict', sample=docs_parent.result_node_balancer_samples ), - configs=dict( + configs=SpecReturnValue( description='A list of configs applied to the NodeBalancer.', docs_url='https://www.linode.com/docs/api/nodebalancers/#config-view__responses', - type='list', + type=FieldType.list, sample=docs_parent.result_configs_samples ), - nodes=dict( + nodes=SpecReturnValue( description='A list of configs applied to the NodeBalancer.', docs_url='https://www.linode.com/docs/api/nodebalancers/#node-view', - type='list', + type=FieldType.list, sample=docs_parent.result_nodes_samples ) ) @@ -79,7 +81,7 @@ class LinodeNodeBalancerInfo(LinodeModuleBase): """Module for getting info about a Linode NodeBalancer""" def __init__(self) -> None: - self.module_arg_spec = linode_nodebalancer_info_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results: dict = dict( node_balancer=None, diff --git a/plugins/modules/nodebalancer_node.py b/plugins/modules/nodebalancer_node.py index 4d38bed5..b05d988e 100644 --- a/plugins/modules/nodebalancer_node.py +++ b/plugins/modules/nodebalancer_node.py @@ -10,6 +10,7 @@ from typing import Optional, cast, Any, Set, List import linode_api4 +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Domain from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -21,59 +22,59 @@ import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.nodebalancer_node as docs MODULE_SPEC = dict( - nodebalancer_id=dict( - type='int', required=True, - description='The ID of the NodeBalancer that contains this node.', + nodebalancer_id=SpecField( + type=FieldType.integer, required=True, + description=['The ID of the NodeBalancer that contains this node.'], ), - config_id=dict( - type='int', required=True, - description='The ID of the NodeBalancer Config that contains this node.', + config_id=SpecField( + type=FieldType.integer, required=True, + description=['The ID of the NodeBalancer Config that contains this node.'], ), - label=dict( - type='str', required=True, - description='The label for this node. This is used to identify nodes within a config.', + label=SpecField( + type=FieldType.string, required=True, + description=['The label for this node. This is used to identify nodes within a config.'], ), - address=dict( - type='str', editable=True, - description='The private IP Address where this backend can be reached. ' - 'This must be a private IP address.', + address=SpecField( + type=FieldType.string, editable=True, + description=['The private IP Address where this backend can be reached. ' + 'This must be a private IP address.'], ), - state=dict( - type='str', - description='Whether the NodeBalancer node should be present or absent.', + state=SpecField( + type=FieldType.string, + description=['Whether the NodeBalancer node should be present or absent.'], choices=['present', 'absent'], required=True ), - mode=dict( - type='str', editable=True, - description='The mode this NodeBalancer should use when sending traffic to this backend.', + mode=SpecField( + type=FieldType.string, editable=True, + description=['The mode this NodeBalancer should use when sending traffic to this backend.'], choices=['accept', 'reject', 'drain', 'backup'], ), - weight=dict( - type='int', editable=True, - description='Nodes with a higher weight will receive more traffic.', + weight=SpecField( + type=FieldType.integer, editable=True, + description=['Nodes with a higher weight will receive more traffic.'], ), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage Linode NodeBalancer Nodes.' ], requirements=global_requirements, author=global_authors, - spec=MODULE_SPEC, + options=MODULE_SPEC, examples=docs.specdoc_examples, return_values=dict( - node=dict( + node=SpecReturnValue( description='The NodeBalancer Node in JSON serialized form.', docs_url='https://www.linode.com/docs/api/nodebalancers/#node-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_node_samples ) ) @@ -90,7 +91,7 @@ class LinodeNodeBalancerNode(LinodeModuleBase): """Module for managing Linode NodeBalancer nodes""" def __init__(self) -> None: - self.module_arg_spec = MODULE_SPEC + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results = dict( changed=False, diff --git a/plugins/modules/object_cluster_info.py b/plugins/modules/object_cluster_info.py index a5b5da72..4b969eb7 100644 --- a/plugins/modules/object_cluster_info.py +++ b/plugins/modules/object_cluster_info.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import List, Optional, Any +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import ObjectStorageKeys, ObjectStorageCluster from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -20,39 +21,39 @@ linode_object_cluster_info_spec = dict( # We need to overwrite attributes to exclude them as requirements - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict( - type='str', required=False, - description='The unique id given to the clusters.'), + id=SpecField( + type=FieldType.string, required=False, + description=['The unique id given to the clusters.']), - region=dict( - type='str', required=False, - description='The region the clusters are in.'), + region=SpecField( + type=FieldType.string, required=False, + description=['The region the clusters are in.']), - domain=dict( - type='str', required=False, - description='The domain of the clusters.'), + domain=SpecField( + type=FieldType.string, required=False, + description=['The domain of the clusters.']), - static_site_domain=dict( - type='str', required=False, - description='The static-site domain of the clusters.') + static_site_domain=SpecField( + type=FieldType.string, required=False, + description=['The static-site domain of the clusters.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode Object Storage Cluster.' ], requirements=global_requirements, author=global_authors, - spec=linode_object_cluster_info_spec, + options=linode_object_cluster_info_spec, examples=docs.specdoc_examples, return_values=dict( - clusters=dict( + clusters=SpecReturnValue( description='The Object Storage clusters in JSON serialized form.', docs_url='https://www.linode.com/docs/api/object-storage/#cluster-view__responses', - type='list', + type=FieldType.list, sample=docs.result_clusters_samples ) ) @@ -67,7 +68,7 @@ class LinodeObjectStorageClustersInfo(LinodeModuleBase): """Module for getting info about a Linode Object Storage Cluster""" def __init__(self) -> None: - self.module_arg_spec = linode_object_cluster_info_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results = dict( changed=False, diff --git a/plugins/modules/object_keys.py b/plugins/modules/object_keys.py index 4b49edd6..924fbdee 100644 --- a/plugins/modules/object_keys.py +++ b/plugins/modules/object_keys.py @@ -8,6 +8,7 @@ # pylint: disable=unused-import from typing import Optional, Union, List, Any +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import ObjectStorageKeys, ObjectStorageCluster from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase @@ -18,48 +19,48 @@ import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.object_keys as docs linode_access_spec = dict( - cluster=dict( - type='str', required=True, - description='The id of the cluster that the provided bucket exists under.'), + cluster=SpecField( + type=FieldType.string, required=True, + description=['The id of the cluster that the provided bucket exists under.']), - bucket_name=dict( - type='str', required=True, - description='The name of the bucket to set the key\'s permissions for.'), + bucket_name=SpecField( + type=FieldType.string, required=True, + description=['The name of the bucket to set the key\'s permissions for.']), - permissions=dict( - type='str', required=True, - description='The permissions to give the key.', + permissions=SpecField( + type=FieldType.string, required=True, + description=['The permissions to give the key.'], choices=['read_only', 'write_only', 'read_write']) ) linode_object_keys_spec = dict( - label=dict( - type='str', - description='The unique label to give this key.'), + label=SpecField( + type=FieldType.string, + description=['The unique label to give this key.']), - access=dict( - type='list', elements='dict', options=linode_access_spec, - description='A list of access permissions to give the key.'), + access=SpecField( + type=FieldType.list, element_type=FieldType.dict, suboptions=linode_access_spec, + description=['A list of access permissions to give the key.']), - state=dict(type='str', - description='The desired state of the target.', + state=SpecField(type=FieldType.string, + description=['The desired state of the target.'], choices=['present', 'absent'], required=True), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage Linode Object Storage Keys.' ], requirements=global_requirements, author=global_authors, - spec=linode_object_keys_spec, + options=linode_object_keys_spec, examples=docs.specdoc_examples, return_values=dict( - key=dict( + key=SpecReturnValue( description='The Object Storage key in JSON serialized form.', docs_url='https://www.linode.com/docs/api/object-storage/#object-storage' '-key-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_key_samples ) ) @@ -69,7 +70,7 @@ class LinodeObjectStorageKeys(LinodeModuleBase): """Module for creating and destroying Linode Object Storage Keys""" def __init__(self) -> None: - self.module_arg_spec = linode_object_keys_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of = ['state', 'label'] self.results = dict( changed=False, From 3bab054e5ce3d1296a8e8c732a6e9e9a2ffec603 Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 16:44:13 -0500 Subject: [PATCH 09/13] finally --- docs/inventory/instance.rst | 178 ++++++++++ docs/modules/profile_info.md | 59 ++++ docs/modules/ssh_key.md | 63 ++++ docs/modules/ssh_key_info.md | 60 ++++ docs/modules/ssh_key_list.md | 96 ++++++ docs/modules/stackscript.md | 96 ++++++ docs/modules/stackscript_info.md | 83 +++++ docs/modules/stackscript_list.md | 107 ++++++ docs/modules/token.md | 77 +++++ docs/modules/token_info.md | 62 ++++ docs/modules/type_list.md | 95 ++++++ docs/modules/user.md | 203 +++++++++++ docs/modules/user_info.md | 130 ++++++++ docs/modules/vlan_info.md | 56 ++++ docs/modules/vlan_list.md | 80 +++++ docs/modules/volume.md | 107 ++++++ docs/modules/volume_info.md | 69 ++++ plugins/modules/account_info.py | 5 +- plugins/modules/api_request.py | 10 +- plugins/modules/database_list.py | 6 +- plugins/modules/database_mysql.py | 14 +- plugins/modules/database_mysql_info.py | 15 +- plugins/modules/database_postgresql.py | 11 +- plugins/modules/database_postgresql_info.py | 15 +- plugins/modules/domain.py | 67 ++-- plugins/modules/domain_info.py | 9 +- plugins/modules/domain_record.py | 9 +- plugins/modules/domain_record_info.py | 10 +- plugins/modules/event_list.py | 9 +- plugins/modules/firewall.py | 9 +- plugins/modules/firewall_device.py | 4 +- plugins/modules/firewall_info.py | 9 +- plugins/modules/image.py | 8 +- plugins/modules/image_info.py | 10 +- plugins/modules/image_list.py | 34 +- plugins/modules/instance.py | 9 +- plugins/modules/instance_info.py | 9 +- plugins/modules/ip_info.py | 12 +- plugins/modules/ipv6_range_info.py | 7 +- plugins/modules/lke_cluster.py | 15 +- plugins/modules/lke_cluster_info.py | 10 +- plugins/modules/lke_node_pool.py | 9 +- plugins/modules/nodebalancer.py | 43 +-- plugins/modules/nodebalancer_info.py | 18 +- plugins/modules/nodebalancer_node.py | 18 +- plugins/modules/object_cluster_info.py | 9 +- plugins/modules/object_keys.py | 11 +- plugins/modules/profile_info.py | 20 +- plugins/modules/ssh_key.py | 35 +- plugins/modules/ssh_key_info.py | 29 +- plugins/modules/ssh_key_list.py | 50 +-- plugins/modules/stackscript.py | 65 ++-- plugins/modules/stackscript_info.py | 27 +- plugins/modules/stackscript_list.py | 70 ++-- plugins/modules/token.py | 40 ++- plugins/modules/token_info.py | 27 +- plugins/modules/type_list.py | 67 ++-- plugins/modules/user.py | 352 ++++++++++---------- plugins/modules/user_info.py | 27 +- plugins/modules/vlan_info.py | 23 +- plugins/modules/vlan_list.py | 73 ++-- plugins/modules/volume.py | 75 ++--- plugins/modules/volume_info.py | 28 +- scripts/render_readme.py | 2 +- 64 files changed, 2290 insertions(+), 765 deletions(-) create mode 100644 docs/inventory/instance.rst create mode 100644 docs/modules/profile_info.md create mode 100644 docs/modules/ssh_key.md create mode 100644 docs/modules/ssh_key_info.md create mode 100644 docs/modules/ssh_key_list.md create mode 100644 docs/modules/stackscript.md create mode 100644 docs/modules/stackscript_info.md create mode 100644 docs/modules/stackscript_list.md create mode 100644 docs/modules/token.md create mode 100644 docs/modules/token_info.md create mode 100644 docs/modules/type_list.md create mode 100644 docs/modules/user.md create mode 100644 docs/modules/user_info.md create mode 100644 docs/modules/vlan_info.md create mode 100644 docs/modules/vlan_list.md create mode 100644 docs/modules/volume.md create mode 100644 docs/modules/volume_info.md diff --git a/docs/inventory/instance.rst b/docs/inventory/instance.rst new file mode 100644 index 00000000..65ce04f0 --- /dev/null +++ b/docs/inventory/instance.rst @@ -0,0 +1,178 @@ +.. _instance_module: + + +instance +======== + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- + +Reads instance inventories from Linode. + +Uses a YAML configuration file that ends with linode.(yml|yaml). + +Linode labels are used by default as the hostnames. + +The default inventory groups are built from groups (deprecated by Linode) and not tags. + + + +Requirements +------------ +The below requirements are needed on the host that executes this module. + +- python >= 3 +- linode_api4 >= 2.0.0 + + + +Parameters +---------- + + **plugin (Required, type=any):** + \• Marks this as an instance of the 'linode' plugin + + \• Options: `linode`, `linode.cloud.instance` + + + **api_token (Required, type=any):** + \• The Linode account personal access token. + + + + **regions (type=list):** + \• Populate inventory with instances in this region. + + + **tags (type=list):** + \• Populate inventory only with instances which have at least one of the tags listed here. + + + **types (type=list):** + \• Populate inventory with instances with this type. + + + **strict (type=bool):** + \• If ``yes`` make invalid entries a fatal error, otherwise skip and continue. + + \• Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default. + + + **compose (type=dict):** + \• Create vars from jinja2 expressions. + + + **groups (type=dict):** + \• Add hosts to group based on Jinja2 conditionals. + + + **keyed_groups (type=list):** + \• Add hosts to group based on the values of a variable. + + + **parent_group (type=str):** + \• parent group for keyed group + + + **prefix (type=str):** + \• A keyed group name will start with this prefix + + + **separator (type=str, default=_):** + \• separator used to build the keyed group name + + + **key (type=str):** + \• The key from input dictionary used to generate groups + + + **default_value (type=str):** + \• The default value when the host variable's value is an empty string. + + \• This option is mutually exclusive with ``trailing_separator``. + + + **trailing_separator (type=bool, default=True):** + \• Set this option to *False* to omit the ``separator`` after the host variable when the value is an empty string. + + \• This option is mutually exclusive with ``default_value``. + + + + **use_extra_vars (type=bool):** + \• Merge extra vars into the available variables for composition (highest precedence). + + + **leading_separator (type=boolean, default=True):** + \• Use in conjunction with keyed_groups. + + \• By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore. + + \• This is because the default prefix is "" and the default separator is "_". + + \• Set this option to False to omit the leading underscore (or other separator) if no prefix is given. + + \• If the group name is derived from a mapping the separator is still used to concatenate the items. + + \• To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead. + + + + + + + +Examples +-------- + +.. code-block:: yaml+jinja + + + # Minimal example. `LINODE_API_TOKEN` is exposed in environment. + plugin: linode.cloud.instance + + # Example with regions, types, groups and access token + plugin: linode.cloud.instance + api_token: foobar + regions: + - eu-west + types: + - g5-standard-2 + + # Example with keyed_groups, groups, and compose + plugin: linode.cloud.instance + api_token: foobar + keyed_groups: + - key: tags + separator: '' + - key: region + prefix: region + groups: + webservers: "'web' in (tags|list)" + mailservers: "'mail' in (tags|list)" + compose: + ansible_port: 2222 + + + + + + +Status +------ + + + + + +Authors +~~~~~~~ + +- Luke Murphy (@decentral1se) +- Lena Garber (@LBGarber) + diff --git a/docs/modules/profile_info.md b/docs/modules/profile_info.md new file mode 100644 index 00000000..61551448 --- /dev/null +++ b/docs/modules/profile_info.md @@ -0,0 +1,59 @@ +# profile_info + +Get info about a Linode Profile. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about the current Linode profile + linode.cloud.profile_info: {} +``` + + + + + + + + + + +## Return Values + +- `profile` - The profile info in JSON serialized form. + + - Sample Response: + ```json + { + "authentication_type": "password", + "authorized_keys": [ + null + ], + "email": "example-user@gmail.com", + "email_notifications": true, + "ip_whitelist_enabled": false, + "lish_auth_method": "keys_only", + "referrals": { + "code": "871be32f49c1411b14f29f618aaf0c14637fb8d3", + "completed": 0, + "credit": 0, + "pending": 0, + "total": 0, + "url": "https://www.linode.com/?r=871be32f49c1411b14f29f618aaf0c14637fb8d3" + }, + "restricted": false, + "timezone": "US/Eastern", + "two_factor_auth": true, + "uid": 1234, + "username": "exampleUser", + "verified_phone_number": "+5555555555" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#profile-view__response-samples) for a list of returned fields + + diff --git a/docs/modules/ssh_key.md b/docs/modules/ssh_key.md new file mode 100644 index 00000000..820f6833 --- /dev/null +++ b/docs/modules/ssh_key.md @@ -0,0 +1,63 @@ +# ssh_key + +Manage a Linode SSH key. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a basic SSH key + linode.cloud.ssh_key: + label: my-ssh-key + state: present +``` + +```yaml +- name: Delete a SSH key + linode.cloud.ssh_key: + label: my-ssh-key + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| This SSH key's unique label. | +| `state` |
`str`
|
**Required**
| The state of this SSH key. **(Choices: `present`, `absent`)** | +| `ssh_key` |
`str`
|
Optional
| The SSH public key value. **(Updatable)** | + + + + + + +## Return Values + +- `ssh_key` - The created SSH key in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "id": 42, + "label": "My SSH Key", + "ssh_key": "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#ssh-key-add__response-samples) for a list of returned fields + + diff --git a/docs/modules/ssh_key_info.md b/docs/modules/ssh_key_info.md new file mode 100644 index 00000000..40930331 --- /dev/null +++ b/docs/modules/ssh_key_info.md @@ -0,0 +1,60 @@ +# ssh_key_info + +Get info about the Linode SSH public key. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about a SSH key by label + linode.cloud.ssh_key_info: + label: my-ssh-key +``` + +```yaml +- name: Get info about a SSH key by ID + linode.cloud.ssh_key_info: + id: 12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`int`
|
Optional
| The ID of the SSH key. | +| `label` |
`str`
|
Optional
| The label of the SSH key. | + + + + + + +## Return Values + +- `ssh_key` - The SSH key in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "id": 42, + "label": "My SSH Key", + "ssh_key": "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#ssh-key-view__response-samples) for a list of returned fields + + diff --git a/docs/modules/ssh_key_list.md b/docs/modules/ssh_key_list.md new file mode 100644 index 00000000..99e05dff --- /dev/null +++ b/docs/modules/ssh_key_list.md @@ -0,0 +1,96 @@ +# ssh_key_list + +List and filter on SSH keys in the Linode profile. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: List all of the SSH keys for the current Linode Account + linode.cloud.ssh_key_list: {} +``` + +```yaml +- name: List the latest 5 SSH keys for the current Linode Account + linode.cloud.ssh_key_list: + + count: 5 + order_by: created + order: desc +``` + +```yaml +- name: List filtered personal SSH keys for the current Linode Account + linode.cloud.ssh_key_list: + + filters: + - name: label-or-some-other-field + values: MySSHKey1 +``` + +```yaml +- name: List filtered personal SSH keys for the current Linode Account + linode.cloud.ssh_key_list: + filters: + - name: label-or-some-other-field + values: + - MySSHKey1 + - MySSHKey2 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `order` |
`str`
|
Optional
| The order to list ssh keys in. **(Choices: `desc`, `asc`; Default: `asc`)** | +| `order_by` |
`str`
|
Optional
| The attribute to order ssh keys by. | +| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting ssh keys. | +| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | + + + + + +### filters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/profile/#ssh-keys-list | +| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | + + + + + + +## Return Values + +- `ssh_keys` - The returned SSH keys. + + - Sample Response: + ```json + [ + { + "created": "2018-01-01T00:01:01", + "id": 42, + "label": "MySSHKey1", + "ssh_key": "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#ssh-keys-list) for a list of returned fields + + diff --git a/docs/modules/stackscript.md b/docs/modules/stackscript.md new file mode 100644 index 00000000..3b02852f --- /dev/null +++ b/docs/modules/stackscript.md @@ -0,0 +1,96 @@ +# stackscript + +Manage a Linode StackScript. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a basic StackScript + linode.cloud.stackscript: + label: my-stackscript + images: ['linode/ubuntu20.04'] + description: Install a system package + script: | + #!/bin/bash + # + apt-get -q update && apt-get -q -y install $PACKAGE + state: present +``` + +```yaml +- name: Delete a StackScript + linode.cloud.stackscript: + label: my-stackscript + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| This StackScript's unique label. | +| `state` |
`str`
|
**Required**
| The state of this StackScript. **(Choices: `present`, `absent`)** | +| `description` |
`str`
|
Optional
| A description for the StackScript. **(Updatable)** | +| `images` |
`list`
|
Optional
| Images that can be deployed using this StackScript. **(Updatable)** | +| `is_public` |
`bool`
|
Optional
| This determines whether other users can use your StackScript. **(Updatable)** | +| `rev_note` |
`str`
|
Optional
| This field allows you to add notes for the set of revisions made to this StackScript. **(Updatable)** | +| `script` |
`str`
|
Optional
| The script to execute when provisioning a new Linode with this StackScript. **(Updatable)** | + + + + + + +## Return Values + +- `stackscript` - The StackScript in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "deployments_active": 1, + "deployments_total": 12, + "description": "This StackScript installs and configures MySQL", + "id": 10079, + "images": [ + "linode/debian9", + "linode/debian8" + ], + "is_public": true, + "label": "a-stackscript", + "mine": true, + "rev_note": "Set up MySQL", + "script": "#!/bin/bash", + "updated": "2018-01-01T00:01:01", + "user_defined_fields": [ + { + "default": null, + "example": "hunter2", + "label": "Enter the password", + "manyOf": "avalue,anothervalue,thirdvalue", + "name": "DB_PASSWORD", + "oneOf": "avalue,anothervalue,thirdvalue" + } + ], + "user_gravatar_id": "a445b305abda30ebc766bc7fda037c37", + "username": "myuser" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/stackscripts/#stackscript-create__response-samples) for a list of returned fields + + diff --git a/docs/modules/stackscript_info.md b/docs/modules/stackscript_info.md new file mode 100644 index 00000000..7bf11310 --- /dev/null +++ b/docs/modules/stackscript_info.md @@ -0,0 +1,83 @@ +# stackscript_info + +Get info about a Linode StackScript. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about a StackScript by label + linode.cloud.stackscript_info: + label: my-stackscript +``` + +```yaml +- name: Get info about a StackScript by ID + linode.cloud.stackscript_info: + id: 12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`int`
|
Optional
| The ID of the StackScript. | +| `label` |
`str`
|
Optional
| The label of the StackScript. | + + + + + + +## Return Values + +- `stackscript` - The StackScript in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "deployments_active": 1, + "deployments_total": 12, + "description": "This StackScript installs and configures MySQL", + "id": 10079, + "images": [ + "linode/debian9", + "linode/debian8" + ], + "is_public": true, + "label": "a-stackscript", + "mine": true, + "rev_note": "Set up MySQL", + "script": "#!/bin/bash", + "updated": "2018-01-01T00:01:01", + "user_defined_fields": [ + { + "default": null, + "example": "hunter2", + "label": "Enter the password", + "manyOf": "avalue,anothervalue,thirdvalue", + "name": "DB_PASSWORD", + "oneOf": "avalue,anothervalue,thirdvalue" + } + ], + "user_gravatar_id": "a445b305abda30ebc766bc7fda037c37", + "username": "myuser" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/stackscripts/#stackscript-view__response-samples) for a list of returned fields + + diff --git a/docs/modules/stackscript_list.md b/docs/modules/stackscript_list.md new file mode 100644 index 00000000..4b2f8a56 --- /dev/null +++ b/docs/modules/stackscript_list.md @@ -0,0 +1,107 @@ +# stackscript_list + +List and filter on Linode stackscripts. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: List all of the stackscripts for the current Linode Account + linode.cloud.stackscript_list: {} +``` + +```yaml +- name: List the latest 5 stackscripts for the current Linode Account + linode.cloud.stackscript_list: + count: 5 + order_by: created + order: desc +``` + +```yaml +- name: List all personal stackscripts for the current Linode Account + linode.cloud.stackscript_list: + filter: + - name: mine + values: true +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `order` |
`str`
|
Optional
| The order to list events in. **(Choices: `desc`, `asc`; Default: `asc`)** | +| `order_by` |
`str`
|
Optional
| The attribute to order events by. | +| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting events. | +| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | + + + + + +### filters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/stackscripts/#stackscripts-list__response-samples | +| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | + + + + + + +## Return Values + +- `stackscripts` - The returned stackscripts. + + - Sample Response: + ```json + [ + { + "created": "2018-01-01T00:01:01", + "deployments_active": 1, + "deployments_total": 12, + "description": "This StackScript installs and configures MySQL\n", + "id": 10079, + "images": [ + "linode/debian9", + "linode/debian8" + ], + "is_public": true, + "label": "a-stackscript", + "mine": true, + "rev_note": "Set up MySQL", + "script": ""#!/bin/bash"\n", + "updated": "2018-01-01T00:01:01", + "user_defined_fields": [ + { + "default": null, + "example": "hunter2", + "label": "Enter the password", + "manyOf": "avalue,anothervalue,thirdvalue", + "name": "DB_PASSWORD", + "oneOf": "avalue,anothervalue,thirdvalue" + } + ], + "user_gravatar_id": "a445b305abda30ebc766bc7fda037c37", + "username": "myuser" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/stackscripts/#stackscripts-list__response-samples) for a list of returned fields + + diff --git a/docs/modules/token.md b/docs/modules/token.md new file mode 100644 index 00000000..2e7bf416 --- /dev/null +++ b/docs/modules/token.md @@ -0,0 +1,77 @@ +# token + +Manage a Linode Token. + +NOTE: The full Personal Access Token is only returned when a new token has been created. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a simple token + linode.cloud.token: + label: my-token + state: present +``` + +```yaml +- name: Create a token with expiry date and scopes + linode.cloud.token: + label: my-token + expiry: 2022-07-09T16:59:26 + scope: '*' + state: present +``` + +```yaml +- name: Delete a token + linode.cloud.token: + domain: my-token + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| This token's unique label. | +| `state` |
`str`
|
**Required**
| The state of this token. **(Choices: `present`, `absent`)** | +| `expiry` |
`str`
|
Optional
| When this token should be valid until. | +| `scopes` |
`str`
|
Optional
| The OAuth scopes to create the token with. | + + + + + + +## Return Values + +- `token` - The token in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "expiry": "2018-01-01T13:46:32", + "id": 123, + "label": "linode-cli", + "scopes": "*", + "token": "abcdefghijklmnop" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#personal-access-token-create__responses) for a list of returned fields + + diff --git a/docs/modules/token_info.md b/docs/modules/token_info.md new file mode 100644 index 00000000..dfabc4ac --- /dev/null +++ b/docs/modules/token_info.md @@ -0,0 +1,62 @@ +# token_info + +Get info about a Linode Personal Access Token. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about a token by label + linode.cloud.token_info: + label: my-token +``` + +```yaml +- name: Get info about a token by ID + linode.cloud.token_info: + id: 12345 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`int`
|
Optional
| The ID of the token. | +| `label` |
`str`
|
Optional
| The label of the token. | + + + + + + +## Return Values + +- `token` - The token in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "expiry": "2018-01-01T13:46:32", + "id": 123, + "label": "linode-cli", + "scopes": "*", + "token": "abcdefghijklmnop" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/profile/#personal-access-token-create__response-samples) for a list of returned fields + + diff --git a/docs/modules/type_list.md b/docs/modules/type_list.md new file mode 100644 index 00000000..b31ae893 --- /dev/null +++ b/docs/modules/type_list.md @@ -0,0 +1,95 @@ +# type_list + +List and filter on Linode Instance Types. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: List all of the Linode Instance Types + linode.cloud.type_list: {} +``` + +```yaml +- name: List a Linode Instance Type named Nanode 1GB + linode.cloud.type_list: + filter: + - name: label + values: Nanode 1GB + +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `order` |
`str`
|
Optional
| The order to list Instance Types in. **(Choices: `desc`, `asc`; Default: `asc`)** | +| `order_by` |
`str`
|
Optional
| The attribute to order Instance Types by. | +| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting Instance Types. | +| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | + + + + + +### filters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/linode-types/#types-list__response-samples | +| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | + + + + + + +## Return Values + +- `types` - The returned Instance Types. + + - Sample Response: + ```json + [ + { + "addons": { + "backups": { + "price": { + "hourly": 0.008, + "monthly": 5 + } + } + }, + "class": "standard", + "disk": 81920, + "gpus": 0, + "id": "g6-standard-2", + "label": "Linode 4GB", + "memory": 4096, + "network_out": 1000, + "price": { + "hourly": 0.03, + "monthly": 20 + }, + "successor": null, + "transfer": 4000, + "vcpus": 2 + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/linode-types/#types-list__response-samples) for a list of returned fields + + diff --git a/docs/modules/user.md b/docs/modules/user.md new file mode 100644 index 00000000..d6b59ba7 --- /dev/null +++ b/docs/modules/user.md @@ -0,0 +1,203 @@ +# user + +Manage a Linode User. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a basic user + linode.cloud.user: + username: my-cool-user + email: user@linode.com + restricted: false + state: present +``` + +```yaml +- name: Create a user that can only access Linodes + linode.cloud.user: + username: my-cool-user + email: user@linode.com + grants: + global: + add_linodes: true + resources: + - type: linode + id: 12345 + permissions: read_write + state: present +``` + +```yaml +- name: Delete a user + linode.cloud.user: + username: my-cool-user + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `username` |
`str`
|
**Required**
| The username of this user. | +| `state` |
`str`
|
**Required**
| The state of this user. **(Choices: `present`, `absent`)** | +| `restricted` |
`bool`
|
Optional
| If true, the User must be granted access to perform actions or access entities on this Account. **(Default: `True`; Updatable)** | +| `email` |
`str`
|
Optional
| The email address for the User. Linode sends emails to this address for account management communications. May be used for other communications as configured. | +| [`grants` (sub-options)](#grants) |
`dict`
|
Optional
| Update the grants a ser has. **(Updatable)** | + + + + + +### grants + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| [`global` (sub-options)](#global) |
`dict`
|
Optional
| A structure containing the Account-level grants a User has. **(Updatable)** | +| [`resources` (sub-options)](#resources) |
`list`
|
Optional
| A list of resource grants to give to the user. **(Updatable)** | + + + + + +### global + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `account_access` |
`str`
|
Optional
| The level of access this User has to Account-level actions, like billing information. A restricted User will never be able to manage users. **(Choices: `read_only`, `read_write`; Updatable)** | +| `add_databases` |
`bool`
|
Optional
| If true, this User may add Managed Databases. **(Default: `False`; Updatable)** | +| `add_domains` |
`bool`
|
Optional
| If true, this User may add Domains. **(Default: `False`; Updatable)** | +| `add_firewalls` |
`bool`
|
Optional
| If true, this User may add Firewalls. **(Default: `False`; Updatable)** | +| `add_images` |
`bool`
|
Optional
| If true, this User may add Images. **(Default: `False`; Updatable)** | +| `add_linodes` |
`bool`
|
Optional
| If true, this User may add Linodes. **(Default: `False`; Updatable)** | +| `add_longview` |
`bool`
|
Optional
| If true, this User may add Longview. **(Default: `False`; Updatable)** | +| `add_nodebalancers` |
`bool`
|
Optional
| If true, this User may add NodeBalancers. **(Default: `False`; Updatable)** | +| `add_stackscripts` |
`bool`
|
Optional
| If true, this User may add StackScripts. **(Default: `False`; Updatable)** | +| `add_volumes` |
`bool`
|
Optional
| If true, this User may add Volumes. **(Default: `False`; Updatable)** | +| `cancel_account` |
`bool`
|
Optional
| If true, this User may add cancel the entire account. **(Default: `False`; Updatable)** | +| `longview_subscription` |
`bool`
|
Optional
| If true, this User may manage the Account’s Longview subscription. **(Default: `False`; Updatable)** | + + + + + +### resources + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `type` |
`str`
|
**Required**
| The type of resource to grant access to. **(Choices: `domain`, `image`, `linode`, `longview`, `nodebalancer`, `stackscript`, `volume`, `database`; Updatable)** | +| `id` |
`int`
|
**Required**
| The ID of the resource to grant access to. **(Updatable)** | +| `permissions` |
`str`
|
**Required**
| The level of access this User has to this entity. If null, this User has no access. **(Choices: `read_only`, `read_write`; Updatable)** | + + + + + + +## Return Values + +- `user` - The user in JSON serialized form. + + - Sample Response: + ```json + { + "email": "example_user@linode.com", + "restricted": true, + "ssh_keys": [ + "home-pc", + "laptop" + ], + "tfa_enabled": null, + "username": "example_user" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#user-view__response-samples) for a list of returned fields + + +- `grants` - The grants info in JSON serialized form. + + - Sample Response: + ```json + { + "domain": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "global": { + "account_access": "read_only", + "add_databases": true, + "add_domains": true, + "add_firewalls": true, + "add_images": true, + "add_linodes": true, + "add_longview": true, + "add_nodebalancers": true, + "add_stackscripts": true, + "add_volumes": true, + "cancel_account": false, + "longview_subscription": true + }, + "image": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "linode": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "longview": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "nodebalancer": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "stackscript": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "volume": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ] + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#users-grants-view__response-samples) for a list of returned fields + + diff --git a/docs/modules/user_info.md b/docs/modules/user_info.md new file mode 100644 index 00000000..b51a0fa7 --- /dev/null +++ b/docs/modules/user_info.md @@ -0,0 +1,130 @@ +# user_info + +Get info about a Linode User. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about a user + linode.cloud.user_info: + username: my-cool-user +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `username` |
`str`
|
**Required**
| The username of the user. | + + + + + + +## Return Values + +- `user` - The user info in JSON serialized form. + + - Sample Response: + ```json + { + "email": "example_user@linode.com", + "restricted": true, + "ssh_keys": [ + "home-pc", + "laptop" + ], + "tfa_enabled": null, + "username": "example_user" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#user-view) for a list of returned fields + + +- `grants` - The grants info in JSON serialized form. + + - Sample Response: + ```json + { + "domain": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "global": { + "account_access": "read_only", + "add_databases": true, + "add_domains": true, + "add_firewalls": true, + "add_images": true, + "add_linodes": true, + "add_longview": true, + "add_nodebalancers": true, + "add_stackscripts": true, + "add_volumes": true, + "cancel_account": false, + "longview_subscription": true + }, + "image": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "linode": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "longview": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "nodebalancer": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "stackscript": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ], + "volume": [ + { + "id": 123, + "label": "example-entity", + "permissions": "read_only" + } + ] + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/account/#users-grants-view__response-samples) for a list of returned fields + + diff --git a/docs/modules/vlan_info.md b/docs/modules/vlan_info.md new file mode 100644 index 00000000..99da7804 --- /dev/null +++ b/docs/modules/vlan_info.md @@ -0,0 +1,56 @@ +# vlan_info + +Get info about a Linode VLAN. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Get info about a VLAN by label + linode.cloud.vlan_info: + label: example-vlan +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `label` |
`str`
|
**Required**
| The VLAN’s label. | + + + + + + +## Return Values + +- `vlan` - The VLAN in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2020-01-01T00:01:01", + "label": "vlan-example", + "linodes": [ + 111, + 222 + ], + "region": "ap-west" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#vlans-list__response-samples) for a list of returned fields + + diff --git a/docs/modules/vlan_list.md b/docs/modules/vlan_list.md new file mode 100644 index 00000000..0a43cd97 --- /dev/null +++ b/docs/modules/vlan_list.md @@ -0,0 +1,80 @@ +# vlan_list + +List and filter on Linode VLANs. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: List all of the VLANs for the current Linode Account + linode.cloud.vlan_list: {} +``` + +```yaml +- name: List all VLANs in the us-southeast region + linode.cloud.vlan_list: + filter: + - name: region + values: us-southeast + +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `order` |
`str`
|
Optional
| The order to list VLANs in. **(Choices: `desc`, `asc`; Default: `asc`)** | +| `order_by` |
`str`
|
Optional
| The attribute to order VLANs by. | +| [`filters` (sub-options)](#filters) |
`list`
|
Optional
| A list of filters to apply to the resulting VLANs. | +| `count` |
`int`
|
Optional
| The number of results to return. If undefined, all results will be returned. | + + + + + +### filters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `name` |
`str`
|
**Required**
| The name of the field to filter on. Valid filterable attributes can be found here: https://www.linode.com/docs/api/networking/#vlans-list__response-samples | +| `values` |
`list`
|
**Required**
| A list of values to allow for this field. Fields will pass this filter if at least one of these values matches. | + + + + + + +## Return Values + +- `vlans` - The returned VLANs. + + - Sample Response: + ```json + [ + { + "created": "2020-01-01T00:01:01", + "label": "vlan-example", + "linodes": [ + 111, + 222 + ], + "region": "ap-west" + } + ] + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/networking/#vlans-list__response-samples) for a list of returned fields + + diff --git a/docs/modules/volume.md b/docs/modules/volume.md new file mode 100644 index 00000000..718ebee9 --- /dev/null +++ b/docs/modules/volume.md @@ -0,0 +1,107 @@ +# volume + +Manage a Linode Volume. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- name: Create a volume attached to an instance + linode.cloud.volume: + label: example-volume + region: us-east + size: 30 + linode_id: 12345 + state: present +``` + +```yaml +- name: Create an unattached volume + linode.cloud.volume: + label: example-volume + region: us-east + size: 30 + state: present +``` + +```yaml +- name: Resize a volume + linode.cloud.volume: + label: example-volume + size: 50 + state: present +``` + +```yaml +- name: Detach a volume + linode.cloud.volume: + label: example-volume + attached: false + state: present +``` + +```yaml +- name: Delete a volume + linode.cloud.volume: + label: example-volume + state: absent +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `state` |
`str`
|
**Required**
| The desired state of the target. **(Choices: `present`, `absent`)** | +| `label` |
`str`
|
Optional
| The Volume’s label, which is also used in the filesystem_path of the resulting volume. | +| `config_id` |
`int`
|
Optional
| When creating a Volume attached to a Linode, the ID of the Linode Config to include the new Volume in. | +| `linode_id` |
`int`
|
Optional
| The Linode this volume should be attached to upon creation. If not given, the volume will be created without an attachment. **(Updatable)** | +| `region` |
`str`
|
Optional
| The location to deploy the volume in. See U(https://api.linode.com/v4/regions) | +| `size` |
`int`
|
Optional
| The size of this volume, in GB. Be aware that volumes may only be resized up after creation. **(Updatable)** | +| `attached` |
`bool`
|
Optional
| If true, the volume will be attached to a Linode. Otherwise, the volume will be detached. **(Default: `True`; Updatable)** | +| `wait_timeout` |
`int`
|
Optional
| The amount of time, in seconds, to wait for a volume to have the active status. **(Default: `240`)** | + + + + + + +## Return Values + +- `volume` - The volume in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "filesystem_path": "/dev/disk/by-id/scsi-0Linode_Volume_my-volume", + "hardware_type": "nvme", + "id": 12345, + "label": "my-volume", + "linode_id": 12346, + "linode_label": "linode123", + "region": "us-east", + "size": 30, + "status": "active", + "tags": [ + "example tag", + "another example" + ], + "updated": "2018-01-01T00:01:01" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/volumes/#volume-view__responses) for a list of returned fields + + diff --git a/docs/modules/volume_info.md b/docs/modules/volume_info.md new file mode 100644 index 00000000..8c7e52d5 --- /dev/null +++ b/docs/modules/volume_info.md @@ -0,0 +1,69 @@ +# volume_info + +Get info about a Linode Volume. + + +- [Examples](#examples) +- [Parameters](#parameters) +- [Return Values](#return-values) + +## Examples + +```yaml +- 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 +``` + + + + + + + + + + +## Parameters + +| Field | Type | Required | Description | +|-----------|------|----------|------------------------------------------------------------------------------| +| `id` |
`int`
|
Optional
| The ID of the Volume. Optional if `label` is defined. | +| `label` |
`str`
|
Optional
| The label of the Volume. Optional if `id` is defined. | + + + + + + +## Return Values + +- `volume` - The volume in JSON serialized form. + + - Sample Response: + ```json + { + "created": "2018-01-01T00:01:01", + "filesystem_path": "/dev/disk/by-id/scsi-0Linode_Volume_my-volume", + "hardware_type": "nvme", + "id": 12345, + "label": "my-volume", + "linode_id": 12346, + "linode_label": "linode123", + "region": "us-east", + "size": 30, + "status": "active", + "tags": [ + "example tag", + "another example" + ], + "updated": "2018-01-01T00:01:01" + } + ``` + - See the [Linode API response documentation](https://www.linode.com/docs/api/volumes/#volume-view__responses) for a list of returned fields + + diff --git a/plugins/modules/account_info.py b/plugins/modules/account_info.py index 69d00225..730cb583 100644 --- a/plugins/modules/account_info.py +++ b/plugins/modules/account_info.py @@ -9,15 +9,12 @@ from typing import List, Any, Optional from ansible_specdoc.objects import SpecDocMeta, SpecReturnValue, FieldType, SpecField -from linode_api4 import Volume +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.account_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.account_info as docs - spec = dict( # Disable the default values label=SpecField(type=FieldType.string, required=False, doc_hide=True), diff --git a/plugins/modules/api_request.py b/plugins/modules/api_request.py index a9d1fe82..e7458349 100644 --- a/plugins/modules/api_request.py +++ b/plugins/modules/api_request.py @@ -6,21 +6,17 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -import copy import json -from typing import Optional, cast, Any, Set, Tuple +from typing import Optional, Any, Tuple -import polling from ansible_specdoc.objects import SpecDocMeta, SpecReturnValue, FieldType, SpecField -from linode_api4 import StackScript, ApiError +from linode_api4 import ApiError +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.api_request as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.api_request as docs - SPEC = dict( label=SpecField(type=FieldType.string, doc_hide=True), state=SpecField(type=FieldType.string, doc_hide=True), diff --git a/plugins/modules/database_list.py b/plugins/modules/database_list.py index 425ab6f4..f00ed09c 100644 --- a/plugins/modules/database_list.py +++ b/plugins/modules/database_list.py @@ -10,13 +10,11 @@ from ansible_specdoc.objects import SpecDocMeta, SpecReturnValue, FieldType, SpecField +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_list as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values, construct_api_filter, get_all_paginated from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_list as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated spec_filter = dict( name=SpecField(type=FieldType.string, required=True, diff --git a/plugins/modules/database_mysql.py b/plugins/modules/database_mysql.py index a068e105..5cab121a 100644 --- a/plugins/modules/database_mysql.py +++ b/plugins/modules/database_mysql.py @@ -6,28 +6,22 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -import copy -import os -from typing import Optional, cast, Any, Set, Dict, Callable +from typing import Optional, Any, Set import polling -import requests from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue -from linode_api4 import LinodeClient, ApiError +from linode_api4 import ApiError from linode_api4.objects import MySQLDatabase +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_mysql as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_database_shared import \ validate_shared_db_input, call_protected_provisioning, SPEC_UPDATE_WINDOW - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ handle_updates, filter_null_values, paginated_list_to_json, mapping_to_dict, poll_condition -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_mysql as docs - SPEC = dict( label=SpecField( type=FieldType.string, @@ -83,7 +77,7 @@ ssl_connection=SpecField( type=FieldType.bool, description=['Whether to require SSL credentials to ' - 'establish a connection to the Managed Database.'], + 'establish a connection to the Managed Database.'], default=True, ), type=SpecField( diff --git a/plugins/modules/database_mysql_info.py b/plugins/modules/database_mysql_info.py index 2f20b678..94293c28 100644 --- a/plugins/modules/database_mysql_info.py +++ b/plugins/modules/database_mysql_info.py @@ -6,23 +6,22 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import List, Any, Optional +from typing import Any, Optional from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import MySQLDatabase +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_mysql \ + as docs_parent +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_mysql_info \ + as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_database_shared import \ call_protected_provisioning -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values, paginated_list_to_json, mapping_to_dict from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_mysql \ - as docs_parent -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_mysql_info \ - as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values, \ + paginated_list_to_json, mapping_to_dict spec = dict( # Disable the default values diff --git a/plugins/modules/database_postgresql.py b/plugins/modules/database_postgresql.py index 42d5abbb..0ec31fe0 100644 --- a/plugins/modules/database_postgresql.py +++ b/plugins/modules/database_postgresql.py @@ -6,25 +6,22 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import Optional, cast, Any, Set, Dict, Callable +from typing import Optional, Any, Set import polling from ansible_specdoc.objects import SpecField, SpecDocMeta, SpecReturnValue, FieldType -from linode_api4 import LinodeClient, ApiError, PostgreSQLDatabase +from linode_api4 import ApiError, PostgreSQLDatabase +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_postgresql \ + as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_database_shared import \ validate_shared_db_input, call_protected_provisioning, SPEC_UPDATE_WINDOW - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ handle_updates, filter_null_values, paginated_list_to_json, mapping_to_dict, poll_condition -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_postgresql \ - as docs - SPEC = dict( label=SpecField( type=FieldType.string, diff --git a/plugins/modules/database_postgresql_info.py b/plugins/modules/database_postgresql_info.py index b061357d..caabd170 100644 --- a/plugins/modules/database_postgresql_info.py +++ b/plugins/modules/database_postgresql_info.py @@ -6,23 +6,22 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import List, Any, Optional +from typing import Any, Optional from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import PostgreSQLDatabase +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_postgresql \ + as docs_parent +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments. \ + database_postgresql_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_database_shared import \ call_protected_provisioning -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values, paginated_list_to_json, mapping_to_dict from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.database_postgresql \ - as docs_parent -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.\ - database_postgresql_info as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values, \ + paginated_list_to_json, mapping_to_dict spec = dict( # Disable the default values diff --git a/plugins/modules/domain.py b/plugins/modules/domain.py index f78b275d..f768b647 100644 --- a/plugins/modules/domain.py +++ b/plugins/modules/domain.py @@ -6,64 +6,63 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import Optional, cast, Any, Set, List +from typing import Optional, Any, Set, List from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Domain +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.domain as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ - filter_null_values, paginated_list_to_json from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.domain as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + filter_null_values, paginated_list_to_json linode_domain_spec = dict( # Unused for domain objects label=SpecField(type=FieldType.string, required=False, doc_hide=True), axfr_ips=SpecField(type=FieldType.list, element_type=FieldType.string, editable=True, - description=['The list of IPs that may perform a zone transfer for this Domain.']), + description=['The list of IPs that may perform a zone transfer for this Domain.']), description=SpecField(type=FieldType.string, editable=True, - description=['The list of IPs that may perform a ' - 'zone transfer for this Domain.']), + description=['The list of IPs that may perform a ' + 'zone transfer for this Domain.']), domain=SpecField(type=FieldType.string, required=True, - description=['The domain this Domain represents.']), + description=['The domain this Domain represents.']), expire_sec=SpecField(type=FieldType.integer, editable=True, - description=['The amount of time in seconds that may pass' - ' before this Domain is no longer authoritative.']), + description=['The amount of time in seconds that may pass' + ' before this Domain is no longer authoritative.']), master_ips=SpecField(type=FieldType.list, element_type=FieldType.string, editable=True, - description=['The IP addresses representing the ' - 'master DNS for this Domain.']), + description=['The IP addresses representing the ' + 'master DNS for this Domain.']), refresh_sec=SpecField(type=FieldType.integer, editable=True, - description=['The amount of time in seconds before ' - 'this Domain should be refreshed.']), + description=['The amount of time in seconds before ' + 'this Domain should be refreshed.']), retry_sec=SpecField(type=FieldType.integer, editable=True, - description=['The interval, in seconds, at which a ' - 'failed refresh should be retried.']), + description=['The interval, in seconds, at which a ' + 'failed refresh should be retried.']), soa_email=SpecField(type=FieldType.string, - description=['The Start of Authority email address.'], - editable=True), + description=['The Start of Authority email address.'], + editable=True), status=SpecField(type=FieldType.string, - description=['Used to control whether this Domain is currently being rendered.'], - editable=True), + description=['Used to control whether this Domain is currently being rendered.'], + editable=True), state=SpecField(type=FieldType.string, - description=['The desired state of the target.'], - choices=['present', 'absent'], required=True), + description=['The desired state of the target.'], + choices=['present', 'absent'], required=True), tags=SpecField(type=FieldType.list, element_type=FieldType.string, editable=True, - description=['An array of tags applied to this object.']), + description=['An array of tags applied to this object.']), ttl_sec=SpecField(type=FieldType.integer, editable=True, - description=['The amount of time in seconds that this ' - 'Domain’s records may be cached by resolvers ' - 'or other domain servers.'] - ), + description=['The amount of time in seconds that this ' + 'Domain’s records may be cached by resolvers ' + 'or other domain servers.'] + ), type=SpecField(type=FieldType.string, - editable=True, - description=['Whether this Domain represents the authoritative ' - 'source of information for the domain' - ' it describes (master), or whether it is a ' - 'read-only copy of a master (slave).']), + editable=True, + description=['Whether this Domain represents the authoritative ' + 'source of information for the domain' + ' it describes (master), or whether it is a ' + 'read-only copy of a master (slave).']), # Deprecated group=SpecField(type=FieldType.string, doc_hide=True) @@ -175,7 +174,7 @@ def _update_domain(self) -> None: self.fail( 'failed to update domain {0}: {1} is a non-updatable field' - .format(self._domain.domain, key)) + .format(self._domain.domain, key)) if should_update: self._domain.save() diff --git a/plugins/modules/domain_info.py b/plugins/modules/domain_info.py index d9a93390..08ea7224 100644 --- a/plugins/modules/domain_info.py +++ b/plugins/modules/domain_info.py @@ -11,14 +11,13 @@ from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Domain +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.domain as docs_parent +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.domain_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - paginated_list_to_json from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.domain as docs_parent -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.domain_info as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ + paginated_list_to_json linode_domain_info_spec = dict( # We need to overwrite attributes to exclude them as requirements diff --git a/plugins/modules/domain_record.py b/plugins/modules/domain_record.py index 9c894531..820718a3 100644 --- a/plugins/modules/domain_record.py +++ b/plugins/modules/domain_record.py @@ -6,18 +6,17 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import Optional, cast, Any, Set, List +from typing import Optional, Any, Set, List from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Domain, DomainRecord +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.domain_record as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ - filter_null_values, paginated_list_to_json from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.domain_record as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + filter_null_values linode_domain_record_spec = dict( # Unused for domain record objects diff --git a/plugins/modules/domain_record_info.py b/plugins/modules/domain_record_info.py index ca19a9cd..0c41df43 100644 --- a/plugins/modules/domain_record_info.py +++ b/plugins/modules/domain_record_info.py @@ -11,16 +11,14 @@ from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Domain, DomainRecord -from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - paginated_list_to_json -from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ - global_requirements - import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.domain_record \ as docs_parent import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.domain_record_info \ as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase +from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ + global_requirements +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import paginated_list_to_json linode_domain_record_info_spec = dict( # We need to overwrite attributes to exclude them as requirements diff --git a/plugins/modules/event_list.py b/plugins/modules/event_list.py index d05478ee..d18f7c32 100644 --- a/plugins/modules/event_list.py +++ b/plugins/modules/event_list.py @@ -6,18 +6,15 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import List, Any, Optional, Dict +from typing import Any, Optional, Dict from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue -from linode_api4 import Image +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.event_list as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values, construct_api_filter, get_all_paginated from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.event_list as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated spec_filter = dict( name=SpecField(type=FieldType.string, required=True, diff --git a/plugins/modules/firewall.py b/plugins/modules/firewall.py index e6aca13a..94bbf1e5 100644 --- a/plugins/modules/firewall.py +++ b/plugins/modules/firewall.py @@ -6,18 +6,17 @@ from __future__ import absolute_import, division, print_function import copy -from typing import Optional, List, Any - import ipaddress +from typing import Optional, List, Any from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.firewall as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ - filter_null_values, mapping_to_dict, paginated_list_to_json, filter_null_values_recursive from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.firewall as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + filter_null_values, mapping_to_dict, paginated_list_to_json, filter_null_values_recursive try: from linode_api4 import Firewall, FirewallDevice diff --git a/plugins/modules/firewall_device.py b/plugins/modules/firewall_device.py index cc6752a5..b2d72f50 100644 --- a/plugins/modules/firewall_device.py +++ b/plugins/modules/firewall_device.py @@ -9,14 +9,12 @@ import linode_api4 from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue -from linode_api4 import Domain +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.firewall_device as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.firewall_device as docs - MODULE_SPEC = dict( firewall_id=SpecField( type=FieldType.integer, required=True, diff --git a/plugins/modules/firewall_info.py b/plugins/modules/firewall_info.py index 283c6717..c2019ac3 100644 --- a/plugins/modules/firewall_info.py +++ b/plugins/modules/firewall_info.py @@ -11,14 +11,13 @@ from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Firewall +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.firewall as docs_parent +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.firewall_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - paginated_list_to_json from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.firewall as docs_parent -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.firewall_info as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ + paginated_list_to_json linode_firewall_info_spec = dict( # We need to overwrite attributes to exclude them as requirements diff --git a/plugins/modules/image.py b/plugins/modules/image.py index 72402c0c..52702f89 100644 --- a/plugins/modules/image.py +++ b/plugins/modules/image.py @@ -6,25 +6,21 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -import copy import os -from typing import Optional, cast, Any, Set +from typing import Optional, Any, Set import polling import requests from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Image +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.image as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ handle_updates, filter_null_values -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.image as docs - SPEC = dict( label=SpecField( type=FieldType.string, diff --git a/plugins/modules/image_info.py b/plugins/modules/image_info.py index 5212049b..e1f6977d 100644 --- a/plugins/modules/image_info.py +++ b/plugins/modules/image_info.py @@ -6,19 +6,17 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import List, Any, Optional +from typing import Any, Optional from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Image +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.image as docs_parent +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.image_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.image as docs_parent -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.image_info as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values spec = dict( # Disable the default values diff --git a/plugins/modules/image_list.py b/plugins/modules/image_list.py index d9bed6f2..f0be4441 100644 --- a/plugins/modules/image_list.py +++ b/plugins/modules/image_list.py @@ -10,26 +10,24 @@ from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.image_list as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values, construct_api_filter, get_all_paginated from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.image_list as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated spec_filter = dict( name=SpecField(type=FieldType.string, required=True, - description=[ - 'The name of the field to filter on.', - 'Valid filterable attributes can be found here: ' - 'https://www.linode.com/docs/api/images/#images-list__responses', - ]), + description=[ + 'The name of the field to filter on.', + 'Valid filterable attributes can be found here: ' + 'https://www.linode.com/docs/api/images/#images-list__responses', + ]), values=SpecField(type=FieldType.list, element_type=FieldType.string, required=True, - description=[ - 'A list of values to allow for this field.', - 'Fields will pass this filter if at least one of these values matches.' - ]) + description=[ + 'A list of values to allow for this field.', + 'Fields will pass this filter if at least one of these values matches.' + ]) ) spec = dict( @@ -38,14 +36,14 @@ label=SpecField(type=FieldType.string, required=False, doc_hide=True), order=SpecField(type=FieldType.string, description=['The order to list events in.'], - default='asc', choices=['desc', 'asc']), + default='asc', choices=['desc', 'asc']), order_by=SpecField(type=FieldType.string, description=['The attribute to order events by.']), filters=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=spec_filter, - description=['A list of filters to apply to the resulting events.']), + description=['A list of filters to apply to the resulting events.']), count=SpecField(type=FieldType.integer, - description=[ - 'The number of results to return.', - 'If undefined, all results will be returned.']) + description=[ + 'The number of results to return.', + 'If undefined, all results will be returned.']) ) SPECDOC_META = SpecDocMeta( diff --git a/plugins/modules/instance.py b/plugins/modules/instance.py index 37d20436..909f2335 100644 --- a/plugins/modules/instance.py +++ b/plugins/modules/instance.py @@ -6,21 +6,20 @@ from __future__ import absolute_import, division, print_function import copy - from typing import Optional, Any, cast, Set, List, Dict, Union + import linode_api4 import polling from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.instance as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import \ LinodeModuleBase +from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ + global_requirements from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ filter_null_values, paginated_list_to_json, drop_empty_strings, mapping_to_dict, \ request_retry, filter_null_values_recursive -from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ - global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.instance as docs try: from linode_api4 import Instance, Config, ConfigInterface, Disk, Volume diff --git a/plugins/modules/instance_info.py b/plugins/modules/instance_info.py index a371383d..ada7f729 100644 --- a/plugins/modules/instance_info.py +++ b/plugins/modules/instance_info.py @@ -11,14 +11,13 @@ from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Instance +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.instance as docs_parent +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.instance_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - paginated_list_to_json from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.instance as docs_parent -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.instance_info as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ + paginated_list_to_json linode_instance_info_spec = dict( # We need to overwrite attributes to exclude them as requirements diff --git a/plugins/modules/ip_info.py b/plugins/modules/ip_info.py index 972d0f43..850fb860 100644 --- a/plugins/modules/ip_info.py +++ b/plugins/modules/ip_info.py @@ -6,18 +6,16 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import List, Any, Optional +from typing import Any, Optional from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue -from linode_api4 import Image, IPAddress +from linode_api4 import IPAddress +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.ip_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.ip_info as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values spec = dict( # Disable the default values @@ -25,7 +23,7 @@ label=SpecField(type=FieldType.string, required=False, doc_hide=True), address=SpecField(type=FieldType.string, required=True, - description=['The IP address to operate on.']), + description=['The IP address to operate on.']), ) SPECDOC_META = SpecDocMeta( diff --git a/plugins/modules/ipv6_range_info.py b/plugins/modules/ipv6_range_info.py index 54f3ddf2..80fc7cdb 100644 --- a/plugins/modules/ipv6_range_info.py +++ b/plugins/modules/ipv6_range_info.py @@ -6,17 +6,16 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import List, Any, Optional +from typing import Any, Optional from ansible_specdoc.objects import SpecField, FieldType, SpecReturnValue, SpecDocMeta from linode_api4 import IPv6Range +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.ipv6_range_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.ipv6_range_info as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values spec = dict( # Disable the default values diff --git a/plugins/modules/lke_cluster.py b/plugins/modules/lke_cluster.py index 4bf34d92..1b14fa75 100644 --- a/plugins/modules/lke_cluster.py +++ b/plugins/modules/lke_cluster.py @@ -7,21 +7,18 @@ # pylint: disable=unused-import import copy -from typing import Optional, cast, Any, Set, List, Dict - -from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue -from linode_api4 import LKECluster, LKENodePool, ApiError +from typing import Optional, Any, Set, List import polling +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue +from linode_api4 import LKECluster, ApiError +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.lke_cluster as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ - filter_null_values, paginated_list_to_json, jsonify_node_pool, validate_required, poll_condition from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.lke_cluster as docs - +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + filter_null_values, jsonify_node_pool, validate_required, poll_condition from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import handle_updates linode_lke_cluster_autoscaler = dict( diff --git a/plugins/modules/lke_cluster_info.py b/plugins/modules/lke_cluster_info.py index 933065e1..75330129 100644 --- a/plugins/modules/lke_cluster_info.py +++ b/plugins/modules/lke_cluster_info.py @@ -11,15 +11,13 @@ from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import LKECluster, ApiError -from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - jsonify_node_pool, filter_null_values -from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ - global_requirements - import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.lke_cluster \ as docs_parent import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.lke_cluster_info as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase +from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ + global_requirements +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import jsonify_node_pool, filter_null_values linode_lke_cluster_info_spec = dict( # We need to overwrite attributes to exclude them as requirements diff --git a/plugins/modules/lke_node_pool.py b/plugins/modules/lke_node_pool.py index 1034362b..aa87fabc 100644 --- a/plugins/modules/lke_node_pool.py +++ b/plugins/modules/lke_node_pool.py @@ -4,23 +4,20 @@ """This module contains all of the functionality for Linode LKE node pools.""" # pylint: disable=unused-import -import copy from typing import Optional, Any, List -import polling - import linode_api4 +import polling from ansible_specdoc.objects import FieldType, SpecField, SpecDocMeta, SpecReturnValue -from linode_api4 import LKENodePool, LKECluster, ApiError +from linode_api4 import LKENodePool +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.lke_node_pool as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ filter_null_values, jsonify_node_pool, handle_updates -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.lke_node_pool as docs - linode_lke_pool_autoscaler = dict( enabled=SpecField( type=FieldType.bool, editable=True, diff --git a/plugins/modules/nodebalancer.py b/plugins/modules/nodebalancer.py index bf2ab61a..722b3013 100644 --- a/plugins/modules/nodebalancer.py +++ b/plugins/modules/nodebalancer.py @@ -10,21 +10,15 @@ import linode_api4 from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue +# pylint: disable=unused-import +from linode_api4 import NodeBalancer, NodeBalancerConfig, NodeBalancerNode -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ - paginated_list_to_json, dict_select_matching, filter_null_values - +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.nodebalancer as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase - - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.nodebalancer as docs - -# pylint: disable=unused-import -from linode_api4 import NodeBalancer, NodeBalancerConfig, NodeBalancerNode, PaginatedList +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + paginated_list_to_json, dict_select_matching, filter_null_values linode_nodes_spec = dict( label=SpecField( @@ -59,7 +53,7 @@ check=SpecField( type=FieldType.string, required=False, editable=True, description=['The type of check to perform against backends to ensure they are ' - 'serving requests.'], + 'serving requests.'], choices=['none', 'connection', 'http', 'http_body']), check_attempts=SpecField( @@ -81,17 +75,17 @@ check_passive=SpecField( type='bool', required=False, editable=True, description=['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.']), + 'for it to be considered unhealthy and taken out of rotation.']), check_path=SpecField( type=FieldType.string, required=False, editable=True, description=['The URL path to check on each backend. If the backend does ' - 'not respond to this request it is considered to be down.']), + 'not respond to this request it is considered to be down.']), check_timeout=SpecField( type=FieldType.integer, required=False, editable=True, description=['How long, in seconds, to wait for a check attempt before considering it ' - 'failed.']), + 'failed.']), cipher_suite=SpecField( type=FieldType.string, required=False, default='recommended', editable=True, @@ -110,25 +104,25 @@ proxy_protocol=SpecField( type=FieldType.string, required=False, editable=True, description=['ProxyProtocol is a TCP extension that sends initial TCP connection ' - 'information such as source/destination IPs and ports to backend devices.'], + 'information such as source/destination IPs and ports to backend devices.'], choices=['none', 'v1', 'v2']), recreate=SpecField( type=FieldType.bool, required=False, default=False, description=['If true, the config will be forcibly recreated on every run. ' - 'This is useful for updates to redacted fields (`ssl_cert`, `ssl_key`)'] + 'This is useful for updates to redacted fields (`ssl_cert`, `ssl_key`)'] ), ssl_cert=SpecField( type=FieldType.string, required=False, editable=True, description=['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.']), + 'PEM-formatted SSL certificate and Certificate Authority chain) ' + 'that should be served on this NodeBalancerConfig’s port.']), ssl_key=SpecField( type=FieldType.string, required=False, editable=True, description=['The PEM-formatted private key for the SSL certificate ' - 'set in the ssl_cert field.']), + 'set in the ssl_cert field.']), stickiness=SpecField( type=FieldType.string, required=False, editable=True, @@ -138,7 +132,7 @@ nodes=SpecField( type=FieldType.list, required=False, element_type=FieldType.dict, suboptions=linode_nodes_spec, editable=True, description=['A list of nodes to apply to this config. ' - 'These can alternatively be configured through the nodebalancer_node module.']) + 'These can alternatively be configured through the nodebalancer_node module.']) ) linode_nodebalancer_spec = dict( @@ -161,15 +155,14 @@ ), state=SpecField(type=FieldType.string, - description=['The desired state of the target.'], - choices=['present', 'absent'], required=True), + description=['The desired state of the target.'], + choices=['present', 'absent'], required=True), configs=SpecField( type=FieldType.list, element_type=FieldType.dict, suboptions=linode_configs_spec, editable=True, description=['A list of configs to apply to the NodeBalancer.']) ) - SPECDOC_META = SpecDocMeta( description=[ 'Manage a Linode NodeBalancer.' @@ -426,7 +419,7 @@ def _update_nodebalancer(self) -> None: self.fail( 'failed to update nodebalancer {0}: {1} is a non-updatable field' - .format(self._node_balancer.label, key)) + .format(self._node_balancer.label, key)) if should_update: self._node_balancer.save() diff --git a/plugins/modules/nodebalancer_info.py b/plugins/modules/nodebalancer_info.py index bd6ec41c..62ff9cf5 100644 --- a/plugins/modules/nodebalancer_info.py +++ b/plugins/modules/nodebalancer_info.py @@ -8,20 +8,18 @@ from typing import List, Optional, Any from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue +# pylint: disable=unused-import +from linode_api4 import NodeBalancer, NodeBalancerConfig, NodeBalancerNode -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ - create_filter_and +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.nodebalancer \ + as docs_parent +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.nodebalancer_info \ + as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.nodebalancer\ - as docs_parent -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.nodebalancer_info\ - as docs - -# pylint: disable=unused-import -from linode_api4 import NodeBalancer, NodeBalancerConfig, NodeBalancerNode, PaginatedList, and_ +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + create_filter_and linode_nodebalancer_info_spec = dict( # We need to overwrite attributes to exclude them as requirements diff --git a/plugins/modules/nodebalancer_node.py b/plugins/modules/nodebalancer_node.py index b05d988e..71ff4a2e 100644 --- a/plugins/modules/nodebalancer_node.py +++ b/plugins/modules/nodebalancer_node.py @@ -7,30 +7,28 @@ # pylint: disable=unused-import import copy -from typing import Optional, cast, Any, Set, List +from typing import Optional, Any, Set, List import linode_api4 from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue -from linode_api4 import Domain +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.nodebalancer_node as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ - filter_null_values, paginated_list_to_json, handle_updates from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.nodebalancer_node as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + handle_updates MODULE_SPEC = dict( nodebalancer_id=SpecField( type=FieldType.integer, required=True, description=['The ID of the NodeBalancer that contains this node.'], - ), + ), config_id=SpecField( type=FieldType.integer, required=True, description=['The ID of the NodeBalancer Config that contains this node.'], - ), + ), label=SpecField( type=FieldType.string, required=True, @@ -40,7 +38,7 @@ address=SpecField( type=FieldType.string, editable=True, description=['The private IP Address where this backend can be reached. ' - 'This must be a private IP address.'], + 'This must be a private IP address.'], ), state=SpecField( @@ -187,7 +185,7 @@ def main() -> None: if __name__ == '__main__': main() -DOCUMENTATION=''' +DOCUMENTATION = ''' author: - Luke Murphy (@decentral1se) - Charles Kenney (@charliekenney23) diff --git a/plugins/modules/object_cluster_info.py b/plugins/modules/object_cluster_info.py index 4b969eb7..fe26de8e 100644 --- a/plugins/modules/object_cluster_info.py +++ b/plugins/modules/object_cluster_info.py @@ -9,15 +9,14 @@ from typing import List, Optional, Any from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue -from linode_api4 import ObjectStorageKeys, ObjectStorageCluster +from linode_api4 import ObjectStorageCluster +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.object_cluster_info \ + as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.object_cluster_info \ - as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and linode_object_cluster_info_spec = dict( # We need to overwrite attributes to exclude them as requirements diff --git a/plugins/modules/object_keys.py b/plugins/modules/object_keys.py index 924fbdee..874b42ae 100644 --- a/plugins/modules/object_keys.py +++ b/plugins/modules/object_keys.py @@ -9,15 +9,13 @@ from typing import Optional, Union, List, Any from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue -from linode_api4 import ObjectStorageKeys, ObjectStorageCluster +from linode_api4 import ObjectStorageKeys +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.object_keys as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.object_keys as docs - linode_access_spec = dict( cluster=SpecField( type=FieldType.string, required=True, @@ -43,8 +41,8 @@ description=['A list of access permissions to give the key.']), state=SpecField(type=FieldType.string, - description=['The desired state of the target.'], - choices=['present', 'absent'], required=True), + description=['The desired state of the target.'], + choices=['present', 'absent'], required=True), ) SPECDOC_META = SpecDocMeta( @@ -66,6 +64,7 @@ ) ) + class LinodeObjectStorageKeys(LinodeModuleBase): """Module for creating and destroying Linode Object Storage Keys""" diff --git a/plugins/modules/profile_info.py b/plugins/modules/profile_info.py index 119591c4..bdf55d16 100644 --- a/plugins/modules/profile_info.py +++ b/plugins/modules/profile_info.py @@ -8,34 +8,32 @@ # pylint: disable=unused-import from typing import List, Any, Optional -from linode_api4 import Volume +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.profile_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.profile_info as docs - spec = dict( # Disable the default values - label=dict(type='str', required=False, doc_hide=True), - state=dict(type='str', required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode Profile.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - profile=dict( + profile=SpecReturnValue( description='The profile info in JSON serialized form.', docs_url='https://www.linode.com/docs/api/profile/#profile-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_profile_samples ) ) @@ -51,7 +49,7 @@ def __init__(self) -> None: profile=None, ) - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec super().__init__(module_arg_spec=self.module_arg_spec, required_one_of=self.required_one_of) diff --git a/plugins/modules/ssh_key.py b/plugins/modules/ssh_key.py index 3a33eee6..feb36db3 100644 --- a/plugins/modules/ssh_key.py +++ b/plugins/modules/ssh_key.py @@ -7,50 +7,48 @@ from typing import Optional, Any +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import SSHKey +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.ssh_key as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ handle_updates -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.ssh_key as docs - ssh_key_spec = dict( - label=dict( - type='str', + label=SpecField( + type=FieldType.string, required=True, - description='This SSH key\'s unique label.'), - state=dict( - type='str', + description=['This SSH key\'s unique label.']), + state=SpecField( + type=FieldType.string, choices=['present', 'absent'], required=True, - description='The state of this SSH key.', + description=['The state of this SSH key.'], ), - ssh_key=dict( - type='str', + ssh_key=SpecField( + type=FieldType.string, editable=True, - description='The SSH public key value.' + description=['The SSH public key value.'] ) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage a Linode SSH key.' ], requirements=global_requirements, author=global_authors, - spec=ssh_key_spec, + options=ssh_key_spec, examples=docs.specdoc_examples, return_values=dict( - ssh_key=dict( + ssh_key=SpecReturnValue( description='The created SSH key in JSON serialized form.', docs_url='https://www.linode.com/docs/api/profile/' '#ssh-key-add__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_ssh_key_samples ) ) @@ -58,11 +56,12 @@ MUTABLE_FIELDS = {'label'} + class SSHKeyModule(LinodeModuleBase): """Module for creating and destroying Linode SSH keys""" def __init__(self) -> None: - self.module_arg_spec = ssh_key_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = dict( changed=False, actions=[], diff --git a/plugins/modules/ssh_key_info.py b/plugins/modules/ssh_key_info.py index 034fa9f5..2f0f848b 100644 --- a/plugins/modules/ssh_key_info.py +++ b/plugins/modules/ssh_key_info.py @@ -6,41 +6,40 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import List, Any, Optional +from typing import Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import SSHKey +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.ssh_key_info \ + as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.ssh_key_info \ - as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values linode_ssh_key_info_spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict(type='int', description='The ID of the SSH key.'), - label=dict(type='str', description='The label of the SSH key.'), + id=SpecField(type=FieldType.integer, description=['The ID of the SSH key.']), + label=SpecField(type=FieldType.string, description=['The label of the SSH key.']), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about the Linode SSH public key.' ], requirements=global_requirements, author=global_authors, - spec=linode_ssh_key_info_spec, + options=linode_ssh_key_info_spec, examples=docs.specdoc_examples, return_values=dict( - ssh_key=dict( + ssh_key=SpecReturnValue( description='The SSH key in JSON serialized form.', docs_url='https://www.linode.com/docs/api/profile/' '#ssh-key-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs.ssh_key_info_response_sample, ) ) @@ -51,7 +50,7 @@ class LinodeSSHKeyInfo(LinodeModuleBase): """Module for getting Linode SSH public key""" def __init__(self) -> None: - self.module_arg_spec = linode_ssh_key_info_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = { 'ssh_key': None } @@ -65,7 +64,7 @@ def _get_ssh_key_by_label(self, label: str) -> Optional[SSHKey]: ssh_keys = self.client.profile.ssh_keys(SSHKey.label == label) if not ssh_keys: return self.fail(msg=f'failed to get ssh key with label {label}: ' - 'ssh key does not exist') + 'ssh key does not exist') return ssh_keys[0] # maybe return whole list? except Exception as exception: return self.fail(msg=f'failed to get ssh key {label}: {exception}') diff --git a/plugins/modules/ssh_key_list.py b/plugins/modules/ssh_key_list.py index 645b1511..45aa8f3f 100644 --- a/plugins/modules/ssh_key_list.py +++ b/plugins/modules/ssh_key_list.py @@ -7,6 +7,8 @@ from typing import Any, Dict, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue + import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.ssh_key_list as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import ( LinodeModuleBase, @@ -21,8 +23,8 @@ ) spec_filter = dict( - name=dict( - type="str", + name=SpecField( + type=FieldType.string, required=True, description=[ "The name of the field to filter on.", @@ -33,9 +35,9 @@ ), ], ), - values=dict( - type="list", - elements="str", + values=SpecField( + type=FieldType.list, + element_type=FieldType.string, required=True, description=[ "A list of values to allow for this field.", @@ -46,23 +48,23 @@ spec = dict( # Disable the default values - state=dict(type="str", required=False, doc_hide=True), - label=dict(type="str", required=False, doc_hide=True), - order=dict( - type="str", - description="The order to list ssh keys in.", + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + order=SpecField( + type=FieldType.string, + description=["The order to list ssh keys in."], default="asc", choices=["desc", "asc"], ), - order_by=dict(type="str", description="The attribute to order ssh keys by."), - filters=dict( - type="list", - elements="dict", - options=spec_filter, - description="A list of filters to apply to the resulting ssh keys.", + order_by=SpecField(type=FieldType.string, description=["The attribute to order ssh keys by."]), + filters=SpecField( + type=FieldType.list, + element_type=FieldType.dict, + suboptions=spec_filter, + description=["A list of filters to apply to the resulting ssh keys."], ), - count=dict( - type="int", + count=SpecField( + type=FieldType.integer, description=[ "The number of results to return.", "If undefined, all results will be returned.", @@ -70,18 +72,18 @@ ), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=["List and filter on SSH keys in the Linode profile."], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.ssh_key_list_specdoc_examples, return_values=dict( - ssh_keys=dict( + ssh_keys=SpecReturnValue( description="The returned SSH keys.", docs_url=("https://www.linode.com/docs/api/profile/" "#ssh-keys-list"), - type="list", - elements="dict", + type=FieldType.list, + elements=FieldType.dict, sample=docs.result_ssh_key_list_samples, ) ), @@ -92,7 +94,7 @@ class SSHKeyListModule(LinodeModuleBase): """Module for getting a list of SSH keys in the Linode profile""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results: Dict[str, Any] = {"ssh_keys": []} super().__init__(module_arg_spec=self.module_arg_spec) diff --git a/plugins/modules/stackscript.py b/plugins/modules/stackscript.py index e9f6b854..9f24bb60 100644 --- a/plugins/modules/stackscript.py +++ b/plugins/modules/stackscript.py @@ -7,72 +7,69 @@ # pylint: disable=unused-import import copy -from typing import Optional, cast, Any, Set +from typing import Optional, Any -import polling +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import StackScript +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.stackscript as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ handle_updates, filter_null_values -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.stackscript as docs - SPEC = dict( - label=dict( - type='str', + label=SpecField( + type=FieldType.string, required=True, - description='This StackScript\'s unique label.'), - state=dict( - type='str', + description=['This StackScript\'s unique label.']), + state=SpecField( + type=FieldType.string, choices=['present', 'absent'], required=True, - description='The state of this StackScript.', + description=['The state of this StackScript.'], ), - description=dict( - type='str', editable=True, - description='A description for the StackScript.', + description=SpecField( + type=FieldType.string, editable=True, + description=['A description for the StackScript.'], ), - images=dict( - type='list', - elements='str', + images=SpecField( + type=FieldType.list, + element_type=FieldType.string, editable=True, - description='Images that can be deployed using this StackScript.', + description=['Images that can be deployed using this StackScript.'], ), - is_public=dict( - type='bool', editable=True, - description='This determines whether other users can use your StackScript.', + is_public=SpecField( + type=FieldType.bool, editable=True, + description=['This determines whether other users can use your StackScript.'], ), - rev_note=dict( - type='str', editable=True, - description='This field allows you to add notes for ' - 'the set of revisions made to this StackScript.', + rev_note=SpecField( + type=FieldType.string, editable=True, + description=['This field allows you to add notes for ' + 'the set of revisions made to this StackScript.'], ), - script=dict( - type='str', editable=True, - description='The script to execute when provisioning a new Linode with this StackScript.' + script=SpecField( + type=FieldType.string, editable=True, + description=['The script to execute when provisioning a new Linode with this StackScript.'] ) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage a Linode StackScript.' ], requirements=global_requirements, author=global_authors, - spec=SPEC, + options=SPEC, examples=docs.specdoc_examples, return_values=dict( - stackscript=dict( + stackscript=SpecReturnValue( description='The StackScript in JSON serialized form.', docs_url='https://www.linode.com/docs/api/stackscripts/' '#stackscript-create__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_stackscript_samples ) ) @@ -91,7 +88,7 @@ class Module(LinodeModuleBase): """Module for creating and destroying Linode StackScripts""" def __init__(self) -> None: - self.module_arg_spec = SPEC + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of = ['state', 'label'] self.results = dict( changed=False, diff --git a/plugins/modules/stackscript_info.py b/plugins/modules/stackscript_info.py index ba705d9e..d46e0c6d 100644 --- a/plugins/modules/stackscript_info.py +++ b/plugins/modules/stackscript_info.py @@ -6,39 +6,38 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import List, Any, Optional +from typing import Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import StackScript -from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values -from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ - global_requirements - import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.stackscript \ as docs_parent import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.stackscript_info \ as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase +from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ + global_requirements +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict(type='int', description='The ID of the StackScript.'), - label=dict(type='str', description='The label of the StackScript.'), + id=SpecField(type=FieldType.integer, description=['The ID of the StackScript.']), + label=SpecField(type=FieldType.string, description=['The label of the StackScript.']), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode StackScript.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - stackscript=dict( + stackscript=SpecReturnValue( description='The StackScript in JSON serialized form.', docs_url='https://www.linode.com/docs/api/stackscripts/' '#stackscript-view__response-samples', @@ -53,7 +52,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode StackScript""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = { 'stackscript': None } diff --git a/plugins/modules/stackscript_list.py b/plugins/modules/stackscript_list.py index b56c0731..3523b1c4 100644 --- a/plugins/modules/stackscript_list.py +++ b/plugins/modules/stackscript_list.py @@ -8,60 +8,60 @@ # pylint: disable=unused-import from typing import Any, Optional, Dict +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue + +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.stackscript_list as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values, construct_api_filter, get_all_paginated from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.stackscript_list as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated spec_filter = dict( - name=dict(type='str', required=True, - description=[ - 'The name of the field to filter on.', - 'Valid filterable attributes can be found here: ' - # pylint: disable-next=line-too-long - 'https://www.linode.com/docs/api/stackscripts/#stackscripts-list__response-samples', - ]), - values=dict(type='list', elements='str', required=True, - description=[ - 'A list of values to allow for this field.', - 'Fields will pass this filter if at least one of these values matches.' - ]) + name=SpecField(type=FieldType.string, required=True, + description=[ + 'The name of the field to filter on.', + 'Valid filterable attributes can be found here: ' + # pylint: disable-next=line-too-long + 'https://www.linode.com/docs/api/stackscripts/#stackscripts-list__response-samples', + ]), + values=SpecField(type=FieldType.list, element_type=FieldType.string, required=True, + description=[ + 'A list of values to allow for this field.', + 'Fields will pass this filter if at least one of these values matches.' + ]) ) spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), - - order=dict(type='str', description='The order to list events in.', - default='asc', choices=['desc', 'asc']), - order_by=dict(type='str', description='The attribute to order events by.'), - filters=dict(type='list', elements='dict', options=spec_filter, - description='A list of filters to apply to the resulting events.'), - count=dict(type='int', - description=[ - 'The number of results to return.', - 'If undefined, all results will be returned.']) + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + + order=SpecField(type=FieldType.string, description=['The order to list events in.'], + default='asc', choices=['desc', 'asc']), + order_by=SpecField(type=FieldType.string, description=['The attribute to order events by.']), + filters=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=spec_filter, + description=['A list of filters to apply to the resulting events.']), + count=SpecField(type=FieldType.integer, + description=[ + 'The number of results to return.', + 'If undefined, all results will be returned.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'List and filter on Linode stackscripts.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - stackscripts=dict( + stackscripts=SpecReturnValue( description='The returned stackscripts.', # pylint: disable-next=line-too-long docs_url='https://www.linode.com/docs/api/stackscripts/#stackscripts-list__response-samples', - type='list', - elements='dict', + type=FieldType.list, + elements=FieldType.dict, sample=docs.result_stackscripts_samples ) ) @@ -72,7 +72,7 @@ class Module(LinodeModuleBase): """Module for getting a list of Linode stackscripts""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results: Dict[str, Any] = { 'stackscripts': [] } @@ -85,7 +85,7 @@ def exec_module(self, **kwargs: Any) -> Optional[dict]: filter_dict = construct_api_filter(self.module.params) self.results['stackscripts'] = get_all_paginated(self.client, '/linode/stackscripts', - filter_dict, num_results=self.module.params['count']) + filter_dict, num_results=self.module.params['count']) return self.results diff --git a/plugins/modules/token.py b/plugins/modules/token.py index 6ea1e908..caaeb922 100644 --- a/plugins/modules/token.py +++ b/plugins/modules/token.py @@ -6,42 +6,40 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import Optional, cast, Any, Set +from typing import Optional, Any -import polling +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import PersonalAccessToken +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.token as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.token as docs - SPEC = dict( - label=dict( - type='str', + label=SpecField( + type=FieldType.string, required=True, - description='This token\'s unique label.'), - state=dict( - type='str', + description=['This token\'s unique label.']), + state=SpecField( + type=FieldType.string, choices=['present', 'absent'], required=True, - description='The state of this token.', + description=['The state of this token.'], ), - expiry=dict( - type='str', default=None, - description='When this token should be valid until.'), + expiry=SpecField( + type=FieldType.string, default=None, + description=['When this token should be valid until.']), - scopes=dict( - type='str', + scopes=SpecField( + type=FieldType.string, description=[ 'The OAuth scopes to create the token with.' ]), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage a Linode Token.', 'NOTE: The full Personal Access Token is only returned ' @@ -49,14 +47,14 @@ ], requirements=global_requirements, author=global_authors, - spec=SPEC, + options=SPEC, examples=docs.specdoc_examples, return_values=dict( - token=dict( + token=SpecReturnValue( description='The token in JSON serialized form.', docs_url='https://www.linode.com/docs/api/profile/' '#personal-access-token-create__responses', - type='dict', + type=FieldType.dict, sample=docs.result_token_samples ) ) @@ -67,7 +65,7 @@ class Module(LinodeModuleBase): """Module for creating and destroying Linode Tokens""" def __init__(self) -> None: - self.module_arg_spec = SPEC + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of = ['state', 'label'] self.results = dict( changed=False, diff --git a/plugins/modules/token_info.py b/plugins/modules/token_info.py index cb5be762..9f453106 100644 --- a/plugins/modules/token_info.py +++ b/plugins/modules/token_info.py @@ -6,41 +6,40 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import List, Any, Optional +from typing import Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import PersonalAccessToken +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.token as docs_parent +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.token_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.token as docs_parent -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.token_info as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict(type='int', description='The ID of the token.'), - label=dict(type='str', description='The label of the token.'), + id=SpecField(type=FieldType.integer, description=['The ID of the token.']), + label=SpecField(type=FieldType.string, description=['The label of the token.']), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode Personal Access Token.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - token=dict( + token=SpecReturnValue( description='The token in JSON serialized form.', docs_url='https://www.linode.com/docs/api/profile/' '#personal-access-token-create__response-samples', - type='dict', + type=FieldType.dict, sample=docs_parent.result_token_samples ) ) @@ -51,7 +50,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode token""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results = { 'token': None } diff --git a/plugins/modules/type_list.py b/plugins/modules/type_list.py index e8b1a033..a19f3250 100644 --- a/plugins/modules/type_list.py +++ b/plugins/modules/type_list.py @@ -8,58 +8,57 @@ # pylint: disable=unused-import from typing import Any, Optional, Dict -from ansible.module_utils.basic import env_fallback +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue + +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.type_list as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values, construct_api_filter, get_all_paginated from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.type_list as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated spec_filter = dict( - name=dict(type='str', required=True, - description=[ - 'The name of the field to filter on.', - 'Valid filterable attributes can be found here: ' - 'https://www.linode.com/docs/api/linode-types/#types-list__response-samples', - ]), - values=dict(type='list', elements='str', required=True, - description=[ - 'A list of values to allow for this field.', - 'Fields will pass this filter if at least one of these values matches.' - ]) + name=SpecField(type=FieldType.string, required=True, + description=[ + 'The name of the field to filter on.', + 'Valid filterable attributes can be found here: ' + 'https://www.linode.com/docs/api/linode-types/#types-list__response-samples', + ]), + values=SpecField(type=FieldType.list, element_type=FieldType.string, required=True, + description=[ + 'A list of values to allow for this field.', + 'Fields will pass this filter if at least one of these values matches.' + ]) ) spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), - order=dict(type='str', description='The order to list Instance Types in.', - default='asc', choices=['desc', 'asc']), - order_by=dict(type='str', description='The attribute to order Instance Types by.'), - filters=dict(type='list', elements='dict', options=spec_filter, - description='A list of filters to apply to the resulting Instance Types.'), - count=dict(type='int', - description=[ - 'The number of results to return.', - 'If undefined, all results will be returned.']) + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + order=SpecField(type=FieldType.string, description=['The order to list Instance Types in.'], + default='asc', choices=['desc', 'asc']), + order_by=SpecField(type=FieldType.string, description=['The attribute to order Instance Types by.']), + filters=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=spec_filter, + description=['A list of filters to apply to the resulting Instance Types.']), + count=SpecField(type=FieldType.integer, + description=[ + 'The number of results to return.', + 'If undefined, all results will be returned.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'List and filter on Linode Instance Types.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - types=dict( + types=SpecReturnValue( description='The returned Instance Types.', docs_url='https://www.linode.com/docs/api/linode-types/#types-list__response-samples', - type='list', - elements='dict', + type=FieldType.list, + elements=FieldType.dict, sample=docs.result_type_samples ) ) @@ -70,7 +69,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode Instance Types""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results: Dict[str, Any] = { 'types': [] } @@ -83,7 +82,7 @@ def exec_module(self, **kwargs: Any) -> Optional[dict]: filter_dict = construct_api_filter(self.module.params) self.results['types'] = get_all_paginated(self.client, '/linode/types', filter_dict, - num_results=self.module.params['count']) + num_results=self.module.params['count']) return self.results diff --git a/plugins/modules/user.py b/plugins/modules/user.py index 171cfdc4..091bf709 100644 --- a/plugins/modules/user.py +++ b/plugins/modules/user.py @@ -6,209 +6,201 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -import copy -from typing import Optional, cast, Any, Set, Dict, List +from typing import Optional, Any, Dict, List -import polling +from ansible_specdoc.objects import SpecDocMeta, SpecReturnValue, FieldType, SpecField from linode_api4 import User +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.user as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.user as docs - from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ handle_updates, filter_null_values SPEC_GRANTS_GLOBAL = { - 'account_access': { - 'type:': 'str', - 'choices': ['read_only', 'read_write'], - 'description': [ - 'The level of access this User has to Account-level actions, ' - 'like billing information.', - 'A restricted User will never be able to manage users.'], - 'default': None, - 'editable': True, - }, - 'add_databases': { - 'type': 'bool', - 'description': 'If true, this User may add Managed Databases.', - 'default': False, - 'editable': True, - }, - 'add_domains': { - 'type': 'bool', - 'description': 'If true, this User may add Domains.', - 'default': False, - 'editable': True, - }, - 'add_firewalls': { - 'type': 'bool', - 'description': 'If true, this User may add firewalls.', - 'default': False, - 'editable': True, - }, - 'add_images': { - 'type': 'bool', - 'description': 'If true, this User may add images.', - 'default': False, - 'editable': True, - }, - 'add_linodes': { - 'type': 'bool', - 'description': 'If true, this User may add Linodes.', - 'default': False, - 'editable': True, - }, - 'add_longview': { - 'type': 'bool', - 'description': 'If true, this User may add LongView.', - 'default': False, - 'editable': True, - }, - 'add_nodebalancers': { - 'type': 'bool', - 'description': 'If true, this User may add NodeBalancers.', - 'default': False, - 'editable': True, - }, - 'add_stackscripts': { - 'type': 'bool', - 'description': 'If true, this User may add StackScripts.', - 'default': False, - 'editable': True, - }, - 'add_volumes': { - 'type': 'bool', - 'description': 'If true, this User may add volumes.', - 'default': False, - 'editable': True, - }, - 'cancel_account': { - 'type': 'bool', - 'description': 'If true, this User may add cancel the entire account.', - 'default': False, - 'editable': True, - }, - 'longview_subscription': { - 'type': 'bool', - 'description': 'If true, this User may manage the Account’s ' - 'Longview subscription.', - 'default': False, - 'editable': True, - }, + 'account_access': SpecField( + type=FieldType.string, + choices=['read_only', 'read_write'], + description=['The level of access this User has to Account-level actions, ' + 'like billing information.', + 'A restricted User will never be able to manage users.'], + default=None, + editable=True, + ), + 'add_databases': SpecField( + type=FieldType.bool, + description=['If true, this User may add Managed Databases.'], + default=False, + editable=True, + ), + 'add_domains': SpecField( + type=FieldType.bool, + description=['If true, this User may add Domains.'], + default=False, + editable=True, + ), + 'add_firewalls': SpecField( + type=FieldType.bool, + description=['If true, this User may add Firewalls.'], + default=False, + editable=True, + ), + 'add_images': SpecField( + type=FieldType.bool, + description=['If true, this User may add Images.'], + default=False, + editable=True, + ), + 'add_linodes': SpecField( + type=FieldType.bool, + description=['If true, this User may add Linodes.'], + default=False, + editable=True, + ), + 'add_longview': SpecField( + type=FieldType.bool, + description=['If true, this User may add Longview.'], + default=False, + editable=True, + ), + 'add_nodebalancers': SpecField( + type=FieldType.bool, + description=['If true, this User may add NodeBalancers.'], + default=False, + editable=True, + ), + 'add_stackscripts': SpecField( + type=FieldType.bool, + description=['If true, this User may add StackScripts.'], + default=False, + editable=True, + ), + 'add_volumes': SpecField( + type=FieldType.bool, + description=['If true, this User may add Volumes.'], + default=False, + editable=True, + ), + 'cancel_account': SpecField( + type=FieldType.bool, + description=['If true, this User may add cancel the entire account.'], + default=False, + editable=True, + ), + 'longview_subscription': SpecField( + type=FieldType.bool, + description=['If true, this User may manage the Account’s ' + 'Longview subscription.'], + default=False, + editable=True, + ), } SPEC_GRANTS_RESOURCE = { - 'type': { - 'type:': 'str', - 'choices': ['domain', 'image', 'linode', 'longview', - 'nodebalancer', 'stackscript', 'volume'], - 'description': [ - 'The type of resource to grant access to.'], - 'required': True, - 'editable': True, - }, - 'id': { - 'type': 'int', - 'description': 'The ID of the resource to grant access to.', - 'required': True, - 'editable': True, - }, - 'permissions': { - 'type': 'str', - 'choices': ['read_only', 'read_write'], - 'description': 'The level of access this User has to this entity. ' - 'If null, this User has no access.', - 'required': True, - 'editable': True, - }, + 'type': SpecField( + type=FieldType.string, + choices=['domain', 'image', 'linode', 'longview', 'nodebalancer', 'stackscript', 'volume', 'database'], + description=['The type of resource to grant access to.'], + required=True, + editable=True + ), + 'id': SpecField( + type=FieldType.integer, + description=['The ID of the resource to grant access to.'], + required=True, + editable=True + ), + 'permissions': SpecField( + type=FieldType.string, + choices=['read_only', 'read_write'], + description=['The level of access this User has to this entity. ' + 'If null, this User has no access.'], + required=True, + editable=True + ) } SPEC_GRANTS = { - 'global': { - 'type': 'dict', - 'description': 'A structure containing the Account-level grants a User has.', - 'options': SPEC_GRANTS_GLOBAL, - 'editable': True, - }, - 'resources': { - 'description': 'A list of resource grants to give to the user.', - 'type': 'list', - 'elements': 'dict', - 'options': SPEC_GRANTS_RESOURCE, - 'editable': True, - } + 'global': SpecField( + type=FieldType.dict, + description=['A structure containing the Account-level grants a User has.'], + suboptions=SPEC_GRANTS_GLOBAL, + editable=True, + ), + 'resources': SpecField( + type=FieldType.list, + element_type=FieldType.dict, + editable=True, + suboptions=SPEC_GRANTS_RESOURCE, + description=['A list of resource grants to give to the user.'] + ) } SPEC = { # We don't use label for this module - 'label': { - 'type': 'str', - 'required': False, - 'doc_hide': True - }, - 'username': { - 'type': 'str', - 'required': True, - 'description': 'The username of this user.', - }, - 'state': { - 'type': 'str', - 'choices': ['present', 'absent'], - 'required': True, - 'description': 'The state of this user.', - }, - 'restricted': { - 'type': 'bool', - 'description': 'If true, the User must be granted access to perform ' - 'actions or access entities on this Account.', - 'default': True, - 'editable': True, - }, - 'email': { - 'type': 'str', - 'description': ['The email address for the User.', - 'Linode sends emails to this address for account ' - 'management communications.', - 'May be used for other communications as configured.'] - }, - 'grants': { - 'type': 'dict', - 'description': 'Update the grants a User has.', - 'options': SPEC_GRANTS, - 'editable': True, - } + 'label': SpecField( + type=FieldType.string, + doc_hide=True, + ), + + 'username': SpecField( + type=FieldType.string, + required=True, + description=['The username of this user.'] + ), + 'state': SpecField( + type=FieldType.string, + choices=['present', 'absent'], + required=True, + description=['The state of this user.'] + ), + 'restricted': SpecField( + type=FieldType.bool, + description=['If true, the User must be granted access to perform ' + 'actions or access entities on this Account.'], + default=True, + editable=True, + ), + 'email': SpecField( + type=FieldType.string, + description=['The email address for the User.', + 'Linode sends emails to this address for account ' + 'management communications.', + 'May be used for other communications as configured.'] + ), + 'grants': SpecField( + type=FieldType.dict, + description=['Update the grants a ser has.'], + suboptions=SPEC_GRANTS, + editable=True, + ) } -specdoc_meta = { - 'description': [ +SPECDOC_META = SpecDocMeta( + description=[ 'Manage a Linode User.' ], - 'requirements': global_requirements, - 'author': global_authors, - 'spec': SPEC, - 'examples': docs.specdoc_examples, - 'return_values': { - 'user': { - 'description': 'The user in JSON serialized form.', - 'docs_url': 'https://www.linode.com/docs/api/account/' - '#user-view__response-samples', - 'type': 'dict', - 'sample': docs.result_user_samples - }, - 'grants': { - 'description': 'The grants info in JSON serialized form.', - 'docs_url': 'https://www.linode.com/docs/api/account/' - '#users-grants-view__response-samples', - 'type': 'dict', - 'sample': docs.result_grants_samples - } - } -} + requirements=global_requirements, + author=global_authors, + options=SPEC, + examples=docs.specdoc_examples, + return_values=dict( + user=SpecReturnValue( + description='The user in JSON serialized form.', + docs_url='https://www.linode.com/docs/api/account/#user-view__response-samples', + type=FieldType.dict, + sample=docs.result_user_samples + ), + grants=SpecReturnValue( + description='The grants info in JSON serialized form.', + docs_url='https://www.linode.com/docs/api/account/' + '#users-grants-view__response-samples', + type=FieldType.dict, + sample=docs.result_grants_samples + ) + ) +) MUTABLE_FIELDS = { 'restricted' @@ -219,7 +211,7 @@ class Module(LinodeModuleBase): """Module for creating and destroying Linode Users""" def __init__(self) -> None: - self.module_arg_spec = SPEC + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of = ['state', 'username'] self.results = dict( changed=False, diff --git a/plugins/modules/user_info.py b/plugins/modules/user_info.py index 412c4bcd..55cec55f 100644 --- a/plugins/modules/user_info.py +++ b/plugins/modules/user_info.py @@ -8,43 +8,42 @@ # pylint: disable=unused-import from typing import List, Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import User +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.user_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.user_info as docs - spec = dict( # Disable the default values - label=dict(type='str', required=False, doc_hide=True), - state=dict(type='str', required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - username=dict(type='str', required=True, - description='The username of the user.') + username=SpecField(type=FieldType.string, required=True, + description=['The username of the user.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode User.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - user=dict( + user=SpecReturnValue( description='The user info in JSON serialized form.', docs_url='https://www.linode.com/docs/api/account/#user-view', - type='dict', + type=FieldType.dict, sample=docs.result_user_samples ), - grants=dict( + grants=SpecReturnValue( description='The grants info in JSON serialized form.', docs_url='https://www.linode.com/docs/api/account/#users-grants-view__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_grants_samples ) ) @@ -60,7 +59,7 @@ def __init__(self) -> None: user=None, ) - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec super().__init__(module_arg_spec=self.module_arg_spec, required_one_of=self.required_one_of) diff --git a/plugins/modules/vlan_info.py b/plugins/modules/vlan_info.py index 9eab5353..0091da0f 100644 --- a/plugins/modules/vlan_info.py +++ b/plugins/modules/vlan_info.py @@ -8,37 +8,36 @@ # pylint: disable=unused-import from typing import List, Optional, Any +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import VLAN +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.vlan_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.vlan_info as docs - linode_vlan_info_spec = dict( # We need to overwrite attributes to exclude them as requirements - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - label=dict( - type='str', required=True, - description='The VLAN’s label.') + label=SpecField( + type=FieldType.string, required=True, + description=['The VLAN’s label.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode VLAN.' ], requirements=global_requirements, author=global_authors, - spec=linode_vlan_info_spec, + options=linode_vlan_info_spec, examples=docs.specdoc_examples, return_values=dict( - vlan=dict( + vlan=SpecReturnValue( description='The VLAN in JSON serialized form.', docs_url='https://www.linode.com/docs/api/networking/#vlans-list__response-samples', - type='dict', + type=FieldType.dict, sample=docs.result_vlan_samples ) ) @@ -49,7 +48,7 @@ class LinodeVLANInfo(LinodeModuleBase): """Module for getting info about a Linode VLAN""" def __init__(self) -> None: - self.module_arg_spec = linode_vlan_info_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results = dict( vlan=None, diff --git a/plugins/modules/vlan_list.py b/plugins/modules/vlan_list.py index fe29403a..f624fd2b 100644 --- a/plugins/modules/vlan_list.py +++ b/plugins/modules/vlan_list.py @@ -8,66 +8,57 @@ # pylint: disable=unused-import from typing import Any, Optional, Dict -from linode_api4 import VLAN +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue -from ansible.module_utils.basic import env_fallback +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.vlan_list as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and, \ - filter_null_values, construct_api_filter, get_all_paginated from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.vlan_list as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated spec_filter = dict( - name=dict(type='str', required=True, - description=[ - 'The name of the field to filter on.', - 'Valid filterable attributes can be found here: ' - 'https://www.linode.com/docs/api/networking/#vlans-list__response-samples', - ]), - values=dict(type='list', elements='str', required=True, - description=[ - 'A list of values to allow for this field.', - 'Fields will pass this filter if at least one of these values matches.' - ]) + name=SpecField(type=FieldType.string, required=True, + description=[ + 'The name of the field to filter on.', + 'Valid filterable attributes can be found here: ' + 'https://www.linode.com/docs/api/networking/#vlans-list__response-samples', + ]), + values=SpecField(type=FieldType.list, element_type=FieldType.string, required=True, + description=[ + 'A list of values to allow for this field.', + 'Fields will pass this filter if at least one of these values matches.' + ]) ) spec = dict( # Disable the default values - state=dict(type='str', required=False, doc_hide=True), - label=dict(type='str', required=False, doc_hide=True), - api_version=dict( - type='str', - fallback=(env_fallback, ['LINODE_API_VERSION']), - default='v4beta', - doc_hide=True, - ), - order=dict(type='str', description='The order to list VLANs in.', - default='asc', choices=['desc', 'asc']), - order_by=dict(type='str', description='The attribute to order VLANs by.'), - filters=dict(type='list', elements='dict', options=spec_filter, - description='A list of filters to apply to the resulting VLANs.'), - count=dict(type='int', - description=[ - 'The number of results to return.', - 'If undefined, all results will be returned.']) + state=SpecField(type=FieldType.string, required=False, doc_hide=True), + label=SpecField(type=FieldType.string, required=False, doc_hide=True), + order=SpecField(type=FieldType.string, description=['The order to list VLANs in.'], + default='asc', choices=['desc', 'asc']), + order_by=SpecField(type=FieldType.string, description=['The attribute to order VLANs by.']), + filters=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=spec_filter, + description=['A list of filters to apply to the resulting VLANs.']), + count=SpecField(type=FieldType.integer, + description=[ + 'The number of results to return.', + 'If undefined, all results will be returned.']) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'List and filter on Linode VLANs.' ], requirements=global_requirements, author=global_authors, - spec=spec, + options=spec, examples=docs.specdoc_examples, return_values=dict( - vlans=dict( + vlans=SpecReturnValue( description='The returned VLANs.', docs_url='https://www.linode.com/docs/api/networking/#vlans-list__response-samples', - type='list', - elements='dict', + type=FieldType.list, + elements=FieldType.dict, sample=docs.result_vlan_samples ) ) @@ -78,7 +69,7 @@ class Module(LinodeModuleBase): """Module for getting info about a Linode VLANs""" def __init__(self) -> None: - self.module_arg_spec = spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.results: Dict[str, Any] = { 'vlans': [] } @@ -91,7 +82,7 @@ def exec_module(self, **kwargs: Any) -> Optional[dict]: filter_dict = construct_api_filter(self.module.params) self.results['vlans'] = get_all_paginated(self.client, '/networking/vlans', filter_dict, - num_results=self.module.params['count']) + num_results=self.module.params['count']) return self.results diff --git a/plugins/modules/volume.py b/plugins/modules/volume.py index 37ad50fa..8255eb23 100644 --- a/plugins/modules/volume.py +++ b/plugins/modules/volume.py @@ -6,79 +6,78 @@ from __future__ import absolute_import, division, print_function # pylint: disable=unused-import -from typing import Optional, cast, Any, Set +from typing import Optional, Any, Set import polling +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Volume +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.volume as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase - from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.volume as docs - linode_volume_spec = dict( - label=dict( - type='str', - description='The Volume’s label, which is also used in the ' - 'filesystem_path of the resulting volume.'), - - config_id=dict( - type='int', default=None, - description='When creating a Volume attached to a Linode, the ID of the Linode Config ' - 'to include the new Volume in.'), - - linode_id=dict( - type='int', default=None, editable=True, + label=SpecField( + type=FieldType.string, + description=['The Volume’s label, which is also used in the ' + 'filesystem_path of the resulting volume.']), + + config_id=SpecField( + type=FieldType.integer, default=None, + description=['When creating a Volume attached to a Linode, the ID of the Linode Config ' + 'to include the new Volume in.']), + + linode_id=SpecField( + type=FieldType.integer, default=None, editable=True, description=[ 'The Linode this volume should be attached to upon creation.', 'If not given, the volume will be created without an attachment.' ]), - region=dict( - type='str', + region=SpecField( + type=FieldType.string, description=[ 'The location to deploy the volume in.', 'See U(https://api.linode.com/v4/regions)' ]), - size=dict( - type='int', default=None, editable=True, + size=SpecField( + type=FieldType.integer, default=None, editable=True, description=[ 'The size of this volume, in GB.', 'Be aware that volumes may only be resized up after creation.' ]), - attached=dict( - type='bool', default=True, editable=True, - description='If true, the volume will be attached to a Linode. ' - 'Otherwise, the volume will be detached.'), + attached=SpecField( + type=FieldType.bool, default=True, editable=True, + description=['If true, the volume will be attached to a Linode. ' + 'Otherwise, the volume will be detached.']), - wait_timeout=dict( - type='int', default=240, - description='The amount of time, in seconds, to wait for a volume to ' - 'have the active status.' - ), + wait_timeout=SpecField( + type=FieldType.integer, default=240, + description=['The amount of time, in seconds, to wait for a volume to ' + 'have the active status.'] + ), - state=dict(type='str', - description='The desired state of the target.', - choices=['present', 'absent'], required=True), + state=SpecField(type=FieldType.string, + description=['The desired state of the target.'], + choices=['present', 'absent'], required=True), ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Manage a Linode Volume.' ], requirements=global_requirements, author=global_authors, - spec=linode_volume_spec, + options=linode_volume_spec, examples=docs.specdoc_examples, return_values=dict( - volume=dict( + volume=SpecReturnValue( description='The volume in JSON serialized form.', docs_url='https://www.linode.com/docs/api/volumes/#volume-view__responses', - type='dict', + type=FieldType.dict, sample=docs.result_volume_samples ) ) @@ -89,7 +88,7 @@ class LinodeVolume(LinodeModuleBase): """Module for creating and destroying Linode Volumes""" def __init__(self) -> None: - self.module_arg_spec = linode_volume_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of = ['state', 'label'] self.results = dict( changed=False, @@ -179,7 +178,7 @@ def _handle_volume(self) -> None: self._volume.attach(linode_id, config_id) self.register_action( 'Attached volume {0} to linode_id {1} and config_id {2}' - .format(label, linode_id, config_id)) + .format(label, linode_id, config_id)) if not attached: self._volume.detach() diff --git a/plugins/modules/volume_info.py b/plugins/modules/volume_info.py index 6d250c95..8164c0aa 100644 --- a/plugins/modules/volume_info.py +++ b/plugins/modules/volume_info.py @@ -8,48 +8,48 @@ # pylint: disable=unused-import from typing import List, Any, Optional +from ansible_specdoc.objects import SpecField, FieldType, SpecDocMeta, SpecReturnValue from linode_api4 import Volume +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.volume as docs_parent +import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.volume_info as docs from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements - -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.volume as docs_parent -import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.volume_info as docs +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import create_filter_and linode_volume_info_spec = dict( # We need to overwrite attributes to exclude them as requirements - state=dict(type='str', required=False, doc_hide=True), + state=SpecField(type=FieldType.string, required=False, doc_hide=True), - id=dict( - type='int', required=False, + id=SpecField( + type=FieldType.integer, required=False, description=[ 'The ID of the Volume.', 'Optional if `label` is defined.' ]), - label=dict( - type='str', required=False, + label=SpecField( + type=FieldType.string, required=False, description=[ 'The label of the Volume.', 'Optional if `id` is defined.' ]) ) -specdoc_meta = dict( +SPECDOC_META = SpecDocMeta( description=[ 'Get info about a Linode Volume.' ], requirements=global_requirements, author=global_authors, - spec=linode_volume_info_spec, + options=linode_volume_info_spec, examples=docs.specdoc_examples, return_values=dict( - volume=dict( + volume=SpecReturnValue( description='The volume in JSON serialized form.', docs_url='https://www.linode.com/docs/api/volumes/#volume-view__responses', - type='dict', + type=FieldType.dict, sample=docs_parent.result_volume_samples ) ) @@ -64,7 +64,7 @@ class LinodeVolumeInfo(LinodeModuleBase): """Module for getting info about a Linode Volume""" def __init__(self) -> None: - self.module_arg_spec = linode_volume_info_spec + self.module_arg_spec = SPECDOC_META.ansible_spec self.required_one_of: List[str] = [] self.results = dict( volume=None, diff --git a/scripts/render_readme.py b/scripts/render_readme.py index e012c11f..beb17e35 100644 --- a/scripts/render_readme.py +++ b/scripts/render_readme.py @@ -59,7 +59,7 @@ def get_module_metadata(module_file): module = importlib.util.module_from_spec(module_spec) module_spec.loader.exec_module(module) - description = getattr(module, 'specdoc_meta')['description'] + description = getattr(module, 'SPECDOC_META').description if isinstance(description, list): description = description[0] From 8cff7ee077b679ba4255508e5dc86cbafb8ee9d4 Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 16:45:08 -0500 Subject: [PATCH 10/13] fix typo --- plugins/modules/user.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/user.py b/plugins/modules/user.py index 091bf709..a23e13ee 100644 --- a/plugins/modules/user.py +++ b/plugins/modules/user.py @@ -171,7 +171,7 @@ ), 'grants': SpecField( type=FieldType.dict, - description=['Update the grants a ser has.'], + description=['Update the grants a user has.'], suboptions=SPEC_GRANTS, editable=True, ) From d3784a699eccb32c9ca2d12acaf5a815d209d8e0 Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Thu, 2 Feb 2023 16:51:56 -0500 Subject: [PATCH 11/13] fix lint --- plugins/modules/database_list.py | 3 ++- plugins/modules/database_mysql_info.py | 4 ++-- plugins/modules/database_postgresql_info.py | 4 ++-- plugins/modules/domain.py | 7 +++++-- plugins/modules/domain_record_info.py | 3 ++- plugins/modules/event_list.py | 3 ++- plugins/modules/firewall.py | 9 ++++++--- plugins/modules/image_list.py | 3 ++- plugins/modules/lke_cluster_info.py | 6 ++++-- plugins/modules/lke_node_pool.py | 3 ++- plugins/modules/nodebalancer.py | 16 ++++++++++------ plugins/modules/stackscript_list.py | 8 +++++--- plugins/modules/type_list.py | 8 ++++++-- plugins/modules/user.py | 5 ++++- plugins/modules/vlan_list.py | 3 ++- 15 files changed, 56 insertions(+), 29 deletions(-) diff --git a/plugins/modules/database_list.py b/plugins/modules/database_list.py index f00ed09c..7c7579b4 100644 --- a/plugins/modules/database_list.py +++ b/plugins/modules/database_list.py @@ -14,7 +14,8 @@ from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + construct_api_filter, get_all_paginated spec_filter = dict( name=SpecField(type=FieldType.string, required=True, diff --git a/plugins/modules/database_mysql_info.py b/plugins/modules/database_mysql_info.py index 94293c28..849fa86d 100644 --- a/plugins/modules/database_mysql_info.py +++ b/plugins/modules/database_mysql_info.py @@ -20,8 +20,8 @@ call_protected_provisioning from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values, \ - paginated_list_to_json, mapping_to_dict +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + filter_null_values, paginated_list_to_json, mapping_to_dict spec = dict( # Disable the default values diff --git a/plugins/modules/database_postgresql_info.py b/plugins/modules/database_postgresql_info.py index caabd170..e8045de7 100644 --- a/plugins/modules/database_postgresql_info.py +++ b/plugins/modules/database_postgresql_info.py @@ -20,8 +20,8 @@ call_protected_provisioning from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import filter_null_values, \ - paginated_list_to_json, mapping_to_dict +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + filter_null_values, paginated_list_to_json, mapping_to_dict spec = dict( # Disable the default values diff --git a/plugins/modules/domain.py b/plugins/modules/domain.py index f768b647..c53c66c4 100644 --- a/plugins/modules/domain.py +++ b/plugins/modules/domain.py @@ -23,7 +23,9 @@ label=SpecField(type=FieldType.string, required=False, doc_hide=True), axfr_ips=SpecField(type=FieldType.list, element_type=FieldType.string, editable=True, - description=['The list of IPs that may perform a zone transfer for this Domain.']), + description=[ + 'The list of IPs that may perform a zone transfer for this Domain.' + ]), description=SpecField(type=FieldType.string, editable=True, description=['The list of IPs that may perform a ' 'zone transfer for this Domain.']), @@ -45,7 +47,8 @@ description=['The Start of Authority email address.'], editable=True), status=SpecField(type=FieldType.string, - description=['Used to control whether this Domain is currently being rendered.'], + description=['Used to control whether this Domain is ' + 'currently being rendered.'], editable=True), state=SpecField(type=FieldType.string, description=['The desired state of the target.'], diff --git a/plugins/modules/domain_record_info.py b/plugins/modules/domain_record_info.py index 0c41df43..3e2ef19b 100644 --- a/plugins/modules/domain_record_info.py +++ b/plugins/modules/domain_record_info.py @@ -18,7 +18,8 @@ from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import paginated_list_to_json +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + paginated_list_to_json linode_domain_record_info_spec = dict( # We need to overwrite attributes to exclude them as requirements diff --git a/plugins/modules/event_list.py b/plugins/modules/event_list.py index d18f7c32..d1896c6c 100644 --- a/plugins/modules/event_list.py +++ b/plugins/modules/event_list.py @@ -14,7 +14,8 @@ from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + construct_api_filter, get_all_paginated spec_filter = dict( name=SpecField(type=FieldType.string, required=True, diff --git a/plugins/modules/firewall.py b/plugins/modules/firewall.py index 94bbf1e5..0a1452de 100644 --- a/plugins/modules/firewall.py +++ b/plugins/modules/firewall.py @@ -66,7 +66,8 @@ ) linode_firewall_rules_spec: dict = dict( - inbound=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=linode_firewall_rule_spec, + inbound=SpecField(type=FieldType.list, element_type=FieldType.dict, + suboptions=linode_firewall_rule_spec, description=[ 'A list of rules for inbound traffic.' ]), @@ -74,7 +75,8 @@ description=[ 'The default behavior for inbound traffic.' ]), - outbound=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=linode_firewall_rule_spec, + outbound=SpecField(type=FieldType.list, element_type=FieldType.dict, + suboptions=linode_firewall_rule_spec, description=[ 'A list of rules for outbound traffic.' ]), @@ -100,7 +102,8 @@ description=[ 'The unique label to give this Firewall.' ]), - devices=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=linode_firewall_device_spec, + devices=SpecField(type=FieldType.list, element_type=FieldType.dict, + suboptions=linode_firewall_device_spec, editable=True, description=[ 'The devices that are attached to this Firewall.' diff --git a/plugins/modules/image_list.py b/plugins/modules/image_list.py index f0be4441..d9c9e4c8 100644 --- a/plugins/modules/image_list.py +++ b/plugins/modules/image_list.py @@ -14,7 +14,8 @@ from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + construct_api_filter, get_all_paginated spec_filter = dict( name=SpecField(type=FieldType.string, required=True, diff --git a/plugins/modules/lke_cluster_info.py b/plugins/modules/lke_cluster_info.py index 75330129..85a64e5c 100644 --- a/plugins/modules/lke_cluster_info.py +++ b/plugins/modules/lke_cluster_info.py @@ -17,7 +17,8 @@ from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import jsonify_node_pool, filter_null_values +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + jsonify_node_pool, filter_null_values linode_lke_cluster_info_spec = dict( # We need to overwrite attributes to exclude them as requirements @@ -63,7 +64,8 @@ ), kubeconfig=SpecReturnValue( description='The Base64-encoded kubeconfig used to access this cluster. \n' - 'NOTE: This value may be unavailable if the cluster is not fully provisioned.', + 'NOTE: This value may be unavailable if the cluster is not ' + 'fully provisioned.', docs_url='https://www.linode.com/docs/api/linode-kubernetes-engine-lke/' '#kubeconfig-view__responses', type=FieldType.string diff --git a/plugins/modules/lke_node_pool.py b/plugins/modules/lke_node_pool.py index aa87fabc..b5eeb380 100644 --- a/plugins/modules/lke_node_pool.py +++ b/plugins/modules/lke_node_pool.py @@ -106,7 +106,8 @@ skip_polling=SpecField( type=FieldType.bool, - description=['If true, the module will not wait for all nodes in the node pool to be ready.'], + description=['If true, the module will not wait for all ' + 'nodes in the node pool to be ready.'], default=False ), diff --git a/plugins/modules/nodebalancer.py b/plugins/modules/nodebalancer.py index 722b3013..95b0a89f 100644 --- a/plugins/modules/nodebalancer.py +++ b/plugins/modules/nodebalancer.py @@ -47,7 +47,8 @@ linode_configs_spec = dict( algorithm=SpecField( type=FieldType.string, required=False, editable=True, - description=['What algorithm this NodeBalancer should use for routing traffic to backends.'], + description=['What algorithm this NodeBalancer should use ' + 'for routing traffic to backends.'], choices=['roundrobin', 'leastconn', 'source']), check=SpecField( @@ -73,9 +74,10 @@ description=['How often, in seconds, to check that backends are up and serving requests.']), check_passive=SpecField( - type='bool', required=False, editable=True, - description=['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.']), + type=FieldType.bool, required=False, editable=True, + description=['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=SpecField( type=FieldType.string, required=False, editable=True, @@ -130,7 +132,8 @@ choices=['none', 'table', 'http_cookie']), nodes=SpecField( - type=FieldType.list, required=False, element_type=FieldType.dict, suboptions=linode_nodes_spec, editable=True, + type=FieldType.list, required=False, element_type=FieldType.dict, + suboptions=linode_nodes_spec, editable=True, description=['A list of nodes to apply to this config. ' 'These can alternatively be configured through the nodebalancer_node module.']) ) @@ -159,7 +162,8 @@ choices=['present', 'absent'], required=True), configs=SpecField( - type=FieldType.list, element_type=FieldType.dict, suboptions=linode_configs_spec, editable=True, + type=FieldType.list, element_type=FieldType.dict, + suboptions=linode_configs_spec, editable=True, description=['A list of configs to apply to the NodeBalancer.']) ) diff --git a/plugins/modules/stackscript_list.py b/plugins/modules/stackscript_list.py index 3523b1c4..14f29e47 100644 --- a/plugins/modules/stackscript_list.py +++ b/plugins/modules/stackscript_list.py @@ -14,7 +14,8 @@ from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + construct_api_filter, get_all_paginated spec_filter = dict( name=SpecField(type=FieldType.string, required=True, @@ -84,8 +85,9 @@ def exec_module(self, **kwargs: Any) -> Optional[dict]: filter_dict = construct_api_filter(self.module.params) - self.results['stackscripts'] = get_all_paginated(self.client, '/linode/stackscripts', - filter_dict, num_results=self.module.params['count']) + self.results['stackscripts'] = get_all_paginated( + self.client, '/linode/stackscripts', + filter_dict, num_results=self.module.params['count']) return self.results diff --git a/plugins/modules/type_list.py b/plugins/modules/type_list.py index a19f3250..6738d8e5 100644 --- a/plugins/modules/type_list.py +++ b/plugins/modules/type_list.py @@ -14,7 +14,8 @@ from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + construct_api_filter, get_all_paginated spec_filter = dict( name=SpecField(type=FieldType.string, required=True, @@ -36,7 +37,10 @@ label=SpecField(type=FieldType.string, required=False, doc_hide=True), order=SpecField(type=FieldType.string, description=['The order to list Instance Types in.'], default='asc', choices=['desc', 'asc']), - order_by=SpecField(type=FieldType.string, description=['The attribute to order Instance Types by.']), + order_by=SpecField( + type=FieldType.string, + description=['The attribute to order Instance Types by.'] + ), filters=SpecField(type=FieldType.list, element_type=FieldType.dict, suboptions=spec_filter, description=['A list of filters to apply to the resulting Instance Types.']), count=SpecField(type=FieldType.integer, diff --git a/plugins/modules/user.py b/plugins/modules/user.py index a23e13ee..99315d1a 100644 --- a/plugins/modules/user.py +++ b/plugins/modules/user.py @@ -100,7 +100,10 @@ SPEC_GRANTS_RESOURCE = { 'type': SpecField( type=FieldType.string, - choices=['domain', 'image', 'linode', 'longview', 'nodebalancer', 'stackscript', 'volume', 'database'], + choices=[ + 'domain', 'image', 'linode', 'longview', + 'nodebalancer', 'stackscript', 'volume', 'database' + ], description=['The type of resource to grant access to.'], required=True, editable=True diff --git a/plugins/modules/vlan_list.py b/plugins/modules/vlan_list.py index f624fd2b..cfb4b6ec 100644 --- a/plugins/modules/vlan_list.py +++ b/plugins/modules/vlan_list.py @@ -14,7 +14,8 @@ from ansible_collections.linode.cloud.plugins.module_utils.linode_common import LinodeModuleBase from ansible_collections.linode.cloud.plugins.module_utils.linode_docs import global_authors, \ global_requirements -from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import construct_api_filter, get_all_paginated +from ansible_collections.linode.cloud.plugins.module_utils.linode_helper import \ + construct_api_filter, get_all_paginated spec_filter = dict( name=SpecField(type=FieldType.string, required=True, From fec24a884fb873544631f68431944160b3af4f88 Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Fri, 10 Feb 2023 14:49:36 -0500 Subject: [PATCH 12/13] Bump requirements --- requirements-dev.txt | 1 - requirements.txt | 3 ++- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/requirements-dev.txt b/requirements-dev.txt index c69e80cf..bea946e9 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -3,6 +3,5 @@ botocore==1.20.23 pylint==2.15.5 ansible-doc-extractor==0.1.8 mypy==0.991 -ansible-specdoc==0.0.11 ansible==7.1.0 Jinja2==3.0.1 \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index c37e3701..5f5746f0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ linode-api4==5.3.0 polling==0.3.2 -types-requests==2.28.11.8 \ No newline at end of file +types-requests==2.28.11.8 +ansible-specdoc==0.0.12 \ No newline at end of file From 786fbcb68a38fdbe0735c758878251c8f25b9e84 Mon Sep 17 00:00:00 2001 From: Lena Garber Date: Fri, 10 Feb 2023 14:55:25 -0500 Subject: [PATCH 13/13] make gendocs --- docs/modules/user.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/user.md b/docs/modules/user.md index d6b59ba7..5796bdf5 100644 --- a/docs/modules/user.md +++ b/docs/modules/user.md @@ -57,7 +57,7 @@ Manage a Linode User. | `state` |
`str`
|
**Required**
| The state of this user. **(Choices: `present`, `absent`)** | | `restricted` |
`bool`
|
Optional
| If true, the User must be granted access to perform actions or access entities on this Account. **(Default: `True`; Updatable)** | | `email` |
`str`
|
Optional
| The email address for the User. Linode sends emails to this address for account management communications. May be used for other communications as configured. | -| [`grants` (sub-options)](#grants) |
`dict`
|
Optional
| Update the grants a ser has. **(Updatable)** | +| [`grants` (sub-options)](#grants) |
`dict`
|
Optional
| Update the grants a user has. **(Updatable)** |