terraform aws apigateway proxy

Terraform module to create an api gateway that proxies requests. It also can create a domain name and supports an authorizer that can be provided by giving a lambda.

This module supports a very powerful route declaration. You can declare a full set of paths, each with different method configuration.

In addition, it has two more clever tricks up its sleeves. It will by default, for any routes given with path ending in {proxy+} and method config uri ending in {proxy}, generate another route for proxying the base route. For example, if a route given is:

{
  path    = "/v1/{proxy+}"
  methods = ["ANY"]
  config  = { uri = "example.com/v1/{proxy}" }
}

and no other routes are given with path "/v1" and url "example.com", then a default base proxy path should be created, such as:

{
  path    = "/v1"
  methods = ["ANY"]
  config  = { uri = "example.com/v1" }
}

If the preceding statement is not true, then this assumes your explicit configuration is correct. You can override this behavior by passing generate_base_proxies = false.

Additionally, it will automatically include any nested resources that aren't explicitly declared, but are nevertheless required for a given method's depth.

Usage

This module is intended to be used in conjunction with terraform-aws-apigateway-route-builder, but it is not a dependency. You can construct the methods and resources objects explicitly, but these are meant to be somewhat opinionated abstractions.

module "api" {
  source = "theherk/apigateway-proxy/aws"

  name        = "h4s-simple"
  stage_name  = "dev"
  vpc_link_id = "ab3ced"

  resources = module.builder.resources
  methods   = module.builder.methods
}

Examples

• Simple
• Complete

CORS

Starting at version 2.0.0, responses can be specified. This allows using MOCK type integrations to return a 200 preflight with necessary headers. See the Complete Example to see how to create an OPTIONS response.

Private

Private rest api's can be created too, by passing PRIVATE as the endpoint_type. In this case the whitelist is used in conduction with given source_vpc_endpoints to build the resource policy.

Contributing

To work on this repository, you need to install the pre-commit hooks, and dependencies from pre-commit-terraform.

make pre-commit

That should be the easy way, but if you use another package manager than apt, brew, or yum or want to configure these differently on your system, you can do so by following the guidance here. For instance, you can set this up to use docker for running checks rather than installing directly to your filesystem.

After doing this, several checks will be run when attempting commits.

---

note: The following is generated by terraform docs.

Requirements

Name	Version
terraform	>= 1.3.0
aws	>= 3.64

Providers

Name	Version
aws	5.73.0

Modules

No modules.

Resources

Name	Type
aws_api_gateway_authorizer.authorizer	resource
aws_api_gateway_base_path_mapping.this	resource
aws_api_gateway_deployment.this	resource
aws_api_gateway_domain_name.this	resource
aws_api_gateway_integration.this	resource
aws_api_gateway_integration_response.this	resource
aws_api_gateway_method.this	resource
aws_api_gateway_method_response.this	resource
aws_api_gateway_method_settings.s_all	resource
aws_api_gateway_resource.depth_0	resource
aws_api_gateway_resource.depth_1	resource
aws_api_gateway_resource.depth_2	resource
aws_api_gateway_resource.depth_3	resource
aws_api_gateway_resource.depth_4	resource
aws_api_gateway_rest_api.this	resource
aws_api_gateway_rest_api_policy.this	resource
aws_api_gateway_stage.this	resource
aws_cloudwatch_log_group.access	resource
aws_cloudwatch_log_group.exec	resource
aws_iam_policy.authorizer	resource
aws_iam_role.authorizer	resource
aws_iam_role_policy_attachment.authorizer	resource
aws_route53_record.this	resource
aws_iam_policy_document.authorizer	data source
aws_iam_policy_document.authorizer_assume_role	data source
aws_iam_policy_document.this	data source

Inputs

