Build a self-service internal developer platform

Development workflows often grow in complexity as your systems and teams scale. When this happens, many organizations build dedicated platform teams to manage infrastructure, data stores, monitoring, and CI/CD pipelines for production applications and guarantee workflow stability. To ensure reproducibility, these platform teams establish and adopt golden patterns and golden actions.

1. Golden patterns standardize the architecture and requirements of production-ready applications. For example, the platform team might provide a scaffold of a Java application that includes standard libraries, CI/CD pipeline connections, and data services.
2. Golden actions standardize safe day-two operations and maintenance tasks. Examples include clearing a cache, performing an off schedule database backup, and seeding a development database with common example data.

HCP Waypoint lets you codify and share these golden patterns and golden actions across your organization. HCP Waypoint lets users choose from a catalog of templates and add-ons to piece together the resources they need. You can also attach actions to these templates to let users perform common day-two operations.

In this tutorial, you will use HCP Waypoint to deploy Terramino, a browser-based game, on EC2 with an optional Redis server. To do this, you create two Terraform no-code modules to build the infrastructure, then create an HCP Waypoint template to deploy the application, a Waypoint add-on to attach a Redis cache to it, and a Waypoint action to clear the cache.

Prerequisites

HCP Waypoint relies on HCP Terraform. This tutorial assumes that you are familiar with the HCP Terraform workflow. If you are new to HCP Terraform, complete the HCP Terraform Get Started tutorials first.

This tutorial also assumes that you have an HCP organization and project, and that you are familiar with the HashiCorp Cloud Platform. If you are new to the HashiCorp Cloud Platform, complete the Get started with HCP Waypoint tutorial.

In order to complete this tutorial, you will need the following:

• An HCP Terraform Plus account.
• A HashiCorp Cloud Platform organization, project, and access to HCP Vault Secrets.
• A GitHub account configured as a VCS provider in HCP Terraform.
• AWS credentials

Create an HCP service principal

Terramino and the Redis module communicate with HCP Vault Secrets and need a service principal keypair to interact with the API. In the HCP portal, choose your organization and project, then complete the following steps to create a new service principal:

1. Click Access control (IAM).
2. Click Service principals.
3. Click Create service principal.
4. Name the service principal terramino-vault-secrets.
5. Under Select service, choose "Secrets".
6. Under Select role(s), choose "Vault Secrets App Manager".
7. Click Create service principal.

Next, click Keys in the sidebar, then click Generate key to create a new keypair for the service principal. Copy this information somewhere secure. You will use these values in a later step and HCP does not show the client secret again.

Create an HCP Terraform team

Create an HCP Terraform team. You will use this team to generate a team token for HCP Waypoint.

In HCP Terraform, click Settings, then Teams.

Click Create a team, give it the name "waypoint", then click Create.

HCP Terraform automatically takes you to the team settings page. Leave all the default organization permissions.

Create an HCP Terraform project

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

From 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 team you just created access to this project. Click Settings, then Team access. Click Add team.

On the next page, choose the "waypoint" team from the Team dropdown, select the Maintain permissions, then click Assign permissions.

Create a variable set with your AWS credentials

Next, create a variable set with your AWS credentials. Navigate to your organization's Settings page, then click Variable sets. Click Create variable set and name it "waypoint-aws".

Under Variable set scope, choose Apply to specific projects and workspaces. In the Apply to projects section, choose the "Waypoint" project you just created.

In the Variables section, add the following variables:

Click Create variable set to save the variable set and apply it to your project.

Generate an HCP Terraform team token

You must provide HCP Waypoint an HCP Terraform token so that it can create and manage workspaces.

To generate a team token:

1. Click API tokens in the left navigation bar of your organizations Settings page.
2. Click the Team Tokens tab.
3. Click Create a team token.
4. Select the "waypoint" team that you just created.
5. Leave the default Expiration of 30 days.
6. Click Create.

HCP Terraform only shows this team token once, so copy it to a secure location. You will reference this token later in the tutorial.

Next, configure HCP Waypoint with the HCP Terraform team token you just created.

In the HCP Waypoint Settings page, click the Manage dropdown and click Edit settings.

Paste your team token in the HCP Terraform team token field, then select the name of your HCP Terraform organization in the HCP Terraform organization name field.

Click Save to finish configuring HCP Waypoint.

Create the Terramino Waypoint template

Templates deploy no-code modules from your organization's HCP Terraform private registry. Templates also define additional metadata, such as developer information on how a user deploying the template can use the template, variables, and tags.

