External Resources

When developing an application that requires resources not provided by the sandbox itself — such as cloud provider services like AWS RDS, SQS, or other managed infrastructure — these can be declared as Resources in the sandbox definition. The lifecycle of these resources is managed by the sandbox.

Lifecycle

The lifecycle of external resources is aligned with the sandbox lifecycle:

All events are optional for custom scripts. For Terraform:

• on_create is automatically mapped to terraform apply.
• on_delete is automatically mapped to terraform destroy.
• on_suspend and on_resume are optional and can be mapped to specific Terraform targets.

Definition

Add a resources section to the sandbox definition. For example:

workspaces:
- name: dev
  checkouts:
  - path: infra
    repo:
      git: git@github.com:example-org/infra
resources:
- name: aws
  brief: The AWS resources for a sandbox
  details: |
    # Sandbox specific AWS resources
    ...
  terraform:
    workspace: dev
    dir: infra/aws/sandbox
    require_build: true
    run:
      max_retries: 3
      timeout: 30m
      vars:
        sandbox_id: '$SANDBOX_ID'
    save_state: true
- name: k8s
  brief: The deployment for a sandbox
  details: |
    # Sandbox specific deployments in the K8s cluster
    ...
  wait_for:
  - aws
  handlers:
    on_create:
      use_workspace:
        name: dev
        run:
          dir: infra/k8s/sandbox
          cmd: |
            kubectl create ns "sandbox-$SANDBOX_ID" || true
            kubectl -n "sandbox-$SANDBOX_ID" apply -f manifest.yaml
    on_delete:
      use_workspace:
        name: dev
        run:
          dir: infra/k8s/sandbox
          cmd: |
            kubectl delete ns "sandbox-$SANDBOX_ID" || true
    on_suspend:
      use_workspace:
        name: dev
        run:
          dir: infra/k8s/sandbox
          cmd: |
            kubectl -n "sandbox-$SANDBOX_ID" scale --replicas=0 --all deploy
    on_resume:
      use_workspace:
        name: dev
        run:
          dir: infra/k8s/sandbox
          cmd: |
            kubectl -n "sandbox-$SANDBOX_ID" scale --replicas=1 --all deploy

In this example:

• On sandbox creation: First, Terraform provisions AWS resources from the dev workspace. Once complete, kubectl deploys workloads to a Kubernetes cluster.
• On suspension: Scales all deployments to zero replicas.
• On resume: Scales deployments back up.
• On deletion: Removes the Kubernetes namespace and destroys AWS resources via Terraform.

Note: The k8s resource uses wait_for: [aws] to ensure AWS resources are provisioned before the Kubernetes deployment begins.

Saved State

When save_state: true is specified, the output of custom scripts or Terraform outputs are stored at:

/run/sandbox/fs/resources/NAME

Where NAME is the resource name. This path is accessible across all workspaces in the sandbox. Keep the state small to avoid storage issues.

See Also

• Lifecycle — full sandbox lifecycle documentation
• Restriction Mode — using privileged secrets during resource provisioning
• Workspace Automation — how the dev workspace runs provisioning scripts
• Sandbox — sandbox definition structure