Create and deploy a Terraform Developer Portal add-on

Similar to a Terraform Developer Portal template, platform engineers can create add-ons that contain pre-defined infrastructure for 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.

For example, a template 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.

In this tutorial, you will create an add-on from a module that deploys the GitHub repository you created in the previous tutorial to AWS S3, as well as configure AWS CloudFront to enable caching and TLS encryption.

Prerequisites

For this tutorial, you will need the following:

• A GitHub account.
• An HCP Terraform account organization on the Standard edition or higher to use HCP Terraform no-code modules and the private module registry.
• A GitHub VCS provider configured in your HCP Terraform organization. Refer to Set up the GitHub.com VCS provider for more information.
• An AWS account, as well as credentials to authenticate to the account.
• A deployed instance of the terramino template you created in the previous tutorial.

Publish the no-code module

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-s3-deployment. Leave the rest of the settings at their default values.

Review module configuration

This module contains Terraform configuration to read the files from your GitHub repository, deploy them to S3, then configure CloudFront. The module repository contains the following files:

├── aws.tf
├── github.tf
├── outputs.tf
├── terraform.tf
└── variables.tf

Open github.tf to review the configuration to read the files from GitHub:

data "github_repository" "app" {
  name = var.developer_portal_application
}

data "github_branch" "app" {
  repository = data.github_repository.app.name
  branch     = data.github_repository.app.default_branch
}

data "github_tree" "app" {
  recursive  = true
  repository = data.github_repository.app.name
  tree_sha   = data.github_branch.app.sha
}

locals {
  # Only deploy the files in the www/ directory of the supplied repository
  files = {
    for file in data.github_tree.app.entries :
    file.path => file
    if file.type == "blob" && startswith(file.path, "www/")
  }

  # Lookup map for content types
  content_types = {
    "html" = "text/html",
    "css"  = "text/css",
    "js"   = "application/x-javascript"
  }
}

data "github_repository_file" "app" {
  for_each = local.files

  repository = data.github_repository.app.name
  branch     = data.github_repository.app.default_branch
  file       = each.key
}

Since the application you created in the previous tutorial created a GitHub repository with a name that matches your application name, it uses the developer_portal_application variable that Terraform Developer Portal prepopulates to look up the repository. This configuration reads all of the files from your GitHub repository, creates a local named files to only choose the files in the www directory, then creates a github_repository_file data source for each file to read its content.

Next, open the aws.tf file and review the configuration to create the S3 and CloudFront infrastructure:

resource "aws_s3_bucket" "app" {
  bucket = "${var.developer_portal_application}-${random_string.bucket_suffix.id}"
}

resource "aws_s3_object" "app" {
  for_each     = local.files
  bucket       = aws_s3_bucket.app.id
  key          = replace(each.key, "/^www//", "") # Replace leading directory name
  content      = data.github_repository_file.app[each.key].content
  content_type = local.content_types[regex(".*\\.(.*)$", each.key)[0]] # Lookup content type based on file extension
}

This configuration creates a new S3 bucket, then creates an aws_s3_object resource for each file found in the github.tf file.

Publish the module

Complete the following steps to publish the module to your HCP Terraform organization's private module registry:

1. Sign in to your HCP Terraform organization and click Registry in the sidebar.
2. Click the Publish dropdown, then click Module.
3. Choose your VCS provider.
4. In the Repository dropdown, select the terraform-aws-s3-deployment repository you created earlier in this tutorial.
5. Under Module Publishing Type, chose Branch.
6. Enter a Branch Name of main.
7. Enter a Module Version of 1.0.0.
8. Click Next.
9. Enter a Module Name of s3-deployment.
10. Enter a Provider Name of aws.
11. Enable the Add module to no-code provision allowlist checkbox.
12. Click Publish module.

After a few moments, HCP Terraform displays your module overview.

Create an add-on

Complete the following steps to create a Terraform Developer Portal add-on that you can use to deploy additional infrastructure for your applications:

1. Sign in to your HCP Terraform organization and click Developer Portal.
2. Click Add-ons in the left navigation panel.
3. Click New Add-on.
4. In the Name textbox, enter s3-deployment.
5. In the Base Module dropdown, choose the s3-deployment (aws) module you published in the previous step.
6. Terraform Developer Portal prompts you to provide values for any variables that do not have default values. In the gh_org textbox, enter the same GitHub username that you entered in the previous tutorial. This is the organization that the add-on reads the application files from.
7. Click Continue.
8. In the Summary textbox, enter Deploy a static website from GitHub to S3.
9. Click Update from module's README to import the module's README file.
10. Click Save.

After you create your add-on, anyone in your HCP Terraform organization can deploy it alongside their deployed applications.

Deploy the add-on

Next, complete the following steps to deploy the add-on:

1. Sign in to your HCP Terraform organization and click Developer Portal.
2. Click Applications in the left navigation panel.
3. Click the terramino-get-started application you created in the previous tutorial.
4. Click Available add-ons in the left navigation panel.
5. Next to the s3-deployment add-on, click Install.

When you install an add-on, Terraform Developer Portal automatically creates a new workspace in the same project as the application. It also populates the following variables in the new workspace:

You can reference these values in your add-on no-code module to automatically tag resources, or use them as values to look up resources created by the template or other add-ons.

Terraform Developer Portal lets you install multiple instances of add-ons for the same application. For example, if you installed a second instance of the s3-deployment add-on, Terraform Developer Portal would create another S3 bucket, upload the same files from you GitHub repository, and report a second URL for the deployment. The ability to attach multiple instances of an add-on could be useful, for example, when creating deployments for multiple environments.

Next, click Overview in the left navigation panel to return to the application overview page, then click the Workspaces dropdown to view the status of your add-on deployment. Terraform Developer Portal lists the second workspace alongside the application workspace. After a few moments, Terraform Developer Portal reports that the workspace apply run completed. You may need to refresh the page to update the status.

When HCP Terraform completes the apply run, you can view the outputs from the add-on workspace. Click Installed add-ons in the left navigation panel, click the name of the add-on you just deployed, then click View all under Outputs.

This add-on reports one output named website_endpoint that links you to your running application. Copy this value and go to this address in a new tab in your browser to see the application running.

Next steps

In this tutorial, you published a new no-code module, then used it to create a Terraform Developer Portal add-on. You then used that add-on to deploy a static website in S3 and create a CloudFront distribution.

In the next tutorial, you will see how you can use Terraform actions to enable pre-defined maintenance workflows for applications and add-ons.