Quick Start Setup Guide

Updated 1 month ago by Michael Cretzman

This guide is intended to take a new Harness user through a simple Harness setup and deployment quickly using the Harness Sample App included in all new accounts.

First, you're going to get a summary of the building blocks of Harness using a sample Harness Application. Next, you will deploy the sample Application's Pipeline in your Kubernetes cluster.

This guide will only take a few minutes. Nearly everything has been set up with the sample Application. There is minimal input from you.

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

Harness Platform

If you are completely new to Harness, take a look at the overall Harness architecture to help you visualize the 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 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 that connects to the Harness Manager and performs Continuous Delivery tasks by connecting to your container orchestration platforms, artifact repositories, monitoring systems, etc.

Requirements for this Guide

There are no requirements to simply tour the Harness Sample App. To tour the Harness Sample App without deploying it, see the steps in Tour Guide.

If you want to follow the deployment steps in this guide and deploy the Harness Sample App, you will need a Kubernetes cluster in your environment. This guide will provide you with links to information for setting up the cluster, and then walk you through installing the Harness Delegate into the cluster to facilitate deployment.

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 Help button at the bottom-right of the Harness Manager.

    The Help Center appears.

  3. Click Tour Guide. The Tour Guide begins with the Welcome message.

  4. To deploy a sample application, click Quickly get started with a sample application. To tour the Harness Sample App and learn about its components in detail, click Learn about applications is 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 Tour Guide button in the Help Center. You will be provided with an option to resume your tour:

Deployment Overview

This guide will walk you through deploying a sample app to your own Kubernetes cluster. We assume you are familiar with Kubernetes and have set up a cluster before.

Need a Cluster?

If you have never set up a Kubernetes cluster, use the following article from Harness to get a free tier account with Google and 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 this article from Harness to connect to your cluster: Installation Example: Google Cloud Platform.

Install and Run the Harness Delegate

Now that you have the Kubernetes cluster prerequisite, we can get started.

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

You can manage your pipeline using the Harness Manager UI or YAML files in your Git repo that are synced with Harness automatically.

For this guide, we will use the Harness Manager. To learn about our Git-sync functionality, see Configuration as Code.

To install the Harness Delegate, do the following:

  1. Download the Delegate.
    1. Log into Harness.
    2. In the Harness Manager, click Setup.
    3. Click Harness Installations.
    4. Click Download Delegate. This menu contains the different Delegate download options.

      There are many 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.

      For this guide, we will select the Kubernetes YAML option so 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.

      This name is required because Harness comes with a built-in Cloud Provider that uses the Delegate name harness-sample-k8s-delegate to connect to your Kubernetes cluster. Please ensure the name harness-sample-k8s-delegate is entered correctly before continuing.

      When you are done the Delegate Setup dialog will look like this:

    7. Click SUBMIT. The YAML file for the Kubernetes Delegate will be downloaded to your computer by your browser.
    8. Open a terminal and navigate to where the Delegate file is located.
    9. Extract the YAML file from the download:

      tar -zxvf harness-delegate-kubernetes.tar.gz
    10. Navigate to the harness-delegate folder that was extracted:

      cd harness-delegate-kubernetes
  2. Install and run the Delegate in your Kubernetes cluster. Before installing the Delegate, ensure that you have kubectl installed in your Kubernetes cluster. For installation steps, see Install and Set Up kubectl from Kubernetes.
    1. Log into your Kubernetes cluster. For example, if your Kubernetes cluster is in Google Cloud Platform, select the cluster, click Connect, and in the 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 the GCE firewall isn’t 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. To 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 the Installations page in Harness.

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

Review Cloud and Artifact Server Connections

Harness comes with two built-in connections for the Harness Sample App:

  • The Cloud Provider Harness Sample K8s Cloud Provider. Cloud Providers represent the infrastructure of your applications. Typically, a Cloud Provider is mapped to a Kubernetes cluster, AWS account, Google service account, Azure subscription, or a 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. The Harness Docker Hub Artifact Server connects Harness with the public Docker registry, Docker Hub, 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 review the Harness Docker Hub Artifact Server settings.

Review the Cloud Provider

A Cloud Provider is a logical representation of your Kubernetes cluster. We have created a sample Cloud Provider for you, Harness Sample K8s Cloud Provider.

To view the Harness Sample K8s Cloud Provider, do the following:

  1. In the 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.

    • Type - Kubernetes Cluster is one of the many platforms supported by Harness.
    • 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.
    • Delegate Name - This is the same Delegate name that was entered earlier in the Harness Delegate installation: harness-sample-k8s-delegate.
    • 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 scope.
  4. Click close or SUBMIT. 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 pull in artifacts, sync with repos, integrate verification and analytics tools, and leverage collaboration channels.

For this guide, we only need one Artifact Server and it is pre-configured 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.

    • Type - Docker Registry is selected. For the sample application using in this guide, a To-Do List image is hosted on the Docker Hub repository.
    • 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.
  3. Close the Harness Docker Hub Artifact Server by clicking the X or SUBMIT.

We're done with 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 Application.

Review the Harness Sample Application

Harness includes a sample Application to quickly show you how a Harness Application works, Harness Sample App. In this section, we'll quickly review the components of the Application.

To review the Harness Sample App, do the following:

  1. In Harness Manager, click Setup.
  2. Click Harness Sample App. The sample Application 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 where the artifacts for those services come from, and you define the container specs, configuration variables, and files for those services.
  • 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, 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) and map the output (such as load balancers, VPCs, etc). They enable Workflows to provision infrastructure on the fly when deploying Services.

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

Let's deploy the Kubernetes sample Application to your Kubernetes cluster. In Harness Manager, click Continuous Deployment.

The Harness Continuous Deployment dashboard appears. If this is the first deployment, then the dashboard will be blank.

Here you will see all deployments, 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 deploy the Harness Sample App, do the following:

  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. Click the menu, select any Build# <version>. Note: If you select latest for an artifact version, you will lose the ability to rollback. As a best practice, avoid choosing latest.

    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 the different deployment stages.

Stage 1 is Deploying

The QA stage is the first stage of deployment for the Pipeline. You can watch each step of the To-Do List K8s Workflow in Stage 1 execute.

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

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 listed in the Notification Strategy of the Workflow, you will receive an email notifying you or a pending approval:

Stage 3 is Deploying

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

Deployment Finished!

To see the To-Do List app you deployed running in your browser, click the Rollout Deployment node in Stage 3 Prod, and then click the link next to 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 detail.

Tour the Harness Sample App

To look through the Harness Sample App without deploying it, simply log into Harness, click Setup, and then, in Applications, click the Harness Sample App. Look through the steps of the Application 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 Help button at the bottom-right of the Harness Manager.
  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 components and explain how they are configured.


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 in 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.
  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?