Harness CD Community Edition Quickstart

Updated 3 weeks ago by Michael Cretzman

This quickstart shows you how to set up Harness CD Community Edition locally and create a CD Pipeline that deploys a public NGINX image to a local cluster.

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.

Objectives

You'll learn how to:

  1. Install and run Harness CD Community Edition locally.
  2. Create and deploy a CD Pipeline in Harness CD Community Edition using a public Docker image and a local Kubernetes cluster.

Requirements

  • Harness CD Community Edition:
    • Docker Desktop minimum version 4.3.1 (72247)
      • 3GB RAM and 2 CPUs is the minimum.
      • Docker Compose (included in Docker Desktop).
    • 20GB of free disk space.
  • Quickstart:
    • GitHub account. You will use your GitHub account to pull a publicly available manifest (https://github.com/kubernetes/website/blob/main/content/en/examples/application/nginx-app.yaml).
    • Docker Compose Kubernetes is installed and running in Docker Desktop (a new installation of Docker Desktop might need to have Kubernetes enabled in its Settings).
      Docker Compose Kubernetes should have at least 2GB memory and 1 CPU. That will bring the total Docker Desktop resources up to a minimum of 5GB and 3 CPUs.
    If you want to use Minikube instead of Docker Desktop Kubernetes, use Minikube minimum version v1.22.0 or later installed locally. Minikube needs 4GB and 4 CPUs:minikube start --memory 4g --cpus 4
    • Kubernetes cluster. This is the target cluster for the deployment you will set up in this quickstart. When Docker Compose Kubernetes is installed it comes with a cluster and the default namespace. You don't need to make any changes to Docker Compose Kubernetes.
      Don't have a cluster? See Notes.
    • Review Harness CD Community Edition Overview and Harness Key Concepts to establish a general understanding of Harness.
The Docker Compose installer is described below, but Harness also supports a Helm installer.
Completely New to Continuous Delivery (CD)?

Simply put, CD is the automation of a software release process. In Harness, you model this process as a Pipeline.

What do I need for a CD Pipeline?

  1. An artifact to deploy: an artifact is the application or microservice you are deploying. It can be a Docker image, a zip file, etc.
  2. A deployment method: this is whatever specification or manifest is needed by the deployment platform you are using, such as a Kubernetes manifest.
  3. A place to deploy it: this is your target environment, such as a Kubernetes cluster.

Harness takes care of the rest.

Architecture Summary

Harness CD Community Edition has two main components:

  • Harness Manager: the Harness Manager is where your CD configurations are stored and your pipelines are managed. After you install Harness, you sign up in the Manager at http://localhost/#/signup. Pipelines are triggered manually in the Harness Manager or automatically in response to Git events, schedules, new artifacts, and so on.
  • Harness Delegate: the Harness Delegate is a software service you install in your environment that connects to the Harness Manager and performs tasks using your container orchestration platforms, artifact repositories, etc. You can install a Delegate inline when setting up connections to your resources or separately as needed. This guide will walk you through setting up a Harness Delegate inline.

Step 1: Installation

Installation and deployment should take about 10 minutes.
The Docker Compose installer is described below, but Harness also supports a Helm installer.

Make sure your system meets the Requirements above.

Ensure Docker Desktop is running and Docker Desktop Kubernetes is running with it.

Clone the Harness Git repo into your local directory:

git clone https://github.com/harness/harness-cd-community

The output will look something like this:

Cloning into 'harness-cd-community'...
remote: Enumerating objects: 793, done.
remote: Counting objects: 100% (793/793), done.
remote: Compressing objects: 100% (371/371), done.
remote: Total 793 (delta 497), reused 592 (delta 339), pack-reused 0
Receiving objects: 100% (793/793), 116.39 KiB | 2.42 MiB/s, done.
Resolving deltas: 100% (497/497), done.

Change directory to the harness folder:

cd harness-cd-community/docker-compose/harness

Build and run Harness using Docker Compose:

docker-compose up -d

Do not try to bring up containers one by one. Harness CD Community Edition is a distributed system with dependencies. The only way to bring it up is using docker-compose up -d.
The first download can take 3–12 mins (downloading images and starting all containers) depending on the speed of your Internet connection. You won't be able to sign up until all the required containers are up and running.

The output will look something like this:

[+] Running 13/13
⠿ Network harness_harness-network Created 0.1s
⠿ Container harness_log-service_1 Started 2.9s
⠿ Container harness_redis_1 Started 2.7s
...

Run the following command to ensure all services are running:

docker-compose ps

All services should show running (healthy). If any show running (starting), wait a minute, and run docker-compose ps again until they are all running (healthy).

Run the following command to start the Harness Manager (it will wait until all services are healthy):

docker-compose run --rm proxy wait-for-it.sh ng-manager:7090 -t 180

The output will look like this:

[+] Running 6/0
⠿ Container harness_platform-service_1 Running 0.0s
⠿ Container harness_pipeline-service_1 Running 0.0s
⠿ Container harness_manager_1 Running 0.0s
⠿ Container harness_delegate-proxy_1 Running 0.0s
⠿ Container harness_ng-manager_1 Running 0.0s
⠿ Container harness_ng-ui_1 Running 0.0s
wait-for-it.sh: waiting 180 seconds for ng-manager:7090
wait-for-it.sh: ng-manager:7090 is available after 0 seconds

Wait until you see that ng-manager is available:

wait-for-it.sh: ng-manager:7090 is available after 0 seconds

In your browser, go to the URL http://localhost/#/signup.

If you see a 403 error, that just means the Harness Manager service isn't up and running yet. Make sure you ran the wait-for-it.sh script earlier and wait a few minutes: docker-compose run --rm proxy wait-for-it.sh ng-manager:7090 -t 180.

Enter an email address and password and click Sign up.

You'll see the CD page:

You're now using Harness!

The next section walks you through setting up and running a simple CD Pipeline using a public manifest and Docker image.

Step 2: Create Pipeline

We'll create a quick CD Pipeline that deploys a public manifest and image to a local Kubernetes cluster. The following steps are similar to the Kubernetes CD Quickstart.

In Harness, click Create Project.

In About the Project, in Name, enter Quickstart, and then click Save and Continue.

In Invite Collaborators, click Save and Continue. Your new project appears. Let's add a CD Pipeline.

In Setup Pipeline, enter the name quickstart, and then click Start. Your new Pipeline is started!

Now let's jumpstart your Pipeline setup by pasting in the YAML for a Pipeline. Once it's pasted in, we'll update a few placeholders and then deploy.

Copy the following YAML:

pipeline:
name: quickstart
identifier: quickstart
projectIdentifier: Quickstart
orgIdentifier: default
tags: {}
stages:
- stage:
name: demo
identifier: demo
description: ""
type: Deployment
spec:
serviceConfig:
serviceRef: <+input>
serviceDefinition:
type: Kubernetes
spec:
variables: []
manifests:
- manifest:
identifier: nginx
type: K8sManifest
spec:
store:
type: Github
spec:
connectorRef: <+input>
gitFetchType: Branch
paths:
- content/en/examples/application/nginx-app.yaml
repoName: <+input>
branch: main
skipResourceVersioning: false
infrastructure:
environmentRef: <+input>
infrastructureDefinition:
type: KubernetesDirect
spec:
connectorRef: <+input>
namespace: <+input>
releaseName: release-<+INFRA_KEY>
allowSimultaneousDeployments: false
execution:
steps:
- step:
type: K8sRollingDeploy
name: Rollout Deployment
identifier: Rollout_Deployment
spec:
skipDryRun: false
timeout: 10m
rollbackSteps: []
serviceDependencies: []
tags: {}
failureStrategies:
- onFailure:
errors:
- AllErrors
action:
type: StageRollback

In the Pipeline Studio, click YAML.

Click Edit YAML.

Replace all of the YAML with the YAML you copied above.

Click Save.

Click Visual. The new Pipeline is created.

Let's quickly review some key Pipeline concepts:
  • Harness Delegate: the Harness Delegate is a software service you install in your environment that connects to the Harness Manager and performs tasks using your container orchestration platforms, artifact repositories, monitoring systems, etc.
  • Pipelines: A CD Pipeline is a series of Stages where each Stage deploys a Service to an Environment.
  • Stages: A CD Stage is a subset of a Pipeline that contains the logic to perform one major segment of the deployment process.
  • Services: A Service represents your microservices and other workloads logically. A Service is a logical entity to be deployed, monitored, or changed independently.
  • Service Definition: Service Definitions represent the real artifacts, manifests, and variables of a Service. They are the actual files and variable values.
  • Environments: Environments represent your deployment targets logically (QA, Prod, etc).
  • Infrastructure Definition: Infrastructure Definitions represent an Environment's infrastructure physically. They are the actual target clusters, hosts, etc.
  • Execution Steps: Execution steps perform the CD operations like applying a manifest, asking for approval, rollback, and so on. Harness automatically adds the steps you need for the deployment strategy you select. You can then add additional steps to perform many other operations.
  • Connectors: Connectors contain the information necessary to integrate and work with 3rd party tools such as Git providers and artifact repos. Harness uses Connectors at Pipeline runtime to authenticate and perform operations with a 3rd party tool.

You'll notice a Runtime Input expression <+input> for most of the settings. These are placeholders we'll replace when we run the Pipeline.

Click Run. The Run Pipeline settings appear.

Now let's update the placeholders.

Placeholder

Steps

Specify Service

Click New Service.

In Name, enter nginx.

Click Save.

Manifests

Here you'll add a Connector to Github using your personal GitHub credentials.

Credentials are encrypted and stored locally in the MongoDB service installed as part of Harness CE.

You'll also install a Harness Kubernetes Delegate in your local Kubernetes cluster. This Delegate will perform all operations at runtime.

Connector

Click the Connector dropdown menu.

Click New Connector.

In Name, enter GitHub, and then click Continue.

In URL Type, select Repository.

In Connection Type, select HTTP.

In GitHub Repository URL, enter https://github.com/kubernetes/website.

Click Continue.

In Username, enter your GitHub account username.

In Personal Access Token, click Create or Select a Secret.

Click New Secret Text.

In Secret Name, enter the name github-pat.

In Secret Value, paste in a GitHub Personal access token.

When you're logged into GitHub, these are typically listed at https://github.com/settings/tokens. For steps on setting up a GitHub PAT, see Creating a personal access token from GitHub.

Ensure you PAT has the repo scope selected:

Click Save, and then click Continue.

In Connect to the provider, click Connect through a Harness Delegate, and then Continue.

In Delegates Setup, click Install a New Delegate.

Click Kubernetes, and then click Continue.

Enter a name quickstart for the Delegate, click the Laptop size, and then click Continue.

Click Download YAML file.

The YAML file for the Kubernetes Delegate will download to your computer.

Open a terminal and navigate to where the Delegate file is located.

If you're using a remote Kubernetes cluster, see Notes.

In the terminal, run this command:

kubectl apply -f harness-delegate.yaml

This installs the Delegate into the default cluster that comes with Docker Desktop Kubernetes. It can take a few minutes for the Delegate pod to run.

Run kubectl get pods -n harness-delegate-ng to verify that it is Ready: 1/1 and Status: Running.

Back in Harness, click Continue.

Once the Delegate registers, click Done.

In Delegates Setup, click Connect only via Delegates which has all of the following tags, and then select the tag for your new Delegate (quickstart).

Click Save and Continue.

The Connection Test should prove successful. If not, review your credentials.

Click Finish.

Repository Name

Enter https://github.com/kubernetes/website.

Infrastructure

Here you'll create a connection to the target cluster for this CD stage.

Specify Environment

Click New Environment.

In Name, enter quickstart, select Non-Production, and click Save.

Connector

Click the Connector dropdown menu, and then click New Connector.

In Name, enter localK8s, and then click Continue.

In Details, click Use the credentials of a specific Harness Delegate, and then click Continue.

If you are running a local Delegate but using a target cluster that does not have a Delegate installed in it, select Specify master URL and credentials, and then see Notes.

In Delegates Setup, select Connect only via Delegates which has all of the following tags, and then enter and select quickstart. The Delegate you added earlier is selected.

Click Save and Continue.

In Connection Test, click Finish.

Namespace

Enter default.

If you are using a different namespace, such as a namespace given to you by someone in your company, enter that namespace instead.

Now that the placeholders are configured, you can deploy the Pipeline.

If you want to save these settings, you can click Save as Input Set. Then you can use them whenever you run this Pipeline.

Step 3: Deploy

In Run Pipeline, click Run Pipeline.

You can see the Pipeline fetch the manifest and deploy the NGINX artifact to your local cluster.

Click Console View to see more of the logs and watch the deployment in realtime.

In the Rollout Deployment step, in Wait for Steady State, you'll see that NGINX was deployed successfully:

Status : my-nginx   deployment "my-nginx" successfully rolled out

Congratulations! You have a successful local deployment using Harness CD Community Edition!

Now you can use Harness to deploy remotely. Simply follow the same steps but use a remote target cluster.

Clean Up

To clean up your environment, do the following.

To delete the Delegate, run the following:

kubectl delete statefulset -n harness-delegate-ng quickstart

To remove Harness CD Community Edition, run the following:

docker-compose down -v

To remove the Harness images, use docker rmi to removes images by their ID.

To remove the image, you first need to list all the images to get the Image IDs, Image name and other details. Run docker images -a or docker images.

Note the images you want to remove, and then run

docker rmi <image-id> <image-id> ...

To remove all images at once, run:

docker rmi $(docker images -q)

Community and Support

Use the following resources to ask questions, find answers, and give feedback:

Upgrades

We are updating builds on a daily basis to fix issues and add features. To upgrade your setup, do the following:

  1. Navigate to the harness-cd-community folder in your terminal.
  2. Run git pull in a terminal in the harness-cd-community folder.
  3. Run docker-compose down in the harness-cd-community/docker-compose/harness folder.
  4. Run docker-compose up -d in the harness-cd-community/docker-compose/harness folder.

Next Steps

In this tutorial, you learned how to:

  1. Install and run Harness CD Community Edition locally.
  2. Create and deploy CD Pipeline in Harness CD Community Edition using a public Docker image and a local Kubernetes cluster.

Try some other tutorials to learn more about Harness CD:

Notes

The following notes will help you if your set up is different from the general steps in this quickstart.

What if I don't have my own Kubernetes cluster?

You have a few Kubernetes cluster options.

Docker Compose Kubernetes

when Docker Compose Kubernetes is installed it comes with a cluster and the default namespace. You don't need to make any changes to Docker Compose Kubernetes. This is recommended.

Free-tier account Kubernetes cluster on AWS, GCP, Azure

The popular cloud providers offer free-tier accounts that include their Kubernetes services. You can create a cluster in these accounts.

Use one of your company's Kubernetes clusters

If your company uses Kubernetes, they likely have dev or QA accounts on a cloud platform. If you have access to those environments, you can add a cluster there.

If you don't have access, you can request access to a namespace in an existing cluster. Just ask for access to a namespace and a service account with permission to create entities in the target namespace.

The YAML provided for the Harness Delegate defaults to the cluster-admin role because that ensures anything could be applied. 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 listgetcreatewatch (to fetch the pod events), and delete permissions for each of the entity types Harness uses.

If you don’t want to use resources: [“*”] for the Role, you can list out the resources you want to grant. Harness needs configMapsecreteventdeployment, and pod at a minimum for deployments, as stated above.

What if I have a local cluster for the Delegate but want to deploy to a remote cluster?

If you can't use a local or remote cluster for both the Harness Delegate and the deployment, you'll be fine.

Install the Delegate locally and then when you set up the Harness Kubernetes Cluster Connector, select Specify master URL and credentials and use the target cluster master URL and a Kubernetes service account token from the target cluster to connect.

You can get the master URL by connecting to the cluster and running kubectl cluster-info.

To use a Kubernetes Service Account (SA) and token, you will need to either use an existing SA that has the cluster-admin permission (or namespace-level admin permissions) or create a new SA and grant it the cluster-admin permission (or namespace-level admin permissions).

For example, here's a manifest that creates a new SA named harness-service-account in the harness namespace.

# harness-service-account.yml
apiVersion: v1
kind: ServiceAccount
metadata:
name: harness-service-account
namespace: harness

Next, you apply the SA.

kubectl apply -f harness-service-account.yml

Next, grant the SA the cluster-admin permission.

# harness-clusterrolebinding.yml
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
name: harness-admin
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- kind: ServiceAccount
name: harness-service-account
namespace: harness

Next, apply the ClusterRoleBinding.

kubectl apply -f harness-clusterrolebinding.yml

Once you have the SA added, you can gets its token using the following commands.

SERVICE_ACCOUNT_NAME={SA name}

NAMESPACE={target namespace}

SECRET_NAME=$(kubectl get sa "${SERVICE_ACCOUNT_NAME}" --namespace "${NAMESPACE}" -o=jsonpath='{.secrets[].name}')

TOKEN=$(kubectl get secret "${SECRET_NAME}" --namespace "${NAMESPACE}" -o=jsonpath='{.data.token}' | base64 -d)

echo $TOKEN

The | base64 -d piping decodes the token. You can now enter it into the Harness Kubernetes Cluster Connector Service Account Token using a Harness secret.

How do I connect to a remote Kubernetes cluster?

If you are using a remote Kubernetes cluster, you must log into it before you can install the Harness Kubernetes Delegate and deploy to that cluster.

How you connect to the remote cluster depends on the provider. Typically, you will need to install the provider's CLI locally and then use the CLI to connect to the cluster and run the kubectl command to install the Harness Delegate. See the following:

Azure AKS

See the Azure doc Quickstart: Deploy an Azure Kubernetes Service cluster using the Azure CLI for a good overview.

The commands will look something like this.

Install the Azure CLI

az aks install-cli

Set the Azure subscription to use.

az account set --subscription [subscription-id]

Connect to the cluster:

az aks get-credentials --resource-group [resource-group-name] --name [cluster-name]

Test the connection:

kubectl get nodes

Next, you simply run the command to install the Delegate:

kubectl apply -f harness-delegate.yaml
AWS EKS

See the AWS doc Connecting a cluster for a good overview.

Once you're connected, you simply run the command to install the Delegate:

kubectl apply -f harness-delegate.yaml
GCP GKE

See the GCP doc Install kubectl and configure cluster access for a good overview.

Basically, you just need to install the gcloud CLI as described in Installing the gcloud CLI from GCP.

Once gcloud is installed you can connect to the remote cluster.

The command will look something like this.

gcloud container clusters get-credentials [cluster-name] --zone [zone-name] --project [project-name]

Once you're connected, you simply run the command to install the Delegate:

kubectl apply -f harness-delegate.yaml


Please Provide Feedback