> 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/agents/automate-with-terraform.md).

# Automate with Terraform

Create and manage Harness Artifacts registries, upstream proxies, filtering rules, and Dependency Firewall as code with the Terraform provider.

The Harness Terraform provider lets you create and manage registries, upstream proxies, artifact filtering rules, and Dependency Firewall configuration as code. This page provides ready-to-use HCL for the most common automation patterns.

## Provider setup

```hcl
terraform {
  required_version = ">= 1.5.0"

  required_providers {
    harness = {
      source  = "harness/harness"
      version = ">= 0.30.0"
    }
  }
}

provider "harness" {
  endpoint         = "https://app.harness.io/gateway"
  account_id       = var.harness_account_id
  platform_api_key = var.harness_platform_api_key
}
```

Always use `platform_api_key` (not the legacy `api_key`); Artifact Registry is a Harness NextGen feature.

**Credentials using environment variables: never hardcode them**.

```bash
export TF_VAR_harness_account_id="<account-id>"
export TF_VAR_harness_platform_api_key="<service-account-token>"
export TF_VAR_space_ref="<account_id>/<org_id>/<project_id>"
```

**Standard `variables.tf` for all configs**:

```hcl
variable "harness_account_id" {
  type        = string
  description = "Harness account ID."
}

variable "harness_platform_api_key" {
  type        = string
  sensitive   = true
  description = "Service account token or PAT."
}

variable "space_ref" {
  type        = string
  description = "Registry scope: account_id/org_id/project_id"
}
```

***

## Virtual registry

A virtual registry is the client-facing endpoint your team uses to push and pull artifacts.

{% tabs %}
{% tab title="Docker" %}

```hcl
resource "harness_platform_har_registry" "docker" {
  identifier   = "my-docker"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "DOCKER"

  config {
    type             = "VIRTUAL"
    upstream_proxies = []  # attach proxies later
  }
}

output "registry_url" {
  value = harness_platform_har_registry.docker.url
}
```

{% endtab %}

{% tab title="npm" %}

```hcl
resource "harness_platform_har_registry" "npm" {
  identifier   = "my-npm"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "NPM"

  config {
    type             = "VIRTUAL"
    upstream_proxies = []
  }
}
```

{% endtab %}

{% tab title="Python / PyPI" %}

```hcl
resource "harness_platform_har_registry" "python" {
  identifier   = "my-pypi"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "PYTHON"

  config {
    type             = "VIRTUAL"
    upstream_proxies = []
  }
}
```

{% endtab %}

{% tab title="Maven" %}

```hcl
resource "harness_platform_har_registry" "maven" {
  identifier   = "my-maven"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "MAVEN"

  config {
    type             = "VIRTUAL"
    upstream_proxies = []
  }
}
```

{% endtab %}

{% tab title="Helm / Generic / Go / Cargo" %}

```hcl
# Change package_type to: HELM, GENERIC, GO, CARGO, NUGET
resource "harness_platform_har_registry" "helm" {
  identifier   = "my-helm"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "HELM"

  config {
    type             = "VIRTUAL"
    upstream_proxies = []
  }
}
```

Supported `package_type` values: `DOCKER`, `HELM`, `MAVEN`, `NPM`, `PYTHON`, `GO`, `NUGET`, `CARGO`, `GENERIC`, `RPM`, `DEBIAN`, `ALPINE`, `WOLFI`, `SWIFT`, `COMPOSER`, `DART`, `RUBYGEMS`, `CRAN`, `CONAN`, `CONDA`, `PUPPET`, `HUGGING_FACE`, `TERRAFORM_MODULE`.
{% endtab %}
{% endtabs %}

***

## Upstream proxy

An upstream proxy caches artifacts from a public or private source registry. Attach it to a virtual registry to serve cached content.

{% tabs %}
{% tab title="Docker Hub (anonymous)" %}

```hcl
resource "harness_platform_har_registry" "dockerhub_proxy" {
  identifier   = "dockerhub-proxy"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "DOCKER"

  config {
    type      = "UPSTREAM"
    source    = "Dockerhub"
    auth_type = "Anonymous"
  }
}
```

{% endtab %}

{% tab title="Docker Hub (authenticated)" %}

```hcl
# Store Docker Hub credentials as Harness secrets first.
# secret_identifier is the Harness secret ID (not the Docker Hub password).

resource "harness_platform_har_registry" "dockerhub_proxy" {
  identifier   = "dockerhub-proxy"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "DOCKER"

  config {
    type      = "UPSTREAM"
    source    = "Dockerhub"
    auth_type = "UserPassword"

    auth {
      auth_type         = "UserPassword"
      user_name         = var.dockerhub_username
      secret_identifier = var.dockerhub_secret_identifier
      secret_space_path = var.space_ref
    }
  }
}

variable "dockerhub_username" { type = string }
variable "dockerhub_secret_identifier" {
  type      = string
  sensitive = true
}
```

{% endtab %}

{% tab title="Custom / Private registry" %}

