feat(stargate): add TOML configuration

[barrygreengus]

Why

Stargate configuration is currently spread across a large flat set of CLI flags and environment variables. Related settings are hard to understand as a unit, and mode flags can become inconsistent with the options they control. Stargate also retained a generic DNS discovery path even though current deployments use DNS only to enumerate local Kubernetes pods and use explicit Watch URLs for remote Stargates.

What changed

• Added strict, typed TOML configuration backed by Serde, toml, and serde_with.
• Added --config-file PATH. When present, the file is the complete source of configuration and every legacy CLI or environment setting is ignored.
• Kept the legacy CLI path with one startup deprecation warning.
• Grouped configuration into descriptive sections and used section presence for Kubernetes pod discovery, development peer forwarding, transport direction, tracing, load-balancer configuration, and worker authentication.
• Added typed environment references for runtime-provided identity and address values.
• Resolved relative paths against the configuration file directory and rejected unknown fields or invalid section combinations.
• Removed generic DNS-based Stargate discovery while retaining local Kubernetes pod discovery and explicit remote Watch URLs.
• Migrated the request-router Helm chart, generated manifest, self-managed values, and benchmark launchers to mounted TOML files.
• Added the implementation plan and full example configuration in STARGATE_CONFIG_FILE_PLAN.md.

Customer Release Notes

Stargate can now load structured TOML configuration with --config-file. Legacy CLI and environment configuration remains available during the deprecation period and emits a warning.

Plan Summary

The request-router chart now creates a Stargate configuration ConfigMap, mounts it read-only at /etc/stargate/stargate.toml, and starts Stargate with only --config-file. Kubernetes pod discovery is selected by the rendered topology: multi-pod and backend-router topologies include the section, while a single direct Deployment omits it and uses self-only discovery.

Usage

stargate --config-file /path/to/stargate.toml

When --config-file is present, all other Stargate CLI flags and their environment-backed values are ignored. Invalid files fail startup without falling back to legacy settings.

Testing

• cargo test -p stargate
• cargo test -p stargate-bench
• CARGO_INCREMENTAL=0 cargo clippy -p stargate -p stargate-bench --all-targets -- -D warnings
• cargo fmt --all -- --check
• make test in deploy/helm/llm-request-router
• helm lint llm-request-router --set llmRequestRouter.image.repository=stargate
• Verified the checked-in generated manifest exactly matches helm template for the documented release name and namespace.
• Started the rendered chart configuration with the Stargate binary and verified successful parsing and startup before graceful timeout shutdown.
• bazel build //src/libraries/rust/stargate/crates/stargate:stargate
• bazel test //src/libraries/rust/stargate/crates/stargate:stargate_test --test_output=errors
• deploy/stacks/self-managed/tests/llm-router-local-chart.sh and check-llm-pki-issuer.sh were not run because helmfile is not installed in the local environment. Their local-chart render expectations were updated, and the underlying chart render suites pass. No additional QA is required beyond CI.

Notes

The deprecated --disable-dns-discovery flag remains only in the legacy CLI compatibility path. The chart-level disableDnsDiscovery value was removed because topology now controls whether the Kubernetes pod discovery section exists.

Issues

Closes #1423

References

• Add structured TOML configuration for Stargate #1423

Related Pull Requests

None.

Dependencies

• Added toml 1.1.4, licensed MIT or Apache-2.0.
• Added serde_with 3.22.0, licensed MIT or Apache-2.0.
• Both licenses are allowed by the repository policy. No NOTICE update is required.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🛡️ CodeQL Analysis

🚨 Found 5 issue(s)

Severity Breakdown:

• 🔴 Errors: 0
• 🟡 Warnings: 0
• 🔵 Notes: 0

📋 Top Issues

🔗 View full details in Security tab

_{🕐 Last updated: 2026-08-31 21:56:01 UTC | Commit: 5bfbdf6}