Integrating Terraform with Vercel
Understand the benefits of Terraform and how to set up the Integration 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"
}
}
repo
value with your Github repository path.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"
}
project_id
is taken from the definition of the vercel_project
resource. For example, since you defined the resource as resource "vercel_project" "with_next"
, the project_id
is vercel_project.with_next.id
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.