Terraform AWS API Gateway

A Terraform module and associated submodules for building an API gateway in AWS.

The infrablocks/api-gateway/aws root module:

has no prerequisite requirements
consists of:
- an API Gateway REST API
- an optional API Gateway REST API policy

Additionally, this module includes 3 submodules:

infrablocks/api-gateway/aws//modules/deployment for managing an API Gateway stage and deployment of an API Gateway REST API
infrablocks/api-gateway/aws//modules/domain for configuring a custom domain on an API Gateway REST API
infrablocks/api-gateway/aws//modules/log_permissions for creating and configuring a logging role for API Gateway

The infrablocks/api-gateway/aws//modules/deployment module:

requires an existing API Gateway REST API as created by the root module
consists of:
- an API Gateway stage
- an API Gateway deployment

The infrablocks/api-gateway/aws//modules/domain module:

requires:
- an existing API Gateway REST API as created by the root module
- an existing ACM certificate
consists of:
- an API Gateway domain
- an API Gateway base path mapping
- AWS Route53 records for the domain in each provided hosted zone

The infrablocks/api-gateway/aws//modules/log_permissions module:

has no prerequisite requirements
consists of:
- an IAM role allowing the API Gateway service to manage Cloudwatch logs
- configuration of the IAM role against the API Gateway service

Usage

To use the infrablocks/api-gateway/aws root module, include something like the following in your Terraform configuration:

module "api_gateway" {
  source  = "infrablocks/api-gateway/aws"
  version = "2.0.0"

  region = "eu-west-2"

  component             = "api-gw"
  deployment_identifier = "production"
}

Then to use the infrablocks/api-gateway/aws//modules/deployment submodule:

module "deployment" {
  source  = "infrablocks/api-gateway/aws//modules/deployment"
  version = "2.0.0"

  region = "eu-west-2"

  component             = "api-gw"
  deployment_identifier = "production"

  api_gateway_rest_api_id           = module.api_gateway.api_gateway_rest_api_id
  api_gateway_stage_name            = "default"
  api_gateway_redeployment_triggers = {
    release : 1
  }
}

And to use the infrablocks/api-gateway/aws//modules/domain submodule:

module "domain" {
  source  = "infrablocks/api-gateway/aws//modules/domain"
  version = "2.0.0"

  region = "eu-west-2"

  component             = "api-gw"
  deployment_identifier = "production"

  api_gateway_rest_api_id                 = module.api_gateway.api_gateway_rest_api_id
  api_gateway_stage_name                  = "default"
  api_gateway_domain_name                 = "example.com"
  api_gateway_domain_name_certificate_arn = "arn:aws:acm:eu-west-2:123456789101:certificate/31bd2209-f35b-4668-b48b-324f44fedc7e"

  dns = {
    records : [
      {
        zone_id : "Z0901234DIVFOTMNA324"
      }
    ]
  }
}

The infrablocks/api-gateway/aws//modules/log_permissions module should be used once per account, as follows:

module "domain" {
  source  = "infrablocks/api-gateway/aws//modules/log_permissions"
  version = "2.0.0"
}

See the Terraform registry entry for more details.

Inputs

Root Module

Name	Description	Default	Required
`region`	The region into which to deploy the API gateway REST API.	-	Yes
`component`	The component for which the API gateway REST API is being created.	-	Yes
`deployment_identifier`	An identifier for this instantiation	-	Yes
`api_gateway_rest_api_endpoint_type`	The type of the endpoints in this REST API. Valid values: `"EDGE"`, `"REGIONAL"` or `"PRIVATE"`.	`"EDGE"`	No
`api_gateway_rest_api_vpc_endpoint_ids`	The VPC endpoint IDs to associate with the REST API when it is deployed privately. Required when `api_gateway_rest_api_endpoint_type` is `"PRIVATE"`.	-	Yes, depending on other vars
`api_gateway_rest_api_source_policy_document`	A source policy document for the policy associated with the REST API. Only required if `include_api_gateway_rest_api_policy` is `true`.	-	Yes, depending on other vars
`include_api_gateway_rest_api_policy`	Whether or not to include an IAM policy on the REST API.	`false`	No

Deployment Sub-module