Create the the example application repository

Navigate to the template repository for this tutorial. Click the Use this template button and select Create a new repository. Choose a GitHub account to create the repository in and name the new repository "terraform-aws-terramino". Leave the rest of the settings at their default values.

This repository contains Terraform configuration to deploy the web application.

.
├── boot.sh
├── hvs.tf
├── main.tf
├── network.tf
├── outputs.tf
├── terraform.tf
├── terraform.tfstate
├── terraform.tfstate.backup
├── terraform.tfvars
└── variables.tf

This configuration creates the required networking for the application. It then creates an EC2 instance and runs the boot.sh script to download, build, and run the web application.

The variables.tf file defines input variables for the HCP service principal client ID and secret. The web application requires this information to connect to HCP Vault Secrets. This file also defines an optional variable named waypoint_application. HCP Waypoint passes this value to the configuration when it deploys this module.

Publish the web application module

To publish your module, navigate to your organization's HCP Terraform registry, click Publish, then select Module.

Select your version control provider, then select your terraform-aws-terramino repository.

On the Add Module screen, provide the following values:

Select Add Module to no-code provision allowlist, then click Publish module.

Create the Waypoint template

Create a Waypoint template to deploy the web application module you just published.

In HCP Waypoint, click Templates in the left navigation bar, then click Create a template.

Enter the following information to configure the template:

HCP Waypoint also shows the input variables for the no-code module that do not have default values. Provide the following values:

Notice that HCP Waypoint shows a checkbox below each variable labeled Enable this value to be defined when the application is created. When you choose this option, users will be able to provide a value for the variable when they deploy the template. For this example, leave these checkboxes unselected.

Click Next.

The next screen collects metadata about the template that developers can use when they deploy it. Enter the following information to configure the template:

Under Developer instructions click Import to import the README.md file from the GitHub repository. These instructions help developers know how to use this template once it's deployed.

To add a label, type a value and then hit Enter. Add the following Labels to the template: web, game, aws.

Click Publish to finish creating the template.

Deploy the Waypoint template

Now that you have created the template, you can use it to deploy an instance of the web application module. HCP Waypoint shows the overview of the template you just created. To deploy an instance of it, click Create application in the top-right corner.

Select your Terramino template and click Next.

The next screen prompts for variable values for this instance of the deployed template.

For the Application name, enter "terramino-app" and click Create application.

When you deploy a template, Waypoint creates a workspace in HCP Terraform and triggers a run to deploy the no-code module. Waypoint provides a link to the workspace in the Infrastructure and resources section on the right side of the application overview screen. HCP Terraform auto-applies this run once it finishes the plan.

After a few minutes, Waypoint reports the Infrastructure status as a success, indicating that the HCP Terraform run completed without issue.

Click the Output tab to see the output values from the HCP Terraform workspace. Copy the hostname output and open it in your browser to verify the Terramino deployment. Leave this tab open as you will visit this page again later in the tutorial.

Create the Redis Waypoint add-on

Add-ons are modular components that application developers can use to install supporting infrastructure, such as databases, new DNS entries, or telemetry dashboards.

Create the Redis example repository

The Redis module creates a Redis server and writes its credentials to HCP Vault Secrets. Terramino uses Redis to store and read the high score of the Terramino game.

Navigate to the template repository containing the Redis module for this tutorial. Click the Use this template button and select Create a new repository. Choose a GitHub account to create the repository in and name the new repository "terraform-aws-redis-ec2". Leave the rest of the settings at their default values.

This repository contains Terraform configuration to deploy an EC2 instance that runs Redis and store the connection information in HashiCorp Vault Secrets.

.
├── boot.sh
├── hvs.tf
├── main.tf
├── network.tf
├── output.tf
├── terraform.tf
├── terraform.tfstate
├── terraform.tfstate.backup
├── terraform.tfvars
└── variables.tf

This configuration creates the required networking for the Redis server. It then generates a username and password, creates an EC2 instance, and runs the boot.sh script to install and configure Redis.

The variables.tf file defines input variables for the HCP service principal client ID and secret. Terraform uses this to write the connection information to HashiCorp Vault Secrets.

Publish the Redis module

To publish your module, navigate to your organization's HCP Terraform registry, click Publish, then select Module.

Select your version control provider, then select your terraform-aws-redis-ec2 repository.

On the Add Module screen, provide the following values:

Select Add Module to no-code provision allowlist, then click Publish module.

Create the Waypoint add-on

