What is the difference between blue/green and rolling deployment?

Blue/green deployment maintains two identical production environments — blue (currently live) and green (new version) — and switches all traffic from blue to green simultaneously via a load balancer flip. The key properties: rollback is instantaneous (flip load balancer back to blue), old and new code never run simultaneously in production (the entire fleet transitions at once), and the green environment can be smoke-tested with real configuration before any user traffic reaches it. The cost is maintaining two full environments during each deployment window, which doubles compute cost for the duration of the transition. Rolling deployment replaces production instances one at a time (or in small batches), running old and new code simultaneously during the transition. The key properties: no extra infrastructure cost (instances are replaced in place), rollback requires re-deploying the old version across all updated instances (minutes, not seconds), and old and new code run concurrently during the rollout. The concurrent execution constraint means that any database schema change applied during a rolling deployment must be backward-compatible — old code reading the new schema must not crash, and new code must handle the old schema state during the transition. This constraint is frequently discovered not at deployment strategy design time but during the first failed migration. The choice between them is a trade-off between infrastructure cost (blue/green is more expensive), rollback speed (blue/green is faster), and schema migration complexity (rolling requires backward-compatible migrations; blue/green does not).

What does a canary deployment validate that blue/green does not?

A canary deployment routes a small percentage of real production traffic — typically 1 to 5 percent — to the new version before committing to a full rollout. The validation that canary provides and blue/green does not is real-user behavior under the new code at production scale, with production data, against the production dependency graph, under real traffic patterns. Blue/green smoke tests run synthetic requests against a pre-production environment — they validate that the application starts, that known test paths return expected responses, and that the configuration is plausible. They do not validate that the new code handles the actual distribution of real user request patterns correctly. Canary catches failure modes that only appear under real load: edge cases in production data that the smoke test data set does not contain, performance regressions under the actual request concurrency distribution, memory growth patterns that only appear at production request volume, and third-party integration failures that only occur with production credentials and production rate limits. The trade-off is that canary exposes a fraction of real users to the potential failure. For failure modes that are catastrophic (data corruption, authentication bypass), exposing even 1 percent of users is unacceptable and the deployment should be aborted based on synthetic test failure before any user traffic reaches the new version. For failure modes that are performance degradations or UX regressions, canary provides a validation surface that no amount of pre-production testing can replicate.

How do you write a backward-compatible database schema migration for rolling deployment?

A backward-compatible schema migration is one where the old application code continues to function correctly after the migration has been applied to the database, and the new application code continues to function correctly on the old schema state during the transition. This requires splitting migrations that would normally be a single operation into a multi-phase sequence. Adding a nullable column is safe for rolling deployment: old code ignores the new column, new code populates it. Adding a NOT NULL column without a default is not safe: old code attempts inserts without the column, the database rejects the inserts, old pods crash. The safe sequence for adding a NOT NULL column is: Phase 1, deploy code that writes the column but treats it as optional, apply migration to add the column as nullable. Phase 2, backfill the column for all existing rows. Phase 3, apply migration to add the NOT NULL constraint. Phase 4, deploy code that requires the column to be present. Renaming a column is not backward-compatible in a single migration: add the new column name, deploy code that writes to both columns, backfill the new column, deploy code that reads from the new column only, drop the old column. The multi-phase pattern adds deployment complexity — each phase is a separate deploy window with a separate migration. Teams that choose rolling deployment must accept this complexity or accept the risk of applying a non-backward-compatible migration during a rolling rollout. The deployment strategy decision record should specify this constraint explicitly: rolling deployment requires that all database schema changes follow the expand-migrate-contract pattern, and this requirement applies to every migration for the lifetime of the system.

When should a team switch from rolling to blue/green or canary deployment?

