Skip to main content

Quickstart

Prerequisites
  • Signadot account with access to https://app.signadot.com.
  • Signadot CLI installed and configured correctly with your account.
  • Kubernetes cluster with the Signadot Operator installed that has been connected to Signadot.
    • You can also use a local cluster (minikube / k3s).
  • Permissions to install a demo application into the above Kubernetes cluster to simulate a baseline environment.

In this guide, we will install an example application consisting of 4 microservices into your Kubernetes cluster. This will serve as our baseline, the stable pre-production version of the application. Once this is set up, we will be able to create ephemeral Sandbox Environments to test new changes to one or more of the microservices that we deployed in our first step. At the end of this tutorial you will know how to:

  1. Create a Sandbox Environment that contains changes to a microservice
  2. Access the Sandbox Environment and test the change

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

Installing the HotROD Application

We will be using the HotROD application in our guide. You can create the HotROD application in your Kubernetes cluster as follows:

kubectl create ns hotrod
kubectl -n hotrod apply -f https://raw.githubusercontent.com/signadot/hotrod/main/k8s/all-in-one/demo.yaml

The application consists of 4 services: frontend, route, customer and driver, and corresponding stateful components. These 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.

Create Sandbox Environments

Prerequisites

The steps below assume that you have connected a cluster to Signadot and set up the CLI correctly on your machine. Please check that these steps have been completed successfully before proceeding.

Note that in the following YAML manifests, you must fill out the cluster name according to the name that you used when connecting your cluster to Signadot. You can find this name under the clusters tab by running the following command from the CLI:

signadot cluster list

Basic Sandbox with no changes

First, we will create a Sandbox Environment that allows us to access the application as-is without any changes to it. If you look closely at the specification below, you will see that we have a section forks which is the set of workloads on the cluster that we will be creating a new version of in this Sandbox environment. In this case, we are creating a fork of the route Deployment, with a simple customization that is setting the image to signadot/hotrod:latest. This is already the version of the image that we're running as part of the baseline environment, so, we're not changing anything just yet. Sandboxes are accessible via endpoints which are URLs that will be surfaced back to the user. There are two sets of endpoints defined in the above specification:

  1. route-endpoint: pointing to the forked version of the route deployment.
  2. frontend-endpoint: pointing to the frontend service inside the cluster.

Both of these endpoints will be surfaced back to us when we finish creating the sandbox.

Step 1: Create Sandbox Template Specification

The example below shows a sandbox template containing a variable named image_tag which can be set on the command line.

name: sandbox-basic
spec:
description: sandbox env with no changes
cluster: <your cluster>
forks:
- forkOf:
kind: Deployment
name: route
namespace: hotrod
endpoints:
- name: route-endpoint
port: 8083
protocol: http
customizations:
images:
- image: signadot/hotrod:@{route-image-tag} # @{route-image-tag} is a template variable
endpoints:
- name: frontend-endpoint
host: frontend.hotrod.svc
port: 8080
protocol: http

You can copy the above into a file and call it sandbox-template.yaml.

Step 2: Create Sandbox

To create the sandbox from the template, you must provide a value for the template variables. The following command gives an example.

signadot sandbox apply -f ./sandbox-template.yaml --set route-image-tag=latest

Running this may take a few moments but you should see something like the following once it completes.

Applied sandbox "sandbox-basic" (routing key: 9df7wtlhn31h2) in cluster "demo".

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

Dashboard page: https://app.signadot.com/sandbox/id/9df7wtlhn31h2

PREVIEW ENDPOINT TYPE URL
route-endpoint fork https://route-endpoint--sandbox-basic.preview.signadot.com
frontend-endpoint static https://frontend-endpoint--sandbox-basic.preview.signadot.com

Step 3: Access Sandbox Endpoints

We can access the URL of the endpoint pointing to the fork of hotrod/route using curl and a Signadot API key. You can generate your own API key from the Signadot Dashboard. This call is directly accessing the forked pod that has been created.

curl -H "signadot-api-key: ${SIGNADOT_API_KEY}" \
'https://route-endpoint--sandbox-basic.preview.signadot.com/route?pickup=577,322&dropoff=115,322'

All sandbox URLs are authenticated. If you want to access the frontend endpoint, you can do so via your web browser directly as long as you are logged into Signadot.

Frontend Preview

We have not made any changes so far to the application. This is exactly as the baseline environment is. So, you can test the frontend and see how the application looks. One thing to note is the reported duration and latency of each call when you click on the controls in the UI. In the sandbox we create subsequently, we will be testing a change that reduces the reported time and latency.

If you take a look at your Kubernetes cluster, you can see a new pod in the hotrod namespace that takes the form sd-sandbox-basic-route-... which is the only pod that was created to support this new Sandbox environment.

Update the Sandbox to test a change to the route service

Now, we are going to update the sandbox to test a change to the route service. Specifically, the change we have made is to improve the latency of the service.

Step 1: Update the sandbox

In order to test this change, we will use the sandbox template file from step 1 above and provide a different route-image-tag template variable. In a real scenario, this change could be part of a new Pull Request, within which the image with the provided tag has been built by the CI pipeline.

signadot sandbox apply -f ./sandbox-better-route.yaml --set route-image-tag=cace2c797082481ac0238cc1310b7816980e3244

This may take a few moments but you should see something like the following once it completes.

Applied sandbox "sandbox-better-route" (routing key: vuzlbf0bcydng) in cluster "demo".

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

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

PREVIEW ENDPOINT URL
Fork of hotrod/route https://route-endpoint--sandbox-better-route.preview.signadot.com
frontend-endpoint https://frontend-endpoint--sandbox-better-route.preview.signadot.com

Step 2: Access Sandbox Endpoints

You can access the new forked version of the route service just as we did before using the endpoint returned.

curl -H "signadot-api-key: ${SIGNADOT_API_KEY}" \
'https://route-endpoint--sandbox-better-route.preview.signadot.com/route?pickup=577,322&dropoff=115,322'

Note that this version of the request is hitting a forked workload that is running the custom image we specified previously. In order 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.

Frontend Preview

As you can see, you can see the significantly lower latency numbers when compared against 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.

tip

The sandbox in this quickstart guide only creates a single new pod within the Kubernetes cluster in order to enable end-to-end testing from the frontend. To learn more about how this works, check out the guide on header propagation.

From the Dashboard page link in the command output, you can visit the Signadot Dashboard and inspect each workload within the Sandbox and look at logs for the forked workload that belongs within the Sandbox.

Deleting Sandboxes

You can use the Dashboard, or CLI to delete these Sandboxes once you have finished using them. Using the CLI, the command looks like the following:

signadot sandbox delete sandbox-basic
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 Service in Kubernetes using Sandboxes. You can use Sandboxes for Integration testing as well as full E2E testing of your services. To learn more about how sandboxes can be isolated from one another, check out header propagation and sandbox resources.