​Labels

Labels are key-value pairs used throughout Kestra to provide a user-defined layer of organization for flows and executions across multiple dimensions, without being limited to a single hierarchy.

They allow you to organize flows and executions by project, priority, maintainer, or any other criteria relevant to your use case. Unlike a fixed set of categories, labels enable 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 can be used to organize and filter flows and their executions based on your own criteria. You can add the labels section to flows to sort and group their executions, making them easier to discover and reason about.

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. Here are some of the benefits of using labels:

• Observability: labels set during execution provide help in monitoring and troubleshooting; you can infer a severity of an error or rerun only a specific subset of flow executions.
• Filtering: labels make it easier to find specific executions; you can use it to mark test runs, track ML experiments, track responses from external APIs, or label executions based on runtime-specific flow inputs.
• Organization: labels help organize and manage workflow executions at scale, especially in complex environments and large-scale deployments. You can create custom dashboards based on labels to monitor specific executions, e.g., http://localhost:8080/ui/executions?filters[labels][EQUALS][team]=finance. You can use that pattern to build custom dashboards for specific teams, projects, flow maintainers, or environments.

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 shown above, you can add execution labels, such as currency, to capture the attributes of the processed invoice. This allows you to filter executions by specific values, like currency: USD.

Another use case is labeling specific 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, the labels are propagated to the created 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 flow execution start by expanding the Advanced configuration section:

Since Kestra 0.15.0, you can also set labels from the UI after the execution has completed. This feature is useful for collaboration and troubleshooting in the team.

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

In Kestra 0.14.0, we introduced 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.

By using this task, you can set custom execution labels based on flow inputs, task outputs, or any other dynamic data within the workflow. 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 label values dynamically during execution based on the results of specific tasks.

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.