Integrating Terraform with Vercel

Terraform is an infrastructure as code (IaC) driven software that allows you to programmatically configure your project infrastructure using configuration files and version control. This mode of allocation ensures logical management and monitoring of resources such as servers, networks, and cloud storage instead of a manual operation for each required resource.

These infrastructure configurations are handled via a JSON-like configuration language called HCL (HashiCorp Configuration Language). For example, when you deploy a project, run a server, and manage your GitHub org or SAML provider, Terraform parses your code and translates it to an API call to the resource provider.

This guide will teach you how to use the Vercel integration with Terraform.

About the Integration

Using the Terraform Vercel provider, you can integrate Vercel with the other third-party services and handle complex preview environment setups that use Vercel for the front-end and other back-end services.

The Vercel Terraform provider is open-source, and you can access it from the Terraform registry. It allows developers to:

• Create and configure projects
• Create Vercel deployments
• Configure domains to Vercel projects

In addition, the Terraform Provider facilitates using Vercel alongside a range of other third-party services, such as Google Cloud Platform (GCP), Amazon Web Services (AWS), Fastly or Cloudflare.

This integration is helpful for two groups:

• Developers that use Terraform to manage their infrastructure and are looking to use Vercel
• Developers that combine multiple third-party services to power their applications

Set up Terraform

• First, install the Terraform CLI. Follow this guide that explains how to do this for all operating systems
• Then, connect Terraform to your Vercel account with an access token. Follow this guide to create an access token in the Vercel dashboard
• Finally, create a folder for your Terraform Vercel Project and add the access token as a shell environment variable by running the following in the command line:

export VERCEL_API_TOKEN=yourAPITokenValue

Set up Vercel as a provider

Let's start with a basic web project that contains only one file called index.html. First, you need to create a terraform file in your project folder to add Vercel as a provider. This is the same folder where you set the Vercel token environment variable described above.

Create a file called main.tf at the root of your project and paste the following content:

terraform {
  required_providers {
    vercel = {
      source  = "vercel/vercel"
      version = "~> 0.2"
    }
  }
}

Run the following in the command line to initialize the project using main.tf:

terraform init

Create and configure a Project

Now that Vercel is initialized as a provider, you can create a Vercel Project for your project without leaving the command line.

Edit the main.tf file and paste the following content:

resource "vercel_project" "with_git" {
  name = "terraform-test-project"
  git_repository = {
    type = "github"
    repo = "vercel-support/terraform-test"
  }
}

Run the following in the command line to get a confirmation of the changes made to your Terraform configuration file:

terraform plan

Run the following in the command line to apply these changes:

terraform apply

You will be asked for a confirmation prompt where only typing yes will continue the process. This command takes only a few seconds, and you will receive a confirmation once it's complete.

Moreover, the value of the repo to work, it needs to be in an organisation where you have the Vercel Github App installed. If this is not the case, you get a an error message upon running terraform apply:

│ Error: Error creating project
│
│   with vercel_project.with_git,
│   on main.tf line 10, in resource "vercel_project" "with_git":
│   10: resource "vercel_project" "with_git" {
│
│ Could not create project, unexpected error: bad_request - To link a GitHub repository, you need to install the GitHub integration first.

You can now check your Vercel dashboard for the account where you added the integration. You should see a project called terraform-test-project added. If you go inside the project and look under the Git settings, you will find that the Github repository that you added as repo is connected to the Project.

To create the Project inside a team account, specific the team_id as follows in the resource specification. You can find the team_id under the Settings tab of your team account.

resource "vercel_project" "with_git" {
  name = "terraform-test-project"
  team_id = myteamid
  git_repository = {
    type = "github"
    repo = "vercel-support/terraform-test"
  }
}

It is important to specify the team_id every time the resource specification is used.

You can now create a Deployment by simply committing Git changes and pushing them to your Github repository.

Deploy a framework-based Project

So far, you deployed a simple one-page project using the Github integration with a Terraform configuration. Let's now look at a more real-world use case where you need to deploy a Project that uses a framework containing files and folders. You can deploy directly with Terraform without using the Vercel Git integration.

Let's create a new directory for our project and call it test-next-project.

In this directory, run the following in the command line to create a create-next-app Project in a folder called ui:

npx create-next-app ui

Create a project-terraform directory for the Terraform configuration at the root of the test-next-project directory.

mkdir project-terraform
cd project-terraform

Next, add a file called main.tf inside the project-terraform directory and paste the following content:

terraform {
  required_providers {
    vercel = {
      source  = "vercel/vercel"
      version = "~> 0.1"
    }
  }
}

resource "vercel_project" "with_next" {
  name      = "example-project-nxtapp"
  framework = "nextjs"
  root_directory = "ui"
}

Inside the project-terraform directory, run the following in the command line to initialize the project using main.tf and then apply the changes:

terraform init
terraform apply

This project will now show up in your Vercel account.

Since you will deploy the Project using Terraform, you will need a place to contain the Vercel Project files and a separate place to deploy the Project in Terraform, as one Project will have many Deployments. After creating a Project-level configuration, you will make the Deployment level configuration.

Let's go back to the root directory test-next-project and create a new Terraform configuration file.

Again, add a file called main.tf inside the test-next-project directory and copy-paste the following content:

terraform {
  required_providers {
    vercel = {
      source  = "vercel/vercel"
      version = "~> 0.1"
    }
  }
}

data "vercel_project_directory" "example" {
  path = "ui"
}

data "vercel_project" "example" {
  name = "example-project-nxtapp"
}

resource "vercel_deployment" "example" {
  project_id = data.vercel_project.example.id
  files      = data.vercel_project_directory.example.files
  production = true
}

Inside the test-next-project directory, run the following in the command line to initialize the project using main.tf and review the changes that will be made:

terraform init
terraform plan

The plan command will output the files to be uploaded (inside the ui directory) and any additional settings such as production=true.

Run the following in the command line to apply the changes:

terraform apply

You will see the progress of the Deployment creation and build in the command line as the Project is deployed. When the Deployment is ready, the progress output will stop, show that the apply command is complete and return to the command line. If you check your Vercel Project's Deployments page, you will see a new Deployment with a create-next-app output.

View a new Deployment with Terraform Vercel provider.

If you make any changes in your ui directory, go back to the root of the test-next-project directory and run terraform apply, a new Deployment will automatically be created based on those changes.

Configure Vercel Project domains

After configuring your Project to create Deployments, let's look at how you can configure a vercel.app domain or a custom domain with your Vercel Project via Terraform.

Edit your project-terraform/main.tf file and copy-paste the following:

resource "vercel_project_domain" "example" {
  project_id = vercel_project.with_next.id
  domain     = "myproject-domain.vercel.app"
}

Run the following two commands to confirm and then apply the changes:

terraform plan
terraform apply

A successful deployment to Vercel with Terraform.

Additional applications

You can also use Terraform to integrate third-party services like Amazon Web Services (AWS) with your Vercel Project in a way that gives you additional flexibility, such as:

• Being able to set all the configuration of the AWS services you are using inside a Terraform configuration file inside your Project directory
• Being able to pass values generated by an AWS service to a Vercel Deployment via an environment variable.

We will add more tutorials related to this in the future.

That's It!

To learn more, please review the following links:

• Terraform vercel_project resources section for a list of options that you can use to configure your Vercel Project from Terraform
• Terraform vercel_deployment resources example for an example Deployment configuration
• Terraform vercel_project_domain resources example for an example domain configuration
• Additionally, Terraform published a useful guide to creating preview environments with Terraform, GitHub Actions, and Vercel.