Zero downtime blue/green deployments with Amazon API Gateway

Modern applications require deployment strategies that minimize downtime and reduce risk. Blue/green deployment is a strategy that reduces downtime and risk by running two identical production environments called “blue” and “green”. At any given time, only one environment serves live production traffic while the other remains idle. This strategy provides immediate fallback to the previous stable version if issues arise after the new deployment. Let’s say a company is deploying a new version of its application. The following diagram shows the blue/green deployment strategy they are using.

As shown in the preceding diagram, current production traffic is served by the blue environment. During deployment of the new version of the application, the following sequence of activities happens:

1. Deploy the new version of the application: Deploy the new version to the green environment.
2. Test thoroughly: Test the new version in the green environment by invoking the API invoke URL from API Gateway. This does not affect production traffic, which continues to be served by the blue environment.
3. Switch traffic: After you have thoroughly tested the green environment, redirect all production traffic from the blue to the green environment.
4. Monitor and take any necessary action: Continue to monitor the green environment as it serves production traffic. Keep the blue environment ready for immediate rollback to the previous stable version, in case any issues arise in the green environment. At this point, one of two possible outcomes happens:
   1. If you identify any issues with the green environment in production, roll back to the previous stable version of the blue environment and fix the green environment before retrying.
   2. If you observe no issues with the green environment, decommission the blue environment. The green environment is now the new blue environment, the environment with stable production version of the application serving live traffic.

In this post, you learn how to implement blue/green deployments by using Amazon API Gateway for your APIs. For this post, we use AWS Lambda functions on the backend. However, you can follow the same strategy for other backend implementations of the APIs. All the required infrastructure is deployed by using AWS Serverless Application Model (AWS SAM).

Solution overview

As you follow along with this post, you will implement the following blue/green deployment architecture by using API Gateway custom domain API mapping. You use API mappings to connect API stages to a custom domain name. After you create a domain name and configure DNS records, you use API mappings to send traffic to your APIs through your custom domain name.

As shown in the preceding diagram, the blue/green deployment architecture includes four primary AWS services – Amazon Route 53, Amazon API Gateway, AWS Lambda functions, and AWS Certificate Manager (ACM). When you send a request to the API, the Route 53 resolves the domain to the API Gateway custom domain. API Gateway handles HTTPS termination by using a configured ACM certificate. API Gateway examines the incoming request path and headers to route the request to the active environment.

You first set up the blue environment along with the Route 53 DNS configuration, API Gateway custom domain mapping, ACM and test it with Route 53 URL. This is your production environment serving live traffic. After that, deploy a new version of the application in the green environment and test it by invoking the API invoke URL from API Gateway while live traffic is still being served from the blue environment. Then, switch the traffic from the blue environment to the green environment by using API Gateway custom domain API mapping. This ensures that there is no change in the external (client-facing) API custom domain URL. Live traffic is now served by the green environment. If you observe any issues during this time, you can quickly roll back to the blue environment and fix the green environment. If the green environment is stable, you can decommission the blue environment.

This post uses two separate regional API endpoints to simulate blue/green environments and traffic routing between them but you can this same architectural pattern using single API endpoint with two stages representing blue and green environments.

Prerequisites

Complete the following prerequisites before you start setting up the solution:

• Make sure you have access to an AWS account through the AWS Management Console and AWS Command Line Interface (AWS CLI). Your AWS Identity and Access Management (IAM) user must have permissions to make the necessary AWS service calls and manage the AWS resources mentioned in this post. When providing permissions to the IAM user, follow the principle of least privilege.
• Install and configure the AWS CLI. If you are using long-term credentials like access keys, follow manage access keys for IAM users and secure access keys for best practices.
• Install Git.
• Install AWS SAM.
• Create a Route 53 public hosted zone for your custom domain.
• Create an ACM public certificate for your custom domain in the target AWS Region.

Set up and test the solution

Note that this is a sample project to understand the concept and not for direct usage in production. The sample project contains three APIs.

• Health GET API to know the current health of the environment and which environment the request was served from.
• Pets GET API to get the list of available pets.
• Order POST API to place a pet order.

Follow the steps below to setup blue/green deployment and test it.

