Azure ACR to AKS CD Quickstart

Updated 1 month ago by Michael Cretzman

Currently, this feature is behind the feature flag NG_Azure. Contact Harness Support to enable the feature.

This quickstart deploys a Docker image in your Azure Container Registry (ACR) repo to your Azure Kubernetes Service (AKS) cluster. Once you've completed this quickstart, you'll be able to easily set up Harness for your own Azure dev, qa, and production deployments.

Objectives

You'll learn how to:

  • Set up an ACR to AKS Kubernetes Pipeline in Harness.
  • Install and launch a Harness Kubernetes Delegate in your target AKS cluster.
  • Connect Harness to your Azure account using a Harness Azure Connector.
  • Run the new Kubernetes Pipeline and deploy a Docker image to your target cluster.

Before You Begin

Review Harness Key Concepts to establish a general understanding of Harness.

Make sure you have the following set up before you begin this quickstart:

  • GitHub account: this quickstart uses publicly available manifests and values YAML files, but GitHub requires that you use a GitHub account for fetching files.
  • Azure ACR and AKS Permissions: make sure you have a Service Principal or Managed Identity you can use to connect Harness to your Azure App registration, and that it has the required permissions:
AKS Cluster

You'll need a target AKS cluster for the deployment. Ensure your cluster meets the following requirements:

  • Number of nodes: 2.
  • vCPUs, Memory, Disk Size: 4vCPUs, 16GB memory, 100GB disk. In AKS, the Standard DS2 v2 machine type is enough for this quickstart.
  • Networking: outbound HTTPS for the Harness connection to app.harness.io, github.com, and hub.docker.com. Allow TCP port 22 for SSH.

Step 1: Create the Deploy Stage

Pipelines are collections of stages. For this quickstart, we'll create a new Pipeline and add a single stage.

Create a Project for your new CD Pipeline: if you don't already have a Harness Project, create a Project for your new CD Pipeline. Ensure that you add the Continuous Delivery module to the Project. See Create Organizations and Projects.

In your Harness Project, click Deployments, and then click Create a Pipeline.

Enter the name Azure Quickstart and click Start.

Your Pipeline appears.

Do the following:

Click Add Stage and select Deploy.

Enter the name Deploy Service, make sure Service is selected, and then click Set Up Stage.

The new stage settings appear.

In About the Service, click New Service.

Give the Service the name quickstart and click Save.

Let's take a moment and review Harness Services and Service Definitions (which are explained below). Harness Services represent your microservices/apps logically. You can add the same Service to as many stages as you need. Service Definitions represent your artifacts, manifests, and variables physically. They are the actual files and variable values.

By separating Services and Service Definitions, you can propagate the same Service across stages while changing the artifacts, manifests, and variables with each stage.

Once you have created a Service, it is persistent and can be used throughout the stages of this or any other Pipeline in the Project.

Step 2: Add the Manifest and Values YAML

Next, we can add a Kubernetes manifest for our deployment. We'll use publicly-available manifests and a values file available from Harness.

In Service Definition, in Deployment Type, click Kubernetes.

In Manifests, click Add Manifest.

Select K8s Manifest, and click Continue.

In Select K8sManifest Store, click GitHub, and then click New GitHub Connector.

The Git Connector settings appear. Enter the following settings.

Name: enter a name for the Connector, like Quickstart.

URL Type: select Repository.

Connection Type: select HTTP.

Git Repository URL: enter https://github.com/wings-software/harness-docs.git.

Username and Token:

Enter the username and a Github Personal Access Token for your Github account. You'll have to create a Harness secret for the password.

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

Click New Secret Text.

In Secret Name, enter a name for the secret like 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 Continue.

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

Now we'll add a Harness Delegate to your Environment.

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.

In Delegates Setup, click Install new Delegate.

The Delegate wizard appears.

Click Kubernetes, and then click Continue.

Enter a name for the Delegate, like quickstart, click the Small size.

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.

You will connect to your cluster using the terminal so you can simply run the YAML file on the cluster.

In the same terminal, log into your Kubernetes cluster. In most platforms, you select the cluster, click Connect, and copy the access command.

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

You can find this command in the Delegate wizard:

The successful output is something like this:

% kubectl apply -f harness-delegate.yaml
namespace/harness-delegate unchanged
clusterrolebinding.rbac.authorization.k8s.io/harness-delegate-cluster-admin unchanged
secret/k8s-quickstart-proxy unchanged
statefulset.apps/k8s-quickstart-sngxpn created
service/delegate-service unchanged

In Harness, click Verify. It will take a few minutes to verify the Delegate. Once it is verified, close the wizard.

Back in Set Up Delegates, you can select the new Delegate.

In the list of Delegates, you can see your new Delegate and its tags.

Select the Connect using Delegates with the following Tags option.

Enter the tag of the new Delegate and click Save and Continue.

In Connection Test, you can see that the connection is successful. Click Finish.

Back in Specify K8s Manifest Store, click Continue.

In Manifest Details, enter the following settings, test the connection, and click Submit.

We are going to provide connection and path information for a manifest located at https://github.com/wings-software/harness-docs/tree/main/default-k8s-manifests/Manifests/Files/templates.

Manifest Identifier: enter manifests.

Git Fetch Type: select Latest from Branch.

Branch: enter main.

File/Folder path:

default-k8s-manifests/Manifests/Files/templates

This is the path from the repo root.

The manifest is now listed.

Next, let's add the values.yaml file for the deployment.