Three conditions should trigger a deployment strategy review. First, the team experiences a rolling deployment failure caused by a non-backward-compatible schema migration — where old and new pods run concurrently and the old pod behavior on the new schema produces crashes, data corruption, or silent incorrect behavior. This is the most common trigger and usually occurs 6 to 18 months after the founding sprint, when the system has accumulated enough schema complexity that the backward-compatibility constraint becomes difficult to maintain rigorously. Second, rollback speed becomes a business-critical requirement: the product is used in production by customers with contractual uptime requirements, and the 3 to 8 minutes required to re-deploy the old version across a rolling rollout is too long for the SLA. At this point, blue/green's instantaneous load-balancer flip becomes a requirement, not a preference. Third, the team wants to validate production behavior before committing to a full rollout — when deployments carry enough risk that exposing 100 percent of users simultaneously (as rolling and blue/green both do, in different ways) is no longer acceptable. Canary is the answer here, but it requires weighted routing infrastructure (a load balancer or service mesh capable of traffic splitting by percentage) and an automatic promotion/abort criterion (the canary promotion is automated on a success signal, not manual). A team that adopts canary without an automated abort criterion will either abort too late (a human notices the error rate manually) or promote too early (the human approves after a 5-minute window that is too short to catch gradual memory growth). The deployment strategy record should document the current strategy, the constraints it imposes, and the specific conditions that would trigger a strategy migration.

The deployment strategy decision record: why the deployment model you chose determines your rollback window and your production validation surface

Published 2026-07-11 · WhyChose

Deployment strategy decisions are made in the founding sprint, in the specific AI session where someone asks "how do I deploy without downtime?" The answer they receive — a rolling update configuration for their Kubernetes deployment, a blue/green setup for their load balancer, a canary controller Helm chart — becomes the deployment model for the system. The conversation ends. The code is written. The CI/CD pipeline begins producing deployments. The decision is not written down.

The deployment strategy choice is not a preference. It is a structural constraint that propagates through every subsequent decision about database migrations, rollback procedures, production validation, and infrastructure cost. A team that chose rolling deployment without documenting the choice will, at some point between six months and two years later, attempt a database schema change that is not backward-compatible. The migration will run. The new schema will be applied to the database. The rolling update will begin replacing old pods with new pods. The old pods — now running against a schema they were not written for — will begin crashing. The alert fires. The on-call engineer looks at the deployment and the migration and the crashing pods and realizes, for the first time, that rolling deployment and non-backward-compatible schema changes cannot coexist. The decision that was made without documentation is now being explained in a postmortem.

Two ways deployment strategy produces the wrong outcome

The rolling deployment migration compatibility failure

A 29-person B2B SaaS company builds an enterprise project management platform. In the founding sprint, an engineer asks Claude how to deploy the Node.js backend to Kubernetes without downtime. The response walks through a Deployment manifest with a RollingUpdate strategy: maxUnavailable 0, maxSurge 1. The engineer implements it, it works, and rolling deployment becomes the production deployment model for the next two years. The decision is embedded in the Kubernetes manifests. No ADR is written. No constraints are documented.

In month 23, the team adds a per-user notification preferences table and, as a follow-on change, adds a NOT NULL column — notifications_enabled — to the existing users table, defaulting to true for all existing rows. The migration is written as a single ALTER TABLE statement: ADD COLUMN notifications_enabled BOOLEAN NOT NULL DEFAULT TRUE. The engineer writing the migration knows about backward compatibility in principle but tests it manually against a staging database and observes no issues. Staging runs one pod. The constraint is invisible on one pod.

In production, the migration runs and completes. The rolling update begins. The first batch of new pods comes up running the new application code — code that expects the notifications_enabled column to exist and uses it for every user session initialization. Meanwhile, the old pods — 14 of the original 18 — are still serving requests. The old application code does not know the notifications_enabled column exists. It runs INSERT statements for new user onboarding flows that do not include the notifications_enabled field. The database, now enforcing the NOT NULL constraint, rejects these inserts with a constraint violation error. The old pods begin producing 500 errors on user registration. Within four minutes, 14 of 18 pods are generating registration failures. The alert fires.

The on-call engineer sees the migration in the deployment log and the constraint violation in the application logs and understands immediately what has happened. The rollback requires re-deploying the previous application version across all 18 pods — a rolling replacement in the opposite direction. It takes six minutes. During those six minutes, new user registration is unavailable. The migration cannot be rolled back without dropping the column, which would crash the new pods. The team runs the old version, disables new user registration as a feature flag, and plans a proper multi-phase migration sequence for the following week. The incident postmortem produces a finding that the team will not forget: rolling deployment requires backward-compatible schema migrations, every time, without exception. This constraint had never been documented. The engineer who wrote the migration had not received the constraint. The deployment strategy choice made in the founding sprint had been waiting 23 months to surface this consequence.

The blue/green smoke test gap

