Skip to main content

Preview Environments with Sandboxes

Prerequisites
  • Signadot account (No account yet? Sign up here).
  • A Kubernetes cluster
    • Option 1: Set it up on your cluster: This can be a local Kubernetes cluster spun up using minikube, k3s, etc. 
      kubectl create ns hotrod
      kubectl -n hotrod apply -f https://raw.githubusercontent.com/signadot/hotrod/main/k8s/all-in-one/demo.yaml
    • Option 2: Use a Playground Cluster: If you don't have a Kubernetes cluster for the above steps, you can provision a Playground Cluster from the Dashboard. It comes with the Signadot Operator and the HotROD application pre-installed in the hotrod namespace.

Overview​

In this guide, we will develop and test changes to a microservice that comprises the HotROD application. By the end of this tutorial, you will learn how to:

  1. Create a Sandbox containing changes to a microservice
  2. Access the Sandbox and test the change

This will take less than 15 minutes. Let's get started!

Understanding the demo application​

HotROD is a demo application that consists of 4 services: frontend, route, customer, and driver, and corresponding stateful components. These components make up a simple ride-sharing application where the end user can request rides to one of 4 locations and have a nearby driver assigned and an ETA available back to the end user.

These four microservices will serve as our "baseline", the stable pre-production version of the application. Typically this is an environment that is being updated continuously by a CI/CD process.

Next, we will create a Sandbox containing some changes to a particular microservice, but still test the whole application end-to-end while making use of unchanged dependencies from the baseline environment.

Developing & Testing changes with Sandboxes​

Basic Sandbox with no changes​

First, we will create a Sandbox that allows us to access the application as-is without any changes to it.

Step 1: Create Sandbox​

You can use either the UI or the CLI for creating sandboxes. The example below shows a sandbox template containing a template variable named cluster. 

name: "sandbox-basic"
spec:
  description: sandbox with no changes
  cluster: "@{cluster}"
  defaultRouteGroup:
    endpoints:
    - name: frontend-endpoint
      target: http://frontend.hotrod.svc:8080

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

Using the UI

The cluster parameter's value can be set to the name of the connected cluster. The input values for the template variables are supplied as shown below:

Once you create the sandbox, follow through the hyperlinked sandbox name on the success message to land on the sandbox detail page. You will see the endpoints listed at the bottom of the page.

Using the CLI
You should see something like the following once it completes:
Created sandbox "sandbox-basic" (routing key: ckn47lv8t2dhn) in cluster "playground-cluster".

Waiting (up to --wait-timeout=3m0s) for sandbox to be ready...
✓ Sandbox status: Ready: All desired workloads are available.

Dashboard page: https://app.signadot.com/sandbox/id/ckn47lv8t2dhn

SANDBOX ENDPOINT    TYPE   URL
frontend-endpoint   host   https://frontend-endpoint--sandbox-basic.preview.signadot.com

The sandbox "sandbox-basic" was applied and is ready.

Step 2: Access Endpoints​

To do some manual testing, we can use the authenticated preview endpoint to send requests to our application. Note that these endpoints can point to any service within the cluster. In this quickstart, we are going to be accessing the application from its frontend.

Here is how the preview looks for the frontend-endpoint endpoint:

We have so far not made any changes to the application. So the endpoints reflect the same response as the baseline environment. Note the high latencies (4000-5000 milliseconds) in the above screenshot for every request. This is due to a "bug" in the baseline application that we will fix and verify in the next step.

Test an improvement to the route microservice​

Next, we are going to create a new sandbox to test a bug fix to the route microservice. Specifically, the change we are making is to improve the latency of the microservice.

Step 1: Create sandbox​

Let us suppose that there is a new docker image tag that has been pushed (either from CI or from a developer machine), that is supposed to fix the observed latency issues.

If you look closely at the specification below, we see that we have a new section named forks. Forks define new test microservice which is derived from applying customizations on top of an existing baseline microservice.

In this case, we are creating a "fork" of the route Deployment, with a simple customization that is setting the image to signadot/hotrod:cace2c797082481ac0238cc1310b7816980e3244 (which is different from the baseline which is running signadot/hotrod:latest). This in turn will create a new Deployment in the same namespace which is running our new image. All other configuration associated with that "forked" deployment will be derived as-is from the baseline deployment.

name: "sandbox-better-route"
spec:
  description: sandbox with fix for the route service
  cluster: "@{cluster}"
  forks:
  - forkOf:
      kind: Deployment
      name: route
      namespace: hotrod
    customizations:
      images:
      - image: signadot/hotrod:@{image-tag}
  defaultRouteGroup:
    endpoints:
    - name: frontend-endpoint
      target: http://frontend.hotrod.svc:8080

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

We now create this sandbox with the following parameters:

cluster: # name of cluster from app.signadot.com/settings/clusters
image-tag: cace2c797082481ac0238cc1310b7816980e3244 # image tag containing 
                                                    # fix for latency regression
Using the UI

The input values for the template variables are supplied as shown below:

Once you create the sandbox, follow through the hyperlinked sandbox name on the success message to land on the sandbox detail page. You will see the endpoints listed at the bottom of the page.

Using the CLI
You should see something like the following once it completes.
Created sandbox "sandbox-better-route" (routing key: bc0vpqzwtvzw4) in cluster "playground-cluster".

Waiting (up to --wait-timeout=3m0s) for sandbox to be ready...
✓ Sandbox status: Ready: All desired workloads are available.

Dashboard page: https://app.signadot.com/sandbox/id/bc0vpqzwtvzw4

SANDBOX ENDPOINT    TYPE   URL
frontend-endpoint   host   https://frontend-endpoint--sandbox-better-route.preview.signadot.com

The sandbox "sandbox-better-route" was applied and is ready.

Step 2: Access Endpoints​

Once the sandbox is created, you can access the version of the application just as we did above using the frontend endpoint.

To verify that the latency "bug" we mentioned above was indeed fixed, you can open up the URL corresponding to frontend-endpoint in your web browser and try the UI associated with this Sandbox.

In this case, you should see a significantly lower latency number when compared to the frontend URL corresponding to the previous Sandbox. You can use both of these sandboxes side by side without affecting each other's behavior or that of the baseline environment.

Deleting Sandboxes​

You can delete the sandbox either from the UI (Sandbox detail or Sandboxes page), or the CLI. If using the CLI, the command looks like the following:

signadot sandbox delete sandbox-basic
signadot sandbox delete sandbox-better-route
tip

All the steps mentioned above can also be performed in code using the Client SDKs.

Congrats! You have tested a custom version of a microservice in Kubernetes using Sandboxes. You can use Sandboxes for Integration Testing as well as Feature Previews of your microservices. To learn more about how sandboxes are isolated from one another, check out header propagation and sandbox resources.