Delegate Installation and Management

Updated 1 day ago by Michael Cretzman

In this article:

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

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.

Intended Audience

  • DevOps

Delegate Requirements

The Delegate is installed in your network and connects to the Harness Manager.

  • Linux/UNIX server
  • Minimum 8GB RAM
  • Minimum 6GB Disk Space
  • Access to artifact servers, deployment environments, and cloud providers
Multiple Delegates can be used and their scope can be managed. For more information, see Delegate Scope.

Delegate Access Requirements

  • The Harness Delegate does NOT require root account access.

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

To install the Delegate:

  1. Sign into the Harness Manager.
  2. Download and install the Harness Delegate.
    1. Click Setup.
    2. Click Harness Installations.

      You can download the Delegate scripts or copy and use the cURL commands to install the Delegate.
    3. Click Download Delegate.
    To install using cURL, click the copy icon next to the Shell Script or Docker Image options, connect to the machine or instance where you want to run the Delegate, and use cURL to download the Delegate.
    1. To use the Shell Script, unzip the file and run the start.sh script ($ ./start.sh).
    2. To use Docker, unzip the file and run the start script ($ ./launch-harness-delegate.sh). You will see the Docker image pull, for example:
    latest: Pulling from harness/delegate
    297061f60c36: Pull complete…
    Status: Downloaded newer image for harness/delegate:latest
    1. For Kubernetes, unzip the file and navigate into the extracted folder in a Terminal. Next, log into your cluster via the Terminal, and run the following commands (ensure you have kubectl installed and credentials to access your Kubernetes cluster):

      $ kubectl apply -f harness-delegate.yaml (installs or replaces the Harness Delegate)
      $ kubectl get pods -n harness-delegate (get pod names)
      $ kubectl logs <pod-name> -n harness-delegate -f (see startup logs)
      $ kubectl exec <pod-name> -n harness-delegate -it -- bash (run a shell in a pod)

      For example, with Google Cloud Platform, you can click the Connect button for your Kubernetes cluster, copy the Command-line access command, and the paste and run it in a Terminal running on the host where you downloaded the harness-delegate.yaml file. Once you are connected, you simply cd to the folder where harness-delegate.yaml is located and run:

      $ kubectl apply -f harness-delegate.yaml.
      If needed, edit the harness-delegate.yaml you unzipped to change the namespace, set proxy settings, or to enter a Delegate description.
  3. Once the Delegate is installed, tour Delegate is listed in the Installations page in a few moments.

In the Installation page is the the list of installed Delegates. The information displayed includes:

  • Hostname.
  • IP Address.
  • Status.
  • Last heartbeat. This is the last time the delegate communicated with the Harness Manager. The Delegate pings the Manager once a minute.
  • Delegate version.

Installation Example: Google Cloud Platform

The following steps describe how to install the Kubernetes Delegate in a Kubernetes cluster in Google Cloud Platform.