1. Clone the repository and navigate to the directory (all commands run from here)
   Clone the GitHub repository in a new folder and navigate to the stacks folder.

   git clone https://github.com/aws-samples/sample-blue-green-deployment-with-api-gateway.git
   cd sample-blue-green-deployment-with-api-gateway/stacks

2. Deploy the blue environment
   You will first setup the blue environment. Run the following commands to deploy the blue environment:

   sam build -t blue-stack.yaml
   sam deploy -g -t blue-stack.yaml

   Enter the following details:

   • Stack name: The CloudFormation stack name (for example, blue-green-api-blue)
   • AWS Region: A supported AWS Region (for example, us-east-1)
   • BlueLambdaFunction has no authentication. Is this okay?: y
   • SAM configuration file: blue-samconfig.toml

   Keep everything else set to their default values. You will use the SAM deploy output for the subsequent steps. Going forward, you can run the following command to deploy the blue environment resources:

   sam build -t blue-stack.yaml
   sam deploy -t blue-stack.yaml --config-file blue-samconfig.toml

3. Test the blue environment

   Run the following commands to test the blue environment after replacing ApiEndpoint with BlueApiEndpoint from the SAM deploy output in each case. First, test Health check API to know the health of the environment. Run the following command.

   curl --request GET \ 
   --url https://<ApiEndpoint>/health

   Sample response:

   {
     "status": "healthy", 
     "environment": "blue", 
     "version": "v1.0.0", 
     "timestamp": "2025-09-05T13:11:11.248267Z"
   }

   Second, test the pets GET API request to get the list of available pets. Run the following command.

   curl --request GET \ 
   --url https://<ApiEndpoint>/pets

   Sample response:

   {
     "environment": "blue",
     "version": "v1.0.0",
     "pets": [
       {
         "id": 1,
         "name": "Buddy",
         "category": "dog",
         "status": "available"
       },
       {
         "id": 2,
         "name": "Whiskers",
         "category": "cat",
         "status": "available"
       },
       {
         "id": 3,
         "name": "Charlie",
         "category": "bird",
         "status": "pending"
       }
     ]
   }

   Now, test create order POST API to place an order for a pet:

   curl --request POST \
     --url https://<ApiEndpoint>/orders \
     --header 'content-type: application/json' \
     --data '{
     "id": 1,
     "name": "Buddy"
   }'

   Expected response:

   {
     "confirmationNumber": "ORD-3251C0F4", 
     "environment": "blue",
     "version": "v1.0.0",
     "timestamp": "2025-09-05T13:16:04.703666Z", 
     "data": 
     {
       "id": 1, 
       "name": "Buddy", 
       "status": "ordered"
     }
   }
   

   Check that the response contains the environment attribute set to blue and the version attribute set to v1.0.0

4. Deploy API Gateway custom domain pointing to the blue environment

   Run the following commands to deploy Amazon API Gateway custom domain with API mapping pointing to the blue environment created in the previous step.

   sam build -t custom-domain-stack.yaml
   sam deploy -g -t custom-domain-stack.yaml

   Enter the following details:

   • Stack name: (for example, blue-green-api-custom-domain)
   • AWS Region: A supported AWS Region (for example, us-east-1)
   • PublicHostedZoneId: The Route 53 public hosted zone ID (for example, ABXXXXXXXXXXXXXXXXXYZ)
   • CustomDomainName: The Route 53 domain name (for example, api.example.com)
   • CertificateArn: The ACM certificate ARN (for example, arn:aws:acm:us-east-1:123456789012:certificate/abc123)
   • ActiveApiId: The value of the BlueApiId output from the blue-stack deployment
   • ActiveApiStage: The value of the BlueApiStage output from the blue-stack deployment
   • SAM configuration file: custom-domain-samconfig.toml

   Keep everything else to their default values. You will use the SAM deploy output for the subsequent steps. At this point the production (live) traffic is routed to blue environment.

5. Test the production (live) traffic which is routed to blue environment

   Follow the test method mentioned in step 3 to test the production environment, but replace ApiEndpoint with CustomDomainUrl. Check that the production environment response contains the environment attribute set to blue and the version attribute set to v1.0.0

