How to Run a Blue-Green Deployment in 7 Steps

A blue-green deployment keeps two production environments that are as identical as possible, sends all traffic to one of them, and releases a new version by switching the router to the other, so switching back is the rollback. This guide runs a blue-green deployment in 7 steps: define the environment boundary, build the green environment, make database changes work for both versions, test green before it takes traffic, switch the router, roll back or keep blue for the next release, and release features inside the build with feature flags.

The steps apply to web services and APIs where a router or load balancer decides which environment receives requests. Software installed on users’ devices is outside the scope.

What blue-green deployment means

Martin Fowler’s note BlueGreenDeployment (March 1, 2010) describes the cut-over from the final stage of testing to live production as one of the challenges of automating deployment, because the cut-over has to happen quickly to keep downtime low. In the note, one environment, blue, is live while the team runs the final stage of testing for the new release in the other environment, green. Once the software works in green, the team switches the router so that all incoming requests go to green, and blue becomes idle. Fowler credits the name to Daniel Terhorst-North and Jez Humble together.

AWS’s whitepaper Blue/Green Deployments on AWS, which AWS now labels as a historical reference whose content might be outdated, describes the same idea as shifting traffic between two identical environments that run different versions of an application. In the whitepaper, the blue environment runs the current version and serves production traffic, the green environment runs the new version, and production traffic moves from blue to green once green is ready. The whitepaper contrasts this with the traditional fix for a failed deployment, redeploying an earlier stable version, which takes time and overwrites the faulty version before anyone can debug it in place.

Fowler describes the two environments trading roles on every release.

Stage of the cycle	Blue environment	Green environment
Before the release	Live, serving all requests	Staging, running the final tests of the new version
After the switch	Idle, kept as the previous version for rollback	Live, serving all requests
Next release	Staging, running the final tests of the next version	Live until the router switches back to blue

Fowler also points out that the switch is the same basic mechanism as a hot standby, so each release exercises the team’s disaster-recovery procedure.

Before you run a blue-green deployment

Six inputs decide whether the switch and the switch back work under production load.

• A router or load balancer that can send all incoming requests to either environment.
• Automated provisioning, so the two environments stay as identical as possible.
• A database plan for schema changes that both the old and the new version can use.
• Final tests that run against green before it receives production traffic.
• A decision on transactions that reach green if the team switches back to blue.
• A budget for running two production environments at the same time.

How to run a blue-green deployment in 7 steps

1. Define the environment boundary

Decide what the switch moves: the whole application, one service, or the web and domain layers in front of a shared database. The AWS whitepaper lists the factors that set the environment boundary.

Factor	What to check
Application architecture	Dependencies, and whether components are loosely or tightly coupled
Organization	Speed and number of iterations
Risk and complexity	Blast radius and impact of a failed deployment
People	Expertise of the teams
Process	Testing and QA, rollback capability
Cost	Operating budgets and additional resources

The whitepaper says applications built as microservices can have smaller environment boundaries because of their loose coupling and well-defined interfaces, while a monolithic application needs a wider scope and more extensive testing.

2. Build the green environment as a copy of blue

Fowler says the two environments need to be different but as identical as possible: different pieces of hardware, different virtual machines on the same or different hardware, or one operating environment partitioned into separate zones with separate IP addresses. The AWS whitepaper recommends automation wherever possible to streamline the process, reduce human error, and control costs, and notes that a green environment launched on new resources depends less on the state and configuration of an existing environment.

Provision both environments from the same definitions, so a difference between blue and green comes from the release and not from drift between the environments.

3. Make database changes work for both versions first

Fowler calls databases a frequent challenge for blue-green deployment, especially when a new version needs a schema change. Fowler’s approach separates schema changes from application upgrades: first apply a database refactoring that supports both the new and the old version, deploy it, and confirm that everything works, so the team has a rollback point. Then deploy the new version of the application, and after the upgrade has settled, remove the database support for the old version. Fowler added the database paragraph to the note on June 5, 2015.

4. Test green before it takes production traffic

Fowler runs the final stage of testing in green while blue stays live. The AWS whitepaper describes two ways to validate green: send test traffic before production traffic, or send a very small fraction of production traffic to better reflect real users, which the whitepaper calls canary analysis or canary testing. If green does not operate as expected, blue is unaffected, and the team routes traffic back to blue.

Write down the checks green must pass before the switch, such as health checks, a smoke test of the main user paths, and the error rate of the canary share of traffic.

5. Switch the router and watch the new environment

Switch the router so that all incoming requests go to green, then watch the same metrics the team watches for blue. Fowler notes a variation in which a project switched by bouncing the web server instead of changing the router. The AWS whitepaper says the impact of a problem is limited to the time between detecting the issue in green and shifting traffic back to blue, and, while traffic shifts gradually, to the share of traffic that reached green.

Plan for transactions that green receives while it is live. Fowler lists two options: feed transactions to both environments so blue stays a usable backup, or, before the cut-over, switch the application to a mode that serves reads and rejects writes, run it that way for a while, and then allow writes again.

6. Roll back by switching back, or keep blue for the next release

If green fails, switch the router back to blue. The AWS whitepaper says the team can roll back to blue at any time during the deployment process. Once green is stable, Fowler uses blue as the staging environment for the final tests of the next release, and the next release switches from green to blue.

