Skip to main content

Install Harness Delegate 2.0 (Closed Beta)

Closed Beta

Delegate 2.0 is currently in closed beta, and is available for select customers only. Access is determined by the product team, and is based on current supported use cases and steps.

This guide describes how to install the new Harness Delegate to local machines. Skip to the End to End Demo if you want to watch video instructions for the new delegate installation.

Important

Harness Delegate 2.0 is under Beta and can only be used for Mac Build, Android Build, and CI Stage Pipelines with limited sets of steps and connector support.

What's Supported​

Supported Connectors​

ConnectorCaveats
Docker RegistryOnly the DockerHub provider type
GithubDoes not work with Github App OAuth.
HashiCorp VaultOnly AppRole and Token Auth; set Renewal Interval to 0 (zero)
AWS Secrets ManagerOnly Access Key and IAM Role Credential Type

Supported CI Steps​

Step NameCaveats
Git CloneOnly for Github
Run
Docker Build and Push

Delegate Installation Instructions​

Get Relevant Information​

In order to install the delegate, you will need:

  • ACCOUNT_ID
  • DELEGATE_TOKEN
  • MANAGER_HOST_AND_PORT

To get this information, do the following:

Download and Install the Delegate​

Download and install the correct binary for your OS.

  1. Download the binary for your system
curl --output harness-runner 'https://storage.googleapis.com/harness-qa-public/public/shared/runner/1.17.0/runner-darwin-arm64'
  1. Give it permission to execute
chmod +x harness-runner
  1. Install the delegate and create the config.env file
./harness-runner install --account=[Account ID] \
                       --token=[Delegate Token] \
                       --url=[Harness URL]  \
                       --tags="macos-arm64" \
                       --name=[Your Delegate Name]
  1. Start the delegate as service.
./harness-runner start

Navigate to Project Settings > Delegates. You should see your new delegate in the delegates list.

info

If you don't set a name for your delegate, it will default to harnessRunner

Configure Pipeline Delegate​

For the CI stages that you want to use the new delegate with, define the stage variable HARNESS_CI_INTERNAL_ROUTE_TO_RUNNER and set it to true.

Then, in order for the pipeline to select this delegate, set your pipeline's build infrastructure as normal.

Most importantly, ensure that you have set Local as the Infrastructure and that the Operating System and Architecture match the delegate you installed in the download and install delegate step.

Delegate Configuration​

Here is where the config.env file is located for each operating system:

  • MacOS: The config.env file is located in ~/.harness-runner/config.env (after you run the ./harness-runner install command).
  • Linux: The config.env file is created by the user during step 3 of linux runner installation. The file will be where you created it at that point in time.

Set Max Stage Capacity​

With Harness Delegate 2.0, you can configure a limit for the maximum number of stages the delegate will be executing at a given time. When the delegate is handling tasks at full capacity, new tasks will be queued and picked up once the delegate's capacity is freed.

In order to configure a max limit for number of stages executed by a delegate, you should add a MAX_STAGES variable in the delegate's config.env file. The value of the MAX_STAGES should be a positive integer.

Example config.env​

If you wanted the delegate to only execute up to 5 stages a time, set MAX_STAGES=5. For example:

ACCOUNT_ID="<ACCOUNT_ID>"
TOKEN="<DELEGATE_TOKEN>"
TAGS="<your delegate tags>"
URL="<MANAGER_HOST_AND_PORT>"
NAME="<your delegate name>"
...
MAX_STAGES=5

Set Graceful Shutdown​

With Harness Delegate 2.0, you can configure a grace period to allow for a clean shutdown of running containers and processes when a pipeline execution is aborted. This ensures that any resources started by the pipeline are given time to terminate gracefully before being forcefully removed.

To configure this grace period, add the CLEANUP_GRACE_PERIOD_SECONDS variable to the delegate's config.env file. The value should be a non-negative integer representing the number of seconds to wait before forcefully terminating resources.

If the grace period is set to 0 (default), the delegate will immediately send a SIGKILL signal to stop containers and processes. If a positive value is configured, the delegate will first send a SIGTERM signal. After the grace period expires, any resources that are still running will be terminated with a SIGKILL.

Example config.env​

If you want the delegate to wait up to 30 seconds before forcefully stopping any running containers or processes, set CLEANUP_GRACE_PERIOD_SECONDS=30. For example:

ACCOUNT_ID="<ACCOUNT_ID>"
TOKEN="<DELEGATE_TOKEN>"
TAGS="<your delegate tags>"
URL="<MANAGER_HOST_AND_PORT>"
NAME="<your delegate name>"
...
CLEANUP_GRACE_PERIOD_SECONDS=30

Debugging​

Logs​

You can find the delegate logs in the following files:

  • MacOS: ~/Library/Logs/harness.runner/stderr.log
  • Linux: nohup-runner.out

End to End Demo​

This video walks through an end to end demo of the delegate installation, including usage and a pipeline execution.