Skip to content


Switch branches/tags

Latest commit

## [2.0.0](v1.9.0...v2.0.0) (2022-06-15)


* Upgraded AWS provider to v4 everywhere (#74)

### Features

* Upgraded AWS provider to v4 everywhere ([#74](#74)) ([2f8ad61](2f8ad61))

Git stats


Failed to load latest commit information.

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


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

  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


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


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


Name Version
terraform >= 0.13.1
aws >= 4.0


Name Version
aws >= 4.0


No modules.


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


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


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_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


Module managed by Anton Babenko. Check out 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.


Apache 2 Licensed. See LICENSE for full details.