Harness Quick Start Setup Guide
This guide is intended to take DevOps and developers through a simple CI/CD Harness set up quickly.
In 10 minutes, you will have a successful deployment of an open source, publicly-available Tomcat artifact to a Kubernetes cluster on Google Cloud Platform (GCP).
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.
Requirements for this Guide
While Harness supports many repositories, container orchestration tools, and deployment environments, this Quick Start Guide only uses a few components:
- Harness SaaS and your browser. You can get a free Harness SaaS account here.
- One-way connectivity from the Harness Delegate to Harness Manager. When you download and install the Delegate from the Harness Manager, you’ll have the connectivity you need for this guide. The Delegate will connect to artifact and cloud providers using your Internet connection.
- An open-source Tomcat artifact as the application we want to deploy. We will get Tomcat from the publicly-available Docker Hub using the Harness Manager. You will need a free Docker Hub account and Harness will take care of the rest.
- A Kubernetes cluster on GCP for our deployment environment. You will need a free GCP account and Harness will manage deployment. Details about the minimum settings for the cluster on Kubernetes Engine are included in the steps in this guide.
Let’s get started.
The Harness Delegate is a service you run in your local network to connect your infrastructure, collaboration, and verification providers with the Harness Manager.
- Sign into Harness SaaS.
- Download and install the Harness Delegate.
- Click Setup.
- Click Harness Installations.
- Click Download Delegate.
- For Shell Script, unzip the file and run the start.sh script (
For Docker, unzip the file and run the start script (
$ ./launch-harness-delegate.sh). You will see the Docker image pull, for example:
latest: Pulling from harness/delegate 297061f60c36: Pull complete… Status: Downloaded newer image for harness/delegate:latest
For Kubernetes, unzip the file and run the following commands (ensure you have kubectl installed and credentials to access your Kubernetes cluster):
$ kubectl apply -f harness-delegate.yaml(installs or replaces the Harness delegate)
$ kubectl get pods -n harness-delegate(get pod names)
$ kubectl logs pod-name -n harness-delegate -f(see startup logs)
$ kubectl exec pod-name -n harness-delegate -it -- bash(run a shell in a pod)
If needed, edit the harness-delegate.yaml you unzipped to change the namespace, set proxy settings, or to enter a delegate description.You do not need root privileges. The delegate does need:
- HTTPS port 443 outbound to Harness.
- API/HTTP access to your cloud providers, container orchestration tools, verification providers, continuous integration tools, artifact repositories, collaboration providers, SSH access to physical and virtual servers.
- For Shell Script, unzip the file and run the start.sh script (
- Click Setup.
- Once the delegate is installed, refresh the Installations page. Your Delegate is listed.
On to Add a Connector.
Now that app.harness.io and your delegate are connected, you can connect your artifact server and cloud provider. You will add the artifact server containing the image you want to deploy and the cloud provider where you will deploy the Kubernetes containers.
- Add the Artifact Server.
- Click Setup.
- Click Connectors.
- Expand Artifact Servers.
- Click Add Artifact Server. The Artifact Server dialog appears.
- In Type, pick Docker Registry. Once you’ve selected a provider, the dialog will display provider-specific fields.
- In Docker Registry URL, enter the URL for the public Docker Registry, https://registry.hub.docker.com/v2/.
- Enter a username and password for the provider (your Docker Hub account).
- In Display Name, enter a display name or let Harness generate one for you.
- Click SUBMIT. The artifact server is displayed.
Add the Cloud Provider.For a Kubernetes deployment on GCP, you need a GCP cluster on Kubernetes Engine in your GCP. For information on creating a cluster, see Creating a Cluster from Google. Ensure that the GCP cluster that you will use to deploy your service has enough resources. Here is an example of a cluster with adequate resources for Tomcat:
- Click Setup.
- Click Cloud Providers.
- Click Add Cloud Provider. The Cloud Provider dialog opens.
In this guide, we will add a GCP cloud provider, but there are several other provider options. In all cases, you will need to provide access keys in order for the delegate to connect to the provider.
- In Type, select Google Cloud Platform. Next you will upload the Google Cloud account service key file. The GCP service account you use must have the
Kubernetes Engine Admin (GKE Admin) and
Storage Object Viewer roles assigned to it.
For steps to add roles to your service account, see Granting Roles to Service Accounts from Google.
Here is what the permissions look like in GCP:
When you create this role GCP will create a service and account key file in the JSON format and download it onto your computer. This is the file you will upload into Harness. For information on creating a new service key file, see Creating and Managing Service Account Keys.
- Click Choose File, select your service and account key file and click Open. The Google Cloud Account Name is automatically entered.
- Click SUBMIT. The GCP cloud provider is added.
On to Add Your Service.
A service in Harness contains an artifact (software image), artifact source server, deployment specification, and any configuration files. In this guide, you create a service using the Tomcat Docker image from the public Docker Registry that we added as a source server in Connect Providers.
- Click Setup, and then click Add Application. The Application dialog appears.
- Let's enter the name kube-app for your application, and click SUBMIT. Your new application appears.
- Click your application’s name. The application entities appear.
- Click Services, and then click Add Service. The Service dialog appears.
- Enter the name micro-service for the service. In Artifact Type, select an artifact type, such as Docker Image, and click SUBMIT. The Service Overview appears.
- Click Add Artifact Source and select the type of artifact source server, Docker Registry. The Artifact Source dialog appears.
The fields in the dialog will be different depending on the type of artifact server you selected. In our example, we are using Docker Registry. Once you have selected a source server and artifact, Harness will generate a name for the artifact source.
- In Source Server, select the name of the artifact source server you added in Connect Providers (typically, registry_hub_docker_com).
- Click in Docker Image Name and select or enter the name of the artifact you want to deploy, library/tomcat. By default, Harness automatically populates the field with the artifacts available from the source
server, but Docker Hub does not allow anyone to scan its images. When you are done, the dialog will look like this:
- Click SUBMIT. The new service is listed in the Services Overview.
If you click Artifact History you will see the build history that Harness pulled from the source server.
On to Set Your Environment.
An environment for your application can be Dev, QA, Production, or any production stage. Once an environment is created, you can deploy one or more services to it.
- Click Setup, click your application name, and then click Environments.
Tip: you can also navigate between the components of an application using the drop-down menu next to the component names:
- Click Add Environment. The Environment dialog appears.
- Enter the name Dev, a description, select the environment type Non-Production, and click SUBMIT. The Environment Overview page appears. Next, you need to add a service infrastructure for the environment. This is the cloud provider you added in Connect Providers.
- Click Add Service Infrastructure. The Service Infrastructure dialog appears.
- In Service, select the name of the service you added in Add Your Service, micro-service.
- In Deployment Type, select the container orchestration service you want to use. In this guide, we are using Kubernetes.
- In Cloud Provider, click the Cloud Provider you added in Connect Providers, and click Next.
- In Cluster Name, select the GCP Kubernetes cluster to deploy your service. The Service Infrastructure dialog will look something like this:
- Click SUBMIT.
The new environment and service infrastructure is listed.
On to Build Your Workflow.
A workflow is where you define how Harness deploys your service to an environment. Workflows can have multiple services, multiple steps (pre-deployment, deployment, and post-deployment), and notification and failure strategies.
- Click Workflows in the setup drop-down menu.
- Click Add Workflow. The Workflow dialog appears.
Here you will define a deployment type, such as Basic or Canary. Later, you will create a deployment pipeline that contains this workflow. It is a useful to give each workflow a name that describes the purpose of its deployment stage.
- In Name, enter the name build-workflow for this workflow.
- In Workflow Type, select Basic Deployment.
- In Environment, select the environment you created in Set Your Environment.
- In Service, select the service you created in Add Your Service.
- In Service Infrastructure, select the infrastructure you added in Set Your Environment, and click SUBMIT.
The workflow is created.
Below the Workflow Overview, you will see the workflow steps.
There are many different options available for configuring your workflow, but for this guide we’ll simply modify Upgrade Containers in Step 2 and add an email verification as part of Step 3.
Harness displays an alert icon next to Upgrade Containers to indicate that this step needs further configuration.
- Click Upgrade Containers. In the Upgrade Containers dialog you can set how much of your deployment environment you want to use for this stage in the workflow.
- In Desired Instances, enter 33, and leave the drop down as Percent. Click SUBMIT. The alert icon is gone from the Upgrade Containers substep. Next, we’ll configure Harness to send an email verification when the deployment is successful.
- Under Verify Service in Step 3, click the Add Verification drop-down, and scroll down and click Email. The Email dialog appears.
- Use the dialog to send an email to your email address with the message Harness deployment was successful! and click SUBMIT. The Verify Service step shows the new item.
You can see the Rollback Steps, Notification Strategy, Failure Strategy, and Workflow Variables on the right side of the page. We won’t change their defaults in this guide, but you can learn about them in the Harness documentation.
- Expand Rollback Steps to see the steps Harness will perform if deployment is unsuccessful.
We’ll leave these settings alone, but you can see the rollback steps in the order they are performed and change them at any time.
- Click Workflows in the Setup breadcrumbs. Your workflow is displayed as a flowchart.
You can click on any flowchart item to go back into your workflow and change it.
On to Deploy.
Now you can set up a deployment pipeline containing your workflow and run it to deploy your service.
- Click Pipelines in the setup drop-down menu.
- Click Add Pipeline. The Add Pipeline dialog appears.
- Enter the name quick-start-pipeline for the pipeline, and click SUBMIT. The next screen of the dialog appears.
In this screen, you define the first stage the pipeline executes.
- Click Execution Step, and in Step Name, enter the name Build.
- In Execution Workflow, select the workflow you created in Build Your Workflow, build-workflow, and click SUBMIT. The pipeline overview displays.
Your deployment pipeline is shown as a series of stages. You can click on a stage to see its configuration and add a stage by clicking the plus icon.
You are now ready to run your deployment pipeline.
- Click Continuous Deployment in the top nav.
- In Deployments, click Start New Deployment. The Start New Deployment dialog appears.
- Click Deploy by executing a Pipeline.
- In Application, click the name of the application you created in Add Your Service, kube-app.
- In Pipeline, click the name of the pipeline you created above, quick-start-pipeline. The dialog changes to show the Artifacts options.
- Next to the name of your service, micro-service, click the drop-down and select the Docker tag for the artifact you want to deploy. For this guide, choose latest.
- To start your deployment, click SUBMIT. This will automatically deploy the artifact to your cloud provider. Ensure that you have configured the cloud provider with enough capacity, as described in Set Your Environment.
- Watch the deployment run. It will take a few minutes to complete. When it is done you will see:
Here is how the cluster looks in GCP:
- Check your email. You will receive the verification email we configured in Build Your Workflow.
You’re done. In just a few minutes you created a deployment pipeline to deploy your service whenever you want. But you’ve only scratched the surface of Harness. Explore Harness and its documentation to see more of its features.
Now that you've learned the basics, explore some of the advanced features that enable CI/CD, YAML integration, rollbacks, Continuous Verification, and Continuous Security.
- Run your Pipeline Automatically - Create a Trigger to run your pipeline automatically. For more information about triggers, see the Add a Trigger.
- Configuration as Code - View or edit the YAML for your all Harness components and settings. Click Setup, then click Configuration as Code or the code icon </> next to your application
name. The Harness YAML Editor appears. Here is the small editor:
Click any application component or setting in Harness to see its YAML. Edit the YAML and click Save and Harness displays the change in the browser GUI. In the large YAML editor (click Configuration as Code ) you can sync your YAML files with your Github account. For more information, see Configuration as Code.
- Fail a deployment and see a Rollback - You can modify your deployment infrastructure to force a deployment failure and see how Harness rolls back your workflow steps. Modify your deployment GCP cluster so that it only has a single node and run your Harness deployment again. Watch how Harness rolls back changes to their last successful state.
- Set up Continuous Verification - Add verification steps using Splunk, SumoLogic, Elk, AppDynamics, New Relic, DynaTrace, and others to your workflow. For more information, see Continuous Verification.
- Learn about Continuous Security - Read the documentation on Harness’ Continuous Security features such as Secret Management.
- Listen to customer stories - Listen to what Harness customers say about how Harness has reduced their CI/CD costs and time dramatically: Jobvite, Build.com.