• Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Network Infrastructure Automation
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Terraform Cloud and Enterprise

  • Overview
  • Plans and Features
  • Getting Started
    • API Docs template
    • Overview
    • Account
    • Agent Pools
    • Agent Tokens
    • Applies
    • Audit Trails
    • Comments
    • Configuration Versions
    • Cost Estimates
    • Feature Sets
    • Invoices
    • IP Ranges
    • Notification Configurations
    • OAuth Clients
    • OAuth Tokens
    • Organizations
    • Organization Memberships
    • Organization Tags
    • Organization Tokens
    • Plan Exports
    • Plans
    • Policies
    • Policy Checks
    • Policy Sets
    • Policy Set Parameters
      • Modules
      • Providers
      • Private Provider Versions and Platforms
      • GPG Keys
    • Runs
      • Run Tasks
      • Stages and Results
      • Custom Integration
    • Run Triggers
    • SSH Keys
    • State Versions
    • State Version Outputs
    • Subscriptions
    • Team Access
    • Team Membership
    • Team Tokens
    • Teams
    • User Tokens
    • Users
    • Variables
    • VCS Events
    • Workspaces
    • Workspace-Specific Variables
    • Workspace Resources
    • Variable Sets
      • Overview
      • Module Sharing
      • Organizations
      • Runs
      • Settings
      • Terraform Versions
      • Users
      • Workspaces
    • Changelog
    • Stability Policy
    • Overview
    • Creating Workspaces
    • Naming
    • Terraform Configurations
      • Overview
      • Managing Variables
      • Overview
      • VCS Connections
      • Access
      • Drift Detection
      • Notifications
      • SSH Keys for Modules
      • Run Triggers
      • Run Tasks
    • Terraform State
    • JSON Filtering
    • Remote Operations
    • Viewing and Managing Runs
    • Run States and Stages
    • Run Modes and Options
    • UI/VCS-driven Runs
    • API-driven Runs
    • CLI-driven Runs
    • The Run Environment
    • Installing Software
    • Users
    • Teams
    • Organizations
    • Permissions
    • Two-factor Authentication
    • API Tokens
      • Overview
      • Microsoft Azure AD
      • Okta
      • SAML
      • Linking a User Account
      • Testing
    • Overview
    • GitHub.com
    • GitHub.com (OAuth)
    • GitHub Enterprise
    • GitLab.com
    • GitLab EE and CE
    • Bitbucket Cloud
    • Bitbucket Server and Data Center
    • Azure DevOps Services
    • Azure DevOps Server
    • Troubleshooting
    • Overview
    • Adding Public Providers and Modules
    • Publishing Private Providers
    • Publishing Private Modules
    • Using Providers and Modules
    • Configuration Designer
  • Migrating to Terraform Cloud
    • Overview
    • Using Sentinel with Terraform 0.12
    • Manage Policies
    • Enforce and Override Policies
    • Mocking Terraform Sentinel Data
    • Working With JSON Result Data
      • Overview
      • tfconfig
      • tfconfig/v2
      • tfplan
      • tfplan/v2
      • tfstate
      • tfstate/v2
      • tfrun
    • Example Policies
    • Overview
    • AWS
    • GCP
    • Azure
      • Overview
      • Service Catalog
      • Admin Guide
      • Developer Reference
      • Example Customizations
      • V1 Setup Instructions
    • Splunk Integration
    • Kubernetes Integration
    • Run Tasks Integration
    • Overview
    • IP Ranges
    • Data Security
    • Security Model
    • Overview
    • Part 1: Overview of Our Recommended Workflow
    • Part 2: Evaluating Your Current Provisioning Practices
    • Part 3: How to Evolve Your Provisioning Practices
    • Part 3.1: From Manual Changes to Semi-Automation
    • Part 3.2: From Semi-Automation to Infrastructure as Code
    • Part 3.3: From Infrastructure as Code to Collaborative Infrastructure as Code
    • Part 3.4: Advanced Workflow Improvements

  • Terraform Cloud Agents

  • Terraform Enterprise Admin

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»Using Providers and Modules from the Private Registry

All users in an organization can view the Terraform Cloud private registry and use the available providers and modules. A private registry has some key requirements and differences from the public Terraform Registry:

  • Location: You must use Terraform Cloud's web UI to search for providers, modules, and usage examples.
  • Provider and Module block source argument: Private providers and modules use a different format.
  • Terraform version: Terraform Cloud workspaces using version 0.11 and higher can automatically access your private modules during Terraform runs, and workspaces using version 0.13 and higher can also automatically access private providers.
  • Authentication: If you run Terraform on the command line, you must authenticate to Terraform Cloud or your Terraform Enterprise instance to use providers and modules in your organization’s private registry.

