all-in-one: add hidden --debug-port flag to pin the debug listener port (#1462)

## Summary

Adds a hidden `--debug-port` flag to the `all-in-one` command that
overrides the auto-allocated ephemeral port for Pomerium's internal
debug/admin listener.

Today the debug/admin listener port is assigned by `AllocatePorts` and
changes on every restart, so the debug endpoints (databroker browser,
pprof, etc.) land on an unpredictable port. This flag lets you pin that
listener to a fixed, stable port. The bind host remains `127.0.0.1`, and
the flag is hidden since it's intended for development/debugging.

When unset (the default), behavior is unchanged — the port stays
ephemeral.

## Related issues

<!-- none -->

## Checklist

- [ ] reference any related issues
- [ ] updated docs
- [ ] updated unit tests
- [ ] updated UPGRADING.md
- [x] add appropriate tag (`improvement`)
- [x] ready for review

Author: wasaga

cmd/all_in_one.go

@@ -6,6 +6,7 @@ import (
 	"net"
 	"net/url"
 	"os"
+	"strconv"
 	"strings"
 	"time"
 
@@ -45,6 +46,7 @@ type allCmdOptions struct {
 	debugPomerium                   bool
 	debugEnvoy                      bool
 	adminBindAddr                   string
+	debugPort                       string
 	configControllerShutdownTimeout time.Duration
 	// healthProbeBindAddress must be externally accessible host:port
 	healthProbeBindAddress string
@@ -116,6 +118,7 @@ const (
 	debugEnvoy               = "debug-envoy"
 	debugAdminBindAddr       = "debug-admin-addr"
 	debugDumpConfigDiff      = "debug-dump-config-diff"
+	debugPort                = "debug-port"
 	configControllerShutdown = "config-controller-shutdown"
 )
 
@@ -124,6 +127,7 @@ var hidden = []string{
 	debugEnvoy,
 	debugAdminBindAddr,
 	debugDumpConfigDiff,
+	debugPort,
 }
 
 func (s *allCmd) setupFlags() error {
@@ -135,6 +139,7 @@ func (s *allCmd) setupFlags() error {
 	flags.StringVar(&s.metricsBindAddress, metricsBindAddress, "", "host:port for aggregate metrics. host is mandatory")
 	flags.StringVar(&s.healthProbeBindAddress, healthProbeBindAddress, "127.0.0.1:28080", "host:port for http health probes")
 	flags.StringVar(&s.adminBindAddr, debugAdminBindAddr, "", "host:port for admin server")
+	flags.StringVar(&s.debugPort, debugPort, "", "bind the debug/admin listener to this fixed port instead of an ephemeral one (127.0.0.1 only)")
 	flags.StringVar(&s.serverAddr, "server-addr", ":8443", "the address the HTTPS server would bind to")
 	flags.StringVar(&s.sshAddr, "ssh-addr", "", "the address the SSH server would bind to")
 	flags.StringVar(&s.httpRedirectAddr, "http-redirect-addr", ":8080", "the address HTTP redirect would bind to")
@@ -267,6 +272,17 @@ func (s *allCmdParam) makeBootstrapConfig(ctx context.Context, opt allCmdOptions
 
 	s.cfg.AllocatePorts(*(*[7]string)(ports[:7]))
 
+	// Override the auto-allocated debug listener port with a fixed value when
+	// requested, so the debug/admin endpoints (databroker browser, pprof, etc.)
+	// are reachable on a stable, predictable port across restarts. The value is
+	// a bare port number; the debug listener always binds to 127.0.0.1.
+	if opt.debugPort != "" {
+		if _, err := strconv.ParseUint(opt.debugPort, 10, 16); err != nil {
+			return fmt.Errorf("--%s: %q is not a valid port number", debugPort, opt.debugPort)
+		}
+		s.cfg.DebugPort = opt.debugPort
+	}
+
 	if opt.deriveTLS != "" {
 		s.cfg.Options.DeriveInternalDomainCert = &opt.deriveTLS
 		s.cfg.Options.GRPCInsecure = proto.Bool(false)