# Flows
Flows are used to implement your workload. They define all the tasks you want to perform and the order in which they will be run.
You define a flow thanks to a declarative model in YAML.
A flow must have an identifier (id), a namespace, and a list of tasks.
A flow can also have inputs, listeners, error handlers, and triggers.
# Flow sample
Here is a sample flow definition. It uses tasks available in Kestra core for testing purposes.
id: samples
namespace: io.kestra.tests
description: "Some flow **documentation** in *Markdown*"
labels:
env: prd
country: FR
inputs:
- name: my-value
type: STRING
required: false
defaults: "default value"
description: This is a not required my-value
variables:
first: "1"
second: "{{vars.first}} > 2"
tasks:
- id: date
type: io.kestra.core.tasks.debugs.Return
description: "Some tasks **documentation** in *Markdown*"
format: "A log line content with a contextual date variable {{taskrun.startDate}}"
taskDefaults:
- type: io.kestra.core.tasks.debugs.Echo
level: ERROR
You can add arbitrary labels
to your flow. Labels can be handy when you have a lot of flows to sort them on multiple dimensions.
You can also define taskDefaults
inside your flow; this is a list of default task properties that will be applied to each task of a certain type inside your flow. Task defaults can be handy to avoid repeating the same value for a task property in case the same task type is used multiple times in the same flow.
You can set flow variables that will be accessible by each task using {{ vars.key }}
. Flow variables
is a map of key/value pairs.
The most important part of a flow is the list of tasks that will be run sequentially when the flow is executed.
# Flow Properties
The following flow properties can be set.
Field | Description |
---|---|
id | The flow identifier, must be unique inside a namespace. |
namespace | Each flow lives in one namespace, this is useful for flow organization and is mandatory. |
revision | The flow version, handled internally by Kestra, and incremented for each modification. You should not manually set it. |
description | The description of the flow, more details here. |
labels | The list of labels which are string key/value pairs. |
inputs | The list of inputs, more details here. |
variables | The list of variables (such as api key, table name, URL, etc) that can be reached inside tasks with {{ vars.name }} . |
tasks | The list of tasks, all tasks will be run sequentially. |
errors | The list of error tasks, all listed tasks will be run sequentially only if there is an error on the current execution. More details here. |
listeners | The list of listeners, more details here. |
triggers | The list of triggers which are external events (such as date schedule or message presence in a broker, for example) that will launch this flow, more details here. |
taskDefaults | The list of default task values, this avoid repeating the same properties on each tasks. |
taskDefaults.[].type | The task type is a full qualified Java class name. |
taskDefaults.[].forced | If set to forced: true , the taskDefault will take precedence over properties defined in the task (default false ). |
taskDefaults.[].values.xxx | The task property that you want to be set as default. |
disabled | Set it to true to disable execution of the flow. |
# Document your flow
You can add documentation to flows, tasks, etc... to explain the goal of the current element.
For this, Kestra allows adding a description
property where you can write documentation of the current element.
The description must be written using the Markdown (opens new window) syntax.
You can add a description
property on:
All descriptions will be visible on the UI:


