Skip to main content
AWS Lambda 1.0.2Last updated in version 0.22.0

API Gateway Proxy Module

View Source Release Notes

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 architectureServerless 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.

important

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​

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​

Sample Usage​

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S API-GATEWAY-PROXY MODULE
# ------------------------------------------------------------------------------------------------------

module "api_gateway_proxy" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-lambda.git//modules/api-gateway-proxy?ref=v1.0.2"

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # Name of the API Gateway REST API.
  api_name = <string>

  # 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.
  lambda_functions = <map(string)>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

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

  # 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.
  api_description = ""

  # Configuration of the API endpoint for the API Gateway REST API. Defaults to
  # EDGE configuration. 
  api_endpoint_configuration = null

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

  # 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).
  api_minimum_compression_size = null

  # 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.
  api_settings = {}

  # 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 var.certificate_domain is set.
  certificate_arn = null

  # 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.
  certificate_domain = null

  # Set to true to automatically create a Rest API policy if necessary, or use
  # `var.rest_api_policy` to pass an external policy. A Rest API policy is
  # necessary if using PRIVATE api_endpoint_configuration type.
  create_rest_api_policy = false

  # Map of tags (where the key is the tag key and the value is tag value) to
  # apply to the resources in this module.
  custom_tags = {}

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

  # 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.
  deployment_id = ""

  # 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.
  domain_base_path = null

  # 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.
  domain_name = null

  # The Transport Layer Security (TLS) version + cipher suite for the API
  # Gateway DomainName. The valid values are TLS_1_0 and TLS_1_2.
  domain_name_security_policy = null

  # 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 var.domain_name.
  enable_execute_api_endpoint = true

  # 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 var.lambda_functions. Conflicts with the catch all
  # lambda function, which is configured using the empty string key in
  # var.lambda_functions. Do not use this to configure a catch all lambda
  # function.
  enable_root_lambda_function = false

  # 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
  # var.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.
  force_deployment = true

  # 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.
  hosted_zone_domain_name = null

  # 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.
  hosted_zone_id = null

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

  # Configuration for passing an external Rest API policy to be attached to API
  # Gateway, instead of the one created internally when setting
  # `var.rest_api_policy` to true. A Rest API policy is necessary if using
  # PRIVATE api_endpoint_configuration type.
  override_rest_api_policy = null

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

  # Description to set on the stage managed by the stage_name variable.
  stage_description = null

  # Name of the stage to create with this API Gateway deployment.
  stage_name = "live"

  # Whether active tracing with X-ray is enabled.
  stage_xray_tracing_enabled = true

}


Reference​

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.

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.

""
api_endpoint_configurationobject(…)optional

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

object({
    # The endpoint type. Must be one of EDGE, REGIONAL, or PRIVATE.
    # Type PRIVATE requires configuring a REST API policy, see var.create_rest_api policy for more details.
    type = string
    # Set of VPC Endpoint Identifiers to use when using a private endpoint.
    vpc_endpoint_ids = list(string)
  })
null
api_key_sourcestringoptional

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

null

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).

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.

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
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.

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.

null

Set to true to automatically create a Rest API policy if necessary, or use <a href="#rest_api_policy"><code>rest_api_policy</code></a> to pass an external policy. A Rest API policy is necessary if using PRIVATE api_endpoint_configuration type.

false
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.

{}

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

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.

""
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.

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.

null

The Transport Layer Security (TLS) version + cipher suite for the API Gateway DomainName. The valid values are TLS_1_0 and TLS_1_2.

null

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.

true

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.

false
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.

true

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.

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.

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.

{}

Configuration for passing an external Rest API policy to be attached to API Gateway, instead of the one created internally when setting <a href="#rest_api_policy"><code>rest_api_policy</code></a> to true. A Rest API policy is necessary if using PRIVATE api_endpoint_configuration type.

null

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

null
stage_descriptionstringoptional

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

null
stage_namestringoptional

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

"live"

Whether active tracing with X-ray is enabled.

true