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.

Create a team token in HCP Terraform

Create a dedicated HCP Terraform team and team token for HCP Waypoint that only has access to HCP Terraform projects you intend to deploy to. Refer to Team API tokens in the Terraform documentation for information about creating team tokens.

The token must have 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 about required permissions, refer to HCP Terraform token permissions.

Configure HCP Waypoint

1. Sign into the HCP portal and click Waypoint in the Services menu.
2. Enter the HCP Terraform team token you created in Create a team token in HCP Terraform.
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