Configure HCP Terraform integration

This page describes how to configure HCP Waypoint to interact with your HCP Terraform organization. Platform engineers often perform this task.

Overview

HCP Waypoint templates and add-on definitions both leverage HCP Terraform no-code modules to deploy applications and their underlying infrastructure. As a result, you must provide HCP Waypoint with your HCP Terraform organization name and team token so it can connect to HCP Terraform.

When an application developer uses a template or installs an add-on, HCP Waypoint calls the HCP Terraform API to create a new workspace and trigger an HCP Terraform run. When an application developer destroys an application or uninstalls an add-on, HCP Waypoint triggers a destroy run and deletes the workspace from HCP Terraform.

You must configure HCP Waypoint with HCP Terraform before you can create or use an HCP Waypoint template or add-on.

Prerequisites

• An HCP account with HCP Waypoint enabled. Refer to HCP Account for information about creating an account.
• an HCP Terraform organization with Plus tier. HCP Terraform must be Plus tier to use HCP Terraform no-code modules and the private module registry.

Usage

We recommend that you create a team and team token in HCP Terraform specifically for HCP Waypoint. The HCP Terraform team should only have access to HCP Terraform projects you intend to deploy to. HCP Waypoint requires that the HCP Terraform API token has the following project team permissions:

• Read the project
• Create workspaces
• Delete workspaces
• Apply runs
• Read and write variables
• Output only access to state

For more information on the required permissions, refer to HCP Terraform token permissions.

To configure HCP Waypoint with your team token:

1. From the HCP Waypoint overview, go to the Settings menu.
2. Enter an HCP Terraform team token.
3. Select the name of the HCP Terraform organization.
4. Click Save.

Next steps

To learn more about what you can do with HCP Waypoint after you configure it to HCP Terraform, refer to the following topics:

• Create and manage templates
• Create and manage add-on definitions