Configure Terraform with Nexus

Note

Nexus Repository supports Terraform proxy repositories for Terraform-compatible upstream registries, including registry.terraform.io, registry.opentofu.org, and registry.coder.com.

Configure Terraform registry file to connect to and authenticate to a Nexus Terraform Repository. You must create a Terraform repository in Nexus before configuring your client to connect to it. Check Create a Terraform Repository for more details.

Nexus Repository supports Non-URL and URL authentication methods for Nexus Terraform repositories. Non-URL authentication is available in Nexus Repository 3.95 and later and URL authentication method is available in all Nexus Repository versions that support Terraform repositories. Before configuring any of the authentication methods, make sure to add the Terraform Token Realm to the list of active realms. For more information, see Realms.

Non-URL Authentication

This authentication method is supported with Terraform CLI 0.13 and later. Take the following steps to connect and authenticate Terraform clients using Non-URL Authentication method:

Obtain a Terraform bearer token by sending a GET request to the token endpoint:
```
curl -u <username>:<password> \
  https://[NexusURL]/repository/<repo-name>/v1/api/token
```
Where,
- <username> - Your Nexus username or usertoken name code
- <password> - Your Nexus password or usertoken pass code
- [NexusURL] - Your Nexus Repository base URL
- <repo-name> - Your Nexus repository name, for example terraform-proxy
Copy the complete token value as returned. It would be in the format as shown:
```
{
  "token": "TerraformBearerToken.<OPAQUE_STRING>"
}
```
Note that an unauthenticated or anonymous request returns an HTTP 401 Unauthorized response.

Open your terraform registry file. Add a credentials block and the required service endpoints to the Terraform CLI configuration file. On Linux/macOS, the file is located at ~/.terraformrc. On Windows it is %APPDATA%\terraform.rc.

credentials "[NexusURL]" {
  token = "TerraformBearerToken.<opaque-string>"
}

host "registry.terraform.io" {
  services = {
    "modules.v1"   = "https://[NexusURL]/repository/<repo-name>/v1/modules/"
    "providers.v1" = "https://[NexusURL]/repository/<repo-name>/v1/providers/"
  }
}

Where,

[NexusURL] - Your Nexus Repository URL
<repo_name> - Repository name, for example terraform-proxy or terraform-hosted

Example:

credentials "example.nexus.com" {
  token = "TerraformBearerToken.<OPAQUE_STRING>"
}

host "registry.terraform.io" {
  services = {
    "modules.v1"   = "https://example.nexus.com/repository/terraform-proxy/v1/modules/"
    "providers.v1" = "https://example.nexus.com/repository/terraform-proxy/v1/providers/"
  }
}

host "terraform-hosted" {
  services = {
    "modules.v1"   = "https://example.nexus.com/repository/terraform-hosted/v1/modules/"
    "providers.v1" = "https://example.nexus.com/repository/terraform-hosted/v1/providers/"
  }
}

URL Authentication

Take the following steps to connect and authenticate Terraform client with Nexus:

Create or edit the Terraform CLI configuration file in the following location:
- Linux and macOS: ~/.terraformrc
- Windows: %APPDATA%\terraform.rc

Edit the .terraformrc file for Linux/macOS or terraform.rc for Windows.

# ~/.terraformrc
# For custom hosts
host "registry.terraform.io" {
  services = {
    "modules.v1"   = "https://[NexusURL]/repository/<REPO_NAME>/v1/modules/<USER_TOKEN>/",
    "providers.v1" = "https://[NexusURL]/repository/<REPO_NAME>/v1/providers/<USER_TOKEN>/"
  }
}

Where,

host - Overrides the default Terraform registry endpoints.
services - Maps service endpoints to your Nexus proxy repository.
providers.v1 - Endpoint for Terraform provider downloads.
modules.v1 - Endpoint for Terraform module downloads.
[NexusURL] - Your Nexus Repository URL
<REPO_NAME> - Repository name, for example terraform-proxy or terraform-hosted
<USER_TOKEN> - base64 representation of either Nexus user token or username:password.

Tip

Sonatype recommends using Nexus user token instead of username and password. To access your user token,

Go to Account → User Token → Access User Token → Authenticate and copy the base64 representation.

Registry Configuration Example:

host "registry.terraform.io" {
  services = {
    "modules.v1"   = "https://example.nexus.com/repository/terraform-proxy/v1/modules/",
    "providers.v1" = "https://example.nexus.com/repository/terraform-proxy/v1/providers/"
  }
}

host "terraform-hosted" {
  services = {
    "modules.v1"   = "https://example.nexus.com/repository/terraform-hosted/v1/modules/",
    "providers.v1" = "https://example.nexus.com/repository/terraform-hosted/v1/providers/"
  }
}

Configuration Examples

The following examples show how to use Terraform and other Terraform-compatible registries with Nexus Repository. Before using these examples, configure either Non-URL Authentication or URL Authentication in the applicable CLI configuration file. In all the examples, the host name must match the registry hostname used in the module or provider source.

Terraform Configuration Example

Terraform configuration files use the .tf file extension. These files define the providers, modules, and infrastructure resources that Terraform uses. The .tf configuration does not contain the Nexus Repository authentication credentials. Authentication and repository endpoints remain configured in the Terraform CLI configuration file.

The following .tf example retrieves one provider through a Terraform hosted repository and another provider through a Terraform proxy repository:

terraform {
  required_version = ">= 1.0"

  required_providers {
    aws = {
      source  = "terraform-hosted/examplecorp/internal-provider"
      version = "4.59.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.5"
    }
  }
}

In the above example,

terraform-hosted/examplecorp/internal-provider is downloaded from the terraform-hosted repository.
hashicorp/random is downloaded from the terraform-proxy repository.

Coder Registry Example

Nexus Repository can proxy Terraform modules from the Coder registry at registry.coder.com. Add a host block for the Coder registry to the Terraform CLI configuration file.

Non-URL Authentication:

credentials "[NexusURL]" {
  token = "TerraformBearerToken.<OPAQUE_STRING>"
}

host "registry.coder.com" {
  services = {
    "modules.v1" = "https://[NexusURL]/repository/<REPO_NAME>/v1/modules/"
  }
}

URL Authentication:

host "registry.coder.com" {
  services = {
    "modules.v1" = "https://[NexusURL]/repository/<REPO_NAME>/v1/modules/<USER_TOKEN>/"
  }
}

OpenTofu Example

OpenTofu can retrieve modules and providers through Terraform repositories in Nexus Repository. OpenTofu uses the following CLI configuration file locations:

Linux and macOS: ~/.tofurc
Windows: %APPDATA%\tofu.rc

For backward compatibility, OpenTofu also supports .terraformrc and terraform.rc configuration files. If both an OpenTofu configuration file and a Terraform CLI configuration file exist, OpenTofu gives precedence to .tofurc on Linux and macOS or tofu.rc on Windows.