> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/delegates/delegate-closed-beta/install-a-delegate/install-kubernetes-delegate.md). # Install a Delegate on Kubernetes {% hint style="warning" %} **CLOSED BETA** Delegate 3.x is currently in closed beta and available only to select users. Access is determined by the product team. See [Feature Parity](/harness-ai/use-harness-platform/delegates/delegate-3x-closed-beta/feature-parity.md) for current supported use cases. {% endhint %} This guide describes how to install Delegate 3.x in a Kubernetes cluster. The Kubernetes delegate runs as a deployment in your cluster and can execute CI builds and other Harness tasks. For supported connectors, CI steps, secret managers, and module support by deployment type, see the [Feature Parity](/harness-ai/use-harness-platform/delegates/delegate-3x-closed-beta/feature-parity.md) page — that's the single source of truth, kept up to date as support expands. {% hint style="info" %} To learn more about Delegate 3.x, including architecture and how it compares to the legacy delegate, see the [Delegate 3.x Overview](/harness-ai/use-harness-platform/delegates/delegate-3x-closed-beta/delegate-overview.md). {% endhint %} ### Feature Flags To use Delegate 3.x for different operations, you need to enable the appropriate feature flags in your Harness account: | Feature Flag | Purpose | When to Enable | | ----------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CI_V0_K8S_BUILDS_USE_RUNNER` | Routes CI stages with Kubernetes infrastructure to Delegate 3.x | Enable this if you want all CI stages with Kubernetes infrastructure to use Delegate 3.x account-wide. Alternatively, you can use a stage variable `HARNESS_CI_INTERNAL_ROUTE_TO_RUNNER` set to `true` for individual stages. | | `PL_USE_RUNNER` | Enables Delegate 3.x for connector tests and secret manager operations | Enable this to use Delegate 3.x for connector connectivity tests and secret manager operations (create, update, rename, delete secrets). | **Note:** Feature flags are account-level settings. Contact your Harness administrator to enable these flags if you don't have the necessary permissions. ### Get Account ID, Token, and Harness URL Before installing the delegate, you need to obtain your Harness account credentials. These values are required for the delegate to authenticate and connect to the Harness platform. 1. Navigate to the delegate listing page in your Harness account. The URL format is: ``` https:///ng/account//module/ci/settings/delegates/list ``` 2. Click **+ New Delegate**. 3. Select **Docker** as the installation type. Even though you're installing in Kubernetes, selecting Docker will prompt you to enter the required credentials. 4. Copy the values from the installation command: * **ACCOUNT\_ID** - Your Harness account identifier * **DELEGATE\_TOKEN** - Authentication token for the delegate * **MANAGER\_HOST\_AND\_PORT** - Your Harness platform URL Save these values for the next step. In the following sections, these will be referred to as your **Account ID**, **Delegate Token**, and **Harness URL**, respectively. ### Install the Delegate in Kubernetes The Kubernetes delegate is deployed using a manifest that includes a namespace, a service account, RBAC permissions, secrets, a deployment, and a horizontal pod autoscaler. #### Download the Kubernetes Manifest Copy the Kubernetes manifest YAML below and save it to a file named `delegate_deployment.yaml` (or any name you prefer) on your local machine.
Click to view the complete Kubernetes manifest ```yaml apiVersion: v1 kind: Namespace metadata: name: "PUT_YOUR_DELEGATE_NAMESPACE" --- apiVersion: v1 kind: ServiceAccount metadata: name: "PUT_YOUR_DELEGATE_NAME" namespace: "PUT_YOUR_DELEGATE_NAMESPACE" --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: "PUT_YOUR_DELEGATE_NAME" subjects: - kind: ServiceAccount name: "PUT_YOUR_DELEGATE_NAME" namespace: "PUT_YOUR_DELEGATE_NAMESPACE" roleRef: kind: ClusterRole name: cluster-admin apiGroup: rbac.authorization.k8s.io --- apiVersion: v1 kind: Secret metadata: name: "PUT_YOUR_DELEGATE_NAME" namespace: "PUT_YOUR_DELEGATE_NAMESPACE" type: Opaque data: HARNESS_DELEGATE_TOKEN: "PUT_YOUR_DELEGATE_TOKEN" --- apiVersion: apps/v1 kind: Deployment metadata: labels: harness.io/name: "PUT_YOUR_DELEGATE_NAME" name: "PUT_YOUR_DELEGATE_NAME" namespace: "PUT_YOUR_DELEGATE_NAMESPACE" spec: replicas: 1 minReadySeconds: 10 selector: matchLabels: harness.io/name: "PUT_YOUR_DELEGATE_NAME" template: metadata: labels: harness.io/name: "PUT_YOUR_DELEGATE_NAME" annotations: prometheus.io/scrape: "true" prometheus.io/port: "3000" prometheus.io/path: "/metrics" spec: serviceAccountName: "PUT_YOUR_DELEGATE_NAME" terminationGracePeriodSeconds: 600 restartPolicy: Always containers: - image: "PUT_YOUR_DELEGATE_IMAGE" imagePullPolicy: Always name: delegate securityContext: allowPrivilegeEscalation: false runAsUser: 0 resources: limits: memory: "256Mi" requests: cpu: "0.5" memory: "256Mi" livenessProbe: httpGet: path: /health port: 3000 initialDelaySeconds: 10 periodSeconds: 10 failureThreshold: 5 timeoutSeconds: 5 readinessProbe: httpGet: path: /health port: 3000 initialDelaySeconds: 5 periodSeconds: 10 failureThreshold: 5 timeoutSeconds: 5 envFrom: - secretRef: name: "PUT_YOUR_DELEGATE_NAME" env: - name: HARNESS_ACCOUNT_ID value: "PUT_YOUR_ACCOUNT_ID" - name: MANAGER_HOST_AND_PORT value: "PUT_YOUR_MANAGER_ENDPOINT" - name: HARNESS_DELEGATE_NAME value: "PUT_YOUR_DELEGATE_NAME" - name: HARNESS_DELEGATE_TAGS value: "PUT_YOUR_DELEGATE_TAGS" - name: POD_NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace - name: POD_SERVICE_ACCOUNT_NAME valueFrom: fieldRef: fieldPath: spec.serviceAccountName --- apiVersion: autoscaling/v1 kind: HorizontalPodAutoscaler metadata: name: "PUT_YOUR_DELEGATE_NAME" namespace: "PUT_YOUR_DELEGATE_NAMESPACE" labels: harness.io/name: "PUT_YOUR_DELEGATE_NAME" spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: "PUT_YOUR_DELEGATE_NAME" minReplicas: 1 maxReplicas: 1 targetCPUUtilizationPercentage: 99 ```
#### Configure the Manifest Open the downloaded YAML file and replace the following placeholders with your actual values: | Placeholder | Description | Example | | ----------------------------- | ------------------------------------------ | ------------------------------------------------------------------------ | | `PUT_YOUR_DELEGATE_NAMESPACE` | Kubernetes namespace for the delegate | `harness-delegate` | | `PUT_YOUR_DELEGATE_NAME` | Name for your delegate | `k8s-delegate` | | `PUT_YOUR_DELEGATE_TOKEN` | Delegate token (obtained in previous step) | Base64 encoded token | | `PUT_YOUR_DELEGATE_IMAGE` | Delegate container image | `us-docker.pkg.dev/gar-prod-setup/harness-public/harness/delegate:3.5.0` | | `PUT_YOUR_ACCOUNT_ID` | Account ID (obtained in previous step) | Your Harness account ID | | `PUT_YOUR_MANAGER_ENDPOINT` | Harness URL (obtained in previous step) | `https://app.harness.io` | | `PUT_YOUR_DELEGATE_TAGS` | Comma-separated delegate tags | `k8s,runner,production` | **Delegate Tags:** The `HARNESS_DELEGATE_TAGS` environment variable accepts a comma-separated string of tags. You can specify multiple tags to organize and filter delegates. For example: `k8s,runner,production,qa-signoff-k8s`. These tags are used when selecting delegates for connectors and pipeline stages. #### Deploy the Delegate Once you've configured all the placeholders in the manifest, apply it to your Kubernetes cluster: ```bash kubectl apply -f delegate_deployment.yaml ``` The manifest creates the following Kubernetes resources: * **Namespace** - Isolated environment for the delegate * **ServiceAccount** - Kubernetes service account for the delegate pod * **ClusterRoleBinding** - Grants cluster-admin permissions to the service account * **Secret** - Stores the delegate token securely * **Deployment** - Manages the delegate pod lifecycle * **HorizontalPodAutoscaler** - Automatically scales the delegate based on CPU usage #### Verify Installation After applying the manifest, verify that the delegate is running: ```bash kubectl get pods -n ``` You should see a pod with your delegate name in a `Running` state. Check the pod logs to ensure it's connecting to Harness: ```bash kubectl logs -n -f ``` Once the pod is running, navigate to **Project Settings** > **Delegates** in the Harness UI. Your new delegate should appear in the list with a **Connected** status, indicating it's successfully communicating with the Harness platform. ### Using the Kubernetes Delegate Once your delegate is installed and connected, you can use it for CI stages with Kubernetes infrastructure, connector tests, and secret manager operations. #### CI Stage with Kubernetes Infrastructure To use Delegate 3.x for CI builds, configure your pipeline stage to use Kubernetes infrastructure and route tasks to it. **Create a Kubernetes Cluster Connector** 1. In your Harness project, go to **Connectors** and create a new **Kubernetes Cluster** connector. 2. In the **Overview** step, enter a name for your connector and click **Continue**. 3. In the **Details** step, select **Use the credentials of a specific Harness Delegate (IAM role, service account, etc)**. 4. In the **Delegates Setup** step, configure delegate selection: * Choose **Only use Delegates with all of the following tags** * Add tags that match your delegate tags (the tags you specified in `HARNESS_DELEGATE_TAGS` during installation) * Verify that your delegate appears in the matching delegates list with a green checkmark 5. Save the connector. You may see a connector test error—this is expected, as connector tests are not yet fully supported for Delegate 3.x. The connector will work correctly even if the test connection is not successful. **Configure CI Stage Infrastructure** 1. In your CI pipeline stage, go to the **Infrastructure** tab. 2. Select **Kubernetes** as your infrastructure type. 3. Select the Kubernetes cluster connector you created. 4. Specify a namespace where the builds will run. This should be a pre-existing namespace in your cluster. **Enable Delegate 3.x Routing** To route CI tasks to Delegate 3.x, you can either: * **Use a stage variable** (recommended for testing): Go to your pipeline stage's **Advanced** tab, add a variable named `HARNESS_CI_INTERNAL_ROUTE_TO_RUNNER`, and set its value to `true`. This enables Delegate 3.x routing for that specific stage only. * **Enable the feature flag** (account-wide): Enable `CI_V0_K8S_BUILDS_USE_RUNNER` in your Harness account (see [Feature Flags](#feature-flags) for details). This routes all CI stages with Kubernetes infrastructure to Delegate 3.x, while still respecting the delegate selectors configured in your Kubernetes connectors. #### Connector Tests and Secret Manager Operations To use Delegate 3.x for connector connectivity tests and secret manager operations (create, update, rename, and delete secrets): 1. Enable the feature flag `PL_USE_RUNNER` in your Harness account (see [Feature Flags](#feature-flags) for details). 2. In your connector's **Delegates Setup** section, select delegate tags that match your delegate installation. 3. The delegate will automatically be used for connector tests and secret manager operations when the tags match. {% hint style="info" %} For the full list of connectors supported by Delegate 3.x, see [Connector support](/harness-ai/use-harness-platform/delegates/delegate-3x-closed-beta/feature-parity.md#connector-support) on the Feature Parity page. {% endhint %}