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
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.
Publishing a Provider
Before consumers can use a private provider, you must create the provider, upload a GPG signing key, create at least one version, create at least one platform for that version, and upload release files.
Create a Provider
Use the Create a Provider endpoint to create the provider in Terraform Cloud.
The provider is available in your organization’s Terraform Cloud private registry, but consumers cannot use it until you add a version and a platform.
Create a Version and Platform
To create a version, a platform, and upload the required release files:
Confirm that you can access the provider binaries, public GPG signing key,
SHA256SUMS
file, andSHA256SUMS.sig
file from at least one release.Use the Add a GPG key endpoint to add the public key that matches the signing key for the release. The response contains a
key-id
that you will use to create a provider version.Use the Create a Provider Version endpoint to create a version with the
key-id
from the previous step. The response includes URL links that you will use to upload theSHA256SUMS
andSHA256.sig
files.Upload the
SHA256SUMS
andSHA256SUMS.sig
files to the URLs returned in the previous step. The example command below uploads the files from a local machine.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). The response includes a
provider-binary-upload
URL that you will use to upload the binary file for the platform.Upload the platform binary file to the URL from the previous step. The example command below uploads the binary from a local machine.
(Optional) Repeat steps 4 and 5 to add additional platform binaries for the release.
The version is available in the Terraform Cloud UI. Consumers can begin using this provider version in configurations.
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.