feat: metal virtual circuit (#141)

Fixes #70 Fixes #33
equinix · Mar 20, 2024 · 26fffc6 · 26fffc6
2 parents 3fd1a24 + be348c7
commit 26fffc6
Show file tree

Hide file tree

Showing 9 changed files with 1,002 additions and 2 deletions.
diff --git a/Makefile b/Makefile
@@ -74,4 +74,7 @@ endif
 ifneq ("${METAL_HARDWARE_RESERVATION_PROJECT_ID}", "")
 	echo "metal_hardware_reservation_project_id: ${METAL_HARDWARE_RESERVATION_PROJECT_ID}" >> $(INTEGRATION_CONFIG)
 endif
+ifneq ("${ANSIBLE_ACC_METAL_DEDICATED_CONNECTION_ID}", "")
+	echo "ansible_acc_metal_dedicated_connection_id: ${ANSIBLE_ACC_METAL_DEDICATED_CONNECTION_ID}" >> $(INTEGRATION_CONFIG)
+endif
 
diff --git a/README.md b/README.md
@@ -35,6 +35,7 @@ Name | Description |
 [equinix.cloud.metal_project_ssh_key](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_project_ssh_key.md)|Manage a project ssh key in Equinix Metal|
 [equinix.cloud.metal_reserved_ip_block](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_reserved_ip_block.md)|Create/delete blocks of reserved IP addresses in a project.|
 [equinix.cloud.metal_ssh_key](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_ssh_key.md)|Manage personal SSH keys in Equinix Metal|
+[equinix.cloud.metal_virtual_circuit](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_virtual_circuit.md)|Manage a Virtual Circuit in Equinix Metal|
 [equinix.cloud.metal_vlan](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_vlan.md)|Manage a VLAN resource in Equinix Metal|
 [equinix.cloud.metal_vrf](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_vrf.md)|Manage a VRF resource in Equinix Metal|
 
@@ -60,6 +61,7 @@ Name | Description |
 [equinix.cloud.metal_project_ssh_key_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_project_ssh_key_info.md)|Gather project SSH keys.|
 [equinix.cloud.metal_reserved_ip_block_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_reserved_ip_block_info.md)|Gather list of reserved IP blocks|
 [equinix.cloud.metal_ssh_key_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_ssh_key_info.md)|Gather personal SSH keys|
+[equinix.cloud.metal_virtual_circuit_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_virtual_circuit_info.md)|Gather information about Equinix Metal Virtual Circuits|
 [equinix.cloud.metal_vlan_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_vlan_info.md)|Gather VLANs.|
 [equinix.cloud.metal_vrf_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/v0.5.0/docs/modules/metal_vrf_info.md)|Gather VRFs|
 

diff --git a/docs/modules/metal_virtual_circuit.md b/docs/modules/metal_virtual_circuit.md
@@ -0,0 +1,100 @@
+# metal_virtual_circuit
+
+Manage a Virtual Circuit in Equinix Metal. You can use *id* or *name* to lookup the resource. If you want to create new resource, you must provide *name*.
+
+
+- [Examples](#examples)
+- [Parameters](#parameters)
+- [Return Values](#return-values)
+
+## Examples
+
+```yaml
+- name: create first VRF virtual circuit for test
+  hosts: localhost
+  tasks:
+  - equinix.cloud.metal_virtual_circuit:
+      connection_id: "52373d96-ac4e-496c-8721-f7ef18a01331"
+      port_id: "52373d96-ac4e-496c-8721-f7ef18a01331"
+      name: "test_virtual_circuit"
+      nni_vlan: 1056
+      peer_asn: 66000
+      project_id: "11e047e1-f51a-49c6-b5b2-1c7bfa4391e6"
+      subnet: "192.168.151.126/31"
+      vrf: "029c4219-04b7-4992-9fef-29ea7e2378a5"
+
+```
+
+
+
+
+
+
+
+
+
+
+## Parameters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `id` | <center>`str`</center> | <center>Optional</center> | UUID of the Virtual Circuit.   |
+| `name` | <center>`str`</center> | <center>Optional</center> | Name of the Virtual Circuit resource.  **(Updatable)** |
+| `connection_id` | <center>`str`</center> | <center>Optional</center> | UUID of Connection where the VC is scoped to.   |
+| `project_id` | <center>`str`</center> | <center>Optional</center> | UUID of the Project where the VC is scoped to.   |
+| `port_id` | <center>`str`</center> | <center>Optional</center> | UUID of the Connection Port where the VC is scoped to.   |
+| `nni_vlan` | <center>`int`</center> | <center>Optional</center> | Equinix Metal network-to-network VLAN ID.   |
+| `vlan_id` | <center>`str`</center> | <center>Optional</center> | UUID of the VLAN to associate.   |
+| `vnid` | <center>`str`</center> | <center>Optional</center> | VNID VLAN parameter, see the documentation for Equinix Fabric.   |
+| `description` | <center>`str`</center> | <center>Optional</center> | Description for the Virtual Circuit resource.   |
+| `tags` | <center>`str`</center> | <center>Optional</center> | Tags for the Virtual Circuit resource.   |
+| `speed` | <center>`str`</center> | <center>Optional</center> | Speed of the Virtual Circuit resource.   |
+| `vrf` | <center>`str`</center> | <center>Optional</center> | UUID of the VRF to associate.   |
+| `peer_asn` | <center>`int`</center> | <center>Optional</center> | The BGP ASN of the peer. The same ASN may be the used across several VCs, but it cannot be the same as the local_asn of the VRF.   |
+| `subnet` | <center>`str`</center> | <center>Optional</center> | A subnet from one of the IP blocks associated with the VRF that we will help create an IP reservation for. Can only be either a /30 or /31. For a /31 block, it will only have two IP addresses, which will be used for the metal_ip and customer_ip. For a /30 block, it will have four IP addresses, but the first and last IP addresses are not usable. We will default to the first usable IP address for the metal_ip.   |
+| `metal_ip` | <center>`str`</center> | <center>Optional</center> | The Metal IP address for the SVI (Switch Virtual Interface) of the VirtualCircuit. Will default to the first usable IP in the subnet.   |
+| `customer_ip` | <center>`str`</center> | <center>Optional</center> | The Customer IP address which the CSR switch will peer with. Will default to the other usable IP in the subnet.   |
+| `md5` | <center>`str`</center> | <center>Optional</center> | The password that can be set for the VRF BGP peer   |
+| `timeout` | <center>`int`</center> | <center>Optional</center> | Timeout in seconds for Virtual Circuit to get to "ready" state  **(Default: `15`)** |
+
+
+
+
+
+
+## Return Values
+
+
+
+### Sample Response for metal_virtual_circuit
+```json
+{
+  "changed": false,
+  "customer_ip": "192.168.151.127",
+  "id": "84f35a2f-1e0c-43ee-bd94-87aec0c5ffec",
+  "metal_ip": "192.168.151.126",
+  "name": "test_virtual_circuit",
+  "nni_vlan": 1056,
+  "peer_asn": 66000,
+  "port": {
+    "href": "/metal/v1/connections/52373d96-ac4e-496c-8721-f7ef18a01331/ports/52373d96-ac4e-496c-8721-f7ef18a01331",
+    "id": "4632fb7b-b1cf-48bc-8f20-a69b0a91d326"
+  },
+  "project": {
+    "href": "/metal/v1/projects/11e047e1-f51a-49c6-b5b2-1c7bfa4391e6",
+    "id": "11e047e1-f51a-49c6-b5b2-1c7bfa4391e6"
+  },
+  "project_id": "11e047e1-f51a-49c6-b5b2-1c7bfa4391e6",
+  "status": "active",
+  "subnet": "192.168.151.126/31",
+  "tags": [],
+  "type": "vrf",
+  "vrf": {
+    "bill": false,
+    "href": "/metal/v1/vrfs/029c4219-04b7-4992-9fef-29ea7e2378a5",
+    "id": "029c4219-04b7-4992-9fef-29ea7e2378a5"
+  }
+}
+```
+
+
diff --git a/docs/modules/metal_virtual_circuit_info.md b/docs/modules/metal_virtual_circuit_info.md
@@ -0,0 +1,59 @@
+# metal_virtual_circuit_info
+
+Gather information about Equinix Metal Virtual Circuits
+
+
+- [Examples](#examples)
+- [Parameters](#parameters)
+- [Return Values](#return-values)
+
+## Examples
+
+```yaml
+- name: Gather information about all projects in an organization
+  hosts: localhost
+  tasks:
+      - equinix.cloud.metal_virtual_circuit_info:
+          organization_id: 2a5122b9-c323-4d5c-b53c-9ad3f54273e7
+
+```
+
+
+
+
+
+
+
+
+
+
+## Parameters
+
+| Field     | Type | Required | Description                                                                  |
+|-----------|------|----------|------------------------------------------------------------------------------|
+| `connection_id` | <center>`str`</center> | <center>Optional</center> | ID of the virtual circuit resource   |
+| `organization_id` | <center>`str`</center> | <center>Optional</center> | ID of the organisation to which the virtual circuit belongs   |
+
+
+
+
+
+
+## Return Values
+
+
+
+### Sample Response for resources
+```json
+{
+  "backend_transfer_enabled": false,
+  "customdata": {},
+  "description": "",
+  "id": "31d3ae8b-bd5a-41f3-a420-055211345cc7",
+  "name": "ansible-integration-test-project-csle6t2y-project2",
+  "organization_id": "70c2f878-9f32-452e-8c69-ab15480e1d99",
+  "payment_method_id": "845b45a3-c565-47e5-b9b6-a86204a73d29"
+}
+```
+
+
diff --git a/plugins/module_utils/metal/api_routes.py b/plugins/module_utils/metal/api_routes.py
@@ -78,6 +78,12 @@ def get_routes(mpc):
         ("metal_plan", action.GET): spec_types.Specs(
             equinix_metal.PlansApi(mpc).find_plans_by_project,
         ),
+        ('metal_virtual_circuit', action.GET): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).get_virtual_circuit,
+        ),
+        ('metal_virtual_circuit_vrf', action.GET): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).get_virtual_circuit,
+        ),
 
         # LISTERS
         ('metal_project_device', action.LIST): spec_types.Specs(
@@ -161,6 +167,18 @@ def get_routes(mpc):
             equinix_metal.PlansApi(mpc).find_plans,
             {'category': 'category', 'type': 'type', 'slug': 'slug', 'include': 'include', 'exclude': 'exclude'},
         ),
+        ('metal_virtual_circuit', action.LIST): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).list_interconnection_virtual_circuits,
+            {'connection_id': 'connection_id'},
+        ),
+        ('metal_virtual_circuit_vrf', action.LIST): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).list_interconnection_virtual_circuits,
+            {'connection_id': 'connection_id'},
+        ),
+        ('metal_port_virtual_circuit', action.LIST): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).list_interconnection_port_virtual_circuits,
+            {'connection_id': 'connection_id', 'port_id': 'port_id'},
+        ),
 
         # DELETERS
         ('metal_device', action.DELETE): spec_types.Specs(
@@ -194,7 +212,12 @@ def get_routes(mpc):
         ('metal_bgp_session', action.DELETE): spec_types.Specs(
             equinix_metal.BGPApi(mpc).delete_bgp_session,
         ),
-
+        ('metal_virtual_circuit', action.DELETE): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).delete_virtual_circuit,
+        ),
+        ('metal_virtual_circuit_vrf', action.DELETE): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).delete_virtual_circuit,
+        ),
 
         # CREATORS
         ('metal_device', action.CREATE): spec_types.Specs(
@@ -284,6 +307,19 @@ def get_routes(mpc):
             {'id': 'project_id'},
             equinix_metal.BgpConfigRequestInput,
         ),
