Create a Waypoint template

HCP Waypoint templates allow 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, a 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 templates can be a production-ready Kubernetes cluster or backend API framework that is configured for serverless.

In this tutorial, you will publish a no-code module to HCP Terraform 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:

• An HCP Terraform Plus 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 and template_repo make up the location of the template repository to copy from
• destination_org is the organization where the new application repository is to be created
• gh_token is the GitHub token with repo and delete_repo permissions
• slack_hook_url is the Slack webhook URL for posting messages
• waypoint_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.

terraform {
  required_providers {
    github = {
      source  = "integrations/github"
      version = "~> 5.0"
    }
  }
}

provider "github" {
  owner = var.destination_org
  token = var.gh_token
}

resource "github_repository" "gh_repo" {
  name       = var.waypoint_application
  visibility = "public"

  template {
    owner                = var.template_org
    repository           = var.template_repo
    include_all_branches = false
  }

  # Enable GitHub pages
  pages {
    build_type = "workflow"
  }
}

#...

Next, it creates a README file from a template, substituting in the Waypoint application name and destination organization to render the GitHub Pages URL.

# ...

resource "github_repository_file" "readme" {
  repository = github_repository.gh_repo.name
  branch     = "main"
  file       = "README.md"
  content = templatefile("${path.module}/templates/README.md", {
    application_name  = var.waypoint_application,
    destination_org   = var.destination_org
  })
  commit_message      = "Added readme file."
  commit_author       = "Platform team"
  commit_email        = "no-reply@example.com"
  overwrite_on_create = true
}

# ...

Finally, it creates a GitHub Actions environment secret that contains the Slack webhook URL.

# ...

resource "github_actions_environment_secret" "slack_hook_url" {
  repository      = github_repository.gh_repo.name
  environment     = "github-pages"
  secret_name     = "SLACK_HOOK_URL"
  plaintext_value = var.slack_hook_url
}

Publish the no-code module

HCP Waypoint uses the no-code provisioning feature in HCP Terraform to create and delete application infrastructure. To give HCP Terraform access to the module, you need to publish it in the private module registry.

Log in to HCP Terraform 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 your fork of the static app no-code module repository.

Select the Tag option under the Module publishing type, click on the Add Module to no-code provision allowlist check box, and finish by clicking on the Publish module button.

Set up an HCP Terraform token

HCP Waypoint requires a token to interact with HCP Terraform. We recommend that you create a team in HCP Terraform specifically for HCP Waypoint, and generate a team token. We also recommend that you give the HCP Terraform team access to only the projects you intend to deploy to.

Open HCP Terraform, 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, leave all permissions set to None.

Scroll down and save these changes by clicking on the Update team organization access button.

Next, generate a team token.

1. Click on the API tokens option in the left navigation.
2. Choose the Team Tokens tab.
3. Click Create a team token.
4. Under Team, choose your hcp-wp team.
5. Choose an Expiration of 30 days.
6. Click Create.

Click Copy token to copy the token string. You will enter it into HCP Waypoint in the next section.

Create an HCP Terraform project

Create the HCP Terraform project. You will deploy your HCP Waypoint applications to this new project.

Navigate to the HCP Terraform homepage, click Projects in the left navigation bar, then click New project.

Name the project "Waypoint", then click Create.

Next, give the "hcp-wp" team you just created access to this project. Click Settings, then Team access. Click Add team.

On the next page, choose the "hcp-wp" team from the Team dropdown, then select the following permissions,

• Read project access
• Create workspaces
• Delete workspaces
• Apply run access
• Read and write variable access
• Read output only state access

Click Assign permissions to save your changes.

Configure HCP Waypoint

Take note of your HCP Terraform 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 HCP Terraform into the HCP Terraform team token field and wait for the HCP Terraform organization name dropdown to populate with your HCP Terraform organization names, then select your HCP Terraform organization name from the dropdown.

Click on the Save button.

Add module variables to HCP Terraform

HCP Terraform 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.

Click the Save variable set button to complete the setup.

Create the Waypoint template

Log in to HCP and navigate to the Waypoint page. Click on the Templates option from the left navigation. Click on the Create template button.

Enter the following information for the template.

Select the static-app module from the HCP Terraform module dropdown. The Waypoint project you created earlier will also be automatically selected for you in the Choose your HCP Terraform project dropdown. Click the Next button at the bottom of the page.

Enter the following information for the template.

# Static Webapp

Your static webapp repository will be ready soon and contain a GitHub Actions workflow to package and serve the webapp on GitHub Pages!

After the application is initialized in a minute or so, you can access your repository with the link below. It will contain a readme with additional information and a link to the deployed app.

[GitHub code repository](https://github.com/ORG_NAME/{{.ApplicationName}})

Click the Publish button at the bottom of the page.

HCP Waypoint creates the template and redirects you to the template's overview page.

Verify that all of the information is correct. To update any of the values click on the Manage button, then Edit template. Any updates you make to the template definition will only affect new applications created from the template and not any pre-existing ones.

Next steps

In this tutorial, you learned about templates, created a no-code module for a template in HCP Terraform, 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.