Merge pull request #543 from linode/dev

v0.28.0

.github/workflows/release.yml

@@ -35,6 +35,9 @@ jobs:
       - name: install ansible dependencies
         run: ansible-galaxy collection install amazon.aws:==6.0.1
 
+      - name: inject docs using specdoc
+        run: make inject
+
       - name: publish the collection
         run: make publish
         env:

Makefile

@@ -105,3 +105,12 @@ endif
 	@echo "api_url: $(TEST_API_URL)" >> $(INTEGRATION_CONFIG)
 	@echo "api_version: $(TEST_API_VERSION)" >> $(INTEGRATION_CONFIG)
 	@echo "ca_file: $(TEST_API_CA)" >> $(INTEGRATION_CONFIG)
+
+inject:
+	@echo "Injecting documentation into source files"
+	for f in `ls ./plugins/modules/*.py`; do ansible-specdoc -j -i $$f; done
+	ansible-test sanity --test ansible-doc
+
+inject-clean:
+	@echo "Removing injected documentation from source files"
+	for f in `ls ./plugins/modules/*.py`; do ansible-specdoc -jc -i $$f; done

README.md

@@ -70,7 +70,7 @@ Name | Description |
 [linode.cloud.ipv6_range_info](./docs/modules/ipv6_range_info.md)|Get info about a Linode IPv6 range.|
 [linode.cloud.lke_cluster_info](./docs/modules/lke_cluster_info.md)|Get info about a Linode LKE cluster.|
 [linode.cloud.nodebalancer_info](./docs/modules/nodebalancer_info.md)|Get info about a Linode NodeBalancer.|
-[linode.cloud.object_cluster_info](./docs/modules/object_cluster_info.md)|Get info about a Linode Object Storage Cluster.|
+[linode.cloud.object_cluster_info](./docs/modules/object_cluster_info.md)|**NOTE: This module has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**|
 [linode.cloud.placement_group_info](./docs/modules/placement_group_info.md)|Get info about a Linode Placement Group.|
 [linode.cloud.profile_info](./docs/modules/profile_info.md)|Get info about a Linode Profile.|
 [linode.cloud.ssh_key_info](./docs/modules/ssh_key_info.md)|Get info about the Linode SSH public key.|
@@ -102,7 +102,7 @@ Name | Description |
 [linode.cloud.instance_type_list](./docs/modules/instance_type_list.md)|List and filter on Linode Instance Types.|
 [linode.cloud.lke_version_list](./docs/modules/lke_version_list.md)|List Kubernetes versions available for deployment to a Kubernetes cluster.|
 [linode.cloud.nodebalancer_list](./docs/modules/nodebalancer_list.md)|List and filter on Nodebalancers.|
-[linode.cloud.object_cluster_list](./docs/modules/object_cluster_list.md)|List and filter on Object Storage Clusters.|
+[linode.cloud.object_cluster_list](./docs/modules/object_cluster_list.md)|**NOTE: This module has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**|
 [linode.cloud.placement_group_list](./docs/modules/placement_group_list.md)|List and filter on Placement Groups.|
 [linode.cloud.region_list](./docs/modules/region_list.md)|List and filter on Linode Regions.|
 [linode.cloud.ssh_key_list](./docs/modules/ssh_key_list.md)|List and filter on SSH keys in the Linode profile.|

docs/modules/child_account_info.md

@@ -2,6 +2,8 @@
 
 Get info about a Linode Child Account.
 
