"It works... mostly."
Think of a brownout in the electrical sense: the lights don't go out completely, but they dim. Appliances behave strangely. You notice something is wrong, but your house doesn't burn down. In platform engineering, a brownout is a controlled, temporary reduction in service quality or availability. Instead of turning the service off completely (a "blackout"), you intentionally introduce failure for short, predictable windows.
The key insight is that brownouts communicate urgency without causing catastrophe. Emails get ignored. Slack messages get muted. But if a developer's build fails three times in a row with a message that says "LegacyCI is being decommissioned — migrate to ModernCI now," they will pay attention.
Why Brownouts Work Better Than Hard Shutdowns
Brownouts exploit a simple behavioral truth: people respond to pain, not to warnings about future pain. A 5-minute outage at 10 AM on a Tuesday is painful enough to motivate action, but short enough that it rarely causes data loss or cascading failures. It also gives you a feedback loop — if a brownout causes a Sev-1 incident, you've discovered a critical dependency you didn't know about, and you can adjust your plan before the permanent shutdown.
A Practical Brownout Escalation Schedule
The following schedule assumes a 90-day deprecation window. Adjust timing based on the criticality of the system and the size of your user base.
Week 1-4: Warnings only. Banner in UI, log line in every response.
Week 5: Phase 1 — 1% of requests return HTTP 503 with a deprecation message.
Week 7: Phase 2 — Service offline for 15 minutes at 10:00 AM daily.
Week 9: Phase 3 — Service offline for 4 hours (9 AM–1 PM) on weekdays.
Week 11: Phase 4 — Service read-only. No writes accepted.
Week 13: Phase 5 — Permanent shutdown.
Each phase should be announced at least one week in advance, with the exact times published in a shared calendar or status page. Predictability is critical — surprise outages destroy trust, but scheduled degradation is a legitimate engineering signal.
Implementation: Returning Deprecation Errors
A brownout is not random chaos — it returns a structured, actionable error. Here is an example HTTP response during a brownout window:
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Retry-After: 900
Deprecation: true
Sunset: Sat, 01 Mar 2025 00:00:00 GMT
Link: <https://internal-docs/migrate-to-v2>; rel="successor-version"
{
"error": "service_deprecated",
"message": "This endpoint is being decommissioned. Please migrate to /v2/user by 2025-03-01.",
"migration_guide": "https://internal-docs/migrate-to-v2",
"brownout_window": "09:00–13:00 UTC weekdays until shutdown"
}
The Sunset and Deprecation HTTP headers are defined in RFC 8594 and are recognized by many API clients and monitoring tools. Using them signals professionalism and gives automated tooling a machine-readable deprecation signal.