Variables and Expressions in Harness

Updated 1 week ago by Michael Cretzman

You can use variables to obtain and set many values in Harness. For example, you can create a variable in a Harness account and later in a dialog field, you can reference the variable:

Harness includes two types of variables you can use:

  • Harness built-in variables: There are variables scoped to different entities, such as applications, services, environments, workflows, and variables that provide information about deployment environments.
  • User-created variables: You can create variables at the account-level and application-level that can be used across your Harness applications, and create variables in application entities to be replaced by users when configuring or deploying a CD pipeline.

For information on passing variables from a Trigger to a Workflow, see Passing Variables into Workflows from Triggers.

To use a variable, you enter a the variable name inside ${...}. For example, to obtain the name of a Harness application, you would use ${app.name}.

Harness only permits variables within their scope. You will not see a variable available in a field where it cannot be used.

Variables can be used in expressions. For example, here is an expression using the variable, ${instance.hostName}:

${instance.hostName.split('\.')[0]}

A split method with the argument ('\.') is called and the result is a Java array, returning the first item, [0].

Harness uses the Java Expression Language (JEXL) expression language to render variables.

For more information, see Expressions.

Avoid using hyphens (dashes) in variable names as some Linux distributions and deployment-related software do not allow them.

Variables List

The following table lists the default, built-in Harness variables, as well as the prefixes used to identify user-created variables. This list will be updated periodically, when new variables are added to Harness.

Entities

Variables

Description

Application

${app.name}

Harness application name.

${app.description}

Harness application description.

Service

${service.name}

Harness service name.

${service.description}

Harness service description.

Service Variables

${serviceVariable.var_name}

References any variable created in a service in the current application. For example, you could add a Shell Script command to a workflow that referenced the variable ${serviceVariable.var_name}, created in a service used by the workflow.

Environment

${env.name}

Harness environment name.

${env.description}

Harness environment description.

${serviceVariable.override_var_name}

References service configuration overrides at the environment level.

Infrastructure

${infra.kubernetes.namespace}

The namespace for the Kubernetes cluster where the microservice/app is deployed.

${infra.route}

A route where the microservice/app is deployed. In a Blue/Green deployment, this is the Green, or production, address.

${infra.tempRoute}

A temporary route where the microservice/app is deployed. In a Blue/Green deployment, this is the Blue, or old, address.

${infra.pcf.route}

A Pivotal Cloud Foundry route where the microservice/app is deployed. In a Blue/Green deployment, this is the Green, or production, address. You set this route as part of the Environment of a PCF deployment.

For more information, see Pivotal Cloud Foundry Deployment.

${infra.pcf.tempRoute}

A Pivotal Cloud Foundry temporary route where the microservice/app is deployed. In a Blue/Green deployment, this is the Blue, or old, address. You set this route as part of the Environment of a PCF deployment.

${infra.helm.releaseName}

Helm release name. The variable is populated after the Helm Deploy workflow step is done. Data for the variable is available during Helm deployment only.

${infra.helm.shortId}

Helm requires the Helm release name to be unique across the cluster, set in a workflow Deploy Helm step. ${infra.helm.shortId} is a Harness-generated unique identifier used as a prefix/suffix to the release name. It contains the first 7 characters of the Infrastructure mapping ID used during the Helm deployment.

Recommended release name: ${service.name}-${env.name}-${infra.helm.shortId}

Data for the variable is available during Helm deployment only.

Workflow

${workflow.displayName}

Workflow name.

${workflow.description}

Workflow description.

${workflow.releaseNo}

The count of deployments for this workflow.

${workflow.lastGoodReleaseNo}

The count of the last successful deployment of this workflow.

${workflow.lastGoodDeploymentDisplayName}

The display name of the last successful deployment of this workflow.

${workflow.pipelineDeploymentUuid}

The unique ID for the execution of the pipeline deploying this workflow.

${workflow.variables.var_name}

References to variables created in a workflow.

${context.published_name.var_name}

The published output variable name created by a Shell Script command. For more information, see Using Shell Script Commands.

Trigger

${deploymentTriggeredBy}

Name of the Harness user that triggered the execution of the workflow or pipeline deployment.

Artifact

${artifact.displayName}

Display name of an artifact used by a service.

${artifact.description}

Description of artifact.

${artifact.buildNo}

Build number of the artifact. It is Job Number for Jenkins, Tag Name for Docker, Artifact File name for Artifactory, and Version number for Nexus.

${artifact.revision}

Artifact revision is available only if artifact source is setup with build servers like Jenkins, Bamboo etc. Artifact source like Nexus, Artifactory would not have the revision details.

