Local Testing

Note

Local testing requires version v0.5+ of the Signadot CLI and v0.13+ of the Signadot Operator.

Overview

This guide explains how you can set up a local test environment for your microservices running in Kubernetes using Sandboxes. First, we'll be sending requests seamlessly from the local workstation into the cluster, and then we'll start receiving traffic from the cluster back to the workstation.

How Local Testing Works with Signadot

See the configuration for details on how to set up the CLI for local testing. Once the CLI has been configured, we can set up outbound connectivity from the workstation to the cluster.

Setting up outbound connectivity from workstation to cluster

% signadot local connect
signadot local connect needs root privileges for:
    - updating /etc/hosts with cluster service names
    - configuring networking to direct local traffic to the cluster
Password:

signadot local connect has been started ✓
* runtime config: cluster demo, running with root-daemon
✓ Local connection healthy!
    * operator version 0.16.0
    * port-forward listening at ":59933"
    * localnet has been configured
    * 45 hosts accessible via /etc/hosts
    * sandboxes watcher is running
* Connected Sandboxes:
    - No active sandbox

Once you have connected, you can check that services running within the cluster are accessible to you using their Kubernetes DNS names. For example, to access a Kubernetes ClusterIP service called my-service in namespace my-namespace, you will address it as my-service.my-namespace.svc:port, or my-service.my-namespace.svc.cluster:port or my-service.my-namespace.svc.cluster.local:port. You can check /etc/hosts for a full list of accessible services.

To verify that you have outbound connectivity you can use curl, wget, or a web browser to access one of the services directly from your workstation. Note that this should work seamlessly without requiring additional port-forwarding if the connection was set up correctly.

Setting up a sandbox to test a microservice running locally

In a microservices stack, we'll now try and set up a test workload on our local workstation such that it can participate in a sandbox.

In this above situation, let us say we're trying to develop and modify the microservice svcB. We can run svcB locally on some port, say 8080. We can now set up a sandbox spec such that our local svcB can participate in traffic coming from the cluster. Note that this still uses routing key-based isolation and the traffic is completely isolated from baseline and other sandboxes that may be running in other developer workstations.

name: "@{user}-svcB-sandbox"
spec:
  cluster: "@{cluster}"
  description: "svcB local sandbox"
  labels:
    feature: my-local-feature
  local:
  - name: "local-svcB"
    from:
      kind: Deployment
      namespace: some-namespace
      name: deploy-b
    mappings:
    - port: 8080
      toLocal: "localhost:8080"
  defaultRouteGroup:
    endpoints:
        # ... optional preview URLs we want to set up

Note how in the above sandbox spec, we'll be capturing traffic from a Deployment named deploy-b running inside the cluster in namespace some-namespace on port 8080 and mapping it to localhost:8080. Now, we're ready to start using our sandbox for testing our code changes.

% signadot sandbox apply -f ./local-sb.yaml --set cluster=demo --set user=alice
Created sandbox "alice-svcB-sandbox" (routing key: y9grlsjyrquqd) in cluster "demo".

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/y9grlsjyrquqd

The sandbox "alice-svcB-sandbox" was applied and is ready.

Now that our sandbox is ready, we can check that the sandbox is connected with this workstation by running signadot local status again.

% signadot local status

* runtime config: cluster demo, running with root-daemon
✓ Local connection healthy!
    * operator version 0.16.0
    * port-forward listening at ":59933"
    * localnet has been configured
    * 45 hosts accessible via /etc/hosts
    * sandboxes watcher is running
* Connected Sandboxes:
    - alice-svcB-route
        * Routing Key: y9grlsjyrquqd
        - local-route: routing from Deployment/deploy-b in namespace "some-namespace"
            - remote port 8080 -> localhost:8080
        ✓ connection ready

We can now send requests to our application from any service, including the ingress, along with the routing key of the sandbox (y9grlsjyrquqd) as a request header to get requests to be served by our local workstation rather than the baseline version of svcB that is running within the cluster.

Note that you will be able to disconnect and when connecting back, your local sandboxes will automatically be restored. If you are running Signadot CLI < v0.6.0 and/or Operator < v0.14.1, local sandboxes are orphaned after disconnect and will need a re-apply to connect back.

Using Preview Endpoints

If you add an endpoints section to your sandbox specification, you can use the generated preview URL to send requests with the routing key context. The endpoint URL that is returned above is authenticated and points to the local version of svcB and can be used to run tests against it using an API key that you can retrieve from the Signadot Dashboard at https://app.signadot.com.

curl -H "signadot-api-key: ${SIGNADOT_API_KEY}" \
  'https://my-endpoint--my-test-sandbox.preview.signadot.com' 

Limitations

Note that the above guide only covers setting up local network connectivity. If you are looking to make use of Persistent Volumes, ConfigMaps, or other Kubernetes constructs, please use Sandbox Forks to set the microservice under test within Kubernetes instead.

Next Steps

This guide described a basic sandbox with a local workload that can be set up to write and test a single service in a microservices stack during development. Building on these fundamental constructs, you can run multiple local workloads, or use a RouteGroup to send requests to multiple sandboxes which may contain other local or in-cluster workloads.