AWS API Gateway Deployment
This page shows how to write Terraform and CloudFormation for API Gateway Deployment and write them securely.
aws_api_gateway_deployment (Terraform)
The Deployment in API Gateway can be configured in Terraform with the resource name aws_api_gateway_deployment
. The following sections describe 5 examples of how to use the resource and its parameters.
Example Usage from GitHub
resource "aws_api_gateway_deployment" "api_gateway_deployment_20210316_1" {
rest_api_id = aws_api_gateway_rest_api.api_gateway.id
}
resource "aws_api_gateway_deployment" "api_gateway_deployment_20210316_2" {
rest_api_id = aws_api_gateway_rest_api.api_gateway.id
resource "aws_api_gateway_deployment" "aplha_deployment" {
depends_on = [aws_api_gateway_integration.accounts_integration, aws_api_gateway_integration.confirmation_integration, aws_api_gateway_integration.events_integration, aws_api_gateway_integration.notifications_integration, aws_api_gateway_integration.payment_integration]
rest_api_id = aws_api_gateway_rest_api.main.id
stage_name = "alpha"
resource "aws_api_gateway_deployment" "aplha_deployment" {
depends_on = [aws_api_gateway_integration.accounts_integration, aws_api_gateway_integration.confirmation_integration, aws_api_gateway_integration.events_integration, aws_api_gateway_integration.notifications_integration, aws_api_gateway_integration.payment_integration]
rest_api_id = aws_api_gateway_rest_api.main.id
stage_name = "alpha"
resource "aws_api_gateway_deployment" "test" {
depends_on = [
module.GetMovies,
module.GetOneMovie,
module.GetFavorites,
module.PostFavorites
resource "aws_api_gateway_deployment" "sum" {
depends_on = [
aws_api_gateway_integration.sum,
aws_api_gateway_integration.sum_lambda_root,
]
Parameters
-
created_date
optional computed - string -
description
optional - string -
execution_arn
optional computed - string -
id
optional computed - string -
invoke_url
optional computed - string -
rest_api_id
required - string -
stage_description
optional - string -
stage_name
optional - string -
triggers
optional - map from string to string -
variables
optional - map from string to string
Explanation in Terraform Registry
Manages an API Gateway REST Deployment. A deployment is a snapshot of the REST API configuration. The deployment can then be published to callable endpoints via the
aws_api_gateway_stage
resource and optionally managed further with theaws_api_gateway_base_path_mapping
resource,aws_api_gateway_domain_name
resource, andaws_api_method_settings
resource. For more information, see the API Gateway Developer Guide. To properly capture all REST API configuration in a deployment, this resource must have dependencies on all prior Terraform resources that manage resources/paths, methods, integrations, etc.
- For REST APIs that are configured via OpenAPI specification (
aws_api_gateway_rest_api
resourcebody
argument), no special dependency setup is needed beyond referencing theid
attribute of that resource unless additional Terraform resources have further customized the REST API.- When the REST API configuration involves other Terraform resources (
aws_api_gateway_integration
resource, etc.), the dependency setup can be done with implicit resource references in thetriggers
argument or explicit resource references using the resourcedepends_on
meta-argument. Thetriggers
argument should be preferred overdepends_on
, sincedepends_on
can only capture dependency ordering and will not cause the resource to recreate (redeploy the REST API) with upstream configuration changes. !> WARNING: It is recommended to use theaws_api_gateway_stage
resource instead of managing an API Gateway Stage via thestage_name
argument of this resource. When this resource is recreated (REST API redeployment) with thestage_name
configured, the stage is deleted and recreated. This will cause a temporary service interruption, increase Terraform plan differences, and can require a second Terraform apply to recreate any downstream stage configuration such as associatedaws_api_method_settings
resources.NOTE: It is recommended to enable the resource
lifecycle
configuration blockcreate_before_destroy
argument in this resource configuration to properly order redeployments in Terraform. Without enablingcreate_before_destroy
, API Gateway can return errors such asBadRequestException: Active stages pointing to this deployment must be moved or deleted
on recreation.
Tips: Best Practices for The Other AWS API Gateway Resources
In addition to the aws_api_gateway_method_settings, AWS API Gateway has the other resources that should be configured for security reasons. Please check some examples of those resources and precautions.
aws_api_gateway_method_settings
Ensure that API Gateway stage-level cache is encrypted
It is better to enable the stage-level cache encryption which reduces the risk of data leakage.
aws_api_gateway_domain_name
Ensure to use modern TLS protocols
It is better to adopt TLS v1.2+.
aws_api_gateway_stage
Ensure to enable access logging of your API Gateway stage (v1)
It is better to enable the access logging of your API Gateway stage (v1).
aws_api_gateway_method
Ensure that your API Gateway method blocks unwanted access
It is better that the API Gateway method does not allow public access.
AWS::ApiGateway::Method Dependency (CloudFormation)
The Method Dependency in ApiGateway can be configured in CloudFormation with the resource name AWS::ApiGateway::Method Dependency
. The following sections describe how to use the resource and its parameters.
Example Usage from GitHub
An example could not be found in GitHub.
Parameters
DeploymentCanarySettings
Specifies settings for the canary deployment.
Required: No
Type: DeploymentCanarySettings
Update requires: Replacement
Description
A description of the purpose of the API Gateway deployment.
Required: No
Type: String
Update requires: No interruption
RestApiId
The ID of the RestApi
resource to deploy.
Required: Yes
Type: String
Update requires: Replacement
StageDescription
Configures the stage that API Gateway creates with this deployment.
Required: No
Type: StageDescription
Update requires: No interruption
StageName
A name for the stage that API Gateway creates with this deployment. Use only alphanumeric characters.
Required: No
Type: String
Update requires: No interruption
Explanation in CloudFormation Registry
The
AWS::ApiGateway::Deployment
resource deploys an API GatewayRestApi
resource to a stage so that clients can call the API over the internet. The stage acts as an environment.If you create an AWS::ApiGateway::RestApi resource and its methods (using AWS::ApiGateway::Method) in the same template as your deployment, the deployment must depend on the
RestApi
's methods. To create a dependency, add aDependsOn
attribute to the deployment. If you don't, AWS CloudFormation creates the deployment right after it creates theRestApi
resource that doesn't contain any methods, and AWS CloudFormation encounters the following error:The REST API doesn't contain any methods
.
Frequently asked questions
What is AWS API Gateway Deployment?
AWS API Gateway Deployment is a resource for API Gateway of Amazon Web Service. Settings can be wrote in Terraform and CloudFormation.
Where can I find the example code for the AWS API Gateway Deployment?
For Terraform, the simweijie/equeue-terraform-apigateway, Paridhi-Mohindra/terraform-aws-api-gw-cookiecutter-template and Paridhi-Mohindra/1-aws source code examples are useful. See the Terraform Example section for further details.