Skip to main content

Specification

Overview​

This document provides a reference for a ResourcePlugin specification.

Purpose​

A ResourcePlugin is an entity used to attach external resources, such as databases, to sandboxes. When a sandbox is created it may define resources to be made available for the sandbox, using a resource plugin. For example, a sandbox spec may contain the following:

spec:
  resource:
  - name: testdb
    plugin: mariadb
    params:
    - dbname: test

In this case, a ResourcePlugin named mariadb is expected to provide a database named test for the associated Sandbox.

Concepts​

ResourcePlugins define 2 phases called create and delete. Each phase is a workflow which in turn is a sequence of steps. Data can flow between the steps, from a sandbox resource declaration to a step, and from a step to runtime sandboxed workloads. The rest of this document discusses the format of a ResourcePlugin specification in detail using these concepts.

Format​

A ResourcePlugin specification can be expressed in json or yaml formats, as structured data. Here is an example:

name: hello-db
spec:
  description: say hello and goodbye
  runner:
    image: ubuntu
  create:
  - name: say-hello
    inputs:
    - name: dbname
      valueFromSandbox: true
      as:
        env: DBNAME
    script: |
      #!/usr/bin/env bash
      echo hello $DBNAME
  delete:
  - name: say-goodbye
    script: |
    #!/usr/bin/env bash
    echo goodbye

Update constraints​

A ResourcePlugin may be not be updated. Moreover, a ResourcePlugin cannot be deleted unless there are no sandboxes which refer to it.

name​

The name is a string used to identify the ResourcePlugin. The name must be unique amongst all ResourcePlugins associated with the Signadot organisation.

A name must match the regular expression [a-zA-Z0-9-]*[a-zA-Z0-9]?$, begin with an letter (^[a-zA-Z]), and end with an alphanumeric ([a-zA-Z0-9]$).
A name may be no longer than 253 bytes in length.

The name is required.

spec​

spec.description​

The ResourcePlugin description is an optional string providing a short summary of what it is used for. The description must not exceed 255 bytes.

spec.runner​

The runner specifies how the plugin phases are executed, namely the image, namespace, and pod template overlay.

The runner is required.

spec.runner.image​

The image must specify a valid docker reference to an image and is required.

spec.runner.namespace​

The namespace specifies the namespace in which the plugin phases are executed. It is optional and when unspecified defaults to the default namespace.

spec.runner.podTemplateOverlay​

The podTemplateOverlay provides an optional string representation of a base pod template spec on which the plugin phases are executed.

This spec is used as a basis on which a Pod is created, by appending an init container, adding a sidecar, and rewriting the main container command to implement the steps specified under the create and delete phases (specified below).

A podTemplateOverlay can be useful for specifying a service account, secret mounts, resource limits, and other runtime configuration.

A podTemplateOverlay must meet the following constraints:

  • If restartPolicy is specified, it must be "Never".
  • If an image or namespace is specified, it must not conflict with spec.runner.image or spec.runner.namespace.
  • If an init container is specified, it must not be named signadot-execunit-input-manager.
  • No container may be named signadot-execunit-output-manager.
  • Finally, the name must be not specified or empty; the name will be determined by the Signadot Operator.

spec.{create,delete} (phase workflow)​

create and delete represent plugin phase workflows to execute. Each phase defines a workflow as a sequence of steps, represented as an array.

The create phase workflow is executed during sandbox startup, before sandboxed workloads are spun up. The delete phase workflow is executed during Sandbox termination, after sandboxed workloads have terminated.

The scheduling of each workflow is determined by dependencies between steps. If a step a consumes output of a step b, then a will run after b has completed. Otherwise, steps are scheduled to run in Kubernetes in parallel.

Workflows must contain at least one step.

Outputs from delete phase workflows cannot be inputs to ResourcePlugin steps in create phase workflows, and I/O cycles are forbidden.

spec.{create,delete}[_] (step)​

A step defines a unit of work to be scheduled, including its inputs and outputs. Each step is run with the resource plugin runner in spec.runner. First, inputs are injected into the main container. Then, the main container process runs to termination, running the script specified in the step. If the main container sucessfully terminates, then the outputs are exported for consumption by any step or sandbox workload which may consume it.

A step is fully described here.