Drivers/Workflow Handlers

A Driver (aka Workflow Handler) is a foundational component for creating custom infrastructure provisioners and workflows that may be challenging to achieve using Terraform/OpenTofu or similar IaC frameworks. It also enables the use of custom images with specific versions of Terraform/OpenTofu, along with the required tools and libraries for building and managing environments.

Drivers can be utilized in the following scenarios:

As a Provider: To support resource templates in creating custom infrastructure provisioners
As Pre- or Post-Hook Handlers: To manage workflows triggered before or after specific actions
As a Cron Job/Scheduled Job Handler: To automate recurring tasks
As an Action Workflow Handler: To execute defined actions within workflows.

The platform supports three types of drivers:

Container
HTTP
Function

Note: Drivers can be defined inline within Environment and Resource templates.

Container¶

The Container driver is designed to run container images to completion. A container image, in this context, is a self-contained executable package that includes everything needed to run an application—such as code, runtime, libraries, and system tools. The Container driver is deployed as a pod in the cluster, managed by the `cd-agent`.

To configure this container driver, users can specify details such as:

CPU and memory limits
Arguments and commands
Environment variables
Files

The Container driver within the workflow engine allows users to define activities that run specific containerized tasks or processes as essential components of the workflow.

Sample Container driver spec

apiVersion: eaas.envmgmt.io/v1
kind: Driver
metadata:
  name: custom-driver
  project: defaultproject
spec:
  config:
    container:
      cpuLimitMilli: "1024"
      image: registry.dev.rafay-edge.net/rafay/custom-driver/fm-tf-custom:v4
      kubeOptions:
        namespace: rafay-system
        serviceAccountName: fmac1
      memoryLimitMb: "512"
    type: container
status: {}

Setting	Description
apiVersion	Rafay’s API version `eaas.envmgmt.io/v1`.
Kind	`Driver`.
metadata	- name: Name of the driver. - project: Project where the driver resides.
spec -> config	Configuration for the driver. The type should be `container`.
spec -> config -> container	- image (String): Specify the container image for the driver. Optional Fields: - arguments (List of String): Set of arguments to pass. - commands (List of String): Commands to execute.
	- cpu_limit_milli (String): CPU limit in milli. - env_vars (Map of String): Environment variables as key-value pairs. - files (Map of String): Specify file data.
	- image_pull_credentials (Block List, Max: 1): Credentials for pulling images from a private registry. - kube_options (Block List): Cluster-specific Kubernetes options.
	- memory_limit_mb (String): Memory limit in MB. - volumes (Block List): Configure container volumes. - working_dir_path (String): Specify the working directory.
Nested Schema: image_pull_credentials	- Required Fields: - password (String): Registry password. - registry (String): Container image registry. - username (String): Registry username.
Nested Schema: kube_config_options	- Optional Fields: - kube_config (String): Specify the Kubernetes config if `out_of_cluster` is enabled. - out_of_cluster (Boolean): Indicates if out-of-cluster.
Nested Schema: kube_options	- Optional Fields: - labels (Map of String): Labels for the resources. - namespace (String): Specify the namespace. - node_selector (Map of String): Node selectors. - security_context (Block List, Max: 1): Security context configuration. - service_account_name (String): Service account name. - tolerations (Block List): Tolerations.
Nested Schema: kube_options.tolerations	- Optional Fields: - key (String): Toleration key. - operator (String): `Exists` or `Equal`. - value (String): Toleration value. - effect (String): Effect of the toleration (`NoSchedule`, `PreferNoSchedule`, `NoExecute`). - toleration_seconds (Number): Duration for `NoExecute` effect.
Nested Schema: kube_options.security_context	- Optional Fields: - privileged (Block List, Max: 1): Enable privileged permissions. - read_only_root_file_system (Block List, Max: 1): Read-only root file system.
Nested Schema: volume_options	- Optional Fields: - mount_path (String): Container mount path. - pvc_size_gb (String): Persistent volume claim size in GB. - pvc_storage_class (String): PVC storage class. - use_pvc (Block List, Max: 1): Use persistent volume claims.
Nested Schema: working_dir_path.use_pvc	- Optional Field: - value (Boolean): Enable persistent volume claim for the working directory.

HTTP¶

The HTTP driver enables the workflow engine to perform HTTP requests, allowing users to define activities within the workflow that interact with external services or APIs. These activities can be used to trigger actions, retrieve data, or communicate with other systems. The HTTP driver facilitates seamless integration between the workflow engine and external services using the HTTP protocol.

Sample HTTP driver spec

apiVersion: eaas.envmgmt.io/v1
kind: Driver
metadata:
  description: This is a HTTP driver
  name: sp-http
  project: demoproject
spec:
  config:
    http:
      body: |-
        <body>
        <h1>This is a heading</h1>
        <p>This is a paragraph.</p>
        </body>
      endpoint: https://httpbin.org
      headers:
        Content-type: application/json
        X-TOKEN: 1234
      method: GET
    maxRetryCount: 2
    successCondition: |-
      if #status.http.statusCode == 200 {
        success: true
      }
      if #status.http.statusCode != 200 {
        failed: true
        reason: "url not reachable"
      }
    timeoutSeconds: 60
    type: http
  sharing:
    enabled: true
    projects:
    - name: project1
    - name: project2

Setting	Description
apiVersion	Rafay’s API version `eaas.envmgmt.io/v1`.
Kind	`Driver`.
metadata	- name: Name of the driver. - project: Project where the driver resides.
spec -> config	Configuration type should be `http`.
spec -> config -> http -> body	This is the payload to pass to the HTTP call.
spec -> config -> http -> method	Set the HTTP method here.
spec -> config -> http -> endpoint	Set the HTTP endpoint URL to call.
spec -> config -> http -> headers	Set the HTTP headers here.
spec -> config -> http -> successCondition	Logic to indicate success or failure with a reason. Example: if #status.http.statusCode == 200 { success: true } if #status.http.statusCode != 200 { failed: true failed: true reason: "url not reachable" }
spec -> config -> http -> maxRetryCount	Retry count setting on failure.
spec -> config -> http -> timeoutSeconds	Timeout in seconds after which the run is declared as failed, and no more retries are attempted.

Functions¶

The Function Driver simplifies running functions written in popular programming languages like Go and Python directly within workflows. It eliminates the need to package these functions into containers, as the framework automatically handles packaging and dependency management, streamlining the process.

This feature can be used for tasks such as:

Executing actions on infrastructure
Integrating with services like Jira and ServiceNow
Sending notifications

By enabling functions to run without containers, the Function Driver reduces complexity and accelerates the implementation of actions. Note that the function signature for each supported programming language is predefined and cannot be modified.

For example, the function signature for python is

def handle(logger: Logger,request: Dict\[str, Any\]) \-\> Dict\[str, Any\]

The function signature for go is

type Handler func(ctx context.Context, logger Logger, req Request) (Response, error) |

Sample Function driver spec

apiVersion: eaas.envmgmt.io/v1
kind: Driver
metadata:
  name: simple-func-go
  project: defaultproject
spec:
  config:
    type: function
    timeoutSeconds: 300
    pollingConfig:
      repeat: "15s"
      until: "1h"
    function:
      cpuLimitMilli: "50"
      memoryLimitMi: "128"
      language: go
      languageVersion: "1.22"
      maxConcurrency: 10
      numReplicas: 1
      source: |
        package function

        import (
          "context"

          sdk "github.com/RafaySystems/function-templates/sdk/go"
        )

        func Handle(ctx context.Context, logger sdk.Logger, req sdk.Request) (sdk.Response, error) {
          logger.Info("received request", "req", req)

          counter := 0.0
          if prev, ok := req["previous"]; ok {
            logger.Info("previous request", "prev", prev)
            counter = prev.(map[string]any)["counter"].(float64)
          }

          resp := make(sdk.Response)
          resp["output"] = "Hello World"
          resp["request"] = req

          if err, ok := req["error"]; ok {
            errString, _ := err.(string)
            switch errString {
            case "execute_again":
              if counter > 1 {
                break
              }
              return nil, sdk.NewErrExecuteAgain(errString, map[string]any{
                "rkey":    "rvalue",
                "counter": counter + 1,
              })
            case "transient":
              return nil, sdk.NewErrTransient(errString)
            default:
              return nil, sdk.NewErrFailed(errString)
            }
          }

          return sdk.Response(resp), nil
        }

Setting	Description
apiVersion	Rafay’s API version `eaas.envmgmt.io/v1`.
Kind	`Driver`.
metadata	- name: Name of the driver. - project: Project where the driver resides.
spec -> config	Configuration type should be `function`.
spec -> config -> timeoutSeconds	Timeout in seconds. For example: `300` (indicates a single run should complete in 5 minutes; otherwise, it is declared as a timeout). pollingConfig - repeat: `"15s"` (indicates the function should poll every 15 seconds). - until: `"1h"` (indicates the function should run for up to 1 hour).
spec -> config -> function	Defines the function properties: - cpuLimitMilli: `"50"` (indicates the CPU limit in milli for the container platform running the function). - memoryLimitMi: `"128"` (indicates memory limit in MiB). - language: `go` (supports only `go` or `python`). - languageVersion: `"1.22"`. - maxConcurrency: `10` (maximum concurrent requests per function instance). - numReplicas: `1` (number of function container replicas). - source: Inline code for the function.