789 reads

Building Maintenance Mode for your API Gateway Using Terraform

by Omry HayJuly 11th, 2020

Too Long; Didn't Read

Building Maintenance Mode for your API Gateway using Terraform on API Gateway. When the API is in maintenance it should return “503 Service Unavailable” response. This led us to the following solution: create a new API Gateway dedicated to the maintenance mode. This API will use a mock integration and return the same response for all endpoints using proxy resource. This mocked API will co-exist with our real API. We will use custom domain and change the base mapping between the real API and the mocked one. We are using ANY method together with “proxy+” to achieve the ability to cover all resources with a simple configuration.

Companies Mentioned

featured image - Building Maintenance Mode for your API Gateway Using Terraform

In my previous blog post, I went through how to create a maintenance mode page for your application, and how to implement it using Terraform and github pages. But the website is just one part of an Application, and often there’s also a public (or private) API that also needs to have a maintenance mode. Let’s see how we can do that using Terraform on API Gateway.

Architecture

As previously mentioned, we host all of our infrastructure on AWS, with a clear separation between the Application and the API:

The front end is a React application, hosted on S3 with CloudFront as a CDN.
The Backend services are mostly Serverless using AWS Lambda with API Gateway that manages our public API.
DNS is managed by Route 53.

Implementing a Solution

Beyond the requirements for our webpage maintenance mode, we had one new one: When the API is in maintenance it should return “503 Service Unavailable” response with an informative message. This led us led us to the following solution:

Create a new API Gateway that will be dedicated to the maintenance mode
This API will use a mock integration
It will return the same response for all endpoints using proxy resource
This mocked API will co-exists with our real API.
We will use custom domain and change the base mapping between the real API and the mocked one.

Based on that, let’s see the Terraform code in action:

Mocked API Gateway

Looking at the code you are able to see that we are using ANY method together with “{proxy+}” to achieve the ability to cover all resources with a simple configuration, and using the response template to generate the “503 Service Unavailable” response with a clear message to the end user.

resource "aws_api_gateway_rest_api" "maintenance_mode_api" {
  name        = "maintenance-mode-API"
  description = "This is my Maintenance mode API"
}

resource "aws_api_gateway_resource" "maintenance_mode_resource" {
  rest_api_id = aws_api_gateway_rest_api.maintenance_mode_api.id
  parent_id   = aws_api_gateway_rest_api.maintenance_mode_api.root_resource_id
  path_part   = "{proxy+}"
}

resource "aws_api_gateway_method" "maintenance_mode_method" {
  rest_api_id   = aws_api_gateway_rest_api.maintenance_mode_api.id
  resource_id   = aws_api_gateway_resource.maintenance_mode_resource.id
  http_method   = "ANY"
  authorization = "NONE"
}

resource "aws_api_gateway_integration" "maintenance_mode_integration" {
  rest_api_id          = aws_api_gateway_rest_api.maintenance_mode_api.id
  resource_id          = aws_api_gateway_resource.maintenance_mode_resource.id
  http_method          = aws_api_gateway_method.maintenance_mode_method.http_method
  type                 = "MOCK"
  timeout_milliseconds = 29000
  passthrough_behavior = "WHEN_NO_MATCH"
  request_templates = {
    "application/json" = <<EOF
    {"statusCode": 503}
EOF
  }
}

resource "aws_api_gateway_method_response" "maintenance_mode_response_503" {
  rest_api_id = aws_api_gateway_rest_api.maintenance_mode_api.id
  resource_id = aws_api_gateway_resource.maintenance_mode_resource.id
  http_method = aws_api_gateway_method.maintenance_mode_method.http_method
  status_code = "503"
}

resource "aws_api_gateway_integration_response" "maintenance_mode_integration_response" {
  rest_api_id = aws_api_gateway_rest_api.maintenance_mode_api.id
  resource_id = aws_api_gateway_resource.maintenance_mode_resource.id
  http_method = aws_api_gateway_method.maintenance_mode_method.http_method
  status_code = aws_api_gateway_method_response.maintenance_mode_response_503.status_code

  # Transforms the backend JSON response to XML
  response_templates = {
    "application/json" = <<EOF
#set($inputRoot = $input.path('$')) { "message" : "Sorry for the inconvenience but we are performing some maintenance at the moment. We will be back online shortly!" }
EOF
  }
}

resource "aws_api_gateway_deployment" "maintenance_mode_deployment" {
  depends_on  = [aws_api_gateway_integration.maintenance_mode_integration]
  rest_api_id = aws_api_gateway_rest_api.maintenance_mode_api.id
  stage_name  = "prod"
}

Now using a custom domain we can control the maintenance mode, so the base path mapping will either point to the real API and in case of a maintenance mode it will point to the mocked API.

resource "aws_api_gateway_domain_name" "domain_name" {
  certificate_arn = var.certificate_arn
  domain_name     = var.domain_name
}

resource "aws_api_gateway_base_path_mapping" "base_mapping" {
  api_id      = var.is_maintenance_mode ? aws_api_gateway_rest_api.maintenance_mode_api.id : aws_api_gateway_rest_api.api.id
  stage_name  = var.is_maintenance_mode ? aws_api_gateway_deployment.maintenance_mode_deployment.stage_name : aws_api_gateway_deployment.deployment.stage_name
  domain_name = aws_api_gateway_domain_name.domain_name.domain_name
  base_path   = "/"
}

Also in AWS, we want to ensure that Route53 is pointing in the custom domain we’ve created. As opposed to the application maintenance mode, here our custom domain switches on and off our maintenance mode and not our DNS record.

resource "aws_route53_record" "api_dns_record" {
  zone_id = var.route53_zone_id
  name    = var.route53_suffix_domain_name
  type    = "A"
  alias {
    name                   = aws_api_gateway_domain_name.domain_name.regional_domain_name
    zone_id                = aws_api_gateway_domain_name.domain_name.regional_zone_id
    evaluate_target_health = false
  }
}

⚠️ Pay attention that this Terraform code does not create the Route53 hosted zone, nor the SSL certificates — you need to complete those as appropriate for your own setup ⚠️

Deployment

Now that our system is all configured, all I have to do is change the Terraform variable of the maintenance mode to be true/false and deploy the environment (in our case via the env0 UI).

The complete template source code can be found in this github repo which includes all the Terraform code. We hope you find this useful, or get other ideas for more ways to use Terraform for your deployment workflows.

About env0

env0 lets your team manage their own environments in AWS, Azure and Google, governed by your policies and with complete visibility & cost management. You can learn more about env0 here and you can also try it out yourself.

Feel free to drop us your thoughts below!

Previously published at https://www.env0.com/blog/creating-a-maintenance-mode-for-your-api-gateway-with-terraform