Skip to main content

Creating Sandbox Environments

Overview​

In this quickstart, you'll learn how to use Signadot Sandboxes to test changes to microservices in isolation. We'll use a sample application called HotROD to:

  • Create sandboxes to test new features in different microservices
  • Route specific requests to your sandboxes
  • Combine multiple sandboxes to test coordinated changes

This hands-on guide will show you how sandboxes enable fast, reliable testing of microservice changes without affecting the rest of your application.

Setup​

Before you begin, you'll need:

Option 1: Set up on your own Kubernetes cluster​

Using minikube, k3s, or any other Kubernetes cluster:

  1. Install the Signadot Operator: Install the operator into your cluster.
  2. Install the HotROD Application: Install the demo app using the appropriate overlay: 
    kubectl create ns hotrod --dry-run=client -o yaml | kubectl apply -f -
    kubectl -n hotrod apply -k 'https://github.com/signadot/hotrod/k8s/overlays/prod/istio'

Option 2: Use a Playground Cluster​

Alternatively, provision a Playground Cluster that comes with everything pre-installed.

Demo App: HotROD​

HotROD is a ride-sharing application with four microservices:

  • frontend: Web UI for requesting rides
  • driver: Manages drivers in the system
  • route: Calculates ETAs
  • location: Provides available pickup and dropoff locations for riders

The services use Kafka as a message queue, and Redis and MySQL for data storage.

Accessing the App's Frontend​

Configure the Signadot CLI to access HotROD:

  1. Create $HOME/.signadot/config.yaml:

    org: <your-org-name>      # From https://app.signadot.com/settings/global
    api_key: <your-api-key>   # From https://app.signadot.com/settings/apikeys
    local:
      connections:
      - cluster: <cluster>    # From https://app.signadot.com/settings/clusters
        type: ControlPlaneProxy

  2. Connect to the cluster:

    signadot local connect

  3. Access the frontend at http://frontend.hotrod.svc:8080

Creating Sandboxes​

Let's test two new features using separate sandboxes. We'll start with the backend change to the driver service.

Backend Feature: Enhanced Driver Plates​

First, let's test the new plate number format (source: @signadot/hotrod#260):

name: driver-plates
spec:
  description: Adding SD- prefix to driver plates
  cluster: "@{cluster}"
  labels:
    feature: hotrod-plates
  forks:
    - forkOf:
        kind: Deployment
        namespace: hotrod
        name: driver
      customizations:
        images:
          - image: signadot/hotrod:022e05f40fbae34cb600183641cf83ce2f7ef209-linux-amd64
            container: hotrod

Click the button below to open and run this spec on Create Sandbox UI.

Frontend Feature: Plate Highlighting​

Now, let's test the new UI feature (source: @signadot/hotrod#276):

name: frontend-highlight
spec:
  description: Add plate number highlighting in UI
  cluster: "@{cluster}"
  labels:
    feature: hotrod-plates
  forks:
    - forkOf:
        kind: Deployment
        namespace: hotrod
        name: frontend
      customizations:
        images:
          - image: signadot/hotrod:2c36f2791a6c3b33248a84e052623b29eec54884-linux-amd64
            container: hotrod

Click the button below to open and run this spec on Create Sandbox UI.

You can test each feature independently using either the Signadot Chrome Extension or any header-setting extension:

  1. Install the Signadot Chrome Extension
  2. Open the extension and search for your sandbox name (e.g. "frontend-highlight")
  3. The extension will automatically set the correct routing key header:

For either option:

  1. Test the backend change by setting the routing key from your driver-plates sandbox
    • You'll see driver plates with the "SD-" prefix (e.g., "SD-123ABC")
  2. Test the UI change by setting the routing key from your frontend-highlight sandbox
    • You'll see the new plate highlighting feature
  3. Visit http://frontend.hotrod.svc:8080 to see the changes

Combining Features with a Route Group​

Since both sandboxes are labeled with feature: hotrod-plates, we can create a route group to test them together:

name: hotrod-plates-feature
spec:
  cluster: "@{cluster}"
  description: "route group for testing multiple sandboxes together"
  match:
    any:
    - label:
        key: feature
        value: hotrod-plates

Save the route group spec as plates-routegroup.yaml and apply it:

% signadot routegroup apply -f ./plates-routegroup.yaml --set cluster=<cluster>

Created route group "hotrod-plates-feature".
A unique routing key will be generated for your route group.

The route group "hotrod-plates" was applied and is ready.

Using either the Signadot Chrome Extension (where you'll see "hotrod-plates-feature" in the dropdown) or your own header-setting extension from above, set the routing key to your route group's value. When you visit http://frontend.hotrod.svc:8080, you'll see both features working together:

  • Driver plates with "SD-" prefix
  • Clickable plate numbers with highlighting

Note that while we used browser extensions to test the frontend, you can use the same baggage header programmatically in any HTTP client like curl, Postman, or your application's test suite to route requests to your sandboxes.

This demonstrates how route groups let you combine multiple sandboxes to test coordinated changes across services.

How Request Routing Works​

With the application of the baggage header in your requests, traffic is routed based on which sandbox or route group you're targeting. For individual sandboxes, requests only go to the specific service you've forked. For the route group, requests are routed to both forked services, allowing you to test the features together.

The actual routing is accomplished using either:

  • A service mesh like Istio or Linkerd
  • Signadot's built-in DevMesh sidecars (enabled by adding the sidecar.signadot.com/inject: "true" annotation to your baseline deployments). For more details on setting up request routing with DevMesh, see our DevMesh Guide.

For routing to work across service-to-service calls, the baggage header needs to be propagated. This is typically done using distributed tracing libraries like OpenTelemetry, which can automatically instrument your code to propagate headers with minimal changes. Note that this doesn't require a tracing backend - the instrumentation libraries are sufficient for header propagation. Many languages support auto-instrumentation that requires no code changes at all. See our Header Propagation Guide and the OpenTelemetry documentation for more details.

The diagrams below show how requests are routed for the baseline and the 2 sandboxes we created.

When using a route group, it simply combines both routing rules into one context, allowing the request to flow through both sandboxes simultaneously.

Conclusion​

Congrats! You have tested new features in Kubernetes using Sandboxes. Sandboxes enable many powerful testing and development workflows - to learn more about what you can do with them, check out our how-to guides for common patterns and best practices. To understand the underlying concepts in more depth, see our Sandbox Concepts documentation.