For cloud deployments, the AWS whitepaper describes scaling green out as it receives more traffic, scaling blue in, and decommissioning blue after a successful deployment to stop paying for its resources. Decommissioning blue ends the switch-back path, so keep blue until the new version has run under production load for the team’s rollback window.

7. Release features inside the build with feature flags

A blue-green switch moves every request to the new build at once, so every change in the build reaches every customer at the same moment. To release one feature to some customers without another environment switch, deploy the feature’s code path switched off and turn it on with a feature flag. Pete Hodgson’s article Feature Toggles (October 9, 2017) describes release toggles, which let incomplete code paths ship to production as latent code that may never be turned on. If blue and green read the same flag rules, a switch back to blue restores the old build and leaves the current flag rules in place, so record flag changes separately from deployments.

In Loglune, the SDK evaluates the published flag version in your own process or at the edge, and every flag edit is appended to the change history as a change event with the customer, the actor, the time, the target flag, and the values before and after. When a customer reports a problem after the switch, pick the customer and the time T of the report. Loglune rebuilds the flag state at T from the change history and delivers it in reproduction mode to a development, CI, or staging environment, and one delivery counts as one reproduction. The rebuilt state shows which flag-controlled code path the customer was on, which tells the team whether to switch the flag off or switch the router back. Loglune reproduces the flag evaluation, not the root cause in application code, and does not route traffic between environments. The walkthrough on reproducing a bug that affects one customer covers the path from a report to a reproduction.

Choosing the blue-green deployment strategy

Blue-green deployment, canary deployment, and flag rollouts move different things, and each has its own rollback.

Strategy	What moves	Rollback	Source
Blue-green deployment	All requests from one production environment to an identical second one	Switch the router back	Fowler, AWS whitepaper
Canary deployment	A share of traffic or users to the new version, before everyone gets it	Route the canary users back to the old version	Sato
Flag rollout	A share of users to a new code path inside one deployed build	Lower the percentage or switch the flag off	Hodgson

Danilo Sato’s note Canary Release on martinfowler.com describes rolling out a change to a small subset of users before rolling it out to everybody. Choose blue-green when the team wants a fast switch of the whole environment and a fast switch back, and can pay for two environments. Choose a canary when the team wants a signal from a small share of production before everyone gets the change. The AWS whitepaper combines the two by sending a very small fraction of production traffic to green before the full switch.

Editorial example (not a customer case): an invoicing release with a blue-green switch and a flag

The table follows one release of an invoicing service. Times, versions, and names are illustrative.

Time	Router	Blue	Green	new-invoice-layout flag
9:00 a.m.	Blue	v17, live	v18, final tests	Off
9:40 a.m.	Green	v17, idle for rollback	v18, live	Off
10:30 a.m.	Green	v17, idle	v18, live	On for 10% of customers, change event recorded
11:15 a.m.	Green	v17, idle	v18, live	On for 10%, and a customer reports wrong invoice totals
11:35 a.m.	Green	v17, idle	v18, live	Customer’s flag state at 11:15 a.m. rebuilt in staging, showing the new layout
11:40 a.m.	Green	v17, idle	v18, live	Off, change event recorded

The rebuilt flag state showed that the reporting customer was on the new invoice layout, so the team switched the flag off and kept v18 live. Switching the router back to v17 would also have reverted the other changes in v18.

Troubleshooting blue-green deployments

• Orders placed in green disappear after a switch back: plan for transactions that reach green, by feeding transactions to both environments or by rejecting writes for a while before the cut-over, as Fowler describes.
• Blue fails after a switch back because of a new schema: apply schema changes that support both versions before the application upgrade, as Fowler’s database paragraph describes.
• Green passes its final tests and fails under production traffic: send a very small fraction of production traffic to green before the full switch, the canary analysis the AWS whitepaper describes.
• Blue and green behave differently with the same build: provision both environments from the same automation, because Fowler asks for environments as identical as possible.
• Running two environments costs too much: scale blue in as traffic moves to green and decommission it after the rollback window, as the AWS whitepaper describes for cloud deployments.
• A customer report arrives after both a switch and a flag change: rebuild that customer’s flag state at the reported time to see whether the flag-controlled code path or the build was involved.

FAQ

What is blue-green software deployment?

Blue-green software deployment is the same technique as blue-green deployment: two production environments, one of them live, and a router switch that releases the new version. Fowler’s note and the AWS whitepaper both describe the switch back to the old environment as the rollback.

Does blue-green deployment need two databases?

Blue-green deployment does not always need two databases. Fowler describes a variation that uses the same database and makes the blue-green switch for the web and domain layers, with schema changes applied first in a form that both versions can use.

Is blue-green deployment the same as a canary deployment?

Blue-green deployment and canary deployment move traffic differently. In Fowler’s note, the router sends all incoming requests to green at once, while a canary release rolls a change out to a small subset of users first. The AWS whitepaper calls validating green with a very small fraction of production traffic canary analysis or canary testing, which combines the two.

Why is blue-green deployment less common on premises?

The AWS whitepaper says blue-green deployment is not commonly used in traditional on-premises environments because of the cost and effort of provisioning additional resources, and that cloud computing makes the approach easier and more cost-effective to adopt.

Deciding when a blue-green deployment is worth running

Run a blue-green deployment when the service needs a fast full cut-over and a fast full rollback, and the team can run two production environments and keep them alike. Pair the switch with feature flags for changes that should reach some customers first, and keep the flag change history, so a report after the switch can be traced to the flag state one customer had at that moment.