Plugin Defaults

Plugin defaults are default values applied to every task of a given type within one or more flows.

They work like default function arguments, helping you avoid repetition when tasks or plugins frequently use the same values.

Plugin defaults on a flow-level

You can define plugin defaults in the pluginDefaults section to avoid repeating properties across multiple tasks of the same type. For example:

id: api_python_sql
namespace: company.team


tasks:
  - id: api
    type: io.kestra.plugin.core.http.Request
    uri: https://dummyjson.com/products


  - id: hello
    type: io.kestra.plugin.scripts.python.Script
    script: |
      print("Hello World!")


  - id: python
    type: io.kestra.plugin.scripts.python.Script
    beforeCommands:
      - pip install polars
    outputFiles:
      - "products.csv"
    script: |
      import polars as pl
      data = {{outputs.api.body | jq('.products') | first}}
      df = pl.from_dicts(data)
      df.glimpse()
      df.select(["brand", "price"]).write_csv("products.csv")


  - id: sql_query
    type: io.kestra.plugin.jdbc.duckdb.Query
    inputFiles:
      in.csv: "{{ outputs.python.outputFiles['products.csv'] }}"
    sql: |
      SELECT brand, round(avg(price), 2) as avg_price
      FROM read_csv_auto('{{workingDir}}/in.csv', header=True)
      GROUP BY brand
      ORDER BY avg_price DESC;
    store: true


pluginDefaults:
  - type: io.kestra.plugin.scripts.python.Script
    values:
      taskRunner:
        type: io.kestra.plugin.scripts.runner.docker.Docker
        pullPolicy: ALWAYS # set it to NEVER to use a local image
      containerImage: python:slim

In this example, Docker and Python configurations are defined once in pluginDefaults, instead of being repeated in every task. This approach helps to streamline the configuration process and reduce the chances of errors caused by inconsistent settings across different tasks.

If you move required attributes into pluginDefaults, the UI code editor may show warnings about missing arguments, because defaults are only resolved at runtime. As long as pluginDefaults contains the relevant arguments, you can save the flow and ignore the warning displayed in the editor.

pluginDefaultsWarning

forced attribute in pluginDefaults

Setting forced: true in pluginDefaults ensures that default values override any properties defined directly in the task. By default, the value of the forced attribute is false.

Plugin defaults in a global configuration

Plugin defaults can also be defined globally in your Kestra configuration, applying the same values across all flows. This is useful when you want to apply the same defaults across multiple flows. Let’s say that you want to centrally manage the default values for the io.kestra.plugin.aws plugin to reuse the same credentials and region across all your flows. You can add the following to your Kestra configuration:

kestra:
  plugins:
    defaults:
      - type: io.kestra.plugin.aws
        values:
          accessKeyId: "{{ secret('AWS_ACCESS_KEY_ID') }}"
          secretKeyId: "{{ secret('AWS_SECRET_ACCESS_KEY') }}"
          region: "us-east-1"

If you want to set defaults only for a specific task, you can do that too:

kestra:
  plugins:
    defaults:
      - type: io.kestra.plugin.aws.s3.Upload
        values:
          accessKeyId: "{{ secret('AWS_ACCESS_KEY_ID') }}"
          secretKeyId: "{{ secret('AWS_SECRET_ACCESS_KEY') }}"
          region: "us-east-1"