Harness supports Go templating with a Values YAML file by default so you can template your manifests. Also, you can use Harness expressions in your values.yaml file. We will use a values.yaml file that uses the <+artifact.image> expression to reference the artifact you will add later in Artifacts.
The values file looks like this:
name: harness-quickstart
replicas: 1

image: <+artifact.image>
dockercfg: <+artifact.imagePullSecret>

createNamespace: true
namespace: <+infra.namespace>

# Service Type allow you to specify what kind of service you want.
# Possible values for ServiceType are:
# ClusterIP | NodePort | LoadBalancer | ExternalName
serviceType: LoadBalancer

# A Service can map an incoming port to any targetPort.
# targetPort is where application is listening on inside the container.
servicePort: 80
serviceTargetPort: 80

# Specify all environment variables to be added to the container.
# The following two maps, config and secrets, are put into a ConfigMap
# and a Secret, respectively.
# Both are added to the container environment in podSpec as envFrom source.
env:
config:
key1: value1
secrets:
key2: value2

Click Add Manifest.

In Specify Manifest Type, select Values YAML, and click Continue.

In Specify Values YAML Store, select the same GitHub Connector you used for your manifests, and then click Continue.

In Manifest Details, enter the following and click Submit.

Manifest Identifier: values.

Git Fetch Type: Latest from Branch.

Branch: main.

File Path: default-k8s-manifests/Manifests/Files/ng_values_dockercfg.yaml

The values file is listed.

Next, let's add your artifact from ACR.

Step 3: Add the Artifact

Now you can add an artifact from your ACR repo. We'll create a Harness Azure Connector to connect Harness with your ACR repo.

In Artifacts, click Add Primary Artifact.

In Artifact Repository Type, click ACR, and then click Continue.

In ACR Repository, click New Azure Connector.

Enter a name for the Connector, such as Azure Quickstart, and click Continue.

In Details, click Specify credentials here.

Enter the credentials for the Azure App registration you want to use. Here's an example of how App registration settings map to the Connector's Details:

Azure ACR and AKS Permissions: make sure the Service Principal or Managed Identity has the required permissions:

Click Continue.

In Delegates Setup, click Only use Delegates with all of the following tags, and then select the Delegate you added earlier.

Click Save and Continue.

The Connection Test is performed. Once it's completed, you'll be back in ACR Repository. Click Continue.

In Artifact Details, select the Subscription Id where the artifact source is located.

In Registry, select the ACR registry to use.

In Repository, select the repo to use.

In Tag, enter or select the tag for the image.

Here's an example of how ACR settings map to Artifact Details:

Click Submit. The Artifact is added to the Service Definition.

Now that the artifact and manifest are defined, you can define the target cluster for your deployment.

Click Next at the bottom of the Service tab.

Step 4: Define Your Target Cluster

The target cluster is your own AKS cluster, hosted in your Azure cloud. This is where we will deploy your ACR image using the manifest you selected.

In Infrastructure Details, in Specify your environment, click New Environment. Just like with a Service, you can create a new Environment or selecting an existing one. We'll create a new one.

In New Environment, enter a name, select Pre-Production, and click Save. The new Environment appears.

In Infrastructure Definition, click Microsoft Azure.

Let's take a moment and review Harness Environments and Infrastructure Definitions. Harness Environments represent your deployment targets logically (QA, Prod, etc). You can add the same Environment to as many stages as you need. Infrastructure Definitions represent your target infrastructure physically. They are the actual clusters, hosts, etc.

By separating Environments and Infrastructure Definitions, you can use the same Environment in multiple stages while changing the target infrastructure settings with each stage.

An Infrastructure Definition is where you specify the target for your deployment. In this case, your Kubernetes cluster and namespace.

In Cluster details, enter the following.

In Connector, click Select a connector.

Select the Azure Connector you added earlier, and then click Apply Selected.

In Subscription Id, select the Subscription where you AKS cluster is located.

In Resource Group, enter the resource group for your AKS cluster.

In Cluster, select the cluster name.

In Namespace, enter an existing namespace, such as default.

Now that the Stage's Infrastructure is complete, you can select the deployment strategy for this stage of the Pipeline.

Step 5: Add a Rollout Deployment Step

Click Continue.

In Execution Strategies, select Rolling, and then click Use Strategy.

The Rollout Deployment step is added.

This is a standard Kubernetes rolling update. By default, Harness uses a 25% max unavailable, 25% max surge strategy.

That's it. Now the Pipeline stage is complete and you can deploy.

Step 6: Deploy and Review

Click Save > Save Pipeline and then Run.

Click Run Pipeline. Harness will verify the Pipeline and then run it.

You can see the status of the deployment, and pause or abort it.

Toggle Console View to watch the deployment with more detailed logging.

Click the Rollout Deployment step and expand Wait for Steady State.

You can see deployment "[name]" successfully rolled out.

Congratulations! The deployment was successful.

Clean Up

To delete the Harness Delegate from your Kubernetes cluster, you delete the StatefulSet for the Delegate. Once created, the StatefulSet ensures that the desired number of pods are running and available at all times. Deleting the pod without deleting the StatefulSet will result in the pod being recreated.

For example, if you have the Delegate pod name quickstart-vutpmk-0, you can delete the StatefulSet with the following command:

$ kubectl delete statefulset -n harness-delegate quickstart-vutpmk

Note that the -0 suffix in the pod name is removed for the StatefulSet name.

Next Steps

See Kubernetes How-tos for other deployment features.


Please Provide Feedback