Sandbox Resources Reference

Working Example

For a full working code example covering all the concepts described below, see https://github.com/signadot/examples.

Resources are ephemeral entities whose lifecycle is managed as part of a sandbox. Resources are typically used to isolate sandbox environments when there are stateful components involved like databases and message queues. A resource does not necessarily represent physical infrastructure. For example:

• A resource can represent an ephemeral MySQL StatefulSet within your Kubernetes cluster
• A resource can represent an ephemeral schema within an Amazon RDS cluster
• A resource can represent an ephemeral topic within RabbitMQ / Kafka.

As a user of resources, there is a high level interface provided via the Signadot APIs that can be used to both request resources and associate them with forked workloads running within your sandbox.

Creating and Deleting Resources

Resource creation and deletion is managed by a Resource Plugin. Each resource plugin can be thought of as a piece of infrastructure that is responsible for managing that specific type of resource. Resource Plugins are installed using the signadot CLI.

Once a resource plugin is installed, it can be referenced by a sandbox during creation. When this is done, the create workflow of the resource plugin is invoked to stand up the resource. When the sandbox is deleted, the corresponding delete workflow is called that in turn destroys the ephemeral resource that was created.

Usage

For example, a sandbox that requests a maria-db resource in order to set up an isolated dependency for a customer microservice is shown below. In this cluster, it is assumed that there is a Resource Plugin called hotrod-mariadb installed which will be used to provision and deprovision the maria-db resource.

# customer-sandbox.yaml
# usage: signadot sandbox apply -f customer-sandbox.yaml
name: customer
spec:
  cluster: ...
  resources:
  - name: customerdb
    plugin: hotrod-mariadb
    params:
      dbname: customer
  forks:
    forkOf:
      kind: Deployment
      namespace: hotrod
      name: customer
    customizations:
      env:
      - name: MYSQL_HOST  # set MYSQL_HOST to that provided by the plugin
        valueFrom:
          resource:
            name: customerdb
            outputKey: provision.host
      - name: MYSQL_PORT
        valueFrom:
          resource:
            name: provision.customerdb
            outputKey: port
      - name: MYSQL_ROOT_PASSWORD
        valueFrom:
          resource:
            name: customerdb
            outputKey: provision.root-password

There are some input parameters that the Resource Plugin's provision workflow takes in order to set up the ephemeral resource. In the above case, the resource request is specified in the call to create a sandbox which specifies that the hotrod-mariadb plugin must be used, and passes the input parameter dbname with value customer to it.

Pinning a plugin version

Resource plugins are versioned with semver. The plugin field accepts an optional @<semver> suffix to pin a specific version:

resources:
- name: customerdb
  plugin: hotrod-mariadb@1.2.0
  params:
    dbname: customer

Without an @semver suffix, the sandbox resolves the plugin reference at sandbox-creation time to the highest-semver published version of hotrod-mariadb and pins the sandbox to that revision. @latest is accepted as an explicit alias for the bare form. The resolved version is then rendered explicitly back into the spec — sandbox get -o yaml on a sandbox that was created with plugin: hotrod-mariadb returns plugin: hotrod-mariadb@1.2.0 (whichever version actually got pinned), so the sandbox's binding is self-evident from the spec without re-running the resolver:

User input	Persisted in the spec (as returned by sandbox get)
plugin: hotrod-mariadb	plugin: hotrod-mariadb@<resolved-semver>
plugin: hotrod-mariadb@latest	plugin: hotrod-mariadb@<resolved-semver>
plugin: hotrod-mariadb@1.2.0	plugin: hotrod-mariadb@1.2.0

Subsequent applies of the round-tripped spec are no-ops — the now-explicit @semver is validated and pinned exactly like any other concrete reference.

note

The bare form means "highest-semver published version, resolve now and pin," not "the default 0.0.0." If the referenced plugin has been bumped past 0.0.0, a bare reference will pin to the newest concrete version, not to the default slot. To reference the default version once newer versions exist, pin explicitly with plugin: hotrod-mariadb@0.0.0.

This is the inverse of the resource-plugin name field, where the bare form does mean the default version 0.0.0 — each form is the easy choice in its own context (an unversioned author publishes plainly; an unversioned consumer just gets whatever's newest).

Once the ephemeral resource has been set up, the "outputs" are typically things like the credentials required to access that resource. These outputs are available as special environment variables that can be supplied to any of the forks within the Sandbox as shown above. By making use of these credentials, the workload within the sandbox can connect to the isolated ephemeral resource in place of a shared entity that may be in the baseline environment. The inputs and outputs associated with each Resource Plugin are specific to them and typically documented in the description of the plugin that is available via the Signadot Dashboard.