Delegates Overview

Updated 1 month ago by Michael Cretzman

The Harness Delegate is a service you run in your local network or VPC to connect all of your artifact, infrastructure, collaboration, verification and other providers with the Harness Manager.

When you connect Harness to a third party resource for the first time, you install a Harness Delegate in your target infrastructure (for example, Kubernetes cluster). 

Once the Delegate is installed, you connect to your third party resources.

Most importantly, the Delegate performs all deployment, integration, and other operations.

Looking for How-tos? See Delegate How-tos.

In this article:

Limitations and Requirements

See Delegate Requirements and Limitations.

What Data does the Delegate Send to the Harness Manager?

The Delegate connects to the Harness Manager via an outbound HTTPS/WSS connection:

The Delegate and the Harness Manager (via SaaS) establish a Secure WebSocket channel (WebSocket over TLS) to send new Delegate task event notifications (not the tasks themselves) and exchange connection heartbeats. In the case that the WebSocket connection is dropped, the Harness Delegate falls back to outbound-only, polling-based task fetch.

  • Heartbeat - The Delegate sends a heartbeat to let the Harness Manager know that it is running.
  • Deployment data - The information from the API executions the Delegate performs are sent to the Manager for display in the Deployments page.
  • Time series and log data for Continuous Verification - The Delegate connects to the verification providers you have configured and sends their data to the Manager for display in Harness Continuous Verification.

Where do I Install the Delegate?

  • Evaluating Harness - When evaluating Harness, you might want to install the Delegate locally. Ensure that it has access to the artifact sources, deployment environments, and verification providers you want to use with Harness.
  • Development, QA, and Production - The Delegate should be installed behind your firewall and in the same VPC as the micro-services you are deploying. The Delegate must have access to the artifact servers, deployment environments, and cloud providers it needs.

Install the Harness Delegate

See the following topics:

Delegate Sizes

One Delegate size does not fit all use cases, so Harness let's you pick from several options:

Remember that the memory and CPU requirements are for the Delegate only. You Delegate host/pod/container will need more computing resources for its operations systems and other services such as Docker or Kubernetes.

How Does Harness Manager Identify Delegates?

All Delegates are identified by your Harness account ID. Depending on the type of Delegate, there are additional factors.

For Delegates running on virtual machines, such as the Shell Script and Docker Delegates running on an AWS EC2 instance, the Delegate is identified by the combination of Hostname and IP.

Therefore, if the hostname or IP changes on the VM, the Delegate cannot be identified by the Harness Manager. The IP used is the private IP. The Delegate connects to the Harness Manager, but the Harness Manager does not initiate a connection to the Delegate, and so the public IP address of the Delegate is not needed, typically.

For Kubernetes Delegates, the IP can change if a pod is rescheduled, for example. Consequently, Kubernetes Delegates are identified by a suffix using a unique six letter code in their Hostname (the first six letters that occur in your account ID).

How Does Harness Manager Pick Delegates?

Delegates are used by Harness for all operations. For example:

  • Connectors: Connectors are used for all third-party connections.
  • Pipeline Services and Infrastructure: Connectors are used in Pipeline Service connections to repos and Pipeline Infrastructure connections to target environments (deployment targets, build farms, etc).
  • Pipeline Steps: you can select a Delegate in each Pipeline step to ensure that the step only uses that Delegate to perform its operation.

In the case of all these Delegate uses, you can select that one or more specific Delegates perform the operation (using Delegate Tags). If you do not specify specific Delegates, then Harness will assign the task to a Delegate.

Task Assignment

In cases where you have selected specific Delegates to perform the task, Harness uses those Delegate only. If these Delegates cannot perform the task, Harness does not use another Delegate.

In cases where you do not select specific Delegates, Harness uses any available Delegate to perform the task. Harness uses the follow process and criteria to pick a Delegate.

When a task is ready to be assigned, the Harness Manager first validates its lists of Delegates to see which Delegate should be assigned the task.

The following information describes how the Harness Manager validates and assigns tasks to a Delegate:

  • Heartbeats - Running Delegates send heartbeats to the Harness Manager in 1 minute intervals. If the Manager does not have a heartbeat for a Delegate when a task is ready to be assigned, it will not assign the task to that Delegate.
  • Tags - For more information, see Select Delegates with Tags.
  • Whitelisting - Once a Delegate has been validated for a task, it is whitelisted for that task and will likely be used again for that task. The whitelisting criteria is the URL associated with the task, such as a connection to a cloud platform, repo, or API. A Delegate is whitelisted for all tasks using that URL. The Time-To-Live (TTL) for the whitelisting is 6 hours, and the TTL is reset with each successful task validation.
  • Blacklisting - If a Delegate fails to perform a task that Delegate is blacklisted for that task and will not be tried again. TTL is 5 minutes. This is true if there is only one Delegate and even if the Delegate is selected for that task with a Selector, such as with a Shell Script command in a Workflow.

Delegate Selection in Pipelines

As stated above, Delegates are selected in Service and Infrastructure Connectors and in steps.

