Add VPC IP List Modules (#499)

README.md

@@ -106,8 +106,10 @@ Name | Description |
 [linode.cloud.user_list](./docs/modules/user_list.md)|List Users.|
 [linode.cloud.vlan_list](./docs/modules/vlan_list.md)|List and filter on Linode VLANs.|
 [linode.cloud.volume_list](./docs/modules/volume_list.md)|List and filter on Linode Volumes.|
+[linode.cloud.vpc_ip_list](./docs/modules/vpc_ip_list.md)|List and filter on VPC IP Addresses.|
 [linode.cloud.vpc_list](./docs/modules/vpc_list.md)|List and filter on VPCs.|
 [linode.cloud.vpc_subnet_list](./docs/modules/vpc_subnet_list.md)|List and filter on VPC Subnets.|
+[linode.cloud.vpcs_ip_list](./docs/modules/vpcs_ip_list.md)|List and filter on all VPC IP Addresses.|
 
 
 ### Inventory Plugins

docs/modules/vpc_ip_list.md

@@ -0,0 +1,66 @@
+# vpc_ip_list
+
+List and filter on VPC IP Addresses.
+
+- [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: List all IPs of a specific VPC.
+  linode.cloud.vpc_ip_list:
+    vpc_id: 12345
+```
+
+
+## Parameters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `vpc_id` | <center>`int`</center> | <center>**Required**</center> | The parent VPC for the VPC IP Addresses.   |
+| `order` | <center>`str`</center> | <center>Optional</center> | The order to list VPC IP Addresses in.  **(Choices: `desc`, `asc`; Default: `asc`)** |
+| `order_by` | <center>`str`</center> | <center>Optional</center> | The attribute to order VPC IP Addresses by.   |
+| [`filters` (sub-options)](#filters) | <center>`list`</center> | <center>Optional</center> | A list of filters to apply to the resulting VPC IP Addresses.   |
+| `count` | <center>`int`</center> | <center>Optional</center> | The number of VPC IP Addresses to return. If undefined, all results will be returned.   |
+
+### filters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `name` | <center>`str`</center> | <center>**Required**</center> | The name of the field to filter on. Valid filterable fields can be found [here]().   |
+| `values` | <center>`list`</center> | <center>**Required**</center> | A list of values to allow for this field. Fields will pass this filter if at least one of these values matches.   |
+
+## Return Values
+
+- `vpcs_ips` - The returned VPC IP Addresses.
+
+    - Sample Response:
+        ```json
+        [
+            {
+                "address": "10.0.0.2",
+                "address_range": null,
+                "vpc_id": 56242,
+                "subnet_id": 55829,
+                "region": "us-mia",
+                "linode_id": 57328104,
+                "config_id": 60480976,
+                "interface_id": 1373818,
+                "active": false,
+                "nat_1_1": null,
+                "gateway": "10.0.0.1",
+                "prefix": 24,
+                "subnet_mask": "255.255.255.0",
+            }
+        ]
+        ```
+
+

docs/modules/vpcs_ip_list.md

@@ -0,0 +1,65 @@
+# vpcs_ip_list
+
+List and filter on all VPC IP Addresses.
+
+- [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: List all IPs of all VPCs in the account.
+  linode.cloud.vpcs_ip_list: {}
+```
+
+
+## Parameters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `order` | <center>`str`</center> | <center>Optional</center> | The order to list all VPC IP Addresses in.  **(Choices: `desc`, `asc`; Default: `asc`)** |
+| `order_by` | <center>`str`</center> | <center>Optional</center> | The attribute to order all VPC IP Addresses by.   |
+| [`filters` (sub-options)](#filters) | <center>`list`</center> | <center>Optional</center> | A list of filters to apply to the resulting all VPC IP Addresses.   |
+| `count` | <center>`int`</center> | <center>Optional</center> | The number of all VPC IP Addresses to return. If undefined, all results will be returned.   |
+
+### filters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `name` | <center>`str`</center> | <center>**Required**</center> | The name of the field to filter on. Valid filterable fields can be found [here]().   |
+| `values` | <center>`list`</center> | <center>**Required**</center> | A list of values to allow for this field. Fields will pass this filter if at least one of these values matches.   |
+
+## Return Values
+
+- `vpcs_ips` - The returned all VPC IP Addresses.
+
+    - Sample Response:
+        ```json
+        
+        [
+            {
+                "address": "10.0.0.2",
+                "address_range": null,
+                "vpc_id": 56242,
+                "subnet_id": 55829,
+                "region": "us-mia",
+                "linode_id": 57328104,
+                "config_id": 60480976,
+                "interface_id": 1373818,
+                "active": false,
+                "nat_1_1": null,
+                "gateway": "10.0.0.1",
+                "prefix": 24,
+                "subnet_mask": "255.255.255.0",
+            }
+        ]
+        ```
+
+

plugins/module_utils/doc_fragments/vpc_ip_list.py

@@ -0,0 +1,27 @@
+"""Documentation fragments for the vpc_ip_list module"""
+
+specdoc_examples = ["""
+- name: List all IPs of a specific VPC.
+  linode.cloud.vpc_ip_list:
+    vpc_id: 12345""",
+]
+
+result_vpc_ip_view_samples = [
+    """[
+    {
+        "address": "10.0.0.2",
+        "address_range": null,
+        "vpc_id": 56242,
+        "subnet_id": 55829,
+        "region": "us-mia",
+        "linode_id": 57328104,
+        "config_id": 60480976,
+        "interface_id": 1373818,
+        "active": false,
+        "nat_1_1": null,
+        "gateway": "10.0.0.1",
+        "prefix": 24,
+        "subnet_mask": "255.255.255.0",
+    }
+]"""
+]

plugins/module_utils/doc_fragments/vpcs_ip_list.py

@@ -0,0 +1,27 @@
+"""Documentation fragments for the vpcs_ip_list module"""
+
+specdoc_examples = [
+    """
+- name: List all IPs of all VPCs in the account.
+  linode.cloud.vpcs_ip_list: {}""",
+]
+
+result_vpc_samples = ["""
+[
+    {
+        "address": "10.0.0.2",
+        "address_range": null,
+        "vpc_id": 56242,
+        "subnet_id": 55829,
+        "region": "us-mia",
+        "linode_id": 57328104,
+        "config_id": 60480976,
+        "interface_id": 1373818,
+        "active": false,
+        "nat_1_1": null,
+        "gateway": "10.0.0.1",
+        "prefix": 24,
+        "subnet_mask": "255.255.255.0",
+    }
+]"""
+]

plugins/modules/vpc_ip_list.py

@@ -0,0 +1,35 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+"""This module contains all of the functionality for listing IP addresses of a VPC."""
+
+from __future__ import absolute_import, division, print_function
+
+import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.vpc_ip_list as docs
+from ansible_collections.linode.cloud.plugins.module_utils.linode_common_list import (
+    ListModule,
+    ListModuleParam,
+)
+from ansible_specdoc.objects import FieldType
+
+module = ListModule(
+    result_display_name="VPC IP Addresses",
+    result_field_name="vpcs_ips",
+    endpoint_template="/vpcs/{vpc_id}/ips",
+    result_docs_url="",
+    examples=docs.specdoc_examples,
+    result_samples=docs.result_vpc_ip_view_samples,
+    params=[
+        ListModuleParam(
+            display_name="VPC",
+            name="vpc_id",
+            type=FieldType.integer,
+        )
+    ],
+)
+
+
+SPECDOC_META = module.spec
+
+if __name__ == "__main__":
+    module.run()

plugins/modules/vpcs_ip_list.py

@@ -0,0 +1,26 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+"""This module contains all of the functionality for listing IP addresses of all VPCs."""
+
+from __future__ import absolute_import, division, print_function
+
+import ansible_collections.linode.cloud.plugins.module_utils.doc_fragments.vpcs_ip_list as docs
+from ansible_collections.linode.cloud.plugins.module_utils.linode_common_list import (
+    ListModule,
+)
+
+module = ListModule(
+    result_display_name="all VPC IP Addresses",
+    result_field_name="vpcs_ips",
+    endpoint_template="/vpcs/ips",
+    result_docs_url="",
+    examples=docs.specdoc_examples,
+    result_samples=docs.result_vpc_samples,
+)
+
+
+SPECDOC_META = module.spec
+
+if __name__ == "__main__":
+    module.run()

tests/integration/targets/vpc_ip_list/tasks/main.yaml

@@ -0,0 +1,133 @@
+- name: vpc_basic
+  block:
+    - set_fact:
+        r: "{{ 1000000000 | random }}"
+
+    - name: Create a VPC
+      linode.cloud.vpc:
+        label: 'ansible-test-{{ r }}'
+        region: us-mia
+        description: test description
+        state: present
+      register: create_vpc
+
+    - name: Assert VPC created
+      assert:
+        that:
+          - create_vpc.changed
+          - create_vpc.vpc.label == 'ansible-test-{{ r }}'
+          - create_vpc.vpc.region == 'us-mia'
+          - create_vpc.vpc.description == 'test description'
+
+    - name: Create a subnet
+      linode.cloud.vpc_subnet:
+        vpc_id: '{{ create_vpc.vpc.id }}'
+        label: 'test-subnet'
+        ipv4: '10.0.0.0/24'
+        state: present
+      register: create_subnet
+
+    - name: Assert Subnet created
+      assert:
+        that:
+          - create_subnet.changed
+          - create_subnet.subnet.label == 'test-subnet'
+          - create_subnet.subnet.ipv4 == '10.0.0.0/24'
+          - create_subnet.subnet.created != None
+          - create_subnet.subnet.updated != None
+          - create_subnet.subnet.linodes | length == 0
+
+    - name: Create a Linode instance with interface
+      linode.cloud.instance:
+        label: 'ansible-test-{{ r }}'
+        region: us-mia
+        type: g6-nanode-1
+        disks:
+          - label: test-disk
+            filesystem: ext4
+            size: 10
+        configs:
+          - label: cool-config
+            devices:
+              sda:
+                disk_label: test-disk
+            interfaces:
+              - purpose: vpc
+                subnet_id: '{{ create_subnet.subnet.id }}'
+                primary: true
+                ipv4:
+                  vpc: 10.0.0.3
+                  nat_1_1: any
+                ip_ranges: [ "10.0.0.5/32" ]
+        wait: false
+        booted: false
+        state: present
+      register: create_instance
+
+    - name: Assert instance created
+      assert:
+        that:
+          - create_instance.changed
+
+          - create_instance.configs[0].interfaces[0].purpose == 'vpc'
+          - create_instance.configs[0].interfaces[0].subnet_id == create_subnet.subnet.id
+          - create_instance.configs[0].interfaces[0].vpc_id == create_vpc.vpc.id
+          - create_instance.configs[0].interfaces[0].ip_ranges[0] == '10.0.0.5/32'
+          - create_instance.configs[0].interfaces[0].ipv4.nat_1_1 == create_instance.instance.ipv4[0]
+          - create_instance.configs[0].interfaces[0].ipv4.vpc == '10.0.0.3'
+
+    - name: List VPC IPs
+      linode.cloud.vpcs_ip_list:
+      register: all_vpc_ips
+
+    - name: Assert VPC IPs were returned
+      assert:
+        that:
+          - all_vpc_ips.vpcs_ips[0].vpc_id == create_vpc.vpc.id
+          - all_vpc_ips.vpcs_ips[1].vpc_id == create_vpc.vpc.id
+
+    - name: List VPC IPs for a specific VPC
+      linode.cloud.vpc_ip_list:
+        vpc_id: '{{ create_vpc.vpc.id }}'
+      register: vpcs_ips
+
+    - name: Assert VPC IPs were returned
+      assert:
+        that:
+          - vpcs_ips.vpcs_ips[0].vpc_id == create_vpc.vpc.id
+          - vpcs_ips.vpcs_ips[1].vpc_id == create_vpc.vpc.id
+
+  always:
+    - ignore_errors: true
+      block:
+        - name: Delete a Linode instance
+          linode.cloud.instance:
+            label: '{{ create_instance.instance.label }}'
+            state: absent
+          register: delete_instance
+
+        - name: Assert instance delete succeeded
+          assert:
+            that:
+              - delete_instance.changed
+              - delete_instance.instance.id == create_instance.instance.id
+
+        - name: Delete a subnet
+          linode.cloud.vpc_subnet:
+            vpc_id: '{{ create_vpc.vpc.id }}'
+            label: 'test-subnet'
+            state: absent
+          register: delete_subnet
+
+        - name: Delete a VPC
+          linode.cloud.vpc:
+            label: '{{ create_vpc.vpc.label }}'
+            state: absent
+          register: delete_vpc
+
+  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 "" }}'