Quick Start Setup Guide

Updated 2 weeks ago by Michael Cretzman

This guide is intended to quickly take a new Harness user through a simple Harness setup and deployment, using the Harness Sample App (Application) included in all new accounts. You will first get a summary of Harness building blocks, and will then deploy the Sample App’s Pipeline in your Kubernetes cluster. The guide includes the following sections:

This guide will take as little as a few minutes (assuming that you already have a Kubernetes cluster)—and it offers you an even faster alternative that relies on Harness' in-app Tour Guide. Nearly everything has been set up in the Sample App, so minimal input is required from you.

While we use a specific artifact and deployment environment in this guide, the steps are very similar for all the service providers and deployment environments Harness supports.

Harness Platform Here's a quick overview of Harness' topology and the many technologies Harness supports. The Harness Platform has two components:

  • Harness Manager - Harness Manager is where your deployment configuration is stored, and where your pipelines are managed and executed. Harness Manager is available either as SaaS (running in the Harness cloud) or as On-Prem (running in your infrastructure).

  • Harness Delegate(s) - The Harness Delegate is software you install in your environment. It connects to Harness Manager, and performs Continuous Delivery tasks by connecting to your container orchestration platforms, artifact repositories, monitoring systems, etc.

Harness Architecture

Requirements for This Guide

You can either tour Harness using our Sample App (which requires minimal setup), or deploy to your own environment (for a more complete, hands-on, examination of Harness).

Simple Tour-Guide Option

To simply tour the Harness Sample App, without deploying it, follow Harness’ built-in Tour Guide, as explained in the next section. The Tour Guide's "in-depth" tour option has no prerequisites.

Deploy to Your Own Environment

To follow the deployment steps in this guide from scratch, and also deploy the Harness Sample App, you will need a Kubernetes cluster in your environment. This guide will link you to information on setting up the cluster, and will then walk you through installing the Harness Delegate into the cluster to facilitate deployment.

In-App Tour Guide

Harness includes a built-in Tour Guide that will walk you through deploying the Harness Sample App or simply touring its components. To start the Tour Guide, do the following:

  1. Log into Harness. If you do not have a Harness account, sign up for a free account here.
  2. Once you are logged in, click the blue Help button at Harness Manager's bottom-right corner. This opens the Help Center.

  1. Click the hamburger menu at the upper-left corner (if necessary), then click Tour Guide. The Tour Guide begins with the Welcome message.

    Harness Tour Guide
  2. To deploy the Harness Sample App, click Quickly deploy a sample application. The Tour Guide will lead you through steps similar to those in the remainder of this document—but will streamline your tour by automating several steps.

    Tour Automation

    If you have deployed the Harness Sample App using this option, skip ahead to Review the Cloud and Artifact Connections to examine the app's contents.

    To tour the Harness Sample App without deploying, while learning about its components in detail, click Learn about applications in depth. No matter which path you choose, you can always do the other path next. And if you need to quit the Tour Guide, you can resume your tour by clicking the Help Center's Tour Guide button.

    Reopen Tour

    You will then be provided with an option to resume your tour.

    Resume Tour

Deployment Prerequisites

The following sections will walk you through deploying a sample application to your own Kubernetes cluster. If you have already deployed the Harness Sample App using our in-app Tour Guide, skip ahead to Review the Cloud and Artifact Connections to examine its contents.

Already Deployed? If you have already deployed the Harness Sample App using our in-app Tour Guide, skip ahead to Review the Cloud and Artifact Connections to examine the app's contents.

Need a Cluster? If you have never set up a Kubernetes cluster, use the following article from Harness to get a free-tier Google Cloud Platform (GCP) account, and to set up your cluster: Installation Example: Google Cloud Platform.

Need Help Connecting to a Kubernetes Cluster on Google Cloud Platform? If you already have a cluster created in GCP, follow steps 3 to 5 in the same Harness article to connect to your cluster.

Install and Run the Harness Delegate

Assuming that you have created and connected to a Kubernetes cluster, we can begin deploying using Harness. First, we'll use Harness Manager to install and launch the Harness Delegate (the component that connects your environment to Harness).