Name	Description	Default	Required
`region`	The region into which to deploy the API gateway deployment.	-	Yes
`component`	The component for which the API gateway deployment is being created.	-	Yes
`deployment_identifier`	An identifier for this instantiation.	-	Yes
`api_gateway_rest_api_id`	The ID of the API gateway REST API for which this deployment is being managed.	-	Yes
`api_gateway_stage_name`	The stage name for the API gateway stage created for this deployment.	-	Yes
`api_gateway_redeployment_triggers`	A map of key value pairs such that when any value changes, redeployment of the API gateway stage is triggered.	-	Yes
`tags`	A map of tags to add to created infrastructure components.	`{}`	No

Domain Sub-module

Name	Description	Default	Required
`region`	The region into which to deploy the API gateway domain.	-	Yes
`component`	The component for which the API gateway domain is being created.	-	Yes
`deployment_identifier`	An identifier for this instantiation.	-	Yes
`api_gateway_rest_api_id`	The ID of the API gateway REST API for which this domain is being managed.	-	Yes
`api_gateway_rest_api_endpoint_type`	The type of the endpoints in this REST API. Valid values: `"EDGE"`, `"REGIONAL"` or `"PRIVATE"`.	`"EDGE"`	Yes
`api_gateway_stage_name`	The stage name for the API gateway stage created for this deployment.	-	Yes
`api_gateway_domain_name`	The domain name to use for the API gateway.	-	Yes
`api_gateway_domain_name_certificate_arn`	The ARN of a certificate to associate with the API gateway for this domain.	-	Yes
`api_gateway_domain_name_security_policy`	The security policy to use on the API gateway for this domain.	`"TLS_1_2"`	No
`api_gateway_domain_name_base_path`	The base path at which to expose the API managed by the API gateway for this domain.	-	No
`dns`	Details of the DNS records to create pointing at the API gateway for this domain name.	`[]`	No
`tags`	AWS tags to use on created infrastructure components.	`{}`	No

Log Permissions Sub-module

Name	Description	Default	Required

Outputs

Root Module

Name	Description
`api_gateway_rest_api_name`	The name of the created API Gateway REST API.
`api_gateway_rest_api_id`	The ID of the created API Gateway REST API.
`api_gateway_rest_api_root_resource_id`	The resource ID of the REST API's root.
`api_gateway_redeployment_triggers`	A map of redeployment triggers for use in the `infrablocks/api-gateway/aws//modules/deployment` module such that a redeployment will be triggered on change.

Deployment Sub-module

Name	Description
`api_gateway_deployment_id`	The ID of the API gateway deployment managed by this module.
`api_gateway_stage_id`	The ID of the API gateway stage managed by this module.
`api_gateway_stage_arn`	The ARN of the API gateway stage managed by this module.
`api_gateway_stage_invoke_url`	The invoke URL of the stage managed by this module.
`api_gateway_stage_execution_arn`	The execution ARN of the stage managed by this module.

Domain Sub-module

Name	Description
`api_gateway_domain_name_cloudfront_domain_name`	The CloudFront domain name of the domain endpoint of the API gateway for the domain. Populated when endpoint type is `"EDGE"`.
`api_gateway_domain_name_cloudfront_zone_id`	The CloudFront zone ID of the domain endpoint of the API gateway for the domain. Populated when endpoint type is `"EDGE"`.
`api_gateway_domain_name_regional_domain_name`	The regional domain name of the domain endpoint of the API gateway for the domain. Populated when endpoint type is `"REGIONAL"`.
`api_gateway_domain_name_regional_zone_id`	The regional zone ID of the domain endpoint of the API gateway for the domain. Populated when endpoint type is `"REGIONAL"`.

Log Permissions Sub-module

Name	Description
`logging_role_id`	The ID of the managed API Gateway logging role.
`logging_role_arn`	The ARN of the managed API Gateway logging role.
`logging_role_name`	The name of the managed API Gateway logging role.
`logging_role_policy_id`	The ID of the policy attached to the API Gateway logging role.
`logging_role_policy_name`	The name of the policy attached to the API Gateway logging role.

Compatibility

This module and all submodules are compatible with Terraform versions greater than or equal to Terraform 1.3 and the Terraform AWS provider 4.0.

