Skip to main content

Overview

Resource Plugins are responsible for creating and deleting Resources. Resource Plugins are installed using the Signadot CLI and are invoked during the creation and deletion of sandboxes that reference them.

Components of a Resource Plugin​

The specification of a resource plugin is as shown here. There are specific sections that are explained below in more detail.

The Resource Plugin defines containerized workflows, each containing one or more steps. The pod that runs these steps is referred to as the runner. The business logic of each step is defined in the script field. The script may reference inputs from other steps, or from the sandbox specification, and write outputs to files and make them available to other steps or a sandbox.

The plugin's steps are only run when a sandbox referencing that resource plugin is created or deleted. When such a sandbox is created, the Signadot Operator will create and run each step within a new Kubernetes pod in the cluster where the sandbox is deployed. The runner pod's specification can be modified in the resource plugin specification by altering the runner. Before the sandboxed workloads are created, all steps of the create workflow must be completed. Later, when that sandbox is requested to be deleted, the delete workflow steps are invoked and complete before the sandbox is deleted.

note

The ordering of execution of the steps is defined implicitly in terms of the input / output relationships between them.

Runner​

The runner is defined in the specification in terms of an image, an optional namespace and an optional podTemplateOverlay.

If only the image is specified, it will be incorporated into a default pod template and used to run each step. Typically, the script specified in each step will make use of the utilites that the image contains. For example, if the script is invoking terraform, we would want to run that on an image that contains the desired version of the terraform binary. The runner will be created in the namespace specified when the resource plugin is invoked.

In some cases, there are secrets, credentials, or configuration in Kubernetes that are required for the runner pod to be able to perform its tasks. In these cases, you can make use of the optional podTemplateOverlay to customize the runner to add environment variables, secrets, etc. Note that if you are referencing any additional Kubernetes objects from the podTemplateOverlay, they must be created directly within the Kubernetes cluster where the plugin is intended to be used.

Workflows​

The create and delete workflows in a ResourcePlugin contain one or more steps. Each step is run in the runner independently, and any parameter passing between steps, or between the sandbox and a step must be done explicitly in the specification.

spec:
  runner:
    ...
  create:
    # steps
  delete:
    # steps

Inputs​

Any step may have one or more inputs. The input may be obtained from a sandbox specification, or from another step. The steps may run in parallel if they don't have dependencies on one another. The inputs once acquired can be set on the runner in two different ways - using environment variables, or using files. Once set, the environment variables or files can be referenced by the script in that particular step in order to perform its actions.

spec:
  runner:
    ...
  create:
    - name: hello
      inputs:
      - name: ...
        valueFromSandbox: true
        as:
          env: ENV_VAR_NAME
          path: /path/to/file
      ...

      script: |
        #!/usr/bin/env bash
         echo $ENV_VAR_NAME
        ...

The script may read inputs from sandboxes to perform custom behaviors. There are also some default environment variables (SIGNADOT_SANDBOX_NAME, SIGNADOT_SANDBOX_ROUTING_KEY, SIGNADOT_RESOURCE_NAME) [^1] that are set on the runner that can be used to infer which sandbox creation / deletion event it is being invoked for, as well as what the name of the instance of the resource is, as in the sandbox specification.

Script​

The script is an executable file with a #! line on top that must specify the interpreter. Commonly, bash or python scripts may be used. This executable will be placed into a newly created runner pod when each step is invoked, and then run using the interpreter specified.

Outputs​

Any step may contain one or more outputs. Outputs are typically obtained from files that are written once a step is executed within a runner.

spec:
  runner:
    ...
  create:
    - name: hello

      script: |
        #!/usr/bin/env bash
        echo 1 > /path/to/my-output
        ...

      outputs:
      - name: my-output
        valueFromPath: /path/to/my-output
        ...

The outputs are referenceable by name, by other steps, or by a sandbox as an environment variable as shown in sandbox resources.

Next Steps​

You can see how a Sandbox can use a resource plugin in resources usage. To see some examples of this, refer to https://github.com/signadot/examples/blob/main/cli/sandbox-resource.yaml.

If you're looking to create your own resource plugin, you can start from one of the example resource plugins.

Notes​

  • [^1] Prior to operator v0.15.0, the now-deprecated variable name $SIGNADOT_SANDBOX_ID was used in place of $SIGNADOT_SANDBOX_ROUTING_KEY. $SIGNADOT_SANDBOX_ID will be removed as a meta variable in a future version.