HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

Use providers and modules from the HCP Terraform private registry

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

  • Location: Search for providers, modules, and usage examples in the HCP Terraform private registry UI.
  • Provider and Module block source argument: Private providers and modules use a different format.
  • Terraform version: HCP Terraform 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 HCP Terraform or your instance to use providers and modules in your organization’s private registry.

HCP Terraform supports using modules in written configuration or through the no-code provisioning workflow.

Finding providers and modules

To find available providers and modules, click the Registry button. The Registry page appears.

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 providers and modules in Terraform Enterprise

On Terraform Enterprise, your registry sharing configuration may grant you access to another organization's providers and modules. Providers and modules that are shared with your current organization have a Shared badge in the private registry (below). Providers and modules in your current organization that are shared with other organizations have a badge that says Sharing.

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.

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.

Provisioning infrastructure from no-code ready modules

You can use modules marked No-Code Ready to create a new workspace and automatically provision the module's resources without writing any Terraform configuration. Refer to Provisioning No-Code Infrastructure for details.

Use providers and modules in workspaces

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

For Terraform configurations, the syntax to define 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"
    }
  }
}

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"
}

Use private providers and modules

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

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 HCP Terraform, 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"
}

Generic Hostname - HCP Terraform and Terraform Enterprise

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

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

Important: CLI-driven workflows require Terraform CLI v1.4.0 or above.

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 only recommend localterraform.com for large organizations that use multiple Terraform Enterprise instances.

Version Requirements

Terraform version 0.11 or later is required to use private modules in HCP Terraform 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 HCP Terraform workspaces and apply configurations with private providers.

Use providers and modules in Stack components

Stack components can source providers and modules from the following:

  • Remote addresses
    • Git Addresses
    • HTTP/HTTPS Addresses
  • HCP Terraform private registry
  • Terraform public registry

Providers

To source a provider from Github, use the following syntax: git::ssh://github.com/<ORGANIZATION_NAME>/repository.git/<SUB-PATH-TO-YOUR-PROVIDER>:

required_providers {
  my_provider_name = {
    source  = "git::ssh://github.com/<ORGANIZATION_NAME>/repository.git/<SUB-PATH-TO-YOUR-PROVIDER>"
    version = "~> 5.59.0"
  }
}

To source a provider from a remote address, use a URL that points to a tar.gz file:

required_providers {
  my_provider_name = {
    source  = "https://example.com/infra/compute?archive=tar.gz"
    version = "~> 1.0.0"
  }
}

To source a provider from the public Terraform registry, use <NAMESPACE>/<PROVIDER_NAME> syntax and reference that provider's documentation for the specifics.

The following example sources the public kubernetes provider and configures it:

required_providers {
  kubernetes = {
    source  = "hashicorp/kubernetes"
    version = "~> 2.32.0"
  }
}

provider "kubernetes" "main" {
  config {
    host                   = component.cluster.cluster_url
    cluster_ca_certificate = component.cluster.cluster_ca
    token                  = component.cluster.cluster_token
  }
}

The syntax for referencing a provider from the HCP Terraform private registry is app.terraform.io/<NAMESPACE>/<MODULE_NAME>/<PROVIDER_NAME>. The following example sources a provider named my-random from the private registry:

required_providers {
  my-random = {
    source  = "app.terraform.io/my-cool-org/demo-module/my-random"
    version = "~> 2.32.0"
  }
}

provider "my-random" "main" {
  config {
    # ...
  }
}

To learn more about specific syntax for providers in components, refer to provider block. To learn more about defining providers in Stacks, refer to Declare providers.

Modules

Each component block specifies the Terraform module to use as the source for that component.

To source a module from a Remote Git address, use the following syntax: git::<protocol>://<hostname>/<resource-path>.git//path/to/dir?ref=<git reference>.

Additional Details:

  • Supported protocols are HTTP/HTTPS and SSH.
  • Userinfo is not allowed in the URL (username & password).
  • Valid Refs (?ref=) include: Full commit sha, Git Tag, and Branch name.

The following example sources a module named kube from a GitHub repository:

component "my-component" {
  source = "git::https://github.com/my-cool-gh-org/kube.git?ref=0.1.0"

  # ...
}

To source a module from a remote address, use a URL that points to a tar.gz file:


component "my-component" {
  source = "https://example.com/infra/compute?archive=tar.gz"

  # ...
}

To source a module from the public Terraform registry, use <NAMESPACE>/<MODULE_NAME> syntax and reference that module's documentation for the specific syntax.

The following example component sources the public iam module:

component "auth" {
  source  = "terraform-aws-modules/iam/aws"
  version = "6.2.1"

  # ...
}

The syntax for referencing a module from the HCP Terraform private registry is app.terraform.io/<NAMESPACE>/<MODULE_NAME>. The following example sources a module named demo-module from the private registry:

component "demo" {
    source  = "app.terraform.io/my-cool-org/demo-module"
    version = "~> 2.32.0"
  # ...
}

To learn more about components syntax, refer to the component block reference.

Provider and Module Availability

A workspace or Stack 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:

  • HCP Terraform: Add providers and modules to the registry for each organization that requires access.

  • Terraform Enterprise: Check your site's registry sharing configuration for workspaces. Workspaces can also use private providers and modules from organizations that are sharing with the workspace's organization.

Authentication configurations with private providers and modules

To authenticate with HCP Terraform, 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. 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 HCP Terraform or your Terraform Enterprise instance, you can:

Make sure the hostname matches the hostname you use in provider and module sources because if the same HCP Terraform 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.

Edit this page on GitHub