Flask app behind NGINX with dual upstream groups: ensuring session continuity during weight‑shift migration

Short answer

Adjust the NGINX upstream weights before sending HUP to the old Gunicorn pool. Traffic first, drain second, signal last. Sending HUP first means the old workers begin shutting down while NGINX may still be routing new requests to them, and any request that outlives Gunicorn's graceful_timeout is terminated rather than finished.

Session continuity across mixed Flask versions is not something the proxy can guarantee. It holds only when the secret key, cookie name/domain/path, and the session serializer/signing format are compatible in both directions. Treat that as a testable condition, not an assumption.

Confirmed versus likely

Well-established behavior: Flask's default session is a client-side signed cookie, so any worker that holds the same secret key can read it. Open-source NGINX upstream weights are static configuration; changing them requires a config reload (nginx -s reload), which is itself graceful and lets in-flight connections finish. Dynamic weight changes without a reload need NGINX Plus or a third-party module.

Likely but version-dependent: whether a cookie written by the new Flask release can be read by the old one. This depends on the Flask and itsdangerous versions in each pool. A read test passing does not prove write compatibility, so test both directions.

Why HUP-before-drain drops requests

Gunicorn's HUP is graceful only up to graceful_timeout. Long HTTP requests and WebSocket connections routinely exceed it. HUP also restarts workers, which closes WebSocket connections regardless of timeout. If the old pool is still receiving traffic when HUP fires, the overlap window is exactly where losses appear.

Sequence that works

1. Deploy the new pool and health-check it independently (direct to its port, not through the proxy).
2. Add the new upstream with weight 0 so it takes no traffic yet.
3. Reload NGINX to pick up the new upstream definition.
4. Shift weights gradually (for example 10/90, then 50/50, then 0/100), pausing to watch error rates.
5. Wait until the old pool's active request count reaches zero, or an agreed drain timeout elapses.
6. Only then send HUP to the old Gunicorn pool, or stop it.

Useful scoped checks:

nginx -T | grep -n -A6 'upstream'
nginx -s reload
# old pool: confirm no active requests before signalling
ps -o pid,etime,cmd -C gunicorn

Session compatibility checklist

• Identical SECRET_KEY in both pools, from the same source of truth.
• Identical SESSION_COOKIE_NAME, DOMAIN, PATH, SECURE, HTTPONLY, SAMESITE.
• Compatible Flask / itsdangerous versions, verified by round-trip tests.
• If Flask-Session or another server-side store is in use, both pools must share the same backend and schema. The client-side cookie reasoning above does not apply.

Long requests and WebSockets

Set Gunicorn graceful_timeout and NGINX proxy_read_timeout / proxy_send_timeout above your longest expected request. For WebSockets, plan for reconnect: worker restarts close the socket, so either drain those connections before HUP or accept a brief reconnect. Sticky sessions are unnecessary for cookie sessions, but any in-memory state or WebSocket room registry is per-pool and must be shared or drained.

One detail that changes the recommendation

Are sessions client-side signed cookies, or server-side (Flask-Session, Redis, database)? If server-side, the mixed-version question becomes a storage-schema question, and the answer above about cookie compatibility is the wrong frame.

Because Flask and itsdangerous release behavior changes over time, confirm the exact versions in both pools before trusting compatibility. This draft is written conservatively and should be validated in staging with a long request and a WebSocket before production use.