​Expression ​Types

There are many ways to use expressions in Kestra. This page will guide you through different types of expressions.

Flow and Execution expressions

Flow and Execution expressions 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 expressions available on each execution.

If execution is created from a Schedule-type trigger, these expressions are also available:

If execution is created from a Flow-type trigger, these expressions are also available:

All these expressions can be accessed using the Pebble template syntax {{expression}}:

id: expressions
namespace: company.team

tasks:
  - id: echo
    type: io.kestra.plugin.core.debug.Return
    format: |
      taskid: {{ task.id }}
      date: {{  execution.startDate | date("yyyy-MM-dd HH:mm:ss.SSSSSS") }}

Environment variables

By default, Kestra allows access to environment variables that start with KESTRA_ unless configured otherwise, see how you can configure environment variables in the variables configuration in your Kestra server settings.

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

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_variables
namespace: company.team

variables:
  my_variable: "my_value"

tasks:

  - id: print_variable
    type: io.kestra.plugin.core.debug.Return
    format: "{{ vars.my_variable }}"

Inputs

You can use any flow inputs using inputs.inputName, for example:

id: render_inputs
namespace: company.team

inputs:
  - id: myInput
    type: STRING

tasks:
  - id: myTask
    type: io.kestra.plugin.core.debug.Return
    format: "{{ inputs.myInput }}"

Secrets

You can retrieve secrets in your flow using the secret() function. Here is an example:

id: use_secret_in_flow
namespace: company.team

tasks:
  - id: myTask
    type: io.kestra.plugin.core.debug.Return
    format: "{{ secret('MY_SECRET') }}"

Secrets can be provided on both open-source and Enterprise Edition. Check the Secrets documentation for more details.

Namespace variables (EE)

Namespace variables are key-value pairs defined in a YAML configurtion. They can be nested and used in your flows using the dot notation e.g. {{ namespace.myproject.myvariable }}. You can define namespace variables in the Variables tab in the UI.

Namespace variables are scoped to the specific namespace and are inherited by child namespaces. Your flow then refers to these variables using the namespace.your_variable syntax, for example:

id: namespace_variables
namespace: company.team

tasks:
  - id: myTask
    type: io.kestra.plugin.core.debug.Return
    format: "{{ namespace.your_variable }}"

However, note that if your namespace variable contains Pebble expressions like e.g. {{ secret('GITHUB_TOKEN') }}, you must use the render function to render the variable. Assuming the following code being added to the Variables tab in a Namespace UI:

github:
  token: "{{ secret('GITHUB_TOKEN') }}"

To reference the github.token variable in your flow, you must use the render function:

id: recursive_namespace_variables_rendering
namespace: company.team
tasks:
  - id: myTask
    type: io.kestra.plugin.core.debug.Return
    format: "{{ render(namespace.github.token) }}"

The render() function is required to parse Namespace or Flow variables that contain Pebble expressions, as this function allows for recursive rendering. If you don't use the render function, the variable will be rendered as a string, and the Pebble expressions within the variable will not be evaluated.

Outputs

You can use any task output attributes using "{{ outputs.taskId.outputAttribute }}" where:

• the taskId is the ID of the task.
• the outputAttribute is the attribute of the task output you want to use; each task can emit various output attributes — check the task documentation for the list of output attributes for any given task.

Example of a flow using outputs to pass data between tasks:

id: pass_data_between_tasks
namespace: company.team

tasks:
    - id: first
      type: io.kestra.plugin.core.debug.Return
      format: First output value

    - id:
      type: io.kestra.plugin.core.debug.Return
      format: Second output value

    - id: print_both_outputs
      type: io.kestra.plugin.core.log.Log
      message: |
        First: {{ outputs.first.value }}
        Second: {{ outputs['second-task'].value }}

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: render_complex_expressions
namespace: company.team

inputs:
  - id: 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.plugin.core.log.Log
    message: "{{ render(vars.trigger_or_yesterday) }}"

  - id: input_or_yesterday
    type: io.kestra.plugin.core.log.Log
    message: "{{ render(vars.input_or_yesterday) }}"

Note how we use the render function to render the variables. This function is required when you want to render a variable that contains Pebble expressions, allowing for recursive rendering. If you don't use the render function, the variable will be rendered as a string, and the Pebble expressions within the variable will not be evaluated.

Pebble templating: deep dive

Pebble templating offers a myriad of ways to parse expressions.