A 41-person API platform company builds a developer tool that processes large volumes of document data for enterprise customers. In year one, they choose blue/green deployment specifically for its rollback property: if a deployment fails, they flip the load balancer back to the blue environment in under 30 seconds. The rationale is documented loosely in a Confluence page ("we chose blue/green for fast rollback") but the specific constraints of the model are not. Over 18 months, the blue/green system works as designed: three times they have flipped back to blue during problematic deployments, and each time the rollback has been instant and clean.

In month 19, a deploy goes wrong in a way the smoke test suite does not catch. The new version — green — passes all 47 smoke test scenarios. The scenarios cover application startup, authentication flows, document processing paths, and integration with four external APIs using test credentials that are rotated monthly and are current. The load balancer flips to green. Within 90 seconds, customer support begins receiving reports that email notifications are not being delivered. The engineering team checks the application logs: the green environment's SMTP credential, which is used for transactional email delivery, has not been rotated in 11 months. The credential expired two days before the deployment. The smoke test suite does not exercise the email notification flow. The test credential set used in smoke tests rotates monthly; the production SMTP credential is not in the rotation process. The team flips back to blue in 22 seconds. The blue environment, which uses the same SMTP credential, also cannot send email — but this is not discovered until the rollback, because no emails have been sent from blue in three weeks. Two hours and 14 minutes of email delivery downtime for all customers.

The postmortem produces a finding about the smoke test coverage surface. The team had assumed that "the green environment is smoke-tested before the flip" was a complete production validation model. It is not. The smoke tests validated the application behavior — but not the production credential state, the external service dependency health, or the configuration drift between blue and green that accumulates over months. The deployment strategy decision record had not specified what the smoke test suite must cover. It had not specified that production credentials must be validated as part of the pre-flip checklist. It had not specified a maximum age for environment-specific configuration that would trigger a pre-deploy credential audit. The blue/green model had been chosen for its rollback speed, implemented correctly, and then operated for 18 months without ever documenting what the model's pre-flip validation surface was required to include. The failure mode that materialized was not a failure of the blue/green model — it was a failure to document the model's constraints.

Four structural properties that deployment strategy determines

Rollback speed and mechanism

The rollback mechanism is determined entirely by the deployment model and cannot be changed without changing the model. Rolling deployment rollback requires re-deploying the previous version: the rolling update controller runs the deployment process in reverse, replacing new pods with old pods one batch at a time. At a typical rolling update rate — maxSurge 1, maxUnavailable 0, two pods per batch — rolling back an 18-pod deployment takes four to eight minutes depending on pod startup time and health check duration. During those four to eight minutes, the defective new version is serving a fraction of production traffic that decreases as each pod is replaced. If the defect is catastrophic — authentication bypass, data corruption, complete service outage — those four to eight minutes represent continued exposure. The question is not whether rolling rollback is fast enough in the abstract. The question is whether it is fast enough given the worst-case defect severity that could reach production.

Blue/green rollback is a load balancer reconfiguration: one API call or one Terraform apply changes the target group or upstream pool from green to blue. The application change is instantaneous from the load balancer's perspective; session draining may take 30 to 90 seconds depending on connection drain timeout configuration, but no new requests reach the defective green environment from the moment the reconfiguration is applied. The rollback speed advantage is clear. The cost is maintaining the blue environment at full production capacity during and after each green deployment — compute costs approximately double during the blue/green window. Teams that run blue/green continuously (green is always the previous production version, kept warm) pay this cost permanently. Teams that terminate the blue environment after a successful green deployment pay the cost only during the deploy window, but lose the instant rollback capability until the blue environment is re-provisioned (which takes minutes to tens of minutes depending on instance type and warmup requirements).

Canary rollback depends on whether the canary abort is automatic or manual. An automated canary abort — triggered when the canary error budget burn rate or SLI breach crosses a defined threshold — can abort the rollout within seconds of detecting the signal. A manual canary abort depends on an engineer noticing the signal and executing the abort command. In practice, automated abort is the safety net; manual abort is the confirmation. The SLO and error budget decision record provides the signal basis for automated canary abort: if the canary's error budget is burning at 14x the allowable rate over a five-minute window, abort. Without an SLO-derived abort threshold, the canary abort criterion is "someone looks at the dashboard and decides it looks bad" — which is too slow and too variable. The deployment strategy decision record should specify the automated abort criterion explicitly, because without it the canary model's safety guarantee is not the automated abort; it is the engineer who happens to be watching.

