From 37c4d067eada9646cec4e5ee04795f9a3e74a45b Mon Sep 17 00:00:00 2001 From: Charles Treatman Date: Wed, 17 Apr 2024 12:20:04 -0500 Subject: [PATCH] demonstrate conversion to generated schema attributes --- docs/data-sources/metal_device.md | 117 ++++++------- docs/index.md | 31 ++-- docs/resources/metal_device.md | 183 +++++++++----------- equinix/data_source_metal_device.go | 5 + equinix/provider.go | 14 +- equinix/resource_metal_device.go | 3 + internal/provider/provider.go | 14 +- main.go | 2 +- templates/data-sources.md.tmpl | 8 - templates/data-sources/metal_device.md.tmpl | 74 +------- templates/index.md.tmpl | 28 +-- templates/resources.md.tmpl | 27 +++ templates/resources/metal_device.md.tmpl | 137 +-------------- 13 files changed, 220 insertions(+), 423 deletions(-) create mode 100644 templates/resources.md.tmpl diff --git a/docs/data-sources/metal_device.md b/docs/data-sources/metal_device.md index 35393630a..01887a9ec 100644 --- a/docs/data-sources/metal_device.md +++ b/docs/data-sources/metal_device.md @@ -36,64 +36,59 @@ output "ipv4" { } ``` -## Argument Reference - -The following arguments are supported: - -* `hostname` - (Optional) The device name. -* `project_id` - (Optional) The id of the project in which the devices exists. -* `device_id` - (Optional) Device ID. - --> **NOTE:** You should pass either `device_id`, or both `project_id` and `hostname`. - -## Attributes Reference - -In addition to all arguments above, the following attributes are exported: - -* `access_private_ipv4` - The ipv4 private IP assigned to the device. -* `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` - (**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. -* `metro` - The metro where the device is deployed -* `network` - The device's private and public IP (v4 and v6) network details. See [Network Attribute](#network-attribute) below for more details. -* `network_type` - L2 network type of the device, one of `layer3`, `layer2-bonded`, `layer2-individual`, `hybrid`. -* `operating_system` - The operating system running on the device. -* `plan` - The hardware config of the device. -* `ports` - List of ports assigned to the device. See [Ports Attribute](#ports-attribute) below for more details. -* `root_password` - Root password to the server (if still available). -* `sos_hostname` - The hostname to use for [Serial over SSH](https://deploy.equinix.com/developers/docs/metal/resilience-recovery/serial-over-ssh/) access to the device -* `ssh_key_ids` - List of IDs of SSH keys deployed in the device, can be both user or project SSH keys. -* `state` - The state of the device. -* `tags` - Tags attached to the device. - -### Network Attribute - -When a device is run without any special network, it will have 3 networks: - -* Public IPv4 at `equinix_metal_device.name.network.0`. -* IPv6 at `equinix_metal_device.name.network.1`. -* Private IPv4 at `equinix_metal_device.name.network.2`. - --> **NOTE:** Elastic addresses stack by type. An assigned public IPv4 will go after the management public IPv4 (to index 1), and will then shift the indices of the IPv6 and private IPv4. Assigned private IPv4 will go after the management private IPv4 (to the end of the network list). - -Each element in the `network` list exports: - -* `address` - IPv4 or IPv6 address string. -* `cidr` - Bit length of the network mask of the address. -* `gateway` - Address of router. -* `public` - Whether the address is routable from the Internet. -* `family` - IP version. One of `4`, `6`. - -### Ports Attribute - -Each element in the `ports` list exports: - -* `name` - Name of the port (e.g. `eth0`, or `bond0`). -* `id` - ID of the port. -* `type` - Type of the port (e.g. `NetworkPort` or `NetworkBondPort`). -* `mac` - MAC address assigned to the port. -* `bonded` - Whether this port is part of a bond in bonded network setup. + +## Schema + +### Optional + +- `device_id` (String) Device ID +- `hostname` (String) The device name +- `project_id` (String) The id of the project in which the devices exists + +### Read-Only + +- `access_private_ipv4` (String) The ipv4 private IP assigned to the device +- `access_public_ipv4` (String) The ipv4 management IP assigned to the device +- `access_public_ipv6` (String) The ipv6 management IP assigned to the device +- `always_pxe` (Boolean) +- `billing_cycle` (String) The billing cycle of the device (monthly or hourly) +- `description` (String) Description string for the device +- `facility` (String, Deprecated) The facility where the device is deployed +- `hardware_reservation_id` (String) The id of hardware reservation which this device occupies +- `id` (String) The ID of this resource. +- `ipxe_script_url` (String) +- `metro` (String) The metro where the device is deployed +- `network` (List of Object) The device's private and public IP (v4 and v6) network details. When a device is run without any special network configuration, it will have 3 networks: ublic IPv4 at equinix_metal_device.name.network.0, IPv6 at equinix_metal_device.name.network.1 and private IPv4 at equinix_metal_device.name.network.2. Elastic addresses then stack by type - an assigned public IPv4 will go after the management public IPv4 (to index 1), and will then shift the indices of the IPv6 and private IPv4. Assigned private IPv4 will go after the management private IPv4 (to the end of the network list). (see [below for nested schema](#nestedatt--network)) +- `network_type` (String) L2 network type of the device, one oflayer3, hybrid, layer2-individual, layer2-bonded +- `operating_system` (String) The operating system running on the device +- `plan` (String) The hardware config of the device +- `ports` (List of Object) Ports assigned to the device (see [below for nested schema](#nestedatt--ports)) +- `root_password` (String, Sensitive) Root password to the server (if still available) +- `sos_hostname` (String) The hostname to use for [Serial over SSH](https://deploy.equinix.com/developers/docs/metal/resilience-recovery/serial-over-ssh/) access to the device +- `ssh_key_ids` (List of String) List of IDs of SSH keys deployed in the device, can be both user or project SSH keys +- `state` (String) The state of the device +- `storage` (String) +- `tags` (List of String) Tags attached to the device + + +### Nested Schema for `network` + +Read-Only: + +- `address` (String) +- `cidr` (Number) +- `family` (Number) +- `gateway` (String) +- `public` (Boolean) + + + +### Nested Schema for `ports` + +Read-Only: + +- `bonded` (Boolean) +- `id` (String) +- `mac` (String) +- `name` (String) +- `type` (String) diff --git a/docs/index.md b/docs/index.md index 071bcccbe..fad52e4f9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,5 @@ --- -page_title: "Provider: Equinix" +page_title: "Equinix Provider" --- # Equinix Provider @@ -70,22 +70,19 @@ provider "equinix" { The Equinix provider requires a few basic parameters. While the authentication arguments are individually optionally, either `token` or `client_id` and `client_secret` must be defined through arguments or environment settings to interact with Equinix Fabric and Network Edge services, and `auth_token` to interact with Equinix Metal. -* `client_id` - (Optional) API Consumer Key available under "My Apps" in developer portal. This argument can also be specified with the `EQUINIX_API_CLIENTID` shell environment variable. - -* `client_secret` (Optional) API Consumer secret available under "My Apps" in developer portal. This argument can also be specified with the `EQUINIX_API_CLIENTSECRET` shell environment variable. - -* `token` (Optional) API tokens are generated from API Consumer clients using the [OAuth2 API](https://developer.equinix.com/dev-docs/fabric/getting-started/getting-access-token#request-access-and-refresh-tokens). This argument can also be specified with the `EQUINIX_API_TOKEN` shell environment variable. - -* `auth_token` - (Optional) This is your Equinix Metal API Auth token. This can also be specified with the `METAL_AUTH_TOKEN` environment variable. - -* `endpoint` (Optional) The Equinix API base URL to point out desired environment. This argument can also be specified with the `EQUINIX_API_ENDPOINT` shell environment variable. (Defaults to `https://api.equinix.com`) - -* `request_timeout` (Optional) The duration of time, in seconds, that the Equinix Platform API Client should wait before canceling an API request. Canceled requests may still result in provisioned resources. (Defaults to `30`) - -* `response_max_page_size` (Optional) The maximum number of records in a single response for REST queries that produce paginated responses. (Default is client specific) +These parameters can be provided in [Terraform variable files](https://www.terraform.io/docs/configuration/variables.html#variable-definitions-tfvars-files) or as environment variables. Nevertheless, please note that it is [not recommended to keep sensitive data in plain text files](https://www.terraform.io/docs/state/sensitive-data.html). -* `max_retries` (Optional) Maximum number of retries in case of network failure. + +## Schema -* `max_retry_wait_seconds` (Optional) Maximum time to wait in case of network failure. +### Optional -These parameters can be provided in [Terraform variable files](https://www.terraform.io/docs/configuration/variables.html#variable-definitions-tfvars-files) or as environment variables. Nevertheless, please note that it is [not recommended to keep sensitive data in plain text files](https://www.terraform.io/docs/state/sensitive-data.html). +- `auth_token` (String) The Equinix Metal API auth key for API operations +- `client_id` (String) API Consumer Key available under "My Apps" in developer portal. This argument can also be specified with the `EQUINIX_API_CLIENTID` shell environment variable. +- `client_secret` (String) API Consumer secret available under "My Apps" in developer portal. This argument can also be specified with the `EQUINIX_API_CLIENTSECRET` shell environment variable. +- `endpoint` (String) The Equinix API base URL to point out desired environment. This argument can also be specified with the `EQUINIX_API_ENDPOINT` shell environment variable. (Defaults to `https://api.equinix.com`) +- `max_retries` (Number) Maximum number of retries in case of network failure. +- `max_retry_wait_seconds` (Number) Maximum number of seconds to wait before retrying a request. +- `request_timeout` (Number) The duration of time, in seconds, that the Equinix Platform API Client should wait before canceling an API request. Canceled requests may still result in provisioned resources. (Defaults to `30`) +- `response_max_page_size` (Number) The maximum number of records in a single response for REST queries that produce paginated responses. (Default is client specific) +- `token` (String) API tokens are generated from API Consumer clients using the [OAuth2 API](https://developer.equinix.com/dev-docs/fabric/getting-started/getting-access-token#request-access-and-refresh-tokens). This argument can also be specified with the `EQUINIX_API_TOKEN` shell environment variable. diff --git a/docs/resources/metal_device.md b/docs/resources/metal_device.md index 67f1540e5..b814c7426 100644 --- a/docs/resources/metal_device.md +++ b/docs/resources/metal_device.md @@ -149,129 +149,118 @@ resource "equinix_metal_device" "pxe1" { } ``` -## Argument Reference - -The following arguments are supported: - -* `always_pxe` - (Optional) If true, a device with OS `custom_ipxe` will continue to boot via iPXE on reboots. -* `behavior` - (Optional) Behavioral overrides that change how the resource handles certain attribute updates. See [Behavior](#behavior) below for more details. -* `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` - (**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`. 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 device deployed, or `next-available` if you want to pick your next available reservation automatically. Changing this from a reservation UUID to `next-available` will re-create the device in another reservation. Please be careful when using hardware reservation UUID and `next-available` together for the same pool of reservations. It might happen that the reservation which Equinix Metal API will pick as `next-available` is the reservation which you refer with UUID in another equinix_metal_device resource. If that happens, and the equinix_metal_device with the UUID is created later, resource creation will fail because the reservation is already in use (by the resource created with `next-available`). To workaround this, have the `next-available` resource [explicitly depend_on](https://learn.hashicorp.com/terraform/getting-started/dependencies.html#implicit-and-explicit-dependencies) the resource with hardware reservation UUID, so that the latter is created first. For more details, see [issue #176](https://github.com/packethost/terraform-provider-packet/issues/176). -* `hostname` - (Optional) The device hostname used in deployments taking advantage of Layer3 DHCP or metadata service configuration. -* `ip_address` - (Optional) A list of IP address types for the device. See [IP address](#ip-address) below for more details. -* `ipxe_script_url` - (Optional) URL pointing to a hosted iPXE script. More information is in the [Custom iPXE](https://metal.equinix.com/developers/docs/servers/custom-ipxe/) doc. -* `metro` - (Optional) Metro area for the new device. Conflicts with `facilities`. -* `operating_system` - (Required) The operating system slug. To find the slug, or visit [Operating Systems API docs](https://metal.equinix.com/developers/api/operatingsystems), set your API auth token in the top of the page and see JSON from the API response. -* `plan` - (Required) The device plan slug. To find the plan slug, visit the [bare-metal server](https://deploy.equinix.com/product/bare-metal/servers/) and [plan documentation](https://deploy.equinix.com/developers/docs/metal/hardware/standard-servers/). -* `project_id` - (Required) The ID of the project in which to create the device -* `project_ssh_key_ids` - (Optional) Array of IDs of the project SSH keys which should be added to the device. If you specify this array, only the listed project SSH keys (and any SSH keys for the users specified in user_ssh_key_ids) will be added. If no SSH keys are specified (both user_ssh_keys_ids and project_ssh_key_ids are empty lists or omitted), all parent project keys, parent project members keys and organization members keys will be included. Project SSH keys can be created with the [equinix_metal_project_ssh_key](equinix_metal_project_ssh_key.md) resource. -* `user_ssh_key_ids` - (Optional) Array of IDs of the users whose SSH keys should be added to the device. If you specify this array, only the listed users' SSH keys (and any project SSH keys specified in project_ssh_key_ids) will be added. If no SSH keys are specified (both user_ssh_keys_ids and project_ssh_key_ids are empty lists or omitted), all parent project keys, parent project members keys and organization members keys will be included. User SSH keys can be created with the [equinix_metal_ssh_key](equinix_metal_ssh_key.md) resource. -* `reinstall` - (Optional) Whether the device should be reinstalled instead of destroyed when modifying user_data, custom_data, or operating system. See [Reinstall](#reinstall) below for more details. -* `storage` - (Optional) JSON for custom partitioning. Only usable on reserved hardware. More information in in the [Custom Partitioning and RAID](https://metal.equinix.com/developers/docs/servers/custom-partitioning-raid/) doc. Please note that the disks.partitions.size attribute must be a string, not an integer. It can be a number string, or size notation string, e.g. "4G" or "8M" (for gigabytes and megabytes). -* `tags` - (Optional) Tags attached to the device. -* `termination_time` - (Optional) Timestamp for device termination. For example `2021-09-03T16:32:00+03:00`. If you don't supply timezone info, timestamp is assumed to be in UTC. -* `user_data` - (Optional) A string of the desired User 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 `"user_data"`, the device will be updated in-place instead of recreated. -* `wait_for_reservation_deprovision` - (Optional) Only used for devices in reserved hardware. If set, the deletion of this device will block until the hardware reservation is marked provisionable (about 4 minutes in August 2019). + +## Schema -### Behavior +### Required -The `behavior` block has below fields: +- `operating_system` (String) The operating system slug. To find the slug, or visit [Operating Systems API docs](https://metal.equinix.com/developers/api/operatingsystems), set your API auth token in the top of the page and see JSON from the API response. By default, changing this attribute will cause your device to be deleted and recreated. If `reinstall` is enabled, the device will be updated in-place instead of recreated. +- `plan` (String) The device plan slug. To find the plan slug, visit the [bare-metal server](https://deploy.equinix.com/product/bare-metal/servers/) and [plan documentation](https://deploy.equinix.com/developers/docs/metal/hardware/standard-servers/) +- `project_id` (String) The ID of the project in which to create the device -* `allow_changes` - (Optional) List of attributes that are allowed to change without recreating the instance. Supported attributes: `custom_data`, `user_data`" +### Optional -### IP address +- `always_pxe` (Boolean) If true, a device with OS custom_ipxe will +- `behavior` (Block List, Max: 1) (see [below for nested schema](#nestedblock--behavior)) +- `billing_cycle` (String) monthly or hourly +- `custom_data` (String, Sensitive) 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` (String) Description string for the device +- `facilities` (List of String, 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 +- `force_detach_volumes` (Boolean) Delete device even if it has volumes attached. Only applies for destroy action +- `hardware_reservation_id` (String) The UUID of the hardware reservation where you want this device deployed, or next-available if you want to pick your next available reservation automatically +- `hostname` (String) The device hostname used in deployments taking advantage of Layer3 DHCP or metadata service configuration. +- `ip_address` (Block List) A list of IP address types for the device (structure is documented below) (see [below for nested schema](#nestedblock--ip_address)) +- `ipxe_script_url` (String) URL pointing to a hosted iPXE script. More +- `locked` (Boolean) Whether the device is locked or unlocked. Locking a device prevents you from deleting or reinstalling the device or performing a firmware update on the device, and it prevents an instance with a termination time set from being reclaimed, even if the termination time was reached +- `metro` (String) Metro area for the new device. Conflicts with facilities +- `project_ssh_key_ids` (List of String) Array of IDs of the project SSH keys which should be added to the device. If you specify this array, only the listed project SSH keys (and any SSH keys for the users specified in user_ssh_key_ids) will be added. If no SSH keys are specified (both user_ssh_keys_ids and project_ssh_key_ids are empty lists or omitted), all parent project keys, parent project members keys and organization members keys will be included. Project SSH keys can be created with the [equinix_metal_project_ssh_key](equinix_metal_project_ssh_key.md) resource +- `reinstall` (Block List, Max: 1) (see [below for nested schema](#nestedblock--reinstall)) +- `storage` (String) JSON for custom partitioning. Only usable on reserved hardware. More information in in the [Custom Partitioning and RAID](https://metal.equinix.com/developers/docs/servers/custom-partitioning-raid/) doc +- `tags` (List of String) Tags attached to the device +- `termination_time` (String) Timestamp for device termination. For example "2021-09-03T16:32:00+03:00". If you don't supply timezone info, timestamp is assumed to be in UTC. +- `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts)) +- `user_data` (String, Sensitive) A string of the desired User 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 `"user_data"`, the device will be updated in-place instead of recreated. +- `user_ssh_key_ids` (List of String) Array of IDs of the users whose SSH keys should be added to the device. If you specify this array, only the listed users' SSH keys (and any project SSH keys specified in project_ssh_key_ids) will be added. If no SSH keys are specified (both user_ssh_keys_ids and project_ssh_key_ids are empty lists or omitted), all parent project keys, parent project members keys and organization members keys will be included. User SSH keys can be created with the [equinix_metal_ssh_key](equinix_metal_ssh_key.md) resource +- `wait_for_reservation_deprovision` (Boolean) Only used for devices in reserved hardware. If set, the deletion of this device will block until the hardware reservation is marked provisionable (about 4 minutes in August 2019) -The `ip_address` block has below fields: +### Read-Only -* `type` - (Required) One of `private_ipv4`, `public_ipv4`, `public_ipv6`. -* `cidr` - (Optional) CIDR suffix for IP address block to be assigned, i.e. amount of addresses. -* `reservation_ids` - (Optional) List of UUIDs of [IP block reservations](metal_reserved_ip_block.md) from which the public IPv4 address should be taken. +- `access_private_ipv4` (String) The ipv4 private IP assigned to the device +- `access_public_ipv4` (String) The ipv4 maintenance IP assigned to the device +- `access_public_ipv6` (String) The ipv6 maintenance IP assigned to the device +- `created` (String) The timestamp for when the device was created +- `deployed_facility` (String, Deprecated) The facility where the device is deployed +- `deployed_hardware_reservation_id` (String) ID of hardware reservation where this device was deployed. It is useful when using the next-available hardware reservation +- `id` (String) The ID of this resource. +- `network` (List of Object) The device's private and public IP (v4 and v6) network details. When a device is run without any special network configuration, it will have 3 addresses: public ipv4, private ipv4 and ipv6 (see [below for nested schema](#nestedatt--network)) +- `network_type` (String, Deprecated) Network type of a device, used in [Layer 2 networking](https://metal.equinix.com/developers/docs/networking/layer2/). Will be one of layer3, hybrid, hybrid-bonded, layer2-individual, layer2-bonded +- `ports` (List of Object) Ports assigned to the device (see [below for nested schema](#nestedatt--ports)) +- `root_password` (String, Sensitive) Root password to the server (disabled after 24 hours) +- `sos_hostname` (String) The hostname to use for [Serial over SSH](https://deploy.equinix.com/developers/docs/metal/resilience-recovery/serial-over-ssh/) access to the device +- `ssh_key_ids` (List of String) List of IDs of SSH keys deployed in the device, can be both user and project SSH keys +- `state` (String) The status of the device +- `updated` (String) The timestamp for the last time the device was updated -You can supply one `ip_address` block per IP address type. If you use the `ip_address` you must always pass a block for `private_ipv4`. + +### Nested Schema for `behavior` -To learn more about using the reserved IP addresses for new devices, see the examples in the [equinix_metal_reserved_ip_block](metal_reserved_ip_block.md) documentation. +Optional: -### Reinstall +- `allow_changes` (List of String) List of attributes that are allowed to change without recreating the instance. Supported attributes: `custom_data`, `user_data` -The `reinstall` block has below fields: -* `enabled` - (Optional) Whether the provider should favour reinstall over destroy and create. Defaults to `false`. -* `preserve_data` - (Optional) Whether the non-OS disks should be kept or wiped during reinstall. Defaults to `false`. -* `deprovision_fast` - (Optional) Whether the OS disk should be filled with `00h` bytes before reinstall. Defaults to `false`. + +### Nested Schema for `ip_address` -### Timeouts +Required: -The `timeouts` block allows you to specify [timeouts](https://www.terraform.io/configuration/resources#operation-timeouts) for certain actions: +- `type` (String) one of public_ipv4,private_ipv4,public_ipv6 -* `create` - (Defaults to 20 mins) Used when creating the Device. This includes the time to provision the OS. -* `update` - (Defaults to 20 mins) Used when updating the Device. This includes the time needed to reprovision instances when `reinstall` arguments are used. -* `delete` - (Defaults to 20 mins) Used when deleting the Device. This includes the time to deprovision a hardware reservation when `wait_for_reservation_deprovision` is enabled. +Optional: -## Attributes Reference +- `cidr` (Number) CIDR suffix for IP block assigned to this device +- `reservation_ids` (List of String) IDs of reservations to pick the blocks from -In addition to all arguments above, the following attributes are exported: -* `access_private_ipv4` - The ipv4 private IP assigned to the device. -* `access_public_ipv4` - The ipv4 maintenance IP assigned to the device. -* `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` - (**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. -* `hostname` - The hostname of the device. -* `id` - The ID of the device. -* `locked` - Whether the device is locked or unlocked. Locking a device prevents you from deleting or reinstalling the device or performing a firmware update on the device, and it prevents an instance with a termination time set from being reclaimed, even if the termination time was reached -* `metro` - The metro area where the device is deployed. -* `network` - The device's private and public IP (v4 and v6) network details. See [Network Attribute](#network-attribute) below for more details. -* `network_type` - (Deprecated) Network type of a device, used in [Layer 2 networking](https://metal.equinix.com/developers/docs/networking/layer2/). Since this attribute is deprecated you should handle Network Type with one of [equinix_metal_port](equinix_metal_port.md), [equinix_metal_device_network_type](equinix_metal_device_network_type.md) resources or [equinix_metal_port](../data-sources/equinix_metal_port.md) datasource. See [network_types guide](../guides/network_types.md) for more info. -* `operating_system` - The operating system running on the device. -* `plan` - The hardware config of the device. -* `ports` - List of ports assigned to the device. See [Ports Attribute](#ports-attribute) below for more details. -* `project_id` - The ID of the project the device belongs to. -* `root_password` - Root password to the server (disabled after 24 hours). -* `sos_hostname` - The hostname to use for [Serial over SSH](https://deploy.equinix.com/developers/docs/metal/resilience-recovery/serial-over-ssh/) access to the device -* `ssh_key_ids` - List of IDs of SSH keys deployed in the device, can be both user and project SSH keys. -* `state` - The status of the device. -* `tags` - Tags attached to the device. -* `updated` - The timestamp for the last time the device was updated. + +### Nested Schema for `reinstall` -### Network Attribute +Optional: -When a device is run without any special network, it will have 3 networks: +- `deprovision_fast` (Boolean) Whether the OS disk should be filled with `00h` bytes before reinstall +- `enabled` (Boolean) Whether the device should be reinstalled instead of destroyed +- `preserve_data` (Boolean) Whether the non-OS disks should be kept or wiped during reinstall -* Public IPv4 at `equinix_metal_device.name.network.0`. -* IPv6 at `equinix_metal_device.name.network.1`. -* Private IPv4 at `equinix_metal_device.name.network.2`. --> **NOTE:** Elastic addresses stack by type. An assigned public IPv4 will go after the management public IPv4 (to index 1), and will then shift the indices of the IPv6 and private IPv4. Assigned private IPv4 will go after the management private IPv4 (to the end of the network list). + +### Nested Schema for `timeouts` -Each element in the `network` list exports: +Optional: -* `address` - IPv4 or IPv6 address string. -* `cidr` - Bit length of the network mask of the address. -* `gateway` - Address of router. -* `public` - Whether the address is routable from the Internet. -* `family` - IP version. One of `4`, `6`. +- `create` (String) +- `delete` (String) +- `update` (String) -### Ports Attribute -Each element in the `ports` list exports: + +### Nested Schema for `network` -* `name` - Name of the port (e.g. `eth0`, or `bond0`). -* `id` - ID of the port. -* `type` - Type of the port (e.g. `NetworkPort` or `NetworkBondPort`). -* `mac` - MAC address assigned to the port. -* `bonded` - Whether this port is part of a bond in bonded network setup. +Read-Only: -## Import +- `address` (String) +- `cidr` (Number) +- `family` (Number) +- `gateway` (String) +- `public` (Boolean) -This resource can be imported using an existing device ID: -```sh -terraform import equinix_metal_device {existing_device_id} -``` + +### Nested Schema for `ports` + +Read-Only: + +- `bonded` (Boolean) +- `id` (String) +- `mac` (String) +- `name` (String) +- `type` (String) diff --git a/equinix/data_source_metal_device.go b/equinix/data_source_metal_device.go index 3dd90f745..d9d14d357 100644 --- a/equinix/data_source_metal_device.go +++ b/equinix/data_source_metal_device.go @@ -19,6 +19,11 @@ import ( func dataSourceMetalDevice() *schema.Resource { return &schema.Resource{ + Description: `The datasource can be used to fetch a single device. + +If you need to fetch a list of devices which meet filter criteria, you can use the [equinix_metal_devices](equinix_metal_devices.md) datasource. + +~> **Note:** All arguments including the ` + "`root_password` and `user_data`" + ` will be stored in the raw state as plain-text. [Read more about sensitive data in state](https://developer.hashicorp.com/terraform/language/state/sensitive-data).`, ReadWithoutTimeout: dataSourceMetalDeviceRead, Schema: map[string]*schema.Schema{ "hostname": { diff --git a/equinix/provider.go b/equinix/provider.go index 7ab01fe65..7fbb03d74 100644 --- a/equinix/provider.go +++ b/equinix/provider.go @@ -25,25 +25,25 @@ func Provider() *schema.Provider { Optional: true, DefaultFunc: schema.EnvDefaultFunc(config.EndpointEnvVar, config.DefaultBaseURL), ValidateFunc: validation.IsURLWithHTTPorHTTPS, - Description: fmt.Sprintf("The Equinix API base URL to point out desired environment. Defaults to %s", config.DefaultBaseURL), + Description: fmt.Sprintf("The Equinix API base URL to point out desired environment. This argument can also be specified with the `EQUINIX_API_ENDPOINT` shell environment variable. (Defaults to `%s`)", config.DefaultBaseURL), }, "client_id": { Type: schema.TypeString, Optional: true, DefaultFunc: schema.EnvDefaultFunc(config.ClientIDEnvVar, ""), - Description: "API Consumer Key available under My Apps section in developer portal", + Description: "API Consumer Key available under \"My Apps\" in developer portal. This argument can also be specified with the `EQUINIX_API_CLIENTID` shell environment variable.", }, "client_secret": { Type: schema.TypeString, Optional: true, DefaultFunc: schema.EnvDefaultFunc(config.ClientSecretEnvVar, ""), - Description: "API Consumer secret available under My Apps section in developer portal", + Description: "API Consumer secret available under \"My Apps\" in developer portal. This argument can also be specified with the `EQUINIX_API_CLIENTSECRET` shell environment variable.", }, "token": { Type: schema.TypeString, Optional: true, DefaultFunc: schema.EnvDefaultFunc(config.ClientTokenEnvVar, ""), - Description: "API token from the developer sandbox", + Description: "API tokens are generated from API Consumer clients using the [OAuth2 API](https://developer.equinix.com/dev-docs/fabric/getting-started/getting-access-token#request-access-and-refresh-tokens). This argument can also be specified with the `EQUINIX_API_TOKEN` shell environment variable.", }, "auth_token": { Type: schema.TypeString, @@ -56,19 +56,19 @@ func Provider() *schema.Provider { Optional: true, DefaultFunc: schema.EnvDefaultFunc(config.ClientTimeoutEnvVar, config.DefaultTimeout), ValidateFunc: validation.IntAtLeast(1), - Description: fmt.Sprintf("The duration of time, in seconds, that the Equinix Platform API Client should wait before canceling an API request. Defaults to %d", config.DefaultTimeout), + Description: fmt.Sprintf("The duration of time, in seconds, that the Equinix Platform API Client should wait before canceling an API request. Canceled requests may still result in provisioned resources. (Defaults to `%d`)", config.DefaultTimeout), }, "response_max_page_size": { Type: schema.TypeInt, Optional: true, ValidateFunc: validation.IntAtLeast(100), - Description: "The maximum number of records in a single response for REST queries that produce paginated responses", + Description: "The maximum number of records in a single response for REST queries that produce paginated responses. (Default is client specific)", }, "max_retries": { Type: schema.TypeInt, Optional: true, Default: 10, - Description: "Maximum number of retries.", + Description: "Maximum number of retries in case of network failure.", }, "max_retry_wait_seconds": { Type: schema.TypeInt, diff --git a/equinix/resource_metal_device.go b/equinix/resource_metal_device.go index 240fe8bef..a83b30fdd 100644 --- a/equinix/resource_metal_device.go +++ b/equinix/resource_metal_device.go @@ -42,6 +42,9 @@ var ( func resourceMetalDevice() *schema.Resource { return &schema.Resource{ + Description: `Provides an Equinix Metal device resource. This can be used to create, modify, and delete devices. + +~> **NOTE:** All arguments including the ` + "`root_password` and `user_data`" + ` will be stored in the raw state as plain-text. [Read more about sensitive data in state](https://developer.hashicorp.com/terraform/language/state/sensitive-data).`, Timeouts: &schema.ResourceTimeout{ Create: schema.DefaultTimeout(30 * time.Minute), Update: schema.DefaultTimeout(30 * time.Minute), diff --git a/internal/provider/provider.go b/internal/provider/provider.go index a9e8d4f86..4e0d18653 100644 --- a/internal/provider/provider.go +++ b/internal/provider/provider.go @@ -51,22 +51,22 @@ func (p *FrameworkProvider) Schema( Attributes: map[string]schema.Attribute{ "endpoint": schema.StringAttribute{ Optional: true, - Description: "The Equinix API base URL to point out desired environment. Defaults to " + config.DefaultBaseURL, + Description: fmt.Sprintf("The Equinix API base URL to point out desired environment. This argument can also be specified with the `EQUINIX_API_ENDPOINT` shell environment variable. (Defaults to `%s`)", config.DefaultBaseURL), Validators: []validator.String{ equinix_validation.URLWithScheme("http", "https"), }, }, "client_id": schema.StringAttribute{ Optional: true, - Description: "API Consumer Key available under My Apps section in developer portal", + Description: "API Consumer Key available under \"My Apps\" in developer portal. This argument can also be specified with the `EQUINIX_API_CLIENTID` shell environment variable.", }, "client_secret": schema.StringAttribute{ Optional: true, - Description: "API Consumer secret available under My Apps section in developer portal", + Description: "API Consumer secret available under \"My Apps\" in developer portal. This argument can also be specified with the `EQUINIX_API_CLIENTSECRET` shell environment variable.", }, "token": schema.StringAttribute{ Optional: true, - Description: "API token from the developer sandbox", + Description: "API tokens are generated from API Consumer clients using the [OAuth2 API](https://developer.equinix.com/dev-docs/fabric/getting-started/getting-access-token#request-access-and-refresh-tokens). This argument can also be specified with the `EQUINIX_API_TOKEN` shell environment variable.", }, "auth_token": schema.StringAttribute{ Optional: true, @@ -74,21 +74,21 @@ func (p *FrameworkProvider) Schema( }, "request_timeout": schema.Int64Attribute{ Optional: true, - Description: fmt.Sprintf("The duration of time, in seconds, that the Equinix Platform API Client should wait before canceling an API request. Defaults to %d", config.DefaultTimeout), + Description: fmt.Sprintf("The duration of time, in seconds, that the Equinix Platform API Client should wait before canceling an API request. Canceled requests may still result in provisioned resources. (Defaults to `%d`)", config.DefaultTimeout), Validators: []validator.Int64{ int64validator.AtLeast(1), }, }, "response_max_page_size": schema.Int64Attribute{ Optional: true, - Description: "The maximum number of records in a single response for REST queries that produce paginated responses", + Description: "The maximum number of records in a single response for REST queries that produce paginated responses. (Default is client specific)", Validators: []validator.Int64{ int64validator.AtLeast(100), }, }, "max_retries": schema.Int64Attribute{ Optional: true, - Description: "Maximum number of retries.", + Description: "Maximum number of retries in case of network failure.", }, "max_retry_wait_seconds": schema.Int64Attribute{ Optional: true, diff --git a/main.go b/main.go index 7dcbf01a0..b9828711f 100644 --- a/main.go +++ b/main.go @@ -15,7 +15,7 @@ import ( "github.com/hashicorp/terraform-plugin-mux/tf5muxserver" ) -//go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs +//go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs --rendered-provider-name=Equinix func main() { ctx := context.Background() diff --git a/templates/data-sources.md.tmpl b/templates/data-sources.md.tmpl index 0923c64ed..673398b5d 100644 --- a/templates/data-sources.md.tmpl +++ b/templates/data-sources.md.tmpl @@ -17,11 +17,3 @@ subcategory: "{{ title (index (split .Name "_") 1) }}" {{- end }} {{ .SchemaMarkdown | trimspace }} -{{- if .HasImport }} - -## Import - -Import is supported using the following syntax: - -{{codefile "shell" .ImportFile }} -{{- end }} diff --git a/templates/data-sources/metal_device.md.tmpl b/templates/data-sources/metal_device.md.tmpl index 406060d26..7511eea41 100644 --- a/templates/data-sources/metal_device.md.tmpl +++ b/templates/data-sources/metal_device.md.tmpl @@ -2,17 +2,9 @@ subcategory: "Metal" --- -{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates. +# {{.Name}} ({{.Type}}) -For example, the {{ .SchemaMarkdown }} template can be used to replace manual schema documentation if descriptions of schema attributes are added in the provider source code. */ -}} - -# equinix_metal_device (Data Source) - -The datasource can be used to fetch a single device. - -If you need to fetch a list of devices which meet filter criteria, you can use the [equinix_metal_devices](equinix_metal_devices.md) datasource. - -~> **Note:** All arguments including the `root_password` and `user_data` will be stored in the raw state as plain-text. [Read more about sensitive data in state](https://developer.hashicorp.com/terraform/language/state/sensitive-data). +{{ .Description | trimspace }} ## Example Usage @@ -20,64 +12,4 @@ If you need to fetch a list of devices which meet filter criteria, you can use t {{tffile "examples/data-sources/metal_device/example_2.tf"}} -## Argument Reference - -The following arguments are supported: - -* `hostname` - (Optional) The device name. -* `project_id` - (Optional) The id of the project in which the devices exists. -* `device_id` - (Optional) Device ID. - --> **NOTE:** You should pass either `device_id`, or both `project_id` and `hostname`. - -## Attributes Reference - -In addition to all arguments above, the following attributes are exported: - -* `access_private_ipv4` - The ipv4 private IP assigned to the device. -* `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` - (**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. -* `metro` - The metro where the device is deployed -* `network` - The device's private and public IP (v4 and v6) network details. See [Network Attribute](#network-attribute) below for more details. -* `network_type` - L2 network type of the device, one of `layer3`, `layer2-bonded`, `layer2-individual`, `hybrid`. -* `operating_system` - The operating system running on the device. -* `plan` - The hardware config of the device. -* `ports` - List of ports assigned to the device. See [Ports Attribute](#ports-attribute) below for more details. -* `root_password` - Root password to the server (if still available). -* `sos_hostname` - The hostname to use for [Serial over SSH](https://deploy.equinix.com/developers/docs/metal/resilience-recovery/serial-over-ssh/) access to the device -* `ssh_key_ids` - List of IDs of SSH keys deployed in the device, can be both user or project SSH keys. -* `state` - The state of the device. -* `tags` - Tags attached to the device. - -### Network Attribute - -When a device is run without any special network, it will have 3 networks: - -* Public IPv4 at `equinix_metal_device.name.network.0`. -* IPv6 at `equinix_metal_device.name.network.1`. -* Private IPv4 at `equinix_metal_device.name.network.2`. - --> **NOTE:** Elastic addresses stack by type. An assigned public IPv4 will go after the management public IPv4 (to index 1), and will then shift the indices of the IPv6 and private IPv4. Assigned private IPv4 will go after the management private IPv4 (to the end of the network list). - -Each element in the `network` list exports: - -* `address` - IPv4 or IPv6 address string. -* `cidr` - Bit length of the network mask of the address. -* `gateway` - Address of router. -* `public` - Whether the address is routable from the Internet. -* `family` - IP version. One of `4`, `6`. - -### Ports Attribute - -Each element in the `ports` list exports: - -* `name` - Name of the port (e.g. `eth0`, or `bond0`). -* `id` - ID of the port. -* `type` - Type of the port (e.g. `NetworkPort` or `NetworkBondPort`). -* `mac` - MAC address assigned to the port. -* `bonded` - Whether this port is part of a bond in bonded network setup. +{{ .SchemaMarkdown | trimspace }} diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl index 9d4ac26b6..b7468c9c3 100644 --- a/templates/index.md.tmpl +++ b/templates/index.md.tmpl @@ -1,12 +1,8 @@ --- -page_title: "Provider: Equinix" +page_title: "{{.RenderedProviderName}} Provider" --- -{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates. - -For example, the {{ .SchemaMarkdown }} template can be used to replace manual schema documentation if descriptions of schema attributes are added in the provider source code. */ -}} - -# Equinix Provider +# {{.RenderedProviderName}} Provider The Equinix provider is used to interact with the resources provided by Equinix Platform. The provider needs to be configured with the proper credentials before it can be used. @@ -50,22 +46,6 @@ When testing against the [Equinix Sandbox API](https://developer.equinix.com/env The Equinix provider requires a few basic parameters. While the authentication arguments are individually optionally, either `token` or `client_id` and `client_secret` must be defined through arguments or environment settings to interact with Equinix Fabric and Network Edge services, and `auth_token` to interact with Equinix Metal. -* `client_id` - (Optional) API Consumer Key available under "My Apps" in developer portal. This argument can also be specified with the `EQUINIX_API_CLIENTID` shell environment variable. - -* `client_secret` (Optional) API Consumer secret available under "My Apps" in developer portal. This argument can also be specified with the `EQUINIX_API_CLIENTSECRET` shell environment variable. - -* `token` (Optional) API tokens are generated from API Consumer clients using the [OAuth2 API](https://developer.equinix.com/dev-docs/fabric/getting-started/getting-access-token#request-access-and-refresh-tokens). This argument can also be specified with the `EQUINIX_API_TOKEN` shell environment variable. - -* `auth_token` - (Optional) This is your Equinix Metal API Auth token. This can also be specified with the `METAL_AUTH_TOKEN` environment variable. - -* `endpoint` (Optional) The Equinix API base URL to point out desired environment. This argument can also be specified with the `EQUINIX_API_ENDPOINT` shell environment variable. (Defaults to `https://api.equinix.com`) - -* `request_timeout` (Optional) The duration of time, in seconds, that the Equinix Platform API Client should wait before canceling an API request. Canceled requests may still result in provisioned resources. (Defaults to `30`) - -* `response_max_page_size` (Optional) The maximum number of records in a single response for REST queries that produce paginated responses. (Default is client specific) - -* `max_retries` (Optional) Maximum number of retries in case of network failure. - -* `max_retry_wait_seconds` (Optional) Maximum time to wait in case of network failure. - These parameters can be provided in [Terraform variable files](https://www.terraform.io/docs/configuration/variables.html#variable-definitions-tfvars-files) or as environment variables. Nevertheless, please note that it is [not recommended to keep sensitive data in plain text files](https://www.terraform.io/docs/state/sensitive-data.html). + +{{ .SchemaMarkdown | trimspace }} diff --git a/templates/resources.md.tmpl b/templates/resources.md.tmpl new file mode 100644 index 000000000..0923c64ed --- /dev/null +++ b/templates/resources.md.tmpl @@ -0,0 +1,27 @@ +--- +{{ if eq (index (split .Name "_") 1) "network" -}} +subcategory: "Network Edge" +{{- else -}} +subcategory: "{{ title (index (split .Name "_") 1) }}" +{{- end }} +--- + +# {{.Name}} ({{.Type}}) + +{{ .Description | trimspace }} + +{{ if .HasExample -}} +## Example Usage + +{{tffile .ExampleFile }} +{{- end }} + +{{ .SchemaMarkdown | trimspace }} +{{- if .HasImport }} + +## Import + +Import is supported using the following syntax: + +{{codefile "shell" .ImportFile }} +{{- end }} diff --git a/templates/resources/metal_device.md.tmpl b/templates/resources/metal_device.md.tmpl index 5b305767e..32e1ded8b 100644 --- a/templates/resources/metal_device.md.tmpl +++ b/templates/resources/metal_device.md.tmpl @@ -2,15 +2,9 @@ subcategory: "Metal" --- -{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates. +# {{.Name}} ({{.Type}}) -For example, the {{ .SchemaMarkdown }} template can be used to replace manual schema documentation if descriptions of schema attributes are added in the provider source code. */ -}} - -# equinix_metal_device (Resource) - -Provides an Equinix Metal device resource. This can be used to create, modify, and delete devices. - -~> **NOTE:** All arguments including the `root_password` and `user_data` will be stored in the raw state as plain-text. [Read more about sensitive data in state](https://developer.hashicorp.com/terraform/language/state/sensitive-data). +{{ .Description | trimspace }} ## Example Usage @@ -34,129 +28,12 @@ Create a device and allow the `user_data` and `custom_data` attributes to change {{tffile "examples/resources/metal_device/example_5.tf"}} -## Argument Reference - -The following arguments are supported: - -* `always_pxe` - (Optional) If true, a device with OS `custom_ipxe` will continue to boot via iPXE on reboots. -* `behavior` - (Optional) Behavioral overrides that change how the resource handles certain attribute updates. See [Behavior](#behavior) below for more details. -* `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` - (**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`. 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 device deployed, or `next-available` if you want to pick your next available reservation automatically. Changing this from a reservation UUID to `next-available` will re-create the device in another reservation. Please be careful when using hardware reservation UUID and `next-available` together for the same pool of reservations. It might happen that the reservation which Equinix Metal API will pick as `next-available` is the reservation which you refer with UUID in another equinix_metal_device resource. If that happens, and the equinix_metal_device with the UUID is created later, resource creation will fail because the reservation is already in use (by the resource created with `next-available`). To workaround this, have the `next-available` resource [explicitly depend_on](https://learn.hashicorp.com/terraform/getting-started/dependencies.html#implicit-and-explicit-dependencies) the resource with hardware reservation UUID, so that the latter is created first. For more details, see [issue #176](https://github.com/packethost/terraform-provider-packet/issues/176). -* `hostname` - (Optional) The device hostname used in deployments taking advantage of Layer3 DHCP or metadata service configuration. -* `ip_address` - (Optional) A list of IP address types for the device. See [IP address](#ip-address) below for more details. -* `ipxe_script_url` - (Optional) URL pointing to a hosted iPXE script. More information is in the [Custom iPXE](https://metal.equinix.com/developers/docs/servers/custom-ipxe/) doc. -* `metro` - (Optional) Metro area for the new device. Conflicts with `facilities`. -* `operating_system` - (Required) The operating system slug. To find the slug, or visit [Operating Systems API docs](https://metal.equinix.com/developers/api/operatingsystems), set your API auth token in the top of the page and see JSON from the API response. -* `plan` - (Required) The device plan slug. To find the plan slug, visit the [bare-metal server](https://deploy.equinix.com/product/bare-metal/servers/) and [plan documentation](https://deploy.equinix.com/developers/docs/metal/hardware/standard-servers/). -* `project_id` - (Required) The ID of the project in which to create the device -* `project_ssh_key_ids` - (Optional) Array of IDs of the project SSH keys which should be added to the device. If you specify this array, only the listed project SSH keys (and any SSH keys for the users specified in user_ssh_key_ids) will be added. If no SSH keys are specified (both user_ssh_keys_ids and project_ssh_key_ids are empty lists or omitted), all parent project keys, parent project members keys and organization members keys will be included. Project SSH keys can be created with the [equinix_metal_project_ssh_key](equinix_metal_project_ssh_key.md) resource. -* `user_ssh_key_ids` - (Optional) Array of IDs of the users whose SSH keys should be added to the device. If you specify this array, only the listed users' SSH keys (and any project SSH keys specified in project_ssh_key_ids) will be added. If no SSH keys are specified (both user_ssh_keys_ids and project_ssh_key_ids are empty lists or omitted), all parent project keys, parent project members keys and organization members keys will be included. User SSH keys can be created with the [equinix_metal_ssh_key](equinix_metal_ssh_key.md) resource. -* `reinstall` - (Optional) Whether the device should be reinstalled instead of destroyed when modifying user_data, custom_data, or operating system. See [Reinstall](#reinstall) below for more details. -* `storage` - (Optional) JSON for custom partitioning. Only usable on reserved hardware. More information in in the [Custom Partitioning and RAID](https://metal.equinix.com/developers/docs/servers/custom-partitioning-raid/) doc. Please note that the disks.partitions.size attribute must be a string, not an integer. It can be a number string, or size notation string, e.g. "4G" or "8M" (for gigabytes and megabytes). -* `tags` - (Optional) Tags attached to the device. -* `termination_time` - (Optional) Timestamp for device termination. For example `2021-09-03T16:32:00+03:00`. If you don't supply timezone info, timestamp is assumed to be in UTC. -* `user_data` - (Optional) A string of the desired User 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 `"user_data"`, the device will be updated in-place instead of recreated. -* `wait_for_reservation_deprovision` - (Optional) Only used for devices in reserved hardware. If set, the deletion of this device will block until the hardware reservation is marked provisionable (about 4 minutes in August 2019). - -### Behavior - -The `behavior` block has below fields: - -* `allow_changes` - (Optional) List of attributes that are allowed to change without recreating the instance. Supported attributes: `custom_data`, `user_data`" - -### IP address - -The `ip_address` block has below fields: - -* `type` - (Required) One of `private_ipv4`, `public_ipv4`, `public_ipv6`. -* `cidr` - (Optional) CIDR suffix for IP address block to be assigned, i.e. amount of addresses. -* `reservation_ids` - (Optional) List of UUIDs of [IP block reservations](metal_reserved_ip_block.md) from which the public IPv4 address should be taken. - -You can supply one `ip_address` block per IP address type. If you use the `ip_address` you must always pass a block for `private_ipv4`. - -To learn more about using the reserved IP addresses for new devices, see the examples in the [equinix_metal_reserved_ip_block](metal_reserved_ip_block.md) documentation. - -### Reinstall - -The `reinstall` block has below fields: - -* `enabled` - (Optional) Whether the provider should favour reinstall over destroy and create. Defaults to `false`. -* `preserve_data` - (Optional) Whether the non-OS disks should be kept or wiped during reinstall. Defaults to `false`. -* `deprovision_fast` - (Optional) Whether the OS disk should be filled with `00h` bytes before reinstall. Defaults to `false`. - -### Timeouts - -The `timeouts` block allows you to specify [timeouts](https://www.terraform.io/configuration/resources#operation-timeouts) for certain actions: - -* `create` - (Defaults to 20 mins) Used when creating the Device. This includes the time to provision the OS. -* `update` - (Defaults to 20 mins) Used when updating the Device. This includes the time needed to reprovision instances when `reinstall` arguments are used. -* `delete` - (Defaults to 20 mins) Used when deleting the Device. This includes the time to deprovision a hardware reservation when `wait_for_reservation_deprovision` is enabled. - -## Attributes Reference - -In addition to all arguments above, the following attributes are exported: - -* `access_private_ipv4` - The ipv4 private IP assigned to the device. -* `access_public_ipv4` - The ipv4 maintenance IP assigned to the device. -* `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` - (**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. -* `hostname` - The hostname of the device. -* `id` - The ID of the device. -* `locked` - Whether the device is locked or unlocked. Locking a device prevents you from deleting or reinstalling the device or performing a firmware update on the device, and it prevents an instance with a termination time set from being reclaimed, even if the termination time was reached -* `metro` - The metro area where the device is deployed. -* `network` - The device's private and public IP (v4 and v6) network details. See [Network Attribute](#network-attribute) below for more details. -* `network_type` - (Deprecated) Network type of a device, used in [Layer 2 networking](https://metal.equinix.com/developers/docs/networking/layer2/). Since this attribute is deprecated you should handle Network Type with one of [equinix_metal_port](equinix_metal_port.md), [equinix_metal_device_network_type](equinix_metal_device_network_type.md) resources or [equinix_metal_port](../data-sources/equinix_metal_port.md) datasource. See [network_types guide](../guides/network_types.md) for more info. -* `operating_system` - The operating system running on the device. -* `plan` - The hardware config of the device. -* `ports` - List of ports assigned to the device. See [Ports Attribute](#ports-attribute) below for more details. -* `project_id` - The ID of the project the device belongs to. -* `root_password` - Root password to the server (disabled after 24 hours). -* `sos_hostname` - The hostname to use for [Serial over SSH](https://deploy.equinix.com/developers/docs/metal/resilience-recovery/serial-over-ssh/) access to the device -* `ssh_key_ids` - List of IDs of SSH keys deployed in the device, can be both user and project SSH keys. -* `state` - The status of the device. -* `tags` - Tags attached to the device. -* `updated` - The timestamp for the last time the device was updated. - -### Network Attribute - -When a device is run without any special network, it will have 3 networks: - -* Public IPv4 at `equinix_metal_device.name.network.0`. -* IPv6 at `equinix_metal_device.name.network.1`. -* Private IPv4 at `equinix_metal_device.name.network.2`. - --> **NOTE:** Elastic addresses stack by type. An assigned public IPv4 will go after the management public IPv4 (to index 1), and will then shift the indices of the IPv6 and private IPv4. Assigned private IPv4 will go after the management private IPv4 (to the end of the network list). - -Each element in the `network` list exports: - -* `address` - IPv4 or IPv6 address string. -* `cidr` - Bit length of the network mask of the address. -* `gateway` - Address of router. -* `public` - Whether the address is routable from the Internet. -* `family` - IP version. One of `4`, `6`. - -### Ports Attribute - -Each element in the `ports` list exports: - -* `name` - Name of the port (e.g. `eth0`, or `bond0`). -* `id` - ID of the port. -* `type` - Type of the port (e.g. `NetworkPort` or `NetworkBondPort`). -* `mac` - MAC address assigned to the port. -* `bonded` - Whether this port is part of a bond in bonded network setup. +{{ .SchemaMarkdown | trimspace }} +{{- if .HasImport }} ## Import -This resource can be imported using an existing device ID: +Import is supported using the following syntax: -```sh -terraform import equinix_metal_device {existing_device_id} -``` +{{codefile "shell" .ImportFile }} +{{- end }}