What is a Harness Variable Expression?

Updated 3 weeks ago by Michael Cretzman

Harness variable expressions are used to parameterize settings in your Harness components, create environment variables, and create templates that can be used by your team.

You can create your own variable expressions to pass information through your Pipeline, or use built-in expressions to reference most of the settings and deployment information 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.

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.

Variable Expression Name Restrictions

Variable names may only contain a-z, A-Z, 0-9, _. They cannot contain hyphens.

The following keywords are reserved, and cannot be used as a variable name or property when using the dot operator:

or and eq ne lt gt le ge div mod not null true false new var return

For example, the following is invalid:

my.new.dotted.var1 // invalid ('new' is keyword)

In such cases, quoted identifiers or the [ ] operator can be used, for example:

my.'new'.dotted.var1

my['new'].dotted.var1

See JEXL grammar details.

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.

When are Variable Expressions Evaluated?

Variable expressions are resolved before the Bash or PowerShell script is run. Therefore, if you use one in a Bash comment, the variable expression is resolved and its value is displayed.

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.

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.
  • For most Service types, Harness uses Service Config Variables to create environment variables on the target hosts at deployment runtime.

See Add Service Config Variables.

Environment

${env.name}

  • Harness Environment name.

${env.description}

  • Harness Environment description.

${serviceVariable.override_var_name}

${environmentVariable.variable_name}

  • References a Service Override variable set in an Environment. In the following example, the name is foo.

Infrastructure

${infra.name}

  • The name of the Harness Infrastructure Definition used by the Workflow or Workflow Phase.

${infra.kubernetes.namespace}

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

${infra.route}

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

${infra.tempRoute}

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

Workflow

${workflow.displayName}

  • Harness 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.
  • This variable expression is used in a Workflow and displays the unique ID of the Pipeline that deploys the Workflow. When the Workflow is run by itself, and not in a Pipeline deployment, this variable expression will output null.

${workflow.pipelineResumeUuid}

  • Original execution ID of a resumed Pipeline execution. See Resume Pipeline Deployments.
  • This variable expression is used in a Workflow and displays the unique ID of the Pipeline that deploys the Workflow. When the Workflow is run by itself, and not in a Pipeline deployment, this variable expression will output null.

${workflow.variables.var_name}

Shell Script Command

${context.published_name.var_name}

Pipelines

  • See ${workflow.pipelineDeploymentUuid} above.
  • See ${workflow.pipelineResumeUuid} above.

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

You cannot access artifact metadata in a Build Workflow because Build Workflows do not use a Harness Service. See CI/CD with the Build Workflow.

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

You cannot access artifact metadata in a Build Workflow because Build Workflows do not use a Harness Service. See CI/CD with the Build Workflow.
  • 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 expression output would be registry.hub.docker.com/library/nginx:stable-perl at runtime.

${artifact.metadata.tag}

You cannot access artifact metadata in a Build Workflow because Build Workflows do not use a Harness Service. See CI/CD with the Build Workflow.
  • 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.metadata.artifactId}

  • The ID of the artifact. What this contains depends on the repository platform.

${artifact.metadata.repositoryName}

  • The name of the repository where this artifact is pulled from.

${artifact.metadata.groupId}

  • The ID of the group (such as a Nexus group ID). What this contains depends on the repository platform.

${artifact.source.dockerconfig}

