README.md

AWS API Gateway v2 (HTTP/Websocket) Terraform module

Terraform module which creates API Gateway version 2 with HTTP/Websocket capabilities.

This Terraform module is part of serverless.tf framework, which aims to simplify all operations when working with the serverless in Terraform.

Supported Features

• Support many of features of HTTP API Gateway, but rather limited support for WebSocket API Gateway
• Conditional creation for many types of resources

Feature Roadmap

• Some features are still missing (especially for WebSocket support)

Usage

HTTP API Gateway

module "api_gateway" {
  source = "terraform-aws-modules/apigateway-v2/aws"

  name          = "dev-http"
  description   = "My awesome HTTP API Gateway"
  protocol_type = "HTTP"

  cors_configuration = {
    allow_headers = ["content-type", "x-amz-date", "authorization", "x-api-key", "x-amz-security-token", "x-amz-user-agent"]
    allow_methods = ["*"]
    allow_origins = ["*"]
  }

  # Custom domain
  domain_name                 = "terraform-aws-modules.modules.tf"
  domain_name_certificate_arn = "arn:aws:acm:eu-west-1:052235179155:certificate/2b3a7ed9-05e1-4f9e-952b-27744ba06da6"

  # Access logs
  default_stage_access_log_destination_arn = "arn:aws:logs:eu-west-1:835367859851:log-group:debug-apigateway"
  default_stage_access_log_format          = "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId $context.integrationErrorMessage"

  # Routes and integrations
  integrations = {
    "POST /" = {
      lambda_arn             = "arn:aws:lambda:eu-west-1:052235179155:function:my-function"
      payload_format_version = "2.0"
      timeout_milliseconds   = 12000
    }
    
    "GET /some-route-with-authorizer" = {
      integration_type = "HTTP_PROXY"
      integration_uri  = "some url"
      authorizer_key   = "azure"
    }

    "$default" = {
      lambda_arn = "arn:aws:lambda:eu-west-1:052235179155:function:my-default-function"
    }
  }

  authorizers = {
    "azure" = {
      authorizer_type  = "JWT"
      identity_sources = "$request.header.Authorization"
      name             = "azure-auth"
      audience         = ["d6a38afd-45d6-4874-d1aa-3c5c558aqcc2"]
      issuer           = "https://sts.windows.net/aaee026e-8f37-410e-8869-72d9154873e4/"
    }
  }

  tags = {
    Name = "http-apigateway"
  }
}

Conditional creation

Sometimes you need to have a way to create resources conditionally but Terraform does not allow usage of count inside module block, so the solution is to specify create arguments.

module "api_gateway" {
  source = "terraform-aws-modules/apigateway-v2/aws"

  create = false # to disable all resources

  create_api_gateway               = false  # to control creation of API Gateway
  create_api_domain_name           = false  # to control creation of API Gateway Domain Name
  create_default_stage             = false  # to control creation of "$default" stage
  create_default_stage_api_mapping = false  # to control creation of "$default" stage and API mapping
  create_routes_and_integrations   = false  # to control creation of routes and integrations
  create_vpc_link                  = false  # to control creation of VPC link

  # ... omitted
}

Notes:

• Make sure provider block has the setting of skip_requesting_account_id disabled (false) to produce correct value in the execution_arn.

Examples

• Complete HTTP - Create API Gateway, authorizer, domain name, stage and other resources in various combinations
• HTTP with VPC Link - Create API Gateway with VPC link and integration with resources in VPC (eg. ALB)

Requirements

Name	Version
terraform	>= 0.13.1
aws	>= 4.0

Providers

Name	Version
aws	>= 4.0

Modules

No modules.

Resources

Name	Type
aws_apigatewayv2_api.this	resource
aws_apigatewayv2_api_mapping.this	resource
aws_apigatewayv2_authorizer.this	resource
aws_apigatewayv2_domain_name.this	resource
aws_apigatewayv2_integration.this	resource
aws_apigatewayv2_route.this	resource
aws_apigatewayv2_stage.default	resource
aws_apigatewayv2_vpc_link.this	resource

Inputs

