Deprecate facility/facilities

This marks all `facility` and `facilities` properties as deprecated, and deprecates `data_source_equinix_metal_facility`. Deprecation messages link to the facility-to-metro [migration guide]. That migration guide was updated in a separate PR to include a link to the [facilities deprecation announcement]. [migration guide]: https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices [facilities deprecation announcement]: https://feedback.equinixmetal.com/changelog/bye-facilities-hello-again-metros.
equinix · Apr 13, 2023 · af87315 · af87315
1 parent 97f5ba0
commit af87315
Show file tree

Hide file tree

Showing 36 changed files with 90 additions and 87 deletions.
diff --git a/docs/data-sources/equinix_metal_connection.md b/docs/data-sources/equinix_metal_connection.md
@@ -28,7 +28,7 @@ In addition to all arguments above, the following attributes are exported:
 
 * `name` - Name of the connection resource.
 * `metro` - Slug of a metro to which the connection belongs.
-* `facility` - Slug of a facility to which the connection belongs.
+* `facility` - (**Deprecated**) Slug of a facility to which the connection belongs. Use metro instead; read the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices)
 * `redundancy` - Connection redundancy, reduntant or primary.
 * `type` - Connection type, dedicated or shared.
 * `project_id` - ID of project to which the connection belongs.

diff --git a/docs/data-sources/equinix_metal_device.md b/docs/data-sources/equinix_metal_device.md
@@ -54,7 +54,7 @@ In addition to all arguments above, the following attributes are exported:
 * `access_public_ipv4` - The ipv4 management IP assigned to the device.
 * `access_public_ipv6` - The ipv6 management IP assigned to the device.
 * `billing_cycle` - The billing cycle of the device (monthly or hourly).
-* `facility` - The facility where the device is deployed.
+* `facility` - (**Deprecated**) The facility where the device is deployed. Use metro instead; read the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices)
 * `description` - Description string for the device.
 * `hardware_reservation_id` - The id of hardware reservation which this device occupies.
 * `id` - The ID of the device.

diff --git a/docs/data-sources/equinix_metal_facility.md b/docs/data-sources/equinix_metal_facility.md
@@ -4,6 +4,8 @@ subcategory: "Metal"
 
 # equinix_metal_facility (Data Source)
 
+> **Deprecated** Use `equinix_metal_metro` instead.  For more information, refer to the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices).
+
 Provides an Equinix Metal facility datasource.
 
 ## Example Usage

diff --git a/docs/data-sources/equinix_metal_hardware_reservation.md b/docs/data-sources/equinix_metal_hardware_reservation.md
@@ -38,7 +38,7 @@ In addition to all arguments above, the following attributes are exported:
 * `project_id` - UUID of project this reservation is scoped to.
 * `device_id` - UUID of device occupying the reservation.
 * `plan` - Plan type for the reservation.
-* `facility` - Plan type for the reservation.
+* `facility` - (**Deprecated**) Facility for the reservation. Use metro instead; read the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices)
 * `provisionable` - Flag indicating whether the reserved server is provisionable or not. Spare
 devices can't be provisioned unless they are activated first.
 * `spare` - Flag indicating whether the Hardware Reservation is a spare. Spare Hardware

diff --git a/docs/data-sources/equinix_metal_ip_block_ranges.md b/docs/data-sources/equinix_metal_ip_block_ranges.md
@@ -34,8 +34,8 @@ output "out" {
 The following arguments are supported:
 
 * `project_id` - (Required) ID of the project from which to list the blocks.
-* `facility` - (Optional) Facility code filtering the IP blocks. Global IPv4 blocks will be listed
-anyway. If you omit this and metro, all the block from the project will be listed.
+* `facility` - (**Deprecated**) Facility code filtering the IP blocks. Global IPv4 blocks will be listed
+anyway. If you omit this and metro, all the block from the project will be listed.   Use metro instead; read the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices)
 * `metro` - (Optional) Metro code filtering the IP blocks. Global IPv4 blocks will be listed
 anyway. If you omit this and facility, all the block from the project will be listed.
 

