Harness Cloud Byoi

Create custom VM images with your tools pre-installed for faster CI builds on Harness Cloud.

Prerequisites

Harness CI Enterprise license
CI_ENABLE_BYOI_HOSTED feature flag enabled (contact Harness support)
Harness Cloud infrastructure (not self-hosted runners)

Quick Start

1. Create a Packer File

Add a .pkr.hcl file to your repository with your customizations:

# packer/my-image.pkr.hcl <a href="#packermy-imagepkrhcl" id="packermy-imagepkrhcl"></a>

# Optional: Define variables for reusability <a href="#optional-define-variables-for-reusability" id="optional-define-variables-for-reusability"></a>
variable "node_version" {
  type    = string
  default = "20"
}

# Install your tools <a href="#install-your-tools" id="install-your-tools"></a>
provisioner "shell" {
  inline = [
    "sudo apt-get update",
    "sudo apt-get install -y nodejs npm python3",
    "sudo npm install -g typescript yarn"
  ]
}

# Copy config files (optional) <a href="#copy-config-files-optional" id="copy-config-files-optional"></a>
provisioner "file" {
  source      = "configs/settings.json"
  destination = "/tmp/settings.json"
}

provisioner "shell" {
  inline = ["sudo mv /tmp/settings.json /etc/myapp/"]
}

2. Build the Image

Add this step to your pipeline:

- step:
    type: Plugin
    name: Build Image
    spec:
      connectorRef: account.dockerhub
      image: harness/byoi-builder:1.0.0
      settings:
        mode: build
        packerFilePath: packer/my-image.pkr.hcl
        targetOs: linux
        targetArch: amd64
        imageName: my-dev-image
        imageVersion: v1
        baseImage: ubuntu/22.04

3. Use the Image

Reference it in your stage configuration:

- stage:
    type: CI
    spec:
      platform:
        os: Linux
        arch: Amd64
      runtime:
        type: Cloud
        spec:
          imageSpec:
            imageName: my-dev-image:v1
      execution:
        steps:
          - step:
              type: Run
              spec:
                command: node --version  # Pre-installed!

LINUX AND WINDOWS BYOI IMAGES ARE STORED AND SERVED BY HARNESS

Reference the image by imageName:imageVersion only. Linux and Windows BYOI do not support supplying a custom image connector (for example, the Override Image Connector stage infrastructure setting) to pull the VM image from your own registry. The image must be built with the Harness BYOI builder plugin and served from Harness-managed storage to be used with Linux or Windows BYOI.

Plugin Settings

Build Mode

Setting

Required

Default

Description

mode

build

Operation mode: build or delete

packerFilePath

Yes

Path to your Packer file (relative to repo root)

imageName

Yes

Image name (3-30 chars, lowercase letters, numbers, hyphens)

imageVersion

Yes

Version tag (1-20 chars, alphanumeric and hyphens)

targetOs

linux

Target operating system: linux or windows

targetArch

amd64

Target architecture: amd64 or arm64. Windows supports amd64 only.

baseImage

ubuntu/22.04

Base image to build from (see Supported Base Images)

dockerVersion

28

Docker version to pre-install (e.g., 28, 27)

debug

false

Enable verbose Packer logging

Delete Mode

To rebuild with the same version, delete the existing image first:

- step:
    type: Plugin
    name: Delete Image
    spec:
      connectorRef: account.dockerhub
      image: harness/byoi-builder:1.0.1
      settings:
        mode: delete
        imageName: my-dev-image
        imageVersion: v1

Supported Base Images

Linux

Base Image

Architectures

ubuntu/24.04

amd64, arm64

ubuntu/22.04

amd64, arm64

Windows

Base Image

Architectures

windows-server/2022

amd64

windows-server/2025

amd64

The BYOI builder plugin also accepts windows-server/2019, but that version is not yet qualified to run as CI VMs on Harness Cloud. Use windows-server/2022 or windows-server/2025 for Windows BYOI images intended to run on Harness Cloud.

Advanced options:

Type

Format

Example

Harness pre-configured

{name}

ubuntu-v1-hosted-amd64

Your previous BYOI image

byoi-{sanitizedAccountId}-{imageName}-{version}

byoi-abc123-my-base-v1

To use a previous BYOI image, specify the full image name (as shown in build output), not imageName:version.

Note: Account IDs are sanitized in image names: lowercase, _ becomes -, and special characters are removed. For example, if your account ID is My_Account_123, your images are stored as byoi-my-account-123-....

Writing Your Packer File

You provide variables and provisioners. Harness handles source configuration, authentication, and cleanup automatically.

Example with Variables

# Define reusable variables <a href="#define-reusable-variables" id="define-reusable-variables"></a>
variable "java_version" {
  type    = string
  default = "17"
}

variable "maven_version" {
  type    = string
  default = "3.9.6"
}

