terraform Learn to prepare private modules for publishing add them to the registry and page title Publishing Private Modules Private Registry HCP Terraform Publishing Private Modules to the HCP Terraform Private Registry vcs terraform cloud docs vcs release new versions

Answer:
---
page_title: Publishing Private Modules - Private Registry - HCP Terraform
description: >-
  Learn to prepare private modules for publishing, add them to the registry, and
  release new versions.
---

[vcs]: /terraform/cloud-docs/vcs

# Publishing Private Modules to the HCP Terraform Private Registry

> **Hands-on:** Try the [Share Modules in the Private Module Registry](/terraform/tutorials/modules/module-private-registry-share) tutorial.

In addition to [adding modules from the Terraform Registry](/terraform/cloud-docs/registry/add), you can publish private modules to an organization's HCP Terraform private registry. The registry handles downloads and controls access with HCP Terraform API tokens, so consumers do not need access to the module's source repository, even when running Terraform from the command line.

The private registry uses your configured [Version Control System (VCS) integrations][vcs] and defers to your VCS provider for most management tasks. For example, your VCS provider handles new version releases. The only manual tasks are adding a new module and deleting module versions.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

## Permissions

Private modules are only available to members of the organization where you add them. In Terraform Enterprise, they are also available to organizations that you configure to [share modules](/terraform/enterprise/admin/application/registry-sharing) with that organization.

