metal_port resource

docs/guides/network_types.md

@@ -0,0 +1,204 @@
+---
+page_title: "Metal Device Network Types"
+description: |-
+  Use port bonding, address assignments, and VLAN attachments to change the device network type from Layer-3, to Layer-2, to Hybrid.
+---
+
+
+# Network types
+
+Server network types, such as Layer-2, Layer-3, and Hybrid may be familiar to users of the Equinix Metal Portal. In the Portal, you can toggle the network type with a click of the UI. To take advantage of these features in Terraform, which closely follows the Equinix Metal API, it is important to understand that the network type is a composite string value determined by one or more port bonding, addressing, and VLAN attachment configurations. To change the network type, you must change these underlying properties of the port(s).
+
+For more details, see the Equinix Metal documentation on [Network Configuration Types](https://metal.equinix.com/developers/docs/layer2-networking/overview/#network-configuration-types).
+
+This Terraform provider offers two ways to define the network type.
+
+* [`metal_port`](#Metal-Port)
+* [`metal_device_network_type`](#Metal-Device-Network-Type)
+
+## Metal Port
+
+The [`metal_port`](../resources/metal_port.md) resource exposes all of the features needed to affect the network type of a device or port pairing.
+
+Following are examples of how the `metal_port` resource can be used to configure various network types, assuming that `bond0_id` is the UUID of the bond interface containing `eth1`.
+
+### Layer 3 Port
+
+Layer-3 (Bonded) is the default port configuration on Equinix Metal devices. The following is provided to illustrate the usage of the `metal_port` resource. This HCL should not be needed in practice, however it may be useful in some configurations to assert the correct mode is set, port by port, on imported `metal_device` resources or data-sources.
+
+```hcl
+resource "metal_port" "bond0" {
+  port_id = local.bond0_id
+  bonded = true
+}
+
+resource "metal_port" "eth1" {
+  port_id = local.eth1_id
+  bonded = true
+}
+```
+
+### Layer 2 Unbonded Port
+
+```hcl
+resource "metal_port" "bond0" {
+  port_id = local.bond0_id
+  layer2 = true
+  bonded = false
+}
+```
+
+### Layer 2 Bonded Port
+
+```hcl
+resource "metal_port" "bond0" {
+  port_id = local.bond0_id
+  layer2 = true
+  bonded = true
+}
+```
+
+### Hybrid Unbonded Port
+
+```hcl
+resource "metal_port" "bond0" {
+  port_id = local.bond0_id
+  layer2 = false
+  bonded = true
+  depends_on = [metal_port.eth1]
+}
+
+resource "metal_port" "eth1" {
+  port_id = local.eth1_id
+  bonded = false
+}
+```
+
+### Hybrid Bonded Port
+
+```hcl
+resource "metal_port" "bond0" {
+  port_id = local.bond0_id
+  layer2 = false
+  bonded = true
+  vlan_ids = [metal_vlan.test.id]
+}
+
+resource "metal_vlan" "test" {
+  description = "test"
+  metro = "sv"
+  project = metal_project.test.id
+}
+```
+
+### Accessing Port IDs
+
+The port ID value can be obtained from a `metal_device` using a [`for` expression](https://www.terraform.io/docs/language/expressions/for.html).
+
+Assuming a `metal_device` exists with the resource name `test`:
+
+```hcl
+locals {
+  bond0_id = [for p in metal_device.test.ports: p.id if p.name == "bond0"][0]
+   eth1_id = [for p in metal_device.test.ports: p.id if p.name == "eth1"][0]
+}
+```
+
+## Metal Device Network Type
+
+The [`metal_device_network_type`](../resources/metal_device_network_type.md) takes a named network type with any mode required parameters and converts a device to the named network type.  This resource simulated the network type interface for Devices in the Equinix Metal Portal.  That interface changed when additional network types were introduced with more diverse port configurations. 
+
+When using this resource, keep in mind:
+
+* this resource is not guaranteed to work in devices with more than two ethernet ports
+* it may not be able to express all possible port configurations
+* subsequent changes to the network configuration may cause this device to detect changes that can not be reconciled without intervention
+* `metal_device_network_type` resources should not be used on devices with ports being controlled with `metal_port` resources
+
+### Hybrid (Unbonded) Device
+
+This example create one c3.small device and puts it into [hybrid (unbonded) network mode](https://metal.equinix.com/developers/docs/layer2-networking/hybrid-unbonded-mode/).
+
+```hcl
+resource "metal_device" "test" {
+  hostname         = "tfacc-device-port-vlan-attachment-test"
+  plan             = "c3.small.x86"
+  metro            = "ny"
+  operating_system = "ubuntu_20_04"
+  billing_cycle    = "hourly"
+  project_id       = local.project_id
+}
+
+resource "metal_device_network_type" "test" {
+  device_id = metal_device.test.id
+  type      = "hybrid"
+}
+```
+
+### Hybrid (Unbonded) Device with a VLAN
+
+This example create two devices in [hybrid (unbonded) mode](https://metal.equinix.com/developers/docs/layer2-networking/hybrid-unbonded-mode/) and adds a VLAN to their eth1 ports.
+
+```hcl
+locals {
+    project_id = "<uuid>"
+    device_count = 2
+}
+
+resource "metal_vlan" "test" {
+  metro       = "ny"
+  project_id  = local.project_id
+}
+
+
+resource "metal_device" "test" {
+  count            = local.device_count
+  hostname         = "test${count.index}"
+  plan             = "c3.small.x86"
+  metro            = "ny"
+  operating_system = "ubuntu_20_04"
+  billing_cycle    = "hourly"
+  project_id       = local.project_id
+}
+
+resource "metal_device_network_type" "test" {
+  count     = local.device_count
+  device_id = metal_device.test[count.index].id
+  type      = "hybrid"
+}
+
+
+resource "metal_port_vlan_attachment" "test" {
+  count     = local.device_count
+  device_id = metal_device_network_type.test[count.index].id
+  port_name = "eth1"
+  vlan_vnid = metal_vlan.test.vxlan
+}
+```
+
+### Hybrid (Bonded) Device
+
+This example create one c3.small device and puts it into [hybrid-bonded network mode](https://metal.equinix.com/developers/docs/layer2-networking/hybrid-bonded-mode/). Notice, the default network type of `layer3` can be used with VLAN attachments without reconfiguring the device ports.
+
+```hcl
+resource "metal_device" "test" {
+  hostname         = "tfacc-device-port-vlan-attachment-test"
+  plan             = "c3.small.x86"
+  metro            = "ny"
+  operating_system = "ubuntu_20_04"
+  billing_cycle    = "hourly"
+  project_id       = local.project_id
+}
+
+resource "metal_vlan" "test" {
+  metro       = "ny"
+  project_id  = local.project_id
+}
+
+resource "metal_port_vlan_attachment" "test" {
+  count     = local.device_count
+  device_id = metal_device.test.id
+  port_name = "bond0"
+  vlan_vnid = metal_vlan.test.vxlan
+}
+```

docs/resources/device_network_type.md

@@ -19,64 +19,7 @@ If you are attaching VLAN to a device (i.e. using metal_port_vlan_attachment), l
 
 ## Example Usage
 
-### Create one c3.small device and put it to hybrid network mode
-
-```hcl
-resource "metal_device" "test" {
-  hostname         = "tfacc-device-port-vlan-attachment-test"
-  plan             = "c3.small.x86"
-  facilities       = ["ny5"]
-  operating_system = "ubuntu_20_04"
-  billing_cycle    = "hourly"
-  project_id       = local.project_id
-}
-
-resource "metal_device_network_type" "test" {
-  device_id = metal_device.test.id
-  type      = "hybrid"
-}
-```
-
-### Create two devices in hybrid mode and add a VLAN to their eth1 ports
-
-```hcl
-locals {
-    project_id = "<uuid>"
-    device_count = 2
-}
-
-resource "metal_vlan" "test" {
-  facility    = "ny5"
-  project_id  = local.project_id
-}
-
-
-resource "metal_device" "test" {
-  count            = local.device_count
-  hostname         = "test${count.index}"
-  plan             = "c3.small.x86"
-  facilities       = ["ny5"]
-  operating_system = "ubuntu_20_04"
-  billing_cycle    = "hourly"
-  project_id       = local.project_id
-}
-
-resource "metal_device_network_type" "test" {
-  count     = local.device_count
-  device_id = metal_device.test[count.index].id
-  type      = "hybrid"
-}
-
-
-resource "metal_port_vlan_attachment" "test" {
-  count     = local.device_count
-  device_id = metal_device_network_type.test[count.index].id
-  port_name = "eth1"
-  vlan_vnid = metal_vlan.test.vxlan
-}
-
-```
-
+See the [Network Types Guide](../guides/network_types.md) for examples of this resource and to learn about the recommended `metal_port` alternative.
 
 ## Import
 

docs/resources/port.md

@@ -0,0 +1,38 @@
+---
+page_title: "Equinix Metal: precreated_port"
+subcategory: ""
+description: |-
+  Manipulate device ports
+---
+
+# metal_port
+
+Use this resource to set up network ports on an Equnix Metal device. This resource can control both physical and bond ports.
+
+This Terraform resource doesn't create an API resource in Equinix Metal, but rather provides finer control for (Layer 2 networking)[https://metal.equinix.com/developers/docs/layer2-networking/].
+
+The port resource referred is created together with device and accessible either via the device resource or over `/port/<uuid>` API path.
+
+## Example Usage
+
+See the [Network Types Guide](../guides/network_types.md) for examples of this resource.
+
+## Argument Reference
+
+* `port_id` - (Required) ID of the port to read
+* `bonded` - (Required) Whether the port should be bonded
+* `layer2` - (Optional) Whether to put the port to Layer 2 mode, valid only for bond ports
+* `vlan_ids` - (Optional) List off VLAN UUIDs to attach to the port
+* `native_vlan_id` - (Optional) UUID of a VLAN to assign as a native VLAN. It must be one of attached VLANs (from `vlan_ids` parameter), valid only for physical (non-bond) ports
+* `reset_on_delete` - (Optional) Flag indicating whether to reset port to default settings. For a bond port it means layer3 without VLANs attached, physical ports will be bonded without native VLAN and VLANs attached
+
+## Attributes Reference
+
+* `name` - Name of the port, e.g. `bond0` or `eth0`
+* `network_type` - One of layer2-bonded, layer2-individual, layer3, hybrid, hybrid-bonded
+* `type` - Type is either "NetworkBondPort" for bond ports or "NetworkPort" for bondable ethernet ports
+* `mac` - MAC address of the port
+* `bond_id` - UUID of the bond port"
+* `bond_name` - Name of the bond port
+* `bonded` - Flag indicating whether the port is bonded
+* `disbond_supported` - Flag indicating whether the port can be removed from a bond

go.mod

@@ -5,7 +5,7 @@ require (
 	github.com/hashicorp/go-multierror v1.0.0
 	github.com/hashicorp/go-retryablehttp v0.6.6
 	github.com/hashicorp/terraform-plugin-sdk/v2 v2.7.0
-	github.com/packethost/packngo v0.18.0
+	github.com/packethost/packngo v0.19.0
 )
 
 go 1.16

go.sum

@@ -272,8 +272,8 @@ github.com/nsf/jsondiff v0.0.0-20200515183724-f29ed568f4ce h1:RPclfga2SEJmgMmz2k
 github.com/nsf/jsondiff v0.0.0-20200515183724-f29ed568f4ce/go.mod h1:uFMI8w+ref4v2r9jz+c9i1IfIttS/OkmLfrk1jne5hs=
 github.com/oklog/run v1.0.0 h1:Ru7dDtJNOyC66gQ5dQmaCa0qIsAUFY3sFpK1Xk8igrw=
 github.com/oklog/run v1.0.0/go.mod h1:dlhp/R75TPv97u0XWUtDeV/lRKWPKSdTuV0TZvrmrQA=
-github.com/packethost/packngo v0.18.0 h1:MOHoHO1EuF//bFL2ByJ+UvbBPvsY+fjaPf80dgMnh0Q=
-github.com/packethost/packngo v0.18.0/go.mod h1:YrtUNN9IRjjqN6zK+cy2IYoi3EjHfoWTWxJkI1I1Vk0=
+github.com/packethost/packngo v0.19.0 h1:uve9pPODyIEXxJWSurn59hmHt7fHdAxRof0XjwBHRiU=
+github.com/packethost/packngo v0.19.0/go.mod h1:/UHguFdPs6Lf6FOkkSEPnRY5tgS0fsVM+Zv/bvBrmt0=
 github.com/pierrec/lz4 v2.0.5+incompatible/go.mod h1:pdkljMzZIN41W+lC3N2tnIh5sFi+IEE17M5jbnwPHcY=
 github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=