> 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/harness-solutions-factory/use-hsf/workflows/delegate-image-factory-workflow.md).

# Delegate Image Factory Workflow

Harness Delegate Image Factory helps teams create and manage custom delegate images when the default Harness delegate does not meet enterprise requirements. It provides a controlled, repeatable process for building, versioning, and releasing custom delegates, with a pre-optimized Dockerfile and configuration included out of the box.

### When to use this workflow <a href="#when-to-use-this-workflow" id="when-to-use-this-workflow"></a>

Use Delegate Image Factory when your enterprise environment requires delegates that the default Harness delegate image does not support. Common scenarios include:

* **Adding tools not bundled with the default delegate:** for example, AWS CLI, Azure CLI, or custom internal utilities required by your CD or pipeline workloads.
* **Embedding enterprise CA certificates and Java trust stores:** avoids x509 certificate errors in environments with internal PKI.
* **Installing custom utilities:** any tooling your pipelines depend on that is not available in the default delegate image.

If the default Harness delegate meets your needs, you do not need this workflow.

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* HSF is deployed and post-deployment configuration is complete.
* You have the certificates, tools, or utilities you want to bake into the delegate image ready to reference.
* A container registry is configured and accessible. If you have not set one up yet, run [Harness Central Build Farm Setup](/harness-solutions-factory/use-hsf/workflows/central-build-farm-workflow.md) first.
* You have been added to the **HSF Users** or **HSF Admins** group.

### Inputs <a href="#inputs" id="inputs"></a>

| Input               | Description                                              |
| ------------------- | -------------------------------------------------------- |
| Delegate image name | The name for your custom delegate image                  |
| Container registry  | Where the built image will be pushed                     |
| Tools to install    | Additional tools or utilities to include in the image    |
| Certificates        | Enterprise CA certificates or Java trust stores to embed |

### What gets created <a href="#what-gets-created" id="what-gets-created"></a>

| Resource       | Details                                                                                                                             |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Pipeline       | A build pipeline that builds, versions, and pushes your custom delegate image                                                       |
| Repository     | `harness-delegate-factory`: contains a pre-optimized Dockerfile and configuration files for embedding certificates and trust stores |
| IaCM workspace | In the Solutions Factory project                                                                                                    |

#### Expected output <a href="#expected-output" id="expected-output"></a>

After the workflow completes:

* [ ] The `harness-delegate-factory` repository is visible in **Harness Code Repository** (or your configured SCM).
* [ ] A delegate build pipeline is visible in the Solutions Factory project.
* [ ] The IaCM workspace appears in **IaCM** → **Workspaces**.
* [ ] An IDP catalog entry for the workspace is registered automatically.

### Post setup: build and deploy your delegate <a href="#post-setup-build-and-deploy-your-delegate" id="post-setup-build-and-deploy-your-delegate"></a>

Once the workflow completes, run the delegate build pipeline to produce your first custom delegate image. After the image is built and pushed to your container registry:

1. Create a new delegate in Harness using the custom image. Go to [Install a delegate](/harness-ai/use-harness-platform/delegates/delegate/install-delegates/overview.md) for instructions.
2. Verify the delegate is connected and healthy in **Account Settings** → **Delegates**.

### Making changes <a href="#making-changes" id="making-changes"></a>

To update the delegate configuration, for example to add a new tool or rotate certificates, navigate to the workspace in **IaCM** → **Workspaces**, update the relevant variable, re-execute the workspace, and then re-run the build pipeline to produce an updated image.

{% hint style="info" %}
Pin your custom delegate images to specific version tags in your pipelines rather than using `latest`. This ensures a certificate rotation or tooling update does not automatically roll out to running pipelines until you are ready.
{% endhint %}