Variables and Expressions in Harness

Updated 5 days ago by Michael Cretzman

You can use expressions containing variable names to refer to components in Harness. For example, you can use an expression containing the variable name account to refer to account properties:

In this topic:

Overview

Harness includes two types of variables that you can use in expressions:

  • Harness built-in variables: There are variables scoped to different entities—such as Applications, Services, Environments, and Workflows—and variables that provide information about deployment environments.
  • User-created variables: You can create variables at the account level and application level, which can be used across your Harness applications. You can also create variables in Application entities, to be replaced by users when configuring or deploying a CD pipeline.
All expressions are evaluated immediately and use the ${} delimiters. Harness uses the Java Expression Language (JEXL) expression language to render variables.

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

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

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

Variables can be used with methods. For example, here is an object using the expression ${instance.hostName}:

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

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

For more information, see Objects and Functors.

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

What Expressions Am I Already Using?

An easy way to see what expressions are already used in your deployments is to look at the Execution Context for each Workflow step:

  1. In Harness, click Continuous Deployment.
  2. Locate a deployment and open it.
  3. Expand the deployment flowchart and then click any step in the deployment. You will see its details displayed.
  4. In the execution details, click the option button and click View Execution Context.
    The expressions used in that step are displayed.
    If an expression is too long to view, hover over it to see its full name.

Now you can reference those expressions elsewhere in your Workflow or Pipeline, in the set up of the Workflow, or in command such as Shell Script.

Creating Custom Variables

You can create variables in Services and Workflows.

Some Workflow commands let you publish their output as variables:

Variables are also integrated into Workflow Approval and Pipeline Approval steps.

Built-in Variables List

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

Entities

Expression

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.your_var_name}

Replace your_var_name to reference any variable created in a Service in the current Application. For example, you could add a Shell Script command to a Workflow that references the variable ${serviceVariable.productName}, 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.

${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}

Workflow

${workflow.displayName}

Workflow name and the timestamp when the Workflow is deploying.

For example, if the Workflow is named SSH, the ${workflow.displayName} would display something like this:

SSH - 02/27/2020 10:07 PM

