Create a Waypoint template
HCP Waypoint templates allows platform engineers to pre-define infrastructure in a Terraform no-code module and Waypoint template configuration. Developers use these templates to create new applications in Waypoint.
Platform engineers can create a template with common infrastructure that complies with your organization's policies for security, finance, scaling, and more. This ensures that any infrastructure that uses the template is properly configured.
Templates serve as a starting point for application developers. For example, an application template can consist of a code repository template configured with your organization's default frontend framework, linting libraries, and CI/CD pipelines. Other examples of application templates can be a production-ready Kubernetes cluster or backend API framework that is configured for serverless.
Note
HCP Waypoint template and add-on features require access to Terraform Cloud's no-code provisioning, and therefore require Terraform Cloud Plus or Enterprise.
In this tutorial, you will publish a no-code module to Terraform Cloud that creates new GitHub repos with pre-populated code and actions to deploy static websites. Then, you will create an HCP Waypoint template that gives developers safe, self-service access to deploy the no-code module, without requiring them to interact with Terraform or other infrastructure tooling.
Prerequisites
For this tutorial, you will need:
- A Terraform Cloud (TFC) Plus or Enterprise account
- A HashiCorp Cloud Platform (HCP) account
- A GitHub account
- (Optional) A Slack channel with Incoming Webhooks configured
Fork the no-code module
The GitHub static app no-code module is a Terraform module that creates a GitHub repository from a template repository, sets up a GitHub Actions workflow to publish a static web application to GitHub Pages, and sends a notification to a Slack channel when the workflow completes.
Fork the no-code repository into your own organization or user space. Then, create a new release with a tag named v1.0.0
. Finally, open the repository in GitHub or clone it locally and open it in your code editor.
Review the module contents
Open variables.tf
and review the module's required variables.
template_org
andtemplate_repo
make up the location of the template repository to copy fromdestination_org
is the organization where the new application repository is to be createdgh_token
is the GitHub token withrepo
anddelete_repo
permissionsslack_hook_url
is the Slack webhook URL for posting messageswaypoint_application
is the Waypoint application name that HCP Waypoint defines when a developer creates an application
The main.tf
file configures the GitHub provider by providing the destination organziation and the GitHub token. It also creates a repository in that organization and enables GitHub Pages in it.
Next, it creates a README file from a template, substituting in the Waypoint application name and destination organization to render the GitHub Pages URL.
Finally, it creates a GitHub Actions environment secret that contains the Slack webhook URL.
Publish the no-code module
HCP Waypoint uses the no-code provisioning feature in Terraform Cloud to create and delete application infrastructure. To give Terraform Cloud access to the module, you need to publish it in the private module registry.
Log in to Terraform Cloud and navigate to the Registry page from the left navigation.
Click on the Publish button on the right side of the page and then click the Module button.
Connect to your GitHub account, follow the steps to authenticate, and then select the GitHub static app no-code module repository.
Tip
This tutorial uses GitHub as the version control provider but you can use other providers. Refer to the full list of supported providers.
Click on the Add Module to no-code provision allowlist check box and finish by clicking on the Publish module button.
Set up a TFC token
HCP Waypoint requires a token to interact with Terraform Cloud.
Open Terraform Cloud, click on the Settings option in the left navigation, and then click on the Teams option. Click on the Create a team button, enter hcp-wp
in the Team name field, and click the Create button.
On the team settings page, under the Organization Access section, select the View all applications option, the Manage all workspaces option, and the Manage run tasks option. Scroll down and save these changes by clicking on the Update team organization access button.
Scroll down to the Team API Token section. Click on the Create a team token button and select an expiration of 1 day from the dropdown. Click on the Generate token button.
Copy the token string. You will enter it into HCP Waypoint in the next section.
Configure HCP Waypoint
Take note of your TFC organization name at the bottom of the left navigation.
Log in to HCP and navigate to the Waypoint page. Click on the Settings option from the left navigation.
Paste the token string from TFC into the Terraform Cloud team token field and enter your TFC organization name into the Terraform organization name field.
Click on the Save button.
Add module variables to TFC
Terraform Cloud can read values from variables stored in Variable Sets when it starts a run.
Create a global variable set with the following variables and update them with your own values. Refer to the Create Variable Sets page for details.
When adding the gh_token
and slack_hook_url
variables, be sure to tick the Sensitive box.
destination_org
gh_token
- (Optional)
slack_hook_url
- Create this variable but leave it empty if you don't have a Slack workspace or don't want deployment notifications
Add the two template variables below with the values provided.
template_org
:hashicorp-education
template_repo
:learn-hcp-waypoint-static-app-template
Click the Save variable set button to complete the setup.
Create the Waypoint application template
Log in to HCP and navigate to the Waypoint page. Click on the Templates option from the left navigation. Click on the Create application template button.
Enter the following information for the template.
Field | Value |
---|---|
Template name | static-webapp |
Tags | static , webapp , javascript |
Summary | A template for static webapps |
Description | A static webapp template that creates a GitHub repository with a GitHub Actions workflow that deploys to GitHub Pages. |
Developer instructions | Use the template below and replace the placeholder value ORG_NAME with your value for destination_org from earlier. |
Select the static-app
module from the Terraform Cloud module dropdown. The latest version will automatically be selected for you in the Terraform Cloud module version dropdown.
Click the Create button at the bottom of the page.
HCP Waypoint creates the template and redirects you to the Templates page.
Click on the static-webapp template name to view the template details and verify that all of the inputs are correct. You can click on the Manage button, then Edit template if you need to update the template.
Note
Any updates made to the template defintion will only affect new applications created from the template and not any pre-existing application created from the template.
Next steps
In this tutorial, you learned about templates, created a no-code module for a template in Terraform Cloud, and created a Waypoint template in HCP Waypoint.
Continue on to the next tutorial to learn how to use a template to create an application.