feat(guest): support multiple gateway clusters

[kvinwang]

Summary

• add explicit cvm.gateway_clusters groups while preserving gateway_urls as a single-cluster failover list
• register every configured cluster with an independent WireGuard key, interface, cache, and listen port
• refresh clusters independently: a failed registration retains that cluster's last working configuration, while successful clusters update normally
• update gateway health checking and guest interface reporting for multiple dstack-wg* interfaces
• document configuration and validate cluster names and URLs in the VMM

Compatibility

Existing gateway_urls configurations retain their current first-healthy-URL behavior and continue using dstack-wg0 and the legacy key cache.

All explicitly configured clusters must use the gateway app identity authorized by the KMS-issued app keys. Different clusters must use disjoint WireGuard addresses.

Tests

• cargo check --manifest-path dstack/Cargo.toml -p dstack-util -p dstack-vmm -p dstack-guest-agent
• cargo test --manifest-path dstack/Cargo.toml -p dstack-util gateway_
• cargo test --manifest-path dstack/Cargo.toml -p dstack-vmm
• cargo test --manifest-path dstack/Cargo.toml -p dstack-types
• cargo test --manifest-path dstack/Cargo.toml -p dstack-guest-agent --no-run

[Copilot]

Pull request overview

This PR extends the guest/gateway wiring to support multiple independently operated gateway clusters while keeping gateway_urls as the legacy single-cluster failover list. It updates the VMM config/schema, guest system config generation, guest-side gateway registration + WireGuard setup, health checking, and documentation to reflect multiple dstack-wg* interfaces.

Changes:

• Add cvm.gateway_clusters configuration (name/urls/required) with validation in VMM and new GatewayClusterConfig in shared types.
• Register each configured cluster independently (separate WireGuard keys, interfaces, caches, and listen ports) and reject overlapping WireGuard addresses.
• Update guest interface reporting and gateway checker logic to handle multiple dstack-wg* interfaces; document the new configuration.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
dstack/vmm/src/config.rs	Adds gateway_clusters to VMM config and validates cluster names/URLs.
dstack/vmm/src/app.rs	Includes gateway_clusters in generated sys_config passed into the guest.
dstack/guest-agent/src/guest_api_service.rs	Expands interface reporting to include all dstack-wg* interfaces.
dstack/dstack-util/src/system_setup.rs	Implements multi-cluster registration, per-cluster key caches, disjoint WG address validation, and per-cluster WireGuard apply.
dstack/dstack-util/src/gateway_checker.rs	Updates health checking to consider multiple configured WireGuard interfaces.
dstack/dstack-types/src/lib.rs	Adds SysConfig.gateway_clusters and GatewayClusterConfig type.
docs/deployment.md	Documents how to configure multiple gateway clusters and constraints.

Suppressed comments (1)

dstack/dstack-util/src/system_setup.rs:741

• Error messages in this crate are expected to start with lowercase text (see CLAUDE.md logging/error style). This new error starts with an uppercase "Gateway".

            if target.urls.is_empty() {
                bail!("Gateway cluster {} has no URLs", target.name);
            }

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.