guide: Migrating to Metro VLANs

[displague]

Users with traditional Facility bound VLANs may wish to "upgrade" their VLANs to Metro VLANs. Create a guide for this workflow.

(All of this is subject to review, but I think the migration guide could be based on the following workflow)

Because these resources are quick to reprovision and carry minimal state (VXLAN / VNI), it should be safe in many configurations (as long as all resources are Terraform managed) to replace legacy facility bound VLANs with Metro VLANs. The devices will experience a temporary detachment from the VLAN, so the applications and OS must be capable of handling that level of interruption.

A Metro VXLAN can not be created while facilities in that metro have the same VXLAN. We must delete the legacy VLANs to create new metro VLANs.

If all of their infrastructure within a project is managed by Terraform, this should be painless:

• modify all metal_vlan resources to use the metro field (not the facility field)
  • set the vxlan value to the desired vxlan (the existing vxlan used by the facility VLAN)
• modify all metal_port_vlan_attachment resources to use the metro field (not facility)
  • This guide should not be used If VLAN attachments are managed outside of Terraform, or through provisioners, for example.
• terraform apply

This will:

• destroy all facility metal_vlan resources
• destroy all metal_port_vlan_attachment resources
• devices will no longer have a connection to their layer 2 network, the affects of this state will depend on the application
• recreate metal_vlan resources with metro scoped vlans
• reattach vlans to devices with metro filtered metal_port_vlan_attachment resources

Any references to deployed_facility in VLANs indicate that the VLAN is following the deployment of a facility-bound device. Change the device to use metro and update the VLAN to match the device's metro.

[displague]

Relevant to https://registry.terraform.io/providers/equinix/metal/latest/docs/guides/migration_guide_facilities_to_metros_devices

It is also worth pointing out that IP address datasources can be changed to filter by metro rather than facility, in most cases. Likewise, IP reservation resources that have already been assigned can be safely changed from facility = ... to metro = ... (so long as the metro matches the facility's metro).