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.

Terraform registry file vary by platform:

• Linux and macOS: ~/.terraformrc
• Windows: %APPDATA%\terraform.rc

Connect and Authenticate

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

1. Create or edit the Terraform CLI configuration file in the following location:

   • Linux and macOS: ~/.terraformrc
   • Windows: %APPDATA%\terraform.rc

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

Note Terraform Token Realm must be added to the Active realms as documented in Realms. Once the realm is activated, a Terraform CLI user can establish the authentication to a repository.

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/"
  }
}

Example .tf configuration:

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 examples,

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

Coder example:

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

Note
The value defined in the host block must match the hostname/namespace prefix used in the source attribute of the provider.

OpenTofu

OpenTofu uses the following CLI configuration file locations:

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

For backward compatibility, OpenTofu also supports Terraform CLI configuration files:

• Linux and macOS: ~/.terraformrc
• Windows: %APPDATA%\terraform.rc

If both OpenTofu and Terraform CLI configuration files exist, OpenTofu gives precedence to .tofurc (or tofu.rc on Windows).

OpenTofu example:

host "registry.opentofu.org" {
  services = {
    "modules.v1"   = "https://[NexusURL]/repository/<REPO_NAME>/v1/modules/<USER_TOKEN>/",
    "providers.v1" = "https://[NexusURL]/repository/<REPO_NAME>/v1/providers/<USER_TOKEN>/"
  }
}

Note
The host name must match the registry hostname used in the module or provider source.

Anonymous Access

Authentication token is not required when using anonymous access. The Terraform registry file may appear as follows.

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