Custom deployments using Deployment Templates
In some cases, you might be using a platform that does not have first-class support in Harness, such as OpenStack, WebLogic, WebSphere, etc. We call these non-native deployments.
For non-native deployments, Harness provides a custom deployment option using Deployment Templates.
Deployment Templates use shell scripts to connect to target platforms, obtain target host information, and execute deployment steps.
This tutorial will walk you through very simple Deployment Templates using Kubernetes. Harness includes first-class Kubernetes support (see Kubernetes deployment tutorial), but we will use it in this tutorial as it is a very simple way to review Deployment Templates features.
Objectives
You'll learn how to:
- Install and register a Harness Delegate for Deployment Templates use cases.
- Create the Deployment Template.
- Add a script to fetch a JSON array containing target instance information.
- Create the Deployment Template Pipeline.
- Add your Docker image to Harness.
- Define the Pipeline Service, Infrastructure, and Execution.
- Run and verify the deployment.
The tutorial should only take about 15 minutes.
Custom deployment using Deployment Templates summary
Here is a summary of the steps for setting up custom deployments using Deployment Templates:
- Create a Deployment Template.
- In the template, include a script that returns a JSON array containing a list of the target instances where Harness will deploy your artifact.
- Identify the array path to the host object in the JSON so Harness can locate these at deployment runtime.
- Map any important host attributes that you want to reference later, like IP, region, etc.
- Create a Harness Pipeline stage using the Deployment Template type and the Deployment Template.
- In your Harness Pipeline stage Service, create a Harness Service that uses the Deployment Template. Add the artifact you want to deploy.
- In your Harness Pipeline stage Environment, create a Harness Infrastructure Definition that uses the Deployment Template.
- In your Harness Pipeline stage Execution, review the automatically added Fetch Instances step, and move it to wherever you want to execute the script from your Deployment Template.
- Add a deployment step to Execution to deploy your artifact to the instances retrieved using the Fetch Instances step.
That's it. Your Pipeline will fetch the target instances as you requested and deploy your artifact to them.
Important notes
Unlike the deployments for supported platforms, like Kubernetes and AWS, Deployment Templates have certain limitations:
- All artifact providers and Custom artifact are supported:
Type | Nexus3 | Artifactory | Jenkins | Amazon S3 | Docker Registry | AWS ECR | GCR | ACR | Google Artifact Registry | Custom | GCS | Bamboo | AMI | Azure Artifacts |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Docker | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | |||||
Other (ZIP, Jobs, etc.) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
- No steady state checks on deployed services.
- Harness does not track releases.
You can add your own scripts or tests to your Pipelines to describe deployments, check steady state, and track releases. For example, using the Shell Script or HTTP steps.
Harness Delegate setup
- Install a Harness Kubernetes Delegate in a cluster. For steps on installing a Delegate, go to Install a delegate.
The Delegate you use for Deployment Templates should be in an environment where it can connect and query your artifact repo and target instances. Typically, you'll want a Delegate in the same subnet as the target instances.
If your scripts will use utilities or software that does not come with the Delegate by default, you can install them on the Delegate manually or using the Delegate INIT_SCRIPT
environment variable.
For steps on using INIT_SCRIPT
, see Build custom delegate images with third-party tools.
Harness Delegate installation packages include TAR
and cURL
. You can use cURL
and TAR
in your Delegate scripts and Pipeline steps without installing these tools.
Harness Delegate installation packages also include standard tools and SDKs for the main platform integrations Harness uses, such as Kubernetes, Helm, AWS, Azure, GCP. You do not need to install their CLI tools on the Delegate.
Once the Delegate is installed and registers with your Harness account, you will see it listed on the Delegates page.
-
Note the default tag added to the Delegate. You will use this to select this Delegate in future steps.
Create custom Deployment Template
You can create a Deployment Template at the Account, Org, or Project level. For this tutorial, we'll use the Project level.
- In your Harness Project, click Project Setup.
- Click Templates.
- Click New Template.
- Select Deployment.
- In Create New Deployment Template, in Name, enter DT.
- In Version Label, enter v1.In Logo, you can upload an image to use as the icon for this template.
- Click Start.
The Deployment Template is composed of two major sections:
-
Infrastructure:
- Variables: variables that can be used when the script is run.
- Fetch Instances Script: script needed to fetch a JSON array of the target instances. The script can be entered here or you can use the [Harness File Store](../x-platform-cd-features/services/add-inline-manifests-using-file-store.mdo share scripts with others.
- Instance Object Array Path: the JSON path to the label that lists the array of instances, such as
items
. - Instance Attributes: the JSON path to the instance name label for the target instances.Mapping the fieldname
instancename
to the JSON Path is mandatory.You can add more instance attributes for additional target instance values you want to use.
-
Execution:
- Any steps that you want to use in the stage and associate with this template. If you create these in the Deployment Template, they are automatically created as separate Step Templates.
- Your stage is not limited to using these steps. You can add any steps you want to your stage.
For this tutorial, we'll only use some of these settings, but the rest of the settings are described in Notes.
Add the Fetch Instance Script
In Fetch Instance Script, you enter the script to pull the JSON collection of target instances from a server or service.
The script is expected to query the server and receive a JSON array containing the target hosts, saved in the file $INSTANCE_OUTPUT_PATH
.
This shell script will be executed at runtime by the Harness Delegate on its host. This should be a shell script you have run on the Delegate host to ensure that the host can connect to your server(s).
The script should return a JSON array containing the target host information Harness needs to deploy.
The script you use depends on the platform you're using.
For this tutorial, we want to deploy to all the Kubernetes pods in the namespace example, so our script looks like this:
/opt/harness-delegate/client-tools/kubectl/v1.19.2/kubectl get pods --namespace=harness-delegate-ng -o json > $INSTANCE_OUTPUT_PATH
If you want, you can replace the namespace harness-delegate-ng
with a namespace in your own cluster that has pods that can be fetched.
Important: The $INSTANCE_OUTPUT_PATH
expression must come last. You can enter the script inline, or use the Harness File Store to store it in a file.
This script returns a JSON array of pods in the namespace, similar to this:
{
"apiVersion": "v1",
"items": [
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"creationTimestamp": "2022-09-28T20:13:50Z",
"generateName": "example-deployment-69877c747f-",
"labels": {
"pod-template-hash": "69877c747f"
},
"name": "example-deployment-69877c747f-gllvt",
"namespace": "harness-delegate-ng",
...
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"creationTimestamp": "2022-09-28T20:13:50Z",
"generateName": "example-deployment-69877c747f-",
"labels": {
"pod-template-hash": "69877c747f"
},
"name": "example-deployment-69877c747f-gpkkk",
"namespace": "harness-delegate-ng",
...
}
This example uses Kubernetes. Harness already has full, first-class support for Kubernetes deployments. We just use this script as an example.
For the main Kubernetes support, go to Kubernetes deployment tutorial.
Next, you need to provide the JSON path to the JSON array object for the target hosts.
Important notes on the Fetch Instances script
- The script must return an array of target instances (virtual machine, pod. etc.). If the template is to be used for executing a trigger to an external orchestrator (for example, Ansible, Puppet, etc.), the script should query the orchestrator to return the total instances running inside. If the script simply returns the application name, Harness cannot track the actual SI count.
- If a service is scaling up/down post-deployemnt, the Fetch Instances script should be written in that way that it should always return the current state of the system. This script is run periodically post-deployment as part of a perpetual task.
Define the Instance Object Array Path
- In Instance Object Array Path, you enter the JSON path to the JSON array object. In our example above, you can see that the array is under
items
. - In Instance Object Array Path, you simply enter
items
. Harness will use this path to traverse the JSON array.
Define Instance Attributes
Now that you have provided a path to the instances array, you can map any useful JSON keys in Instance Attributes.
Important The instancename
value in the Field Name setting is mandatory.
You must use instancename
to identify the target host(s) in the JSON array.
For our Kubernetes example, we will use:
- Field Name:
instancename
. - JSON Path:
metadata.name
.
You can map any additional attributes containing information you want to reference in your Execution, most likely in a Shell Script step. See Referencing fetched instances using expressions.
Add Execution steps
- Now that the Deployment Template Infrastructure is complete, click Continue to view Execution.
You can create or select step templates in Execution.
You don't have to use any of these steps in your stage. Execution is simply a way of associating steps with Deployment Templates.
We'll create a Shell Script step template to deploy our Docker image artifact to the instances we fetch using the script we added in Fetch Instance Script.
- In Deployment Steps, click Add Step, and click Create and Use Template.
- In Step Library, click Shell Script.
- In Name, enter deploy.
- In Script, enter the following:
/opt/harness-delegate/client-tools/kubectl/v1.19.2/kubectl apply -f deployment.yaml
- Click Save.
- In Save as new Template, in Name, enter deploy.
- In Version Label, enter v1.
- Click Save. The step template is added to the Deployment Template.
- Click Save to save the Deployment Template. If you haven't already, name the Deployment Template DT.
Create the Pipeline
Now we'll create a Harness Pipeline that will use the Deployment Template.
- Click Pipelines.
- Click Create a Pipeline.
- In Create new Pipeline, enter the name DT Tutorial, and click Start.
- Click Add Stage.
- Click Deploy, and enter the name DT Tutorial.
- In Deployment Templates, click the Deployment Template you created, DT, and then click Use Template.
- Click Set Up Stage.
The stage is created and you are on the Service tab.
Next we'll define the Harness Service using the Deployment Template you created and a Docker artifact for deployment.
If you are new to Harness, learn about the basics in CD overview and key concepts and CD Pipeline modeling overview.