Skip to main content

Create your first CD pipeline

This is a step-by-step tour of using Harness CD pipelines to deploy an application. We show you how to use our YAML, API, Terraform Provider, and console (Pipeline Studio) methods for building pipelines.

Want to try out Harness CD locally?

You can also run all of Harness CD locally using the Harness CD Community Edition.

Harness CD Community Edition is a lightweight version of Harness that you can download and run on your laptop or any VM with 3GB RAM and 2 CPUs. Harness CD Community Edition is intended to get devs started with Harness quickly without having to sign up for a Harness SaaS account.

For more information, go to:


All you need is a deployment environment and a Harness delegate installed where it can reach the environment and Harness.

Deployment environment

If you already have access to a cluster, you can skip this section. Simply install a Harness delegate in the cluster as described in the next section.

Here are several options for creating a cluster, including popular cloud platforms and local options.

If you want to use Minikube, use Minikube minimum version v1.22.0 or later installed locally.

minikube start --memory=4g --cpus=1 --nodes=2

After running this command, you can verify that the cluster is running by running the following command:

kubectl get nodes

Harness delegate

We now need to install a Harness delegate in the target Kubernetes cluster.

Delegates are worker processes that run on your infrastructure to execute tasks on behalf of the Harness platform. Delegates make outbound, secure connections to Harness and your other providers only.

Use the delegate installation wizard
  1. In your Harness project, select Project Setup.
  2. Select Delegates.
  3. Select Install a Delegate.
  4. Follow the delegate installation wizard.

Use this delegate installation wizard video to guide you through the process.

Install a delegate using the terminal

Install Harness Delegate on Kubernetes or Docker

What is Harness Delegate?

Harness Delegate is a lightweight worker process that is installed on your infrastructure and communicates only via outbound HTTP/HTTPS to the Harness Platform. This enables the Harness Platform to leverage the delegate to execute the CI/CD and other tasks on your behalf, without any of your secrets leaving your network.

You can install the Harness Delegate on either Docker or Kubernetes.

Install Harness Delegate

Create a new delegate token

Log in to the Harness Platform and go to Account Settings -> Account Resources -> Delegates. Select the Tokens tab. Select +New Token, and enter a token name, for example firstdeltoken. Select Apply. Harness Platform generates a new token for you. Select Copy to copy and store the token in a temporary file. You will provide this token as an input parameter in the next installation step. The delegate will use this token to authenticate with the Harness Platform.

Get your Harness account ID

Along with the delegate token, you will also need to provide your Harness accountId as an input parameter during delegate installation. This accountId is present in every Harness URL. For example, in the following URL:

6_vVHzo9Qeu9fXvj-AcQCb is the accountId.

Now you are ready to install the delegate on either Docker or Kubernetes.


Ensure that you have access to a Kubernetes cluster. For the purposes of this tutorial, we will use minikube.

Install minikube

  • On Windows:
choco install minikube
  • On macOS:
brew install minikube

Now start minikube with the following config.

minikube start --memory 4g --cpus 4

Validate that you have kubectl access to your cluster.

kubectl get pods -A

Now that you have access to a Kubernetes cluster, you can install the delegate using any of the options below.

Install the Helm chart

As a prerequisite, you must have Helm v3 installed on the machine from which you connect to your Kubernetes cluster.

You can now install the delegate using the delegate Helm chart. First, add the harness-delegate Helm chart repo to your local Helm registry.

helm repo add harness-delegate
helm repo update
helm search repo harness-delegate

You can see that there are two Helm charts available. We will use the harness-delegate/harness-delegate-ng chart in this tutorial.

NAME                                    CHART VERSION   APP VERSION DESCRIPTION                                
harness-delegate/harness-delegate-ng 1.0.8 1.16.0 A Helm chart for deploying harness-delegate

Now we are ready to install the delegate. The following command installs/upgrades firstk8sdel delegate (which is a Kubernetes workload) in the harness-delegate-ng namespace using the harness-delegate/harness-delegate-ng Helm chart.

helm upgrade -i firstk8sdel --namespace harness-delegate-ng --create-namespace \
harness-delegate/harness-delegate-ng \
--set delegateName=firstk8sdel \
--set delegateToken=PUT_YOUR_DELEGATE_TOKEN_HERE \
--set delegateDockerImage=harness/delegate:23.02.78306 \
--set replicas=1 --set upgrader.enabled=false

The above command uses the default values.yaml located in the delegate-helm-chart GitHub repo. If you want change one or more values in a persistent manner instead of the command line, you can download and update the values.yaml file as per your need. You can use the updated values.yaml file as shown below.

helm upgrade -i firstk8sdel --namespace harness-delegate-ng --create-namespace \
harness-delegate/harness-delegate-ng \
-f values.yaml \
--set delegateName=firstk8sdel \
--set delegateToken=PUT_YOUR_DELEGATE_TOKEN_HERE \
--set delegateDockerImage=harness/delegate:23.02.78306 \
--set replicas=1 --set upgrader.enabled=false

Replace the PUT_YOUR_MANAGER_HOST_AND_PORT_HERE variable with the Harness Manager Endpoint noted below. For Harness SaaS accounts, you can find your Harness Cluster Location on the Account Overview page under the Account Settings section of the left navigation. For Harness CDCE, the endpoint varies based on the Docker vs. Helm installation options.

Harness Cluster LocationHarness Manager Endpoint on Harness Cluster
SaaS prod-1
SaaS prod-2
SaaS prod-3
CDCE Dockerhttp://<HARNESS_HOST> if Docker Delegate is remote to CDCE or http://host.docker.internal if Docker Delegate is on same host as CDCE
CDCE Helmhttp://<HARNESS_HOST>:7143 where HARNESS_HOST is the public IP of the Kubernetes node where CDCE Helm is running

Verify delegate connectivity

Select Continue. After the health checks pass, your delegate is available for you to use. Select Done and verify your new delegate is listed.

Helm chart & Terraform Helm provider

Delegate Available

Kubernetes manifest

Delegate Available


Delegate Available

You can now route communication to external systems in Harness connectors and pipelines by selecting this delegate via a delegate selector.


The delegate installer provides troubleshooting information for each installation process. If the delegate cannot be verified, select Troubleshoot for steps you can use to resolve the problem. This section includes the same information.

Harness asks for feedback after the troubleshooting steps. You are asked, Did the delegate come up?

If the steps did not resolve the problem, select No, and use the form to describe the issue. You'll also find links to Harness Support and to Delegate docs.

Use the following steps to troubleshoot your installation of the delegate using Helm.

  1. Verify that Helm is correctly installed:

    Check for Helm:


    And then check for the installed version of Helm:

    helm version

    If you receive the message Error: rendered manifests contain a resource that already exists..., delete the existing namespace, and retry the Helm upgrade command to deploy the delegate.

    For further instructions on troubleshooting your Helm installation, go to Helm troubleshooting guide.

  2. Check the status of the delegate on your cluster:

    kubectl describe pods -n <namespace>
  3. If the pod did not start, check the delegate logs:

    kubectl logs -f <harnessDelegateName> -n <namespace>

    If the state of the delegate pod is CrashLoopBackOff, check your allocation of compute resources (CPU and memory) to the cluster. A state of CrashLoopBackOff indicates insufficent Kubernetes cluster resources.

  4. If the delegate pod is not healthy, use the kubectl describe command to get more information:

    kubectl describe <pod_name> -n <namespace>

For details and a video, go to Delegate overview.

Create your first pipeline

Harness provides multiple methods for creating your pipelines.