As an alternative to the Harness Manager UI, you can also manage your pipelines using using YAML files in your Git repo that are automatically synced with Harness. To learn about our Git-sync functionality, see Configuration as Code.

Download the Delegate

To download the Delegate:

  1. Log into Harness.

  2. In the Harness Manager UI, click Setup.

    Setup is where you configure your microservices, their deployment pipelines, and all the building blocks and resources for those pipelines.

  3. Click Harness Delegates.

  4. Click Download Delegate.

    The resulting drop-down menu offers several Delegate download options, corresponding to the different ways the Delegate can run in your environment:

    Shell Script – You can download the tar.gz file and run the Delegate directly on any Linux VM.

    Docker Image – You can run the Delegate as a Docker instance on any VM.

    Kubernetes YAML – You can run the Delegate as a pod in your K8s cluster.

    ECS Task Spec – You can run the Delegate as an ECS service using this Task Spec.

    For this guide, we will select the Kubernetes YAML option so that the Delegate can run in the same Kubernetes cluster as the application.

  5. Click Kubernetes YAML. The Delegate Setup dialog appears.

  6. In Name, enter the name harness-sample-k8s-delegate exactly.

  7. Click SUBMIT. The YAML file for the Kubernetes Delegate, and its README, will download to your computer as an archive.

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

  9. Extract the YAML file's folder from the download:

    tar -zxvf harness-delegate-kubernetes.tar.gz

  10. Navigate to the harness-delegate folder that you extracted:

    cd harness-delegate-kubernetes

Install and Launch the Delegate in Your Kubernetes Cluster

With the Delegate now downloaded and extracted, we can install and run it.

Before installing the Delegate, ensure that you have kubectl installed in your Kubernetes cluster. For kubectl installation steps, see Install and Set Up kubectl from Kubernetes.

Also, we use the wget command below to test connections. Doing so is optional, but on Mac OS or Windows, you might need to first install wget.
  1. Log into your Kubernetes cluster. For example, if your Kubernetes cluster is in Google Cloud Platform, select the cluster, click Connect, and from the resulting Connect to the cluster dialog, copy the Command-line access command.

  2. In the terminal you used to navigate to the harness-delegate folder, paste the command and press Enter.

    You are now connected to the Kubernetes cluster. If the connection is unsuccessful, ensure that the GCE firewall is not blocking port 22 to your VMs. For more information, see SSH troubleshooting from Kubernetes.

  3. 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: HTTP request sent, awaiting response... 200 OK.

  4. 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

  5. Run this command to verify that the Delegate pod was created:

    kubectl get pods -n harness-delegate

    It will take a moment for the Delegate to appear in Harness' Installations page.

When you onboard your own applications, you might need to install multiple Delegates, depending on their workloads, network segmentation, and firewall zones. Typically, you will need one Delegate for every 300-500 service instances across your applications, and will need one Delegate in each subnet or zone.

Review Cloud and Artifact Connections

The Harness Sample App includes two built-in connections for cloud-data and artifact providers:

  • The Cloud Provider, Harness Sample K8s Cloud Provider. Cloud Providers represent the infrastructure of your applications, such as a Kubernetes cluster, AWS account, Google service account, Azure subscription, or data center. The Harness Sample K8s Cloud Provider will connect Harness with your Kubernetes cluster using the Delegate you installed.

  • The Artifact Server, Harness Docker Hub. This will connect Harness with Docker Hub, the public Docker registry from which the Harness Sample App obtains its sample artifact, a To-Do List app.

In this section, we will review the Harness Sample K8s Cloud Provider's connection to your Kubernetes cluster, and will then review the Harness Docker Hub Artifact Server's settings. You can use these as models for specifying a Cloud Provider and Artifact Server in your own Harness applications.

Review the Cloud Provider