The incident response playbook decision record should reference the deployment strategy record directly: the rollback procedure for a deployment-caused incident is deployment-strategy-specific. A runbook that says "roll back the deployment" without specifying the mechanism is not a runbook — it is a task description. The runbook should specify: for rolling deployments, the kubectl rollout undo command and the expected completion time; for blue/green, the load balancer reconfiguration command and the drain timeout; for canary, the abort flag or the canary weight parameter reset. The time an engineer spends figuring out the rollback mechanism during an active incident is time the defective version is in production.

Database migration compatibility constraint

Rolling deployment imposes a structural constraint on every database schema change: the old code and the new code must both work correctly against the new schema simultaneously. This is the backward-compatibility constraint, and it applies without exception to every migration for the lifetime of the system. It is not a sometimes-constraint that applies only to risky changes. It applies to every change, because every rolling deployment transitions the fleet through a state where both code versions are running against the production database.

The constraint manifests differently for different migration types. Adding a nullable column is safe: old code ignores the new column; new code populates it. Adding a NOT NULL column without a default is unsafe: old code runs inserts without the column and receives a constraint violation. Adding a NOT NULL column with a server-side DEFAULT is safe if the old code never explicitly enumerates column names in INSERT statements, and unsafe if it does. Renaming a column is unsafe in a single migration. Dropping a column used by old code is unsafe. Adding an index is typically safe (reads and writes continue while the index builds, with some write overhead). Adding a unique constraint is unsafe if the data that would be written by old code could violate the constraint. Each of these cases requires a specific multi-phase approach.

The database migration strategy decision record covers the expand-migrate-contract pattern that makes complex migrations backward-compatible: Phase 1 (expand) adds new structures without removing old ones and deploys code that writes to both; Phase 2 (migrate) backfills and validates the new structures; Phase 3 (contract) removes the old structures after all code has migrated away from them. The deployment strategy decision record must reference this pattern as a hard requirement for rolling deployments, not a best practice. Teams that adopt rolling deployment without documenting this constraint will inevitably discover it during an incident, typically in a migration that was written by an engineer who joined after the founding sprint and was never told that the deployment model imposes this requirement.

Blue/green deployment does not impose the backward-compatibility constraint in the same way, because the entire fleet switches from old to new simultaneously. Old code never runs against the new schema in production — the schema migration is applied either before the green deployment (which may cause a brief degraded state on blue if the migration changes behavior old blue code relies on) or after the load balancer flip (which exposes green to both the old and new schema states). The conventional blue/green migration sequence is: apply migration changes that are backward-compatible with both old and new code before the flip; apply migration changes that only work with new code after the flip, with the old blue environment available for rollback. This is still a discipline, but it is substantially less restrictive than the rolling deployment compatibility constraint — it requires that pre-flip migrations are safe for old code, not that all migrations are safe for old code running concurrently with new code in production.

Production validation surface before full rollout

Blue/green deployment's production validation surface is the smoke test suite: the set of synthetic requests run against the green environment before the load balancer flip. The smoke test validates that the application starts, that defined test paths return expected responses, and that the configuration is plausible as measured by the scenarios the team has bothered to write. It does not validate the full distribution of real user request patterns, production data edge cases, production credential state, or behaviors that only emerge at production traffic volume. The gap between "smoke tests pass" and "production behavior is correct" can be large or small depending on how comprehensive and production-representative the smoke test suite is. The gap grows over time as the system evolves and the smoke test suite falls behind.

Rolling deployment has no pre-rollout validation stage. The new version receives production traffic as soon as the first new pod is healthy. The first 1 to 5 percent of requests to the new pod are the validation signal — the engineer watches the error rate on the new pods during the rollout and can pause or abort if anomalies appear. This requires that the rollout controller supports pause (Kubernetes rolling updates do) and that the engineer watching the rollout has a dashboard showing per-pod or per-deployment-version error rates. Without a per-version error rate breakdown, the aggregate error rate signal is too diluted at low new-pod percentages to detect failures early: if 2 of 18 pods are running the new version and the new version has a 10% error rate, the aggregate error rate increase is (2/18 × 10%) = 1.1% — potentially within normal variation, invisible to the engineer watching the total error rate.