ARTIFACT_FILE_NAME

The file name of the artifact attached to a service.

${artifact.metadata.image}

Available for Docker images Artifact Sources in Services. For example, if you used a publicly-available Docker Hub NGINX image as the Artifact Source for a Service, when the Service is deployed, the variable output would be registry.hub.docker.com/library/nginx:stable-perl at runtime.

${artifact.metadata.tag}

Access tags associated with an artifact, such as AMI tags. For example, if an AMI used the tag harness, use ${artifact.metadata.harness}.

${artifact.source.dockerconfig}

Base64 representation of your Docker credentials. See Inspecting the Secret regcred from Kubernetes.

${artifact.bucketName}

Name of the bucket on the artifact server where the artifact is located. For example, an S3 bucket.

${artifact.key}

The unique key that is used to identify the artifact in the artifact source, such as in AWS S3.

${artifact.url}

The URL to download the artifact from the artifact server.

${artifact.buildFullDisplayName}

The full name of the artifact file.

${artifact.artifactPath}

The path to the location of the artifact on the artifact server.

${artifact.source.username}

The artifact source user name key.

${artifact.source.registryUrl}

The artifact source registry URL key.

${artifact.source.repositoryName}

The artifact source repository name key.

Instance

${instance.name}

The name of the instance on which the service is deployed.

${instance.hostName}

The host/container/pod name where the service is deployed.

${instance.dockerId}

The container ID where the service is deployed.

${instance.host.publicDns}

The public DNS domain name of the host where the service us deployed. In environments like AWS, the public DNS name can be different from the host name.

Host (Deprecated)

${host.name}

The name of the host/container/pod where the service is deployed. In the JSON for the deployment environment, this will be the label hierarchy of the name label of the host/container/pod, such as host:name.

(Deprecated)

${host.hostName}

The name of the host/container/pod where the service is deployed. The host/container/pod might be located by ${host.name} or ${host.hostName}, depending on the JSON label that identifies the host.

(Deprecated)

${host.ip}

The public IP address used to locate the host in the deployment environment.

(Deprecated)

${host.publicDns}

In environments like AWS public DNS name can be different from the host name.

(Deprecated)

${host.ec2Instance.instanceId}

The AWS EC2 instance ID.

AWS EC2 Instance model attributes can be accessed over SSH or using AWSCodeDeploy in the AWS environment.

Additional attributes can be accessed as documented at com.amazonaws.services.ec2.model.Instance from Amazon.

(Deprecated)

${host.ec2Instance.instanceType}

The AWS EC2 instance type.

(Deprecated)

${host.ec2Instance.imageId}

The AWS EC2 instance image ID.

(Deprecated)

${host.ec2Instance.architecture}

The AWS EC2 instance architecture (for example, AMD64).

(Deprecated)

${host.ec2Instance.kernelId}

The AWS EC2 instance kernel ID (for example, aki-004ec330).

(Deprecated)

${host.ec2Instance.keyName}

The AWS EC2 instance key pair name.

(Deprecated)

${host.ec2Instance.privateDnsName}

The AWS EC2 instance private DNS FQDN.

(Deprecated)

${host.ec2Instance.privateIpAddress}

The AWS EC2 instance private IP address.

(Deprecated)

${host.ec2Instance.publicDnsName}

The AWS EC2 instance public DNS FQDN.

(Deprecated)

${host.ec2Instance.publicIpAddress}

The AWS EC2 instance public IP address.

(Deprecated)

${host.ec2Instance.subnetId}

The AWS EC2 instance subnet ID (for example, subnet-1122aabb).

(Deprecated)

${host.ec2Instance.vpcId}

The AWS EC2 instance VPC ID (for example, vpc-1a2b3c4d).

HTTP

${httpUrl}

URL of the server where Harness is deploying the service.

${httpRespondeMethod}

HTTP response method (for example, GET, POST, PUT).

${httpResponseCode}

HTTP response code returned by the server (for example, 200, 404).

${httpResponseBody}

HTTP message excluding headers. An example use might be ${httpResponseBody}.contains("hello").

${assertionStatement}

HTTP assertion statement. For example, ${assertionStatement}=${httpResponseCode}==200.

${assertionStatus}

Status of assertion (for example, true, false).

Approval

${approvedBy.name}

The name of the Harness user that approved a workflow approval step.

Just like other states, the approval timestamp can be fetched using ${endTs} variable.

${approvedBy.email}

The email address of the Harness user that approved a workflow approval step.

Email

${toAddress}

The email address to send an email as part of an Email step in a workflow.

${ccAddress}

