Skip to main content

Using Resources with Sandboxes

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 environment. 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.

Provisioning and Deprovisioning Resources

Resource provisioning and deprovisioning 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 directly onto the Kubernetes cluster using a Kubernetes CustomResource. Once a resource plugin is installed on the cluster, it can be referenced by a sandbox during creation. When this is done, the provision workflow of the resource plugin is invoked to stand up the resource. When the sandbox is deleted, the corresponding deprovision 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.

// see working example in https://github.com/signadot/examples/blob/main/java-sdk-example/src/test/java/ResourcesTest.java

SandboxFork customerServiceFork = new SandboxFork()
.forkOf(new ForkOf().kind("Deployment").namespace("hotrod").name("customer"))
.customizations(new SandboxCustomizations()
.addImagesItem(...)

// Dynamic env vars are derived from the resource and set on the forked pod within the sandbox.
// This allows the forked pod to connect to the maria-db resource that was provisioned.
.env(Arrays.asList(
new EnvOp().name("MYSQL_HOST").valueFrom(new EnvValueFrom().resource(
new EnvValueFromResource().name("customerdb").outputKey("host")
)),
new EnvOp().name("MYSQL_PORT").valueFrom(new EnvValueFrom().resource(
new EnvValueFromResource().name("customerdb").outputKey("port")
)),
new EnvOp().name("MYSQL_ROOT_PASSWORD").valueFrom(new EnvValueFrom().resource(
new EnvValueFromResource().name("customerdb").outputKey("root_password")
))
)
)
.addEndpointsItem(...);

CreateSandboxRequest request = new CreateSandboxRequest()
.cluster(...)
.name(...)

// specify the resource plugin to use and input param for it
.addResourcesItem(
new SandboxResource()
.name("customerdb")
.plugin("hotrod-mariadb")
.putParamsItem("dbname", "customer")
)
.addForksItem(customerServiceFork);

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 CreateSandbox which specifies that the hotrod-mariadb plugin must be used, and passes the input parameter dbname with value customer to it.

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.