Built-in Variables List

Updated 1 week ago by Michael Cretzman

The following lists describes 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.

For information on how Harness uses built-in variable expressions, see What is a Harness Variable Expression?.

In this topic:

Application

${app.name}

  • Harness Application name.

${app.description}

  • Harness Application description.

Service

${service.name}

  • Harness Service name.

${service.description}

  • Harness Service description.

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

${env.environmentType}

  • Harness Environment type. Evaluates to PROD or NON-PROD.

${serviceVariable.override_var_name}

${environmentVariable.variable_name}

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

${env.accountId}

  • The Harness account ID where the Environment is set up.

${env.keywords}

  • Lists Environment type (Prod or Non-Prod) followed by Environment name.

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.

${infra.cloudProvider.name}

  • Name of the Harness Cloud Provider selected in the Infrastructure Definition used by the Workflow.

Workflow

See Set Workflow Variables.

${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 Workflow Step

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

A few things to remember when using instance variable expressions:

  • Only use instance variable expressions at points in Workflow where instances are identifiable. For example, in a pre-deployment phase, the target instances are not known. In cases where Harness is creating instances, such as an AWS AMI/ASG deployment, the instances are not known until after they created.
  • If you use an instance variable expression in a script, the script is forked and executed once for each 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.

${httpResponseMethod}

  • 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

${instance.ecsContainerDetails.taskId}

  • AWS Task ID for ECS container.

${instance.ecsContainerDetails.taskArn}

  • AWS Task ARN for ECS container.

ECS Service Name

The ECS service Harness deploys is named using whatever is set in the ECS Service Setup Workflow step's ECS Service Name setting:

By default, the ECS service is named using a concatenation of Harness Application, Service, and Environment names: ${app.name}__${service.name}__${env.name}.

You can use a Workflow variable or built-in Harness expression in the ECS Service Name setting. You can then use that variable elsewhere to refer to the deployed service name.

ECS Service Names Create by Harness

When Harness creates your new ECS service, it names it according to the ECS Service Setup Workflow step's ECS Service Name setting, and adds a version number as a suffix. For example:

ECS__Example__Default_Replica__stage__ecs__4

You can reference this name in your Workflow after the ECS Service Setup step using the following expression:

${ECS__Service__Setup.serviceName}

For example, you can use a Shell Script step after the ECS Service Setup step to output the newly created ECS service name, including the version number suffix Harness adds each deployment:

echo "${ECS__Service__Setup.serviceName}"

You can then output that value from the Shell Script step for use elsewhere in your Workflow.

You can reference the target ECS cluster using the following expression:

${ECS__Service__Setup.clusterName}

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.

${terraformApply.tfplan}

  • Displays the Terraform plan that was executed as a dry run in the Terraform Apply or Terraform Provision step.
  • When you use the Terraform Apply or Terraform Provision step in a Workflow, you can select the Set as Terraform Plan option to run the step as a dry run. See Perform a Terraform Dry Run.

${terraformDestroy.tfplan}

  • Displays the Terraform plan that was executed as a dry run in the Terraform Destroy step.
  • When you use the Terraform Destroy step in a Workflow, you can select the Set as Terraform Destroy Plan and Export option to run the step as a dry run. See Remove Provisioned Infra with Terraform Destroy.

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 Built-in Variables.

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.


How did we do?