Publishing private providers to the Terraform Cloud private registry
In addition to curating public providers from the Terraform Registry, you can publish private providers to an organization's Terraform Cloud 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.
You must be a member of the owners team or a team with Manage Private Registry permissions 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. 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 or create a release 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 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 to upload an official HashiCorp public provider into your private registry, use HashiCorp's public PGP key. 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:
- Create the provider
- Upload a GPG signing key
- Create at least one version
- Create at least one platform for that version
- Upload release files
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.
Use the Create a Provider endpoint to create the provider in Terraform Cloud. Replace TOKEN
in the Authorization
header with your Terraform Cloud API token and replace ORG_NAME
with the name of your organization.
The provider is now available in your organization’s Terraform Cloud 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 in the the 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.
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.
Use the Add a GPG key endpoint to add the public key that matches the signing key for the release. Replace TOKEN
in the Authorization
header with your Terraform Cloud API token.
The response contains a key-id
that you will use to create a provider version.
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 step. If you are uploading an official HashiCorp public provider, use the value 34365D9472D7468F
for your key-id
.
Use the Create a Provider Version endpoint to create a version for your provider. Replace TOKEN
in the Authorization
header with your Terraform Cloud API token, and replace both instances of ORG_NAME
with the name of your organization.
The response includes URL links that you will use to upload the SHA256SUMS
and SHA256.sig
files.
Upload signatures
Upload the SHA256SUMS
and SHA256SUMS.sig
files to the URLs returned in the previous step. 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.
Next, upload the SHA256SUMS.sig
file to the URL returned in the shasums-sig-upload
field.
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.
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.
Use the Create a Provider Platform endpoint 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 Terraform Cloud API token and replace both instances of ORG_NAME
with the name of your organization.
The response includes a provider-binary-upload
URL that you will use to upload the binary file for the platform.
Upload provider binary
Upload the platform binary file to the provider-binary-upload
URL returned in the previous step. The example command below uploads the binary from your local machine.
The version is available in the Terraform Cloud user interface. Consumers can now begin using this provider version in configurations. You can repeat these steps starting from 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. To determine whether these files have been uploaded:
- Click Registry and click the private provider to go to its details page.
- 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.
- 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 Terraform Cloud API to create, read, update, and delete the following:
Deleting private providers and versions
In addition to the Registry Providers API, you can delete providers and provider versions through the Terraform Cloud UI. To delete providers and versions in the UI:
Click Registry and click the private provider to go to its details page.
If you want to delete a single version, use the Versions menu to select it.
Open the Manage Provider menu and select Delete Provider. The Delete Provider from Organization box appears.
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.
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.