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.

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

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.

# 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}})

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.

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.