A Kubernetes cluster in Google Cloud Platform has a variety of settings that are different from other vendors. For example, when creating your cluster in Google Cloud Platform, you might need to add more or less CPUs or RAM to your nodes than you would with another cloud vendor or an Internal cluster.
  1. Sign up for a free tier Google Cloud Platform account.
  2. In Google Cloud Platform, create a Kubernetes cluster.
    1. In Kubernetes Engine, click CREATE CLUSTER.


      The Create a Kubernetes cluster panel appears.
    2. Choose the Standard cluster template.
    3. Customize the template:
      Name: Enter the name for the cluster.
      Location type: Select Zonal for this example.
      Zone: Select the default Compute Engine compute zone, as the location type is Zonal.
    4. For Node pools, do the following:
      Number of nodes: Enter 3 nodes.
      Machine type: Enter 2 vCPU, and click Customize. In Memory, enter 8GB.
    5. Click the Advanced edit button.
    6. In the Edit node pool panel, below Size, click Enable autoscaling.
    7. Enter a Minimum of 3 and a Maximum of 8.
      When you are done, your setting will look something like this:
    8. Click Save.
    9. Click Create to create the cluster. It will take a few minutes to create the Kubernetes cluster.
  3. When the cluster is created, click the Connect button.
  4. In the Connect to the cluster dialog, copy the Command-line access command.
  5. On your local machine, open a Terminal, and paste the command, and press Enter. You are now connected to the Kubernetes cluster.
  6. Let's quickly confirm that the cluster you created can connect to the Harness platform. Enter the following command:
    wget -p https://app.harness.io/ -O /dev/null
    A successful connection will display the following output:
    Resolving app.harness.io (app.harness.io)... 35.197.53.196
    Connecting to app.harness.io (app.harness.io)|35.197.53.196|:443... connected.
    HTTP request sent, awaiting response... 200 OK
  7. Download the Kubernetes Delegate from Harness.
    1. In Harness, click Setup, and then click Harness Installations.
    2. Click Download Delegate and then click Kubernetes YAML.
    3. In the Delegate Setup dialog, enter a name for the Delegate, such as harness-sample-k8s-delegate, and click Submit. the YAML file is downloaded to your machine.
  8. Install the Delegate in your cluster.
    1. In the Terminal you used to connect to the Kubernetes cluster, navigate to the folder where you downloaded the Harness Delegate YAML file.
      For example, cd ~/Downloads.
    2. Extract the YAML file: tar -zxvf harness-delegate-kubernetes.tar.gz.
    3. Navigate to the harness-delegate folder that was created:
      cd harness-delegate-kubernetes
    4. Paste the following installation command into the Terminal and press enter:
      kubectl apply -f harness-delegate.yaml

      You will see the following output (this delegate is named k8s-test):
      namespace/harness-delegate created
      clusterrolebinding.rbac.authorization.k8s.io/harness-delegate-cluster-admin created
      statefulset.apps/k8s-test-vutpmk created
  9. Run this command to verify that the Delegate pod was created:
    kubectl get pods -n harness-delegate

    You will see output with the status Pending. The Pending status simply means that the cluster is still loading the pod.
  10. Wait a few moments for the cluster to finish loading the pod and for the Delegate to connect to Harness Manager.
  11. In Harness Manager, in the Harness Installations page, the new Delegate will appear. You can refresh the page if you like.

Installation Example: Amazon Web Services and ECS

The following steps show you how to install the Delegate on an EC2 instance to enable the Delegate to connect to your AWS resources. We use ECS as an example, although the steps are the same for other AWS services.

Need a Cluster? If you do not have an AWS account, you can use an AWS Free Tier account and create an ECS cluster by following the steps in ECS Getting Started from Amazon. If you do have an AWS account and you want to evaluate Harness with ECS, you can simply create a new ECS cluster in your AWS account.

