Install a legacy Kubernetes delegate
This topic describes how to install the legacy Kubernetes delegate, which always auto upgrades to the default delegate version associated with a Harness Manager version.
Harness supports Kubernetes versions 1.25.16, 1.26.10, and 1.27.8 for delegate installation.
This is an End of Support (EOS) notice for the Delegate-Legacy image type. This image type reached End of Support (EOS) as of January 31, 2024.
End of Support means the following:
- Harness Support will no longer accept support requests for the Delegate-Legacy image type in both Harness FirstGen and Harness NextGen (including Harness Self-Managed Enterprise Edition (SMP)).
- Security fixes will still be addressed.
- Product defects will not be addressed.
Follow the below steps to upgrade Delegate-Legacy to Delegate image
- Download new yaml from Harness by keeping the same name as the previous delegate
- Check if the existing delegate has any tags/selector, if yes then add them in DELEGATE_TAGS
- Compare the permissions given to the legacy delegate in their yaml and give the same permissions to new delegates
- Check if custom image is used, if yes then build a new image with immutable delegate as base image and override the account setting to point to that image
- Ensure that auto upgrade is enabled for Kubernetes delegates
- Our delegate yaml ships with default HPA of min and max replicas to be 1, adjust the desired number of replicas in HPA
- Deploy the new yaml and see new replicas coming under the same delegate
- Scale down the old stateful set and verify that everything is correct
If you are migrating from Harness FirstGen to Harness NextGen, you must install new delegates in Harness NextGen. Harness FirstGen Delegates won't work with Harness NextGen.
Limitations
Currently, Harness Kubernetes Delegates don't install with the default settings in GKE Auto Pilot Mode. Use the Manual mode when creating the cluster to make sure it meets the delegate requirements.
The delegate requires access to all the connectors and Harness Secrets needed to run a pipeline. This means that the delegate requires permissions to do the following:
- Access all the secrets used by all the connectors used in a pipeline.
- Create and update secrets in Kubernetes. This is necessary to pull the images needed to run individual Steps.
You might need additional permissions to execute commands in delegate scripts and create Harness users.
Inline or standalone installation
You can install a delegate whenever you are adding a connector to a pipeline, or you can install one outside a pipeline in Resources.
The steps involved are the same.
Installation location
You can install the Kubernetes delegate inside or outside your deployment target cluster (CD) or build farm cluster (CIE).
- Inside the cluster: you can install the Kubernetes delegate inside the target or build farm cluster. Later, when you add a Kubernetes Cluster Connector, the connector can inherit its credentials from the Kubernetes delegate.
- Outside the cluster: you can install the Kubernetes delegate outside the target or build farm cluster. Later, when you add a Kubernetes Cluster Connector, the connector cannot inherit its credentials from the Kubernetes delegate. In this case, the Kubernetes Cluster Connector must use an alternate method for credentials. For example, the master URL of the target cluster and a Service Account with the required credentials.
Step 1: Ensure Kubernetes prerequisites
To install a Kubernetes delegate, you must have access to a Kubernetes cluster. You'll install the Harness Delegate as YAML or Helm Chart.
For connectivity, go to Delegate Requirements.
You'll need the following Kubernetes permissions to install the delegate:
- Permission to create a namespace (for the Harness Delegate namespace).
- Permission to create statefulSets (to create the Harness Delegate pod).
Step 2: Select the Kubernetes delegate type
Inline or standalone, select New Delegate. Delegate selection options appear.
Select Kubernetes, and then select Continue.
Enter a name and description for the delegate that informs others of its use or installation location.
Step 3: Add delegate name
Do not run delegates with the same name in different clusters. Go to Troubleshooting.
Add a name for the delegate. The name will be added to the delegate YAML as the name
metadata of the StatefulSet.
Legacy Delegates are deployed as StatefulSet objects. By default, the StatefulSet.serviceName field is empty ("") and does not need to be specified. Delegates do not require service names.
The combined length of the Delegate name and the service name must not exceed 255 bytes. If the maximum length is exceeded, the Delegate might not appear in the Harness Manager UI. For more information on StatefulSet.serviceName, go to StatefulSetSpec in Kubernetes API**.
Add tags to the delegate. By default, Harness adds a tag using the name you enter, but you can more. Simply type them in, and press Enter.
These tags are useful for selecting the delegate when creating a connector.
Step 4: Select delegate size
In Delegate Size, select the size of delegate you want to install.
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
Important: These sizing requirements are for the delegate only. Your cluster will require more memory for Kubernetes, the operating system, and other services.
Important resource considerations
These requirements are for the delegate only. Your cluster will have system, Kubernetes, and other resources consumers. Make sure that the cluster has enough memory, storage, and CPU for all of its resource consumers.
Most importantly, when the delegate is installed inside the target deployment or build farm cluster, the cluster must also support the resources needed by the services you are deploying or building.
For example, if you use the Small option that requires 3.3GB of memory, don't use a cluster with only 4GB or memory. It won't be enough to run the delegate and other resources.
Step 5: Download and install the script
Click Download Script. The YAML file for the Kubernetes delegate, and its README, downloads to your computer as an archive.
Open a terminal and change your directory to the delegate file's location.
Extract the YAML file from the download, and then navigate to the extracted file:
tar -zxvf harness-delegate-kubernetes.tar.gz
cd harness-delegate-kubernetes
You'll connect to your cluster using the terminal, so you can simply copy the YAML file over.
In the same terminal, log into your Kubernetes cluster. In most platforms, you select the cluster, select Connect, and copy the access command.
To 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 displays the following:
HTTP request sent, awaiting response... 200 OK
Next, install the Harness Delegate using the harness-delegate.yaml file you just downloaded. In the terminal connected to your cluster, run this command:
kubectl apply -f harness-delegate.yaml
The successful output is something like this:
% kubectl apply -f harness-delegate.yaml
namespace/harness-delegate unchanged
clusterrolebinding.rbac.authorization.k8s.io/harness-delegate-cluster-admin unchanged
secret/k8s-quickstart-proxy unchanged
statefulset.apps/k8s-quickstart-sngxpn created
service/delegate-service unchanged
Run this command to verify that the delegate pod was created:
kubectl get pods -n harness-delegate-ng
It'll take a moment for the delegate to appear in Harness' Delegates list.
You're ready to connect Harness to your artifact server and cluster. After those steps, you'll begin creating your deployment.
Review: Delegate role requirements
The YAML provided for the Harness Delegate defaults to the cluster-admin
role to ensure you can apply updates. If you can't use cluster-admin
because you are using a cluster in your company, you'll need to edit the delegate YAML.
The set of permissions should include list
, get
, create
, watch
(to fetch the pod events), and delete
permissions for each entity type Harness uses.
If you don't want to use resources: ["*"]
for the role, you can list out the resources you want to grant. Harness requires configMap
, secret
, event
, deployment
, and pod
at a minimum for deployments, as stated above.
In the delegate installation settings, you also have the option to select cluster read-only access and namespace-specific access. When you select these options, the YAML generated by Harness is changed to reflect the limited access.