# Configure Terraform with Nexus

**Note**  
Nexus Repository supports Terraform proxy repositories for Terraform-compatible upstream registries, including [registry.terraform.io](https://registry.terraform.io/), [registry.opentofu.org](http://registry.opentofu.org/), and [registry.coder.com](http://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](https://help.sonatype.com/en/create-a-terraform-repository.html "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](https://help.sonatype.com/en/realms.html "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/"
  }
}
```