Introducing the Harness CLI
We are pleased to announce the public preview launch of the new Harness CLI.
Why a CLI for Harness?
The Harness UI as well as the underlying Harness API have received critical acclaim from customers for their developer-first UX. Additionally, the Harness Terraform Provider has also become extremely popular among experienced Harness users for automating large-scale onboarding of their applications onto Harness. However, all three interfaces create a certain amount of friction when it comes to learning of Harness concepts for users new to the Harness Platform and its multiple modules. Following are some examples:
- Harness API is the foundation of all interfaces including the Harness UI and the Harness Terraform Provider. However, using the API requires writing new code on the client side using the stubs generated from Harness API Reference Docs.
- Harness UI may require navigating through multiple wizards, sometimes spread across developer-centric setup inside a Project and administrator-centric setup inside the Harness Account.
- Finally, the Harness Terraform Provider requires a basic understanding of Terraform (and its providers) which is another tool a new Harness user needs to be already familiar with.
To solve the above new user learning challenge, we are pleased to announce the public preview launch of the new Harness CLI. As the name suggests, it is a command-line interface (CLI) designed for interacting with Harness and it is fully open source under the MIT license. It lowers the barrier to entry and offers a simple and intuitive way for everyone to access their Harness resources. For developers, it offers the best of both worlds, which is developer-friendly automation while also remaining within the developer’s IDE or familiar environment.
Key Features
- Manages the following Harness resources that are necessary for a new user to onboard onto the Harness CD & GitOps module. Coverage for other Harness resources used in other Harness modules is on the roadmap. You can request coverage for these resources as well as other new features through GitHub issues. - Pipeline, Service, Environment, Infrastructure Definition, Connector, Secret, GitOps Application, GitOps Cluster, GitOps Repository.
- Designed with inspiration from popular CLIs in the cloud native ecosystem such as helm and kubectl where input can be via a YAML file with value overrides on the command line. Under the covers, the CLI uses the same Harness API that the Harness UI and Harness Terraform Provider use.
- Support for multiple operating systems: Available for Mac, Linux (both ARM64 and AMD64 architectures), and Windows.
- Open source: The CLI source code is publicly available on GitHub, and we welcome contributions.
- Easy to install and upgrade: A single, lightweight golang-based binary that’s only 11MB in size. Add to your $PATH variable and you are off to the races!
- Full documentation: The CLI has built-in documentation, always available for all commands via a simple --help argument. Additionally, following documentation is also available on the Harness Developer Hub. - Install & configure Harness CLI , Harness CLI Examples, Harness CLI Reference
Get Started with Harness CLI - Video Tutorial
Thanks to Nicholas Lotz, our new Developer Advocate, you can get started here by simply watching a video.
Get Started with Harness CLI - Step-by-Step Tutorial
You can use the CLI for both push-based CD pipeline deployments as well as pull-based GitOps deployments. For this blog post, you will see how to get a GitOps deployment going with the CLI. This tutorial is also available in the Harness Docs.
Prerequisites
Setup your Kubernetes cluster
You should have access to a Kubernetes cluster. For simplicity, this post will use minikube that is running on the same local machine as the Harness CLI (you will download and install later in this tutorial).
minikube start --memory 4g --cpus 4
Create free Harness account
You will need a Harness SaaS account to complete this tutorial. It is free to sign up if you don’t have one already. After signing up, you will get access to the free tiers of many Harness modules including the Harness CD & GitOps module used in this tutorial.
Install Harness GitOps Agent
Harness GitOps Agent is a worker process that runs in your Kubernetes cluster and performs all the GitOps tasks you request in Harness. It makes secure, outbound connections to Harness Platform so that you don’t have to open up ports to the Internet from your Kubernetes cluster.
Download Harness GitOps Agent from your Harness account
First you have to download the agent from the Harness UI. Click on GitOps → Settings → GitOps Agents → New GitOps Agent. Let’s assume you do not have any existing Argo CD instance running in our Kubernetes cluster, so you will choose the NO option to the question “Do you have any existing Argo CD instances?” and click Start. In the next screen, enter mygitopsagent for the agent name and mygitopsns for the agent namespace.
Click Continue and then download the gitops agent helm chart (with Argo CD included) in the form of a tgz file.
Install Harness GitOps Agent on your Kubernetes cluster
Now that you have downloaded the agent, it is time to install it on our Kubernetes cluster which in this case is the local minikube. You will first create the namespace where you will install the agent. And then you will install the agent there using the helm install command.
kubectl create namespace mygitopsagentns
helm install gitops-agent ./gitops-agent.tgz -n mygitopsagentns
You can check the status of the installation using the command below. Notice that your installation also includes an instance of Argo CD since that’s the option you chose during the agent download from Harness UI in the previous step.
kubectl --namespace mygitopsagentns get pods
NAME READY STATUS RESTARTS AGE
argocd-application-controller-0 0/1 ContainerCreating 0 57s
argocd-applicationset-controller-5c89c8c576-wwn9s 0/1 ContainerCreating 0 57s
argocd-redis-6fdfb99d58-c88kf 1/1 Running 0 57s
argocd-repo-server-5b865c755b-5vg4v 0/1 Init:0/2 0 57s
mygitopsagent-agent-58755856dc-22hq2 0/1 ContainerCreating 0 57s
Set the environment variable AGENT_NAME to mygitopsagent so that we can use it during the later steps.
export AGENT_NAME=mygitopsagent
Install Harness CLI on your local machine
Download the CLI as shown below. Make sure to use the binary specific to your operating system.
curl -LO https://github.com/harness/harness-cli/releases/download/v0.0.16-Preview/harness-v0.0.16-Preview-darwin-amd64.tar.gz
tar -xvf harness-v0.0.16-Preview-linux-amd64.tar.gz
sudo mv harness /usr/local/bin
Now login to your Harness account using the CLI using your account id and your API key. Account id is available on every Harness URL as well as your Account Settings page. Create a new personal API key from your User Profile page using these instructions.
harness login --api-key [your-api-key] --account-id [your-account-id]
After successful login, the API key and account id are stored locally on your machine and used by CLI for subsequent operations.
Use Harness CLI to create Harness GitOps resources
Fork https://github.com/harness-community/harnesscd-example-apps into your own GitHub account and then clone it to your local machine.
git clone https://github.com/[your-github-username]/harnesscd-example-apps.git
cd harnesscd-example-apps
Now, you will create the Harness GitOps repository, cluster and application using the sample YAMLs provided for the guestbook app. Before that, you need to make the following edits to the YAMLs.
- Change the repo url in guestbook/harness-gitops/repository.yml and guestbook/harness-gitops/application.yml to https://github.com/<your-github-username>/harnesscd-example-apps
- Change the application.metadata.namespace to mygitopsagentns and application.spec.destination.namespace to mygitopsappns. This will ensure that your application points to the GitOps agent you just installed and is installed in a namespace of its own.
kubectl create namespace mygitopsappns
harness gitops-repository --file guestbook/harness-gitops/repository.yml apply --agent-identifier $AGENT_NAME
harness gitops-cluster --file guestbook/harness-gitops/cluster.yml apply --agent-identifier $AGENT_NAME
harness gitops-application --file guestbook/harness-gitops/application.yml apply --agent-identifier $AGENT_NAME
Perform Manual GitOps Sync via Harness UI
On the Harness UI, go to GitOps → Applications. Click on the gitops-application tile and then click SYNC at the top right to initiate a sync between the state of your GitOps application in Git and the state of your Kubernetes cluster. Since the application did not exist in Kubernetes till now, the application will get deployed now. You can check the status using the command below as well as from the UI.
kubectl --namespace mygitopsappns get pods
NAME READY STATUS RESTARTS AGE
guestbook-ui-5b64f69597-kn4v4 1/1 Running 0 1m13s
guestbook-ui-5b64f69597-v8kfq 1/1 Running 0 1m13s
guestbook-ui-5b64f69597-vnk88 1/1 Running 0 1m13s
Setup Automated Sync for Future Changes
Go to App Details in the gitops-application and scroll down to Sync Options & Policy. Toggle it to turn on Automated sync. Any changes to your Git repo will now be automatically synced to your Kubernetes cluster.
The Road to GA
Using the CLI to simplify Harness CD & GitOps onboarding for new users is just the start. We plan to enhance the CLI to cover all Harness resources that are managed by the Harness API. This will bring the same simple onboarding experience to other Harness modules as well. Meanwhile, your feedback goes a long way in helping us prioritize the most important use cases, especially as we aim to get the CLI to a GA stage over the next few months. You are welcome to file GitHub issues, ask questions on our Community Slack or send in contributions via Pull Requests.