» Using Modules from the Terraform Cloud Private Module Registry

Hands-on: Try the Use Modules from the Registry tutorial on HashiCorp Learn.

A Terraform Cloud private module registry has a few key differences from the public Terraform Registry:

  • Location: You must use Terraform Cloud's web UI to search for modules and usage examples.
  • Module source strings: Private modules use a four-part format: <HOSTNAME>/<ORGANIZATION>/<MODULE NAME>/<PROVIDER>.
  • Authentication: Terraform Cloud workspaces using version 0.11 and higher can automatically access your private modules during Terraform runs. But when you run Terraform on the command line, you must authenticate to Terraform Cloud or your Terraform enterprise instance.

» Finding Modules

All users in your organization can view your private module registry. To find available modules, click the "Registry" button in the main navigation bar.

Terraform Cloud screenshot: Navigation bar with registry button highlighted

The "Modules" page appears, containing a list of all available modules. You can filter with:

  • Search: Show modules with titles that contain the specified keyword. Note that it does not search READMEs or resource details.
  • Providers: Show only modules for the selected provider.
  • Registries: Show only public or private modules.

Terraform Cloud screenshot: the list of available modules

» Shared Modules - Terraform Enterprise

On Terraform Enterprise, your module sharing configuration may grant you access to modules outside your organization. Modules that are shared with your current organization have a "Shared" badge (below). Modules in your current organization that are shared with other organizations have a badge that says "Sharing".

Terraform Enterprise screenshot: shared module

» Viewing Module Details and Versions

Click a module to view its details page. Use the "Versions" dropdown in the upper right to switch between the available versions, and use the Readme/Inputs/Outputs/Dependencies/Resources tabs to view detailed documentation and information about the selected version.

Terraform Cloud screenshot: a module details page

» Viewing Nested Modules and Examples

If a module contains nested modules following the standard module structure, then you can use the "Submodules" dropdown to navigate to the detail pages for nested modules. If there are examples, you can use the "Examples" dropdown to navigate to the detail pages for example modules.

Terraform Cloud screenshot: a module submodules button

» Using Modules in Configurations

The syntax for referencing publicly curated modules in the module block source argument is <NAMESPACE>/<MODULE NAME>/<PROVIDER>.

module "subnets" {
  source  = "hashicorp/subnets/cidr"
  version = "1.0.0"
}

The syntax for referencing private modules in the module block source argument is <HOSTNAME>/<ORGANIZATION>/<MODULE NAME>/<PROVIDER>.

  • Hostname: For the SaaS version of Terraform Cloud, use app.terraform.io. In Terraform Enterprise, use the hostname for your instance or the generic hostname.
  • Organization: If you are using a shared module with Terraform Enterprise, the module's organization name may be different than your organization's name. Check the source string at the top of the module's registry page to find the proper organization name. 
module "vpc" {
  source  = "app.terraform.io/example_corp/vpc/aws"
  version = "1.0.4"
}

To get started, you can copy and paste the usage example on the module's registry page or use the configuration designer to select multiple modules and fill in their variables.

» Generic Hostname - Terraform Enterprise

You can use the generic hostname localterraform.com in module sources to reference modules without modifying the Terraform Enterprise instance. When you run Terraform, it automatically requests any localterraform.com modules from the Terraform Enterprise instance.

module "vpc" {
  source  = "localterraform.com/example_corp/vpc/aws"
  version = "1.0.4"
}

To test configurations on a developer workstation without the remote backend configured, you must replace the generic hostname with a literal hostname in all module sources and then change them back before committing to VCS. We are working on making this workflow smoother, but we currently only recommend localterraform.com for large organizations that use multiple Terraform Enterprise instances.

» Module Availability

A workspace can only use private modules from its own organization's registry. When using modules from multiple organizations in the same configuration, we recommend:

  • Terraform Cloud: Add modules to the registry for each organization that requires access.

  • Terraform Enterprise: Check your site's module sharing configuration. Note that in Terraform Enterprise v202012-1 or higher, workspaces can also use private modules from organizations that are sharing modules with the workspace's organization.

» Running Configurations with Private Modules

» Version Requirements

Terraform 0.11 or later is required to:

  • Use private modules in Terraform Cloud workspaces with no extra setup.
  • Use the CLI to apply configurations with private modules.

» Authentication

You can use either a user token or a team token for authentication, but the type of token you choose may grant different permissions.

  • User Token: Allows you to access modules from any organization in which you are a member. You are a member of an organization if you belong to any team in that organization. In Terraform Enterprise v202012-1 or higher, you can also access modules from any organization that is sharing modules with any of your organizations.

  • Team Token: Allows you to access the private module registry from that team's organization and modules from any organizations that are sharing a private module registry with that team's organization.


Permissions Example

A user belongs to three organizations (1, 2, and 3), and organizations 1 and 2 share private module access with each other. In this case, the user's token gives them access to the private module registries for all of the organizations they belong to: 1, 2, and 3. However, a team token from a team in organization 1 only gives the user access the private modules in organizations 1 and 2.

» Configure Authentication

To configure authentication to Terraform Cloud or your Terraform Enterprise instance, you can:

Make sure the hostname matches the hostname you use in module sources because if the same Terraform Cloud server is available at two hostnames, Terraform will not know that they are the same. To support multiple hostnames for module sources, use the terraform login command multiple times, and specify a different hostname each time.