direktiv

README

direktiv

event-based serverless container workflows

---

Check out our online demo: wf.direktiv.io

What is Direktiv?

Direktiv is a specification for a serverless computing workflow language that aims to be simple and powerful above all else.

Direktiv defines a selection of intentionally primitive states, which can be strung together to create workflows as simple or complex as the author requires. The powerful jq JSON processor allows authors to implement sophisticated control flow logic, and when combined with the ability to run containers as part of Direktiv workflows just about any logic can be implemented.

Workflows can be triggered by CloudEvents for event-based solutions, can use cron scheduling to handle periodic tasks, and can be scripted using the APIs for everything else.

Why use Direktiv?

Direktiv was created to address 4 problems faced with workflow engines in general:

• Cloud agnostic: we wanted Direktiv to run on any platform or cloud, support any code or capability and NOT be dependent on the cloud provider's services for running the workflow or executing the actions (but obviously support it all)
• 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 of your workflows. We wanted to ensure that your code always remains reusable and portable and not tied into a specific vendor format or requirement (or vendor specific language) - so we've modelled Direktiv's specification after the CNCF Serverless Workflow Specification with the ultimate goal to make it feature-complete and easy to implement.
• Multi-tenanted and secure: we want to use Direktiv in a multi-tenant service provider space, which means all workflow executions have to be isolated, data access secured and isolated and all workflows and actions are truly ephemeral (or serverless).

Direktiv internals?

This repository contains a reference implementation that runs Docker containers as isolated virtual machines on Firecracker using Vorteil.io.

Quickstart

Starting the Server

Getting a local playground environment can be easily done with either Vorteil.io or Docker. Direktiv's defaul isolation level is firecracker based on vorteil machines. This behaviour can be changed in the configuration file or via environment variable.

---

Using Docker:

Firecracker Isolation

docker run --privileged -p6666:6666 -eDIREKTIV_INGRESS_BIND=0.0.0.0:6666 vorteil/direktiv

Container Isolation:

docker run --privileged -p6666:6666 -eDIREKTIV_INGRESS_BIND=0.0.0.0:6666 -eDIREKTIV_ISOLATION=container vorteil/direktiv

*Note: *

• You may need to run this command as an administrator.

• In a public cloud instance, nested virualization is needed to support the firecracker micro-VMs. Each public cloud provider has different configuration settings which need to be applied to enable nested virtualization. Examples are shown below for each public cloud provider:

  • Google Cloud Platform
  • Amazon Web Services (only supported on bare metal instances)
  • Microsoft Azure
  • Alibaba (only supported on bare metal instances)
  • Oracle Cloud
  • VMware

Using Vorteil:

With Vorteil installed (full instructions here):

1. download direktiv.vorteil from the releases page,
2. run one of the following commands from within your downloads folder:

vorteil run direktiv.vorteil for firecracker/vorteil isolation

vorteil run --program[2].env="DIREKTIV_ISOLATION=container" direktiv.vorteil for container isolation

Testing Direktiv:

Download the direkcli command-line tool from the releases page and create your first namespace by running:

direkcli namespaces create demo

$ direkcli namespaces create demo
Created namespace: demo
$ direkcli namespaces list
+------+
| NAME |
+------+
| demo |
+------+

Workflow specification

The below example is the minimal configuration needed for a workflow, following the workflow language specification:

id: helloworld
states:
- id: hello
  type: noop
  transform: '{ msg: ("Hello, " + .name + "!") }'

Creating and Running a 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.

$ direkcli namespaces create demo
Created namespace: demo
$ cat > helloworld.yml <<- EOF
id: helloworld
states:
- id: hello
  type: noop
  transform: '{ msg: ("Hello, " + .name + "!") }'
EOF
$ direkcli workflows create demo helloworld.yml
Created workflow 'helloworld'
$ cat > input.json <<- EOF
{
  "name": "Alan"
}
EOF
$ direkcli workflows execute demo helloworld --input=input.json
Successfully invoked, Instance ID: demo/helloworld/aqMeFX <---CHANGE_THIS_TO_YOUR_VALUE
$ direkcli instances get demo/helloworld/aqMeFX
ID: demo/helloworld/aqMeFX
Input: {
  "name": "Alan"
}
Output: {"msg":"Hello, Alan!"}

Roadmap

• Installation instructions (Kubernetes, Non-Kubernetes environments, Container/Vorteil setting)
• Providing individual vorteil / docker containers for individual components (workflow, isolates etc.)
• HTTP API & Simple UI
• Service Mesh configuration

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 vorteil.io repository.
• The Direktiv documentation.
• The Direktiv Beta UI.
• The Godoc library documentation.