For example, in the Infrastructure section of a stage, there is a Connector setting. For Harness CD, this is the Connector to the target infrastructure. For Harness CI, this is Connector to the build farm.

When you add Connectors to Harness, you can select several or all Delegates for the Connector to use.

Each CD step in the stage Execution has a Delegate Selector setting.

Here you use Delegate Tags to select the Delegate(s) to use.

Which Delegate is Used During Pipeline Execution?

The Delegates assigned to Connectors and steps are used during Pipeline execution.

If no Delegates are selected, then the Delegates are selected as described in Task Assignment.

If no Delegates are selected for a CD step in its Delegate Selector setting, Harness prioritizes the Delegate used successfully for the Infrastructure Connector.

Harness will try this Delegate first for the step task because this Delegate has been successful in the target environment.

Most CI steps use Connectors to pull the image of the container where the step will run. The Delegates used for the step's Connector are not necessarily used for running the step. In general, the Delegate(s) used for the Connector in the Infrastructure build farm is used to run the step.

Delegate High Availability (HA)

You might need to install multiple Delegates depending on how many Continuous Delivery tasks you do concurrently, and on the compute resources you are providing to each Delegate. Typically, you will need one Delegate for every 300-500 service instances across your applications.

In addition to compute considerations, you can enable High Availability (HA) for Harness Delegates. HA simply involves installing multiple Delegates in your environment.

For example, in Kubernetes deployments, you can set up two Kubernetes Delegates, each in its own pod in the same target K8s cluster. Simply edit the Kubernetes Delegate spec you download from Harness, harness-kubernetes.yaml, to have multiple replicas:

...
apiVersion: apps/v1beta1
kind: StatefulSet
metadata:
labels:
harness.io/app: harness-delegate
harness.io/account: xxxx
harness.io/name: test
name: test-zeaakf
namespace: harness-delegate
spec:
replicas: 2
selector:
matchLabels:
harness.io/app: harness-delegate
...

For the Kubernetes Delegate, you only need one Delegate in the cluster. Simply increase the number of replicas, and nothing else. Do not add another Delegate to the cluster in an attempt to achieve HA.
If you want to install Kubernetes Delegates in separate clusters, do not use the same harness-kubernetes.yaml and name for both Delegates. Download a new Kubernetes YAML spec from Harness for each Delegate you want to install. This will avoid name conflicts.

In every case, the Delegates need to be identical in terms of permissions, keys, connectivity, etc.

With two or more Delegates running in the same target environment, HA is provided by default. One Delegate can go down without impacting Harness' ability to perform deployments. If you want more availability, you can set up three Delegates to handle the loss of two Delegates, and so on.

Two Delegates in different locations with different connectivity do not support HA. For example, if you have a Delegate in a Dev environment and another in a Prod environment, the Dev Delegate will not communicate with the Prod Delegate or vice versa. If either Delegate went down, Harness would not operate in their environment.

Delegate Configurations

A Delegate Configuration enables you to run a startup script on the host/container/pod for a Harness Delegate during or after installation. You can create a single Delegate Configuration and apply it to multiple Delegates.

See Run Scripts on Delegates using Delegate Configurations.

Delegate Scope

Delegates are scoped in two ways:

Project/Org/Accounts

You can add Delegates at the Project, Org, and Account level. Delegate availability then becomes subject to Harness implicit Project, Org, and Account hierarchy.

For example, let's look at two users, Alex and Uri, and the Delegates (Dn) available to them:

Alex's Pipelines can use Delegates D1, D2, or D4.

Uri's Pipelines can use Delegates D1, D3, or D5.

Delegate Configurations

You can scope Delegates using Delegate Configurations.

The Scope settings let you select the Harness Environments that can use the Delegate.

Delegate Tags

When Harness makes a connection via its Delegates, it will select the best Delegate according to How Does Harness Manager Pick Delegates?.

To ensure a specific Delegate is used by a Harness entity, you can add Tags to Delegates and then reference the Tags in commands and Connectors.

See Select Delegates with Tags.

Delegate Log File

The Delegate creates a new log file each day, named delegate.log, and its maximum size is 50MB.

Every day the log file is saved with the day's date and a new log file is created.

If a log file grows beyond 50MB in a day, the log file is renamed with today's date and a new log file is created.

Harness keeps log files for today and the previous 10 days (up to one 1GB).

Delegate Permissions

You can set permissions on Delegates using Harness RBAC.

You create roles and then assign them to Harness Users.

There are role permissions for Delegates and Delegate Configurations:

The permissions are:

  • Delegate permissions: Create/Edit, Delete, View.
  • Delegate Configuration permissions: Create/Edit, Delete, View.

The Delegate View permission cannot be disabled. Every user has the permission to view the Delegate.

Access to a Delegate can also be restricted by downstream resource types:

  • Pipelines: Execute
  • Secrets: Access
  • Connectors: Access

This means that if a role does not have these permissions the User with that role cannot use the related Delegates in these Pipelines, Secrets, or Connectors.


Please Provide Feedback