Serverless Container Orchestration
APACHE-2.0 License
Direktiv provides a Docker container with all required components pre-installed (Linux only). The initial startup can take a couple of minutes to download all required images.
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 with the command
sudo sysctl fs.inotify.max_user_instances=4096
If you are not using Linux please follow the installation instructions on the documentation page.
Direktiv is an event-driven workflow engine made for orchestration, integration, and automation. In it's core it is a state machine which uses containers as functions within workflows and passes JSON structured data between states. It offers key features like retries, error handling, and conditional logic. The flow's state, stored as JSON, allows for dynamic transformations during execution using JQ or JavaScript.
direktiv_api: workflow/v1
states:
- id: start
type: noop
transform:
result: Hello world!
transition: second
- id: second
type: noop
log: second state
transform:
final: this value is from state one jq(.result)
Workflows can be triggered by events, start periodically via crons or can be started by a HTTP POST request where the data is the initial state fo the workflow.
Writing workflows is a very simple task. The basic idea is that there are multiple states where the workflow steps through. These states are of different types to provide switches, errors or other functionality. The most important type is the action
state. This state calls a function which is basically a simple container.
Writing workflows is quite simple. Essentially, a workflow is progressing through different states with a JSOJ payload passed between those states. These states come in various types, providing switches, error management, and more. The most important type is the action
state. The action
state is basically a call to a container. Internally Direktiv spins up a serverless Knative function and passes data to that container. The response of that call becomes part of the JSON state of the flow.
direktiv_api: workflow/v1
functions:
- id: request
image: gcr.io/direktiv/functions/http-request:1.0
type: knative-workflow
states:
- id: joke
type: action
action:
function: request
input:
method: GET
url: https://api.chucknorris.io/jokes/random?category=jq(.category // "dev")
transform:
joke: jq(.return[0].result.value)
The above example is a very simple one-step workflow. It uses the http-request
function. This function accepts multiple input parameters e.g. the HTTP method or the URL. The section under input
defines the data send to the function as JSON. In this case Direktiv would post the following payload to the container:
{
"method": "GET",
"url": "https://api.chucknorris.io/jokes/random?category=dev"
}
In this example, there's a JQ statement, jq(.category // "dev")
, which is getting evaluated at runtime. If the 'category' value is defined in the state, it's utilized in the URL; otherwise, dev
is used as the default. For instance, initiating the workflow with a payload like { "category": "animal" }
would result in the URL: https://api.chucknorris.io/jokes/random?category=animal
.
The state can be transformed after each state of the workflow. In this case the JQ command fetches the joke from the return values of the function and sets it as new state.
Although every standard container can be used in Direktiv it is easy to write a custom function if necessary. The basic requirement for a custom function is a container listening to port 8080
and accepting JSON as a payload. There is more information about writing custom functions in the documentation but the following code snippet shows a very simple Rust example of a a custom function.
use actix_web::{App, HttpResponse, HttpServer, Responder, post};
use actix_web::web::Json;
use serde::{Deserialize, Serialize};
#[derive(Deserialize)]
struct Input {
name: String,
}
#[derive(Serialize)]
struct Output {
greeting: String,
}
#[post("/")]
async fn index(info: Json<Input>) -> impl Responder {
HttpResponse::Ok().json(Output { greeting: format!("Welcome to Direktiv, {}!", info.name) })
}
#[actix_rt::main]
async fn main() -> std::io::Result<()> {
HttpServer::new(|| {
App::new()
.service(index)
})
.bind("0.0.0.0:8080")?
.run()
.await
}
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.