As a best practice, install the Delegate in the same VPC as the AWS resources Harness will use. You can even choose to install the Delegate in the same subnet. For example, if you are using AWS ECS, install the Delegate on an EC2 instance in the same VPC as the ECS cluster. Installing the Delegate in the same VPC will help you to avoid cross-VPC networking complexities.
  1. Log into AWS using an AWS account that can create an EC2 instance in your target AWS VPC.
  2. Create an AWS IAM role containing the policies needed for the AWS resources Harness will use.
    For example, if you are using Harness for an ECS deployment, you create a role with the policies described in ECS (Existing Cluster).
    Later, when you create the EC2 instance for the delegate, you will need to assign this role to the instance.
    1. In your ECS cluster, locate the VPC where you want to install the Delegate. You can locate the VPC using the AWS VPC console, but the following steps describe how to find the VPC using an ECS Service.
      1. In the ECS console, click Clusters.
      2. Click the name of the cluster.
      3. In the Services tab, click the name of the ECS service.
      4. In the Service page, on the Details tab, note the Network Access information for your service.
      5. Note the Allowed VPC and Allowed subnets. You can use the same security group or simply create one when you create your EC2 instance.
  3. In the EC2 console, create an EC2 instance for the Delegate.
    1. Ensure that the EC2 instance meets the Delegate Requirements. A General Purpose t2.large type instance meets the requirements.
    2. In Step 3: Configure Instance Details, in Network, select the VPC where your ECS cluster service is located.
    3. In Subnet, select a new subnet or use one of the Allowed subnets from your ECS cluster service.
    4. In IAM role, select the role you created for the ECS resources Harness will use.
    5. In Step 6: Configure Security Group, you can use the same security group as your ECS cluster service or create a new group. The only inbound rule required is the AMI default, SSH over port 22.
    6. Complete the EC2 instance wizard and launch your instance.
  4. SSH into the EC2 instance.
    1. In the EC2 console, select the instance and click Connect.
    2. Use SSH and your private key file to connect to your instance. In this example, we will assume you are connecting via a Linux terminal.
    3. Quickly test that the instance can connect to the Harness Manager by entering the following command:

      wget -p https://app.harness.io/ -O /dev/null

      When the instance connects, the following output will appear:

      Resolving app.harness.io (app.harness.io)... 35.197.53.196Connecting to app.harness.io (app.harness.io)|35.197.53.196|:443... connected.HTTP request sent, awaiting response... 200 OK
  5. Download and run the Delegate on the EC2 instance.
    1. In Harness Manager, click Setup, and then click Harness Installations.
    2. Click Download Delegate, and click the copy icon next to Shell Script. This copies a cURL command.

      You can also use the Docker or Kubernetes delegates, but they require Docker or Kubernetes to be installed and running in your EC2 Delegate instance.
    3. In your Terminal connection to your ECS instance, paste the cURL command you copied.
    4. Press Enter. The Delegate file is downloaded onto your EC2 instance.
    5. Extract the Delegate file: tar -zxvf harness-delegate.tar.gz
    6. Navigate into the extracted Delegate folder: cd harness-delegate/
    7. Start the Delegate: ./start.sh
  6. In Harness Manager, in the Installations page, wait for the Delegate to register. This can take a few minutes. When the Delegate connects to the Harness Manager, it is listed with a status of Connected:


    Congratulations! You are done installing and running the Delegate.

    The following steps simply show you how to use a tag name to identify this delegate when making a connection to AWS. You simply instruct Harness to connect to AWS using the same IAM role as the Delegate via its tag name.
  7. Once the Delegate is listed in Harness, assign a tag to the Delegate.
    1. Next to the Tags label in the Delegate listing, click Edit.
    2. Enter a tag name, for example, ecs-delegate, and press Enter. The tag is listed.

  8. In Harness Manager, click Setup.
  9. Click Cloud Providers. The Cloud Providers page appears.
  10. Click Add Cloud Provider. The Cloud Provider dialog appears.
  11. In Type, select AWS.
  12. In Display Name, enter a name for the Cloud Provider, such as aws-ecs.
  13. Enable the Assume IAM Role on Delegate option.
  14. In Delegate Tag, enter the tag you gave the Delegate.
  15. Click SUBMIT. The Cloud Provider is added.

Later, when you create a Service Infrastructure in an Environment, you will select this Cloud Provider and Harness will use the connection to obtain ECS cluster and networking information.

Delegate Proxy Settings

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

Shell Script Proxy Settings

The proxy settings are in the proxy.config file:

PROXY_HOST=
          
          PROXY_PORT=
          
          PROXY_SCHEME=
          
          NO_PROXY=
          

Docker Proxy Settings

The proxy settings are in the launch-harness-delegate.sh file:

-e PROXY_HOST= \
          
          -e PROXY_PORT= \
          
          -e PROXY_SCHEME= \
          
          -e NO_PROXY= \
          

Kubernetes Proxy Settings

The proxy settings are in the harness-delegate.yaml file:

- name: PROXY_HOST
          
            value: ""
          
          - name: PROXY_PORT
          
            value: ""
          
          - name: PROXY_SCHEME
          
            value: ""
          
          - name: NO_PROXY
          
            value: ""
          

Delegate Scope

By default, a Delegate will perform all connections you set up and processes you run. To limit, or scope, a Delegate, you can set specific boundaries and associations for each Delegate you run. You can scope a Delegate to:

  • A specific command.
  • Application.
  • Environment.
  • Environment type.
  • Service infrastructure.

Delegate Scope Example

You need to restrict access to a production environment. Without defining a scope, the Delegate scans all network ports to map out the environment and performs checks to access the artifact and cloud providers it needs. By defining a scope, you can limit the Delegate to connect to only the specific environments, applications, and service infrastructure it needs. 

Defining a scope is optional, but if you use scoping you can prevent the Delegate from constantly looking for what’s available or accessible.

Scope a Delegate

To scope a Delegate, do the following:

  1. On the Harness Installations page, which lists all of the Delegates, select a Delegate and click Scope Included or Scope Excluded.


    The Delegate Scope dialog appears.
  2. Click New scope, and then click ADD SCOPE. The dialog changes to display the scope properties.
  3. Enter a name for the scope, and then select its properties, such as the command, Harness Application, Environment, and Service Infrastructure to which the scope applies.
    If you clicked Scope Included, then the Delegate is only used for the properties selected.
    If you clicked Scope Excluded, then the Delegate is excluded from running for the properties selected.
  4. Click SUBMIT. The scope is added to the Delegate.

