​Labels

Labels are key-value pairs in Kestra that let you organize flows and executions across multiple dimensions, without being restricted to a single hierarchy.

You can organize flows and executions by project, priority, maintainer, or any other relevant criteria. Unlike fixed categories, labels support flexible filtering, grouping, and discovery.

Labels can be associated with both the flow definition and individual execution instances. This allows you to distinguish between different executions of the same flow.

The purpose of labels

Labels help organize and filter flows and their executions based on your criteria. Adding a labels section to flows lets you sort and group executions, making them easier to discover and analyze.

Here's a simple example of a flow with two labels defined:

id: process_invoice_flow
namespace: company.team

labels:
  team: finance
  priority: HIGH

tasks:
  - id: hello
    type: io.kestra.plugin.core.log.Log
    message: hello from a flow with labels

Executing such a flow results in the execution inheriting both team: finance and priority: HIGH labels by default. However, you can also define additional labels at the time of execution launch.

Benefits of labels

Labels provide a simple and effective way to organize and filter flows and their executions. Key benefits include:

• Observability: Track execution status, monitor errors, and rerun only a subset of executions.
• Filtering: Quickly find executions, mark test runs, track ML experiments, or label runs by runtime inputs.
• Organization: Manage workflows at scale by grouping executions by team, project, maintainer, or environment.

You can also build custom dashboards using labels, for example: http://localhost:8080/ui/executions?filters[labels][EQUALS][team]=finance.

Common scenarios

To group flows related to the same project across Kestra namespaces, you can use a common flow label, such as project: XYZ-123.

When running the process_invoice_flow, you can add execution labels (e.g., currency) to capture attributes of the processed invoice. This allows you to filter executions by specific values, like currency: USD.

You can also label executions related to a pre-production run. For example, using a purpose: pre-prod label. This enables you to safely delete only those executions associated with the pre-production phase.

In multi-team environments, labels help you to separate executions by team—for example, support: EMEA and support: APAC—when the same flow handles data from different regions.

Execution labels propagated from flow labels

When you execute a flow with labels, those labels are automatically applied to its executions.

Set execution labels when executing a flow from the UI

When executing flows manually from the UI, you can override and define new labels at the execution's start by expanding the Advanced configuration section:

You can set labels from the UI even after an execution completes. This helps with collaboration and troubleshooting.

For example, you can add a label to a failed execution to indicate its status, such as whether it has been acknowledged, is being investigated, or has been resolved.

To set labels from the UI, go to the Overview tab of an Execution and click on the "Set labels" button. You can add multiple labels at once.

You can even set labels for multiple executions at once from the UI. This feature is helpful for bulk operations, such as acknowledging multiple failed executions at once after an outage.

Set labels based on flow inputs and task outputs

You have the ability to set execution labels from a dedicated Labels task. This task provides a dynamic way to label your flows, helping with observability, debugging, and monitoring of failures.

This task lets you set custom execution labels based on flow inputs, task outputs, or other dynamic workflow data. There are two ways to set labels in this task:

1. Using a Map (Key-Value Pairs): ideal when the key is static and the value is dynamic. The key is the label name, and the value is a dynamic label value that might be derived from the flow inputs or task outputs. In the example below, the task update_labels overrides the default label song with the output of the get task, and adds a new label called artist.

id: labels_override
namespace: company.team

labels:
  song: never_gonna_give_you_up

tasks:
  - id: get
    type: io.kestra.plugin.core.debug.Return
    format: never_gonna_stop

  - id: update_labels
    type: io.kestra.plugin.core.execution.Labels
    labels:
      song: "{{ outputs.get.value }}"
      artist: rick_astley # new label

2. Using a List of Key-Value Pairs: particularly useful if both the key and the value are dynamic properties.

id: labels
namespace: company.team

inputs:
  - id: user
    type: STRING
    defaults: Rick Astley

  - id: url
    type: STRING
    defaults: song_url

tasks:
  - id: update_labels_with_map
    type: io.kestra.plugin.core.execution.Labels
    labels:
      customerId: "{{ inputs.user }}"

  - id: get
    type: io.kestra.plugin.core.debug.Return
    format: https://t.ly/Vemr0

  - id: update_labels_with_list
    type: io.kestra.plugin.core.execution.Labels
    labels:
      - key: "{{ inputs.url }}"
        value: "{{ outputs.get.value }}"

Overriding flow labels at runtime

You can set default labels at the flow level and override them at runtime. This approach is useful for overriding labels dynamically during execution, based on task results.

The example below shows how to override the default label song with the output of the get task:

id: flow_with_labels
namespace: company.team

labels:
  song: never_gonna_give_you_up
  artist: rick-astley
  genre: pop

tasks:
  - id: get
    type: io.kestra.plugin.core.debug.Return
    format: never_gonna_stop

  - id: update-list
    type: io.kestra.plugin.core.execution.Labels
    labels:
      song: "{{ outputs.get.value }}"

In this example, the default label song is overridden by the output of the get task.