The process is the same for all methods:

  1. Add a Kubernetes Cluster connector to connect Harness with your cluster.
  2. Define a Harness service that represents your app or microservice. This includes your manifest and artifact but we'll only using a manifest with a hardcoded artifact in this topic.
  3. Define a target environment.
  4. Define the pipeline execution steps. If you use the Harness Manager, Harness automatically adds the steps you need for different deployment strategies.

First, let's add the manifest we'll be using to the Harness File Store in your project. You can add a manifest from any remote repo, but we'll use the File Store in this topic.

  1. In your Harness project, select Project Setup, and then select File Store.
  2. Select New, and then select New File.
  3. Name the file nginx-deployment.yaml, in File Usage select Manifest, and the select Create.
  4. Paste the following manifest into the new file and select Save.
apiVersion: apps/v1
kind: Deployment
name: nginx-deployment
app: nginx
replicas: 1
app: nginx
app: nginx
- name: nginx
image: nginx:1.14.2
- containerPort: 80

Next, choose one of the following methods for building your pipeline.

The following example creates the Harness entities needed for a simple pipeline that deploys a publicly available Docker Nginx image to your target cluster using the manifest we just added.

For information on using YAML in Harness, go to Harness YAML Quickstart.

Create the Harness connector

We'll create a Harness Kubernetes Cluster connector to connect to your target cluster.

Kubernetes Cluster connector:

name: K8s Cluster
identifier: K8s cluster
description: ""
orgIdentifier: default
projectIdentifier: CD_Docs
type: K8sCluster
type: InheritFromDelegate
- [delegate tag]

Replace [delegate tag] with tag of the delegate you installed in your cluster. For example:

delete tag

Create the Harness service

The following service uses the manifest you added to the Harness File Store earlier.

name: Nginx
identifier: Nginx
tags: {}
- manifest:
identifier: nginx
type: K8sManifest
type: Harness
- /nginx-deployment.yaml
skipResourceVersioning: false
enableDeclarativeRollback: false
primary: {}
type: Kubernetes
Create the Harness environment and infrastructure definition

First, create the Harness environment.

name: myenv
identifier: myenv
tags: {}
type: PreProduction
orgIdentifier: default
projectIdentifier: CD_Docs
variables: []

Next, create the infrastructure definition for that environment. This infrastructure definition uses the Kubernetes Cluster connector you created earlier and targets the default namespace. You can enter a different namespace.

name: myinfra
identifier: myinfra
description: ""
tags: {}
orgIdentifier: default
projectIdentifier: CD_Docs
environmentRef: myenv
deploymentType: Kubernetes
type: KubernetesDirect
connectorRef: K8s_Cluster
namespace: default
releaseName: release-<+INFRA_KEY>
allowSimultaneousDeployments: false
Create the pipeline

Now we can put everything together in a pipeline with a CD stage that deploys the Harness service to the infrastructure definition we added.

The pipeline uses a Kubernetes rolling deployment.

name: cd
identifier: cd
projectIdentifier: CD_Docs
orgIdentifier: default
tags: {}
- stage:
name: nginx
identifier: nginx
description: ""
type: Deployment
deploymentType: Kubernetes
serviceRef: Nginx
environmentRef: myenv
deployToAll: false
- identifier: myinfra
- step:
name: Rollout Deployment
identifier: rolloutDeployment
type: K8sRollingDeploy
timeout: 10m
skipDryRun: false
pruningEnabled: false
- step:
name: Rollback Rollout Deployment
identifier: rollbackRolloutDeployment
type: K8sRollingRollback
timeout: 10m
pruningEnabled: false
tags: {}
- onFailure:
- AllErrors
type: StageRollback

You can now run your pipeline.

View and manage your pipelines

You can view your pipeline executions in Pipeline Executions.

Pipeline Executions

Select any execution to view its steps and logs.

pipeline logs

Next steps

Now that you know the basics of CD pipeline modeling in Harness, go to CD third-party integrations to see how Harness supports your manifest and artifact repos and deployment environments.