Deploying an Equinix Metal Instance Using Terraform

Terraform has become the de facto tool for Infrastructure-as-Code (IaC) needs. This guide will walk you through the steps of using Terraform to deploy a server on Equinix Metal, and serves as a starting point for becoming familiar with the Equinix Metal Terraform Provider.

Prerequisites

To complete this tutorial, you'll need the following:

• An Equinix Metal Account.
• An Equinix Metal Project ID.
• An Equinix Metal API key.
• Terraform installed on your workstation.
• (Optional) An IDE, like VS Code.

Creating an Equinix Account, Organization, and Project

Start by going to the Equinix Metal Console and log in to your existing account or create a new one.

When you create your account, you also create and name an organization, add billing information, and create a project.

If you already have an account, you can find all of your projects by navigating to the top left of the navigation menu and choosing All Projects.

If you need some more help navigating the Equinix Metal console, check out the relevant documentation:

• Organization Managament
• User Account Managment
• Project Managament

Finding and Copying Your Project ID

After creating a project, you'll need to locate and copy the project ID. You can find it by going to the left-hand navigation bar and selecting Project Settings.

You'll be taken to the project's details where you'll see the ID and a button to copy it. Copy and save the ID as you'll need it later.

Creating and copying an API Key

You'll also need to create an API key. Navigate to the upper right-hand corner, click the avatar, and select My Profile.

When your profile page opens, find the tab titled API Keys and click the Add New Key button.

Give your key a name and choose to give it the Read/Write permission.

Once the key is created it will show up in your list of API keys. There will be a copy button on that same line. Copy and save the API key as well.

If you are having trouble creating an API key, check out the API Key Documentation.

If you would like to learn more about the Metal API, check out Equinix Metal API.

Installing Terraform

Terraform is an open-source infrastructure-as-code software tool created by HashiCorp. Users define and provide data center infrastructure using a declarative configuration language known as HashiCorp Configuration Language (HCL).

To install Terraform, check out the official documentaiton.

On a MacOS workstation, you can install Terraform with brew:

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

To test that it's been installed correctly, run:

terraform -help

If you had trouble getting Terraform installed, refer to Terraform's official installation video.

Now you have everything required to begin using Terraform to deploy Equinix Metal servers.

Deploying a Metal server with Terraform

To use Terraform with Equinix Metal, you'll create a new directory with a Terraform file inside that will hold the script with the deployment plan.

From a terminal, make a new directory and navigate into it.

mkdir terraform-example
cd terraform-example

Create a Terraform file using the touch command, name it main.tf

touch main.tf 

Now you should have a directory that looks like this:

❯ terraform-example
.
└── main.tf

Terraform Script

Using the text editor of your choice, find and open main.tf:

Copy and paste this plan configuration inside your file.

terraform {
  required_providers {
    equinix = {
      source  = "equinix/equinix"
      version = "1.13.0"
    }
  }
}

provider "equinix" {
  # Configuration options 
  # Credentials for only Equinix Metal resources 
  auth_token = "API_key"
}

#specs of server and machine  
resource "equinix_metal_device" "web1" {
  hostname = "test"
  plan = "c3.small.x86"
  metro = "da"
  operating_system = "ubuntu_20_04"
  billing_cycle = "hourly"
  project_id = "project_id"
}

resource "equinix_metal_vlan" "vlan1" {
  description = "VLAN in Dallas"
  metro = "da"
  project_id = "project_id"
}

Update API key and Project ID

There are two changes you'll need to make in this file for it to work:

1. Update the auth_token value with your own API key that you created earlier.
2. Update the project_id values for the server and VLAN sections with your own project ID that you created earlier.

The current configuration deploys a c3.small.x86 server named test running Ubuntu 20.04 on an hourly billing cycle located in the Dallas metro. It will also create a VLAN in the Dallas metro, with the description VLAN in Dallas.

You can modify all these configuration options your your purpose. Check out the Equinix Terraform Provider Docs for more information.

For more information about valid input options and attribute references check out the Attribute Reference Page in the Equinix Terraform Provider Docs.

Operating System Tags

You can find all valid operating system options by checking the operating-system slug. The slugs are what you would put inside the quotes for operating_system = "slug". For example, if you wanted CentOS 7, change the value to:

operating_system = "centos_7"

Metro Codes

You can find all valid metro options by checking the metro codes. The values are what you would put inside the quotes for metro = "code". For example, if you want to deploy in Toronto, change the value to:

metro = "tr"

Plan Tags

You will be able to find all valid plan options by checking the plan slugs. The slugs are what you would put inside the quotes for plan = "slug". For example, if you wanted a c3.medium.x86 plan, change the value to:

plan = "c3.medium.x86"

Running Terraform

You're ready to run your Terraform plan. Navigate back to your terminal and make sure you are in the directory you made that has the Terraform file inside.

The first step is to initialize Terraform, which will install the Equinix Metal provider.

terraform init 

Use terraform plan to verify the actions that Terraform will take with the current plan.

terraform plan 

Finally, apply the plan to begin the deployment.

terraform apply 

After running the terraform apply command, you'll be prompted to verify that you want to deploy the server; choose yes. You can see the progress of the deployment in the terminal. You can also go back to the Equinix Metal console to see the server and VLAN being deployed there.

Delete and stop the server

To delete and stop the servers use the terraform destroy command:

terraform destroy  

After entering this command, it will prompt you to type yes to confirm you want to run the plan and delete all devices.

Optionally, you can navigate back to the Metal console, locate each respective server and choose to delete them from the action menu.

Conclusion

This guide covered the setup and steps needed to use Terraform to deploy Equinix Metal servers. Specifically, we covered:

• Creating an Equinix Account, Organization and Project.
• Creating an API Key and finding your project key inside the Metal Portal.
• Creating a Terraform script that can be used to deploy Equinix Metal servers.
• Running the Terraform script you created.