6. Deploy the green environment

   You will now deploy the v2.0.0 of the application on green environment. Run the following commands to deploy the green environment:

   sam build -t green-stack.yaml
   sam deploy -g -t green-stack.yaml

   Enter the following details:

   • Stack name: (for example, blue-green-api-green)
   • AWS Region: Select the same Region as the blue environment (for example, us-east-1)
   • GreenLambdaFunction has no authentication. Is this okay?: y
   • SAM configuration file: green-samconfig.toml

   Keep everything else to default values. You will use the SAM deploy output for the subsequent steps. Going forward, you can run the following commands to deploy the green environment.

   sam build -t green-stack.yaml
   sam deploy -t green-stack.yaml --config-file green-samconfig.toml
   

7. Test the green environment
   Follow the test method shown in step 3 to test the production environment, but replace ApiEndpoint with GreenApiEndpoint. Validate that the response contains the environment attribute set to green and the version attribute set to v2.0.0
8. Switch the live traffic to the green environment
   Run the following command to switch live traffic to the green environment:

   sam deploy -g -t custom-domain-stack.yaml  --config-file custom-domain-samconfig.toml

   Enter the following details:

   • Stack name: Keep it as it is.
   • AWS Region: Keep it as it is.
   • PublicHostedZoneId: Keep it as it is.
   • CustomDomainName: Keep it as it is.
   • CertificateArn: Keep it as it is.
   • ActiveApiId: The value of GreenApiEndpoint output from the green-stack deployment
   • ActiveApiStage: The value of GreenApiStage output from the green-stack deployment
   • SAM configuration file: Keep it as it is.

   Keep everything else at their default values.

9. Test the production environment (now green) again

   Follow the test method shown in step 3 to test the production environment (now green) again, and be sure to replace ApiEndpoint with CustomDomainUrl from SAM deploy output. Validate that the response now contains the environment attribute set to green and the version attribute set to v2.0.0. Note that it may take a minute or two for the change to be seen due to local DNS caching, during this time some of the traffic may be still served from the blue environment. After switching the live traffic to the green environment, if there is an issue, you can switch the live traffic back to the blue environment and fix the green environment. Depending on whether you need to roll back to the previous stable blue environment or decommission the blue environment when you no longer need it, follow either step 10 or 11.

10. (Option 1) Roll back to the blue environment, if necessary
    Run the following command to roll back to the blue environment, if necessary.

    sam deploy -g -t custom-domain-stack.yaml  --config-file custom-domain-samconfig.toml

    Enter the following details:

    • Stack name: Keep it as it is.
    • AWS Region: Keep it as it is.
    • PublicHostedZoneId: Keep it as it is.
    • CustomDomainName: Keep it as it is.
    • CertificateArn: Keep it as it is.
    • ActiveApiId: Value of BlueApiEndpoint output from the blue-stack deployment.
    • ActiveApiStage: The value of BlueApiStage output from the blue-stack deployment.
    • SAM configuration file: Keep it as it is.

    Keep everything else to their default values. Live traffic is switched to the blue environment. You can confirm that by following step 3.

11. (Option 2) Decommission the blue environment when you no longer need it
    Run the following command to decommission (delete) the blue environment when you no longer need it. Replace blue-stack-name with your blue deployment stack name:

    sam delete --stack-name <blue-stack-name> --no-prompts

Clean up

To avoid costs, remove all resources created along this post once you’re done.

Run the following command after replacing the <placeholder> variables to delete the resources you deployed for this post’s solution:

# Delete all stacks (in reverse order)
# Delete custom domain
sam delete --stack-name <api-custom-domain-stack-name> --no-prompts
# Delete green stack
sam delete --stack-name <green-stack-name> --no-prompts
# Delete blue stack, if already not deleted in step 10
sam delete --stack-name <blue-stack-name> --no-prompts

Conclusion

Blue/green deployments with API Gateway provide a robust, scalable solution for zero-downtime deployments that deliver significant technical and operational advantages. This post’s solution architecture enables traffic switching at the API Gateway level while maintaining complete isolation between the blue and green environments to prevent interference. The solution offers immediate rollback capabilities for quick issue resolution and supports comprehensive testing through production-like validation before any traffic switching occurs.

Following this solution you can build a solid foundation for production blue/green deployments for your serverless microservice architecture that maintains the flexibility to adapt to your specific requirements while ensuring reliability, scalability, and operational excellence. To learn more about serverless architectures see Serverless Land.