Skip to main content

signadot local

Note

The examples here work with v0.5.0+ of the Signadot CLI.

The local command lets you run workloads locally that can interact with your cluster services.

Connecting to a Cluster​

Connect your local environment to a cluster:

signadot local connect --cluster=my-cluster

This will:

  • Update /etc/hosts with cluster service names
  • Configure networking for local-cluster traffic

Once connected, you can run workloads locally that:

Remote Development Environments (RDEs)

For platform teams deploying Signadot to remote development environments where multiple users share the same machine-id, use devboxes to enable signadot local connect without LocalMachineID configuration. Devboxes also provide automatic isolation between non-admin users' local connect sessions.

View connection status:

signadot local status

Disconnect from the cluster:

# Keep sandbox configurations with local mappings
signadot local disconnect

# Remove all sandbox configurations with local mappings
signadot local disconnect --clean-local-sandboxes

Traffic Override​

Note

The examples here work with v1.3.0+ of the Signadot CLI.

signadot local override --sandbox=<sandbox> --with=<target> --workload=<workload> --workload-port=<port>

Where:

  • --sandbox: The sandbox to override traffic for
  • --workload (-w): The sandbox spec workload name of the workload to override.
  • --workload-port (-p): The container port on the sandboxed workload to override.
  • --with: Address of local server implementing the override (e.g., localhost:9999 or just 9999)

Description​

The 'override' command lets you intercept both HTTP and gRPC traffic coming into your sandbox and process it with a local service you specify (such as on your laptop).

How it works:

  • Any HTTP request (including gRPC) to your sandbox is first routed to your local service.
  • Your local service processes the request and replies.
  • By default:
    • If your local service's response contains the header 'sd-override: true', the response from your local service is immediately sent back to the client—the request does NOT reach the original sandbox workload.
    • For all other responses (i.e., 'sd-override: true' not present), the request is forwarded to the original sandbox workload as usual, and its response is returned to the client.
  • If your local service is unavailable or not running, all requests automatically fall through to the original sandbox workload.

Special case: Using '--except-status'

  • When you provide the '--except-status' flag, you specify a list of HTTP status codes (such as 404,503).
  • With this flag, all requests are overridden and served by your local service, EXCEPT when your local service returns one of the specified HTTP status codes.
  • In those cases (when your local service replies with a status listed in '--except-status'), the request is forwarded to the original sandbox workload, and its response is returned to the client instead.

This setup allows flexible and powerful local testing of changes for both HTTP and gRPC services while letting you make exceptions for specific HTTP status codes as needed.

Note

local override can easily record baseline traffic at near zero cost with virtual workloads

Example​

# Override traffic from port 8081 in a sandbox to local port 3000
signadot local override --sandbox=my-location-sandbox --with=3000 --workload=my-workload -p=8081

# Override with full localhost address and run in detached mode
signadot local override --sandbox=my-sandbox --with=localhost:9999 --workload=my-workload -p=8080 --detach

# Override traffic for a specific workload
signadot local override --sandbox=my-sandbox --with=localhost:9999 --workload=my-workload -p=8080

Listing and Removing Overrides​

You can use signadot local override list to see all active traffic overrides, and signadot local override delete to remove a specific override:

# List active traffic overrides
signadot local override list

# Delete a specific traffic override
signadot local override delete <name> --sandbox=<sandbox>

Example Session​

# Start traffic override
signadot local override --sandbox my-location-sandbox --with 3000 --workload my-workload -p 8081 --policy-default-fallthrough-status implemented

# Output shows:
# Waiting (up to --wait-timeout=3m0s) for sandbox to be ready...
# ✓ Sandbox status: Ready: All desired workloads are available.
# (my-location-sandbox) GET     /locations/123123 -> 404
# (my-location-sandbox) GET     /locations -> 200
# ^C
# Session terminated
# → Removing redirect in my-location-sandbox

Local Proxy​

The local proxy command lets you run cluster services locally via proxy, similar to Kubernetes port forwarding.

Required parameters (choose one):

  • --sandbox <sandbox-name>
  • --routegroup <route-group-name>
  • --cluster <cluster-name>

In the event a Sandbox or RouteGroup is specified, the proxy goes to the associated cluster and will inject the associated routing keys (unless already present in a given request). In the event a cluster is specified, no headers are injected.

With this in hand, signadot local proxy then will proxy remote services to local servers, each specified as

--map <scheme>://<host>:<port>@<host>:<port>

Where:

  • Left of @: URL resolved in remote cluster
  • Right of @: Local bind address
  • Scheme: http, grpc, or tcp (no header injection with tcp)

Example - running a test against a sandbox:

export BACKEND_SERVICE_ADDR=localhost:8001
signadot local proxy --sandbox feature-x \
  --map http://backend.staging.svc:8000@$BACKEND_SERVICE_ADDR &
pid=$!

# Run your test
newman run -env-var backend=$BACKEND_SERVICE_ADDR

kill $pid