The email address to CC as part of an Email step in a workflow.

${subject}

The email address subject as part of an Email step in a workflow.

${body}

The email address body as part of an Email step in a workflow.

AWS

${ami.newAsgName}

To obtain the name of the Auto Scaling Group created by Harness, use the Harness variable ${ami.newAsgName}. For example, you could add a Shell Script command to your Workflow that contains the command echo ${ami.newAsgName}.

Terraform

${terraform.outputName}

When you map a Terraform script output to a Harness field as part of a Service Mapping, the variable for the output can be used anywhere in the Workflow that uses that Terraform Provisioner.

For more information, see Terraform Provisioner.

CloudFormation

${cloudformation.outputName}

When you map a CloudFormation template output to a Harness field as part of a Service Mapping, the variable for the output can be used anywhere in the Workflow that uses that CloudFormation Provisioner.

For more information, see CloudFormation Provisioner.

Kubernetes

${k8s.primaryServiceName}

${k8s.stageServiceName}

${k8s.canaryWorkload}

${k8s.virtualServiceName}

${k8s.canaryDestination}

${k8s.stableDestination}

Kubernetes Workflows uses various expressions to represent Kubernetes services, Blue/Green and Canary deployment values, and Istio traffic splitting. For more information, see Workflow Variable Expressions.

Constants

The following constants define the paths used at runtime, backup, and staging of deployments.

Constant

Description

$WINGS_RUNTIME_PATH

The runtime path for a Harness application:

$HOME/${app.name}/${service.name}/${env.name}/runtime

$WINGS_BACKUP_PATH

The backup path for a Harness application:

$HOME/${app.name}/${service.name}/${env.name}/backup/${timestampId}

$WINGS_STAGING_PATH

The staging path for a Harness application:

$HOME/${app.name}/${service.name}/${env.name}/staging/${timestampId}

Naming and Availability

The variables used in Harness follow a naming convention that describes where they can be used. When you select a variable, it helps to understand the naming convention, as there might be numerous variables from which to choose.

For example, an account-level variable created in Account Defaults begins with the namespace account.defaults followed by the variable name. The reference for an Account Defaults variable named productName is ${account.defaults.productName}.