Note: Private providers are not available in Terraform Enterprise.

»Finding Providers and Modules

To find available providers and modules, click the Registry button in the main navigation bar. The Registry page appears.

Terraform Cloud screenshot: a filtered list of available providers

Click Providers and Modules to toggle back and forth between lists of available providers and modules in the private registry. You can also use the search field to filter for titles that contain a specific keyword. The search does not include READMEs or resource details.

»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 in the private registry (below). Modules in your current organization that are shared with other organizations have a badge that says Sharing.

Terraform Enterprise screenshot: shared module

»Viewing Provider and Module Details and Versions

Click a provider or module to view its details page. Use the Versions menu in the upper right to switch between the available versions, and use the Readme, Inputs, Outputs, Dependencies, and Resources tabs to view more information about the selected version.

Terraform Cloud screenshot: a module details page

»Viewing Nested Modules and Examples

Use the Submodules menu to navigate to the detail pages for any nested modules. Use the Examples menu to navigate to the detail pages for any available example modules.

Terraform Cloud screenshot: a module submodules button

»Using Public Providers and Modules in Configurations

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

The syntax for public providers in a private registry is the same as for providers that you use directly from the public Terraform Registry. The syntax for the provider block source argument is <NAMESPACE>/<PROVIDER_NAME>.

terraform {
  required_providers {
    google = {
      source = "hashicorp/google"
      version = "4.0.0"
    }
  }
terraform {
  required_providers {
    google = {
      source = "hashicorp/google"
      version = "4.0.0"
    }
  }

The syntax for referencing public modules in the module block source argument is <NAMESPACE>/<MODULE_NAME>/<PROVIDER_NAME>.

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

»Using Private Providers and Modules in Configurations

The syntax for referencing private providers in the provider block source argument is <HOSTNAME>/<NAMESPACE>/<PROVIDER_NAME>. For the SaaS version of Terraform Cloud, the hostname is app.terraform.io.

terraform {
  required_providers {
    random = {
      source = "app.terraform.io/demo-custom-provider/random"
      version = "1.1.0"
    }
  }
terraform {
  required_providers {
    random = {
      source = "app.terraform.io/demo-custom-provider/random"
      version = "1.1.0"
    }
  }

The syntax for referencing private modules in the module block source argument is <HOSTNAME>/<ORGANIZATION>/<MODULE_NAME>/<PROVIDER_NAME>.

  • 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 from 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"
}
module "vpc" {
  source  = "app.terraform.io/example_corp/vpc/aws"
  version = "1.0.4"
}

»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"
}
module "vpc" {
  source  = "localterraform.com/example_corp/vpc/aws"
  version = "1.0.4"
}

Important: The generic hostname only works within a Terraform Enterprise instance.

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.

»Provider and Module Availability

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

  • Terraform Cloud: Add providers and 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. Private providers are not available in Terraform Enterprise.

»Running Configurations with Private Providers and Modules

»Version Requirements

Terraform version 0.11 or later is required to use private modules in Terraform cloud workspaces and to use the CLI to apply configurations with private modules. Terraform version 0.13 and later is required to use private providers in Terraform Cloud workspaces and apply configurations with private providers.

»Authentication

To authenticate with Terraform Cloud, you can use either a user token or a team token. The type of token you choose may grant different permissions.

  • User Token: Allows you to access providers and 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.

    Note: When SAML SSO is enabled, there is a session timeout for user API tokens, requiring you to periodically re-authenticate through the web UI. Expired tokens produce a 401 Unauthorized error. A SAML SSO account with IsServiceAccount is treated as a service account and will not have the session timeout.

  • Team Token: Allows you to access the private registry of that team's organization and the registries from any other organizations that have configured sharing.

Permissions Example

A user belongs to three organizations (1, 2, and 3), and organizations 1 and 2 share access with each other. In this case, the user's token gives them access to the private 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 to the private registry in organizations 1 and 2.

»Configure Authentication

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

  • (Terraform 0.12.21 or later) Use the terraform login command to obtain and save a user API token.
  • Create a token and manually configure credentials in the CLI config file.

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

github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager