Task runner that executes a task inside a pod in a Kubernetes cluster.

This plugin is only available in the Enterprise Edition (EE).

To generate output files you can:

Use the outputFiles property of the task and create a file with the same name in the task’s working directory, or
Create any file in the output directory, which can be accessed with the {{outputDir}} Pebble expression or the OUTPUT_DIR environment variable.

When the Kestra Worker running this task is terminated, the pod continues until completion. After restarting, the Worker will resume processing on the existing pod unless resume is set to false.

If your cluster is configured with RBAC, the service account running your pod must have the following authorizations:

pods: get, create, delete, watch, list
pods/log: get, watch
pods/exec: get, watch

Here is an example role that grants these authorizations:

yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata: 
  name: task-runner
rules: 
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "create", "delete", "watch", "list"]
- apiGroups: [""]
  resources: ["pods/exec"]
  verbs: ["get", "watch"]
- apiGroups: [""]
  resources: ["pods/log"]
  verbs: ["get", "watch"]

yaml
type: "io.kestra.plugin.ee.kubernetes.runner.kubernetes"

Examples

Execute a Shell command.

yaml
id: new-shell
namespace: company.team

tasks:
  - id: shell
    type: io.kestra.plugin.scripts.shell.Commands
    taskRunner:
      type: io.kestra.plugin.ee.kubernetes.runner.Kubernetes
    commands:
      - echo "Hello World"

Pass input files to the task, execute a Shell command, then retrieve output files.

yaml
id: new-shell-with-file
namespace: company.team

inputs:
  - id: file
    type: FILE

tasks:
  - id: shell
    type: io.kestra.plugin.scripts.shell.Commands
    inputFiles:
      data.txt: "{{ inputs.file }}"
    outputFiles:
      - out.txt
    containerImage: centos
    taskRunner:
      type: io.kestra.plugin.ee.kubernetes.runner.Kubernetes
    commands:
      - cp {{ workingDir }}/data.txt {{ workingDir }}/out.txt

Properties

config Connection

The configuration of the target Kubernetes cluster.

containerDefaultSpec object

Default container spec applied to all containers in the pod

When set, these container spec fields are merged into all containers including:

User-defined containers in the spec
Init and sidecar containers for file transfer (unless fileSidecar.defaultSpec is set)

This provides a convenient way to apply uniform container settings across all containers, which is especially useful in restrictive environments like GovCloud.

Supports any valid Kubernetes container spec fields such as:

securityContext: Security settings for all containers
volumeMounts: Volume mounts to add to all containers
resources: Resource limits/requests for all containers
env: Environment variables for all containers

Merge behavior:

For nested objects (like securityContext): deep merge, container-specific values take precedence
For lists (like volumeMounts, env): concatenated, with defaults added first
Container-specific values always override defaults

Example configuration:

text

containerDefaultSpec: 
  securityContext: 
    allowPrivilegeEscalation: false
    capabilities: 
      drop: 
      - ALL
    readOnlyRootFilesystem: true
    seccompProfile: 
      type: RuntimeDefault
  volumeMounts: 
    - name: tmp
      mountPath: /tmp
  resources: 
    limits: 
      memory: "256Mi"

containerSpec object

Additional YAML spec for the container.

delete booleanstring

Default true

Whether the pod should be deleted upon completion.

fileSideCarSpec object

Additional YAML spec for the sidecar container.

fileSidecar SideCar

Default

{
  "image": "busybox"
}

The configuration of the file sidecar container that handle download and upload of files.

killed AtomicBoolean

Default false

labels object

The pod custom labels

Kestra will add default labels to the pod with execution and flow identifiers.

namespace string

Default default

The namespace where the pod will be created.

nodeSelector object

Node selector for pod scheduling

Kestra will assign the pod to the nodes you want (see Assign Pod Nodes)

podSpec object

Additional YAML spec for the pod.

pullPolicy string

Default ALWAYS

Possible Values

IF_NOT_PRESENTALWAYSNEVER

The image pull policy for a container image and the tag of the image, which affect when Docker attempts to pull (download) the specified image.

resources Kubernetes-Resources

The pod custom resources

resume booleanstring

Default true

Whether to reconnect to the current pod if it already exists.

serviceAccountName string

The name of the service account.

syncWorkingDirectory booleanstring

Default false

Whether to synchronize working directory from remote runner back to local one after run.

version string

Plugin Version

Defines the version of the plugin to use.

The version must follow the Semantic Versioning (SemVer) specification:

A single-digit MAJOR version (e.g., 1).
A MAJOR.MINOR version (e.g., 1.1).
A MAJOR.MINOR.PATCH version, optionally with any qualifier (e.g., 1.1.2, 1.1.0-SNAPSHOT).

waitForLogs string

Default PT30S

Format duration

The additional duration to wait for logs to arrive after pod completion.

As logs are not retrieved in real time, we cannot guarantee that we have fetched all logs when the pod complete, therefore we wait for a fixed amount of time to fetch late logs.

waitUntilCompletion string

Default PT1H

Format duration

The maximum duration to wait for the pod completion unless the task timeout property is set which will take precedence over this property.

waitUntilRunning string

Default PT10M

Format duration

The maximum duration to wait until the pod is created.

This timeout is the maximum time that Kubernetes scheduler can take to

schedule the pod
pull the pod image
and start the pod.

Definitions

io.kestra.plugin.ee.kubernetes.models.OAuthTokenProvider

output string

task Task

io.kestra.core.models.tasks.retrys.Constant

interval *string

Format duration

type *object

behavior string

Default RETRY_FAILED_TASK

Possible Values

RETRY_FAILED_TASKCREATE_NEW_EXECUTION

maxAttempts integer

Minimum >= 1

maxDuration string

Format duration

warningOnRetry boolean

Default false

io.kestra.plugin.ee.kubernetes.runner.SideCar

defaultSpec object

Default container spec for the file sidecar and init containers

Default container spec fields applied to the init and sidecar containers used for file transfer. When set, this overrides containerDefaultSpec for file transfer containers only.

Supports the same fields as containerDefaultSpec:

securityContext: Security settings for file transfer containers
volumeMounts: Volume mounts to add to file transfer containers
resources: Resource limits/requests (note: also available as top-level 'resources' property)
env: Environment variables for file transfer containers

Example configuration:

text

fileSidecar: 
  defaultSpec: 
    securityContext: 
      allowPrivilegeEscalation: false
      capabilities: 
        drop: 
        - ALL
      readOnlyRootFilesystem: true
      seccompProfile: 
        type: RuntimeDefault
    volumeMounts: 
      - name: tmp
        mountPath: /tmp

image string

Default busybox

The image used for the file sidecar container.

resources object

The resource requirements applied to the file sidecar container

io.kestra.core.models.tasks.retrys.Random

maxInterval *string

Format duration

minInterval *string

Format duration

type *object

behavior string

Default RETRY_FAILED_TASK

Possible Values

RETRY_FAILED_TASKCREATE_NEW_EXECUTION

maxAttempts integer

Minimum >= 1

maxDuration string

Format duration

warningOnRetry boolean

Default false

io.kestra.plugin.ee.kubernetes.runner.Kubernetes-Resource

cpu string

memory string

io.kestra.plugin.ee.kubernetes.runner.Kubernetes-Resources

limit Kubernetes-Resource

request Kubernetes-Resource

io.kestra.core.models.tasks.retrys.Exponential

interval *string

Format duration

maxInterval *string

Format duration

type *object

behavior string

Default RETRY_FAILED_TASK

Possible Values

RETRY_FAILED_TASKCREATE_NEW_EXECUTION

delayFactor number

maxAttempts integer

Minimum >= 1

maxDuration string

Format duration

warningOnRetry boolean

Default false

java.util.concurrent.atomic.AtomicBoolean

io.kestra.core.models.tasks.Cache

enabled *boolean

ttl string

Format duration

io.kestra.plugin.ee.kubernetes.models.Connection

apiVersion string

Default v1

The API version

caCertData string

CA certificate as data

caCertFile string

CA certificate as file path

clientCertData string

Client certificate as data

clientCertFile string

Client certificate as a file path

clientKeyAlgo string

Default RSA

Client key encryption algorithm

default is RSA

clientKeyData string

Client key as data

clientKeyFile string

Client key as a file path

clientKeyPassphrase string

Client key passphrase

disableHostnameVerification booleanstring

Disable hostname verification

keyStoreFile string

Key store file

keyStorePassphrase string

Key store passphrase

masterUrl string

Default https://kubernetes.default.svc

The url to the Kubernetes API

namespace string

The namespace used

oauthToken string

Oauth token

oauthTokenProvider OAuthTokenProvider

Oauth token provider

password string

Password

trustCerts booleanstring

Trust all certificates

trustStoreFile string

Truststore file

trustStorePassphrase string

Truststore passphrase

username string

Username

io.kestra.core.models.tasks.WorkerGroup

fallback string

Possible Values

FAILWAITCANCEL

key string