Variables
You can use variables to set any task property. They use the power of Pebble Templates with Kestra's special context system, allowing powerful task composition inside a flow.
Variables can use flow execution contextual information registered inside the execution context. The execution context is a set of data from different sources: flow and execution, environment variables, global variables, task defaults, flow inputs, and task outputs.
Flow and Execution variables
Flow and Execution variables allow using the current execution context to set task properties. For example: name a file with the current date or the current execution id.
The following table lists all the default variables available on each execution.
Parameter | Description |
---|---|
{{ flow.id }} | The identifier of the flow. |
{{ flow.namespace }} | The name of the flow namespace. |
{{ flow.tenantId }} | The identifier of the tenant (EE only). |
{{ flow.revision }} | The revision of the flow. |
{{ execution.id }} | The execution ID, a generated unique id for each execution. |
{{ execution.startDate }} | The start date of the current execution, can be formatted with {{ execution.startDate | date("yyyy-MM-dd HH:mm:ss.SSSSSS") }} . |
{{ execution.originalId }} | The original execution ID, this id will never change even in case of replay and keep the first execution ID. |
{{ task.id }} | The current task ID |
{{ task.type }} | The current task Type (Java fully qualified class name). |
{{ taskrun.id }} | The current task run ID. |
{{ taskrun.startDate }} | The current task run start date. |
{{ taskrun.parentId }} | The current task run parent identifier. Only available with tasks inside a (Flowable Task). |
{{ taskrun.value }} | The value of the current task run, only available with tasks inside a (Flowable Task). |
{{ taskrun.attemptsCount }} | The number of attempts for the current task (when retry or restart is performed). |
{{ parent.taskrun.value }} | The value of the closest (first) parent task run Flowable Task, only available with tasks inside a (Flowable Task). |
{{ parent.outputs }} | The outputs of the closest (first) parent task run Flowable Task, only available with tasks inside in a (Flowable Task). |
{{ parents }} | The list of parent tasks, only available with tasks inside a (Flowable Task). See Parents variables for its usage. |
If a schedule event triggers the flow, these variables are also available:
Parameter | Description |
---|---|
{{ trigger.date }} | The date of the current schedule. |
{{ trigger.next }} | The date of the next schedule. |
{{ trigger.previous }} | The date of the previous schedule. |
If a flow event triggers the flow, these variables are also available:
Parameter | Description |
---|---|
{{ trigger.executionId }} | The ID of the execution that triggers the current flow. |
{{ trigger.namespace }} | The namespace of the flow that triggers the current flow. |
{{ trigger.flowId }} | The ID of the flow that triggers the current flow. |
{{ trigger.flowRevision }} | The revision of the flow that triggers the current flow. |
All these variables can be used thanks to the Pebble template syntax {{varName}}
:
id: context-example
namespace: io.kestra.tests
tasks:
- id: echo
type: io.kestra.core.tasks.debugs.Return
format: |
taskid: {{task.id}}
date: {{ execution.startDate | date("yyyy-MM-dd HH:mm:ss.SSSSSS") }}
{{ execution.startDate | date("yyyy-MM-dd HH:mm:ss.SSSSSS") }}
uses the date
filter to format the execution.startDate
variable with the date pattern yyyy-MM-dd HH:mm:ss.SSSSSS
. More information on filters here.
Environment variables
By default, Kestra allows access to environment variables that start with KESTRA_
unless configured otherwise, see Variables configuration.
To access an environment variable KESTRA_FOO
from one of your tasks, you can use {{ envs.foo }}
, the variable's name is the part after the KESTRA_
prefix in lowercase.
Global variables
You can define global variables inside Kestra's configuration files and access them using {{ globals.foo }}
, see Variables configuration for more information.
Flow variables
You can declare variables at the flow level with the variables
property, then refer to these variables using the vars.my_variable
syntax, for example:
id: flow-variable
namespace: io.kestra.tests
variables:
my_variable: "my_value"
tasks:
- id: my_task
type: io.kestra.core.tasks.debugs.Return
format: "{{ vars.my_variable }}"
Inputs variables
You can use any flow inputs using inputs.inputName
, for example:
id: context-inputs
namespace: io.kestra.tests
inputs:
- name: myInput
type: STRING
tasks:
- id: myTask
type: io.kestra.core.tasks.debugs.Return
format: "{{inputs.myInput}}"
Secret variables
You can retrieve secrets in your flow using the secret()
function. Here is an example:
id: secret
namespace: io.kestra.tests
tasks:
- id: myTask
type: io.kestra.core.tasks.debugs.Return
format: "{{secret('MY_SECRET')}}"
Secrets can be provided on both open-source and Enterprise Edition. Check the Secrets documentation for more details. Also, see the Administrator Guide for detailed instructions on Secrets Manager configuration.
Outputs variables
You can use any task output attributes using outputs.taskId.outputAttribute
where:
taskId
is the ID of the task.outputAttribute
is the attribute of the task output you want to use. Each task output can emit different attributes; refer to the task documentation for the list of output attributes.
Example:
id: context-outputs
namespace: io.kestra.tests
tasks:
- id: firstExample
type: io.kestra.core.tasks.debugs.Return
format: "First return"
- id: second-example
type: io.kestra.core.tasks.debugs.Return
format: "Second return"
- id: log-both-variables
type: io.kestra.core.tasks.log.Log
message: "First: {{outputs.firstExample.value}}, Second: {{outputs['second-example'].value}}"
The Return
task has an output attribute value
which is used by the log-both-variables
task.
In the log-both-variables
task, you can see two ways to access task outputs: the dot notation (outputs.firstExample
) and the subscript notation (outputs['second-example']
). The subscript notation must be used when a variable contains a special character, such as -
that is a Pebble reserved character.
Pebble templating: example
The example below will parse the Pebble expressions within the variables
based on the inputs
and trigger
values. Both variables use the Null-Coalescing Operator to use the first non-null value.
Here, the first variable trigger_or_yesterday
will evaluate to a trigger.date
if the flow runs on schedule. Otherwise, it will evaluate to the yesterday's date by using the execution.startDate
minus one day.
The second variable input_or_yesterday
will evaluate to the mydate
input if it's provided. Otherwise, it will evaluate to the yesterday's date — again, using the execution.startDate
and subtracting one day with the help of the dateAdd
function.
id: vars_example
namespace: dev
inputs:
- name: mydate
type: DATETIME
required: false
variables:
trigger_or_yesterday: "{{ trigger.date ?? (execution.startDate | dateAdd(-1, 'DAYS')) }}"
input_or_yesterday: "{{ inputs.mydate ?? (execution.startDate | dateAdd(-1, 'DAYS')) }}"
tasks:
- id: yesterday
type: io.kestra.core.tasks.log.Log
message: "{{ vars.trigger_or_yesterday }}"
- id: input_or_yesterday
type: io.kestra.core.tasks.log.Log
message: "{{ vars.input_or_yesterday }}"
Pebble templating: deep dive
Pebble templating offers a myriad of ways to process variables. For a deep dive, check the following section: