direktiv

README

Event-Driven Serverless Orchestration, Integration and Automation

Run Workflows and Create Services in Seconds

Documentation · Blog · Report Bug · Request Feature

Features & Standards

• 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 Prometheus (metrics), 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.

Quick Start

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.

About Direktiv

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

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.

Custom Functions

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
}

Documentation

• Getting Started
• Workflow Specification
• Examples

Talk to us!

• Open Source Support Channel on Slack

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.