Canary deployment provides the richest production validation surface: a defined percentage of real production traffic — typically 1 to 5 percent — routes to the new version for a defined observation window before the rollout proceeds. The signal is real users, real data, real production credentials, and real traffic patterns. The failure modes that canary catches and that smoke tests miss are failure modes that require production-scale data or traffic patterns to manifest: a performance regression that only appears at 50+ requests per second, a database query that takes 200ms on the 20,000-row test dataset and 8 seconds on the 8-million-row production dataset, an edge case in production user data (a zero-length value in a field that test data always populates, a special character in a username) that causes a crash in the new code. The observation window must be long enough for the traffic sample to be statistically meaningful. For high-traffic services, five minutes may be sufficient. For low-traffic services or failure modes that only appear in specific time windows (batch jobs, scheduled tasks, low-volume paths), the observation window may need to be hours. The deployment strategy decision record should specify the canary percentage, the observation window, and the automated abort threshold for each service or service tier — because these parameters are not constants across all services in the system.

Feature-flag-controlled release decouples the deployment from the release in a way that all three deployment models can use as a complement. The new code is deployed to all pods (using rolling, blue/green, or canary as the deployment mechanism), but the new behavior is gated behind a feature flag that is initially disabled. The "release" is the flag enabling for a subset of users, then all users. This model provides a production validation surface that is broader than canary (the full production fleet is running the new code, responding to real traffic) and with a rollback mechanism that is faster than any deployment rollback (disable the flag). The cost is flag management complexity: every flagged behavior must have an explicitly planned flag removal (flags that are never cleaned up create dead code and configuration complexity that compounds over years). The feature flag decision record covers flag lifecycle management, the flag service architecture, and the flag-as-deployment-gate pattern. The deployment strategy record should specify when feature flags are required as a complement to the deployment model — for high-risk behavior changes, for changes affecting enterprise customers under SLA, for changes that affect billing or authentication flows — rather than leaving the choice to individual engineers on a per-change basis.

Infrastructure cost and complexity overhead

Rolling deployment has the lowest infrastructure cost: instances are replaced in-place, no additional capacity is required, and the deployment mechanism is built into every major container orchestration system without additional infrastructure. The container orchestration decision record covers the Kubernetes rolling update controller configuration: the maxSurge and maxUnavailable parameters determine the rollout speed and the minimum available capacity during the rollout. A maxSurge of 1 and maxUnavailable of 0 maintains full capacity throughout the rollout at the cost of requiring one extra pod's worth of capacity during the surge window. A maxSurge of 25% and maxUnavailable of 25% is the Kubernetes default and accepts a 25% capacity reduction during the rollout in exchange for faster completion. The parameters are not arbitrary — they should be set based on the service's scaling headroom and the acceptable minimum capacity during a deploy. Setting them to the default without reviewing their implications is a deployment strategy decision made by omission.

Blue/green deployment requires either a permanent second environment (the previous production version is kept warm, doubling running cost) or an on-demand second environment (the green environment is provisioned for each deployment, adding deployment time for provisioning). Most teams that adopt blue/green use the on-demand model for cost reasons: green is provisioned, smoke-tested, and flipped; blue is terminated after a stability window (typically 15 to 30 minutes). The stability window is the period during which the rollback option remains available at full speed. After the stability window, rollback requires re-provisioning the old environment, which takes minutes to tens of minutes and may involve database state that has changed since the flip. The stability window duration is a deployment strategy decision: too short (5 minutes) and a slow-manifesting failure mode (gradual memory growth, an issue that only appears in a specific session-age pattern) is not caught before rollback becomes expensive; too long (several hours) and the team is paying for idle blue capacity. The deployment strategy record should specify the stability window duration and the rationale — and should be reconsidered when the service's incident response data shows the median time-to-detection for deployment-caused issues.

Canary deployment requires weighted routing infrastructure: a load balancer or service mesh capable of splitting traffic by percentage to different backend versions simultaneously. Standard Application Load Balancers support weighted target groups. NGINX and Envoy support traffic splitting configuration. Kubernetes service meshes (Istio, Linkerd) provide canary traffic splitting through traffic management resources. The complexity cost is real: the routing infrastructure must be configured, the canary weight must be managed (either manually or by a progressive delivery controller like Flagger or Argo Rollouts), and the automated abort criterion must be wired to the routing infrastructure so that an abort actually removes canary traffic, not just sets a weight parameter. A canary implementation that requires a human to manually set the weight to 0 on abort is not a reliable safety net under incident pressure. The deployment strategy decision record should specify the canary infrastructure stack and the automated abort wiring before the first canary deployment, not after the first manual abort fails.