Delegate Profiles

A Delegate Profile enables you to run a startup script on the host/container/pod for a Harness Delegate when the Delegate is installed. You can create a single Delegate Profile and apply it to multiple Delegates.

For example, if you need to install and run Helm every time a Harness Kubernetes Delegate is added, then you could create a Delegate Profile named Helm-Install containing the commands for installing and running Helm.

Each time you add a Kubernetes Delegate, you apply the Helm-Install profile. For example:

When the Delegate is started, the commands to install and run Helm are executed.

What Can I Run In a Profile?

You can add any commands supported on the host. Linux shell commands are most common. If kubectl, Helm, or Docker is running on the host/container/pod where you install the Delegate, then you can use their commands.

When is the Profile Executed?

Delegate Profiles are applied under the following conditions:

  • New Delegate - If you add a Delegate Profile when you create the Delegate, the profile commands are executed after the Delegate is started.
  • Running Delegate - If you apply a Delegate Profile to a running Delegate, either by applying it as a new profile or switching the Delegate’s current profile, the profile commands are executed immediately.
  • Edited Profile - If you edit a Delegate Profile, the new commands in the profile are applied to all Delegates using the profile.

Create a Delegate Profile

To create a Delegate Profile, do the following:

  1. In Harness, click Setup.
  2. Click Harness Installations.

  3. Click Manage Delegate Profiles, and then click Add Delegate Profile.


    The Manage Delegate Profile dialog appears.
  4. In Name, enter a name for the profile.
  5. In Startup Script, enter the script you want to run when the profile is applied, such as when the Delegate is started. Here is an example of a profile that installs and runs Helm:
  6. Click SUBMIT. The profile is created. Now you can apply the profile to new or existing Delegates.

Applying a Profile

You can apply a profile in the following ways:

  • Kubernetes Delegate - For a Harness Kubernetes Delegate, you can apply a profile when you download the Kubernetes YAML file for the Delegate, or after the Delegate is installed and running.
  • Shell Script and Docker Image Delegate - For the Harness Shell Script and Docker Image delegates, you download, install, and run the Delegates first, and then apply the profile using the Harness Manager.
Apply Profile to New Kubernetes Delegate

To apply a profile to a new Kubernetes Delegate, do the following:

  1. In Harness Manager, click Setup.
  2. Click Harness Installations.

  3. Click Download Delegate, and then click Kubernetes YAML.



    The Delegate dialog appears.

  4. In Delegate Name, enter a name for the new Kubernetes Delegate. In this example, we will use the name profiles-delegate.
  5. In Delegate Profile, select the profile for the Delegate. In this example, we will select the profile named Helm-Install.
  6. Click SUBMIT. Once the Kubernetes Delegate is install and running, the profile is listed in the Delegate information, next to Profile:
Apply Profile to a Running Delegate

You can apply a profile to a running Delegate. You can apply a profile for the first time, or switch from the profile currently applied to a new profile.

To apply a profile to an existing Delegate, do the following:

  1. In Harness, click Setup.
  2. Click Harness Installations.

  3. Locate the Delegate to which you want to apply the profile.
  4. Next to Profile, click Select Profile, and then click the profile you want applied to the Delegate.
  5. In the confirmation dialog, click Confirm.
Notes
  • It might take a few minutes to apply the new profile.
  • When switching profiles, any binaries installed as part of the earlier profile are not removed automatically. If you need to remove them, then restart the Kubernetes pod hosting the Kubernetes Delegate or manually clean up the VM hosting the Shell or Docker delegate.
  • To remove a profile from a Delegate, click Select Profile, and then click None.

Managing Profiles

When you update a Delegate Profile, the changes are applied to the Delegates using the profile. You can also delete a profile and it will be removed from the Delegates using it.

When editing or deleting profiles, any binaries installed as part of the earlier profile are not removed automatically. If you need to remove them, then restart the Kubernetes pod hosting the Kubernetes Delegate or manually clean up the VM hosting the Shell or Docker Delegate.

To update a profile, do the following:

  1. In Harness Manager, click Setup.
  2. Click Harness Installations.

  3. Click Manage Delegate Profiles, and then click the profile you want to update.



    To delete a profile, simply click the X next to the profile, and then confirm.
  4. In the Manage Delegate Profile dialog, edit the Name, Description, or Startup Script for the profile, and then click SUBMIT. The profile is updated with all delegates using it.