${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 step, 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 microservice/application is deployed.
  • If you use this variable in a Workflow, such as in a Shell Script step, Harness will apply the script to all target instances. You do not have to loop through instances in your script.

${instance.host.hostName}

  • The same as ${instance.hostName}. For Docker containers, it displays the Docker ID.
  • For example: d40161ece682.
  • See ${instance.EcsContainerDetails.dockerId} in AWS ECS below also.

${instance.host.ip}

  • The IP address of the target deployment host(s).

${instance.dockerId}

  • The container ID where the Service is deployed. Also see AWS ECS below.

${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.hostName} — (Deprecated)

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

${host.ip} — (Deprecated)

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

${host.publicDns} — (Deprecated)

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

${host.ec2Instance.instanceId} — (Deprecated)

  • The AWS EC2 instance ID.

${host.ec2Instance.instanceType} — (Deprecated)

  • The AWS EC2 instance type.

${host.ec2Instance.imageId} — (Deprecated)

  • The AWS EC2 instance image ID.

${host.ec2Instance.architecture} — (Deprecated)

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

${host.ec2Instance.kernelId} — (Deprecated)

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

${host.ec2Instance.keyName} — (Deprecated)

  • The AWS EC2 instance key-pair name.

${host.ec2Instance.privateDnsName} — (Deprecated)

  • The AWS EC2 instance private DNS FQDN.

${host.ec2Instance.privateIpAddress} — (Deprecated)

  • The AWS EC2 instance private IP address.

${host.ec2Instance.publicDnsName} — (Deprecated)

  • The AWS EC2 instance public DNS FQDN.

${host.ec2Instance.publicIpAddress} — (Deprecated)

  • The AWS EC2 instance public IP address.

${host.ec2Instance.subnetId} — (Deprecated)

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

${host.ec2Instance.vpcId} — (Deprecated)

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

HTTP

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.

Approval

Approval variables can be defined only within Workflow Approval steps that use the Harness UI. See Harness UI Approvals.

${approvedBy.name} — (Deprecated)

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

${approvedBy.email} — (Deprecated)

  • 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 (published_name). For details about this convention, see Using Variables in Workflow Approvals.

${published_name.approvedBy.email}

${published_name.approvedOn}

${published_name.comments}

${published_name.timeoutMillis}

${published_name.approvalStateType}

${published_name.approvalStatus}

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

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

${published_name.variables.var_name}

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/ASG

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

AWS ECS

${instance.EcsContainerDetails.dockerId}

  • Short form Docker ID for the Docker container hosting the deployed image. For example: d40161ece682.

${instance.EcsContainerDetails.completeDockerId}

  • Full form Docker ID for the Docker container hosting the deployed image. For example:
    d40161ece682a74922b9c540be199cd9fbead4760cd9826b637a58d930c0f526

${ECS__Service__Setup.<Service_Name>}

  • To obtain the name of the ECS service deployed in a Harness ECS Workflow (from the ECS Service Setup step), you can use the Harness expression ${ECS__Service__Setup.<Service_Name>}. You might want to use the name in additional Workflow steps also.

Terraform

${terraform.<output_name>}

  • 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 How-tos.

CloudFormation

${cloudformation.<output_name>}

  • When you map a CloudFormation template output to a Harness field, as part of an Infrastructure Definition, 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

Kubernetes Workflows use various expressions to represent Kubernetes services, Blue/Green and Canary deployment values, and Istio traffic splitting.

For more information, see Kubernetes How-tos and Kubernetes 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.
  • You can use this variable in a Workflow Shell Script to set the environment variable at the beginning of your kubectl script:
    export KUBECONFIG=${HARNESS_KUBE_CONFIG_PATH}

Pivotal

See PCF Workflows and Deployments.

Helm

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

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.

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.

Service Config Variables

When you create variables in a Harness Service's Config Variables section, they can be referenced anywhere that Service is used in your Workflow. For more information, see Add Service Config Variables.

You reference the Service Config Variable using the ${serviceVariable.your_var_name} format.

The Service Config Variables are added to your target hosts as Environment variables.

For example, if you have a Service Config Variable named jarName, Harness creates an environment variable name jarName that can be referenced in two ways:

  • As a Service variable: ${serviceVariable.jarName}. There is no escaping done by Harness.
  • As an environment variable: ${jarName}. Escaping is automatically done by Harness.

Service 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 Add Service 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.

See Also


How did we do?