```hcl
resource "harness_platform_har_registry" "private_proxy" {
  identifier   = "nexus-proxy"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "MAVEN"

  config {
    type       = "UPSTREAM"
    source     = "Custom"
    remote_url = "https://nexus.example.com/repository/maven-public"
    auth_type  = "UserPassword"

    auth {
      auth_type         = "UserPassword"
      user_name         = var.nexus_username
      secret_identifier = var.nexus_secret_id
      secret_space_path = var.space_ref
    }
  }
}

variable "nexus_username" { type = string }
variable "nexus_secret_id" {
  type      = string
  sensitive = true
}
```

{% endtab %}
{% endtabs %}

***

## Virtual registry wired to an upstream proxy

The full pattern: create both resources and wire them together in a single config. This is the recommended approach for new infrastructure.

```hcl
# Virtual registry (client-facing)
resource "harness_platform_har_registry" "docker" {
  identifier   = "my-docker"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "DOCKER"

  config {
    type             = "VIRTUAL"
    upstream_proxies = [harness_platform_har_registry.dockerhub_proxy.identifier]
  }

  depends_on = [harness_platform_har_registry.dockerhub_proxy]
}

# Upstream proxy (caches from Docker Hub)
resource "harness_platform_har_registry" "dockerhub_proxy" {
  identifier   = "dockerhub-proxy"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "DOCKER"

  config {
    type      = "UPSTREAM"
    source    = "Dockerhub"
    auth_type = "Anonymous"
  }
}

output "registry_url" {
  value = harness_platform_har_registry.docker.url
  # e.g. https://pkg.harness.io/<account_id>/my-docker
}
```

The `depends_on` ensures the proxy is created before the virtual registry references its identifier.

***

## Artifact filtering rules

Add `allowed_pattern` and `blocked_pattern` to restrict which artifacts can be pushed to or pulled from a registry. Each pattern is a full regex match against the artifact name.

```hcl
resource "harness_platform_har_registry" "prod_docker" {
  identifier   = "prod-docker"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "DOCKER"

  # Allow only images tagged with a semver or a commit SHA
  allowed_pattern = ["v[0-9]+\\.[0-9]+\\.[0-9]+.*", "[a-f0-9]{40}"]

  # Block images tagged 'latest' or 'dev' in production
  blocked_pattern = ["latest", "dev", ".*-snapshot"]

  config {
    type = "VIRTUAL"
  }
}
```

***

## Dependency Firewall

Dependency Firewall evaluates artifacts fetched through an **upstream proxy** against security policies before caching them. Configure it on the upstream proxy registry, not the virtual registry.

| `firewall_mode` value | Behavior                                                                                              |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| Omitted / `"ALLOW"`   | Firewall disabled                                                                                     |
| `"ENABLED"`           | Firewall on; artifacts that trigger a Warn policy are cached and usable (violation logged)            |
| `"QUARANTINE"`        | Firewall on; artifacts that trigger a Warn policy are cached but blocked until manually unquarantined |

```hcl
# Upstream proxy with Dependency Firewall in quarantine mode
resource "harness_platform_har_registry" "npm_proxy" {
  identifier   = "npm-proxy"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "NPM"

  config {
    type          = "UPSTREAM"
    source        = "NpmJs"
    auth_type     = "Anonymous"
    firewall_mode = "QUARANTINE"
  }
}

# Virtual registry routing through the firewall-protected proxy
resource "harness_platform_har_registry" "npm" {
  identifier   = "npm-prod"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "NPM"

  config {
    type             = "VIRTUAL"
    upstream_proxies = [harness_platform_har_registry.npm_proxy.identifier]
  }

  depends_on = [harness_platform_har_registry.npm_proxy]
}
```

{% hint style="info" %}
Dependency Firewall is behind the `HAR_DEPENDENCY_FIREWALL` feature flag. Contact [Harness Support](mailto:support@harness.io) to enable it. Applying `firewall_mode` without the flag enabled has no effect.
{% endhint %}

***

## Import an existing registry

If a registry was created through the Harness UI, bring it under Terraform management.

The import path is always `account_id/org_id/project_id/registry_identifier`, with no leading slash, no `https://`, and no `.` separators.

**HCL import block (Terraform ≥ 1.5, recommended)**:

```hcl
import {
  to = harness_platform_har_registry.my_registry
  id = "<account_id>/<org_id>/<project_id>/<registry_identifier>"
}

resource "harness_platform_har_registry" "my_registry" {
  identifier   = "<registry_identifier>"
  space_ref    = var.space_ref
  parent_ref   = var.space_ref
  package_type = "DOCKER"

  config {
    type = "VIRTUAL"
  }
}
```

Run `terraform plan`; Terraform shows what would change without applying. Run `terraform apply` to complete the import.

**CLI import (all Terraform versions)**:

```bash
terraform import harness_platform_har_registry.my_registry \
  "<account_id>/<org_id>/<project_id>/<registry_identifier>"
```

After importing, run `terraform plan` to confirm the existing state matches your configuration before applying any changes.

***

## Remote state for teams and CI/CD

Local state (`terraform.tfstate`) only works on a single workstation. For shared infrastructure, configure a remote backend.

{% tabs %}
{% tab title="S3 (AWS)" %}

