Skip to main content
AWS Lambda 1.0.2Last updated in version 0.22.0 View Source Release Notes

Lambda Function HTTP API Gateway

Overview​

This module contains Terraform code to deploy a HTTP (V2) API Gateway to front Lambda functions so that they can be invoked on HTTP calls.

Serverless architectureServerless architecture

note

If you are looking for a simple proxy to route all requests to a Lambda function, refer to the api-gateway-proxy module.

Features​

  • Expose serverless applications using API Gateway.
  • Route different HTTP methods and paths to different Lambda functions.
  • Use request authorizers to protect routes

Learn​

note

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

Deploy​

Non-production deployment (quick start for learning)​

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

Manage​

What is the syntax for the keys of the route_config input variable?​

The route_config variable expects the keys to be HTTP API Gateway routes. Refer to the official AWS documentation for more information on route syntax that API Gateway expects.

Sample Usage​

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S LAMBDA-HTTP-API-GATEWAY MODULE
# ------------------------------------------------------------------------------------------------------

module "lambda_http_api_gateway" {

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

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

  # The name of the API Gateway. This will be used to namespace all resources
  # created by this module.
  name = <string>

  # Routing configurations for the API Gateway, encoded as a map from route to
  # lambda function configuration. The keys should be the routes to match (e.g.,
  # 'GET /pet').
  route_config = <any>

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

  # The ID (ARN, alias ARN, AWS ID) of a customer managed KMS Key to use for
  # encrypting log data. Only used if var.access_log_cloudwatch_log_group_name
  # is set.
  access_log_cloudwatch_log_group_kms_key_id = null

  # The name of the CloudWatch Log Group where API Gateway access logs should be
  # stored. When null, access logs will be disabled.
  access_log_cloudwatch_log_group_name = null

  # The number of days to retain log events in the log group. Refer to
  # https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group#retention_in_days
  # for all the valid values. When null, the log events are retained forever.
  # Only used if var.access_log_cloudwatch_log_group_name is set.
  access_log_cloudwatch_log_group_retention_in_days = null

  # The ARN of the destination to deliver matching log events to. Kinesis stream
  # or Lambda function ARN. Only used if
  # var.access_log_cloudwatch_log_group_name is set.
  access_log_cloudwatch_log_group_subscription_destination_arn = null

  # The method used to distribute log data to the destination. Only applicable
  # when var.cloudwatch_log_group_subscription_destination_arn is a kinesis
  # stream. Valid values are `Random` and `ByLogStream`.
  access_log_cloudwatch_log_group_subscription_distribution = null

  # A valid CloudWatch Logs filter pattern for subscribing to a filtered stream
  # of log events. Only used if var.access_log_cloudwatch_log_group_name is set.
  access_log_cloudwatch_log_group_subscription_filter_pattern = ""

  # ARN of an IAM role that grants Amazon CloudWatch Logs permissions to deliver
  # ingested log events to the destination. Only applicable when
  # var.cloudwatch_log_group_subscription_destination_arn is a kinesis stream.
  access_log_cloudwatch_log_group_subscription_role_arn = null

  # Tags to apply on the CloudWatch Log Group, encoded as a map where the keys
  # are tag keys and values are tag values. Only used if
  # var.access_log_cloudwatch_log_group_name is set.
  access_log_cloudwatch_log_group_tags = null

  # The format of the access logs as they are logged by API Gateway. Refer to
  # https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html#apigateway-cloudwatch-log-formats
  # for how each format appears. When set to CUSTOM, the format specified in
  # var.custom_access_log_format will be used. Valid values are CLF, JSON, and
  # CUSTOM. Only used when var.access_log_cloudwatch_log_group_name is set.
  access_log_format_type = "JSON"

  # A map of tags to assign to the API.
  api_tags = {}

  # A version identifier for the API.
  api_version = 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.
  # When null (default), var.domain_name will be used to look up the
  # certificate.
  certificate_domain = null

  # The cross-origin resource sharing (CORS) configuration to apply to the API.
  cors_configuration = null

  # Set to true if you want a DNS record automatically created and pointed at
  # the API Gateway endpoint.
  create_route53_entry = false

  # A single line format of the access logs of data, as specified by selected
  # $context variables. Only used when var.access_log_format_type is CUSTOM.
  custom_access_log_format = null

  # The description of the API.
  description = null

  # The domain name to create a route 53 record for. This DNS record will point
  # to the API Gateway endpoint.
  domain_name = null

  # The ID of the Route 53 hosted zone into which the Route 53 DNS record should
  # be written.
  hosted_zone_id = null

  # Authorizers for the API Gateway, encoded as a map from authorizer name to
  # authorizer configuration. The keys should be the authorizer name.
  lambda_authorizers = {}

  # A map of tags to assign to the API Gateway stage.
  stage_tags = {}

}


Reference​

Required​

namestringrequired

The name of the API Gateway. This will be used to namespace all resources created by this module.

route_configanyrequired

Routing configurations for the API Gateway, encoded as a map from route to lambda function configuration. The keys should be the routes to match (e.g., 'GET /pet').

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

   Ideally, we will use a more strict type here but since we want to support required and optional values, and since
   Terraform's type system only supports maps that have the same type for all values, we have to use the less useful
   `any` type.

