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.

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

3. 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:

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

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​

Current Limitations​

The local sandbox functionality currently focuses on network connectivity. Other Kubernetes resources are not automatically synchronized:

  • Environment variables
  • Secrets
  • ConfigMaps
  • Volume mounts

For workloads requiring these resources, consider using Pull Request sandboxes instead.

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.