${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.

Deployments

${deploymentUrl}

The URL of the deployment in the Harness Deployments page.

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.

For AWS AMI, it is the name of the build.

${artifact.label.<label-key>}

Lists the value of a Docker image artifact's label. The label is identified using the label key. For example, if the Docker image has the following label:

"Labels": {
"maintainer": "NGINX Docker Maintainers <docker-maint@nginx.com>"
},

You can reference the label in a Workflow Shell Script step using ${artifact.label.maintainer}.

Note that this key value example has the placeholder character <. Bash will throw an unexpected token error. Ensure that label values do not have unexpected tokens.

${artifact.revision}

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

For AWS AMI, it is the AMI ID, for example: ami-0ff62736444c74a47.

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, then 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, you would 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.

If you use this variable in a Workflow, such as in a Shell Script command, Harness will apply the script to all target instances. You do not have to loop through instances in your script.

${instance.hostName}

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

If you use this variable in a Workflow, such as in a Shell Script command, Harness will apply the script to all target instances. You do not have to loop through instances in your script.

${instance.dockerId}

The container ID where the Service is deployed.

${instance.host.publicDns}

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

If you use this variable in a Workflow, such as in a Shell Script command, Harness will apply the script to all target instances. You do not have to loop through instances in your script.

Host (Deprecated)

Host variables are deprecated, but existing usage is supported. All host properties are available using Instance.

${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, the public DNS name can be different from the host name.

(Deprecated)

${host.ec2Instance.instanceId}

The AWS EC2 instance ID.

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

The HTTP expressions are typically used in the Workflow HTTP step.

${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").

You can also use JSON and XML functors that httpResponseBody.

For example, json.select("status", ${httpResponseBody}) == "success". See JSON and XML Functors

${assertionStatement}

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

${assertionStatus}

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

Approval

(Approval variables can be defined only within Workflow Approval steps that use the Harness UI Ticketing System.)

(Deprecated)

${approvedBy.name}

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

(Deprecated)

${approvedBy.email}

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

${published_name.approvedBy.name}

The name of the Harness user that approved a Workflow approval step. (As of December, 2019, this—and the other Approval variables below—must be preceded by a published output variable name. For details about this convention, see Approvals.)

${published_name.approvedBy.email}

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

${published_name.approvedOn}

The epoch time at which a Workflow approval step was approved.

${published_name.comments}

Free-text comments that a user entered when approving (or rejecting) a Workflow approval step.

${published_name.timeoutMillis}

Timeout (in milliseconds) set for this approval step.

${published_name.approvalStateType}

The ticketing system used for this approval. The only currently supported value isUSER_GROUP. (Other possible values are: JIRA, SERVICENOW, and SHELL_SCRIPT.)

${published_name.approvalStatus}

The approval's outcome. Can take the values SUCCESS or REJECTED.

${published_name.userGroups[<index>].name}

An array of User Groups that were added in a Workflow's approval step. E.g., if two User Groups were added, you can access those groups' names as ${published_name.userGroups[0].name} and ${published_name.userGroups[1].name}.

${published_name.variables.var_name}

Use the .variables. prefix when referring to an Additional Input Variable that was defined in a Workflow Approval step.

Email

${toAddress}

The destination email address for an Email step in a Workflow.

${ccAddress}

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

${subject}

The email 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}

Use this expression to obtain the name of the new Auto Scaling Group created by Harness during deployment. For example, you could add a Shell Script step to your Workflow that contains the command echo ${ami.newAsgName}.

For more information, see AMI Deployments Overview.

${ami.oldAsgName}

Use this expression to obtain the name of the Auto Scaling Group created by the last successful deployment.

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 example, ${terraform.clusterName}.

For more information, see Terraform Provisioner.

CloudFormation

${cloudformation.output_name}

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 example, ${cloudformation.Region}.

For more information, see CloudFormation Provisioner.

Kubernetes

${k8s.primaryServiceName}

${k8s.stageServiceName}

${k8s.canaryWorkload}

${k8s.virtualServiceName}

${k8s.canaryDestination}

${k8s.stableDestination}

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

${HARNESS_KUBE_CONFIG_PATH}

The path to a Harness-generated kubeconfig file containing the credentials you provided. The credentials can be used by kubectl commands by exporting its value to the KUBECONFIG environment variable (see below).

You can use this variable in a Workflow Shell Script command to set the environment variable at the beginning of your kubectl script:

export KUBECONFIG=${HARNESS_KUBE_CONFIG_PATH}

Pivotal

See Pivotal variables.

Constants

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

Constant

Expression

Description

RUNTIME_PATH

${app.defaults.RUNTIME_PATH}

The runtime path for a Harness application:

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

BACKUP_PATH

${app.defaults.BACKUP_PATH}

The backup path for a Harness application:

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

STAGING_PATH

${app.defaults.STAGING_PATH}

The staging path for a Harness application:

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

WINDOWS_RUNTIME_PATH

${app.defaults.WINDOWS_RUNTIME_PATH}

The runtime path for a Harness application on Windows.

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 conventions 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 Definition

infra

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

Instance

instance

${instance.hostName}

Approval

published_name, published_name.variables

${published_name.approvedBy.email}, ​

${published_name.variables.signoff}

Email

NA

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

Pivotal Cloud Foundry

pcf

${infra.pcf.route}

Kubernetes

kubernetes

${infra.kubernetes.namespace}

Multi-Phase Workflows and Variable Availability

If you are using a multi-phase Workflow, such as a Canary Workflow, certain expressions will only return results within the Phases in which their targets are set up and used.

For example, when you set up a Canary Workflow's Phase, you select an Infrastructure Definition and a Service. Expressions that refer to the Infrastructure Definition and Service, such as ${infra.name} and ${serviceVariable.foo}, will not return results outside of that Phase.

Using ${infra.name} and ${serviceVariable.foo} in the Pre-deployment Steps of the Workflow, which is before the Phases, will result in a bad substitution error.

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 More Options ⋮ menu 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.

  1. Open a Harness Application, and then open a Service, such as Docker or Pivotal Cloud Foundry (PCF) Service within that Application.
  2. In the Service, under Configuration, click Add Variable. The Config Variable dialog appears.
  3. In Value, enter ${account.defaults} to see the account variables displayed.
  4. 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 the 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 who have the required permissions:

  • To create Application Default variables, you must be logged into Harness as a member of a User Group that has create or update permissions on that Application.
  • To add or edit Application Default variables, you must also be a member of a User Group with the Administer Other Account Functions setting enabled.
For details about enabling these required permissions, 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")}.

By default, the ${secrets.getValue("var_name")} is available in the Harness Applications listed in its Usage Scope. To make the secret available Account-wide, so that it can be used in a Delegate Profile, you must select the Scope to Account option:

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") – Plain text file contents.
  • configFile.getAsBase64("fileName") – Base64-encoded file contents.

For more information, see Config Files.

Objects and Functors

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

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

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

A split method is called with the argument ('\.'), 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 were 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".

For more functors, see JSON and XML Functors.

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, that 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 output information. An example is 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.

Limitations

  • Harness does not support the Ternary conditional ?: operator from JEXL.
  • Harness permits variables only within their scope. You will not see a variable available in a field where it cannot be used.
  • Do not use hyphens (dashes) in variable names, as some Linux distributions and deployment-related software do not allow them.

See Also


How did we do?