Harness Delegate FAQs

Updated 1 week ago by Michael Cretzman

This article addresses some frequently asked questions about Harness Delegates.

Before You Begin

General

For an overview of Harness' support for platforms, methodologies, and related technologies, see Supported Platforms and Technologies.

What is the Harness Delegate?

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.

The Harness Platform has two components:

  • Harness Manager - Harness Manager is where your deployment configuration is stored and your pipelines are managed and executed. Harness Manager is available either as SaaS (running in the Harness cloud) or as Self-Managed (running in your infrastructure).
  • Harness Delegate - The Harness Delegate is software you install in your environment that connects to the Harness Manager and performs tasks by connecting to your container orchestration platforms, artifact repositories, monitoring systems, etc.

How is the Delegate updated?

There are two options.

Automatic

The Delegate updates automatically. The Delegate installation also installs a Watcher program that checks the Harness cloud periodically for new versions.

Watcher ensures there is exactly one Delegate process of each published version running.

If there is a published version that is not running, Watcher downloads the JAR file for that version securely over HTTPS, installs it, and updates the Delegate connection to the Harness Manager. There is no downtime.

Self-Managed

You update the Delegate. When you install a Delegate by downloading the Delegate YAML from Harness, you select the Self-Managed option.

The Delegate is upgraded using a Ring methodology commonly used in software release management.

The Delegate images are on Docker Hub and are tagged by version.

The Delegate image is signed. You can check it by running this command (with the current version number):

docker trust inspect --pretty harness/delegate-immutable:22.03.74407

Can same YAML be used to create automatic or Self-Managed Delegates?

No. The YAMLs for the two types are very different.

Can I create my own Delegate?

Yes. See Create a Custom Delegate that Includes Custom Tools.

How Does Harness Manager Identify Delegates?

All Delegates are identified by your Harness account ID. This is contained in the Delegate YAML.

Depending on the type of Delegate, there are additional factors.

For Delegates running on virtual machines, such as 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).

What data does the Delegate send to the Harness Manager?

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 pages such as 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.

Can I whitelist IPs for the Harness Delegate?

Yes. See Whitelist Harness Domains and IPs.

Do I need separate Delegates for different isolated environments?

No. Delegates connect to the Harness Manager and are tested for connectivity to resources and tasks.

Harness Connectors only use Delegates that can connect to their resources and perform their tasks.

You could even have a Delegate in one cloud platform use a resource in a separate cloud platform so long as there is connectivity.

Delegate Installation

For an overview of Harness' support for platforms, methodologies, and related technologies, see Supported Platforms and Technologies.

What types of Delegate are there?

Harness provides different types of Delegates to give you flexibility in how you manage deployments.

You are not limited to using a Delegate of the same type as your deployment platform, although that is more complicated to set up initially.

For the types of Delegates, see Delegates How-tos.

Where do I install the Harness 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.

When do I install the Harness Delegate?

You can set up or select an existing Delegate inline as you model your Pipelines.

How many Delegates do I need to run?

Typically, you will need one Delegate for every 300-500 service instances across your applications.

Can I automate Delegate installation?

Yes. You can use a simple script to support scenarios where you want to name, configure, and install a Harness Kubernetes Delegate from a repo.

Developers often need to create Delegates in multiple cluster in their environments (DEV, UAT, SIT, STAGE, PROD, etc). This script method gives developers a quick alternative to using the manual process in the Harness Manager.

See Automate Delegate Installation.

Delegate Requirements

For an overview of Harness' support for platforms, methodologies, and related technologies, see Supported Platforms and Technologies.

What are the Delegate system requirements?

It depends on the size of the Delegate you are installing. For example, for the Kubernetes Delegate, your Kubernetes cluster must have the unallocated resources required to run the Harness Delegate workload:

  • Laptop - 1.6GB memory, 0.5CPU
  • Small - 3.3GB memory, 1CPU
  • Medium - 6.6GB memory, 2CPU
  • Large - 13.2GB memory, 4CPU

What are the Delegate network requirements?

See Delegate Requirements and Limitations and Permissions and Ports for Harness Connections.

What are the Delegate access requirements?

  • The Harness Delegate does NOT require root account access, but the Kubernetes and Docker Delegates run as root by default. This is to enable the Delegate to install applications using INIT environment variable in the Delegate YAML. If you do not need to install applications, then you can use a non-root account or install the application without the Delegate.
  • If you do not run the Delegate as root, be aware that you cannot install any software using a Delegate.

See Run Scripts on Delegates.

What are the Delegate limitations for deployments?

  • The daily deployment limit is 100 deployments every 24 hours. The hourly limit is 40 deployments and is designed to detect any atypical upsurge of deployments. Contact Harness to increase this limit.
  • 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.

