Terraform

Use a Terraform registry to host private Terraform modules and providers.

---

Before you begin

• Ensure you have the Terraform CLI (terraform) installed on your local machine.

• Access to a Harness account with appropriate permissions to create registries and connectors.

---

Create a Terraform artifact registry

1. Go to the Artifact Registry module in your Harness project.

2. Click New Artifact Registry.

3. In the Registry Type list, select Terraform.

4. Enter a Registry Name.

   REGISTRY NAME CRITERIA

   The registry name must start with a letter, should only contain lowercase alphanumerics, _, . and -, and must be unique to your Harness account.

5. Optionally, add a Description and Labels for better organization.

6. Choose visibility between Public and Private. By default, the visibility is set to Private.

7. Select Create Registry 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 an upstream proxy

1. In the Artifact Registry module, select the dropdown next to New Artifact Registry and select Upstream Proxy.

2. Select Terraform as the proxy type.

3. Enter an Upstream Proxy Key.

4. Optionally, add a Description and Labels.

5. Select your Source:

   • Terraform Registry

   • Custom

6. If you choose Custom, enter your Remote Registry URL (for example, https://registry.terraform.io).

7. Choose your Authentication method (Anonymous by default for public Terraform registries).

8. Click Create Upstream Proxy to establish the connection.

Configure the upstream proxy in your registry

1. In the Artifact Registry module, select an existing Terraform Artifact Registry.

2. Go to the Configuration tab.

3. In the Advanced (Optional) section, click Configure Upstream.

4. Select from the list of compatible proxies to add them to your registry.

5. Select Save to save the configuration.

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.

---

Set up the Terraform client

In your Harness Terraform Artifact Registry, click Set Up Client and follow the instructions to configure Terraform or OpenTofu to use the registry.

Configure a module

Terraform CLI

1. Generate identity token

1. In your Harness Terraform Artifact Registry, click Set Up Client.

2. Click Generate Token to generate an identity token.

2. Configure ~/.terraformrc

Add the following to ~/.terraformrc:

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

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

3. Upload module

Upload the module directory to the registry:

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

4. Use module

1. Reference the module in your .tf file:

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

1. Run terraform init.

OpenTofu

1. Generate identity token

1. In your Harness Terraform Artifact Registry, click Set Up Client.

2. Click Generate Token to generate an identity token.

2. Configure ~/.tofurc

Add the following to ~/.tofurc:

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

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

3. Upload module

Upload the module directory to the registry:

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

4. Use module

1. Reference the module in your .tf file:

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

1. Run tofu init.

Configure a provider

Terraform CLI

1. Generate identity token

1. In your Harness Terraform Artifact Registry, click Set Up Client.

2. Click Generate Token to generate an identity token.

2. Configure ~/.terraformrc

Add the following to ~/.terraformrc:

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

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

3. Upload provider

Upload a provider binary to the registry:

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

4. Use provider

1. Reference the provider in your .tf file:

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

1. Run terraform init.

OpenTofu

1. Generate identity token

1. In your Harness Terraform Artifact Registry, click Set Up Client.

2. Click Generate Token to generate an identity token.

2. Configure ~/.tofurc

Add the following to ~/.tofurc:

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

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

3. Upload provider

Upload a provider binary to the registry:

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

4. Use provider

1. Reference the provider in your .tf file:

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

1. Run tofu init.

---

Troubleshooting

Publish to a Terraform registry returns 409 Conflict

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.