> 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/infrastructure-as-code-management/platform/iacm-pipelines/plugin-images.md).

# Custom images

Build and configure custom plugin images for IACM pipeline steps using the UI or YAML.

Harness lets you use custom plugin images in your IACM pipeline steps. Custom images extend the default Harness base image with your own binaries, providers, or certificates, and are configured per step. You can specify a custom image for Terraform, OpenTofu, Terragrunt, and CDK steps.

## Before you begin

* A Harness project with an IACM stage and at least one IaCM step configured.
* A container registry accessible from your pipeline environment (for private images).
* A Harness connector for the container registry, if the image is in a private registry.

## Network connectivity requirements

OpenTofu steps connect to external services to download binaries, modules, and providers. Verify that your infrastructure allows outbound access to the following domains:

* `get.opentofu.org`: required to download OpenTofu binaries.
* `registry.opentofu.org`: required to resolve and download providers and modules.
* `github.com`: required to access provider and module resources.
* `packages.opentofu.org` (optional): required only for Red Hat-based installations. You can bypass it by pre-caching binaries in your shared file system.

In air-gapped environments, pre-install the required providers and modules in a custom image so the pipeline does not attempt to download them during `tofu init`.

## Create an image <a href="#create-an-image" id="create-an-image"></a>

Harness lets you build custom images from the provided base image. The base image includes the OpenTofu or Terraform binary and common dependencies. Extend it with the additional binaries, providers, or certificates your workflow requires.

{% hint style="warning" %}
Custom images are version-locked to the base image tag they were built from. They do not update automatically when Harness releases a new base image. Harness logs a warning when your image is five versions behind the latest release. Rebuild your custom image periodically to avoid security vulnerabilities and compatibility issues.
{% endhint %}

Create custom images with root-based and rootless containers for **Harness Cloud** and **Kubernetes** environments. The following examples show package installation using `microdnf` and direct binary installation for tools like `kubectl`.

{% tabs %}
{% tab title="Root-based custom container" %}
Create a root-based custom container for use in **Harness Cloud** and **Docker**.

Once your image is created, build with: `docker build -f Dockerfile --platform linux/amd64 --target custom-root -t harness_terraform_vm_custom .`

```sh
FROM plugins/harness_terraform_vm AS custom-root

# Install a package using the built-in microdnf package manager
RUN microdnf install -y wget
RUN microdnf clean all

# Download and install a binary directly (binaries must target the amd64 architecture)
RUN curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
RUN install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
```

{% endtab %}

{% tab title="Rootless custom container" %}
Create a custom container for use in **Kubernetes**.

Once your image is created, build with: `docker build -f Dockerfile --platform linux/amd64 --target custom-rootless -t harness_terraform_custom .`

```sh
FROM plugins/harness_terraform AS custom-rootless

# Switch to root temporarily to install extra tools
USER root

# Install a package using the built-in microdnf package manager
RUN microdnf install -y wget
RUN microdnf clean all

# Download and install a binary directly (binaries must target the amd64 architecture)
RUN curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
RUN install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# Switch back to the harness user after installation
USER harness
```

{% endtab %}
{% endtabs %}

<details>

<summary>Cloud v0.56 or later</summary>

For cloud environments, version 0.56 and later images no longer run as root. If you need the image to use the root user, use the following code:

```sh
FROM plugins/harness_terraform_vm:0.62.0
USER root
RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
RUN unzip awscliv2.zip
RUN ./aws/install
RUN aws --version
RUN curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
RUN install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
RUN curl -LO "https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv5.3.0/kustomize_v5.3.0_linux_amd64.tar.gz" \
    && tar xzf kustomize_v5.3.0_linux_amd64.tar.gz \
    && mv kustomize /usr/local/bin/kustomize \
    && rm kustomize_v5.3.0_linux_amd64.tar.gz
```

</details>

## Use your own image <a href="#use-your-own-image" id="use-your-own-image"></a>

You can configure a custom image for each IACM step through the pipeline UI or by editing the YAML directly. Both methods are supported for Terraform, OpenTofu, Terragrunt, and CDK steps.

### Configure through the UI <a href="#configure-through-the-ui" id="configure-through-the-ui"></a>

To configure a custom image through the UI:

1. In your pipeline, select an IACM step (for example, **init**, **plan**, or **apply**).
2. Scroll to and expand **Optional Configuration**.
3. Under **Container Registry**, select a connector for the registry where your image is stored. Connectors can be scoped at the project, organization, or account level.
4. Under **Image**, enter the full image path including the tag (for example, `demo-org/harness_terraform_custom:latest`).

