Kestra Kubernetes Operator – GitOps for Flows and Resources

How to use the Kestra Kubernetes Operator to provision and manage changes to Kestra resources, including flows, namespace files, and key-value store entries.

Manage Kestra with the Kubernetes Operator

labels:
  system.readOnly: true

This feature requires the Enterprise Edition.

A Kubernetes operator is an application-specific controller that extends the functionality of the Kubernetes API to create, configure, and manage instances of applications or their components on behalf of a Kubernetes user. It is a custom Kubernetes controller that uses custom resources (CR).

To define and manage these components, operators leverage Custom Resource Definitions (CRDs). CRDs allow you to extend the Kubernetes API with new resource types that are specific to your application or service.

The Kestra Kubernetes Operator manages Kestra flows, namespace files, and key-value store entries as Kubernetes resources.

Installing the Kestra Kubernetes Operator

We provide a Helm chart to install Kestra in Kubernetes; see the installation guide. The Kestra Operator can be installed with the kestra-operator chart. To install the chart with the release name my-kestra-operator use:

$ helm repo add kestra https://helm.kestra.io/
$ helm install my-kestra-operator kestra/kestra-operator --version 1.0.0

This chart can also deploy the Kestra Kubernetes Operator in your cluster.

Because the operator calls the Kestra API, you must provide credentials — either a service account or an API token—if authentication is enabled.

To install the Kestra Kubernetes Operator inside your cluster, you need to configure the following properties in your Helm values:

operator:
  enabled: true
  apiKey: <your-kestra-api-token>

If you prefer to use a service account, please configure the following properties instead:

operator:
  enabled: true
  basicAuth: <username:password>

Then run helm install or helm upgrade to roll out the changes to your cluster.

If everything goes well, you will see a kestra-operator pod running.

kubectl get po
NAME                                 READY   STATUS    RESTARTS        AGE
kestra-operator-7d7bdbd846-pzpl2     1/1     Running   0               158m
kestra-postgresql-0                  1/1     Running   1 (2d23h ago)   3d
kestra-standalone-677474499f-4r5ft   1/1     Running   2 (5h10m ago)   2d23h

Managing multiple operators in one cluster

Each operator instance manages a single Kestra instance. If you run multiple Kestra deployments in the same Kubernetes cluster, deploy one operator per Kestra instance and scope each operator to the namespaces that will contain that instance’s custom resources.

Configure the namespace watch list via quarkus.operator-sdk.namespaces (Helm chart values) or the QUARKUS_OPERATOR_SDK_NAMESPACES environment variable. Example snippets:

quarkus:
  operator-sdk:
    namespaces:
      - kestra-dev
      - kestra-prod

kestraOperator:
  env:
    - name: QUARKUS_OPERATOR_SDK_NAMESPACES
      value: "kestra-dev,kestra-prod"

Deploying separate operator releases with different namespace lists ensures each instance reconciles only its own KestraFlow, KestraKeyValue, and KestraNamespaceFile resources.

Manage Kestra resources via the operator

The Kestra Kubernetes operator watches for three resource types in all namespaces:

• KestraFlow, shortname flow. To manage flows.
• KestraKeyValue, shortnames keyvalue or kv. To manage K/V store entries.
• KestraNamespaceFile, shortnames namespacefile or nsfile. To manage Namespace files.

Managing Flow resources

Here is an example flow resource that you can create in a hello-world.yml file:

apiVersion: model.kestra.io/v1alpha1
kind: KestraFlow
metadata:
  name: hello-world
spec:
  id: hello-world
  namespace: company.team # This is a Kestra namespace, not a Kubernetes namespace
  source: |
   id: hello-world
   namespace: company.team
   tasks:
   - id: hello
     type: io.kestra.core.tasks.log.Log

You can then use standard kubectl commands to create, update, list, and delete your flows:

## Create or update the flow
kubectl apply hello-world.yml

## List all flows
kubectl get flow

## Get the 'hello-world' flow
kubectl get flow hello-world

## Delete the 'hello-world' flow
kubectl delete flow hello-world

Managing K/V entry resources

Here is an example key-value entry resource that you can create in a kv-1.yml file:

apiVersion: model.kestra.io/v1alpha1
kind: KestraKeyValue
metadata:
  name: kv-1
spec:
  namespace: company.team # This is a Kestra namespace, not a Kubernetes namespace
  key: key1
  value: value1

Use the same kubectl workflow to create, update, list, and delete your entries:

## Create or update the k/v entry
kubectl apply kv-1.yml

## List all entries
kubectl get kv

## Get the 'kv-1' k/v entries
kubectl get kv kv-1

## Delete the 'kv-1' k/v entry
kubectl delete kv kv-1

Managing Namespace File resources

Here is an example namespace file resource that you can create in an nsfile-1.yml file:

apiVersion: model.kestra.io/v1alpha1
kind: KestraNamespaceFile
metadata:
  name: nsfile-1
spec:
  namespace: company.team # This is a Kestra namespace, not a Kubernetes namespace
  filename: nsfile-1.txt
  content: Hello World

You can then use the standard kubectl commands to create, update, list and delete your namespace files:

## Create or update the namespace file
kubectl apply nsfile-1.yml

## List all namespace files
kubectl get nsfile

## Get the 'nsfile-1' namespace file
kubectl get nsfile nsfile-1

## Delete the 'nsfile-1' namespace file
kubectl delete nsfile nsfile-1