Built-in Harness Variables Reference

Updated 2 days ago by Michael Cretzman

This topic 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.

FQNs and Alias

Everything in Harness can be referenced by a Fully Qualified Name (FQN). The FQN is the path to a setting in the YAML of your Pipeline:

You can select the FQN for a setting or value in the Pipeline editor or execution.

For example, you can click the copy button in a Pipeline execution to get the FQNs of settings and values.

When building a Pipeline in Pipeline Studio, you can copy the FQN of a setting using Variables.

Harness also includes aliases for the most common settings.

For example, you could reference a Service name using the FQN or alias:

  • FQN: <+pipeline.stages.[stage_name].serviceConfig.service.serviceRef>
  • Alias: <+service.name>

When Should I Use an FQNs or Alias?

Use FQNs when you have multiple stages and want to reference the specific setting in a stage from another stage.

For example, if you have a two stage Pipeline and you want to reference the name of the first stage in a step in the second stage, using <+service.name> would not work.

Instead, you would use <+pipeline.stages.stage1.spec.serviceConfig.serviceRef>.

Expression Example

Here is a simple example of a Shell Script step echoing some common variable expressions:

echo "Harness account name: "<+account.name>

echo "Harness comp name: "<+account.companyName>

echo "pipeline executionId: "<+pipeline.executionId>

echo "pipeline sequenceId: "<+pipeline.sequenceId>

echo "stage name: "<+stage.name>

echo "service name: "<+service.name>

echo "service variables: "<+service.variables.example_var>

echo "artifact image: "<+artifact.image>

echo "artifact.imagePath: "<+artifact.imagePath>

echo "environment name: "<+environment.name>

echo "infrastructure connectorRef: "<+infra.connectorRef>

echo "infrastructure namespace: "<+infra.namespace>

echo "infrastructure releaseName: "<+infra.releaseName>

Here is an example of the output:

Harness account name: Harness.io

Harness comp name: Harness.io

pipeline executionId: T4a7uBs7T-qWhNTr-LnFDw

pipeline sequenceId: 16

stage name: dev

service name: nginx

service variables: foo

artifact image: index.docker.io/library/nginx:stable

artifact.imagePath: library/nginx

environment name: quickstart

infrastructure connectorRef: account.harnesstestpmdemocluster

infrastructure namespace: default

infrastructure releaseName: docs

Command completed with ExitCode (0)

Copying Expressions in the UI

Every step in a stage contains Input and Output information that displays the same information as the expressions:

Copy the Input Name of an setting:

Paste the result into a Shell Script step or a text editor to see the variable path:

<+pipeline.stages.Variables.serviceConfig.output.artifactsResult.primary.artifactType>

This allows you to reference that setting anywhere in the Pipeline.

Account

<+account.name>

Harness account name.

<+account.companyName>

The name of the company for the account.

Org

<+org.name>

The name of the Org.

<+org.description>

The description of the Org.

Project

<+project.name>

The name of the Harness Project.

<+project.description>

The description of the Harness Project.

<+project.tags>

All Harness Tags attached to the Project.

<+project.identifier>

The entity identifier of the Harness Project.

Pipeline

<+pipeline.executionId>

Every execution of a Pipeline is given a universally unique identifier (UUID). The UUID can be referenced anywhere.

For example, in the following execution URL the UUID follows executions and is kNHtmOaLTu66f_QNU-wdDw:

https://app.harness.io/ng/#/account/12345678910/cd/orgs/default/projects/CD_Quickstart/pipelines/Helm_Quickstart/executions/kNHtmOaLTu66f_QNU-wdDw/pipeline

<+pipeline.sequenceId>

The incremental sequential ID for the execution of a Pipeline. A <+pipeline.executionId> does not change, but a <+pipeline.sequenceId> is incremented with each run of the Pipeline.

The first run of a Pipeline receives a sequence ID of 1 and each subsequent execution is incremented by 1.

For CD Pipelines the ID is named Execution. For CI Pipelines the ID is named Builds.

You can use <+pipeline.sequenceId> to tag a CI build when you push it to a repo, and then use <+pipeline.sequenceId> to pull the same build and tag in a subsequent stage. See CI Pipeline Quickstart.

<+pipeline.startTs>

The start time of a Pipeline execution in Unix Epoch format.

Stage

<+stage.name>

The name of the stage where the expression is evaluated.

<+stage.description>

The description of the stage where the expression is evaluated.

<+stage.tags>

The tags on the stage where the expression is evaluated. See Tags Reference.

These tags are different from Docker image tags.

<+stage.identifier>

The entity identifier of the stage where the expression is evaluated.

Service

<+service.name>

The name of the Service where the expression is evaluated.