Name	Description	Type	Default	Required
access_log_format	Format for access log entries.	map(any)	{ "contextPath": "$context.path", "domainName": "$context.domainName", "error.message": "$context.error.message", "httpMethod": "$context.httpMethod", "ip": "$context.identity.sourceIp", "protocol": "$context.protocol", "requestId": "$context.requestId", "requestTime": "$context.requestTime", "responseLength": "$context.responseLength", "routeKey": "$context.routeKey", "status": "$context.status" }	no
associate_vpc_endpoints	List of vpc endpoints to associate with PRIVATE type api in endpoint configuration. This would be a subset of source_vpc_endpoints. It is only needed if invoking the api via generated Route53 alias, rather than with x-apigw-api-id header. You can read more about this here: https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html#associate-private-api-with-vpc-endpoint.	list(string)	null	no
authorizer	Lambda authorizer.	any	null	no
authorizer_identity_source	(Optional) Source of the identity in an incoming request. Defaults to method.request.header.Authorization. For REQUEST type, this may be a comma-separated list of values, including headers, query string parameters and stage variables - e.g., method.request.header.SomeHeaderName,method.request.querystring.SomeQueryStringName,stageVariables.SomeStageVariableName	string	null	no
binary_media_types	List of binary media types supported by the REST API.	list(string)	[]	no
certificate_arn	Certificate arn for api domain.	string	null	no
description	API description.	string	"API Gateway for proxying requests."	no
domain_name	Primary domain name to access the api.	string	null	no
domain_names_alternate	Alternate domain names to access the api. domain_name is the domain for which the Route53 record will be added; not these. These alternate names are for subject alternative names in the given certificate.	list(string)	[]	no
endpoint_type	API endpoint type.	string	"REGIONAL"	no
ip_whitelist	List of IP addresses that can reach the api.	list(string)	[]	no
log_retention_days	Number of days logs will be kept in CloudWatch.	number	365	no
method_settings	Settings for all API path methods. For descriptions see: https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_method_settings#settings	object({ cache_data_encrypted = optional(bool) cache_ttl_in_seconds = optional(number) caching_enabled = optional(bool) data_trace_enabled = optional(bool) logging_level = optional(string) metrics_enabled = optional(bool) require_authorization_for_cache_control = optional(bool) throttling_burst_limit = optional(number) throttling_rate_limit = optional(number) unauthorized_cache_control_header_strategy = optional(string) })	{ "data_trace_enabled": true, "logging_level": "INFO", "throttling_burst_limit": 3, "throttling_rate_limit": 2 }	no
methods	Methods with resource associations and integration configuration. This is a complex type manual configuration is not recommended. It is recommended to use terraform-aws-apigateway-route-builder to generate this data. Nevertheless, a description of the type's attributes are: methods = { "0	v1	POST" = { config = { "uri" = "example.com/v1" } depth = 0 key = "0	v1
name	Name of the api.	string	n/a	yes
permissions_boundary	ARN of the boundary policy to attach to roles.	string	null	no
resources	Resources keyed by the route's depth and path, and containing: depth, parent_key, path_part. This is a complex type manual configuration is not recommended. It is recommended to use terraform-aws-apigateway-route-builder to generate this data. Nevertheless, a description of the type's attributes are: resources = { "0	v1" = { depth = 0 parent_key = null path_part = "v1" } }	map(object({ # key by depth	path depth = number # nested depth parent_key = string # key of containing resource path_part = string # individual, last path component }))
routing_policy	Routing policy applied to the alias A record when domain_name is given. This can be useful if you intend to failover to an alternate API. It is not required, and when not given, a simple routing policy will be used.	object({ set_identifier = string cidr = optional(object({ collection_id = string location_name = string })) failover = optional(object({ type = string })) geolocation = optional(object({ continent = string country = string subdivision = optional(string) })) geoproximity = optional(object({ aws_region = optional(string) bias = optional(string) local_zone_group = optional(string) coordinates = optional(object({ latitude = string longitude = string })) })) latency = optional(object({ region = string })) weighted = optional(object({ weight = number })) })	null	no
source_vpc_endpoints	Source VPC endpoints to whitelist. Required in addition to ip_whitelist for private endpoint type.	list(string)	[]	no
source_vpce	Source VPC endpoint to whitelist. Required in addition to ip_whitelist for private endpoint type. Deprecated, but provided for compatibility. Use source_vpc_endpoints instead.	string	null	no
stage_name	Name of the api stage to deploy.	string	n/a	yes
throttling_burst_limit	(DEPRECATED) Use method_settings instead. This will still work until removed, but will be superseded by methods_settings. Specifies the throttling burst limit. Should be used in combination with throttling_rate_limit.	number	null	no
throttling_rate_limit	(DEPRECATED) Use method_settings instead. This will still work until removed, but will be superseded by methods_settings. Specifies the throttling rate limit. Should be used in combination with throttling_burst_limit.	number	null	no
vpc_link_id	vpc link id for proxy integrations. Can be given per route, but will be default if given when not found in route.	string	null	no
xray_tracing_enabled	Whether active tracing with X-ray is enabled.	bool	null	no
zone_id	DNS zone for api. Only applicable if domain_name given.	string	null	no

Outputs

Name	Description
api	n/a
log_groups	n/a
stage	n/a