Four AI chat session types that embed deployment strategy decisions without documenting them

The founding "how do I deploy without downtime?" session is where the deployment model is selected. The engineer's question is operational — they want to deploy their application without a maintenance window. The AI's answer is a working implementation: a Kubernetes Deployment manifest with RollingUpdate strategy, a Terraform module for blue/green with an ALB target group switch, or a Helm values file with canary weight parameters. The implementation is the answer to "how do I do this?" not "what are the constraints of this model?" The constraints — backward-compatible migrations for rolling, smoke test surface requirements for blue/green, automated abort criterion for canary — are not part of the implementation answer. They are part of the decision rationale that should be in the ADR but is not, because no ADR was written. The engineer has the working deployment configuration and moves on.

The migration debugging session is where the rolling deployment constraint is discovered. "My database migration is causing errors in some pods" leads to a diagnosis that old pods are running against the new schema. The AI explains backward compatibility and the expand-migrate-contract pattern. The engineer fixes the immediate migration. But the constraint is not written into the deployment strategy record — it is fixed in this specific migration and forgotten as a system-wide requirement. The next engineer who writes a non-backward-compatible migration has the same conversation with an AI six months later. The constraint is rediscovered, not inherited. Each rediscovery is an incident.

The "deployment took down production" postmortem session is where blue/green gaps are discovered. "Our smoke tests passed but production failed immediately after the load balancer flip" leads to analysis of the gap between the smoke test scenarios and the production failure mode. The AI helps diagnose the specific failure — stale credentials, configuration drift, a path not covered by smoke tests — and recommends adding a specific test or validation step. The recommendation is implemented for the specific failure mode. But the structural gap — that the smoke test suite must be periodically audited against the current production surface, and that production credentials must be validated as part of the pre-flip checklist — is not written into the deployment strategy record. The next configuration drift failure reaches production before the smoke test catches it.

The "how do I do a staged rollout?" session is where canary is adopted without the abort criterion being designed. The engineer wants to validate a high-risk change against a subset of users. The AI provides an Argo Rollouts analysis template or an NGINX weighted upstream configuration. The canary is implemented. The first few canaries go well because the engineer watches them manually and aborts or promotes based on visual inspection of a dashboard. Six months later, a canary that should have been aborted is promoted because the engineer observing it made a judgment call that the early error rate was within noise — and the error rate that was within noise in the first five minutes grew to 8% two hours into the rollout as production data edge cases accumulated. The automated abort criterion that would have caught this was never configured because the first few canaries worked without it. The deployment strategy record did not specify the abort criterion as a requirement. It was optional until it was not.

Five sections the deployment strategy decision record should address

1. Deployment model selection and rationale

Document the deployment model chosen and the rationale for the choice at decision time. The rationale should reference the specific properties that drove the selection: rollback speed requirement (how quickly must production be restored after a failed deployment?), production validation requirement (must the new version be validated against real user traffic before full rollout, or is synthetic pre-deploy testing sufficient?), infrastructure cost constraint (is a permanently warm second environment feasible, or must deployment infrastructure be on-demand?), and schema migration complexity tolerance (does the team have the operational discipline to maintain backward-compatible migrations consistently, or does the deployment model need to reduce this constraint?). Record the alternatives considered: if rolling was chosen over blue/green, document why the rollback speed trade-off was acceptable. If blue/green was chosen over canary, document why the production validation surface of smoke tests was considered sufficient. The rationale is the decision. The Kubernetes manifest or Terraform module is the implementation of the decision. The implementation without the rationale is code; the rationale without the implementation is a document. Both are required for the record to be useful when the deployment strategy needs to change.

The CI/CD pipeline decision record is the adjacent record: the pipeline covers how code changes are built, tested, and validated before they reach the deployment stage. The deployment strategy record covers what happens at the deployment stage itself — how the validated artifact is released to production instances. The two records are complementary and should reference each other. A CI/CD pipeline that produces a validated artifact but deploys it via a rolling update that lacks backward-compatible migration discipline is producing reliable artifacts and releasing them unreliably. A CI/CD pipeline that produces artifacts with comprehensive test coverage deployed via blue/green with a minimal smoke test suite is validating the code but not validating the production environment the code runs in. The production quality guarantee requires both records to be complete.