Can I configure Delegate proxy settings?

Yes. All of the Delegate settings include proxy settings you can use to change how the Delegate connects to the Harness Manager.

By default, the Harness Delegate uses HTTP and HTTPS in its Proxy Scheme settings.

See Configure Delegate Proxy Settings.

Delegate Selection

For an overview of Harness' support for platforms, methodologies, and related technologies, see Supported Platforms and Technologies.

How Does the Harness Manager pick Delegates for tasks?

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.
  • Delegate Selectors - You can select specific Delegates for each Pipeline steps using Delegate Selectors.
    Delegate Selectors use the Tags you add to Delegates. 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.

Can I pick a Delegate for a Pipeline step?

Yes, for all Pipeline steps you can use Delegate Selectors to select specific Delegates for the step.

Delegate Selectors use the Tags you add to Delegates. For more information, see Select Delegates with Tags.

Running scripts and installations on Delegates

For an overview of Harness' support for platforms, methodologies, and related technologies, see Supported Platforms and Technologies.

Can I run scripts on Delegate hosts using Harness?

Yes. The Delegate config file includes an INIT environment variable that you can use to run scripts.

You can run scripts when you first install the Delegate, or add your scripts to an existing Delegate and rerun its setup.

See Run Scripts on Delegates.

Can I install software on Delegate hosts using Harness?

Yes. See Run Scripts on Delegates.

Can I use Harness secret expressions in a Delegate script?

No. You can add your passwords, tokens, etc to your scripts, but you cannot use Harness text secrets.

Installing Certificates on the Delegate

For an overview of Harness' support for platforms, methodologies, and related technologies, see Supported Platforms and Technologies.

Can I import certificates on the Delegate host?

Yes. By default, the Delegate uses a trusted certificate to connect to the Harness Manager over HTTPS.

For the Harness SaaS edition, you can add a self-signed certificates on the Delegate host using a Delegate script, or by simply importing the certificate on the host.

Can I override the truststore of the Delegate?

Yes. See Truststore Override for Delegates.

Copying and downloading artifacts using the Delegate

For an overview of Harness' support for platforms, methodologies, and related technologies, see Supported Platforms and Technologies.

How does the Delegate download or copy an artifact to the target host?

For container-based deployments such as Kubernetes, the Delegate pulls the artifact from a repository to the target container.

Delegate and Kubernetes namespaces

For an overview of Harness' support for platforms, methodologies, and related technologies, see Supported Platforms and Technologies.

What Kubernetes namespace does the Delegate use?

By default, Harness Delegates deploy to all namespaces in a target Kubernetes cluster.

The Delegate resides in a namespace in the target cluster with a service account attached to it. The service account uses a ClusterRole for permission to deploy to all namespaces in the cluster.

Can I install the Delegate in other namespaces?

Yes, you can use a distributed model.

This model places a Delegate in each namespace in the cluster. It limits each Delegate to deploying into its own namespace.

Here is the illustration of the distributed model:

In this model, each team uses their own Delegate for their deployments into their own namespace.

The distributed model is more complex, but it prevents a team member from deploying into the wrong namespace.

You can target the Delegate to specific namespaces buy editing its YAML file with a Role, RoleBinding, and Service Account limited to a specific namespace.

Delegate high availability (HA)

For an overview of Harness' support for platforms, methodologies, and related technologies, see Supported Platforms and Technologies.

Does the Delegate support high availability (HA)?

Yes. You might need to install multiple Delegates depending on how many deployment 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 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 YAML spec 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.

See Delegates Overview.

Troubleshooting the Delegate

For an overview of Harness' support for platforms, methodologies, and related technologies, see Supported Platforms and Technologies.

What are common problems with the Delegate?

Most Delegate issues are:

  • Delegate does not meet system, network, or access requirements. See Delegate Requirements and Limitations and Permissions and Ports for Harness Connections.
    • Keep in mind, the Delegate host/node/etc needs resources to host the Delegate and other software. The Delegate resource requirements should be factored in, but they are not the minimum requirements for the infrastructure.
  • Delegate is not running.
  • Delegate does not have required permissions. The Delegate uses the credentials you enter in Harness Connectors to connect to cloud providers, artifact servers, etc.
    In most cases, this is a user account. In some cases, the host/pod/container running the Delegate has a user, profile, or IAM account assigned to it, and the Harness Connector is inheriting those credentials.
    The credentials used by the Delegate must have the roles and permissions required to perform the task. For example, if the IAM user account used for an AWS Connector does not have the roles required for EKS deployments, then it will fail.
    The Harness Deployment will show which Pipeline step failed because of Delegate permission issues.
    See the permissions required for the Harness Connector used for the failed task.


Please Provide Feedback