HCP Terraform allows users to create and confidentially share infrastructuremodules within an organization using the privateregistry. WithTerraform Enterprise, the private registry allows you to share moduleswithin or across organizations.

In this tutorial, you will share a module in the privateregistry that deploys an S3-backed webapp. Then you will use that module byreferencing it in a root Terraform configuration. For this tutorial, you will fork and work with two samplerepositories: one containing the module definition, and another withconfiguration 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 theGetting Started - HCP Terraform tutorial on creating a workspace.
• An AWS accountwith IAM AccessKeys
• anHCP Terraform variable set configured with your AWScredentials.
• 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 theexample repository for the webapp module.

Review the module configuration for thes3-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

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

Rename your forked repository. Go to theSettings tab of your forkedrepository. UnderRepository name, rename your repository toterraform-aws-s3-webapp. When you publish a single module in a git repository,we recommend you follow the naming conventionterraform-<PROVIDER>-<NAME> tomake it easier for users to identify which module corresponds to which gitrepository.

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

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

ClickCreate a new release, select1.0.0 in the tag version field, and set the Release title toFirst module release!.

ClickPublish 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 yourorganization'sRegistry, click thePublish dropdown, then selectModule.

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

Select theTag module publishing type.

Leave theModule Tag Prefix andSource Directory fields empty. Use thesefields when the repository contains multiple modules so that HCP Terraform andTerraform Enterprise can select which source files to import when you publishnew releases. Refer to thedocumentation on publishingmodules for more information.

Click theNext button.

On theConfirm selection step, set theModule Name toterraform-aws-s3-webapp and theProvider Name asaws. The click thePublish module button to publish your module.

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

Create a configuration that uses the module

Fork theroot 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 locallycreate a Terraform module, but now that your modules are stored in the cloud, your configuration will need to reflect the new location.

Yourmain.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 replacehashicorp-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 formapp.terraform.io/<ORGANIZATION-NAME>/terraform/<NAME>/<PROVIDER>.

In this repository, you have avariables.tf file and anoutputs.tf file as well.

Thevariables.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 theoutputs.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, calledlearn-private-module-root.

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

Once your configuration is uploaded successfully, HCP Terraform will promptyou toConfigure Terraform variables.

Set the region tous-east-1, the prefix todev-test, and the name to yourname. These variables correspond to thevariables.tf file in your root moduleconfiguration and are necessary to create a unique S3 bucket name for yourwebapp. Then clickSave variables.

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

Deploy the infrastructure

On the workspace overview page, drop down theActions menu, and selectStart 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 thewebsite_endpoint address in a browser to test your deployment.

Destroy your deployment

In the HCP Terraform UI for your workspace, open theSettings menu and chooseDestruction and Deletion. Click theQueue 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 toallow this plan to run. ClickQueue destroy plan to start the run. When theplan finishes, clickConfirm & 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 theprivateregistry.

• Follow theCreate and Use No-CodeModules tutorial.

• In this tutorial, you published a single module, hosted in a single gitrepository. You can also publishmultiplemodulesfrom a single repository.