Documentation · Blog · Report Bug · Request Feature
- YAML: Define flows and subflows with simple YAML including if/else switches, error handling, retries, validations and more.
- Serverless: Call multiple serverless functions from a flow and merge and modify the responses to a single consumable function call.
- Event-Based: Catch events within the system or from external sources like AWS or Github and execute flows based on that event.
- JSON Inputs & States: Use JSON as input for flows and respond with JSON to the caller. JSON will be saved between the states fo a flow.
- API Gateway: Includes an API gateway to expose flows as services for third-party consumers including authentication.
- CloudEvents: Supports CNCF's CloudEvents natively.
- GitOps Approach: All configurations, services and flows can be synced from Git. Git becomes the single source of truth.
- Observability: Integrated into Fluent Bit (logging) & OpenTelemetry (instrumentation & tracing).
- Periodic Tasks: Call flows periodically via cron jobs for repeating tasks.
- Scalable: Direktiv scales on mulitple levels with Kubernetes scaling and Knative's scaling features.
- Easily Extendable: Add custom functions with simple Docker containers.
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-kubeIf 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.
- The direktiv.io website.
- The direktiv documentation.
- The direktiv blog.
- The Godoc library documentation.