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