![IACM step Optional Configuration panel showing a project-scoped Container Registry connector and an image path](https://3575326923-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ffhx6XzjvtJmfv5gPWZ5m%2Fuploads%2Fgit-blob-49dc24edac59e0e3939efef4c9b467fce0062d6e%2Fiacm-plugin-image-optional-configuration.png?alt=media)

{% hint style="info" %}
Both the **Container Registry** and **Image** fields are required to use a custom plugin image.
{% endhint %}

### Configure through YAML <a href="#configure-through-yaml" id="configure-through-yaml"></a>

To configure a custom image in the YAML, add the `image` and `connectorRef` fields to the step spec:

```yaml
- step:
    type: IACMTerraformPlugin
    name: apply
    identifier: apply
    timeout: 2h
    spec:
        command: apply
        image: plugins/private_harness_terraform_plugin  # (1)
        connectorRef: privateConnector  # (2)
```

{% hint style="info" %}
The `image` attribute **(1)** points to the plugin image in your container registry.

If the image is in a private registry, create a connector and set `connectorRef` **(2)** to give Harness access.
{% endhint %}

***

## IACM execution-config <a href="#iacm-execution-config" id="iacm-execution-config"></a>

Use the `execution-config` API to override supported IaCM execution images at the account level. These overrides apply to the IaCM stage infrastructure images listed below and are separate from the custom plugin image you configure for an individual pipeline step.

{% hint style="info" %}
Overrides specified using the IACM `execution-config` APIs are not applied to CI stages, and CI overrides are not applied to IACM stages. Some images are shared, but the override scope is separate. The images you can override are:

* harness/ci-addon.
* harness/ci-lite-engine.
* harness/drone-git.
* plugins/harness\_terraform.
  {% endhint %}

{% tabs %}
{% tab title="Set images" %}
Set your images with the `update-config` endpoint:

```sh
curl \
-X POST \
-H 'x-api-key: <pat>' \
'https://app.harness.io/gateway/iacm-manager/execution-config/update-config?accountIdentifier=<account>&infra=k8' \
--header 'Content-Type: application/json' \
--data-binary @- << EOF
[
    {
        "field": "addonTag",
        "value": "<your_repo>/ci-addon:1.16.44"
    },
    {
        "field": "liteEngineTag",
        "value": "<your_repo>/ci-lite-engine:1.16.37"
    },
    {
        "field": "gitCloneTag",
        "value": "<your_repo>/drone-git:1.5.0-rootless"
    },
    {
        "field": "IACMTerraformTag",
        "value": "<your_repo>/harness_terraform:latest"
    },
    {
        "field": "IACMOpentofuTag",
        "value": "<your_repo>/harness_terraform:latest"
    }
]
EOF
```

{% endtab %}

{% tab title="Reset default images" %}
Reset the images back to the defaults with the `reset-config` endpoint:

```sh
curl \
-X POST \
-H 'x-api-key: <pat>' \
'https://app.harness.io/gateway/iacm-manager/execution-config/reset-config?accountIdentifier=<account>&infra=k8' \
--header 'Content-Type: application/json' \
--data-binary @- << EOF
[
    {
        "field": "addonTag"
    },
    {
        "field": "liteEngineTag"
    },
    {
        "field": "gitCloneTag"
    },
    {
        "field": "IACMTerraformTag"
    },
    {
        "field": "IACMOpentofuTag"
    }
]
EOF
```

{% endtab %}

{% tab title="List custom images" %}
View your custom images using the `get-customer-config` endpoint:

```sh
curl \
-H 'x-api-key: <pat>' \
'https://app.harness.io/gateway/iacm-manager/execution-config/get-customer-config?accountIdentifier=<account>&infra=k8'
```

{% endtab %}

{% tab title="View default images" %}
View the default images using the `get-default-config` endpoint:

```sh
curl \
-H 'x-api-key: <pat>' \
'https://app.harness.io/gateway/iacm-manager/execution-config/get-default-config?accountIdentifier=<account>&infra=k8'
```

{% endtab %}
{% endtabs %}

## Next steps

* Go to [Custom images for OpenTofu](https://developer.harness.io/infrastructure-as-code-management/use-iacm/iac-provisioners/opentofu/custom-images.md) to review OpenTofu-specific scenarios and version compatibility considerations.
* Go to [Plugin binary directory](https://developer.harness.io/infrastructure-as-code-management/platform/iacm-connectors-variables/iacm-plugins/plugin-binary-dir.md) to pre-bake provisioner binaries in a custom image and avoid runtime downloads.
* Go to [Plugin CA certificate path](https://developer.harness.io/infrastructure-as-code-management/platform/iacm-connectors-variables/iacm-plugins/plugin-ca-cert-path.md) to add custom CA certificates to your plugin image for internal endpoints.

{% @harness-feedback/feedback %}
