AWS API Gateway Terraform Module

terraform-aws-arc-api-gateway

Overview

The API Gateway Terraform module provides an easy way to create and manage REST APIs on AWS. It supports defining resources, methods (GET, POST, etc.), and integrations with Lambda functions or other AWS services. The module also supports adding usage plans and API keys, enabling you to manage access, throttle requests, and monitor API usage. This helps ensure secure, scalable, and well-governed API deployments.

Prerequisites

Before using this module, ensure you have the following:

• AWS credentials configured.
• Terraform installed.
• A working knowledge of Terraform.

Getting Started

1. Define the Module

Initially, it's essential to define a Terraform module, which is organized as a distinct directory encompassing Terraform configuration files. Within this module directory, input variables and output values must be defined in the variables.tf and outputs.tf files, respectively. The following illustrates an example directory structure:

api-gateway/
|-- main.tf
|-- variables.tf
|-- outputs.tf

1. Define Input Variables

Inside the variables.tf or in *.tfvars file, you should define values for the variables that the module requires.

1. Use the Module in Your Main Configuration In your main Terraform configuration file (e.g., main.tf), you can use the module. Specify the source of the module, and version, For Example

module "api_gateway" {
  source                 = "sourcefuse/arc-api-gateway/aws"
  version                = "0.0.1"

  name          = "arc-app"
  stage_name    = "dev"
  endpoint_type = "REGIONAL"
  open_api_json = file("${path.module}/openapi.json")

  enable_cloudwatch_logs = true

  # Custom domain (optional)
  api_gateway_domain = {
    create              = true
    domain              = "arc-api.${local.domain}"
    certificate_arn     = data.aws_acm_certificate.this.arn
    route53_root_domain = local.domain
  }
}

1. Output Values

Inside the outputs.tf file of the module, you can define output values that can be referenced in the main configuration. For example:

output "id" {
  description = "The ID of the API Gateway REST API"
  value       = module.api_gateway.id
}

output "arn" {
  description = "The ARN of the API Gateway REST API"
  value       = module.api_gateway.arn
}

output "execution_arn" {
  description = "The execution ARN of the API Gateway (useful for Lambda permissions)"
  value       = module.api_gateway.execution_arn
}

1. .tfvars

Inside the .tfvars file of the module, you can provide desired values that can be referenced in the main configuration.

First Time Usage

uncomment the backend block in main.tf

terraform init -backend-config=config.dev.hcl

If testing locally, terraform init should be fine

Create a dev workspace

terraform workspace new dev

Plan Terraform

terraform plan -var-file dev.tfvars

Apply Terraform

terraform apply -var-file dev.tfvars

Production Setup

terraform init -backend-config=config.prod.hcl

Create a prod workspace

terraform workspace new prod

Plan Terraform

terraform plan -var-file prod.tfvars

Apply Terraform

terraform apply -var-file prod.tfvars  

Requirements

Name	Version
terraform	>= 1.3, < 2.0.0
aws	>= 5.0, < 6.0

Providers

Name	Version
aws	5.100.0
terraform	n/a

Modules

No modules.

Resources

Name	Type
aws_api_gateway_account.api_gateway_account	resource
aws_api_gateway_api_key.this	resource
aws_api_gateway_base_path_mapping.base_path_mapping	resource
aws_api_gateway_deployment.this	resource
aws_api_gateway_domain_name.custom_domain	resource
aws_api_gateway_rest_api.this	resource
aws_api_gateway_stage.this	resource
aws_api_gateway_usage_plan.this	resource
aws_api_gateway_usage_plan_key.this	resource
aws_iam_role.api_gateway_account_role	resource
aws_iam_role_policy.api_gateway_cloudwatch_policy	resource
aws_route53_record.api_gateway_alias	resource
terraform_data.replacement	resource
aws_caller_identity.current	data source
aws_region.current	data source
aws_route53_zone.this	data source

Inputs

Name	Description	Type	Default	Required
access_log_format	Acess log format for API Gateway	string	null	no
api_gateway_domain	Configuration for API Gateway custom domain and Route53 record	object({ create = optional(bool, false) domain = string # eg. "api.example.com" route53_root_domain = string # eg. "example.com" certificate_arn = string # ACM cert ARN })	n/a	yes
api_key_map	Configuration for API Gateway API keys. Each API key entry represents a client or application that requires access to the API, and can be associated with one or more usage plans. Fields: - name : The name of the API key (must be unique). - description : Optional description of the API key (e.g., which client it belongs to). - usage_plan : List of usage plan names (from var.usage_plan) this key should be associated with. This should match the names defined in var.usage_plan	map(object({ name = string description = string usage_plan = string // This should match the names defined in var.usage_plan }))	{}	no
enable_cloudwatch_logs	Whether to enable CloudWatch logs for API Gateway	bool	true	no
endpoint_type	API Gateway endpoint type. Valid values are 'EDGE', 'REGIONAL', or 'PRIVATE'. If not specified, defaults to 'REGIONAL'.	string	"REGIONAL"	no
name	Name of the API Gateway REST endpoint	string	n/a	yes
open_api_json	Open API JSON file	string	null	no
security_policy	The Transport Layer Security version for the custom domain. Valid values: TLS_1_0 or TLS_1_2	string	"TLS_1_2"	no
stage_name	API Gateway stage name	string	n/a	yes
tags	Tags for the resources	map(string)	{}	no
usage_plan	Configuration for API Gateway usage plan	list(object({ name = string description = optional(string, "API usage plan") quota_settings = object({ limit = number offset = number period = string }) throttle_settings = object({ burst_limit = number rate_limit = number }) }))	[]	no
xray_tracing_enabled	Enable X-Ray tracing for Lambda	bool	true	no

Outputs

Name	Description
api_keys	Map of API keys created (name => value)
arn	The ARN of the API Gateway REST API
custom_domain	The custom domain name for API Gateway (if created)
custom_domain_regional_domain_name	The regional domain name for the custom domain (if created)
custom_domain_regional_zone_id	The Route53 hosted zone ID for the custom domain
deployment_id	The ID of the current API Gateway deployment
execution_arn	The execution ARN of the API Gateway (useful for Lambda permissions)
id	The ID of the API Gateway REST API
invoke_url	Base invoke URL for the API Gateway stage
stage_name	The name of the API Gateway stage
usage_plans	Map of usage plans created

Versioning

This project uses a .version file at the root of the repo which the pipeline reads from and does a git tag.

When you intend to commit to main, you will need to increment this version. Once the project is merged, the pipeline will kick off and tag the latest git commit.

Development

Prerequisites

• terraform
• terraform-docs
• pre-commit
• golang
• golint

Configurations

• Configure pre-commit hooks

  pre-commit install
  

Versioning

while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch

For Example

git commit -m "your commit message #major"

By specifying this , it will bump the version and if you don't specify this in your commit message then by default it will consider patch and will bump that accordingly

Tests

• Tests are available in test directory
• Configure the dependencies

  cd test/
  go mod init github.com/sourcefuse/terraform-aws-refarch-<module_name>
  go get github.com/gruntwork-io/terratest/modules/terraform
  

• Now execute the test
  

  go test -timeout  30m
  

Authors

This project is authored by: - SourceFuse ARC Team