Traditional (SSH) Quickstart
- Before You Begin
- Visual Summary
- Step 1: Install and Launch the Shell Script Delegate
- Step 2: Add the AWS Cloud Provider
- Step 3: Add the Artifactory Artifact Server
- Step 4: Add Target Instance SSH Key to Harness
- Step 5: Create a Harness SSH Service
- Step 6: Add the Artifact Source
- Step 7: Create an Application
- Step 8: Add an Environment to the Application
- Step 9: Define Your Target Servers
- Step 10: Set up a Basic SSH Workflow
- Step 11: Deploy and Review
- Next Steps
This quickstart shows you how to deploy application package files and a runtime environment such as Tomcat to target hosts using Harness.
This deployment is called traditional because it uses SSH (Secure Shell) scripts and a traditional runtime environment as opposed to containers and orchestration mechanisms, such as those in the Kubernetes Quickstart.
You'll learn how to:
- Install and run the Harness Shell Script Delegate on an EC2 host.
- Connect Harness with your AWS account.
- Connect Harness with Artifactory.
- Review the Default Script Commands.
- Specify the target hosts.
- Create and deploy a Harness SSH Basic Workflow.
Before You Begin
- Review Harness Key Concepts to establish a general understanding of Harness.
- Target host — In this guide, we use an AWS EC2 instance as the target host. Minimum t2.medium.
- EC2 Instance for Harness Shell Script Delegate — The EC2 instance for the Harness Delegate must meet the following requirements:
- Linux/UNIX server.
- Minimum 1 CPU.
- Minimum 8GB RAM. For example, an AWS EC2 instance type such as m5a.xlarge has 16GB of RAM, 8 for the Delegate and 8 for the remaining operations.
- Minimum 6GB Disk space.
- Inbound Access: SSH.
- Outbound Access: HTTP and HTTPS. This enables the Delegate to communicate with Harness and Artifactory.
- IAM role: AmazonEC2FullAccess. See Policies Required: AWS EC2.
- If you wish to use an App Stack like Tomcat, then ensure that you have JAVA installed in your target AWS instance.
- Ensure that you have
netcat (nc)installed on your target host. The Harness SSH Service Port Listening command uses
netcat. You can use the following command to do the installation:
yum install -y nc
The following diagram shows the very simple topology for this tutorial:
Step 1: Install and Launch the Shell Script Delegate
First, we'll install the Harness Shell Script Delegate on the EC2 instance you set up. Ensure that the EC2 instance meets the requirements in Before You Begin.
To install the Delegate on your EC2 instance:
- Sign into the Harness Manager.
- Click Setup, and then click Harness Delegates.
- Click Download Delegate, and then click Shell Script.
- Enter a name for the Delegate, and select the Primary Profile.
- Click Copy Download Link.
- Log into your EC2 instance, paste the Shell Script Delegate command, and hit Enter.
- Once the Delegate is downloaded, unzip it (
tar -zxvf harness-delegate.tar.gz), change directories into the harness-delegate folder, and run the start command:
./start.sh. Ignore any warning about the ulimit.
The Delegate will start and in a few moments, you will see it listed on the Harness Delegates page.
Delegate Selectors — As a best practice, add a Delegate Selector to the Delegate so you can quickly identify it.
- In the Delegate listing on the Harness Delegates page, click Custom Selector.
- In Edit Selectors, type in a Selector name such as
ssh-quickstart, press Enter, and then click Submit.
The Selector is added to the Delegate.
Next, we need to add the AWS cloud provider.
Step 2: Add the AWS Cloud Provider
In this section, we will add a Harness AWS Cloud Provider to your Harness account to connect to AWS CodeDeploy, EC2, and S3.
The AWS Cloud Provider will assume the IAM Role associated with the EC2 host running the Delegate you installed in your VPC.
- In the Harness Manager, click Setup, and then click Cloud Providers.
- Click Add Cloud Provider. The Cloud Provider settings appear. Enter the following settings:
- Type: Select Amazon Web Services.
- Display Name: Enter Traditional SSH.
- Credentials: Select Assume IAM Role on Delegate.
- Delegate Selector: Select the Delegate Selector you added to your Delegate, ssh-quickstart.
- Click Test and then Submit.
Step 3: Add the Artifactory Artifact Server
For this tutorial, we'll use a Todo List app artifact, todolist.war, available in a public Harness Artifactory repo.
- In Harness, click Setup, and then click Connectors.
- Click Artifact Servers, and then click Add Artifact Server. Enter the following settings:
- Type: Select Artifactory.
- Display Name: Enter Artifactory Public.
- Artifactory URL: Enter https://harness.jfrog.io/harness.
- Username/Select Encrypted Password: Leave these settings empty.
- Click Test and then Submit. If the test fails, that means the Delegate can't connect to https://harness.jfrog.io/harness. Make sure that the EC2 instance hosting the Delegate can make outbound connections to https://harness.jfrog.io/harness.
Step 4: Add Target Instance SSH Key to Harness
When you set up your target AWS instance, you created an SSH key file for connecting to it.
Harness uses this key to make a connection from the Harness Delegate to the target host during deployment. And so you must add the key to Harness Secrets,
First, you add the key as an Encrypted File Secret in Harness, and then use that file to add an SSH Key secret.
- In Harness, in Security, in Secrets Management, click Encrypted Files.
- Click Add Encrypted File. The Add Encrypted File settings appear.
- Secrets Manager: Use the default setting.
- Name: Enter ssh_quickstart.
- File: Upload your PEM file.
- Click Submit.
Next, use the Encrypted File to create an SSH Key in Harness.
- In Secrets Management, click SSH.
- Click Add SSH Key. The SSH Configuration settings appear.
- Name: Enter ssh_quickstart.
- Auth Scheme: Leave the default.
- User Name: Enter ec2-user (this is the default for AWS EC2 instances)
- Credentials: Select SSH Key File.
- Select Encrypted SSH key Files: Select the Harness Encrypted File you just added.
- Select Encrypted Passphrase: Leave empty.
- SSH Port: Leave the default, 22.
Now you're all set to use this SSH key when you set up the Infrastructure Definition in Harness, later in this quickstart.
Step 5: Create a Harness SSH Service
To create a Service for an application package, do the following:
- In your Application, click Services, and then click Add Service. The Add Service settings appear.
- In Name, enter a name for the Service. You will use this name when selecting this Service in Harness Environments, Workflows, and other components. For more information, see Services.
- In Deployment Type, select Secure Shell (SSH). All file-based Services are Secure Shell (SSH) deployments. The Artifact Type and Application Stack settings appear.
- In Artifact Type, select Web Archive (WAR).
- In Application Stack, select Tomcat. The app stack is used as a runtime environment for your application.Ensure your target hosts have JAVA installed.
Review: Default SSH Script Commands
The Service page has the following important sections:
- Artifact Source - The package files you want to be deployed are added here. In some cases an actual file is obtained, but in most cases metadata is sufficient.
- Artifact History - You can manually pull metadata on your artifacts to see their builds and versions.
- Script - The scripts to set up your files. These will typically include an application stack setup unless your target hosts already have the application stack set up.
- Add Commands - You can add new commands from an Application or Shared Template Library, or simply add a blank command and add Harness scripts to it.
- Configuration - You can add variables and files to use in your Service scripts. These can be encrypted by Harness, allowing you to use secrets. The variables and files can be overwritten in Environments and Workflows.
Step 6: Add the Artifact Source
The Artifact Source for the Service lists the file(s) that you want to be copied to the target host(s). The Artifact History will manually pull artifact build and version metadata from the Artifact Source.
To add an artifact source, do the following:
- In your Service, click Add Artifact Source.
- Select the repo or cloud platform where the artifact is located. The Artifact Source settings appear. This topic uses Artifactory as an example.
- In Display Name, enter a name for the Artifactory Server. This is the name you will use to identify this connection when adding an Artifact Source to a Harness Service.
- In Source Server, select the Artifact Server you added to Harness.
- In Repository, select the repository where the artifact source is located.
- In Artifact Path/File Filter, enter the artifact path in the repository. You can use wildcards such as
Harness uses Metadata Only to download the file on the target host.
Metadata is sufficient as it contains enough information for the target host(s) to obtain or build the artifact. Harness stores the metadata. During runtime, Harness passes the metadata to the target host(s) where it is used to obtain the artifact(s). Ensure that the target host has network connectivity to the Artifact Server. For more information, see Service Types and Artifact Sources.
- Click Submit. The Artifact Source is listed.
Step 7: Create an Application
- Click Setup, and then click Add Application. The Application settings appear.
- Enter the name for your Application, and click Submit. Your new Application appears.
For more information, see Create an Application.
Step 8: Add an Environment to the Application
Add deployment Environments for the Services in your Application. These Environments will be deployed on the cloud providers you added as a connector. To add an Environment, do the following:
- Click Setup and then select the Application that where you want to add the Environment.
- In Application Defaults, click Environments and then click Add Environment. The Add Pipeline settings appear.
- Enter a name and description for the Environment. For example, Traditional SSH.
- In Environment Type, choose Production or Non-Production.
- Click Submit.
Step 9: Define Your Target Servers
As an example, we will create an Infrastructure Definition for an AWS EC2 target infrastructure.
To add an Infrastructure Definition, do the following:
- In your Harness Application Environment, click Add Infrastructure Definition. The Infrastructure Definition settings appear.
- In Name, enter the name you will use when you select this Infrastructure Definition in Workflows.
- In Cloud Provider Type, select the type of Cloud Provider that this Infrastructure Definition will use for connections. For example, select Amazon Web Services for AWS EC2 infrastructures.
- In Deployment Type, select the deployment type for the Services that will use this Infrastructure Definition. In this example, you are deploying SSH type Services like JAR, WAR, etc., you would select Secure Shell (SSH).
- Click Use Already Provisioned Infrastructure. If you were using a Harness Infrastructure Provisioner, you would select Map Dynamically Provisioned Infrastructure.
- In Cloud Provider, select Amazon Web Services: Traditional SSH to connect Harness to your deployment infrastructure.
- Select your AWS Region, for example, US East (N. Virginia). When you select a region, more settings appear, such as VPC and Tags.
- Select Connection Attribute to access the Target Host that uses a Harness SSH Key secret. This key is used by the Harness Delegate to SSH into the target host. See Step 4: Add Target Instance SSH Key to Harness.
- In the Host Name Convention, you can leave the default expression.
Host Name Convention is used to derive the instance(s) hostname. The hostname that results from the convention should be the same as the output of the command hostname on the host itself. For information on obtaining the AWS instance hostname, see Instance Metadata and User Data from AWS.
- Select Use AWS Instance Filter.
- Select the VPC where the AWS instances you want to deploy to is located. Ensure that the Delegate host has connectivity to the VPC.
- In Tags, add the AWS EC2 Tags that are assigned to your target host(s). You can check your hosts in EC2 to get their Tags and ensure that you are using the correct Tags here. For example,
- In Host Connection Type, select Private DNS (default selection).
- When you are finished, click Submit. The Infrastructure Definition is added.
Step 10: Set up a Basic SSH Workflow
Traditional (SSH) deployments involve obtaining an application package from an artifact source, such as a WAR file in an AWS S3 bucket, and deploying it to a target host, such as a virtual machine.
Typically, the Harness Basic Workflow is used for Traditional deployments, but Harness provides Canary and Rolling Workflows for Traditional deployments also.
In this topic, we will use the Basic Workflow to demonstrate a simple Traditional deployment.
Create a Workflow
To create a Basic Workflow for a Traditional deployment, do the following:
- In your Harness Application, click Workflows.
- In Workflows, click Add Workflow. The Workflow dialog appears.
- In Name, enter a name for the Workflow.
- In Workflow Type, select Basic Deployment.
- In Environment, select the Environment where the Infrastructure Definition you defined for your deployment is located.
- In Service, select the SSH Service to be deployed.
- In Infrastructure Definition, select your target infrastructure.
- Click Submit. The Workflow is created.
Let's look at the two default steps in the Workflow, Select Nodes and Install.
Select Target Node
The Select Nodes step selects the target hosts from the Infrastructure Definition you defined. You can choose to select a specific host or simply specify the number of instances to select with the Infrastructure Definition criteria.
The following image shows an Infrastructure Definition specifying an AWS Region, VPC, and Tags (Name:ssh-target), the EC2 instance that meets that criteria, and the host name in the Node Select dialog.
For details, see Select Nodes Workflow Step.
Install and Run the Application and Stacks
The Install step runs the command scripts in your Harness SSH and Service on the target host. See Install Workflow Step.
The Install step is added in the Basic Workflow as part of its Deploy Service section. The Install step is used after the Select Nodes step, which select the target nodes on which to run the Install step.
For details, see Create a Basic Workflow for Traditional (SSH) Deployments.
Step 11: Deploy and Review
The Basic Workflow is the most common deployment of Services deploying application packages. Once you've successfully deployed the Workflow, you can click the Install step to see the Service commands and scripts in the Deployments page.
You can expand logs for each script in the Install step to see the log of its execution by the Harness Delegate. For example, here is the Copy Artifact script copying the application package todolist.war to the runtime location set up in Application Defaults (
Begin execution of command: Copy Artifact
Connecting to ip-172-31-7-227.ec2.internal ....
Connection to ip-172-31-7-227.ec2.internal established
Begin file transfer todolist.war to ip-172-31-7-227.ec2.internal:/home/ec2-user/Traditional SSH/SSH Service Tomcat 8/Traditional SSH/runtime/tomcat/webapps
Metadata only option set for ARTIFACTORY. Starting download of artifact: todolist-tutorial/todolist.war
ARTIFACTORY: Download complete for artifact: todolist.war
File successfully transferred to ip-172-31-7-227.ec2.internal:/home/ec2-user/Traditional SSH/SSH Service Tomcat 8/Traditional SSH/runtime/tomcat/webapps
Command execution finished with status SUCCESS