Members of the [owners team](/terraform/cloud-docs/users-teams-organizations/permissions#organization-owners) and teams with [Manage Private Registry permissions](/terraform/cloud-docs/users-teams-organizations/permissions#manage-private-registry) can publish and delete modules from the private registry.

## Preparing a Module Repository

After you configure at least one [connection to a VCS provider][vcs], you can publish a new module by specifying a properly formatted VCS repository (details below). The registry automatically detects the rest of the information it needs, including the module's name and its available versions.

A module repository must meet all of the following requirements before you can add it to the registry:

- **Location and permissions:** The repository must be in one of
  your configured [VCS providers][vcs], and HCP Terraform's VCS user account must have admin access to the repository. The registry needs admin access to create the webhooks to import new module versions. GitLab repositories must be in the main organization or group, and not in any subgroups.

- **Named `terraform-<PROVIDER>-<NAME>`:** Module repositories must use this
  three-part name format, where `<NAME>` reflects the type of infrastructure
  the module manages and `<PROVIDER>` is the main provider where it creates that
  infrastructure. The `<PROVIDER>` segment must be all lowercase. The `<NAME>`
  segment can contain additional hyphens. Examples: `terraform-google-vault` or
  `terraform-aws-ec2-instance`.

- **Standard module structure:** The module must adhere to the
  [standard module structure](/terraform/language/modules/develop/structure).
  This allows the registry to inspect your module and generate documentation,
  track resource usage, and more.

## Publishing a New Module

You can publish modules through the UI as shown below or with the [Registry Modules API](/terraform/cloud-docs/api-docs/private-registry/modules). The API also supports publishing modules without a VCS repo as the source, which is not possible in the UI.

To publish a new module:

  1. Click **Registry**. The **Registry** page appears.

  1. Click **Publish** and select **Module**.

    The **Add Module** page appears with a list of available repositories.

  1. Select the repository containing the module you want to publish.

    You can search the list by typing part or all of a repository name into the filter field. Remember that VCS providers use `<NAMESPACE>/<REPO NAME>` strings to locate repositories. The namespace is an organization name for most providers, but Bitbucket Data Center, not Bitbucket Cloud, uses project keys, like `INFRA`.

  1. When prompted, choose either the **Tag** or **Branch** module publishing type.

  1.  (Optional) If this module is a [no-code ready module](/terraform/cloud-docs/no-code-provisioning/module-design), select the **Add Module to no-code provision allowlist** checkbox.

  1.  Click **Publish module**.

    HCP Terraform displays a loading page while it imports the module versions and then takes you to the new module's details page. On the details page, you can view available versions, read documentation, and copy a usage example.

<!-- BEGIN: TFC:only name:pnp-callout -->
@include 'tfc-package-callouts/nocode.mdx'
<!-- END: TFC:only name:pnp-callout -->

### Tag-based publishing considerations

When using the **Tag** module publishing type, the registry uses `x.y.z` formatted release tags to identify module versions. Your repository must contain at least one release tag for you to publish a module. Release tag names must be a [semantic version](http://semver.org), which you can optionally prefix with a `v`. For example, `v1.0.4` and `0.9.2`. The registry ignores tags that do not match these formats.

<!-- BEGIN: TFC:only name:branch-based-publishing -->

### Branch-based publishing considerations

When using the **Branch** module publishing type, you must provide the name of an existing branch in your VCS repository and give the module a **Module version**. Your VCS repository does not need to contain a matching tag or release.

You can only enable testing on modules published using branch-based publishing. Refer to the [test-integrated modules](/terraform/cloud-docs/registry/test) documentation for more information.

<!-- END: TFC:only name:branch-based-publishing -->

## Releasing New Versions of a Module

<!-- BEGIN: TFC:only name:branch-based-publishing -->

The process to release a new module version differs between the tag-based and branch-based publishing workflows.

### Tag-Based Publishing Workflow

<!-- END: TFC:only name:branch-based-publishing -->

To release a new version of a module in the tag-based publishing workflow, push a new release tag to its VCS repository. The registry automatically imports the new version.

Refer to [Preparing a Module Repository](#preparing-a-module-repository) for details about release tag requirements.

<!-- BEGIN: TFC:only name:branch-based-publishing -->

### Branch-Based Publishing Workflow

To release a new version of a module using the branch-based publishing workflow, navigate to the module overview screen, then click the **Publish New Version** button. Select the commit SHA that the new version will point to, and assign a new module version. You cannot re-use an existing module version.

## Update Publish Settings

After publishing your module, you can change between tag-based and branch-based publishing. To update your module's publish settings, navigate to the the module overview page, click the **Manage Module for Organization** dropdown, and then click **Publish Settings**.

- To change from tag-based to branch-based publishing, you must configure a **Module branch** and [create a new module version](#branch-based-publishing-workflow), as HCP Terraform will not automatically create one.

- To change from branch-based publishing to tag-based publishing, you must create at least one tag in your VCS repository.

<!-- END: TFC:only name:branch-based-publishing -->

## Deleting Versions and Modules

-> **Note:** Deleting a tag from your VCS repository does not automatically remove the version from the private registry.

You can delete individual versions of a module or the entire module. If deleting a module version would leave a module with no versions, HCP Terraform removes the entire module. To delete a module or version:

1. Navigate to the module's details page.

1. If you want to delete a single version, use the **Versions** menu to select it.

1. Click **Delete module**.

1. Select an action from the menu:

   - **Delete only this module version:** Deletes only the version of the module you were viewing when you clicked **Delete module**.
   - **Delete all versions for this provider for this module:** Deletes the entire module for a single provider. This action is important if you have modules with the same name but with different providers. For example, if you have module repos named `terraform-aws-appserver` and `terraform-azure-appserver`, the registry treats them as alternate providers of the same `appserver` module.
   - **Delete all providers and versions for this module:** Deletes all modules with this name, even if they are from different providers. For example, this action deletes both `terraform-aws-appserver` and `terraform-azure-appserver`.

1. Type the module name and click **Delete**.

### Restoring a Deleted Module or Version

Deletion is permanent, but there are ways to restore deleted modules and module versions.

- To restore a deleted module, re-add it as a new module.
- To restore a deleted version, either delete the corresponding tag from your VCS and push a new tag with the same name, or delete the entire module from the registry and re-add it.

## Sharing Modules Across Organizations

HCP Terraform does not typically allow one organization's workspaces to use private modules from a different organization. This restriction is because HCP Terraform gives Terraform temporary credentials to access modules that are only valid for that workspace's organization. Although it is possible to mix modules from multiple organizations when you run Terraform on the command line, we strongly recommend against it.

Instead, you can share modules across organizations by sharing the underlying VCS repository. Grant each organization access to the module's repository, and then add the module to each organization's registry. When you push tags to publish new module versions, both organizations update accordingly.

Terraform Enterprise administrators can configure [module sharing](/terraform/enterprise/admin/application/registry-sharing) to allow organizations to use private modules from other organizations.

## Generating Module Tests (Beta)

You can generate and run generated tests for your module with [the `terraform test` command](/terraform/cli/commands/test).

Before you can generate tests for a module, it must have at least one version published. Tests can only be generated once per module and are intended to be reviewed by the module's authors before being checked into version control and maintained with the rest of the module's content. If the module's configuration files exceed 128KB in total size, HCP Terraform will not be able to generate tests for that module.

You must have [permission to manage registry modules](/terraform/cloud-docs/users-teams-organizations/permissions#manage-private-registry) and [permission to manage module test generation](/terraform/cloud-docs/users-teams-organizations/permissions#manage-module-test-generation-beta) to generate tests.

page title  Publishing Private Modules   Private Registry   HCP Terraform description       Learn to prepare private modules for publishing  add them to the registry  and   release new versions        vcs    terraform cloud docs vcs    Publishing Private Modules to the HCP Terraform Private Registry      Hands on    Try the  Share Modules in the Private Module Registry   terraform tutorials modules module private registry share  tutorial   In addition to  adding modules from the Terraform Registry   terraform cloud docs registry add   you can publish private modules to an organization s HCP Terraform private registry  The registry handles downloads and controls access with HCP Terraform API tokens  so consumers do not need access to the module s source repository  even when running Terraform from the command line   The private registry uses your configured  Version Control System  VCS  integrations  vcs  and defers to your VCS provider for most management tasks  For example  your VCS provider handles new version releases  The only manual tasks are adding a new module and deleting module versions    permissions citation    intentionally unused   keep for maintainers     Permissions  Private modules are only available to members of the organization where you add them  In Terraform Enterprise  they are also available to organizations that you configure to  share modules   terraform enterprise admin application registry sharing  with that organization   Members of the  owners team   terraform cloud docs users teams organizations permissions organization owners  and teams with  Manage Private Registry permissions   terraform cloud docs users teams organizations permissions manage private registry  can publish and delete modules from the private registry       Preparing a Module Repository  After you configure at least one  connection to a VCS provider  vcs   you can publish a new module by specifying a properly formatted VCS repository  details below   The registry automatically detects the rest of the information it needs  including the module s name and its available versions   A module repository must meet all of the following requirements before you can add it to the registry       Location and permissions    The repository must be in one of   your configured  VCS providers  vcs   and HCP Terraform s VCS user account must have admin access to the repository  The registry needs admin access to create the webhooks to import new module versions  GitLab repositories must be in the main organization or group  and not in any subgroups       Named  terraform  PROVIDER   NAME      Module repositories must use this   three part name format  where   NAME   reflects the type of infrastructure   the module manages and   PROVIDER   is the main provider where it creates that   infrastructure  The   PROVIDER   segment must be all lowercase  The   NAME     segment can contain additional hyphens  Examples   terraform google vault  or    terraform aws ec2 instance        Standard module structure    The module must adhere to the    standard module structure   terraform language modules develop structure     This allows the registry to inspect your module and generate documentation    track resource usage  and more      Publishing a New Module  You can publish modules through the UI as shown below or with the  Registry Modules API   terraform cloud docs api docs private registry modules   The API also supports publishing modules without a VCS repo as the source  which is not possible in the UI   To publish a new module     1  Click   Registry    The   Registry   page appears     1  Click   Publish   and select   Module         The   Add Module   page appears with a list of available repositories     1  Select the repository containing the module you want to publish       You can search the list by typing part or all of a repository name into the filter field  Remember that VCS providers use   NAMESPACE   REPO NAME   strings to locate repositories  The namespace is an organization name for most providers  but Bitbucket Data Center  not Bitbucket Cloud  uses project keys  like  INFRA      1  When prompted  choose either the   Tag   or   Branch   module publishing type     1    Optional  If this module is a  no code ready module   terraform cloud docs no code provisioning module design   select the   Add Module to no code provision allowlist   checkbox     1   Click   Publish module         HCP Terraform displays a loading page while it imports the module versions and then takes you to the new module s details page  On the details page  you can view available versions  read documentation  and copy a usage example        BEGIN  TFC only name pnp callout      include  tfc package callouts nocode mdx       END  TFC only name pnp callout          Tag based publishing considerations  When using the   Tag   module publishing type  the registry uses  x y z  formatted release tags to identify module versions  Your repository must contain at least one release tag for you to publish a module  Release tag names must be a  semantic version  http   semver org   which you can optionally prefix with a  v   For example   v1 0 4  and  0 9 2   The registry ignores tags that do not match these formats        BEGIN  TFC only name branch based publishing          Branch based publishing considerations  When using the   Branch   module publishing type  you must provide the name of an existing branch in your VCS repository and give the module a   Module version    Your VCS repository does not need to contain a matching tag or release   You can only enable testing on modules published using branch based publishing  Refer to the  test integrated modules   terraform cloud docs registry test  documentation for more information        END  TFC only name branch based publishing         Releasing New Versions of a Module       BEGIN  TFC only name branch based publishing      The process to release a new module version differs between the tag based and branch based publishing workflows       Tag Based Publishing Workflow       END  TFC only name branch based publishing      To release a new version of a module in the tag based publishing workflow  push a new release tag to its VCS repository  The registry automatically imports the new version   Refer to  Preparing a Module Repository   preparing a module repository  for details about release tag requirements        BEGIN  TFC only name branch based publishing          Branch Based Publishing Workflow  To release a new version of a module using the branch based publishing workflow  navigate to the module overview screen  then click the   Publish New Version   button  Select the commit SHA that the new version will point to  and assign a new module version  You cannot re use an existing module version      Update Publish Settings  After publishing your module  you can change between tag based and branch based publishing  To update your module s publish settings  navigate to the the module overview page  click the   Manage Module for Organization   dropdown  and then click   Publish Settings       To change from tag based to branch based publishing  you must configure a   Module branch   and  create a new module version   branch based publishing workflow   as HCP Terraform will not automatically create one     To change from branch based publishing to tag based publishing  you must create at least one tag in your VCS repository        END  TFC only name branch based publishing         Deleting Versions and Modules       Note    Deleting a tag from your VCS repository does not automatically remove the version from the private registry   You can delete individual versions of a module or the entire module  If deleting a module version would leave a module with no versions  HCP Terraform removes the entire module  To delete a module or version   1  Navigate to the module s details page   1  If you want to delete a single version  use the   Versions   menu to select it   1  Click   Delete module     1  Select an action from the menu          Delete only this module version    Deletes only the version of the module you were viewing when you clicked   Delete module           Delete all versions for this provider for this module    Deletes the entire module for a single provider  This action is important if you have modules with the same name but with different providers  For example  if you have module repos named  terraform aws appserver  and  terraform azure appserver   the registry treats them as alternate providers of the same  appserver  module         Delete all providers and versions for this module    Deletes all modules with this name  even if they are from different providers  For example  this action deletes both  terraform aws appserver  and  terraform azure appserver    1  Type the module name and click   Delete         Restoring a Deleted Module or Version  Deletion is permanent  but there are ways to restore deleted modules and module versions     To restore a deleted module  re add it as a new module    To restore a deleted version  either delete the corresponding tag from your VCS and push a new tag with the same name  or delete the entire module from the registry and re add it      Sharing Modules Across Organizations  HCP Terraform does not typically allow one organization s workspaces to use private modules from a different organization  This restriction is because HCP Terraform gives Terraform temporary credentials to access modules that are only valid for that workspace s organization  Although it is possible to mix modules from multiple organizations when you run Terraform on the command line  we strongly recommend against it   Instead  you can share modules across organizations by sharing the underlying VCS repository  Grant each organization access to the module s repository  and then add the module to each organization s registry  When you push tags to publish new module versions  both organizations update accordingly   Terraform Enterprise administrators can configure  module sharing   terraform enterprise admin application registry sharing  to allow organizations to use private modules from other organizations      Generating Module Tests  Beta   You can generate and run generated tests for your module with  the  terraform test  command   terraform cli commands test    Before you can generate tests for a module  it must have at least one version published  Tests can only be generated once per module and are intended to be reviewed by the module s authors before being checked into version control and maintained with the rest of the module s content  If the module s configuration files exceed 128KB in total size  HCP Terraform will not be able to generate tests for that module   You must have  permission to manage registry modules   terraform cloud docs users teams organizations permissions manage private registry  and  permission to manage module test generation   terraform cloud docs users teams organizations permissions manage module test generation beta  to generate tests


terraform page title Publishing Private Providers Private Registry In addition to curating public providers from the Terraform Registry terraform cloud docs registry add you can publish private providers to an organization s HCP Terraform private registry Once you have published a private provider through the API members of your organization can search for it in the private registry UI and use it in configurations and release new versions Publishing private providers to the HCP Terraform private registry Prepare private providers for publishing add them to the private registry

page title  Publishing Private Providers   Private Registry description       Prepare private providers for publishing  add them to the private registry    and release new versions         Publishing private providers to the HCP Terraform private registry  In addition to  curating public providers from the Terraform Registry   terraform cloud docs registry add   you can publish private providers to an organization s HCP Terraform private registry  Once you have published a private provider through the API  members of your organization can search for it in the private registry UI and use it in configurations       Requirements  Review the following before publishing a new provider or provider version       Permissions  Users must be members of an organization to access its registry and private providers  In Terraform Enterprise  providers are also available to organizations that you configure to  share registry access   terraform enterprise admin application registry sharing    You must be a member of the  owners team   terraform cloud docs users teams organizations permissions organization owners  or a team with  Manage Private Registry permissions   terraform cloud docs users teams organizations permissions manage private registry  to publish and delete private providers from the private registry       Release files  You must publish at least one version of your provider that follows  semantic versioning format  http   semver org   For each version  you must upload the  SHA256SUMS  file   SHA256SUMS sig  file  and one or more provider binaries  Using GoReleaser to  create a release on GitHub   terraform registry providers publishing creating a github release  or  create a release locally   terraform registry providers publishing using goreleaser locally  generates these files automatically  The private registry does not have strict naming conventions  but we recommend using GoReleaser file naming schemes for consistency   Private providers do not currently support documentation       Signed releases  GPG signing is required for private providers  and you must upload the public key of the GPG keypair used to sign the release  Refer to  Preparing and Adding a Signing Key   terraform registry providers publishing preparing and adding a signing key  for more details  Unlike the public Terraform Registry  the private registry does not automatically upload new releases  You must manually add new provider versions and the associated release files        Note    If you are using the  provider API   terraform cloud docs api docs private registry providers  to upload an official HashiCorp public provider into your private registry  use  HashiCorp s public PGP key  https   www hashicorp com  well known pgp key txt   You do not need to upload this public key  and it is automatically included in Terraform Enterprise version v202309 1 and newer      Publishing a provider  Before consumers can use a private provider  you must do the following  1   Create the provider   create the provider  2   Upload a GPG signing key   add your public key  3   Create at least one version   create a version  4   Create at least one platform for that version   create a provider platform  5   Upload release files   upload provider binary       Create the provider  Create a file named  provider json  with the following contents  Replace  PROVIDER NAME  with the name of your provider and replace  ORG NAME  with the name of your organization      json      data          type    registry providers        attributes            name    PROVIDER NAME          namespace    ORG NAME          registry name    private                   Use the  Create a Provider endpoint   terraform cloud docs api docs private registry providers create a provider  to create the provider in HCP Terraform  Replace  TOKEN  in the  Authorization  header with your HCP Terraform API token and replace  ORG NAME  with the name of your organization      shell session   curl       header  Authorization  Bearer  TOKEN        header  Content Type  application vnd api json        request POST       data  provider json     https   app terraform io api v2 organizations ORG NAME registry providers      The provider is now available in your organization s HCP Terraform private registry  but consumers cannot use it until you add a version and a platform    To create a version and a platform  you need the following resources    The Provider binaries   A public GPG signing key   A  SHA256SUMS  file   A  SHA256SUMS sig  file from at least one release       Add your public key       Note    If you are uploading an official HashiCorp public provider into your private registry  skip this step and instead use  HashiCorp s public PGP key  https   www hashicorp com  well known pgp key txt  in the the  create a version   create a version  step  The key ID for HashiCorp s public ID is  34365D9472D7468F   and you can verify the ID by  importing the public key locally   terraform tutorials cli verify archive download and import hashicorp s public key    Create a file named  key json  with the following contents  Replace  ORG NAME  with the name of your organization and supply your public key in the  ascii armor  field      hcl      data          type    gpg keys        attributes            namespace    ORG NAME          ascii armor         BEGIN PGP PUBLIC KEY BLOCK      n nmQINB    txfz n     END PGP PUBLIC KEY BLOCK      n                  Use the  Add a GPG key endpoint   terraform cloud docs api docs private registry gpg keys add a gpg key  to add the public key that matches the signing key for the release  Replace  TOKEN  in the  Authorization  header with your HCP Terraform API token      shell session   curl       header  Authorization  Bearer  TOKEN        header  Content Type  application vnd api json        request POST       data  key json     https   app terraform io api registry private v2 gpg keys      The response contains a  key id  that you will use to create a provider version      json  key id    34365D9472D7468F           Create a version  Create a file named  version json  with the following contents  Replace the value of the  version  field with the version of your provider  and replace the  key id  field with the id of the GPG key that you created in the  Add your public key   add your public key  step  If you are uploading an official HashiCorp public provider  use the value  34365D9472D7468F  for your  key id       hcl      data          type    registry provider versions        attributes            version    5 14 0          key id    34365D9472D7468F          protocols     5 0                    Use the  Create a Provider Version endpoint   terraform cloud docs api docs private registry provider versions platforms create a provider version  to create a version for your provider  Replace  TOKEN  in the  Authorization  header with your HCP Terraform API token  and replace both instances of  ORG NAME  with the name of your organization  If are not using the  aws  provider  then replace  aws  with your provider s name      shell session   curl       header  Authorization  Bearer  TOKEN        header  Content Type  application vnd api json        request POST       data  version json     https   app terraform io api v2 organizations ORG NAME registry providers private ORG NAME aws versions       The response includes URL links that you will use to upload the  SHA256SUMS  and  SHA256 sig  files      json  links          shasums upload        https   archivist terraform io v1 object dmF1b64hd73ghd63        shasums sig upload    https   archivist terraform io v1 object dmF1b37dj37dh33d               Upload signatures  Upload the  SHA256SUMS  and  SHA256SUMS sig  files to the URLs  returned in the previous step   create a version   The example command below uploads the files from your local machine  First upload the  SHA256SUMS  file to the URL returned in the  shasums upload  field      shell session   curl      T terraform provider aws 5 14 0 SHA256SUMS     https   archivist terraform io v1 object dmF1b64hd73ghd63         Next  upload the  SHA256SUMS sig  file to the URL returned in the  shasums sig upload  field      shell session   curl      T terraform provider aws 5 14 0 SHA256SUMS 72D7468F sig     https   archivist terraform io v1 object dmF1b37dj37dh33d             Create a provider platform  First  calculate the SHA256 hash of the provider binary that you intend to upload  This should match the SHA256 hash of the file listed in the  SHA256SUMS  file      shell session   shasum  a 256 terraform provider aws 5 14 0 linux amd64 zip f1d83b3e5a29bae471f9841a4e0153eac5bccedbdece369e2f6186e9044db64e  terraform provider aws 5 14 0 linux amd64 zip      Next  create a file named  platform json   Replace the  os    arch    filename   and  shasum  fields with the values that match the provider you intend to upload       json      data          type    registry provider version platforms        attributes            os    linux          arch    amd64          shasum    f1d83b3e5a29bae471f9841a4e0153eac5bccedbdece369e2f6186e9044db64e          filename    terraform provider aws 5 14 0 linux amd64 zip                   Use the  Create a Provider Platform endpoint   terraform cloud docs api docs private registry provider versions platforms create a provider platform  to create a platform for the version  Platforms are binaries that allow the provider to run on a particular operating system and architecture combination  e g   Linux and AMD64    Replace  TOKEN  in the  Authorization  header with your HCP Terraform API token and replace both instances of  ORG NAME  with the name of your organization      shell session   curl       header  Authorization  Bearer  TOKEN        header  Content Type  application vnd api json        request POST       data  platform json     https   app terraform io api v2 organizations ORG NAME registry providers private ORG NAME aws versions 5 14 0 platforms      The response includes a  provider binary upload  URL that you will use to upload the binary file for the platform      json  links            provider binary upload    https   archivist terraform io v1 object dmF1b45c367djh45nj78                 Upload provider binary  Upload the platform binary file to the  provider binary upload  URL returned in the  previous step   create a version   The example command below uploads the binary from your local machine      shell session   curl  T local example terraform provider random 5 14 0 linux amd64 zip   https   archivist terraform io v1 object dmF1b45c367djh45nj78      The version is available in the HCP Terraform user interface  Consumers can now begin using this provider version in configurations  You can repeat these steps starting from  Create a provider platform   create a provider platform  to add additional platform binaries for the release      Checking Release Files  Consumers cannot use a private provider version until you upload all required  release files   release files   To determine whether these files have been uploaded   1  Click   Registry   and click the private provider to go to its details page  1  Use the version menu to navigate to the version you want to check  The UI shows a warning banner for versions that do not have all required release files  1  Open the   Manage Provider   menu and select   Show release files    The   Release Files   page appears containing lists of uploaded and missing files for the current version       Managing private providers  Use the HCP Terraform API to create  read  update  and delete the following      GPG keys   terraform cloud docs api docs private registry gpg keys     Private providers   terraform cloud docs api docs private registry providers     Provider versions and platforms   terraform cloud docs api docs private registry provider versions platforms      Deleting private providers and versions  In addition to the  Registry Providers API   terraform cloud docs api docs private registry providers delete a provider   you can delete providers and provider versions through the HCP Terraform UI  To delete providers and versions in the UI   1  Click   Registry   and click the private provider to go to its details page  1  If you want to delete a single version  use the   Versions   menu to select it  1  Open the   Manage Provider   menu and select   Delete Provider    The   Delete Provider from Organization   box appears  1  Select an action from the menu           Delete only this provider version    Deletes only the version of the provider you are currently viewing          Delete all versions for this provider    Deletes the entire provider and all associated versions   1  Type the provider name into the confirmation box and click   Delete     The provider version or entire provider has been deleted from this organization s private registry and its data has been removed  Consumers will no longer be able to reference it in configurations       Restoring a deleted provider  Deletion is permanent  but you can restore a deleted private provider by re adding it to your organization and recreating its versions and platforms


terraform Location Search for providers modules and usage examples in the HCP Terraform private registry UI 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 terraform registry Using Providers and Modules from the Private Registry Find available providers and modules and include them in configurations page title Using Providers and Modules Private Module Registry HCP Terraform

Answer:
---
page_title: Using Providers and Modules - Private Module Registry - HCP Terraform
description: Find available providers and modules and include them in configurations.
---

# Using Providers and Modules from the 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](/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/cloud-docs/registry/using#using-private-providers-and-modules-in-configurations).
- **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](/terraform/cloud-docs/registry/using#authentication) 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](/terraform/cloud-docs/no-code-provisioning/provisioning).

## 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 - Terraform Enterprise

On Terraform Enterprise, your [registry sharing](/terraform/enterprise/admin/application/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](/terraform/cloud-docs/no-code-provisioning/provisioning) for details.

## Using Public Providers and Modules in Configurations

> **Hands-on:** Try the [Use Modules from the Registry](/terraform/tutorials/modules/module-use) tutorial.

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](/terraform/language/providers/configuration#provider-configuration-1) `source` argument is `<NAMESPACE>/<PROVIDER_NAME>`.

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

The syntax for referencing public modules in the [module block](/terraform/language/modules/syntax) `source` argument is `<NAMESPACE>/<MODULE_NAME>/<PROVIDER_NAME>`.

```hcl
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](/terraform/language/providers/configuration#provider-configuration-1) `source` argument is `<HOSTNAME>/<NAMESPACE>/<PROVIDER_NAME>`. For the SaaS version of HCP Terraform, the hostname is `app.terraform.io`.

```hcl
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](/terraform/language/modules/syntax) `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](/terraform/cloud-docs/registry/using#generic-hostname-terraform-enterprise).
- **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.

```hcl
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.

```hcl
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.

### 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:

- **HCP Terraform:** [Add providers and modules to the registry](/terraform/cloud-docs/registry/publish-modules#sharing-modules-across-organizations) for each organization that requires access.

- **Terraform Enterprise:** Check your site's [registry sharing](/terraform/enterprise/admin/application/registry-sharing) configuration. Workspaces can also use private providers and modules from organizations that are sharing with the workspace's organization.

## Running Configurations with Private Providers and Modules

### 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.

### Authentication

To authenticate with HCP Terraform, you can use either a [user token](/terraform/cloud-docs/users-teams-organizations/users#api-tokens) or a [team token](/terraform/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens). 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](/terraform/enterprise/saml/login#api-token-expiration), requiring you to periodically re-authenticate through the web UI. Expired tokens produce a _401 Unauthorized_ error. A SAML SSO account with [IsServiceAccount](/terraform/enterprise/saml/attributes#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:

- (Terraform 0.12.21 or later) Use the [`terraform login`](/terraform/cli/commands/login) command to obtain and save a user API token.
- Create a token and [manually configure credentials in the CLI config file][cli-credentials].

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.

[user-token]: /terraform/cloud-docs/users-teams-organizations/users#api-tokens

[cli-credentials]: /terraform/cli/config/config-file#credentials

[permissions-citation]: #intentionally-unused---keep-for-maintainers

page title  Using Providers and Modules   Private Module Registry   HCP Terraform description  Find available providers and modules and include them in configurations          Using Providers and Modules from the 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   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 cloud docs registry using using private providers and modules in configurations       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   terraform cloud docs registry using authentication  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   terraform cloud docs no code provisioning provisioning       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   Terraform Enterprise  On Terraform Enterprise  your  registry sharing   terraform enterprise admin application 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   terraform cloud docs no code provisioning provisioning  for details      Using Public Providers and Modules in Configurations      Hands on    Try the  Use Modules from the Registry   terraform tutorials modules module use  tutorial   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   terraform language providers configuration provider configuration 1   source  argument is   NAMESPACE   PROVIDER NAME        hcl terraform     required providers       google           source    hashicorp google        version    4 0 0                 The syntax for referencing public modules in the  module block   terraform language modules syntax   source  argument is   NAMESPACE   MODULE NAME   PROVIDER NAME        hcl 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   terraform language providers configuration provider configuration 1   source  argument is   HOSTNAME   NAMESPACE   PROVIDER NAME    For the SaaS version of HCP Terraform  the hostname is  app terraform io       hcl 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   terraform language modules syntax   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   terraform cloud docs registry using generic hostname terraform enterprise       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      hcl 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      hcl 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       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       HCP Terraform     Add providers and modules to the registry   terraform cloud docs registry publish modules sharing modules across organizations  for each organization that requires access       Terraform Enterprise    Check your site s  registry sharing   terraform enterprise admin application registry sharing  configuration  Workspaces can also use private providers and modules from organizations that are sharing with the workspace s organization      Running Configurations with Private Providers and Modules      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        Authentication  To authenticate with HCP Terraform  you can use either a  user token   terraform cloud docs users teams organizations users api tokens  or a  team token   terraform cloud docs users teams organizations api tokens team api tokens   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   terraform enterprise saml login api token expiration   requiring you to periodically re authenticate through the web UI  Expired tokens produce a  401 Unauthorized  error  A SAML SSO account with  IsServiceAccount   terraform enterprise saml attributes 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      Terraform 0 12 21 or later  Use the   terraform login    terraform cli commands login  command to obtain and save a user API token    Create a token and  manually configure credentials in the CLI config file  cli credentials    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    user token    terraform cloud docs users teams organizations users api tokens   cli credentials    terraform cli config config file credentials   permissions citation    intentionally unused   keep for maintainers


terraform We recommend that you test your Sentinel policies extensively before deploying page title Mocking Terraform Sentinel Data Sentinel HCP Terraform Learn how to use the UI or API to generate mock Sentinel data and how to use Mocking Terraform Sentinel Data that data for testing

Answer:
---
page_title: Mocking Terraform Sentinel Data - Sentinel - HCP Terraform
description: >-
  Learn how to use the UI or API to generate mock Sentinel data and how to use
  that data for testing.
---

# Mocking Terraform Sentinel Data

We recommend that you test your Sentinel policies extensively before deploying
them within HCP Terraform. An important part of this process is mocking
the data that you wish your policies to operate on.

<!-- BEGIN: TFC:only name:pnp-callout -->
@include 'tfc-package-callouts/policies.mdx'
<!-- END: TFC:only name:pnp-callout -->

Due to the highly variable structure of data that can be produced by an
individual Terraform configuration, HCP Terraform provides the ability to
generate mock data from existing configurations. This can be used to create
sample data for a new policy, or data to reproduce issues in an existing one.

Testing policies is done using the [Sentinel
CLI](https://docs.hashicorp.com/sentinel/commands). More general information on
testing Sentinel policies can be found in the [Testing
section](https://docs.hashicorp.com/sentinel/writing/testing) of the [Sentinel
runtime documentation](https://docs.hashicorp.com/sentinel).

~> **Be careful!** Mock data generated by HCP Terraform directly exposes any
and all data within the configuration, plan, and state. Terraform attempts to
scrub sensitive data from these mocks, but we do not guarantee 100% accuracy.
Treat this data with care, and avoid generating mocks with live sensitive data
when possible. Access to this information requires [permission to download
Sentinel mocks](/terraform/cloud-docs/users-teams-organizations/permissions) for the
workspace where the data was generated.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

## Generating Mock Data Using the UI

Mock data can be generated using the UI by expanding the plan status section of
the run page, and clicking on the **Download Sentinel mocks** button.

![sentinel mock generate ui](/img/docs/download-mocks.png)

For more information on creating a run, see the
[Terraform Runs and Remote Operations](/terraform/cloud-docs/run/remote-operations) section of the docs.

If the button is not visible, then the plan is ineligible for mock generation or
the user doesn't have the necessary permissions. See [Mock Data
Availability](#mock-data-availability) for more details.

## Generating Mock Data Using the API

Mock data can also be created with the [Plan Export
API](/terraform/cloud-docs/api-docs/plan-exports).

Multiple steps are required for mock generation. The export process is
asynchronous, so you must monitor the request to know when the data is generated
and available for download.

1. Get the plan ID for the run that you want to generate the mock for by
   [getting the run details](/terraform/cloud-docs/api-docs/run#get-run-details).
   Look for the `id` of the `plan` object within the `relationships` section of
   the return data.
1. [Request a plan
   export](/terraform/cloud-docs/api-docs/plan-exports#create-a-plan-export) using the
   discovered plan ID. Supply the Sentinel export type `sentinel-mock-bundle-v0`.
1. Monitor the export request by [viewing the plan
   export](/terraform/cloud-docs/api-docs/plan-exports#show-a-plan-export). When the
   status is `finished`, the data is ready for download.
1. Finally, [download the export
   data](/terraform/cloud-docs/api-docs/plan-exports#download-exported-plan-data).
   You have up to an hour from the completion of the export request - after
   that, the mock data expires and must be re-generated.

## Using Mock Data

-> **Note:** The v2 mock files are only available on Terraform 0.12 and higher.

Mock data is supplied as a bundled tarball, containing the following files:

```
mock-tfconfig.sentinel    # tfconfig mock data
mock-tfconfig-v2.sentinel # tfconfig/v2 mock data
mock-tfplan.sentinel      # tfplan mock data
mock-tfplan-v2.sentinel   # tfplan/v2 mock data
mock-tfstate.sentinel     # tfstate mock data
mock-tfstate-v2.sentinel  # tfstate/v2 mock data
mock-tfrun.sentinel       # tfrun mock data
sentinel.hcl              # sample configuration file
```

The sample `sentinel.hcl` file contains mappings to the mocks so that you
can get started testing with `sentinel apply` right away. For `sentinel test`,
however, we recommend a more detailed layout.

We recommend placing the files for `sentinel test` in a subdirectory
of the repository holding your policies, so they don't interfere with the
command's automatic policy detection. While the test data is Sentinel code, it's
not a policy and will produce errors if evaluated like one.

```
.
├── foo.sentinel
├── sentinel.hcl
├── test
│   └── foo
│       ├── fail.hcl
│       └── pass.hcl
└── testdata
    ├── mock-tfconfig.sentinel
    ├── mock-tfconfig-v2.sentinel
    ├── mock-tfplan.sentinel
    ├── mock-tfplan-v2.sentinel
    ├── mock-tfstate.sentinel
    ├── mock-tfstate-v2.sentinel
    └── mock-tfrun.sentinel
```

Each configuration that needs access to the mock should reference the mock data
files within the `mock` block in the Sentinel configuration file.

For `sentinel apply`, this path is relative to the working directory. Assuming
you always run this command from the repository root, the `sentinel.hcl`
configuration file would look like:

```hcl
mock "tfconfig" {
  module {
    source = "testdata/mock-tfconfig.sentinel"
  }
}

mock "tfconfig/v1" {
  module {
    source = "testdata/mock-tfconfig.sentinel"
  }
}

mock "tfconfig/v2" {
  module {
    source = "testdata/mock-tfconfig-v2.sentinel"
  }
}

mock "tfplan" {
  module {
    source = "testdata/mock-tfplan.sentinel"
  }
}

mock "tfplan/v1" {
  module {
    source = "testdata/mock-tfplan.sentinel"
  }
}

mock "tfplan/v2" {
  module {
    source = "testdata/mock-tfplan-v2.sentinel"
  }
}

mock "tfstate" {
  module {
    source = "testdata/mock-tfstate.sentinel"
  }
}

mock "tfstate/v1" {
  module {
    source = "testdata/mock-tfstate.sentinel"
  }
}

mock "tfstate/v2" {
  module {
    source = "testdata/mock-tfstate-v2.sentinel"
  }
}

mock "tfrun" {
  module {
    source = "testdata/mock-tfrun.sentinel"
  }
}
```

For `sentinel test`, the paths are relative to the specific test configuration
file. For example, the contents of `pass.hcl`, asserting that the result of the
`main` rule was `true`, would be:

```
mock "tfconfig" {
  module {
    source = "../../testdata/mock-tfconfig.sentinel"
  }
}

mock "tfconfig/v1" {
  module {
    source = "../../testdata/mock-tfconfig.sentinel"
  }
}

mock "tfconfig/v2" {
  module {
    source = "../../testdata/mock-tfconfig-v2.sentinel"
  }
}

mock "tfplan" {
  module {
    source = "../../testdata/mock-tfplan.sentinel"
  }
}

mock "tfplan/v1" {
  module {
    source = "../../testdata/mock-tfplan.sentinel"
  }
}

mock "tfplan/v2" {
  module {
    source = "../../testdata/mock-tfplan-v2.sentinel"
  }
}

mock "tfstate" {
  module {
    source = "../../testdata/mock-tfstate.sentinel"
  }
}

mock "tfstate/v1" {
  module {
    source = "../../testdata/mock-tfstate.sentinel"
  }
}

mock "tfstate/v2" {
  module {
    source = "../../testdata/mock-tfstate-v2.sentinel"
  }
}

mock "tfrun" {
  module {
    source = "../../testdata/mock-tfrun.sentinel"
  }
}

test {
  rules = {
    main = true
  }
}
```

## Mock Data Availability

The following factors can prevent you from generating mock data:

* You do not have permission to download Sentinel mocks for the workspace.
  ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))
  Permission is required to protect the possibly sensitive data which can be
  produced via mock generation.
* The run has not progressed past the planning stage, or did not create a plan
  successfully.
* The run progressed past the planning stage prior to July 23, 2021. Prior to this date, HCP Terraform only kept JSON plans for 7 days.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

If a plan cannot have its mock data exported due to any of these reasons, the
**Download Sentinel mocks** button within the plan status section of the UI will
not be visible.

-> **Note:** Only a successful plan is required for mock generation. Sentinel can still generate the data if apply or policy checks fail.

page title  Mocking Terraform Sentinel Data   Sentinel   HCP Terraform description       Learn how to use the UI or API to generate mock Sentinel data and how to use   that data for testing         Mocking Terraform Sentinel Data  We recommend that you test your Sentinel policies extensively before deploying them within HCP Terraform  An important part of this process is mocking the data that you wish your policies to operate on        BEGIN  TFC only name pnp callout      include  tfc package callouts policies mdx       END  TFC only name pnp callout      Due to the highly variable structure of data that can be produced by an individual Terraform configuration  HCP Terraform provides the ability to generate mock data from existing configurations  This can be used to create sample data for a new policy  or data to reproduce issues in an existing one   Testing policies is done using the  Sentinel CLI  https   docs hashicorp com sentinel commands   More general information on testing Sentinel policies can be found in the  Testing section  https   docs hashicorp com sentinel writing testing  of the  Sentinel runtime documentation  https   docs hashicorp com sentinel         Be careful    Mock data generated by HCP Terraform directly exposes any and all data within the configuration  plan  and state  Terraform attempts to scrub sensitive data from these mocks  but we do not guarantee 100  accuracy  Treat this data with care  and avoid generating mocks with live sensitive data when possible  Access to this information requires  permission to download Sentinel mocks   terraform cloud docs users teams organizations permissions  for the workspace where the data was generated    permissions citation    intentionally unused   keep for maintainers     Generating Mock Data Using the UI  Mock data can be generated using the UI by expanding the plan status section of the run page  and clicking on the   Download Sentinel mocks   button     sentinel mock generate ui   img docs download mocks png   For more information on creating a run  see the  Terraform Runs and Remote Operations   terraform cloud docs run remote operations  section of the docs   If the button is not visible  then the plan is ineligible for mock generation or the user doesn t have the necessary permissions  See  Mock Data Availability   mock data availability  for more details      Generating Mock Data Using the API  Mock data can also be created with the  Plan Export API   terraform cloud docs api docs plan exports    Multiple steps are required for mock generation  The export process is asynchronous  so you must monitor the request to know when the data is generated and available for download   1  Get the plan ID for the run that you want to generate the mock for by     getting the run details   terraform cloud docs api docs run get run details      Look for the  id  of the  plan  object within the  relationships  section of    the return data  1   Request a plan    export   terraform cloud docs api docs plan exports create a plan export  using the    discovered plan ID  Supply the Sentinel export type  sentinel mock bundle v0   1  Monitor the export request by  viewing the plan    export   terraform cloud docs api docs plan exports show a plan export   When the    status is  finished   the data is ready for download  1  Finally   download the export    data   terraform cloud docs api docs plan exports download exported plan data      You have up to an hour from the completion of the export request   after    that  the mock data expires and must be re generated      Using Mock Data       Note    The v2 mock files are only available on Terraform 0 12 and higher   Mock data is supplied as a bundled tarball  containing the following files       mock tfconfig sentinel      tfconfig mock data mock tfconfig v2 sentinel   tfconfig v2 mock data mock tfplan sentinel        tfplan mock data mock tfplan v2 sentinel     tfplan v2 mock data mock tfstate sentinel       tfstate mock data mock tfstate v2 sentinel    tfstate v2 mock data mock tfrun sentinel         tfrun mock data sentinel hcl                sample configuration file      The sample  sentinel hcl  file contains mappings to the mocks so that you can get started testing with  sentinel apply  right away  For  sentinel test   however  we recommend a more detailed layout   We recommend placing the files for  sentinel test  in a subdirectory of the repository holding your policies  so they don t interfere with the command s automatic policy detection  While the test data is Sentinel code  it s not a policy and will produce errors if evaluated like one             foo sentinel     sentinel hcl     test         foo             fail hcl             pass hcl     testdata         mock tfconfig sentinel         mock tfconfig v2 sentinel         mock tfplan sentinel         mock tfplan v2 sentinel         mock tfstate sentinel         mock tfstate v2 sentinel         mock tfrun sentinel      Each configuration that needs access to the mock should reference the mock data files within the  mock  block in the Sentinel configuration file   For  sentinel apply   this path is relative to the working directory  Assuming you always run this command from the repository root  the  sentinel hcl  configuration file would look like      hcl mock  tfconfig      module       source    testdata mock tfconfig sentinel         mock  tfconfig v1      module       source    testdata mock tfconfig sentinel         mock  tfconfig v2      module       source    testdata mock tfconfig v2 sentinel         mock  tfplan      module       source    testdata mock tfplan sentinel         mock  tfplan v1      module       source    testdata mock tfplan sentinel         mock  tfplan v2      module       source    testdata mock tfplan v2 sentinel         mock  tfstate      module       source    testdata mock tfstate sentinel         mock  tfstate v1      module       source    testdata mock tfstate sentinel         mock  tfstate v2      module       source    testdata mock tfstate v2 sentinel         mock  tfrun      module       source    testdata mock tfrun sentinel             For  sentinel test   the paths are relative to the specific test configuration file  For example  the contents of  pass hcl   asserting that the result of the  main  rule was  true   would be       mock  tfconfig      module       source          testdata mock tfconfig sentinel         mock  tfconfig v1      module       source          testdata mock tfconfig sentinel         mock  tfconfig v2      module       source          testdata mock tfconfig v2 sentinel         mock  tfplan      module       source          testdata mock tfplan sentinel         mock  tfplan v1      module       source          testdata mock tfplan sentinel         mock  tfplan v2      module       source          testdata mock tfplan v2 sentinel         mock  tfstate      module       source          testdata mock tfstate sentinel         mock  tfstate v1      module       source          testdata mock tfstate sentinel         mock  tfstate v2      module       source          testdata mock tfstate v2 sentinel         mock  tfrun      module       source          testdata mock tfrun sentinel         test     rules         main   true               Mock Data Availability  The following factors can prevent you from generating mock data     You do not have permission to download Sentinel mocks for the workspace      More about permissions    terraform cloud docs users teams organizations permissions     Permission is required to protect the possibly sensitive data which can be   produced via mock generation    The run has not progressed past the planning stage  or did not create a plan   successfully    The run progressed past the planning stage prior to July 23  2021  Prior to this date  HCP Terraform only kept JSON plans for 7 days    permissions citation    intentionally unused   keep for maintainers  If a plan cannot have its mock data exported due to any of these reasons  the   Download Sentinel mocks   button within the plan status section of the UI will not be visible        Note    Only a successful plan is required for mock generation  Sentinel can still generate the data if apply or policy checks fail