Details

   The values support the following attributes:
  
   REQUIRED (must be provided for every entry):
   - lambda_function_arn     string   : ARN of the Lambda function that should be invoked for requests to this route.
  
   OPTIONAL:
   - description             string   : The description of the integration.
   - payload_format_version  string   : The format of the payload to use as specified by API Gateway. Defaults to 1.0.
   - timeout_milliseconds    number   : Custom timeout between 50 and 30,000 milliseconds for HTTP APIs. The default
                                        timeout is 30 seconds.
   - authorizer_name         string   : The name of the authorizer to use for this route. The name should match the
                                        name of an authorizer defined in var.lambda_authorizers.
   - authorization_type      string   : The type of authorization to use for this route. Valid values are NONE, JWT, and
                                        AWS_IAM and CUSTOM. Defaults to CUSTOM if authorizer_name is set otherwise NONE.
  
   Example:
   {
     "ANY /" = {
       lambda_function_arn = "default-function-arn"
     }
     "GET /pet" = {
       lambda_function_arn  = "pet-function-arn"
       timeout_milliseconds = 100
       authorizer_name      = lambda-authorizer
     }
   }

Optional​

The ID (ARN, alias ARN, AWS ID) of a customer managed KMS Key to use for encrypting log data. Only used if access_log_cloudwatch_log_group_name is set.

null

The name of the CloudWatch Log Group where API Gateway access logs should be stored. When null, access logs will be disabled.

null

The number of days to retain log events in the log group. Refer to https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group#retention_in_days for all the valid values. When null, the log events are retained forever. Only used if access_log_cloudwatch_log_group_name is set.

null

The ARN of the destination to deliver matching log events to. Kinesis stream or Lambda function ARN. Only used if access_log_cloudwatch_log_group_name is set.

null

The method used to distribute log data to the destination. Only applicable when cloudwatch_log_group_subscription_destination_arn is a kinesis stream. Valid values are Random and ByLogStream.

null

A valid CloudWatch Logs filter pattern for subscribing to a filtered stream of log events. Only used if access_log_cloudwatch_log_group_name is set.

""

ARN of an IAM role that grants Amazon CloudWatch Logs permissions to deliver ingested log events to the destination. Only applicable when cloudwatch_log_group_subscription_destination_arn is a kinesis stream.

null

Tags to apply on the CloudWatch Log Group, encoded as a map where the keys are tag keys and values are tag values. Only used if access_log_cloudwatch_log_group_name is set.

null

The format of the access logs as they are logged by API Gateway. Refer to https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html#apigateway-cloudwatch-log-formats for how each format appears. When set to CUSTOM, the format specified in custom_access_log_format will be used. Valid values are CLF, JSON, and CUSTOM. Only used when access_log_cloudwatch_log_group_name is set.

"JSON"
api_tagsmap(string)optional

A map of tags to assign to the API.

{}
api_versionstringoptional

A version identifier for the API.

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. When null (default), domain_name will be used to look up the certificate.

null

The cross-origin resource sharing (CORS) configuration to apply to the API.

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

   Ideally, we will use a more strict type here but since we want to support required and optional values, and since
   Terraform's type system only supports maps that have the same type for all values, we have to use the less useful
   `any` type.

Details

   The values support the following attributes:
   OPTIONAL (at least one must be set):
   - allow_credentials   bool          : Whether credentials are included in the CORS request.
   - allow_headers       list(string)  : The set of allowed HTTP headers in the CORS request.
   - allow_methods       list(string)  : The set of allowed HTTP methods in the CORS request.
   - allow_origins       list(string)  : The set of allowed origins in the CORS request.
   - expose_headers      list(string)  : The set of exposed HTTP headers in the CORS request.
   - max_age             number        : The number of seconds that the browser should cache preflight request results.
  
   Example:
   {
     allow_credentials = true
     allow_headers     = ["Authorization", "*"]
   }

Set to true if you want a DNS record automatically created and pointed at the API Gateway endpoint.

false

A single line format of the access logs of data, as specified by selected $context variables. Only used when access_log_format_type is CUSTOM.

null
descriptionstringoptional

The description of the API.

null
domain_namestringoptional

The domain name to create a route 53 record for. This DNS record will point to the API Gateway endpoint.

null
hosted_zone_idstringoptional

The ID of the Route 53 hosted zone into which the Route 53 DNS record should be written.

null
lambda_authorizersmap(any)optional

Authorizers for the API Gateway, encoded as a map from authorizer name to authorizer configuration. The keys should be the authorizer name.

Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
Example
   {
     "lambda-authorizer"                 = {
       authorizer_payload_format_version = "1.0"
       authorizer_uri                    = "lambda-authorizer-uri"
     }
   }

Details

   The values support the following attributes:
  
   REQUIRED (must be provided for every entry):
   - authorizer_name   string   : The name of the authorizer Lambda function.

stage_tagsmap(string)optional

A map of tags to assign to the API Gateway stage.

{}