Skip to main content

Set up Local Sandboxes

Overview​

This guide explains how to enable local development workflows that connect with your Kubernetes environment using Signadot sandboxes. The setup involves configuring bidirectional connectivity between developer workstations and the cluster.

Implementation Steps​

1. Configure Cluster Connectivity​

Set up the infrastructure for local-to-cluster communication using the Signadot CLI. See the configuration guide for detailed setup instructions.

% 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

Verify connectivity by ensuring cluster services are accessible via their Kubernetes DNS names from the workstation. For example

% curl agent-metrics.signadot.svc:9090/metrics

2. Define Local Service Configuration​

Create a sandbox specification that maps cluster traffic to locally running services. This template enables developers to run services locally while maintaining connections to the cluster environment:

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}"

With such a template in place, and while connected to the cluster with signadot local connect, one can create the sandbox from the template as follows:

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

3. Working With Configuration​

Often workloads need to reference data via

  • Environment variables
  • Secrets
  • ConfigMaps
  • Volume mounts
  • Sandbox Resource Outputs

Running such workloads locally can involve cumbersome copying and/or modifying the in-cluster data. However, starting in v0.9.2 of the CLI one can extract environment variables and mounts using ConfigMaps and Secrets and modify them for local workloads. Also, starting in Signadot Operator v1.0, sandbox resource outputs can be made available to the local application using signadot sandbox get-env and signadot sandbox get-files.

Note

This mechanism requires the user to have kubectl read access to the workloads, ConfigMaps and Secrets for the kubectx associated with the local connection configuration used in signadot local connect.

For a sandbox named jane-hotrod with 1 local workload, one can call

% signadot sandbox get-env jane-hotrod
export MYSQL_HOST="localhost" # constant
export MYSQL_PORT="3306"      # constant
export MYSQL_PASS="abc"       # secret: mysql-secret.yaml[password]
%
% # or simply run
%
% eval $(signadot sandbox get-env jane-hotrod)

This will export the environment of the baseline workload for use locally.

Similarly, for files:

% signadot sandbox get-files jane-hotrod
/Users/jane/.signadot/sandboxes/jane-hotrod/local/files
└── app-config.yaml
    └── debug                                           # configMap: app-config.yaml[debug]

After running the above, the listed file tree has been populated with values from the cluster.

Overriding get-env and get-files​

Every local workload in a sandbox spec can specify overrides for the values output by get-env and get-files. For details, see the sandbox specification reference

4. Standardize Developer Workflow​

Provide a standardized approach for teams to create local sandboxes. Store the template in your infrastructure repository and document the usage pattern:

Developers can run their services either directly on their machine or via containers, binding to the specified ports to integrate with the sandbox environment.

Implementation Notes​

Streamlining Developer Experience​

To simplify the local development workflow:

  1. Create Internal Tooling

    • Build wrappers around the Signadot CLI
    • Automate sandbox specification generation
    • Provide sensible defaults for your environment

  2. Standardize Configuration

    • Define consistent port mappings
    • Create templates per service or service type
    • Document environment setup requirements

This standardization helps teams focus on development rather than infrastructure setup.

Conclusion​

A well-configured local sandbox environment enables efficient development workflows by connecting local workloads with your Kubernetes infrastructure. Build on these fundamentals to support:

  • Multiple local services
  • Combined testing with RouteGroups
  • Integration between local and cluster-based services

Focus on creating consistent, documented patterns that teams can easily adopt.