<+service.description>

The description of the Service where the expression is evaluated.

<+service.tags>

The tags on the Service where the expression is evaluated.

<+service.identifier>

The entity identifier of the Service where the expression is evaluated.

<+service.variables.[var_name]>

The value of the Service-level variable in [var_name].

Use expression anywhere after the Service step in the Pipeline.

The variables are referenced in sequence, starting with 0: <+service.variables[0].name>, <+service.variables[1].name>, etc.

Artifact

<+artifact.tag>

Not Harness Tags. This expression evaluates to the tags on the artifact pushed, pulled, or deployed. For example, AMI tags, or if you are deploying Docker image nginx:stable-perl then stable-perl is the tag.

<+artifact.image>

The name of the artifact use for the stage.

For example, if you are deploying the public Docker image nginx then nginx:stable-perl at is the output runtime.

Typically you use this expression in the values.yaml to reference the artifact added to Harness.

name: <+stage.variables.name>
replicas: 2

image: <+artifact.image>
# dockercfg: <+artifact.imagePullSecret>

createNamespace: true
namespace: <+infra.namespace>
...

See Add Container Images as Artifacts for Kubernetes Deployments.

<+artifact.imagePath>

The location of the artifact.

For example, if you are deploying the public Docker image nginx then registry.hub.docker.com/library/nginx:stable-perl at is the output runtime.

<+artifact.imagePullSecret>

If some cases, your Kubernetes cluster might not have the permissions needed to access a private Docker registry. For these cases, the values.yaml or manifest file in Service Definition Manifests section must use the dockercfg parameter.

If the Docker image is added in the Service Definition Artifacts section, then you reference it like this: dockercfg: <+artifact.imagePullSecret>.

values.yaml:

name: <+stage.variables.name>
replicas: 2

image: <+artifact.image>
dockercfg: <+artifact.imagePullSecret>

createNamespace: true
namespace: <+infra.namespace>
...

See Pull an Image from a Private Registry for Kubernetes.

<+artifact.type>

The type of repository used to add this artifact in the Service Artifacts. For example, Dockerhub, Ecr, or Gcr.

<+artifact.connectorRef>

The entity identifier for the Connector used to connect to the artifact repo.

Sidecar Artifacts

Sidecar artifact expressions use the Sidecar Identifier to reference the sidecar artifact.

The sidecar identifier is set when you add the sidecar artifact. It can bee seen in the artifact listing:

Here are the sidecar expressions:

  • <+artifacts.sidecars.[sidecar_identifier].imagePath>
  • <+artifacts.sidecars.[sidecar_identifier].imagePath>
  • <+artifacts.sidecars.[sidecar_identifier].type>
  • <+artifacts.sidecars.[sidecar_identifier].tag>
  • <+artifacts.sidecars.[sidecar_identifier].connectorRef>

Environment

<+env.name>

The name of the stage Environment.

<+env.identifier>

The entity identifier of the stage's Environment.

<+env.description>

The description of the Environment.

<+env.type>

The Environment Type, such as Production or Non-Production.

Infrastructure

<+infra.connectorRef>

The name of the Connector used in the Infrastructure Definition.

<+INFRA_KEY>

The infrastructure key. The key is a unique string that identifies a deployment target infrastructure. It is typically used in the Release Name setting to add labels to release for tracking.

For example, in a Deploy stage's Infrastructure Definition, the <+INFRA_KEY> is used in the Release Name to give the release a unique name:

When you deploy, Harness adds the Release Name as a label. For example, in a Kubernetes deployment you can see harness.io/release-name=release-2f9eadcc06e2c2225265ab3cbb1160bc5eacfd4f:

...
Pod Template:
Labels: app=hello
deployment=hello
harness.io/release-name=release-2f9eadcc06e2c2225265ab3cbb1160bc5eacfd4f
Containers:
the-container:
Image: monopole/hello:1
...

Harness can now track the release for comparisons and rollback.

<+infra.namespace>

The namespace used in the Infrastructure Definition.

<+infra.releaseName>

The release name used in the Infrastructure Definition.

Kubernetes

${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 Shell Script step to set the environment variable at the beginning of your kubectl script:

export KUBECONFIG=${HARNESS_KUBE_CONFIG_PATH}

Tag Expressions

You can reference Tags using Harness expressions.

You simply reference the tagged entity and then use tags.[tag name], like <+pipeline.tags.docs>

For example, here are several different references:

  • <+pipeline.tags.[tag name]>
  • <+stage.tags.[tag name]>
  • <+pipeline.stages.s1.tags.[tag name]>
  • <+serviceConfig.service.tags.[tag name]>


Please Provide Feedback