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:
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
Talk to us!
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