Development

Machine Requirements

In order for the build to run correctly, a few tools will need to be installed on your development machine:

Ruby (3.1)
Bundler
git
git-crypt
gnupg
direnv
aws-vault

Mac OS X Setup

Installing the required tools is best managed by homebrew.

To install homebrew:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Then, to install the required tools:

# ruby
brew install rbenv
brew install ruby-build
echo 'eval "$(rbenv init - bash)"' >> ~/.bash_profile
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
eval "$(rbenv init -)"
rbenv install 3.1.1
rbenv rehash
rbenv local 3.1.1
gem install bundler

# git, git-crypt, gnupg
brew install git
brew install git-crypt
brew install gnupg

# aws-vault
brew cask install

# direnv
brew install direnv
echo "$(direnv hook bash)" >> ~/.bash_profile
echo "$(direnv hook zsh)" >> ~/.zshrc
eval "$(direnv hook $SHELL)"

direnv allow <repository-directory>

Running the build

Running the build requires an AWS account and AWS credentials. You are free to configure credentials however you like as long as an access key ID and secret access key are available. These instructions utilise aws-vault which makes credential management easy and secure.

To run the full build, including unit and integration tests, execute:

aws-vault exec <profile> -- ./go

To run the unit tests, execute:

aws-vault exec <profile> -- ./go test:unit

To run the integration tests, execute:

aws-vault exec <profile> -- ./go test:integration

To provision the module prerequisites:

aws-vault exec <profile> -- ./go deployment:prerequisites:provision[<deployment_identifier>]

To provision the module contents:

aws-vault exec <profile> -- ./go deployment:root:provision[<deployment_identifier>]

To destroy the module contents:

aws-vault exec <profile> -- ./go deployment:root:destroy[<deployment_identifier>]

To destroy the module prerequisites:

aws-vault exec <profile> -- ./go deployment:prerequisites:destroy[<deployment_identifier>]

Configuration parameters can be overridden via environment variables. For example, to run the unit tests with a seed of "testing", execute:

SEED=testing aws-vault exec <profile> -- ./go test:unit

When a seed is provided via an environment variable, infrastructure will not be destroyed at the end of test execution. This can be useful during development to avoid lengthy provision and destroy cycles.

To subsequently destroy unit test infrastructure for a given seed:

FORCE_DESTROY=yes SEED=testing aws-vault exec <profile> -- ./go test:unit

Common Tasks

Generating an SSH key pair

To generate an SSH key pair:

ssh-keygen -m PEM -t rsa -b 4096 -C integration-test@example.com -N '' -f config/secrets/keys/bastion/ssh

Generating a self-signed certificate

To generate a self signed certificate:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365

To decrypt the resulting key:

openssl rsa -in key.pem -out ssl.key

Managing CircleCI keys

To encrypt a GPG key for use by CircleCI:

openssl aes-256-cbc \
  -e \
  -md sha1 \
  -in ./config/secrets/ci/gpg.private \
  -out ./.circleci/gpg.private.enc \
  -k "<passphrase>"

To check decryption is working correctly:

openssl aes-256-cbc \
  -d \
  -md sha1 \
  -in ./.circleci/gpg.private.enc \
  -k "<passphrase>"

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/infrablocks/terraform-aws-api-gateway. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The library is available as open source under the terms of the MIT License.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Terraform AWS API Gateway

Usage

Inputs

Root Module

Deployment Sub-module

Domain Sub-module

Log Permissions Sub-module

Outputs

Root Module

Deployment Sub-module

Domain Sub-module

Log Permissions Sub-module

Compatibility

Development

Machine Requirements

Mac OS X Setup

Running the build

Common Tasks

Generating an SSH key pair

Generating a self-signed certificate

Managing CircleCI keys

Contributing

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

Terraform AWS API Gateway

Usage

Inputs

Root Module

Deployment Sub-module

Domain Sub-module

Log Permissions Sub-module

Outputs

Root Module

Deployment Sub-module

Domain Sub-module

Log Permissions Sub-module

Compatibility

Development

Machine Requirements

Mac OS X Setup

Running the build

Common Tasks

Generating an SSH key pair

Generating a self-signed certificate

Managing CircleCI keys

Contributing

License