Skip to main content

~> Deprecation Notice Equinix Metal will reach end of life on June 30, 2026. All Metal resources will be removed in version 5.0.0 of this provider. Use version 4.x of this provider for continued use through sunset. See https://docs.equinix.com/metal/ for more information.

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.

Example Usage​

Create a device and add it to cool_project

resource "equinix_metal_device" "web1" {
  hostname         = "tf.coreos2"
  plan             = "c3.small.x86"
  metro            = "sv"
  operating_system = "ubuntu_24_04"
  billing_cycle    = "hourly"
  project_id       = local.project_id
}

Same as above, but boot via iPXE initially, using the Ignition Provider for provisioning

resource "equinix_metal_device" "pxe1" {
  hostname         = "tf.coreos2-pxe"
  plan             = "c3.small.x86"
  metro            = "sv"
  operating_system = "custom_ipxe"
  billing_cycle    = "hourly"
  project_id       = local.project_id
  ipxe_script_url  = "https://rawgit.com/cloudnativelabs/pxe/master/packet/coreos-stable-metal.ipxe"
  always_pxe       = "false"
  user_data        = data.ignition_config.example.rendered
}

Create a device without a public IP address in metro ny, with only a /30 private IPv4 subnet (4 IP addresses)

resource "equinix_metal_device" "web1" {
  hostname         = "tf.coreos2"
  plan             = "c3.small.x86"
  metro            = "ny"
  operating_system = "ubuntu_24_04"
  billing_cycle    = "hourly"
  project_id       = local.project_id
  ip_address {
    type = "private_ipv4"
    cidr = 30
  }
}

Deploy device on next-available reserved hardware and do custom partitioning.

resource "equinix_metal_device" "web1" {
  hostname                = "tftest"
  plan                    = "c3.small.x86"
  metro                   = "ny"
  operating_system        = "ubuntu_24_04"
  billing_cycle           = "hourly"
  project_id              = local.project_id
  hardware_reservation_id = "next-available"
  storage                 = <<EOS
{
  "disks": [
    {
      "device": "/dev/sda",
      "wipeTable": true,
      "partitions": [
        {
          "label": "BIOS",
          "number": 1,
          "size": "4096"
        },
        {
          "label": "SWAP",
          "number": 2,
          "size": "3993600"
        },
        {
          "label": "ROOT",
          "number": 3,
          "size": "0"
        }
      ]
    }
  ],
  "filesystems": [
    {
      "mount": {
        "device": "/dev/sda3",
        "format": "ext4",
        "point": "/",
        "create": {
          "options": [
            "-L",
            "ROOT"
          ]
        }
      }
    },
    {
      "mount": {
        "device": "/dev/sda2",
        "format": "swap",
        "point": "none",
        "create": {
          "options": [
            "-L",
            "SWAP"
          ]
        }
      }
    }
  ]
}
EOS
}

Create a device and allow the user_data and custom_data attributes to change in-place (i.e., without destroying and recreating the device):

resource "equinix_metal_device" "pxe1" {
  hostname         = "tf.coreos2-pxe"
  plan             = "c3.small.x86"
  metro            = "sv"
  operating_system = "custom_ipxe"
  billing_cycle    = "hourly"
  project_id       = local.project_id
  ipxe_script_url  = "https://rawgit.com/cloudnativelabs/pxe/master/packet/coreos-stable-metal.ipxe"
  always_pxe       = "false"
  user_data        = local.user_data
  custom_data      = local.custom_data

  behavior {
    allow_changes = [
      "custom_data",
      "user_data"
    ]
  }
}

Schema​

Required​

  • operating_system (String) The operating system slug. To find the slug, or visit Operating Systems API docs, 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 plan documentation
  • project_id (String) The ID of the project in which to create the device

Optional​

  • always_pxe (Boolean) If true, a device with OS custom_ipxe will
  • behavior (Block List, Max: 1) (see below for nested schema)
  • 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). 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)
  • 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 resource
  • reinstall (Block List, Max: 1) (see below for nested schema)
  • storage (String) JSON for custom partitioning. Only usable on reserved hardware. More information in in the Custom Partitioning and 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)
  • 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 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)

Read-Only​

  • 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)
  • network_type (String, Deprecated) Network type of a device, used in Layer 2 networking. 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)
  • root_password (String, Sensitive) Root password to the server (disabled after 24 hours)
  • sos_hostname (String) The hostname to use for 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

Nested Schema for behavior​

Optional:

  • allow_changes (List of String) List of attributes that are allowed to change without recreating the instance. Supported attributes: custom_data, user_data

Nested Schema for ip_address​

Required:

  • type (String) one of public_ipv4,private_ipv4,public_ipv6

Optional:

  • cidr (Number) CIDR suffix for IP block assigned to this device
  • reservation_ids (List of String) IDs of reservations to pick the blocks from

Nested Schema for reinstall​

Optional:

  • 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

Nested Schema for timeouts​

Optional:

  • create (String)
  • delete (String)
  • update (String)

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)
Was this page helpful?