id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
35400	SECRET_KEY_FALLBACKS documentation can be misleading when running multiple instances of an application	Ryan Siemens	nobody	"Hi, I was looking at the documentation for [https://docs.djangoproject.com/en/dev/ref/settings/#secret-key-fallbacks SECRET_KEY_FALLBACKS] and I think the documentations advice for how to rotate keys is a little to simplistic and will lead to unexpected issues with any modestly larger application that runs on multiple boxes (or pods).

""In order to rotate your secret keys, set a new SECRET_KEY and move the previous value to the beginning of SECRET_KEY_FALLBACKS.""

Just following this advice can lead to a scenario where your request is routed to a rotated box that has the new `SECRET_KEY` set, signs the session successfully and returns. A subsequent request could route to an un-rotated box which hasn't received the `SECRET_KEY` update and fails to validate the session. This diagram aims to illustrate the problem [[Image(https://cdn.zappy.app/f223668c63259e3316cfe0afb6bc97c3.png)]].

I believe the way to handle this situation is to have a two phase rollout where:

- Phase 1: **don't** update `SECRET_KEY`, but update `SECRET_KEY_FALLBACKS` to `['old_key', 'new_key']` and let all boxes sync. Everything is still being signed/validated with the current, unchanged `SECRET_KEY`.
- Phase 2: update `SECRET_KEY='new_key'` and `SECRET_KEY_FALLBACKS=['old_key']`. Now boxes that aren't rotated can validate sessions signed from boxes with the new_key even though they will still sign with the old_key.

Things can then proceed as normal where the `old_key` is dropped from `SECRET_KEY_FALLBACKS` after some time. Visually it looks like this [[Image(https://cdn.zappy.app/0edeb791cdc40d9d8e3b7f3918b1b11b.png)]]

My request is to update the documentation to ''at least'' indicate that the advice doesn't hold in scenarios where you are running the application across a fleet of boxes."	Cleanup/optimization	closed	Documentation	5.0	Normal	invalid	SECRET_KEY_FALLBACKS	Ryan Siemens	Unreviewed	0	0	0	0	1	0