# Install Java <a href="#install-java" id="install-java"></a>
provisioner "shell" {
  inline = [
    "sudo apt-get update",
    "sudo apt-get install -y openjdk-${var.java_version}-jdk"
  ]
}

# Install Maven <a href="#install-maven" id="install-maven"></a>
provisioner "shell" {
  inline = [
    "wget -q https://archive.apache.org/dist/maven/maven-3/${var.maven_version}/binaries/apache-maven-${var.maven_version}-bin.tar.gz",
    "sudo tar -xzf apache-maven-${var.maven_version}-bin.tar.gz -C /opt",
    "sudo ln -s /opt/apache-maven-${var.maven_version} /opt/maven",
    "rm apache-maven-${var.maven_version}-bin.tar.gz"
  ]
}

Copying Files

# Copy files from your repo into the image <a href="#copy-files-from-your-repo-into-the-image" id="copy-files-from-your-repo-into-the-image"></a>
provisioner "file" {
  source      = "configs/app.conf"
  destination = "/tmp/app.conf"
}

provisioner "shell" {
  inline = ["sudo mv /tmp/app.conf /etc/myapp/app.conf"]
}

What Harness Adds Automatically

Linux:

Git, Git LFS, wget, curl, CA certificates
Docker (configurable version)
git safe.directory * configuration
HOME environment variable
Cleanup (apt cache, logs) to reduce image size

What Gets Ignored

If your Packer file contains source or build blocks, they will be ignored. Harness uses its own secure configuration. Only your variable and provisioner blocks are used.

Limitations

Image Naming

imageName: 3-30 characters, must start with lowercase letter
imageVersion: 1-20 characters, must start/end with alphanumeric
Combined length of imageName + imageVersion should not exceed ~35 characters (the full name includes your account ID)

Platform

Linux: Ubuntu (amd64 and arm64)
Windows: Windows Server 2022 or 2025 (amd64 only). The builder plugin also accepts windows-server/2019, but that version is not yet qualified to run as CI VMs on Harness Cloud.
macOS: Coming soon
Harness Cloud only. Self-hosted runners are not supported.

Image storage and registry

Linux and Windows BYOI images must be built with the Harness BYOI builder plugin and are stored in Harness-managed storage.
Linux and Windows BYOI do not support supplying a custom image connector. The Override Image Connector stage infrastructure setting does not apply to the Linux or Windows BYOI VM image, so you cannot point Linux or Windows BYOI at an image hosted in your own registry.
Reference Linux and Windows BYOI images by imageName:imageVersion only. To build on top of an existing image, go to Supported Base Images to use the full Harness-managed image name as baseImage.
This restriction applies only to the BYOI VM image. Step-level image: fields inside your pipeline (for example, on a Run step) continue to honor their own connectorRef and can pull from any registry as usual.

Build Process

Maximum build time: 3 hours (bounded by authentication token lifetime)
Automatic retries: 3 attempts on transient failures
Disk size: 100GB
Cannot build same image name/version concurrently

Security

Do not include credentials in your Packer file. The following patterns will cause the build to fail:

credentials = "..."
account_file = "..."
access_token = "..."

Harness injects credentials securely.

Troubleshooting

Issue

Solution

Build fails

Set debug: "true" to see detailed Packer output

"Image name too long" error

Shorten imageName or imageVersion

"Image already exists" error

Use mode: delete first, or use a different version

Packer file not found

Check packerFilePath is relative to repo root

Authentication error

Contact Harness support

Build times out

The maximum build time is 3 hours.

FAQ

Can I use my image across all projects? Yes, BYOI images are available to all projects in your account.

Can I build on ARM64? Yes, set targetArch: arm64 in your plugin settings (Linux only).

Can I build on top of a previous BYOI image? Yes. Use the full image name from your previous build output as baseImage. For example: baseImage: byoi-abc123-my-base-v1 (not my-base:v1). Note that the account ID in the image name is sanitized (lowercase, _ → -, special chars removed). You can only use your own account's BYOI images.

Can I host my Linux or Windows BYOI image in my own registry and pull it with an image connector? No. Linux and Windows BYOI do not support supplying a custom image connector, and the Override Image Connector stage infrastructure setting does not apply to the Linux or Windows BYOI VM image. The image must be built with the Harness BYOI builder plugin and served from Harness-managed storage. Reference it by imageName:imageVersion.

Do I need to set mode to build? No, build is the default mode. You only need to explicitly set mode: delete when deleting an image.

What is the maximum build time? 3 hours, bounded by the GCP authentication token lifetime. If your build needs more time, optimize your Packer provisioners.

Support

If you encounter issues:

Enable debug: "true" for verbose logs
Check the error message against the troubleshooting table above
Contact Harness support

PreviousFeature Flags Reference

NextPipeline Infrastructure Setup

Last updated 7 days ago

Was this helpful?