Version: v0.7.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Oct 16, 2022 License: Apache-2.0




event-driven serverless orchestration

Build Go Report Card Slack

What is direktiv?

Direktiv is an event-driven container orchestration engine, running on Kubernetes and Knative. The following key concepts:

  • direktiv runs containers as part of workflows from any compliant container registry, passing JSON structured data between workflow states.
  • JSON structured data is passed to the containers using HTTP protocol on port 8080.
  • direktiv uses a primitive state declaration specification to describe the flow of the orchestration in YAML, or users can build the workflow using the workflow builder UI.
  • direktiv uses jq JSON processor to implement sophisticated control flow logic and data manipulation through states.
  • Workflows can be event-based triggers (Knative Eventing & CloudEvents), cron scheduling to handle periodic tasks, or can be scripted using the APIs.
  • Integrated into Prometheus (metrics), Fluent Bit (logging) & OpenTelemetry (instrumentation & tracing).

Additional resources to get started:

direktiv uidirektiv uidirektiv uidirektiv ui
Knative Services Orchestration Flow
YAML definition OpenTelemetry Integration

Why use direktiv?

  • Cloud agnostic: direktiv runs on any platform, supports any code and is not dependent on cloud provider's services for running workflows or executing actions
  • Simplicity: the configuration of the workflow components should be simple more than anything else. Using only YAML and jq you should be able to express all workflow states, transitions, evaluations, and actions needed to complete the workflow
  • Reusable: if you're going to the effort and trouble of pushing all your microservices, code or application components into a container platform why not have the ability to reuse and standardise this code across all your workflows? We wanted to ensure that code always remains reusable and portable without the need for SDKs (or vendor specific language).


Running a local direktiv instance (docker)

Getting a local playground environment can be easily done with Docker. The following command starts a docker container with kubernetes. On startup it can take a few minutes to download all images. When the installation is done all pods should show "Running" or "Completed".

docker run --privileged -p 8080:80 -ti direktiv/direktiv-kube

If the upper limit for inotify instances is too low the pods might be stuck in pending. Increase that limit if necessary:

sudo sysctl fs.inotify.max_user_instances=4096

Testing Installation:

Browse the UI: http://localhost:8080

... or ...

verify direktiv is online manually from the command-line using cURL:

$ curl -vv -X PUT "http://localhost:8080/api/namespaces/demo"
  "namespace": {
    "createdAt": "2021-10-06T00:03:22.444884147Z",
    "updatedAt": "2021-10-06T00:03:22.444884447Z",
    "name": "demo",
    "oid": ""

Kubernetes Install

For full instructions on how to install direktiv on a Kubernetes environment go to the installation pages

Creating your first workflow

The following script does everything required to run the first workflow. This includes creating a namespace & workflow and running the workflow the first time.

$ curl -X PUT "http://localhost:8080/api/namespaces/demo"
  "namespace": {
    "createdAt": "2021-10-06T00:03:22.444884147Z",
    "updatedAt": "2021-10-06T00:03:22.444884447Z",
    "name": "demo",
    "oid": ""
$ cat > helloworld.yml <<- EOF
- id: hello
  type: noop
    msg: "Hello, jq(.name)!"
$ curl -vv -X PUT --data-binary "@helloworld.yml" "http://localhost:8080/api/namespaces/demo/tree/helloworld?op=create-workflow"
  "namespace": "demo",
  "node": {...},
  "revision": {...}
$ cat > input.json <<- EOF
  "name": "Alan"
$ curl -vv -X POST --data-binary "@input.json" "http://localhost:8080/api/namespaces/demo/tree/helloworld?op=wait"
{"msg":"Hello, Alan!"}

Running a container workflow

The next example uses the direktiv/request container in https://hub.docker.com/r/direktiv/request. The container starts a HTTP listener on port 8080 and accepts as input a JSON object containing all the parameters for a HTTP(S) request. It returns the result to the workflow on the same listener. This is the template for how all containers run as part of workflow execution.

$ cat > bitcoin.yaml <<- EOF
  - type: reusable
    id: get-request
    image: direktiv/request:latest
  - id: get-bitcoin
    type: action
    log: jq(.)
      function: get-request
        method: "GET"
        url: "https://blockchain.info/ticker"
        max_attempts: 3
        delay: PT30S
        multiplier: 2.0
        codes: [".*"]
    transform: "jq({ value: .return.body.USD.last })"
    transition: print-bitcoin
  - id: print-bitcoin
    type: noop
    log: "BTC value: jq(.value)"
$ curl -vv -X PUT --data-binary "@bitcoin.yaml" "http://localhost:8080/api/namespaces/demo/tree/get-bitcoin?op=create-workflow"
  "namespace":  "demo",
  "node":  {... },
  "revision":  {...}
$ curl -X POST  "http://localhost:8080/api/namespaces/demo/tree/get-bitcoin?op=wait"

The UI displays the log output and state of the workflow from start to completion.

direktiv ui


Talk to us!

Code of Conduct

We have adopted the Contributor Covenant code of conduct.


Any feedback and contributions are welcome. Read our contributing guidelines for details.


Distributed under the Apache 2.0 License. See LICENSE for more information.

See Also


Path Synopsis
Package classification Direktiv API
Package classification Direktiv API
Package states implements the logic for Direktiv workflow states.
Package states implements the logic for Direktiv workflow states.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL