View SourceRelease Notes

API Gateway Proxy Module

This module creates an API Gateway that can be used to expose your serverless applications running in AWS Lambda.

This module configures API Gateway to proxy all requests to the underlying Lambda function with basic path-based routing (but no control over HTTP method based routing, or other details). The Lambda function can contain any code that handles the requests from API Gateway: e.g., you can use a full web framework like Express, or you can write a handler with your own route handling logic, or whatever else you want.

This module does not provide a way to define individual routes, methods, etc in the API Gateway. If you need more control over the API Gateway settings, consider using the Serverless framework. We recommend using a framework like Serverless to avoid the verbose configuration of routing for API Gateway in Terraform.

Serverless architecture

note

If you are looking for a module to route different requests and methods to different Lambda functions, refer to the lambda-http-api-gateway module.

info

This module specifies configuration_aliases, requiring an aws provider configured for the us-east-1 region with the alias us_east_1 to be provided.

Features

• Expose serverless applications using API Gateway
• Proxy all requests from the gateway to the underlying applications

Learn

This repo is a part of the Gruntwork Infrastructure as Code Library, a collection of reusable, battle-tested, production ready infrastructure code. If you've never used the Infrastructure as Code Library before, make sure to read How to use the Gruntwork Infrastructure as Code Library!

Core concepts

• What is API Gateway?
• What is the difference between the different endpoint types?
• API Gateway Documentation: Amazon's docs on API Gateway covering core concepts such as security, monitoring, and invoking APIs.

Repo organization

• modules: the main implementation code for this repo, broken down into multiple standalone, orthogonal submodules.
• examples: This folder contains working examples of how to use the submodules.
• test: Automated tests for the modules and examples.

Deploy

If you just want to try this repo out for experimenting and learning, check out the following resources:

• examples folder: The examples folder contains sample code optimized for learning, experimenting, and testing (but not production usage).

Manage

Day-to-day operations

• How do I expose AWS Lambda functions using API Gateway?
• Can I expose additional lambda functions in a decentralized manner?
• How do I pass in the us_east_1 aws provider?

Reference

Inputs

Required

api_namestringrequired

Name of the API Gateway REST API.

lambda_functionsmap(string)required