2. Backward compatibility constraint and migration discipline

For rolling deployments, document the backward-compatibility constraint explicitly and without qualification: every database schema change must be backward-compatible with the previous application version, and this requirement is non-negotiable for the lifetime of the system under the rolling deployment model. Document the expand-migrate-contract pattern as the required approach for any migration that is not trivially backward-compatible (adding a nullable column, adding an index). Provide concrete examples of safe and unsafe migration types. Specify the review requirement: each database migration should include an explicit backward-compatibility assessment in the pull request, not as a best practice but as a mandatory checklist item before the migration is applied to production. This assessment can be brief — "adds nullable column, safe for rolling" or "renames column, requires three-phase expand-migrate-contract" — but it must exist. Without a per-migration assessment, the constraint is a policy that engineers follow until they forget it, then rediscover in an incident.

For blue/green deployments, document the pre-flip migration sequencing requirement: schema changes that are backward-compatible with both old and new code are applied before the flip; schema changes that are only compatible with new code are applied after the flip, within the stability window. Specify the rollback behavior for post-flip migrations: if a rollback is required within the stability window, any post-flip migrations that are incompatible with the old code version must be reverted before the load balancer flip back to blue. If post-flip migrations cannot be easily reverted (because they've applied business-critical data transformations), rollback is no longer simple. The deployment strategy record should specify whether any migration is considered "no-rollback" — i.e., once applied, the system cannot roll back to the previous version without data loss — and what process is required before applying such a migration.

3. Pre-deploy validation surface and smoke test requirements

Document the pre-deploy validation surface: what must be validated before the deployment proceeds, and what the validation must cover. For blue/green, the smoke test suite is the primary validation. The record should specify what the smoke test suite is required to cover: all application entry points for the primary user flows, all external API integrations with production or production-equivalent credentials, all environment-specific configuration (production credentials, not test credentials), and any flow that was the cause of a previous deployment failure. The last category is important: every production deployment failure that smoke tests missed should result in a smoke test addition. Without this requirement, the smoke test suite validates what the team thought about at test-writing time, not what has actually gone wrong in production.

For canary deployments, document the canary parameters: the canary traffic percentage, the observation window duration, the automated abort criterion, and the automated promotion criterion. The abort criterion should be derived from the SLO baseline: the canary is aborted if the error budget burn rate on the canary backend exceeds a defined threshold (for example, 14x the allowable burn rate over a 5-minute window). The promotion criterion should be the absence of abort signals after the observation window completes. Both the abort and promotion should be automated where possible: manual promotion requires an engineer to approve every deployment, which creates a bottleneck and an accumulation of pending promotions during busy periods. The observability strategy decision record should provide the instrumentation foundation that makes per-version error rate, latency, and saturation metrics available for the automated abort signal.

For all deployment models, document the production credential validation procedure: a periodic audit of production credentials, external API keys, and environment-specific secrets that are required for production operation but may not be exercised by automated smoke tests. The frequency of this audit should be based on the rotation policy for each credential type. Credentials with a 90-day rotation policy should be validated before any deployment that falls within 14 days of the rotation deadline. The secrets management decision record covers credential rotation policy and the secret store architecture. The deployment strategy record should reference it to define the pre-deploy credential check requirement.

4. Rollback procedure and stability window

Document the rollback procedure for each deployment model as a concrete step sequence, not as a policy statement. "We can roll back deployments" is not a rollback procedure. The rollback procedure for rolling deployments is: pause the current rollout (kubectl rollout pause deployment/name), assess whether a rollback is required, execute rollback (kubectl rollout undo deployment/name --to-revision=N), monitor rollback progress (kubectl rollout status deployment/name), verify health after rollback completion. Include the expected duration for each step. Include the specific command for the production cluster (not a generic kubectl command). Include the requirement to notify the incident channel at rollback initiation, because a rollback that is executed silently produces a confused on-call team when the deployment state changes unexpectedly.

For blue/green deployments, document the stability window: the duration after the load balancer flip during which the blue environment is kept warm and the rollback is instantaneous. Document what happens after the stability window: is the blue environment terminated, or kept warm at reduced capacity? If terminated, what is the estimated time to re-provision blue for a post-stability-window rollback? Document the signals that should trigger a rollback within the stability window: a specific error rate threshold, a specific latency percentile breach, a customer-facing report of a critical issue, or a manual judgment call by the on-call engineer. Without defined rollback triggers, the stability window is time during which the team could roll back easily but doesn't know whether to.

The stability window duration should be informed by the incident response data: what is the median time-to-detection for deployment-caused issues in the current system? If deployment-caused issues are typically detected within 10 minutes, a 15-minute stability window provides meaningful coverage. If deployment-caused issues are typically detected within 60 minutes (because they require specific user behavior patterns that take time to accumulate), a 15-minute stability window provides false confidence. Track the time-to-detection distribution for deployment-caused incidents in the system's postmortem log, and calibrate the stability window against the 90th percentile time-to-detection, not the median. The tail is where the deployments that failed slowly live.

5. Multi-region deployment sequencing

For systems deployed across multiple geographic regions, the deployment strategy record must specify the region deployment sequence and the promotion criteria for advancing from one region to the next. The simplest safe sequence is serial: deploy to region 1 (the canary region), observe for a defined window, then deploy to region 2, observe, then deploy to the remaining regions. The canary region should be the region with the lowest traffic (to minimize user impact from failures) or the region with the most representative traffic mix (to maximize the chance of catching issues). Specify which region is the canary region and why — the rationale matters because a new engineer who sees the staging promotion sequence might reorder it for apparent efficiency without understanding that the canary region was chosen deliberately.

Document the abort criterion for multi-region promotions: what signal causes the promotion to region 2 to be paused, and who has the authority to abort or continue. For automated progressive delivery controllers (Argo Rollouts, Spinnaker), the abort criterion is a pipeline stage gate condition. For manual multi-region deployments, the abort criterion is the on-call engineer's assessment — which means the engineer must know what to look for. The deployment strategy record should specify the minimum observation window per region, the specific metrics to evaluate (error rate, latency P99, saturation), and the threshold values that constitute a pass/fail for promotion. Without these specifications, multi-region deployment sequencing is "deploy to region 1, watch it for a while, deploy to region 2 when it looks okay" — which is not a reproducible procedure and produces inconsistent promotion decisions across engineers and incidents.

The multi-region deployment decision record covers the full regional architecture: traffic routing, data residency, failover behavior, and the trade-offs between active-active, active-passive, and read-replica regional models. The deployment strategy record's multi-region sequencing section references the regional architecture by specifying the deployment order as a function of traffic weight, data criticality, and failover relationship between regions. A region that serves as the failover target for another region should not be the canary region, because a deployment failure in the canary region would temporarily degrade the failover capability for the region it protects. This interaction between the deployment sequencing decision and the failover architecture decision is invisible unless both decision records exist and reference each other.

The infrastructure as code strategy decision record should specify whether deployment strategy parameters — rolling update configuration, blue/green target group weights, canary analysis templates — are managed in version control or in runtime configuration. The most common failure mode here is deployment strategy configuration that drifted from the original decision: someone changed the maxSurge parameter on a specific deployment from 1 to 25% to speed up a deploy during an incident, and the change was never reverted or documented. The Kubernetes manifest in version control says maxSurge 1; the live deployment object says maxSurge 25%. The deployment model that engineers believe they are running is not the deployment model actually running. All deployment strategy configuration should be managed in version control, applied via the same CI/CD pipeline as application code, and never modified directly on running infrastructure outside of an explicitly declared emergency change procedure.

The WhyChose extractor can surface the original deployment strategy sessions from AI chat history — the Claude or ChatGPT conversation where the founding engineer asked "how do I deploy without downtime?" and received a rolling update manifest, or the conversation where the team evaluated blue/green and decided the cost was acceptable. Those sessions contain the constraints that were visible at the time: the team size, the infrastructure budget, the rollback requirement that was the primary driver. When the deployment strategy needs to change — because the system has grown too complex for rolling deployment's backward-compatibility discipline, or because the rollback speed requirement has tightened with an enterprise SLA, or because the production validation surface of smoke tests has been revealed as insufficient by an incident — recovering the original constraints makes the migration planning faster. The team does not have to reconstruct why rolling was chosen before they can evaluate whether the reasons that led to rolling still justify it, or whether those reasons have changed enough to justify the investment in blue/green or canary infrastructure.