{"id":21202500,"url":"https://github.com/infrablocks/terraform-aws-api-gateway","last_synced_at":"2025-06-12T16:41:24.701Z","repository":{"id":38326531,"uuid":"193224519","full_name":"infrablocks/terraform-aws-api-gateway","owner":"infrablocks","description":"Terraform module for deploying an API gateway to AWS","archived":false,"fork":false,"pushed_at":"2024-10-28T02:07:51.000Z","size":564,"stargazers_count":2,"open_issues_count":1,"forks_count":6,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-10-28T05:59:13.857Z","etag":null,"topics":["api-gateway","aws","infrastructure","terraform","terraform-modules"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/infrablocks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-22T11:06:38.000Z","updated_at":"2024-10-28T02:07:54.000Z","dependencies_parsed_at":"2023-02-14T12:55:19.233Z","dependency_job_id":"b1d2cb61-c9bf-42ea-9d9f-2d54c58447a9","html_url":"https://github.com/infrablocks/terraform-aws-api-gateway","commit_stats":null,"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infrablocks%2Fterraform-aws-api-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infrablocks%2Fterraform-aws-api-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infrablocks%2Fterraform-aws-api-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infrablocks%2Fterraform-aws-api-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infrablocks","download_url":"https://codeload.github.com/infrablocks/terraform-aws-api-gateway/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225622825,"owners_count":17498170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","aws","infrastructure","terraform","terraform-modules"],"created_at":"2024-11-20T20:16:19.739Z","updated_at":"2024-11-20T20:16:21.229Z","avatar_url":"https://github.com/infrablocks.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Terraform AWS API Gateway\n===================================\n\n[![Version](https://img.shields.io/github/v/tag/infrablocks/terraform-aws-api-gateway?label=version\u0026sort=semver)](https://github.com/infrablocks/terraform-aws-api-gateway/tags)\n[![Build Pipeline](https://img.shields.io/circleci/build/github/infrablocks/terraform-aws-api-gateway/main?label=build-pipeline)](https://app.circleci.com/pipelines/github/infrablocks/terraform-aws-api-gateway?filter=all)\n[![Maintainer](https://img.shields.io/badge/maintainer-go--atomic.io-red)](https://go-atomic.io)\n\nA Terraform module and associated submodules for building an API gateway in AWS.\n\nThe `infrablocks/api-gateway/aws` root module:\n\n* has no prerequisite requirements\n* consists of:\n    * an API Gateway REST API\n    * an optional API Gateway REST API policy\n\nAdditionally, this module includes 3 submodules:\n\n* `infrablocks/api-gateway/aws//modules/deployment` for managing an API\n  Gateway stage and deployment of an API Gateway REST API\n* `infrablocks/api-gateway/aws//modules/domain` for configuring a custom\n  domain on an API Gateway REST API\n* `infrablocks/api-gateway/aws//modules/log_permissions` for creating and\n  configuring a logging role for API Gateway\n\nThe `infrablocks/api-gateway/aws//modules/deployment` module:\n\n* requires an existing API Gateway REST API as created by the root module\n* consists of:\n    * an API Gateway stage\n    * an API Gateway deployment\n\nThe `infrablocks/api-gateway/aws//modules/domain` module:\n\n* requires:\n    * an existing API Gateway REST API as created by the root module\n    * an existing ACM certificate\n* consists of:\n    * an API Gateway domain\n    * an API Gateway base path mapping\n    * AWS Route53 records for the domain in each provided hosted zone\n\nThe `infrablocks/api-gateway/aws//modules/log_permissions` module:\n\n* has no prerequisite requirements\n* consists of:\n    * an IAM role allowing the API Gateway service to manage Cloudwatch logs\n    * configuration of the IAM role against the API Gateway service\n\nUsage\n-----\n\nTo use the `infrablocks/api-gateway/aws` root module, include something like the\nfollowing in your Terraform configuration:\n\n```terraform\nmodule \"api_gateway\" {\n  source  = \"infrablocks/api-gateway/aws\"\n  version = \"2.0.0\"\n\n  region = \"eu-west-2\"\n\n  component             = \"api-gw\"\n  deployment_identifier = \"production\"\n}\n```\n\nThen to use the `infrablocks/api-gateway/aws//modules/deployment` submodule:\n\n```terraform\nmodule \"deployment\" {\n  source  = \"infrablocks/api-gateway/aws//modules/deployment\"\n  version = \"2.0.0\"\n\n  region = \"eu-west-2\"\n\n  component             = \"api-gw\"\n  deployment_identifier = \"production\"\n\n  api_gateway_rest_api_id           = module.api_gateway.api_gateway_rest_api_id\n  api_gateway_stage_name            = \"default\"\n  api_gateway_redeployment_triggers = {\n    release : 1\n  }\n}\n```\n\nAnd to use the `infrablocks/api-gateway/aws//modules/domain` submodule:\n\n```terraform\nmodule \"domain\" {\n  source  = \"infrablocks/api-gateway/aws//modules/domain\"\n  version = \"2.0.0\"\n\n  region = \"eu-west-2\"\n\n  component             = \"api-gw\"\n  deployment_identifier = \"production\"\n\n  api_gateway_rest_api_id                 = module.api_gateway.api_gateway_rest_api_id\n  api_gateway_stage_name                  = \"default\"\n  api_gateway_domain_name                 = \"example.com\"\n  api_gateway_domain_name_certificate_arn = \"arn:aws:acm:eu-west-2:123456789101:certificate/31bd2209-f35b-4668-b48b-324f44fedc7e\"\n\n  dns = {\n    records : [\n      {\n        zone_id : \"Z0901234DIVFOTMNA324\"\n      }\n    ]\n  }\n}\n```\n\nThe `infrablocks/api-gateway/aws//modules/log_permissions` module should be\nused once per account, as follows:\n\n```terraform\nmodule \"domain\" {\n  source  = \"infrablocks/api-gateway/aws//modules/log_permissions\"\n  version = \"2.0.0\"\n}\n```\n\nSee the\n[Terraform registry entry](https://registry.terraform.io/modules/infrablocks/api-gateway/aws/latest)\nfor more details.\n\n### Inputs\n\n#### Root Module\n\n| Name                                          | Description                                                                                                                                           | Default  |           Required           |\n|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|:----------------------------:|\n| `region`                                      | The region into which to deploy the API gateway REST API.                                                                                             |    -     |             Yes              |\n| `component`                                   | The component for which the API gateway REST API is being created.                                                                                    |    -     |             Yes              |\n| `deployment_identifier`                       | An identifier for this instantiation                                                                                                                  |    -     |             Yes              |\n| `api_gateway_rest_api_endpoint_type`          | The type of the endpoints in this REST API. Valid values: `\"EDGE\"`, `\"REGIONAL\"` or `\"PRIVATE\"`.                                                      | `\"EDGE\"` |              No              |\n| `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 |\n| `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 |\n| `include_api_gateway_rest_api_policy`         | Whether or not to include an IAM policy on the REST API.                                                                                              | `false`  |              No              |\n\n#### Deployment Sub-module\n\n| Name                                | Description                                                                                                    | Default | Required |\n|-------------------------------------|----------------------------------------------------------------------------------------------------------------|:-------:|:--------:|\n| `region`                            | The region into which to deploy the API gateway deployment.                                                    |    -    |   Yes    |\n| `component`                         | The component for which the API gateway deployment is being created.                                           |    -    |   Yes    |\n| `deployment_identifier`             | An identifier for this instantiation.                                                                          |    -    |   Yes    |\n| `api_gateway_rest_api_id`           | The ID of the API gateway REST API for which this deployment is being managed.                                 |    -    |   Yes    |\n| `api_gateway_stage_name`            | The stage name for the API gateway stage created for this deployment.                                          |    -    |   Yes    |\n| `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    |\n| `tags`                              | A map of tags to add to created infrastructure components.                                                     |  `{}`   |    No    |\n\n#### Domain Sub-module\n\n| Name                                      | Description                                                                                      |   Default   | Required |\n|-------------------------------------------|--------------------------------------------------------------------------------------------------|:-----------:|:--------:|\n| `region`                                  | The region into which to deploy the API gateway domain.                                          |      -      |   Yes    |\n| `component`                               | The component for which the API gateway domain is being created.                                 |      -      |   Yes    |\n| `deployment_identifier`                   | An identifier for this instantiation.                                                            |      -      |   Yes    |\n| `api_gateway_rest_api_id`                 | The ID of the API gateway REST API for which this domain is being managed.                       |      -      |   Yes    |\n| `api_gateway_rest_api_endpoint_type`      | The type of the endpoints in this REST API. Valid values: `\"EDGE\"`, `\"REGIONAL\"` or `\"PRIVATE\"`. |  `\"EDGE\"`   |   Yes    |\n| `api_gateway_stage_name`                  | The stage name for the API gateway stage created for this deployment.                            |      -      |   Yes    |\n| `api_gateway_domain_name`                 | The domain name to use for the API gateway.                                                      |      -      |   Yes    |\n| `api_gateway_domain_name_certificate_arn` | The ARN of a certificate to associate with the API gateway for this domain.                      |      -      |   Yes    |\n| `api_gateway_domain_name_security_policy` | The security policy to use on the API gateway for this domain.                                   | `\"TLS_1_2\"` |    No    |\n| `api_gateway_domain_name_base_path`       | The base path at which to expose the API managed by the API gateway for this domain.             |      -      |    No    |\n| `dns`                                     | Details of the DNS records to create pointing at the API gateway for this domain name.           |    `[]`     |    No    |\n| `tags`                                    | AWS tags to use on created infrastructure components.                                            |    `{}`     |    No    |\n\n#### Log Permissions Sub-module\n\n| Name | Description | Default | Required |\n|------|-------------|:-------:|:--------:|\n\n### Outputs\n\n#### Root Module\n\n| Name                                    | Description                                                                                                                                                  |\n|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `api_gateway_rest_api_name`             | The name of the created API Gateway REST API.                                                                                                                |\n| `api_gateway_rest_api_id`               | The ID of the created API Gateway REST API.                                                                                                                  |\n| `api_gateway_rest_api_root_resource_id` | The resource ID of the REST API's root.                                                                                                                      |\n| `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. |\n\n#### Deployment Sub-module\n\n| Name                              | Description                                                  |\n|-----------------------------------|--------------------------------------------------------------|\n| `api_gateway_deployment_id`       | The ID of the API gateway deployment managed by this module. |\n| `api_gateway_stage_id`            | The ID of the API gateway stage managed by this module.      |\n| `api_gateway_stage_arn`           | The ARN of the API gateway stage managed by this module.     |\n| `api_gateway_stage_invoke_url`    | The invoke URL of the stage managed by this module.          |\n| `api_gateway_stage_execution_arn` | The execution ARN of the stage managed by this module.       |\n\n#### Domain Sub-module\n\n| Name                                             | Description                                                                                                                      |\n|--------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|\n| `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\"`.   |\n| `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\"`.       |\n| `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\"`. |\n| `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\"`.     |\n\n#### Log Permissions Sub-module\n\n| Name                       | Description                                                      |\n|----------------------------|------------------------------------------------------------------|\n| `logging_role_id`          | The ID of the managed API Gateway logging role.                  |\n| `logging_role_arn`         | The ARN of the managed API Gateway logging role.                 |\n| `logging_role_name`        | The name of the managed API Gateway logging role.                |\n| `logging_role_policy_id`   | The ID of the policy attached to the API Gateway logging role.   |\n| `logging_role_policy_name` | The name of the policy attached to the API Gateway logging role. |\n\n### Compatibility\n\nThis module and all submodules are compatible with Terraform versions greater\nthan or equal to Terraform 1.3 and the Terraform AWS provider 4.0.\n\nDevelopment\n-----------\n\n### Machine Requirements\n\nIn order for the build to run correctly, a few tools will need to be installed\non your development machine:\n\n* Ruby (3.1)\n* Bundler\n* git\n* git-crypt\n* gnupg\n* direnv\n* aws-vault\n\n#### Mac OS X Setup\n\nInstalling the required tools is best managed by [homebrew](http://brew.sh).\n\nTo install homebrew:\n\n```shell\nruby -e \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)\"\n```\n\nThen, to install the required tools:\n\n```shell\n# ruby\nbrew install rbenv\nbrew install ruby-build\necho 'eval \"$(rbenv init - bash)\"' \u003e\u003e ~/.bash_profile\necho 'eval \"$(rbenv init - zsh)\"' \u003e\u003e ~/.zshrc\neval \"$(rbenv init -)\"\nrbenv install 3.1.1\nrbenv rehash\nrbenv local 3.1.1\ngem install bundler\n\n# git, git-crypt, gnupg\nbrew install git\nbrew install git-crypt\nbrew install gnupg\n\n# aws-vault\nbrew cask install\n\n# direnv\nbrew install direnv\necho \"$(direnv hook bash)\" \u003e\u003e ~/.bash_profile\necho \"$(direnv hook zsh)\" \u003e\u003e ~/.zshrc\neval \"$(direnv hook $SHELL)\"\n\ndirenv allow \u003crepository-directory\u003e\n```\n\n### Running the build\n\nRunning the build requires an AWS account and AWS credentials. You are free to\nconfigure credentials however you like as long as an access key ID and secret\naccess key are available. These instructions utilise\n[aws-vault](https://github.com/99designs/aws-vault) which makes credential\nmanagement easy and secure.\n\nTo run the full build, including unit and integration tests, execute:\n\n```shell\naws-vault exec \u003cprofile\u003e -- ./go\n```\n\nTo run the unit tests, execute:\n\n```shell\naws-vault exec \u003cprofile\u003e -- ./go test:unit\n```\n\nTo run the integration tests, execute:\n\n```shell\naws-vault exec \u003cprofile\u003e -- ./go test:integration\n```\n\nTo provision the module prerequisites:\n\n```shell\naws-vault exec \u003cprofile\u003e -- ./go deployment:prerequisites:provision[\u003cdeployment_identifier\u003e]\n```\n\nTo provision the module contents:\n\n```shell\naws-vault exec \u003cprofile\u003e -- ./go deployment:root:provision[\u003cdeployment_identifier\u003e]\n```\n\nTo destroy the module contents:\n\n```shell\naws-vault exec \u003cprofile\u003e -- ./go deployment:root:destroy[\u003cdeployment_identifier\u003e]\n```\n\nTo destroy the module prerequisites:\n\n```shell\naws-vault exec \u003cprofile\u003e -- ./go deployment:prerequisites:destroy[\u003cdeployment_identifier\u003e]\n```\n\nConfiguration parameters can be overridden via environment variables. For\nexample, to run the unit tests with a seed of `\"testing\"`, execute:\n\n```shell\nSEED=testing aws-vault exec \u003cprofile\u003e -- ./go test:unit\n```\n\nWhen a seed is provided via an environment variable, infrastructure will not be\ndestroyed at the end of test execution. This can be useful during development\nto avoid lengthy provision and destroy cycles.\n\nTo subsequently destroy unit test infrastructure for a given seed:\n\n```shell\nFORCE_DESTROY=yes SEED=testing aws-vault exec \u003cprofile\u003e -- ./go test:unit\n```\n\n### Common Tasks\n\n#### Generating an SSH key pair\n\nTo generate an SSH key pair:\n\n```shell\nssh-keygen -m PEM -t rsa -b 4096 -C integration-test@example.com -N '' -f config/secrets/keys/bastion/ssh\n```\n\n#### Generating a self-signed certificate\n\nTo generate a self signed certificate:\n\n```shell\nopenssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365\n```\n\nTo decrypt the resulting key:\n\n```shell\nopenssl rsa -in key.pem -out ssl.key\n```\n\n#### Managing CircleCI keys\n\nTo encrypt a GPG key for use by CircleCI:\n\n```shell\nopenssl aes-256-cbc \\\n  -e \\\n  -md sha1 \\\n  -in ./config/secrets/ci/gpg.private \\\n  -out ./.circleci/gpg.private.enc \\\n  -k \"\u003cpassphrase\u003e\"\n```\n\nTo check decryption is working correctly:\n\n```shell\nopenssl aes-256-cbc \\\n  -d \\\n  -md sha1 \\\n  -in ./.circleci/gpg.private.enc \\\n  -k \"\u003cpassphrase\u003e\"\n```\n\nContributing\n------------\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/infrablocks/terraform-aws-api-gateway. This project is\nintended to be a safe, welcoming space for\ncollaboration, and contributors are expected to adhere to the\n[Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\nLicense\n-------\n\nThe library is available as open source under the terms of the\n[MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfrablocks%2Fterraform-aws-api-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfrablocks%2Fterraform-aws-api-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfrablocks%2Fterraform-aws-api-gateway/lists"}