# Create a Terraform Repository

This guide describes how to create Terraform proxy, hosted and group repositories in Nexus Repository.

## Terraform Proxy Repository

Use Nexus proxy repository when you want to download packages and centralize package caching of external dependencies. To learn more, check [Proxy Repositories](https://help.sonatype.com/en/repository-types.html#proxy-repository-type "Proxy Repository Type").

To create a new Terraform proxy repository, take the following steps:

1. Navigate to _Settings_→ _Repository_→ _Repositories_.
2. Select the _Create repository_ button.
3. From the list of Recipes, select _terraform (proxy)_.
4. In the form that appears, complete the required fields
   - Repository Name, for example, _terraform-proxy_
   - Remote storage URL, for example:
     - [https://registry.terraform.io](https://registry.terraform.io/)
     - [https://registry.opentofu.org](https://registry.opentofu.org/)
     - [https://registry.coder.com](https://registry.coder.com/)
     - An HTTPS registry URL that serves a valid `/.well-known/terraform.json` response.
   - Blob store
5. Complete the additional fields for configurations you wish to add for creating your repository. Available configurations differ by repository format and type. See [Configurable Repository Fields](https://help.sonatype.com/en/configurable-repository-fields.html "Configurable Repository Fields") for more details.
6. Select _Create repository_.

**Tip**  
Terraform artifacts are indexed in Nexus search. You can search by name, namespace, and provider. You can filter by exact versions or version ranges. For providers, you can filter by operating system and architecture.

Use a separate Terraform proxy repository for each upstream registry. To expose multiple Terraform repositories through one URL, add them to a Terraform group repository.

## Terraform Hosted Repository

Use Nexus hosted repository when you want to publish and store your own internal artifacts and third party components, so they can be consumed via Nexus. To learn more, check [Hosted Repositories](https://help.sonatype.com/en/repository-types.html#hosted-repository-type "Hosted Repository Type").

To create a new Terraform hosted repository, take the following steps:

1. Navigate to _Settings_→ _Repository_→ _Repositories_.
2. Select the _Create repository_ button.
3. From the list of Recipes, select _terraform (hosted)_.
4. In the form that appears, complete the required fields
   - Repository Name, for example _terraform-hosted_
   - Signing Key, for example _gpg --export-secret-key --armor_. Check [Generate GPG Keypair](https://help.sonatype.com/en/create-a-terraform-repository.html#generate-gpg-keypair "Generate GPG Keypair")
   - Passphrase, for example the passphrase used when generating the GPG key (see [Generate GPG Keypair](https://help.sonatype.com/en/create-a-terraform-repository.html#generate-gpg-keypair "Generate GPG Keypair"))
   **Note**  
   Configure the passphrase in Settings → Repository → Repositories → \[your repository\], below the Signing Key field.
   - Blob store
5. Complete the additional fields for configurations you wish to add for creating your repository. Available configurations differ by repository format and type. See [Configurable Repository Fields](https://help.sonatype.com/en/configurable-repository-fields.html "Configurable Repository Fields") for more details.
6. Select _Create repository_.

**Tip**  
To upload packages using the UI, see [Uploading Components](https://help.sonatype.com/en/uploading-components.html "Uploading Components").

**Note**  
GPG signing is mandatory for Terraform hosted repositories. Configure the _Signing Key_ which is a GPG key used for signing and _Passphrase_ which is the passphrase for the private key by reviewing the Generate GPG Key Pair section.

### [Generate GPG Keypair](https://help.sonatype.com/en/create-a-terraform-repository.html#generate-gpg-keypair_body)

GPG (GNU Privacy Guard) keys are used to cryptographically sign Terraform provider packages. Terraform verifies these signatures during provider installation to ensure integrity and authenticity.

GPG signing is required for publicly distributed providers and recommended for internal providers in enterprise environments. GPG signing is optional for Terraform modules, which typically do not require signatures.

Nexus manages GPG keys used for Terraform provider signing. The private key is stored in encrypted form in the Nexus database. The public key is extracted automatically and included in provider metadata. The key ID is derived from the last 8 bytes of the key fingerprint and is represented in hexadecimal format, for example `72D7468F`.

Take the following steps to generate a GPG Keypair:

1. Install GPG on your machine.
```
# macOS
brew install gnupg

# Ubuntu/Debian
sudo apt-get install gnupg

# CentOS/RHEL
sudo yum install gnupg
```

2. Generate a GPG keypair.
```
# Generate keypair interactively
gpg --full-generate-key
```
Use the following values when prompted:
   - _Key type:_ Select `(1) RSA and RSA (default)`
   - _Key size:_ Enter `4096` (recommended)
   - _Expiration:_ Enter `0` to create a key that does not expire, or specify an expiration period based on your security policy
   - _Real name:_ Organization name or Team name
   - _Email address:_ Team or service mail address
   - _Comment:_ Optionally enter `Used for signing Terraform providers`
   - _Passphrase:_ Enter a strong passphrase. This is required

3. Export the Private Key.
```
# List your keys to find the key ID
gpg --list-secret-keys --keyid-format=long

# Output will look like:
# sec   rsa4096/ABCD1234EFGH5678 2024-01-15 [SC]
#       1234567890ABCDEF1234567890ABCDEF12345678
# uid           [ultimate] Acme Corp Terraform <terraform@acme.com>

# Export the private key in ASCII-armored format
# Replace ABCD1234EFGH5678 with your key ID
gpg --export-secret-keys --armor ABCD1234EFGH5678 > terraform-private-key.asc
```

**Note**  
   - The private key file contains sensitive data. Store it securely and never commit it to version control.
   - The private key must be in ASCII-armored format:
     ```
     -----BEGIN PGP PRIVATE KEY BLOCK-----

lXXXXXXXXXXXXXX7...
     ...
     -----END PGP PRIVATE KEY BLOCK-----
     ```

4. Export the public key (optional).
```
# Export public key for distribution
gpg --export --armor ABCD1234EFGH5678 > terraform-public-key.asc
```

When users download a signed provider, they can verify the signature by running the following command:
```
# Download provider and signature
curl -O "http://nexus.company.com/repository/terraform-hosted/v1/providers/myorg/custom/1.0.0/download/linux/amd64"
curl -O "http://nexus.company.com/repository/terraform-hosted/v1/providers/myorg/custom/1.0.0/download/linux/amd64.sig"

# Verify signature
gpg --verify terraform-provider-custom_1.0.0_linux_amd64.zip.sig terraform-provider-custom_1.0.0_linux_amd64.zip
```
Expected output:
```
gpg: Signature made Mon Jan 14 10:30:00 2026 PST
gpg:                using RSA key 1234ABCD5678EFGH1234ABCD5678EFGH12345678
gpg: Good signature from "Terraform Provider Signing Key <terraform@company.com>"
```

## Terraform Group Repository

Use Nexus group repository when you want to combine multiple other repositories (proxy, hosted, and other groups) and expose them through a single URL. To learn more, check [Group Repositories](https://help.sonatype.com/en/repository-types.html#group-repository-type "Group Repository Type").

To create a new Terraform group repository, take the following steps:

1. Navigate to _Settings_ → _Repository_→ _Repositories_.
2. Select the _Create repository_ button.
3. From the list of Recipes, select _terraform (group)_.
4. In the form that appears, complete the required fields
   - Repository Name, for example _terraform-group_
   - Blob store
   - Member repositories in the desired order
5. Complete the additional fields for configurations you wish to add for creating your repository. Available configurations differ by repository format and type. See [Configurable Repository Fields](https://help.sonatype.com/en/configurable-repository-fields.html "Configurable Repository Fields") for more details.
6. Select _Create repository_.