Whenever you have a Harness field that permits variables, begin by typing ${ and the variables available to that entity are displayed.

The following table lists the naming convention for the different variable namespaces.

Entity

Prefix Namespace

Examples

Account Defaults

account.defaults

${account.defaults.productName}

Application Defaults

app.defaults

${app.defaults.MyApp}

application

app

${app.name}

artifact

artifact

${artifact.displayName}

service

service

${service.name}, ${serviceVariable.variable_name}

environment

env

${env.description}

workflow

workflow

${workflow.lastGoodDeploymentDisplayName}

infrastructure

infra

${infra.route}, ${infra.kubernetes.namespace}, ${infra.pcf.route}

instance

instance

${instance.hostName}

approval

approvedBy

${approvedBy.email}

email

NA

${toAddress}, ${ccAddress}, ${subject}, ${body}

Pivotal Cloud Foundry

pcf

${infra.pcf.route}

Kubernetes

kubernetes

${infra.kubernetes.namespace}

Account Default Variables

You can define account-wide variables that can be referenced by any application and entity in your account.

Account Defaults are account-level variables available to all users logged into the account. To manage Account Defaults, you must be logged into Harness as a member of a group that has Manage Account permissions, such as the default Account Administrator group.

To create an account default variable, do the following:

  1. Log into Harness, and then click Setup.
  2. Click the ellipsis next to Account, and then click Account Defaults.
  3. Click Add Row. A new row appears.
  4. In Name, enter a name for the variable. Ensure that the name is descriptive as users will be looking at a list of variable names and will need to distinguish between them.
  5. In Type, select STRING.
  6. In Value, enter the value for the variable. For example, if you added an Account Default variable for productName, the dialog would look like this:
  7. Click SUBMIT. The new variable is added. Now, let's reference the variable.
  8. Open a Harness application, and then open a service, such as Docker or Pivotal Cloud Foundry (PCF) service within the application.
  9. In the service, under Configuration, click Add Variable. The Config Variable dialog appears.
  10. In Value, enter ${account.defaults} to see the account variables displayed.
  11. Click the account variable name to enter it. It is entered as ${account.defaults.variable_name}.

Application Default Variables

When you create an application in Harness, you can define application-wide variables that can be referenced in any entity within an application. For example, you might want to create an application-wide variable for an approval.

Application Defaults are application-level variables available to all users with the required permissions to that application. To create Application Defaults, you must be logged into Harness as a member of a group that has create or update permissions for that application.

To add/edit Application Default variables, you must be a member of a User Group with the Administer Other Account Functions setting enabled. For more information, see Managing Users and Groups (RBAC).

To create an application default variable, do the following:

  1. In Harness, open a Harness application.
  2. Click Application Defaults.
    The Application Defaults dialog appears, displaying several built-in variables.
  3. To add a new variable, click Add Row. A new row appears.
  4. In Name, enter a name for the variable. Ensure that the name is descriptive as users will be looking at a list of variable names and will need to distinguish between them.
  5. In Type, select STRING.
  6. In Value, enter the value for the variable.

    For example, if you added an Application Default variable for a product name, the dialog would look like this:
  7. Click SUBMIT. The new variable is added. Now, let's reference the variable.
  8. Open a Harness application, and then open a service, such as Docker or Pivotal Cloud Foundry (PCF) service within the application.
  9. In the service, under Configuration, click Add Variable. The Config Variable dialog appears.
  10. In Value, enter ${app.defaults to see the application variables displayed.
  11. All Application Defaults variables begin with app.defaults to identify the namespace of the variable.
  12. Click the application variable name to enter it. It is entered as ${app.defaults.variable_name}.

Secrets and Variables

You can create encrypted text items in Harness Secrets Management and reference that the text using variables. For information on creating and managing secrets, see Secrets Management.

For example, you can add a username as an encrypted text item, named Username, and then reference it using the variable ${secrets.getValue("Username")}.

The ${secrets.getValue("var_name")} is available only if the secret it references is made Account-level, by deleting all of the Applications in its Usage Scope.

For an extended example, see Using Secrets in a Profile.

Config Files

Files added in the Config Files section of a Service are referenced using the configFile.getAsString("fileName") Harness expression:

  • configFile.getAsString("fileName") - Unencrypted text file.
  • configFile.getAsBase64("fileName") - Encrypted text file.

For more information, see Config Files.

Expressions

Anywhere that variables are allowed in Harness, expressions using the variable are also allowed. Expressions follow Java expressions, Java regex pattern format, and operators may be used in building expressions.

For example, here is an expression using the variable, ${artifact.source.repositoryName}:

${artifact.source.repositoryName.split('\.')[0]}

A split method with the argument ('\.') is called and the result is a Java array, returning the first item, [0].

Functors

Harness provides functors to enable you to map over a set of values. Harness provides a Regex and an AWS functor.

Regex Functor

The Regex Functor allows you to operate over variables using regular expressions.

For example, the following argument is a regular expression in Java regex format that extracts the first matching non-empty substring:

${regex.extract("[0-9]*", "build-webservices-3935-0.noarch.rpm")}

It resolves to "3935". If there was no matching substring, it would resolve as an empty string.

The next argument uses operators to extract the substring and its iteration number:

${regex.extract("[0-9]+-[0-9]+", "build-webservices-3935-0.noarch.rpm")}

It resolves to "3935-0".

AWS Functor

The AWS functor allows you to operate over complex objects returned from the AWS API.

For example, the following arguments use AWS Tags to find a tag with a particular key. In this example, the tags collection is:

{“Name”, “main-service”; “Environment”, “Green”}

The first argument resolves to an empty string because find() is case sensitive and the tag name is "Name":

${aws.tags.find(host.ec2Instance.tags, 'name')}

The next argument finds the tag Name and resolves to ”main-service”:

${aws.tags.find(host.ec2Instance.tags, 'Name')}

The last argument finds the key Green:

${aws.tags.find(host.ec2Instance.tags, Environment)}
Java StrSubstitutor

Harness also supports the Java StrSubstitutor class for taking a piece of text and substituting all the variables within it. This can useful because it includes many static convenience methods for replacing variables.

View Output in Deployments

The Deployments page in Harness Manager displays the output of any of the Harness built-in variables or third-party API calls you use in its Execution Context panel.

View Variable Output

Here is an example of the Harness variables in a Shell Script command in a Kubernetes Workflow:

Here is the output of these variables displayed in the Execution Context panel:

View 3rd Party API Calls

To see the output from third-party API calls, you select a Verification Provider node, and then click View 3rd Party API Calls option:

The Third Party API Call History window appears.

Clicking the API call links displays the request and response for the call:

Install Command

Some Workflow commands contain a lot of variable out information. For example, the Install Command:

Output History

Each deployment shows its own execution variable output. Rerunning the deployment does not overwrite the output. If you rerun a deployment, the old deployment contains its variable output and the new deployment contains its new variable output.

See Also

Passing Variables into Workflows and Pipelines from Triggers

Triggers


How did we do?