Add region_info module

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.|

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:/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
+
+

plugins/module_utils/doc_fragments/region.py

@@ -0,0 +1,31 @@
+"""Documentation fragments for the region module"""
+
+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"
+}"""]

plugins/module_utils/doc_fragments/region_info.py

@@ -0,0 +1,6 @@
+"""Documentation fragments for the region_info module"""
+
+specdoc_examples = ['''
+- name: Get Info of a Linode Region
+ linode.cloud.region_info:
+ id: us-mia''']

plugins/module_utils/linode_common.py

@@ -107,6 +107,7 @@
 class LinodeModuleBase: # pylint: disable=too-many-positional-arguments
  """A base for all Linode resource modules."""
 
+ ## pylint: disable=too-many-positional-arguments
  def __init__(
  self,
  module_arg_spec: dict,

plugins/module_utils/linode_common_info.py

@@ -113,6 +113,7 @@ class InfoModuleResult:
 class InfoModule(LinodeModuleBase):
  """A common module for listing API resources given a set of filters."""
 
+ # pylint: disable=too-many-positional-arguments
  def __init__(
  # pylint: disable=too-many-positional-arguments
  self,

plugins/module_utils/linode_common_list.py

@@ -45,6 +45,7 @@ class ListModule(
 ): # pylint: disable=too-many-instance-attributes,too-many-positional-arguments
  """A common module for listing API resources given a set of filters."""
 
+ # pylint: disable=too-many-positional-arguments
  def __init__(
  self,
  result_display_name: str,

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()

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 "" }}'