Publish private providers to the HCP Terraform private registry

In addition to curating public providers from the Terraform Registry, 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.

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

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.

{
  "data": {
    "type": "registry-providers",
    "attributes": {
      "name": "PROVIDER_NAME",
      "namespace": "ORG_NAME",
      "registry-name": "private"
    }
  }
}

Use the Create a Provider endpoint 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.

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

{
  "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 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.

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

"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 step. If you are uploading an official HashiCorp public provider, use the value 34365D9472D7468F for your key-id.

{
  "data": {
    "type": "registry-provider-versions",
    "attributes": {
      "version": "5.14.0",
      "key-id": "34365D9472D7468F",
      "protocols": ["5.0"]
    }
  }
}

Use the Create a Provider Version endpoint 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.

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

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

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

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

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

{
  "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 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.

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

"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. The example command below uploads the binary from your local machine.

$ 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 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 HCP Terraform 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 HCP Terraform 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.