Add region_info module

zliang-akamai · Sep 25, 2024 · 2e5fa74 · 2e5fa74
1 parent 7769e33
commit 2e5fa74
Show file tree

Hide file tree

Showing 6 changed files with 177 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -73,6 +73,7 @@ Name | Description |
 [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.region_info](./docs/modules/region_info.md)|Get info about a Linode Region.|
 [linode.cloud.ssh_key_info](./docs/modules/ssh_key_info.md)|Get info about a Linode SSH Key.|
 [linode.cloud.stackscript_info](./docs/modules/stackscript_info.md)|Get info about a Linode StackScript.|
 [linode.cloud.token_info](./docs/modules/token_info.md)|Get info about a Linode Personal Access Token.|

diff --git a/docs/modules/region_info.md b/docs/modules/region_info.md
@@ -0,0 +1,68 @@
+# region_info
+
+Get info about a Linode Region.
+
+- [Minimum Required Fields](#minimum-required-fields)
+- [Examples](#examples)
+- [Parameters](#parameters)
+- [Return Values](#return-values)
+
+## Minimum Required Fields
+| Field       | Type  | Required     | Description                                                                                                                                                                                                              |
+|-------------|-------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `api_token` | `str` | **Required** | The Linode account personal access token. It is necessary to run the module. <br/>It can be exposed by the environment variable `LINODE_API_TOKEN` instead. <br/>See details in [Usage](https://github.com/linode/ansible_linode?tab=readme-ov-file#usage). |
+
+## Examples
+
+```yaml
+- name: Get Info of a Linode Region
+  linode.cloud.region_info:
+    id: us-mia
+```
+
+
+## Parameters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `id` | <center>`str`</center> | <center>**Required**</center> | The ID of the Region to resolve.   |
+
+## Return Values
+
+- `region` - The returned Region.
+
+    - Sample Response:
+        ```json
+        {
+            "id": "us-mia",
+            "label": "Miami, FL",
+            "country": "us",
+            "capabilities": [
+                "Linodes",
+                "Backups",
+                "NodeBalancers",
+                "Block Storage",
+                "Object Storage",
+                "Kubernetes",
+                "Cloud Firewall",
+                "Vlans",
+                "VPCs",
+                "Metadata",
+                "Premium Plans",
+                "Placement Group"
+            ],
+            "status": "ok",
+            "resolvers": {
+                "ipv4": "172.233.160.34, 172.233.160.27, 172.233.160.30, 172.233.160.29, 172.233.160.32, 172.233.160.28, 172.233.160.33, 172.233.160.26, 172.233.160.25, 172.233.160.31",
+                "ipv6": "2a01:7e04::f03c:93ff:fead:d31f, 2a01:7e04::f03c:93ff:fead:d37f, 2a01:7e04::f03c:93ff:fead:d30c, 2a01:7e04::f03c:93ff:fead:d318, 2a01:7e04::f03c:93ff:fead:d316, 2a01:7e04::f03c:93ff:fead:d339, 2a01:7e04::f03c:93ff:fead:d367, 2a01:7e04::f03c:93ff:fead:d395, 2a01:7e04::f03c:93ff:fead:d3d0, 2a01:7e04::f03c:93ff:fead:d38e"
+            },
+            "placement_group_limits": {
+                "maximum_pgs_per_customer": null,
+                "maximum_linodes_per_pg": 5
+            },
+            "site_type": "core"
+        }
+        ```
+    - See the [Linode API response documentation](https://techdocs.akamai.com/linode-api/reference/get-region) for a list of returned fields
+
+
diff --git a/plugins/module_utils/doc_fragments/region.py b/plugins/module_utils/doc_fragments/region.py
@@ -0,0 +1,29 @@
+result_region_samples = ["""{
+    "id": "us-mia",
+    "label": "Miami, FL",
+    "country": "us",
+    "capabilities": [
+        "Linodes",
+        "Backups",
+        "NodeBalancers",
+        "Block Storage",
+        "Object Storage",
+        "Kubernetes",
+        "Cloud Firewall",
+        "Vlans",
+        "VPCs",
+        "Metadata",
+        "Premium Plans",
+        "Placement Group"
+    ],
+    "status": "ok",
+    "resolvers": {
+        "ipv4": "172.233.160.34, 172.233.160.27, 172.233.160.30, 172.233.160.29, 172.233.160.32, 172.233.160.28, 172.233.160.33, 172.233.160.26, 172.233.160.25, 172.233.160.31",
+        "ipv6": "2a01:7e04::f03c:93ff:fead:d31f, 2a01:7e04::f03c:93ff:fead:d37f, 2a01:7e04::f03c:93ff:fead:d30c, 2a01:7e04::f03c:93ff:fead:d318, 2a01:7e04::f03c:93ff:fead:d316, 2a01:7e04::f03c:93ff:fead:d339, 2a01:7e04::f03c:93ff:fead:d367, 2a01:7e04::f03c:93ff:fead:d395, 2a01:7e04::f03c:93ff:fead:d3d0, 2a01:7e04::f03c:93ff:fead:d38e"
+    },
+    "placement_group_limits": {
+        "maximum_pgs_per_customer": null,
+        "maximum_linodes_per_pg": 5
+    },
+    "site_type": "core"
+}"""]
diff --git a/plugins/module_utils/doc_fragments/region_info.py b/plugins/module_utils/doc_fragments/region_info.py
@@ -0,0 +1,4 @@
+specdoc_examples = ['''
+- name: Get Info of a Linode Region
+  linode.cloud.region_info:
+    id: us-mia''']
diff --git a/plugins/modules/region_info.py b/plugins/modules/region_info.py
@@ -0,0 +1,49 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+"""This module allows users to retrieve information about a Linode Region."""
+
+from __future__ import absolute_import, division, print_function
+
+import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.region as docs_parent
+import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.region_info as docs
+from ansible_collections.linode.cloud.plugins.module_utils.linode_common_info import (
+    InfoModule,
+    InfoModuleAttr,
+    InfoModuleResult,
+)
+from ansible_specdoc.objects import FieldType
+from linode_api4 import Region
+
+module = InfoModule(
+    examples=docs.specdoc_examples,
+    primary_result=InfoModuleResult(
+        display_name="Region",
+        field_name="region",
+        field_type=FieldType.dict,
+        docs_url="https://techdocs.akamai.com/linode-api/reference/get-region",
+        samples=docs_parent.result_region_samples,
+    ),
+    attributes=[
+        InfoModuleAttr(
+            name="id",
+            display_name="ID",
+            type=FieldType.string,
+            get=lambda client, params: client.load(
+                Region, params.get("id")
+            )._raw_json,
+        ),
+    ],
+)
+
+SPECDOC_META = module.spec
+
+DOCUMENTATION = r"""
+"""
+EXAMPLES = r"""
+"""
+RETURN = r"""
+"""
+
+if __name__ == "__main__":
+    module.run()
diff --git a/tests/integration/targets/region_info/tasks/main.yaml b/tests/integration/targets/region_info/tasks/main.yaml
@@ -0,0 +1,26 @@
+- name: region_list
+  block:
+    - name: List regions that support PGs
+      linode.cloud.region_list: {}
+      register: all_regions
+
+    - set_fact:
+        selected_region: "{{ (all_regions.regions | list)[0] }}"
+
+    - name: Get Info of a Linode Region
+      linode.cloud.region_info:
+        id: "{{ selected_region.id }}"
+      register: region_info
+
+    - name: Assert GET placement_group_info response
+      assert:
+        that:
+          - region_info.region.id == selected_region.id
+          - region_info.region.label == selected_region.label
+
+  environment:
+    LINODE_UA_PREFIX: '{{ ua_prefix }}'
+    LINODE_API_TOKEN: '{{ api_token }}'
+    LINODE_API_URL: '{{ api_url }}'
+    LINODE_API_VERSION: '{{ api_version }}'
+    LINODE_CA: '{{ ca_file or "" }}'