Share modules in the private registry

HCP Terraform allows users to create and confidentially share infrastructure modules within an organization using the private registry. With Terraform Enterprise, the private registry allows you to share modules within or across organizations.

In this tutorial, you will share a module in the private registry that deploys an S3-backed webapp. Then you will use that module by referencing it in a root Terraform configuration. For this tutorial, you will fork and work with two sample repositories: one containing the module definition, and another with configuration code that uses the module.

Prerequisites

To complete this tutorial, you will need:

• A GitHub account
• An HCP Terraform account. If you have not set up HCP Terraform yet, follow the Getting Started - HCP Terraform tutorial on creating a workspace.
• An AWS account with IAM Access Keys
• an HCP Terraform variable set configured with your AWS credentials.
• OAuth Access to GitHub configured. If you belong to an organization where you don't have permission to configure this access, you can create a new organization for this tutorial.

Create the repository

Fork the example repository for the webapp module.

Review the module configuration for the s3-webapp module. The repository looks similar to the directory structure below.

.
└──learn-private-module-aws-s3-webapp
  ├── main.tf
  ├── outputs.tf
  └── variables.tf
  └── assets
      └── index.html

The variables.tf file will define your HCP Terraform variables as inputs for the aws_bucket resource that Terraform will create. This module also contains the webapp assets as well as the aws_s3_object resource to upload your content to the S3 bucket resource.

In order to publish modules to the Terraform registry, the module's repository name must have the format terraform-<PROVIDER>-<NAME>, where <NAME> can contain extra hyphens.

Rename your forked repository to match the convention. Go to the Settings tab of your forked repository. Under Repository name rename your repository to terraform-aws-s3-webapp.

HCP Terraform modules should be semantically versioned, and pull their versioning information from repository release tags. To publish a module initially, at least one release tag must be present. Tags that don't look like version numbers are ignored. Version tags can optionally be prefixed with a v.

To tag a release, click on the tag icon under your repository's Code tab.

Click Create a new release, select 1.0.0 in the tag version field, and set the Release title to First module release!.

Click Publish release to create the release.

Now that you have created and versioned your module, you need to add a VCS connection to your HCP Terraform organization.

Import the module

To create a Terraform module for your private registry, go to your organization's Registry, click the Publish dropdown, then select Module.

Choose the GitHub(Custom) VCS provider you configured and select the module repository named terraform-aws-s3-webapp.

Select the Tag module type and click the Publish module button.

Once you have added your module, notice the Usage Instructions section. You will use these as the building blocks for your workspace configuration.

Create a configuration that uses the module

Fork the root configuration repository. This repository will access the module you created and Terraform will use it to create infrastructure.

In a previous tutorial, you learned how to locally create a Terraform module, but now that your modules are stored in the cloud, your configuration will need to reflect the new location.

Your main.tf file in your root GitHub repository has the module reference to the private module you created in in HCP Terraform. You will need to replace hashicorp-learn with your own organization name.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0.0"
    }
  }
}

provider "aws" {
  region = var.region
}

module "s3-webapp" {
  source  = "app.terraform.io/hashicorp-learn/s3-webapp/aws"
  name   = var.name
  region = var.region
  prefix = var.prefix
  version = "1.0.0"
}

Modules from the private registry can be referenced using a registry source address of the form app.terraform.io/<ORGANIZATION-NAME>/terraform/<NAME>/<PROVIDER>.

In this repository, you have a variables.tf file and an outputs.tf file as well.

The variables.tf file defines the variables that are required inputs into your module. Although you will enter these manually in the HCP Terraform web UI, it is still a good idea to have these in your root configuration so that other teammates understand the required inputs.

variable "region" {
  description = "This is the cloud hosting region where your webapp will be deployed."
}

variable "prefix" {
  description = "This is the environment your webapp will be prefixed with. dev, qa, or prod"
}

variable "name" {
  description = "Your name to attach to the webapp address"
}

HCP Terraform uses the outputs.tf file to display your module outputs as you run them in the web UI.

output "website_endpoint" {
  value = module.s3-webapp.endpoint
}

Create a workspace for the configuration

In HCP Terraform, create a new workspace and choose your GitHub connection.

HCP Terraform will display a list of your GitHub repositories. You may need to filter by name to find and choose the your root configuration repository, called learn-private-module-root.

Leave the workspace name and advanced options unchanged, and click the Create workspace button to create the workspace.

Once your configuration is uploaded successfully, HCP Terraform will prompt you to Configure Terraform variables.

Set the region to us-east-1, the prefix to dev-test, and the name to your name. These variables correspond to the variables.tf file in your root module configuration and are necessary to create a unique S3 bucket name for your webapp. Then click Save variables.

HCP Terraform displays a success message. Click the Go to workspace overview button.

Deploy the infrastructure

On the workspace overview page, drop down the Actions menu, and select Start new run.

The output in the HCP Terraform UI plan is similar to the output from a Terraform CLI plan and will detail the resources each module will create. Confirm the plan.

The apply output generates the resources as they are defined in the modules. Navigate to the website_endpoint address in a browser to test your deployment.

Destroy your deployment

In the HCP Terraform UI for your workspace, open the Settings menu and choose Destruction and Deletion. Click the Queue destroy plan button and run a destroy plan against the infrastructure you created.

When Terraform prompts you, enter the workspace name to verify that you want to allow this plan to run. Click Queue destroy plan to start the run. When the plan finishes, click Confirm & Apply to clean up your deployment.

Next Steps

In this tutorial, you:

1. Created and versioned a GitHub repository for use in the private registry

2. Imported a module into your organization's private registry.

3. Constructed a root module to consume modules from the private registry.

Learn more about finding and sharing modules:

• Read the documentation on the private registry.

• Follow the Create and Use No-Code Modules tutorial.

• Find or share public modules in the public Terraform Registry.