```hcl
terraform {
  backend "s3" {
    bucket         = "my-tf-state"
    key            = "harness/artifact-registry/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "tf-state-lock"
  }
}
```

{% endtab %}

{% tab title="GCS (Google Cloud)" %}

```hcl
terraform {
  backend "gcs" {
    bucket = "my-tf-state-bucket"
    prefix = "harness/artifact-registry"
  }
}
```

{% endtab %}

{% tab title="HashiCorp Cloud Platform (HCP) Terraform" %}

```hcl
terraform {
  cloud {
    organization = "my-org"
    workspaces {
      name = "harness-artifact-registry"
    }
  }
}
```

{% endtab %}
{% endtabs %}

Never commit `*.tfstate` or `*.tfstate.*` files to source control. Add this `.gitignore`:

```
*.tfstate
*.tfstate.*
.terraform/
terraform.tfvars
*.tfvars.json
```

***

## Run Terraform in CI/CD

### GitHub Actions

```yaml
name: Provision Artifacts registries

on:
  push:
    branches: [main]
    paths:
      - 'infra/artifact-registry/**'

jobs:
  terraform:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: infra/artifact-registry

    steps:
      - uses: actions/checkout@v4

      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "~1.9"

      - name: Terraform init
        run: terraform init

      - name: Terraform plan
        run: terraform plan -out=tfplan

      - name: Terraform apply
        if: github.ref == 'refs/heads/main'
        run: terraform apply -auto-approve tfplan

    env:
      TF_VAR_harness_account_id: ${{ secrets.HARNESS_ACCOUNT_ID }}
      TF_VAR_harness_platform_api_key: ${{ secrets.HARNESS_API_KEY }}
      TF_VAR_space_ref: ${{ secrets.HARNESS_SPACE_REF }}
```

Store `HARNESS_API_KEY` as a repository secret. Use a **service account token** scoped to the Artifact Registry Admin role, not a personal access token.

### Harness CI pipeline

```yaml
pipeline:
  stages:
    - stage:
        type: CI
        spec:
          execution:
            steps:
              - step:
                  type: Run
                  spec:
                    image: hashicorp/terraform:1.9
                    command: |
                      cd infra/artifact-registry
                      terraform init
                      terraform apply -auto-approve
                    envVariables:
                      TF_VAR_harness_account_id: <+account.identifier>
                      TF_VAR_harness_platform_api_key: <+secrets.getValue("harness_api_key")>
                      TF_VAR_space_ref: <+account.identifier>/<+org.identifier>/<+project.identifier>
```

***

## Troubleshooting

<details>

<summary>Error: `undefined response type` during terraform apply</summary>

The registry may have been created despite the error. Check the Harness UI. If the registry exists, import it:

```bash
terraform import harness_platform_har_registry.<name> \
  "<account_id>/<org_id>/<project_id>/<registry_identifier>"
```

Then run `terraform init -upgrade` to pull the latest provider version and retry.

</details>

<details>

<summary>Error: `terraform import` fails with "not found"</summary>

The import path must be exactly `account_id/org_id/project_id/registry_identifier`. Common mistakes:

* Leading or trailing slash
* Using the registry URL (`pkg.harness.io/...`) instead of the identifier path
* Using `.` instead of `/` as the separator

Run `terraform state list` after a successful import to confirm the resource was added.

</details>

<details>

<summary>Error: `401 Unauthorized` from the Harness provider</summary>

Confirm:

1. `platform_api_key` is set (not the legacy `api_key`).
2. The token has not expired. Check in **Account Settings > Service Accounts > \[account] > Tokens**.
3. The service account has the **Artifact Registry Admin** or **Contributor** role at the scope matching `space_ref`.

</details>

<details>

<summary>Error: `403 Forbidden`: provider authenticates but cannot create the registry</summary>

The service account has valid credentials but lacks permission to create registries at the scope in `space_ref`. Go to **Account Settings > Service Accounts > \[account] > Role Bindings** and assign the **Artifact Registry Admin** role at the project, org, or account scope that matches your `space_ref`.

</details>

<details>

<summary>upstream_proxies change is ignored on terraform apply</summary>

If the virtual registry was created before the upstream proxy existed, Terraform may have stored the initial empty list in state. Run:

```bash
terraform refresh
terraform plan
```

If the plan still shows no changes but the proxy is not attached, the resource may need to be re-imported or the state may be stale. Force a replace:

```bash
terraform apply -replace="harness_platform_har_registry.docker"
```

</details>

***

## Next steps

* [Terraform provider reference](https://developer.harness.io/artifact-registry/3.0/reference/terraform-provider.md): full `harness_platform_har_registry` argument and attribute reference
* [Authentication for agents](https://developer.harness.io/artifact-registry/3.0/agents/authentication-for-agents.md): create service account tokens for Terraform automation
* [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md): minimum permissions for provisioning agents
* [Using Artifacts with AI agents](https://developer.harness.io/artifact-registry/3.0/agents/using-ar-with-ai-agents.md): URL patterns and REST API for agents that consume provisioned registries

{% @harness-feedback/feedback %}