diff --git a/docs/data-sources/equinix_metal_metro.md b/docs/data-sources/equinix_metal_metro.md
@@ -25,7 +25,7 @@ output "id" {
   devices and 1 c3.medium.x86 device
 
 data "equinix_metal_metro" "test" {
-  code = "dc13"
+  code = "sv"
 
   capacity {
     plan = "c3.small.x86"
@@ -43,10 +43,10 @@ data "equinix_metal_metro" "test" {
 
 The following arguments are supported:
 
-* `code` - (Required) The facility code to search for facilities.
-* `capacity` - (Optional) One or more device plans for which the facility must have capacity.
+* `code` - (Required) The metro code to search for.
+* `capacity` - (Optional) One or more device plans for which the metro must have capacity.
   * `plan` - (Required) Device plan that must be available in selected location.
-  * `quantity` - (Optional) Minimun number of devices that must be available in selected location.
+  * `quantity` - (Optional) Minimum number of devices that must be available in selected location.
   Default is `1`.
 
 ## Attributes Reference

diff --git a/docs/data-sources/equinix_metal_operating_system.md b/docs/data-sources/equinix_metal_operating_system.md
@@ -18,7 +18,7 @@ data "equinix_metal_operating_system" "example" {
 resource "equinix_metal_device" "server" {
   hostname         = "tf.ubuntu"
   plan             = "c3.medium.x86"
-  facilities       = ["ny5"]
+  metro            = "ny"
   operating_system = data.equinix_metal_operating_system.example.id
   billing_cycle    = "hourly"
   project_id       = local.project_id

diff --git a/docs/data-sources/equinix_metal_plans.md b/docs/data-sources/equinix_metal_plans.md
@@ -57,13 +57,13 @@ output "plans" {
 }
 ```
 
-### Ignoring Changes to Plans/Facilities/Metro
+### Ignoring Changes to Plans/Metro
 
 Preserve deployed device plan, facility and metro when creating a new execution plan.
 
 As described in the [`data-resource-behavior`](https://www.terraform.io/language/data-sources#data-resource-behavior), terraform reads data resources during the planning phase in both the terraform plan and terraform apply commands. If the output from the data source is different to the prior state, it will propose changes to resources where there is a reference to their attributes.
 
-For `equinix_metal_plans`, it may happen that a device plan is no longer available in a facility/metro because there is no stock at that time or you were using a legacy server plan, and thus the returned list of plans matching your search criteria will be different from last `plan`/`apply`. Therefore, if a resource such as a `equinix_metal_device` uses the output of this data source to select a device plan or facility/metro, the Terraform plan will report that the `equinix_metal_device` needs to be recreated.
+For `equinix_metal_plans`, it may happen that a device plan is no longer available in a metro because there is no stock at that time or you were using a legacy server plan, and thus the returned list of plans matching your search criteria will be different from last `plan`/`apply`. Therefore, if a resource such as a `equinix_metal_device` uses the output of this data source to select a device plan or metro, the Terraform plan will report that the `equinix_metal_device` needs to be recreated.
 
 To prevent that you can take advantage of the Terraform [`lifecycle ignore_changes`](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes) feature as shown in the example below.
 
@@ -84,32 +84,32 @@ data "equinix_metal_plans" "example" {
     }
 }
 
-# This equinix_metal_device will use the first returned plan and the list of facilities
-# It will ignore future changes on plan and facilities
+# This equinix_metal_device will use the first returned plan and the first metro in which that plan is available
+# It will ignore future changes on plan and metro
 resource "equinix_metal_device" "example" {
   hostname         = "example"
   plan             = data.equinix_metal_plans.example.plans[0].name
-  facilities       = data.equinix_metal_plans.example.plans[0].available_in
+  metro            = data.equinix_metal_plans.example.plans[0].available_in_metros[0]
   operating_system = "ubuntu_20_04"
   billing_cycle    = "hourly"
   project_id       = var.project_id
 
   lifecycle {
     ignore_changes = [
         plan,
-        facilities,
+        metro,
     ]
   }
 }
 ```
 
-If your use case requires dynamic changes of a device plan or metro/facility you can define the lifecycle with a condition.
+If your use case requires dynamic changes of a device plan or metro you can define the lifecycle with a condition.
 
 ```hcl
 # Following example uses a boolean variable that may eventually be set to you false when you update your equinix_metal_plans filter criteria because you need a device plan with a new feature.
-variable "ignore_plans_facilities_changes" {
+variable "ignore_plans_metros_changes" {
   type = bool
-  description = "If set to true, it will ignore plans or facilities changes"
+  description = "If set to true, it will ignore plans or metros changes"
   default = false
 }
 
@@ -121,9 +121,9 @@ resource "equinix_metal_device" "example" {
   // required device arguments
 
   lifecycle {
-    ignore_changes = var.ignore_plans_facilities_changes ? [
+    ignore_changes = var.ignore_plans_metros_changes ? [
         plan,
-        facilities,
+        metro,
     ] : []
   }
 }
@@ -149,7 +149,7 @@ All fields in the `plans` block defined below can be used as attribute for both
 
 In addition to all arguments above, the following attributes are exported:
 
-* `plans` - The ID of the facility
+* `plans`
   - `id` - id of the plan
   - `name` - name of the plan
   - `slug`- plan slug
@@ -160,5 +160,5 @@ In addition to all arguments above, the following attributes are exported:
   - `pricing_hour`- plan hourly price
   - `pricing_month`- plan monthly price
   - `deployment_types`- list of deployment types, e.g. on_demand, spot_market
-  - `available_in`- list of facilities where the plan is available
-  - `available_in_metros`- list of facilities where the plan is available
+  - `available_in`- (**Deprecated**) list of facilities where the plan is available
+  - `available_in_metros`- list of metros where the plan is available
diff --git a/docs/data-sources/equinix_metal_port.md b/docs/data-sources/equinix_metal_port.md
@@ -19,7 +19,7 @@ locals {
 resource "equinix_metal_device" "test" {
   hostname         = "tfacc-test-device-port"
   plan             = "c3.medium.x86"
-  facilities       = ["sv15"]
+  metro            = "sv"
   operating_system = "ubuntu_20_04"
   billing_cycle    = "hourly"
   project_id       = local.project_id

diff --git a/docs/data-sources/equinix_metal_precreated_ip_block.md b/docs/data-sources/equinix_metal_precreated_ip_block.md
@@ -58,7 +58,7 @@ The following arguments are supported:
 * `address_family` - (Required) 4 or 6, depending on which block you are looking for.
 * `public` - (Required) Whether to look for public or private block.
 * `global` - (Optional) Whether to look for global block. Default is false for backward compatibility.
-* `facility` - (Optional) Facility of the searched block. (for non-global blocks).
+* `facility` - (**Deprecated**) Facility of the searched block. (for non-global blocks). Use metro instead; read the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices)
 * `metro` - (Optional) Metro of the searched block (for non-global blocks).
 
 ## Attributes Reference

diff --git a/docs/data-sources/equinix_metal_spot_market_price.md b/docs/data-sources/equinix_metal_spot_market_price.md
@@ -8,15 +8,6 @@ Use this data source to get Equinix Metal Spot Market Price for a plan.
 
 ## Example Usage
 
-Lookup by facility:
-
-```hcl
-data "equinix_metal_spot_market_price" "example" {
-  facility = "ny5"
-  plan     = "c3.small.x86"
-}
-```
-
 Lookup by metro:
 
 ```hcl
@@ -31,7 +22,7 @@ data "equinix_metal_spot_market_price" "example" {
 The following arguments are supported:
 
 * `plan` - (Required) Name of the plan.
-* `facility` - (Optional) Name of the facility.
+* `facility` - (**Deprecated**) Name of the facility. Use metro instead; read the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices)
 * `metro` - (Optional) Name of the metro.
 
 ## Attributes Reference

diff --git a/docs/data-sources/equinix_metal_spot_market_request.md b/docs/data-sources/equinix_metal_spot_market_request.md
@@ -15,7 +15,7 @@ device IDs created by referenced Spot Market Request.
 resource "equinix_metal_spot_market_request" "req" {
   project_id       = local.project_id
   max_bid_price    = 0.1
-  facilities       = ["ny5"]
+  metro            = "ny"
   devices_min      = 2
   devices_max      = 2
   wait_for_devices = true
@@ -79,7 +79,7 @@ In addition to all arguments above, the following attributes are exported:
 * `devices_min` - Miniumum number devices to be created.
 * `devices_max` - Maximum number devices to be created.
 * `max_bid_price` - Maximum price user is willing to pay per hour per device.
-* `facilities` - Facility IDs where devices should be created.
+* `facilities` - (**Deprecated**) Facility IDs where devices should be created. Use metro instead; read the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices)
 * `metro` - Metro where devices should be created.
 * `project_id` - Project ID.
 * `plan` - The device plan slug.

diff --git a/docs/data-sources/equinix_metal_vlan.md b/docs/data-sources/equinix_metal_vlan.md
@@ -40,7 +40,7 @@ The following arguments are supported:
 * `vlan_id` - (Optional) Metal UUID of the VLAN resource to look up.
 * `project_id` - (Optional) UUID of parent project of the VLAN. Use together with the vxlan number and metro or facility.
 * `vxlan` - (Optional) vxlan number of the VLAN to look up. Use together with the project_id and metro or facility.
-* `facility` - (Optional) Facility where the VLAN is deployed.
+* `facility` - (Optional) Facility where the VLAN is deployed. Deprecated, see https://feedback.equinixmetal.com/changelog/bye-facilities-hello-again-metros
 * `metro` - (Optional) Metro where the VLAN is deployed.
 
 -> **NOTE:** You must set either `vlan_id` or a combination of `vxlan`, `project_id`, and, `metro` or `facility`.

diff --git a/docs/resources/equinix_metal_bgp_session.md b/docs/resources/equinix_metal_bgp_session.md
@@ -38,14 +38,14 @@ locals {
 
 resource "equinix_metal_reserved_ip_block" "addr" {
   project_id = local.project_id
-  facility   = "ny5"
+  metro      = "ny"
   quantity   = 1
 }
 
 resource "equinix_metal_device" "test" {
   hostname         = "terraform-test-bgp-sesh"
   plan             = "c3.small.x86"
-  facilities       = ["ny5"]
+  metro            = ["ny"]
   operating_system = "ubuntu_20_04"
   billing_cycle    = "hourly"
   project_id       = local.project_id

diff --git a/docs/resources/equinix_metal_connection.md b/docs/resources/equinix_metal_connection.md
@@ -115,7 +115,7 @@ The following arguments are supported:
 
 * `name` - (Required) Name of the connection resource
 * `metro` - (Optional) Metro where the connection will be created.
-* `facility` - (Optional) Facility where the connection will be created.
+* `facility` - (**Deprecated**) Facility where the connection will be created.   Use metro instead; read the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices)
 * `redundancy` - (Required) Connection redundancy - redundant or primary.
 * `type` - (Required) Connection type - dedicated or shared.
 * `project_id` - (Optional) ID of the project where the connection is scoped to, must be set for.

diff --git a/docs/resources/equinix_metal_device.md b/docs/resources/equinix_metal_device.md
@@ -42,13 +42,13 @@ resource "equinix_metal_device" "pxe1" {
 }
 ```
 
-Create a device without a public IP address in facility ny5, with only a /30 private IPv4 subnet (4 IP addresses)
+Create a device without a public IP address in metro ny, with only a /30 private IPv4 subnet (4 IP addresses)
 
 ```hcl
 resource "equinix_metal_device" "web1" {
   hostname         = "tf.coreos2"
   plan             = "c3.small.x86"
-  facilities       = ["ny5"]
+  metro            = "ny"
   operating_system = "ubuntu_20_04"
   billing_cycle    = "hourly"
   project_id       = local.project_id
@@ -65,7 +65,7 @@ Deploy device on next-available reserved hardware and do custom partitioning.
 resource "equinix_metal_device" "web1" {
   hostname                = "tftest"
   plan                    = "c3.small.x86"
-  facilities              = ["ny5"]
+  metro                   = "ny"
   operating_system        = "ubuntu_20_04"
   billing_cycle           = "hourly"
   project_id              = local.project_id
@@ -162,11 +162,11 @@ on reboots.
 * `billing_cycle` - (Optional) monthly or hourly
 * `custom_data` - (Optional) A string of the desired Custom Data for the device.  By default, changing this attribute will cause the provider to destroy and recreate your device.  If `reinstall` is specified or `behavior.allow_changes` includes `"custom_data"`, the device will be updated in-place instead of recreated.
 * `description` - (Optional) The device description.
-* `facilities` - (Optional) List of facility codes with deployment preferences. Equinix Metal API will go
+* `facilities` - (**Deprecated**) List of facility codes with deployment preferences. Equinix Metal API will go
 through the list and will deploy your device to first facility with free capacity. List items must
 be facility codes or `any` (a wildcard). To find the facility code, visit
 [Facilities API docs](https://metal.equinix.com/developers/api/facilities/), set your API auth
-token in the top of the page and see JSON from the API response. Conflicts with `metro`.
+token in the top of the page and see JSON from the API response. Conflicts with `metro`.  Use metro instead; read the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices)
 * `force_detach_volumes` - (Optional) Delete device even if it has volumes attached. Only applies
 for destroy action.
 * `hardware_reservation_id` - (Optional) The UUID of the hardware reservation where you want this
@@ -265,7 +265,7 @@ In addition to all arguments above, the following attributes are exported:
 * `access_public_ipv6` - The ipv6 maintenance IP assigned to the device.
 * `billing_cycle` - The billing cycle of the device (monthly or hourly).
 * `created` - The timestamp for when the device was created.
-* `deployed_facility` - The facility where the device is deployed.
+* `deployed_facility` - (**Deprecated**) The facility where the device is deployed. Use metro instead; read the [facility to metro migration guide](https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/migration_guide_facilities_to_metros_devices)
 * `deployed_hardware_reservation_id` - ID of hardware reservation where this device was deployed.
 It is useful when using the `next-available` hardware reservation.
 * `description` - Description string for the device.

diff --git a/docs/resources/equinix_metal_ip_attachment.md b/docs/resources/equinix_metal_ip_attachment.md
@@ -7,22 +7,22 @@ subcategory: "Metal"
 Provides a resource to attach elastic IP subnets to devices.
 
 To attach an IP subnet from a reserved block to a provisioned device, you must derive a subnet CIDR
-belonging to one of your reserved blocks in the same project and facility as the target device.
+belonging to one of your reserved blocks in the same project and metro as the target device.
 
 For example, you have reserved IPv4 address block `147.229.10.152/30`, you can choose to assign
 either the whole block as one subnet to a device; or 2 subnets with CIDRs `147.229.10.152/31` and
 `147.229.10.154/31`; or 4 subnets with mask prefix length `32`. More about the elastic IP subnets
 is [here](https://metal.equinix.com/developers/docs/networking/elastic-ips/).
 
-Device and reserved block must be in the same facility.
+Device and reserved block must be in the same metro.
 
 ## Example Usage
 
 ```hcl
-# Reserve /30 block of max 2 public IPv4 addresses in Parsippany, NJ (ny5) for myproject
+# Reserve /30 block of max 2 public IPv4 addresses in metro ny for myproject
 resource "equinix_metal_reserved_ip_block" "myblock" {
   project_id = local.project_id
-  facility   = "ny5"
+  metro      = "ny"
   quantity   = 2
 }
 
@@ -40,7 +40,7 @@ The following arguments are supported:
 
 * `device_id` - (Required) ID of device to which to assign the subnet.
 * `cidr_notation` - (Required) CIDR notation of subnet from block reserved in the same project
-and facility as the device.
+and metro as the device.
 
 ## Attributes Reference