diff --git a/changelog.d/stage5-simulation-entrypoint-cutover.changed.md b/changelog.d/stage5-simulation-entrypoint-cutover.changed.md new file mode 100644 index 000000000..5f64bea20 --- /dev/null +++ b/changelog.d/stage5-simulation-entrypoint-cutover.changed.md @@ -0,0 +1 @@ +Route API v1 simulation requests through the qualified Cloud Run Simulation Entrypoint while retaining direct Modal routing as the deployment rollback path. diff --git a/docs/migration/history/stage5-simulation-entrypoint-cutover.md b/docs/migration/history/stage5-simulation-entrypoint-cutover.md new file mode 100644 index 000000000..7c6d53314 --- /dev/null +++ b/docs/migration/history/stage5-simulation-entrypoint-cutover.md @@ -0,0 +1,62 @@ +# Stage 5 Simulation Entrypoint Cutover Record + +This is the auditable release record for moving API v1's outbound simulation +requests to the separate Cloud Run Simulation Entrypoint. The merge commit for +this record intentionally triggers the normal API v1 staging-to-production +release after the environment selector is changed. + +## Scope + +The cutover changes only the network path used by API v1 for simulation +submissions and polling: + +```text +API v1 -> canonical Simulation Entrypoint -> Modal gateway -> Modal executor +``` + +It does not change API v1's public routes or response contracts, move +simulation compute or durable job state out of Modal, or migrate SQL-backed +application data. Direct Modal routing remains configured for rollback. + +## Qualification completed before cutover + +- The canonical entrypoint passed health, readiness, version, authentication, + comparison, and one-year budget-window checks. +- Comparison and budget-window IDs were unchanged and pollable through both + the canonical entrypoint and direct Modal, with identical completed payloads. +- `X-PolicyEngine-Request-ID` correlated requests from the canonical edge + through the Cloud Run entry service, the Modal gateway, and the executor. +- Cloud Run used its own client-credentials identity for Modal rather than + forwarding the API caller's bearer token. +- Three alternating paired runs per path put every canonical median latency + and completion metric within the 20% migration gate; the largest measured + canonical median increase was 9.4%. +- The standard Simulation API workflow completed its full staging integration + suite before deploying, promoting, and verifying production and the + canonical hostname. + +## Release behavior + +Immediately before this PR is merged, both API v1 GitHub environments must set +`SIM_ENTRYPOINT=cloud_run_simulation_entrypoint`. The qualified canonical URL +must remain present as the environment-scoped `SIMULATION_ENTRYPOINT_URL` +secret, and the direct Modal URL must remain available under +`OLD_SIMULATION_GATEWAY_URL`. + +The normal API v1 workflow then owns the entire release: + +1. Deploy staging with the Cloud Run selector. +2. Run the complete staging calculation, economy, and budget-window suite. +3. Block production on any staging failure. +4. Automatically deploy and verify production with the same selector. +5. Assign stable API v1 traffic to the exact tested production revision. + +Production does not repeat the calculation suite already completed in the +production-equivalent staging environment. + +## Rollback + +For a later regression, restore both environment selectors to +`old_gateway_direct` and run the normal release workflow. Staging must again +pass before production returns to direct Modal. Do not change DNS or manually +adjust Cloud Run traffic percentages for this rollback.