Skip to main content

signadot sandbox

Creating a Sandbox​

To create a sandbox (alias: sb), first write a YAML or JSON file containing the name and spec for the sandbox. The available fields within spec are documented in the Sandbox spec reference.

For example:

name: my-sandbox
spec:
  cluster: my-cluster
  description: Testing sandboxes
  forks:
  - forkOf:
      kind: Deployment
      namespace: example
      name: my-app
    customizations:
      images:
      - image: example.com/my-app:dev-abcdef
      env:
      - name: EXTRA_ENV
        value: foo
  defaultRouteGroup: # CLI v0.3.7+ required (see sandbox specification for details)
    endpoints:
    - name: my-endpoint       
      target: http://my-app.example.svc:8080

Then submit this sandbox by passing the filename to the sandbox apply command:

signadot sandbox apply -f my-sandbox.yaml

Creating a Sandbox with Local Mappings​

Note

To create a sandbox with a local workload one must be connected via signadot local connect.

An example local workload follows

name: my-sandbox
spec:
  cluster: staging
  local:
  - from:
      kind: Deployment
      name: location
      namespace: hotrod-devmesh
    mappings:
    - port: 8081
      toLocal: localhost:8888
    name: local-location
    env:
    - name: EXTRA_ENV
      value: foo
    - name: DEBUG
      valueFrom:
        configMap:
          key: debug
          name: app-config
    files:
    - path: debug
      valueFrom:
        configMap:
          key: debug
          name: app-config
% signadot sandbox apply -f my-sandbox.yaml

Working with Configuration​

Note

This mechanism requires the user to have kubectl read access to the workloads, ConfigMaps and Secrets for the kubectx associated with the local connection configuration used in signadot local connect.

One can retrieve configuration data from the in-cluster environment variables and file mounts of ConfigMaps, Secrets, and FieldRefs using the get-env and get-files sandbox commands:

% signadot sandbox get-env my-sandbox
export MYSQL_HOST="localhost"                           # constant
export MYSQL_PORT="3306"                                # constant
export MYSQL_PASS="abc"                                 # constant
export DEBUG="true"                                     # configMap: hotrod-devmesh/app-config[debug] (override)
export EXTRA_ENV="foo"                                  # constant (override)
%
% signadot sandbox get-files my-sandbox
/Users/jane/.signadot/sandboxes/my-sandbox/local/files
└── debug                                             # configMap: hotrod-devmesh/app-config[debug] (override)

Retrieving and Deleting Sandboxes​

You can use signadot sandbox list to see all existing sandboxes, and signadot sandbox get to see details about a single sandbox:

# List all sandboxes
signadot sandbox list

# Get one sandbox by name
signadot sandbox get my-sandbox

Each of the above commands can also produce machine-readable output (JSON or YAML):

# List all sandboxes in machine-readable format
signadot sandbox list -o json

# Get one sandbox in machine-readable format
signadot sandbox get my-sandbox -o yaml

You can delete a sandbox either by name, or by pointing at the same file that was used to create it:

# Delete sandbox by name
signadot sandbox delete my-sandbox

# Delete sandbox specified in a file
signadot sandbox delete -f my-sandbox.yaml

The sandbox spec also supports automatic deletion with time to live.

If sandbox creation fails, check that:

  • The cluster name matches a connected cluster
  • The referenced resources exist in the specified namespace
  • Image tags are correct and accessible

For templatizing your sandbox configurations, check out YAML Templates which let you create reusable sandbox definitions.