» Using Modules from the Terraform Cloud Private Module Registry

By design, Terraform Cloud's private module registry works much like the public Terraform Registry. If you're already familiar with the public registry, here are the main differences:

  • Use Terraform Cloud's web UI to browse and search for modules.
  • Module source strings are slightly different. The public registry uses a three-part <NAMESPACE>/<MODULE NAME>/<PROVIDER> format, and private modules use a four-part <HOSTNAME>/<ORGANIZATION>/<MODULE NAME>/<PROVIDER> format. For example, to load a module from the example_corp organization on the SaaS version of Terraform Cloud:

    module "vpc" {
      source  = "app.terraform.io/example_corp/vpc/aws"
      version = "1.0.4"
    }
    
  • Terraform Cloud can automatically access your private modules during Terraform runs. However, when running Terraform on the command line, you must configure a credentials block in your CLI configuration file (.terraformrc). See below for the credentials format.

» Finding Modules

All users in your organization can view your private module registry.

To see which modules are available, click the "Modules" button in Terraform Cloud's main navigation bar.

Terraform Cloud screenshot: Navigation bar with modules button highlighted

This brings you to the modules page, which lists all available modules.

Terraform Cloud screenshot: the list of available modules

You can browse the complete list, or shrink the list by searching or filtering.

  • The "Providers" drop-down filters the list to show only modules for the selected provider.
  • The search field searches by keyword. This only searches the titles of modules, not READMEs or resource details.

» Viewing Module Details and Versions

Click a module's "Details" button 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 a version.

Terraform Cloud screenshot: a module details page

» Using Private Modules in Terraform Configurations

In Terraform configurations, you can use any private module from your organization's registry. The syntax for referencing private modules in source attributes is <HOSTNAME>/<ORGANIZATION>/<MODULE NAME>/<PROVIDER>.

module "vpc" {
  source  = "app.terraform.io/example_corp/vpc/aws"
  version = "1.0.4"
}

If you're using the SaaS version of Terraform Cloud, the hostname is app.terraform.io; Terraform Enterprise instances have their own hostnames. The second part of the source string (the namespace) is the name of your organization.

For more details on using modules in Terraform configurations, see "Configuration Language: Modules" in the Terraform docs.

» Usage Examples and the Configuration Designer

Each registry page for a module version includes a usage example, which you can copy and paste to get started.

Alternately, you can use the configuration designer, which lets you select multiple modules and fill in their variables to build a much more useful initial configuration. See the configuration designer docs for details.

» The Generic Module Hostname (localterraform.com)

Optionally, you can use the generic hostname localterraform.com in module sources instead of the literal hostname of a Terraform Enterprise instance. When Terraform is executed on a Terraform Enterprise instance, it automatically requests any localterraform.com modules from that instance.

For example:

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

Configurations that reference modules via the generic hostname can be used without modification on any Terraform Enterprise instance, which is not possible when using hardcoded hostnames.

» Running Configurations with Private Modules

» In Terraform Cloud

Terraform Cloud can use your private modules during plans and applies with no extra configuration, as long as the workspace is configured to use Terraform 0.11 or higher.

A given workspace can only use private modules from the organization it belongs to. If you want to use the same module in multiple organizations, you should add it to both organizations' registries. (See Sharing Modules Across Organizations.)

» On the Command Line

If you're using Terraform 0.11 or higher, you can use private modules when applying configurations on the CLI. To do this, you must provide a valid Terraform Cloud API token.

» Permissions

When you authenticate with a user token, you can access modules from any organization you are a member of. (A user is a member of an organization if they belong to any team in that organization.)

Within a given Terraform configuration, you should only use modules from one organization. Mixing modules from different organizations might work on the CLI with your user token, but it will make your configuration difficult or impossible to collaborate with. If you want to use the same module in multiple organizations, you should add it to both organizations' registries. (See Sharing Modules Across Organizations.)

» Configuration

To configure private module access, add a credentials block to your CLI configuration file (.terraformrc).

credentials "app.terraform.io" {
  token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
}

The block label for the credentials block must be Terraform Cloud's hostname (app.terraform.io or the hostname of your Terraform Enterprise instance), and the block body must contain a token attribute whose value is a Terraform Cloud authentication token. You can generate a personal API token from your user settings page in Terraform Cloud.

Make sure the hostname matches the hostname you use in module sources — if the same Terraform Cloud server is available at two hostnames, Terraform doesn't have any way to know that they're the same. If you need to support multiple hostnames for module sources, you can add two credentials blocks with the same token.