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

deployments.tf#L1
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
deployments.tf#L1
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"

deployments.tf#L1
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"

apigateway.tf#L65
resource "aws_api_gateway_deployment" "test" {
   depends_on = [
     module.GetMovies,
     module.GetOneMovie,
     module.GetFavorites,
     module.PostFavorites
api_gateway.tf#L232
resource "aws_api_gateway_deployment" "sum" {
   depends_on = [
     aws_api_gateway_integration.sum,
     aws_api_gateway_integration.sum_lambda_root,

   ]

Parameters

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 the aws_api_gateway_base_path_mapping resource, aws_api_gateway_domain_name resource, and aws_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 resource body argument), no special dependency setup is needed beyond referencing the id 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 the triggers argument or explicit resource references using the resource depends_on meta-argument. The triggers argument should be preferred over depends_on, since depends_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 the aws_api_gateway_stage resource instead of managing an API Gateway Stage via the stage_name argument of this resource. When this resource is recreated (REST API redeployment) with the stage_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 associated aws_api_method_settings resources.

    NOTE: It is recommended to enable the resource lifecycle configuration block create_before_destroy argument in this resource configuration to properly order redeployments in Terraform. Without enabling create_before_destroy, API Gateway can return errors such as BadRequestException: Active stages pointing to this deployment must be moved or deleted on recreation.

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 Gateway RestApi 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 a DependsOn attribute to the deployment. If you don't, AWS CloudFormation creates the deployment right after it creates the RestApi 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.