Waypoint
Create an add-on
Similar to a Waypoint template, a Waypoint add-on lets platform engineers pre-define infrastructure in a Terraform module. Add-ons differ from templates in their intended use. Where a template creates infrastructure that is required for every application, an add-on creates infrastructure that only some applications will need.
A template, for example, may create several instances for a multi-tier application, along with networking, security, and access management infrastructure components because those are all required for the application to operate.
An add-on may create and configure a database that each tier of the application can access, but only if that specific application requires a database.
Since templates and add-ons both use Terraform no-code modules, platform engineers need to determine whether infrastructure should be in one versus the other.
In this tutorial, you will create an add-on from a module that updates a Route 53 configuration to redirect a shortened subdomain URL to the GitHub Pages URL from the previous tutorial.
Prerequisites
For this tutorial, you will need:
- An HCP Terraform Plus or Enterprise account
- A HashiCorp Cloud Platform (HCP) account
- A GitHub account
- An AWS account
- A web domain that can be configured with custom name servers
- Use a Waypoint template tutorial completed
Create the Route 53 hosted zone
This tutorial creates a hosted zone because the domain is not registered within AWS. Route 53 creates subdomains but requires you to update the name servers in your domain name configuration to use the ones from the Route 53 hosted zone to route traffic correctly.
Navigate to the Route 53 hosted zone page in AWS and click on the Create hosted zone button.
Enter your domain name, select the Public hosted zone option, and click the Create hosted zone button.
Click on the hosted zone name to view the records. Copy the values in the NS record and add them to the list of name servers in your domain registrar's configuration page.
Make a note of the hosted zone ID by clicking on the Hosted zone details section. This will be used during the module configuration in HCP Terraform.
Fork the no-code module
The GitHub Route53 subdomain no-code module is a Terraform module that creates a subdomain in Amazon Route 53, an S3 bucket for URL redirection, and adds a file with the subdomain URL to a GitHub repository.
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.
destination_org
is the organization where the new application repository is to be createdgh_token
is the GitHub token withrepo
anddelete_repo
permissionswaypoint_application
is the Waypoint application name that is passed through from HCP Waypoint during application creationdomain
is the domain name URL that will be the base of the subdomain URLaws_region
is the AWS region that will contain the S3 bucketroute53_zone_id
is the ID of the Route 53 hosted zone created earlier
The main.tf
file configures the GitHub provider with the destination_org
and gh_token
variables and the AWS provider with the aws_region
variable.
It creates an S3 bucket with waypoint_application
and the domain
, sets up the bucket configuration to redirect all subdomain requests to the GitHub Pages URL of the repository, and adds an A record to the hosted zone with the S3 bucket configuration.
main.tf
# ...
resource "aws_s3_bucket" "redirect" {
bucket = "${var.waypoint_application}.${var.domain}"
}
resource "aws_s3_bucket_website_configuration" "redirect" {
bucket = "${var.waypoint_application}.${var.domain}"
redirect_all_requests_to {
host_name = "${var.destination_org}.github.io/${var.waypoint_application}"
}
}
resource "aws_route53_record" "subdomain" {
name = "${var.waypoint_application}.${var.domain}"
zone_id = var.route53_zone_id
type = "A"
alias {
name = aws_s3_bucket_website_configuration.redirect.website_domain
zone_id = aws_s3_bucket.redirect.hosted_zone_id
evaluate_target_health = true
}
}
Finally, it adds a new file to the application repository with the subdomain URL. This is added to a new file instead of appending it to the README so that if the add-on is uninstalled, the README won't be deleted during the Terraform destruction process.
main.tf
# ...
resource "github_repository_file" "subdomain_url" {
repository = var.waypoint_application
branch = "main"
file = "shortlink.md"
content = "http://${var.waypoint_application}.${var.domain}"
commit_message = "http://${var.waypoint_application}.${var.domain}"
commit_author = "Platform team"
commit_email = "no-reply@example.com"
overwrite_on_create = true
}
# ...
Publish the no-code module
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 version control provider account, follow the steps to authenticate, and then select the AWS Route 53 subdomain 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.
Add module variables to HCP Terraform
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.
Note that destination_org
and gh_token
are also required but these were set as part of the Waypoint template setup process in a previous tutorial. The subdomain module will read them from the variable set created in those tutorials.
Click the Save variable set button to complete the setup.
AWS credentials
Create another global variable set with two Sensitive environment variables for your AWS credentials, with the keys AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
and the values for your AWS account.
Create the Waypoint add-on definition
Log in to HCP and navigate to the Waypoint page. Click on the Add-ons option from the left navigation. Click on the Create an add-on button.
Enter the following information for the add-on.
Field | Value |
---|---|
Add-on name | subdomain |
Labels | subdomain , route53 |
Summary | An add-on for creating subdomains |
Description | This add-on creates a subdomain for the Waypoint application that points to the GitHub Pages website for that application. |
Developer instructions | Use the template below and replace the placeholder value ORG_NAME with your value for destination_org from earlier. |
Developer instructions template
# Subdomain add-on
A subdomain is being created for your application.
This will take a few minutes.
Once it completes, you can check your application repository for a `shortlink.md` file with the subdomain URL.
[GitHub code repository](https://github.com/ORG_NAME/{{.ApplicationName}})
Select the route53-subdomain
module from the HCP Terraform module dropdown. The latest version will automatically be selected for you in the HCP Terraform module version dropdown. The Use the same HCP Terraform project that the application is in option will also be automatically selected for you.
Click the Publish button at the bottom of the page.
HCP Waypoint creates the add-on and redirects you to the Add-ons page.
Click on the subdomain add-on name to view the add-on details and verify that all of the information is correct. You can click on the Manage button, then Edit add-on if you need to update the add-on.
Note
Any updates made to the add-on definition will only affect new installations of the add-on and not any pre-existing add-on installations.
Next steps
In this tutorial, you learned about add-ons, created a no-code module for an add-on in HCP Terraform, and created a Waypoint add-on in HCP Waypoint.
Continue on to the next tutorial to learn how to install an add-on in a Waypoint application.