sandbox: add CLI for GCE sandbox environments#303
Closed
Conversation
Add 6 sandbox subcommands (create, ssh, stop, start, destroy, list) to manage GCE-based development environments via gcloud CLI. This includes gcloud wrapper utilities, SQLite state tracking for sandbox instances, a SandboxError exception hierarchy, and GCE constants. The Docker precheck is moved after argument parsing so sandbox commands work without Docker running.
Semver Impact of This PR⚪ None (no version bump detected) 📋 Changelog PreviewThis is how your changes will appear in the changelog. Bug Fixes 🐛
Internal Changes 🔧Release
Other
🤖 This preview updates automatically when you update the PR. |
Add Phase 3 developer workflow commands: - sync: pull latest branch changes via maintenance-sync.sh over SSH - status: show instance details with port-forward state and hints - port-forward: background SSH tunnels with PID lifecycle tracking - API validation on create (iap.googleapis.com, compute.googleapis.com) - Auto-kill port-forward tunnels on stop/destroy
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
dashed
changed the title
Forward port 8000 by default when running `sandbox ssh`, eliminating the need for a separate `port-forward` command. Users can customize with `--ports 8000,8010` or skip with `--no-forward`.
Replace hardcoded URL strings in test assertions with SANDBOX_REQUIRED_APIS constant references to fix 3 high-severity "Incomplete URL substring sanitization" alerts. Add explicit `permissions: contents: read` to build, lint, and test workflows to fix 5 medium-severity missing permissions alerts.
Adds `devservices sandbox logs [SERVICE]` to view logs from sandbox VM services. Supports devserver/webpack (default), startup orchestration, and Docker containers (postgres, redis, kafka, etc.) with partial name matching. Includes follow mode (-f) for real-time tailing.
Adds LOCAL:REMOTE syntax to --ports flag, e.g. `--ports 8000,15432:5432` forwards localhost:15432 to sandbox:5432. Plain port numbers (e.g. 8000) continue to work as before, mapping same port on both sides.
Allows overriding the sentry repo checkout to a specific branch or SHA, independent of the getsentry/sentry-version pin. Useful when developing features that span both repos. Usage: devservices sandbox create my-sandbox --branch feat/gs --sentry-ref feat/sentry devservices sandbox sync --sentry-ref abc123def
Generates SSH config entries with IAP ProxyCommand, enabling direct SSH, VS Code Remote-SSH, JetBrains Gateway, and Mutagen file sync without specifying gcloud flags each time. Supports --append to write to ~/.ssh/config, --remove to clean up, and --ports for LocalForward directives. Uses BEGIN/END markers for safe upsert and removal of config entries.
4 tasks
- migrate: runs make apply-migrations on the sandbox VM - restart-devserver: restarts sandbox-devserver systemd unit - exec: runs arbitrary commands on the sandbox via SSH
Add named profiles (devserver, services, all) to --ports flag for quick port forwarding of service groups. Enables hybrid workflow where devserver runs locally while connecting to sandbox Docker services.
Single command to toggle hybrid mode: stops the remote devserver, forwards all service ports, and prints instructions. Reversible with --stop which restarts the devserver and kills port forwarding.
Check if service ports are already in use locally before entering hybrid mode. Warns about conflicts and suggests running devservices down. Port check happens before stopping the remote devserver, so cancelling has no side effects.
Enable terminal color passthrough for `sandbox logs` by: - Adding `--color/--no-color` flag with auto-detect (TTY → colors, pipe → plain) - Adding `tty` parameter to `ssh_stream()` for PTY allocation (`--ssh-flag=-t`) - Stripping ANSI codes via remote sed when colors are disabled - Switching non-follow mode to streaming output for direct terminal passthrough
Two fixes discovered during live sandbox testing: 1. SSH PTY: Changed --ssh-flag=-t to --ssh-flag=-tt. The single -t requires stdin to be a terminal, but subprocess.Popen doesn't have one. Double -tt forces PTY allocation regardless. 2. journalctl output format: The default --short format strips ANSI escape codes from stored messages. When colors are enabled, use -o cat which outputs raw message content preserving ANSI codes written by the --pretty devserver.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the
devservices sandboxcommand group for managing GCE-based development environments. This provides a complete CLI for creating, managing, and developing on cloud sandbox VMs pre-configured with all Sentry dependencies.Subcommands (17)
sandbox createsandbox sshsandbox ssh-configsandbox syncsandbox logs--color/--no-color)sandbox port-forwardsandbox migratesandbox restart-devserversandbox execsandbox hybridsandbox startsandbox stopsandbox destroysandbox listsandbox statussandbox start-iap-tunnelsandbox stop-iap-tunnelKey Features
SSH Config (
ssh-config)~/.ssh/configentries with IAP ProxyCommand, connection keepalives, and port forwarding--appendwrites to config,--removecleans up, default prints to stdoutConvenience Commands (
migrate,restart-devserver,exec)execsupports arbitrary commands with proper error handlingPort Profiles
devserver(8000),services(PostgreSQL, Redis, Kafka, Snuba, ClickHouse, Relay, Spotlight),allport-forward,ssh, andhybridcommandsHybrid Mode (
hybrid)--stop(restarts remote devserver, stops port forwarding)Colored Logs (
logs --color/--no-color)--ssh-flag=-tt(double -t to force even without local tty)journalctl -o catwhen colors enabled to preserve stored ANSI codes (default--shortformat strips them)--no-coloror piped--colorforces colors through pipes (e.g.,| less -R)--prettydevserver +FORCE_COLOR=1) for rich HTTP status, prefix, and error coloringTests
196 tests (107 command + 85 utility + 4 profile) — all passing.
Test plan
--colorshows ANSI-colored output,--no-colorstrips codes-f) with color streaming tested on live sandbox