Skip to main content

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 set up outbound connectivity from the local workstation to the cluster, and then we'll start receiving traffic from the cluster back to the workstation.

High-Level Steps​

1. Set Up Outbound Connectivity from Workstation to Cluster​

Configure the Signadot CLI for local testing. See the configuration guide for details on setting up the CLI.

% 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

Check that services running within the cluster are accessible using their Kubernetes DNS names.

2. Set Up a Sandbox to Test Microservice Running Locally​

Run a microservice (e.g., svcB) locally on a specific port (e.g., 8080). Create a sandbox spec to map the cluster traffic to your local service.

name: "@{user}-@{deployment}-sandbox"
spec:
  cluster: "staging-cluster"
  ttl:
    duration: 1d
  description: "@{user} local sandbox"
  labels:
    feature: "@{branch}"
  local:
  - name: "local-@{user}-@{deployment}"
    from:
      kind: Deployment
      namespace: "@{namespace}"
      name: "@{deployment}"
    mappings:
    - port: "@{port}"
      toLocal: "localhost:@{localPort}"

3. Set up Sandbox Template for developers​

You can check the above template into a central repository for developers to use by running a command as shown below:

signadot sandbox apply -f ./local-sbx.yaml \
  --set user=alice \
  --set branch=my-branch \
  --set deployment=route \
  --set namespace=my-ns \
  --set port=8080
  --set localPort=8080
...

Note that the actual running of the local process may be in docker or on the machine directly but the expectation is that the user will start the required dependency that they want to run locally and bind it to the port specified above.

Best Practices​

Caveats​

Currently, the scope of local in sandboxes is limited to network connectivity only. Management of environment variables, secrets, ConfigMaps, and file mounts is not implemented yet for local workloads. These are not automatically attached to the local process, and will need to be managed by the user.

If you are looking to make use of cluster secrets, environment variables and volumes, specifying the sandboxes in-cluster like that in Pull Request sandboxes may work better for you.

Wrapping Signadot Local in Internal CLIs​

To simplify the use of Signadot Sandboxes and to abstract away some of the complexities, we recommend creating / using an internal CLI that wraps the Signadot CLI. This tool can provide a simpler user experience by auto-generating the sandbox spec from minimal inputs provided by the user. Here's a pattern you might follow:

  1. Simplify Input Requirements: Allow users to specify only the essential information, such as the service name, version, and any specific environment variables or configurations needed for the sandbox.
  2. Auto-Generate Sandbox Specs: Based on the user inputs, automatically generate the sandbox spec.

By following these best practices and utilizing an internal tool for local sandbox management, you can streamline the development process and make it easier for developers to test and validate changes in a controlled environment.

Conclusion​

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.