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 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 created
• gh_token is the GitHub token with repo and delete_repo permissions
• waypoint_application is the Waypoint application name that is passed through from HCP Waypoint during application creation
• domain is the domain name URL that will be the base of the subdomain URL
• aws_region is the AWS region that will contain the S3 bucket
• route53_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.

# ...

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.

# ...

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.

• domain
• aws_region
• route53_zone_id

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.

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

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.