​Plugin ​Defaults

Plugin defaults are a list of default values applied to each task of a certain type within your flow(s).

Plugin defaults are like default function arguments — they help avoid repetition when a given task or plugin is often called with the same values.

Plugin defaults on a flow-level

You can add plugin defaults to avoid repeating task properties on multiple occurrences of the same task in a pluginDefaults properties. 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
    warningOnStdErr: false
    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

Here, we avoid repeating Docker and Python configurations in each task by directly setting those within the pluginDefaults property. This approach helps to streamline the configuration process and reduce the chances of errors caused by inconsistent settings across different tasks.

Note that when you move some required task attributes into the pluginDefaults property, the code editor within the UI will complain that the required task argument is missing. The editor shows this message because pluginDefaults are resolved at runtime and the editor is not aware of those default attributes until you run your flow. As long as pluginDefaults contains the relevant arguments, you can save the flow and ignore the warning displayed in the editor.

forced attribute in pluginDefaults

In the pluginDefaults, if you set forced: true, the plugin default will take precedence over properties defined in the task. By default, the value of the forced attribute is false.

Plugin defaults in a global configuration

You can also set plugin defaults in your global Kestra configuration. 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"

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