The sample Cloud Provider we have created for you, Harness Sample K8s Cloud Provider, is a logical representation of your Kubernetes cluster. To view this Cloud Provider, do the following:

  1. In Harness Manager, click Setup.
  2. Click Cloud Providers.
    On the Cloud Providers page, you will see the built-in Cloud Provider, Harness Sample K8s Cloud Provider.
  3. Click Harness Sample K8s Cloud Provider. The Cloud Provider dialog appears.
    In this dialog, you can explore the following settings:
    • Type – Kubernetes Cluster is one of the many platforms supported by Harness.
    • Display Name – Identifies this Cloud Provider when you set up your Harness Environments, Service Infrastructures, and other settings. Preset to Harness Sample K8s Cloud Provider in this Sample App.
    • Inherit Cluster details from the selected Delegate – For this guide, we will run the Delegate as a pod in the same cluster used to deploy the sample application. (Harness recommends this practice.)
    • Type – Kubernetes Cluster is one of the many platforms supported by Harness.
    • Delegate Name – This is the same Delegate name that was entered earlier in Install and Run the Harness Delegate.
      harness-sample-k8s-delegate.
    • Skip Validation – You would select this option when you first create a cloud provider.
    • Usage Scope – You can limit the use of a Cloud Provider to specific Harness Applications and Environments. For this tour, we will use the default scopes.
  4. Click the Close or SUBMIT button.

    We're done with Cloud Providers. Next, we'll review the Artifact Server.

Review the Artifact Server

Harness integrates with many different types of repositories and providers. We call these Connectors, and they help you sync with repos, pull in artifacts, integrate verification and analytics tools, and leverage collaboration channels.

For this guide, we only need one Artifact Server, and it is preconfigured with your account. To review the Harness Docker Hub Artifact Server, do the following:

  1. In Setup, click Connectors.
  2. Click Artifact Servers, and then click Harness Docker Hub.
    The Docker Artifact Server dialog appears. In this dialog, you can explore the following settings:
  • TypeDocker Registry is preselected. For the Sample App used in this guide, a To-Do List image is hosted on the Docker Hub repository.
  • Display Name – You’d normally assign this name, to later identify this Artifact Server connection when you add an Artifact Source to a Harness Service. In this Sample App, we've preset to Harness Docker Hub.
  • Docker Repository URL – This is the URL of the public Docker Hub repo.
  • Username and Password – A username and password are required for private repos.
  1. Close the Docker Artifact Server dialog by clicking the Close or SUBMIT button.

We're done reviewing the Artifact Server. We don't need any other connectors for this sample Kubernetes deployment. Next, we'll look at the Harness Sample App.

Review the Harness Sample Application

The Harness Sample App will quickly show you the range of settings that a Harness Application manages. To examine the Sample App, do the following:

  1. In Harness Manager, click Setup.
  2. Scroll to Harness Sample App, and click it. The Sample App appears.

    A Harness Application represents a group of microservices, their deployment pipelines, and all the building blocks for those pipelines. Harness represents your microservice using a logical group of one or more entities:
  • Services - Services represent your microservices. You define the sources of artifacts for those services, and you define the services' container specs, configuration variables, and files.
  • Environments - Environments represent one or more of your deployment infrastructures, such as Dev, QA, Stage, Production, etc.
  • Workflows - Workflows define the deployment orchestration steps, including how a Service is deployed, verified, rolled back, and more. Some of the common Workflow types are Canary, Blue/Green, and Rolling. An Application might have different deployment orchestration steps in different Environments.
  • Pipelines - Pipelines define multiple workflows and approvals in sequential and/or parallel stages as a new build progresses through your release process.
  • Triggers - Triggers automate deployments using a variety of conditions, such as Git events, new artifacts, schedules, and the success of other pipelines.
  • Infrastructure Provisioners - Infrastructure Provisioners define blueprints from known Infrastructure-as-Code technologies (Terraform, Cloud Formation, etc.), and map the outputs (such as load balancers, VPCs, etc.). They enable Workflows to provision infrastructure on the fly when deploying Services.

To sum up, Harness Applications organize all of the entities and configurations in Harness CI/CD. Now that you've seen the components of a Harness Application, it's time to deploy the Application to your Kubernetes cluster.

Deploy the Harness Sample Application

Here's what you've been waiting for—assuming you haven't already deployed the application via Harness' Tour Guide. Let's explicitly deploy the Kubernetes sample application to your Kubernetes cluster. In Harness Manager, click Continuous Deployment.