Name	Description	Type	Default	Required
api_key_selection_expression	An API key selection expression. Valid values: $context.authorizer.usageIdentifierKey, $request.header.x-api-key.	string	"$request.header.x-api-key"	no
api_version	A version identifier for the API	string	null	no
authorizers	Map of API gateway authorizers	map(any)	{}	no
body	An OpenAPI specification that defines the set of routes and integrations to create as part of the HTTP APIs. Supported only for HTTP APIs.	string	null	no
cors_configuration	The cross-origin resource sharing (CORS) configuration. Applicable for HTTP APIs.	any	{}	no
create	Controls if API Gateway resources should be created	bool	true	no
create_api_domain_name	Whether to create API domain name resource	bool	true	no
create_api_gateway	Whether to create API Gateway	bool	true	no
create_default_stage	Whether to create default stage	bool	true	no
create_default_stage_api_mapping	Whether to create default stage API mapping	bool	true	no
create_routes_and_integrations	Whether to create routes and integrations resources	bool	true	no
create_vpc_link	Whether to create VPC links	bool	true	no
credentials_arn	Part of quick create. Specifies any credentials required for the integration. Applicable for HTTP APIs.	string	null	no
default_route_settings	Settings for default route	map(string)	{}	no
default_stage_access_log_destination_arn	Default stage's ARN of the CloudWatch Logs log group to receive access logs. Any trailing :* is trimmed from the ARN.	string	null	no
default_stage_access_log_format	Default stage's single line format of the access logs of data, as specified by selected $context variables.	string	null	no
default_stage_tags	A mapping of tags to assign to the default stage resource.	map(string)	{}	no
description	The description of the API.	string	null	no
disable_execute_api_endpoint	Whether clients can invoke the API by using the default execute-api endpoint. To require that clients use a custom domain name to invoke the API, disable the default endpoint	string	false	no
domain_name	The domain name to use for API gateway	string	null	no
domain_name_certificate_arn	The ARN of an AWS-managed certificate that will be used by the endpoint for the domain name	string	null	no
domain_name_ownership_verification_certificate_arn	ARN of the AWS-issued certificate used to validate custom domain ownership (when certificate_arn is issued via an ACM Private CA or mutual_tls_authentication is configured with an ACM-imported certificate.)	string	null	no
domain_name_tags	A mapping of tags to assign to API domain name resource.	map(string)	{}	no
integrations	Map of API gateway routes with integrations	map(any)	{}	no
mutual_tls_authentication	An Amazon S3 URL that specifies the truststore for mutual TLS authentication as well as version, keyed at uri and version	map(string)	{}	no
name	The name of the API	string	""	no
protocol_type	The API protocol. Valid values: HTTP, WEBSOCKET	string	"HTTP"	no
route_key	Part of quick create. Specifies any route key. Applicable for HTTP APIs.	string	null	no
route_selection_expression	The route selection expression for the API.	string	"$request.method $request.path"	no
tags	A mapping of tags to assign to API gateway resources.	map(string)	{}	no
target	Part of quick create. Quick create produces an API with an integration, a default catch-all route, and a default stage which is configured to automatically deploy changes. For HTTP integrations, specify a fully qualified URL. For Lambda integrations, specify a function ARN. The type of the integration will be HTTP_PROXY or AWS_PROXY, respectively. Applicable for HTTP APIs.	string	null	no
vpc_link_tags	A map of tags to add to the VPC Link	map(string)	{}	no
vpc_links	Map of VPC Links details to create	map(any)	{}	no

Outputs

Name	Description
apigatewayv2_api_api_endpoint	The URI of the API
apigatewayv2_api_arn	The ARN of the API
apigatewayv2_api_execution_arn	The ARN prefix to be used in an aws_lambda_permission's source_arn attribute or in an aws_iam_policy to authorize access to the @connections API.
apigatewayv2_api_id	The API identifier
apigatewayv2_api_mapping_id	The API mapping identifier.
apigatewayv2_authorizer_id	The map of API Gateway Authorizer identifiers
apigatewayv2_domain_name_api_mapping_selection_expression	The API mapping selection expression for the domain name
apigatewayv2_domain_name_arn	The ARN of the domain name
apigatewayv2_domain_name_configuration	The domain name configuration
apigatewayv2_domain_name_hosted_zone_id	The Amazon Route 53 Hosted Zone ID of the endpoint
apigatewayv2_domain_name_id	The domain name identifier
apigatewayv2_domain_name_target_domain_name	The target domain name
apigatewayv2_vpc_link_arn	The map of VPC Link ARNs
apigatewayv2_vpc_link_id	The map of VPC Link identifiers
default_apigatewayv2_stage_arn	The default stage ARN
default_apigatewayv2_stage_domain_name	Domain name of the stage (useful for CloudFront distribution)
default_apigatewayv2_stage_execution_arn	The ARN prefix to be used in an aws_lambda_permission's source_arn attribute or in an aws_iam_policy to authorize access to the @connections API.
default_apigatewayv2_stage_id	The default stage identifier
default_apigatewayv2_stage_invoke_url	The URL to invoke the API pointing to the stage

Authors

Module managed by Anton Babenko. Check out serverless.tf to learn more about doing serverless with Terraform.

Please reach out to Betajob if you are looking for commercial support for your Terraform, AWS, or serverless project.

License

Apache 2 Licensed. See LICENSE for full details.