On the Waypoint homepage, click Add-ons, then click Create an add-on.

Set the following values to configure the add-on:

Ensure that Use the same HCP Terraform project that the application is in is enabled. This will keep your application and add-on workspaces in the same project in HCP Terraform.

HCP Waypoint prompts for values for the no-code module's the input variables that do not have default values. Provide the following values:

Click Next.

Enter the following information to configure the template:

Add the following Labels to the add-on: redis, dedicated, cache.

Click Publish to finish creating the add-on:

Install the Redis Waypoint add-on

Click Applications in the left navigation bar, then choose your terramino-app application from the list.

Click Add-ons in the left navigation bar, then click the Install button next to the redis-dedicated add-on.

As with templates, Waypoint creates a new workspace in HCP Terraform to deploy your add-on. Click 1 instance installed under the Install button to review the installed add-ons.

On the next screen, HCP Waypoint displays the add-on, named terramino-app-redis-dedicated-xxxxxx. This name is the combination of the application name, add-on name, and a random string to avoid naming collisions for multiple deployments. Click the name of this installed add-on.

Similar to the deployed template, Waypoint provides a link to the HCP Terraform workspace and a deploy status on the right side of the screen. Wait for Waypoint to finish the deployment and report the status as Success.

Return to your Terramino tab and refresh the page. Click the Debug button in the top-right corner to view the connection information that the application read from HCP Vault Secrets. This confirms that Terramino can connect to your Redis server. Terramino uses the HCP Vault Secrets API to read the connection information and configure a connection to the Redis server.

Play a few rounds of Terramino and try to beat your high score. Notice that your score now persists when you refresh the page.

Create a Waypoint action

HCP Waypoint actions codify common day-two operations, such as rolling back to a known good version of an application, clearing a cache, or performing an off-schedule database backup. Actions enable downstream development teams to safely and independently perform these operations.

Create an action to send an HTTP request to change the Terramino high score.

On the Waypoint homepage, click Actions, then click Create an action. Create an action with the following information:

Create one Variable named score with a value of 0. Select Enable this value to be defined when the action is triggered. You may optionally enter a default value to provide a value when you run the action.

Choose the Custom action type and provide the following information:

Add the following header:

Click Create action to finish creating the action.

Assign the action to the Terramino application

You can assign actions to both templates and applications. If you assign an action to a template, Waypoint will automatically assign the action to every future application created from the template. Since you already deployed the template, assign the action directly to the application instead.

On the Actions overview screen, select your Set high score action.

Click Assignments in the left navigation bar, then choose the Applications tab. Click the Manage dropdown, the select Edit assignments.

Select the checkbox next to your terramino-app application, then click Confirm. HCP Waypoint shows a summary of the assignment changes for your review. Click Apply.

Run the action

Click Back to actions in the top-left corner, then click Applications in the left navigation bar. Choose your terramino-app from the list of applications.

Click the Actions dropdown at the top of the page, then choose your Set high score action.

Waypoint prompts you to provide a value for the score variable you defined in your action configuration. Enter "12345" then click Run.

Return to your Terramino tab and refresh the page. Notice that the high score is now "12345".

Destroy infrastructure

Clean up the infrastructure that you created in this tutorial.

Uninstall the Redis add-on

In HCP Waypoint, navigate to the Terramino application and click Add-ons. Click the three dots (...) next to your redis add-on, then click Uninstall. Enter "UNINSTALL" when Waypoint prompts you to confirm.

When you uninstall an add-on, Waypoint automatically starts a destroy run in the HCP Terraform workspace. When HCP Terraform finishes the destroy run, Waypoint deletes the workspace.

Uninstall the Terramino application

Click Back to terramino-app to navigate back to the application overview page. Click the Manage dropdown, then select Delete Application. Enter "DELETE" when Waypoint prompts you to confirm.

Similar to when you uninstalled the Redis addon, Waypoint starts a destroy run in HCP Terraform, then deletes the workspace.

Next steps

In this tutorial, you learned how you can use HCP Waypoint to package golden patterns and golden actions into an interface for your organization's development teams. You created a template to deploy a web application, and an add-on to attach a Redis cache to it, and an action to manage day-two operations like updating a value in the cache. HCP Waypoint makes the available to your organization to make it quick and easy for application teams to deploy the resources they need.

Refer to the following resources to learn more:

• Run the Get started with HCP Waypoint tutorials.
• Read the HCP Waypoint documentation.
• Learn more about HCP Vault Secrets.