The Harness Continuous Deployment dashboard appears. If this is your account's first deployment, the dashboard will be blank.

Here you will see all deployments, with their stages, successes and failures. See which user deployed each pipeline, and which artifacts were pulled or copied from your Artifact Server and deployed to your Cloud Provider.

You can deploy a Pipeline or a Workflow. We're going to deploy the Pipeline we looked at in Review the Harness Sample Application. To do so:

  1. On the Continuous Deployment dashboard, click Start New Deployment. The Start New Deployment dialog appears.
  2. In Application, select the Harness Sample App.
  3. In Pipeline, select K8s Prod Pipeline.

    After you select the Pipeline, the Artifacts section will appear. Harness generates a list of all of the artifacts available in the Artifact Source for the Service being deployed.
  4. From Build / Version menu, select any Build#.

    When you are done, the Start New Deployment dialog will look like this:
  5. To begin deploying your Pipeline and artifact, click SUBMIT.

    Below, we'll look at each of the deployment stages.

Stage 1 Deploying

The QA stage is the Pipeline's first stage of deployment. Here, you can watch the execution of each step of Stage 1 in the To-Do List K8s Workflow.

Once QA is complete, the Approval stage will start. Watch the QA deployment stage, and wait for the Approval step.

Stage 2 Approve Deployment

Your approval is required before the Pipeline can continue the release process. Click APPROVE.

If you are the Admin for the Harness account, or are listed in the Workflow’s Notification Strategy, you will receive an email notifying you of a pending approval:

Stage 3 Deploying

Watch Stage 3 deploy the Docker image from the To-Do List K8s Service to your Kubernetes cluster.

Deployment Finished!

To see your deployed To-Do List app running in your browser, click the Rollout Deployment node in Stage 3 Prod, and then click the link to the right of Load Balancer.

If the deployment timed out trying to set up the load balancer, it is most likely because the Google Cloud account you are using for your Kubernetes cluster has reached its load balancer quota. For more information, see Resource Quotas from Google Cloud.

The To-Do List app will open in a new tab. Once you see the app, return to the browser tab for Continuous Deployment.

The To-Do List app is deployed and running in your Kubernetes cluster. This Quick Start Guide is now complete. Next, use the Harness Tour Guide to examine the Harness Sample App in greater detail.

Tour the Harness Sample App in Detail

To look through the Harness Sample App in greater detail, without deploying it, simply log into Harness, click Setup, and then, in Applications, click the Harness Sample App. Click through the Application's components to see how Harness sets up and deploys a microservice.

You can also tour the Harness Sample App using Harness built-in Tour Guide:

  1. Click the blue Help button at Harness Manager's bottom-right corner.
  2. In the Help Center, click Tour Guide. The Tour Guide Welcome message appears.
  3. Click Learn about application in depth.
  4. Follow the steps in the tour. The tour will take you through each of the Harness Sample App's components and explain how it is configured.

Next Steps

Now that you've installed the Harness Sample App, proceed to our Tour Harness Manager topic. This provides an annotated visual guide to the Harness Dashboard, and to other key features of Harness' graphical UI.

Troubleshooting

This section suggests how to resolve common problems in completing the above Quick Start.

Delegate Not Showing Up?

If you successfully ran the command to install the Delegate in your Kubernetes cluster (kubectl apply -f harness-delegate.yaml), but the Delegate does not appear on the Installations page, try each of the following steps:

  1. Run following command to see if the Delegate pod is running in your Kubernetes cluster:

    kubectl get pods -n harness-delegate

    The harness-delegate parameter is the namespace in your Kubernetes cluster.
  2. Check if your cluster has outbound connectivity to Harness and Docker Hub. From your cluster, try this:

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

    wget -p https://hub.docker.com/ -O /dev/null
  3. Check if you have enough system resources in your Kubernetes cluster. The Harness Delegate requires a minimum of 1 CPU and 8GB RAM per node. (The operating system will require additional RAM.)
  4. Follow the steps in this brief procedure from Harness.
  5. Reach out to Harness (support@harness.io) if you are still experiencing a problem.


How did we do?