> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/terraform.md).

# Terraform

Terraform - host modules in Harness Artifacts

Use a **Terraform** registry to host private Terraform modules and providers. The registry works with both the Terraform CLI and OpenTofu.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## Before you begin

* Install the Terraform CLI (`terraform`) or OpenTofu (`tofu`) on your local machine.
* Install the Harness CLI (`hc`). You use it to publish packages to your registry.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Terraform Registry

To create a Terraform Registry:

1. In Artifact Registry, select **Registries**.
2. Click **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Terraform** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Terraform modules and providers from external Terraform-protocol registries when they are not available locally. The default upstream is `registry.terraform.io`.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Click the drop-down next to **+ Create Registry** and select **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Terraform** as the **Registry type**.
7. Select the **Source**: **Terraform Registry** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL** (for example, `https://registry.terraform.io`).
8. Select the **Authentication method**.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Anonymous**: No credentials required. This works for public Terraform registries.
9. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing Terraform artifact registry.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Click **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Select **Apply**.
7. Click **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If a module or provider is not found in your Harness registry, the upstream proxy fetches it from the remote registry and caches it.
{% endhint %}

## Terraform client setup

In your Harness Terraform Artifact, select the required Terraform registry, and then select **Setup Client**. The dialog gives you an identity token, then setup instructions for a module or a provider, using either the Terraform CLI or OpenTofu.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your Terraform Artifact Registry, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. You use it in the following steps in place of `<IDENTITY_TOKEN>`.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.
{% endhint %}

### Configure the client

Select **Module** or **Provider** for what you want to publish or use, then select **Terraform CLI** or **OpenTofu** for your client. In the code samples, replace the values in angle brackets with your own values.

{% tabs %}
{% tab title="Module" %}
{% tabs %}
{% tab title="Terraform CLI" %}
**1. Configure \~/.terraformrc**

Add the following to `~/.terraformrc`:

```hcl
host "pkg.harness.io" {
  services = {
    "modules.v1" = "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/terraform/v1/modules/"
  }
}

credentials "pkg.harness.io" {
  token = "<IDENTITY_TOKEN>"
}
```

**2. Publish the module**

Upload the module directory to the registry:

```bash
hc artifact push terraform <REGISTRY_NAME> <MODULE_DIR> --namespace <NAMESPACE> --name <NAME> --provider <PROVIDER> --version <VERSION>
```

**3. Use the module**

Reference the module in your `.tf` file:

```hcl
module "example" {
  source  = "pkg.harness.io/<NAMESPACE>/<NAME>/<PROVIDER>"
  version = "<VERSION>"
}
```

Then initialize your configuration:

```bash
terraform init
```

{% endtab %}

{% tab title="OpenTofu" %}
**1. Configure \~/.tofurc**

Add the following to `~/.tofurc`:

```hcl
host "pkg.harness.io" {
  services = {
    "modules.v1" = "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/terraform/v1/modules/"
  }
}

credentials "pkg.harness.io" {
  token = "<IDENTITY_TOKEN>"
}
```

**2. Publish the module**

Upload the module directory to the registry:

```bash
hc artifact push terraform <REGISTRY_NAME> <MODULE_DIR> --namespace <NAMESPACE> --name <NAME> --provider <PROVIDER> --version <VERSION>
```

**3. Use the module**

Reference the module in your `.tf` file:

```hcl
module "example" {
  source  = "pkg.harness.io/<NAMESPACE>/<NAME>/<PROVIDER>"
  version = "<VERSION>"
}
```

Initialize your configuration:

```bash
tofu init
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="Provider" %}
{% hint style="warning" %}
**Provider installation**

The `exclude` setting stops Terraform and OpenTofu from installing providers directly from `registry.terraform.io`. Providers are installed from your Harness registry instead. To make public providers available, configure an upstream proxy for your registry.
{% endhint %}

{% tabs %}
{% tab title="Terraform CLI" %}
**1. Configure \~/.terraformrc**

Add the following to `~/.terraformrc`:

```hcl
credentials "pkg.harness.io" {
  token = "<IDENTITY_TOKEN>"
}

provider_installation {
  network_mirror {
    url     = "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/terraform/v1/providers/"
    include = ["<NAMESPACE>/<TYPE>"]
  }
  direct {
    exclude = ["<NAMESPACE>/<TYPE>"]
  }
}
```

**2. Publish the provider**

Upload a provider binary to the registry:

```bash
hc artifact push terraform <REGISTRY_NAME> <FILE_PATH> --namespace <NAMESPACE>
```

**3. Use the provider**

Reference the provider in your `.tf` file:

```hcl
terraform {
  required_providers {
    <TYPE> = {
      source  = "<NAMESPACE>/<TYPE>"
      version = "<VERSION>"
    }
  }
}
```

Initialize your configuration:

```bash
terraform init
```

{% endtab %}

{% tab title="OpenTofu" %}
**1. Configure \~/.tofurc**

Add the following to `~/.tofurc`:

```hcl
credentials "pkg.harness.io" {
  token = "<IDENTITY_TOKEN>"
}

provider_installation {
  network_mirror {
    url     = "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/terraform/v1/providers/"
    include = ["<NAMESPACE>/<TYPE>"]
  }
  direct {
    exclude = ["<NAMESPACE>/<TYPE>"]
  }
}
```

**2. Publish the provider**

Upload a provider binary to the registry:

```bash
hc artifact push terraform <REGISTRY_NAME> <FILE_PATH> --namespace <NAMESPACE>
```

**3. Use the provider**

Reference the provider in your `.tf` file:

```hcl
terraform {
  required_providers {
    <TYPE> = {
      source  = "<NAMESPACE>/<TYPE>"
      version = "<VERSION>"
    }
  }
}
```

Initialize your configuration:

```bash
tofu init
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Setup verification

Confirm that your registry serves the package you published. To verify your setup:

1. In a new directory with no cached modules, providers, or local Terraform state, use your package client to install or resolve the package you published.
2. Confirm that the client downloaded the package from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the package and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step shows the shape of a publish step. Replace `<PUBLISH_COMMAND>` with the publish command from the earlier steps. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        <PUBLISH_COMMAND> --version "$PACKAGE_VERSION"
```

## Troubleshooting

<details>

<summary>A publish to a Terraform registry returns 409 Conflict</summary>

Module and provider versions are immutable after publish. Choose a new SemVer version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>Package client cannot authenticate to the registry</summary>

Check that the registry address in your client configuration matches the one shown in **Setup Client**, and that the identity token is the one you generated there. If the token has expired or was revoked, generate a new one and update your client configuration.

</details>

<details>

<summary>Package client cannot find the package</summary>

Check that the package name and version match the values you used when you published the package. Also, check that the registry name and account ID in your client configuration are correct.

</details>

<details>

<summary>Client still uses an old version after publishing a new one</summary>

Refresh or clear the cache of your package client, and update the version you pinned in your project.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