Map of path prefixes to lambda functions to invoke. Any request that hits paths under the prefix will be routed to the lambda function. Note that this only supports single levels for now (e.g., you can configure to route foo and everything below that path like foo/api/v1, but you cannot configure to route something like api/foo/*). Use empty string for the path prefix if you wish to route all requests, including the root path, to the lambda function. Refer to the example for more info.

Optional

api_binary_media_typeslist(string)optional

List of binary media types supported by the REST API. The default only supports UTF-8 encoded text payloads.

Default:null

api_descriptionstringoptional

Description to set on the API Gateway REST API. If empty string, defaults to 'REST API that proxies to lambda function LAMBDA_FUNCTION_NAME'. Set to null if you wish to have an API with no description.

Default:""

api_endpoint_configurationobject(…)optional

Configuration of the API endpoint for the API Gateway REST API. Defaults to EDGE configuration.

Type Details

object({
    # The endpoint type. Must be one of EDGE, REGIONAL, or PRIVATE.
    type = string
    # Set of VPC Endpoint Identifiers to use when using a private endpoint.
    vpc_endpoint_ids = list(string)
  })

Default:null

api_key_sourcestringoptional

Source of the API key for requests. Valid values are HEADER (default) and AUTHORIZER.

Default:null

api_minimum_compression_sizenumberoptional

Minimum response size to compress for the REST API. Must be a value between -1 and 10485760 (10MB). Setting a value greater than -1 will enable compression, -1 disables compression (default).

Default:null

api_settingsanyoptional

Map of HTTP methods (e.g., GET, POST, etc - * for all methods) to the API settings to apply for that method. Refer to the terraform resource docs for available settings: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_method_settings#settings.

Type Details

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.

Default:{}

Examples

Example

   {
     GET = {
       metrics_enabled = true
       logging_level   = "INFO"
     }
   }

certificate_arnstringoptional

ARN of the ACM certificate you wish to use for the bound domain name. When null, the module will look up an issued certificate that is bound to the given domain name, unless certificate_domain is set.

Default:null

certificate_domainstringoptional

The domain to use when looking up the ACM certificate. This is useful for looking up wild card certificates that will match the given domain name.

Default:null

custom_tagsmap(string)optional

Map of tags (where the key is the tag key and the value is tag value) to apply to the resources in this module.

Default:{}

deployment_descriptionstringoptional

Description to apply to the API Gateway deployment. This can be useful to identify the API Gateway deployment managed by this module.

Default:null

deployment_idstringoptional

An arbitrary identifier to assign to the API Gateway deployment. Updates to this value will trigger a redeploy of the API Gateway, which is necessary when any underlying configuration changes. This is the only way to trigger a redeployment of an existing API Gateway if force_deployment = false.

Default:""

domain_base_pathstringoptional

Path segment that must be prepended to the path when accessing the API via the given domain. If omitted, the API is exposed at the root of the given domain.

Default:null

domain_namestringoptional

Full domain (e.g., api.example.com) you wish to bind to the API Gateway endpoint. Set to null if you do not wish to bind any domain name.

Default:null

enable_execute_api_endpointbooloptional

When true, enables the execute-api endpoint. Set to false if you wish for clients to only access the API via the domain set on domain_name.

Default:true

enable_root_lambda_functionbooloptional

When true, route the root path (URL or URL/) to the lambda function specified by root_lambda_function_name. This is useful when you want to route just the home route to a specific lambda function when configuring path based routing with lambda_functions. Conflicts with the catch all lambda function, which is configured using the empty string key in lambda_functions. Do not use this to configure a catch all lambda function.

Default:false

More Details

Details

   MAINTAINER'S NOTE: Ideally, we would add a validation block to ensure that this is not configured if the user has a
   catch all route (var.lambda_functions[""] is set), but the terraform variable validation expression does not support
   looking up other variables in the condition block at this time. So we don't configure variable validation here.

force_deploymentbooloptional

When true, force a deployment on every touch. Ideally we can cause a deployment on the API Gateway only when a configuration changes, but terraform does not give reliable mechanisms for triggering a redeployment when any related resource changes. As such, we must either pessimistically redeploy on every touch, or have user control it. You must use the deployment_id input variable to trigger redeployments if this is false. Note that setting this to true will, by nature, cause a perpetual diff on the module.

Default:true

hosted_zone_domain_namestringoptional

Domain name to use when looking up the Route 53 hosted zone to bind the API Gateway domain to. Only used if hosted_zone_id is null.

Default:null

hosted_zone_idstringoptional

ID of the Route 53 zone where the domain should be configured. If null, this module will lookup the hosted zone using the domain name, or the provided parameters.

Default:null

hosted_zone_tagsmap(string)optional

Tags to use when looking up the Route 53 hosted zone to bind the domain to. Only used if hosted_zone_id is null.

Default:{}

root_lambda_function_namestringoptional

Name of the lambda function to invoke just for the root path (URL or URL/). Only used if enable_root_lambda_function is true.

Default:null

stage_descriptionstringoptional

Description to set on the stage managed by the stage_name variable.

Default:null

stage_namestringoptional

Name of the stage to create with this API Gateway deployment.

Default:"live"

Outputs

deployment

The API Gateway deployment resource. Contains all the attributes returned by the terraform resource aws_api_gateway_deployment.

rest_api

The API Gateway REST API resource. Contains all the attributes returned by the Terraform resource aws_api_gateway_rest_api.

stage

The API Gateway stage resource. Contains all the attributes returned by the terraform resource aws_api_gateway_stage.

url

The URL of the API Gateway that you can use to invoke it.