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.
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
.
Import the module
Note
The Private Registry requires OAuth verification to GitHub. If you haven't already, follow the OAuth instructions before proceeding.
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
.
On the next screen, fill in the following information.
Field | Value |
---|---|
Module type | Branch |
Branch name | master |
Module version | 1.0.0 |
Next, 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.
Tip
HCP Terraform Plus Edition lets you publish modules that users deploy without referencing them in Terraform configuration. Follow the Create and Use No-Code Modules tutorial to create a no-code ready module.
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.
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.
HCP Terraform uses the outputs.tf
file to display your module outputs as you run them in the web UI.
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.
Note
This tutorial assumes that you are using a tutorial-specific HCP Terraform organization with a global variable set of your AWS credentials. Review the Create a Credential Variable Set for detailed guidance. If you are using a scoped variable set, assign it to your new workspace now.
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:
Created and versioned a GitHub repository for use in the private registry
Imported a module into your organization's private registry.
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.