Using Secrets in a Profile

Harness Secrets Management feature can be used to provide credentials and other secret information inside the Delegate Profile commands.

For example, if you wanted to add a Helm repo that requires login credentials to every Kubernetes pod running a Harness Kubernetes Delegate, you can create encrypted text in Harness Secrets Management for those credentials, and then use variable names for those credentials in the Delegate Profile.

Let’s walk through this example:

  1. In Harness, hover over Continuous Security, and then click Secrets Management.



    The Secrets Management page appears.

  2. Under Execution Credentials, click Encrypted Text. The Encrypted Text page appears.

  3. Click Add Encrypted Text. The Add Encrypted Text dialog appears.

  4. In Name, enter repoUsername. This name will be used later in the Delegate Profile script to reference this secret.
  5. In Usage Scope, click the X next to both All Applications rows, as this secret is scoped to Account-level Delegates.
  6. In Value, enter any username. The dialog will look like this:
  7. Click SUBMIT.
  8. Add a second encrypted text with the name repoPassword, using any password. Be sure to delete the Usage Scope settings, also. The dialog will look like this:
  9. Click SUBMIT. Now you can create a Delegate Profile and use these secrets.
  10. Click Setup.
  11. Click Harness Installations.

  12. Click Manage Delegate Profiles, and then Add Delegate Profile.



    The Manage Delegate Profile dialog appears.
  13. In Name, enter Helm Repo.
  14. In Startup Script, enter your Helm commands using the secrets you created:

    helm init --client-only

    helm repo add --username ${secrets.getValue(“repoUsername”)} --password ${secrets.getValue(“repoPassword”)} nginx https://charts.bitnami.com/bitnami

    helm repo update

    The secrets are referenced as variables using ${secrets.getValue()} and the names you gave them, repoUsername and repoPassword:

    ${secrets.getValue(“repoUsername”)}
    ${secrets.getValue(“repoPassword”)}

    The Manage Delegate Profile dialog will look like this:
  15. Click SUBMIT.

Now when you add this profile to a Kubernetes Delegate, it will add the Helm repo using the credentials you added as Encrypted Text in Harness Secrets Management.

Delegate Tags

When Harness makes a connection via its Delegates, it will select the best Delegate according to its history or round robin between delegates. To ensure a specific Delegate is used by a Harness entity, you can scope the delegate as explained in Delegate Scope, or you can add tags to delegates and then reference the tags in commands and configurations.

For example, in a Delegate listing in Harness Installations, click Edit next to Tags.

Type in the tag name, such as Local, and press Enter. The tag is added.

Elsewhere, such as in a Shell Script command in a workflow, you can use the tag to ensure that this Delegate is used when executing the command.

The most common use of a Delegate Tag is in a Cloud Provider. For example, you can install a Delegate in an AWS VPC and tag in with a name such as ecs-delegate.

When you set up an AWS Cloud Provider, you can select the Delegate installed in your AWS VPC using its tag.

Now the AWS Cloud Provider will use the Delegate's credentials to connect with AWS.

Troubleshooting

This section contains troubleshooting tips for installing and running the Delegate.

Google Cloud Platform: Cluster has unschedulable pods

If you do not have enough space available in your Kubernetes cluster, you might receive the following error:

Cause

Depending on the size of your cluster, without Autoscaling enabled or enough space, your cluster cannot run the delegate.

Solution

Add more space (see Delegate Requirements above), or turn on Autoscaling, wait for the cluster to restart, reconnect to the cluster, and then rerun the command:

$ kubectl apply -f harness-delegate.yaml

For more information, see Autoscaling Deployments from Google.

Deleting a Kubernetes Delegate

In the case where you have to delete a Harness Delegate from your Kubernetes cluster, you can delete the StatefulSet for the Delegate. Once created, the StatefulSet ensures that the desired number of pods are running and available at all times. Deleting the pod without deleting the StatefulSet will result in the pod being recreated.

For example, if you have the Delegate pod name mydelegate-vutpmk-0, you can delete the StatefulSet with the following command:

$ kubectl delete statefulset -n harness-delegate mydelegate-vutpmk

Note that the -0 suffix in the pod name is removed for the StatefulSet name.


How did we do?