direktiv

README

direktiv

event-driven serverless orchestration

---

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:

• Pre-built plugins are available from https://github.com/vorteil/direktiv-apps - we're working hard to add more every day!
• Examples for integration your own containers https://github.com/vorteil/direktiv-apps/tree/main/examples with an explanation here.

Dashboard	Flow Builder
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).

Quickstart

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 vorteil/direktiv-kube

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
states:
- id: hello
  type: noop
  transform:
    msg: "Hello, jq(.name)!"
EOF
$ 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"
}
EOF
$ 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 vorteil/request container in https://hub.docker.com/r/vorteil/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
functions:
  - type: reusable
    id: get-request
    image: vorteil/request:latest
states:
  - id: get-bitcoin
    type: action
    log: jq(.)
    action:
      function: get-request
      input:
        method: "GET"
        url: "https://blockchain.info/ticker"
      retries:
        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)"
EOF
$ 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"
{
  "value":62988.71
}

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

Documentation

• Getting Started
• Workflow Specification
• Examples

Talk to us!

• Open Source Support Channel on Slack
• Open Source Support Channel on Discord

Code of Conduct

We have adopted the Contributor Covenant code of conduct.

Contributing

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

License

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

See Also

• The direktiv.io website.
• The direktiv documentation.
• The direktiv blog.
• The Godoc library documentation.