+        ('metal_virtual_circuit', action.CREATE): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).create_interconnection_port_virtual_circuit,
+            {'connection_id': 'connection_id', 'port_id': 'port_id'},
+            equinix_metal.VlanVirtualCircuitCreateInput,
+            equinix_metal.VirtualCircuitCreateInput,
+        ),
+        ('metal_virtual_circuit_vrf', action.CREATE): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).create_interconnection_port_virtual_circuit,
+            {'connection_id': 'connection_id', 'port_id': 'port_id'},
+            equinix_metal.VrfVirtualCircuitCreateInput,
+            equinix_metal.VirtualCircuitCreateInput,
+        ),
+
 
         # UPDATERS
         ('metal_device', action.UPDATE): spec_types.Specs(
@@ -326,4 +362,16 @@ def get_routes(mpc):
             {},
             equinix_metal.BGPSessionInput,
         ),
+        ('metal_virtual_circuit', action.UPDATE): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).update_virtual_circuit,
+            {},
+            equinix_metal.VlanVirtualCircuitUpdateInput,
+            equinix_metal.VirtualCircuitUpdateInput,
+        ),
+        ('metal_virtual_circuit_vrf', action.UPDATE): spec_types.Specs(
+            equinix_metal.InterconnectionsApi(mpc).update_virtual_circuit,
+            {},
+            equinix_metal.VrfVirtualCircuitUpdateInput,
+            equinix_metal.VirtualCircuitUpdateInput,
+        ),
     }
diff --git a/plugins/module_utils/metal/metal_api.py b/plugins/module_utils/metal/metal_api.py
@@ -131,7 +131,7 @@ def extract_ids_from_projects_hrefs(resource: dict):
     'name': 'name',
     'metro': 'metro',
     'project_id': 'project.id',
-    'description': 'description',
+    'description': optional_str('description'),
     'local_asn': 'local_asn',
     'ip_ranges': 'ip_ranges',
 }
@@ -152,6 +152,7 @@ def extract_ids_from_projects_hrefs(resource: dict):
     'bgp_sessions',     # metal_bgp_session
     'sessions',         # metal_bgp_session_info
     'plans',
+    'virtual_circuits',
 ]
 
 
@@ -289,6 +290,23 @@ def private_ipv4_subnet_size(resource: dict):
     'available_in_metros': 'available_in_metros',
 }
 
+METAL_VIRTUAL_CIRCUIT_RESPONSE_ATTRIBUTE_MAP = {
+    'id': 'id',
+    'name': 'name',
+    'customer_ip': 'customer_ip',
+    'metal_ip': 'metal_ip',
+    'nni_vlan': 'nni_vlan',
+    'peer_asn': 'peer_asn',
+    'port': 'port',
+    'project': 'project',
+    'status': 'status',
+    'subnet': optional('subnet'),
+    'tags': 'tags',
+    'type': 'type',
+    'vrf': 'vrf',
+    'project_id': 'project.id',
+}
+
 
 def get_attribute_mapper(resource_type):
     """
@@ -309,6 +327,7 @@ def get_attribute_mapper(resource_type):
     bgp_resources = {'metal_bgp_session', 'metal_bgp_session_by_project'}
     project_bgp_config_resources = {'metal_project_bgp_config'}
     plan_resources = set(["metal_plan"])
+    virtual_circuit_resources = set(["metal_virtual_circuit", "metal_virtual_circuit_vrf"])
     if resource_type in device_resources:
         return METAL_DEVICE_RESPONSE_ATTRIBUTE_MAP
     elif resource_type in project_resources:
@@ -341,6 +360,8 @@ def get_attribute_mapper(resource_type):
         return METAL_PROJECT_BGP_CONFIG_RESPONSE_ATTRIBUTE_MAP
     elif resource_type in plan_resources:
         return METAL_PLAN_RESPONSE_ATTRIBUTE_MAP
+    elif resource_type in virtual_circuit_resources:
+        return METAL_VIRTUAL_CIRCUIT_RESPONSE_ATTRIBUTE_MAP
     else:
         raise NotImplementedError("No mapper for resource type %s" % resource_type)