+NOTE: Parent/Child related features may not be generally available.
+
 - [Minimum Required Fields](#minimum-required-fields)
 - [Examples](#examples)
 - [Parameters](#parameters)

docs/modules/child_account_list.md

@@ -2,6 +2,8 @@
 
 List and filter on Child Account.
 
+NOTE: Parent/Child related features may not be generally available.
+
 - [Minimum Required Fields](#minimum-required-fields)
 - [Examples](#examples)
 - [Parameters](#parameters)

docs/modules/ipv6_range_info.md

@@ -17,7 +17,7 @@ Get info about a Linode IPv6 range.
 ```yaml
 - name: Get info about an IPv6 range
   linode.cloud.ipv6_range_info:
-    range: 2600:3c01::
+    range: "2600:3c01::"
 ```
 
 

docs/modules/object_cluster_info.md

@@ -1,5 +1,7 @@
 # object_cluster_info
 
+**NOTE: This module has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**
+
 Get info about a Linode Object Storage Cluster.
 
 - [Minimum Required Fields](#minimum-required-fields)

docs/modules/object_cluster_list.md

@@ -1,5 +1,7 @@
 # object_cluster_list
 
+**NOTE: This module has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**
+
 List and filter on Object Storage Clusters.
 
 - [Minimum Required Fields](#minimum-required-fields)

docs/modules/object_keys.md

@@ -22,11 +22,21 @@ Manage Linode Object Storage Keys.
 ```
 
 ```yaml
-- name: Create a limited Object Storage key
+- name: Create an Object Storage key limited to specific regions
+  linode.cloud.object_keys:
+    label: 'my-region-limited-key'
+    regions:
+        - us-mia
+        - us-ord
+    state: present
+```
+
+```yaml
+- name: Create an Object Storage key limited to specific buckets
   linode.cloud.object_keys:
     label: 'my-limited-key'
     access:
-      - cluster: us-east-1
+      - cluster: us-mia
         bucket_name: my-bucket
         permissions: read_write
     state: present
@@ -47,14 +57,16 @@ Manage Linode Object Storage Keys.
 | `state` | <center>`str`</center> | <center>**Required**</center> | The desired state of the target.  **(Choices: `present`, `absent`)** |
 | `label` | <center>`str`</center> | <center>Optional</center> | The unique label to give this key.   |
 | [`access` (sub-options)](#access) | <center>`list`</center> | <center>Optional</center> | A list of access permissions to give the key.   |
+| `regions` | <center>`list`</center> | <center>Optional</center> | A list of regions to scope this key to.  **(Updatable)** |
 
 ### access
 
 | Field     | Type | Required | Description                                                                  |
 |-----------|------|----------|------------------------------------------------------------------------------|
-| `cluster` | <center>`str`</center> | <center>**Required**</center> | The id of the cluster that the provided bucket exists under.   |
 | `bucket_name` | <center>`str`</center> | <center>**Required**</center> | The name of the bucket to set the key's permissions for.   |
 | `permissions` | <center>`str`</center> | <center>**Required**</center> | The permissions to give the key.  **(Choices: `read_only`, `write_only`, `read_write`)** |
+| `region` | <center>`str`</center> | <center>Optional</center> | The region of the cluster that the provided bucket exists under.  **(Conflicts With: `cluster`)** |
+| `cluster` | <center>`str`</center> | <center>Optional</center> | The id of the cluster that the provided bucket exists under. **NOTE: This field has been deprecated because it relies on deprecated API endpoints. Going forward, `region` will be the preferred way to designate where Object Storage resources should be created.**  **(Conflicts With: `region`)** |
 
 ## Return Values
 
@@ -63,18 +75,33 @@ Manage Linode Object Storage Keys.
     - Sample Response:
         ```json
         {
-          "access_key": "ACCESSKEY",
+          "access_key": "redacted",
           "bucket_access": [
             {
-              "bucket_name": "example-bucket",
-              "cluster": "ap-south-1",
-              "permissions": "read_only"
+              "bucket_name": "my-bucket",
+              "cluster": "us-iad-1",
+              "permissions": "read_write",
+              "region": "us-iad"
             }
           ],
-          "id": 123,
+          "id": 12345,
           "label": "my-key",
           "limited": true,
-          "secret_key": "SECRETKEY"
+          "regions": [
+            {
+              "id": "us-iad",
+              "s3_endpoint": "us-iad-1.linodeobjects.com"
+            },
+            {
+              "id": "us-ord",
+              "s3_endpoint": "us-ord-1.linodeobjects.com"
+            },
+            {
+              "id": "us-sea",
+              "s3_endpoint": "us-sea-1.linodeobjects.com"
+            }
+          ],
+          "secret_key": "[REDACTED]"
         }
         ```
     - 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

plugins/module_utils/doc_fragments/ipv6_range_info.py

@@ -3,7 +3,7 @@
 specdoc_examples = ['''
 - name: Get info about an IPv6 range
   linode.cloud.ipv6_range_info:
-    range: 2600:3c01::''']
+    range: "2600:3c01::"''']
 
 
 result_range_samples = ['''{

plugins/module_utils/doc_fragments/object_keys.py

@@ -5,11 +5,18 @@
   linode.cloud.object_keys:
     label: 'my-fullaccess-key'
     state: present''', '''
-- name: Create a limited Object Storage key
+- name: Create an Object Storage key limited to specific regions
+  linode.cloud.object_keys:
+    label: 'my-region-limited-key'
+    regions:
+        - us-mia
+        - us-ord
+    state: present''', '''
+- name: Create an Object Storage key limited to specific buckets
   linode.cloud.object_keys:
     label: 'my-limited-key'
     access:
-      - cluster: us-east-1
+      - cluster: us-mia
         bucket_name: my-bucket
         permissions: read_write
     state: present''', '''
@@ -19,16 +26,31 @@
     state: absent''']
 
 result_key_samples = ['''{
-  "access_key": "ACCESSKEY",
+  "access_key": "redacted",
   "bucket_access": [
     {
-      "bucket_name": "example-bucket",
-      "cluster": "ap-south-1",
-      "permissions": "read_only"
+      "bucket_name": "my-bucket",
+      "cluster": "us-iad-1",
+      "permissions": "read_write",
+      "region": "us-iad"
     }
   ],
-  "id": 123,
+  "id": 12345,
   "label": "my-key",
   "limited": true,
-  "secret_key": "SECRETKEY"
+  "regions": [
+    {
+      "id": "us-iad",
+      "s3_endpoint": "us-iad-1.linodeobjects.com"
+    },
+    {
+      "id": "us-ord",
+      "s3_endpoint": "us-ord-1.linodeobjects.com"
+    },
+    {
+      "id": "us-sea",
+      "s3_endpoint": "us-sea-1.linodeobjects.com"
+    }
+  ],
+  "secret_key": "[REDACTED]"
 }''']

plugins/module_utils/linode_common_info.py

@@ -96,13 +96,17 @@ def __init__(
         params: List[InfoModuleParam] = None,
         attributes: List[InfoModuleAttr] = None,
         examples: List[str] = None,
+        description: List[str] = None,
         requires_beta: bool = False,
     ) -> None:
         self.primary_result = primary_result
         self.secondary_results = secondary_results or []
         self.params = params or []
         self.attributes = attributes or []
         self.examples = examples or []
+        self.description = description or [
+            f"Get info about a Linode {self.primary_result.display_name}."
+        ]
         self.requires_beta = requires_beta
 
         self.module_arg_spec = self.spec.ansible_spec
@@ -198,11 +202,9 @@ def spec(self):
             for v in [self.primary_result] + self.secondary_results
         }
 
-        description = [
-            f"Get info about a Linode {self.primary_result.display_name}."
-        ]
+        description = self.description
 
-        if self.requires_beta:
+        if self.requires_beta and BETA_DISCLAIMER not in description:
             description.append(BETA_DISCLAIMER)
 
         return SpecDocMeta(

plugins/module_utils/linode_common_list.py

@@ -53,6 +53,7 @@ def __init__(
         result_docs_url: str = "",
         params: List[ListModuleParam] = None,
         examples: List[str] = None,
+        description: List[str] = None,
         result_samples: List[str] = None,
         requires_beta: bool = False,
     ) -> None:
@@ -63,6 +64,9 @@ def __init__(
         self.result_docs_url = result_docs_url
         self.params = params or []
         self.examples = examples or []
+        self.description = description or [
+            f"List and filter on {self.result_display_name}."
+        ]
         self.result_samples = result_samples or []
         self.requires_beta = requires_beta
 
@@ -156,9 +160,9 @@ def spec(self):
                 required=True,
             )
 
-        description = [f"List and filter on {self.result_display_name}."]
+        description = self.description
 
-        if self.requires_beta:
+        if self.requires_beta and BETA_DISCLAIMER not in description:
             description.append(BETA_DISCLAIMER)
 
         return SpecDocMeta(

plugins/modules/account_availability_info.py

@@ -40,5 +40,12 @@
 
 SPECDOC_META = module.spec
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 if __name__ == "__main__":
     module.run()

plugins/modules/account_availability_list.py

@@ -24,5 +24,12 @@
 
 SPECDOC_META = module.spec
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 if __name__ == "__main__":
     module.run()

plugins/modules/account_info.py

@@ -44,6 +44,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for getting info about a Linode Account"""

plugins/modules/api_request.py

@@ -87,6 +87,13 @@
     },
 )
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 
 class Module(LinodeModuleBase):
     """Module for running arbitrary Linode API requests"""

plugins/modules/child_account_info.py

@@ -36,9 +36,20 @@
         ),
     ],
     examples=docs.specdoc_examples,
+    description=[
+        "Get info about a Linode Child Account.",
+        "NOTE: Parent/Child related features may not be generally available.",
+    ],
 )
 
 SPECDOC_META = module.spec
 
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
 if __name__ == "__main__":
     module.run()