> 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/reference/terraform-provider.md).

# Terraform provider

Reference for the harness\_platform\_har\_registry Terraform resource: arguments, computed attributes, examples, and import syntax.

The [Harness Terraform provider](https://registry.terraform.io/providers/harness/harness/latest) lets you manage Artifact Registry resources as infrastructure as code. This page covers the `harness_platform_har_registry` resource, which creates and manages both virtual registries and upstream proxies.

## Before you begin

* Terraform v1.5.0 or later installed.
* A Harness API key (Personal Access Token or Service Account Token). Generate one under **My Profile > API Keys**.
* Your account ID, organization ID, and project ID.

## Provider configuration

```hcl
terraform {
  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
}
```

{% hint style="info" %}
Artifact Registry is a Harness Next Gen feature. Use `platform_api_key`, not the legacy `api_key`, when configuring the provider.
{% endhint %}

Store credentials as environment variables rather than hardcoding them:

```bash
export TF_VAR_harness_account_id="<ACCOUNT_ID>"
export TF_VAR_harness_platform_api_key="<API_KEY>"
```

***

## harness\_platform\_har\_registry

Creates and manages a Harness Artifacts virtual registry or upstream proxy.

### Arguments

**Required**:

| Argument       | Type   | Description                                                                                                            |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `identifier`   | string | Unique registry identifier within the project. Becomes part of the registry URL.                                       |
| `package_type` | string | Artifact format. Go to [Supported package types](#supported-package-types) for all values.                             |
| `parent_ref`   | string | Scope of the registry: `account_id` (account), `account_id/org_id` (org), or `account_id/org_id/project_id` (project). |
| `space_ref`    | string | Same value as `parent_ref`. Required for creation.                                                                     |

**Optional**:

| Argument          | Type         | Description                                                                                                         |
| ----------------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `description`     | string       | Human-readable description of the registry.                                                                         |
| `is_public`       | bool         | Make the registry publicly accessible. Default: `false`. Requires the `PL_ALLOW_TO_SET_PUBLIC_ACCESS` feature flag. |
| `allowed_pattern` | list(string) | Artifact name patterns that are allowed on push. If set, only matching names are accepted.                          |
| `blocked_pattern` | list(string) | Artifact name patterns that are blocked on push. Takes precedence over `allowed_pattern`.                           |
| `metadata`        | map(string)  | Custom key-value labels. Keys and values must match `[letters, numbers, _ . / = + - @]`. Maximum 49 entries.        |
| `config`          | block        | Registry type and behavior. Go to [`config` block](#config-block).                                                  |

**Computed (read-only)**:

| Attribute    | Type   | Description                                                                                              |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------- |
| `id`         | string | Resource ID, assigned by Harness.                                                                        |
| `created_at` | string | ISO 8601 timestamp of when the registry was created.                                                     |
| `url`        | string | Registry URL for client configuration (for example, `https://pkg.harness.io/<account_id>/<identifier>`). |

### config block

The `config` block defines whether the resource is a client-facing virtual registry or an upstream proxy, and how it behaves.

**Required**:

| Argument | Type   | Description                                                             |
| -------- | ------ | ----------------------------------------------------------------------- |
| `type`   | string | `VIRTUAL` for a client-facing registry; `UPSTREAM` for a caching proxy. |

**Optional**:

| Argument            | Type         | Description                                                                                                                                                             |
| ------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `upstream_proxies`  | list(string) | Identifiers of upstream proxies to attach. VIRTUAL type only. Order determines resolution priority.                                                                     |
| `source`            | string       | Upstream source. Required for UPSTREAM type. Values: `Dockerhub`, `MavenCentral`, `PyPi`, `Terraform Registry`, `Custom`, and others per package type.                  |
| `auth_type`         | string       | Top-level auth method: `Anonymous` or `UserPassword`. Required for UPSTREAM type.                                                                                       |
| `auth`              | block        | Auth credentials when `auth_type` is `UserPassword`. Go to [`config.auth` block](#configauth-block).                                                                    |
| `url`               | string       | Upstream registry URL. Required when `type = UPSTREAM` and `package_type = HELM`.                                                                                       |
| `firewall_mode`     | string       | Dependency Firewall enforcement mode: `ALLOW` (default, Firewall off), `ENABLED` (audit only), or `QUARANTINE` (block on violation). Not supported for DOCKER and HELM. |
| `remote_url_suffix` | string       | Path suffix appended to the upstream URL. Python UPSTREAM with Custom source only. Leading and trailing slashes are normalized.                                         |
| `debian_config`     | block        | Debian-specific index settings. VIRTUAL + DEBIAN type only. Go to [`config.debian_config` block](#configdebian_config-block).                                           |

### config.auth block

Provides credentials for an UPSTREAM registry when `auth_type = "UserPassword"`.

| Argument                 | Type   | Description                                                                                                                             |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `auth_type`              | string | Required. Must be `UserPassword` or `Anonymous`.                                                                                        |
| `user_name`              | string | Username.                                                                                                                               |
| `secret_identifier`      | string | Identifier of the Harness secret that holds the password or token.                                                                      |
| `secret_space_path`      | string | Scope where the secret lives: `account_id`, `account_id/org_id`, or `account_id/org_id/project_id`. Defaults to `space_ref` when empty. |
| `access_key`             | string | (Sensitive) Raw access key value.                                                                                                       |
| `access_key_identifier`  | string | Identifier of the Harness secret for the access key.                                                                                    |
| `access_key_secret_path` | string | Scope of the access key secret.                                                                                                         |
| `secret_key_identifier`  | string | Identifier of the Harness secret for the secret key.                                                                                    |
| `secret_key_secret_path` | string | Scope of the secret key secret.                                                                                                         |

### config.debian\_config block

Controls Debian repository index generation for VIRTUAL + DEBIAN registries.

| Argument                             | Type         | Description                                                                    |
| ------------------------------------ | ------------ | ------------------------------------------------------------------------------ |
| `remote_indexed_architectures`       | list(string) | Architectures included in the index. Defaults to `["amd64", "i386", "arm64"]`. |
| `optional_index_compression_formats` | list(string) | Additional compression formats for metadata files, for example, `[".xz"]`.     |

***

## Examples

### Virtual registry

A client-facing registry that stores artifacts directly:

```hcl
resource "harness_platform_har_registry" "my_docker" {
  identifier   = "my-docker"
  space_ref    = "abc123/default/my-project"
  parent_ref   = "abc123/default/my-project"
  package_type = "DOCKER"

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

### Virtual registry with upstream proxy

Route cache misses through Docker Hub:

```hcl
resource "harness_platform_har_registry" "dockerhub_proxy" {
  identifier   = "dockerhub-proxy"
  space_ref    = "abc123/default/my-project"
  parent_ref   = "abc123/default/my-project"
  package_type = "DOCKER"

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

resource "harness_platform_har_registry" "my_docker" {
  identifier   = "my-docker"
  space_ref    = "abc123/default/my-project"
  parent_ref   = "abc123/default/my-project"
  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 with authenticated access

For private registries or Docker Hub authenticated pulls:

```hcl
resource "harness_platform_har_registry" "my_maven_proxy" {
  identifier   = "my-maven-proxy"
  space_ref    = "abc123/default/my-project"
  parent_ref   = "abc123/default/my-project"
  package_type = "MAVEN"

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

    auth {
      auth_type         = "UserPassword"
      user_name         = "deploy-user"
      secret_identifier = "nexus-deploy-token"
      secret_space_path = "abc123/default/my-project"
    }
  }
}
```

### Registry with artifact filtering and metadata

Restrict which artifacts can be pushed and attach labels:

```hcl
resource "harness_platform_har_registry" "prod_npm" {
  identifier   = "prod-npm"
  space_ref    = "abc123/default/my-project"
  parent_ref   = "abc123/default/my-project"
  package_type = "NPM"
  description  = "Production npm registry, scoped packages only"

  allowed_pattern = ["@myorg/.*"]
  blocked_pattern = [".*-beta$", ".*-alpha$"]

  metadata = {
    env    = "prod"
    team   = "platform"
    owner  = "platform@example.com"
  }

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

### Debian virtual registry with custom index settings

```hcl
resource "harness_platform_har_registry" "my_debian" {
  identifier   = "my-debian"
  space_ref    = "abc123/default/my-project"
  parent_ref   = "abc123/default/my-project"
  package_type = "DEBIAN"

  config {
    type             = "VIRTUAL"
    upstream_proxies = ["debian-upstream"]

    debian_config {
      remote_indexed_architectures       = ["amd64", "arm64"]
      optional_index_compression_formats = [".xz"]
    }
  }
}
```

### Dependency Firewall in quarantine mode

Block and quarantine artifacts that violate policies on pull:

```hcl
resource "harness_platform_har_registry" "my_npm" {
  identifier   = "my-npm"
  space_ref    = "abc123/default/my-project"
  parent_ref   = "abc123/default/my-project"
  package_type = "NPM"

  config {
    type             = "VIRTUAL"
    upstream_proxies = ["npm-upstream"]
    firewall_mode    = "QUARANTINE"
  }
}
```

***

## Import

Import an existing registry into Terraform state using the resource's scope path and identifier.

```bash
# Project-level registry
terraform import harness_platform_har_registry.example \
  "<account_id>/<org_id>/<project_id>/<registry_identifier>"

# Org-level registry
terraform import harness_platform_har_registry.example \
  "<account_id>/<org_id>/<registry_identifier>"

# Account-level registry
terraform import harness_platform_har_registry.example \
  "<account_id>/<registry_identifier>"
```

After import, run `terraform plan` to confirm there are no unexpected diffs before applying changes.

***

## Supported package types

Valid values for the `package_type` argument:

| Value               | Format                           |
| ------------------- | -------------------------------- |
| `DOCKER`            | Docker container images          |
| `HELM`              | OCI-compliant Helm charts        |
| `HELM_HTTP`         | HTTP (non-OCI) Helm charts       |
| `MAVEN`             | Maven artifacts                  |
| `PYTHON`            | Python / PyPI packages           |
| `NPM`               | npm packages                     |
| `NUGET`             | NuGet / .NET packages            |
| `GENERIC`           | Generic / Raw files              |
| `RPM`               | RPM packages                     |
| `CARGO`             | Cargo (Rust) packages            |
| `GO`                | Go modules                       |
| `CONDA`             | Conda packages                   |
| `DEBIAN`            | Debian / APT packages            |
| `ALPINE`            | Alpine / APK packages            |
| `WOLFI`             | Wolfi APK packages               |
| `CONAN`             | Conan (C/C++) packages           |
| `RUBY`              | RubyGems                         |
| `TERRAFORM`         | Terraform modules and providers  |
| `TERRAFORM_BACKEND` | Terraform state backend          |
| `CRAN`              | R / CRAN packages                |
| `COMPOSER`          | PHP Composer packages            |
| `DART`              | Dart packages                    |
| `SWIFT`             | Swift packages                   |
| `HUGGINGFACE`       | Hugging Face models and datasets |
| `PUPPET`            | Puppet modules                   |
| `RAW`               | Raw file storage                 |

***

## Troubleshooting

<details>

<summary>terraform apply returns "undefined response type" for a registry resource</summary>

The registry may have been created despite the error. Check the Harness UI. If the registry exists, import it with `terraform import harness_platform_har_registry.<name> '<space_ref>/<identifier>'`, then run `terraform init -upgrade` to pull the latest provider and retry `terraform apply`.

</details>

<details>

<summary>terraform import fails with "not found"</summary>

The import path must be exactly `account_id/org_id/project_id/registry_identifier` with no leading or trailing slashes and no `https://` prefix. Confirm the registry identifier matches what appears in the Harness UI, not the display name.

</details>

<details>

<summary>Authentication errors from the provider when managing registries</summary>

Use `platform_api_key` with a Next Gen API key, not the legacy `api_key`. Confirm the token has Create/Edit permissions on registries in the target project. Verify `space_ref` and `parent_ref` match `account_id/org_id/project_id` exactly, including letter case.

</details>

<details>

<summary>upstream_proxies order is not preserved after apply</summary>

Terraform may reorder the `upstream_proxies` list on subsequent plans. Use explicit ordering in your configuration and check the provider changelog for fixes if this affects pull resolution in your setup.

</details>

## Next steps

* [Create a registry](https://developer.harness.io/artifact-registry/3.0/registries/create-a-registry.md)
* [Create an upstream proxy](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md)
* [Set artifact filtering rules](https://developer.harness.io/artifact-registry/3.0/registries/set-artifact-filtering-rules.md)
* [CLI reference](https://developer.harness.io/artifact-registry/3.0/reference/cli.md)
* [Harness Terraform provider](https://registry.terraform.io/providers/harness/harness/latest/docs/resources/platform_har_registry) on the Terraform Registry

{% @harness-feedback/feedback %}
