Resource: awsApiGatewayDeployment

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 awsApiGatewayStage resource and optionally managed further with the awsApiGatewayBasePathMapping resource, awsApiGatewayDomainName resource, and awsApiMethodSettings 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 (awsApiGatewayRestApi 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 (awsApiGatewayIntegration resource, etc.), the dependency setup can be done with implicit resource references in the triggers argument or explicit resource references using the resource dependsOn meta-argument. The triggers argument should be preferred over dependsOn, since dependsOn can only capture dependency ordering and will not cause the resource to recreate (redeploy the REST API) with upstream configuration changes.

!> WARNING: We recommend using the awsApiGatewayStage resource instead of managing an API Gateway Stage via the stageName argument of this resource. When this resource is recreated (REST API redeployment) with the stageName 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 awsApiMethodSettings resources.

\~> NOTE: Enable the resource lifecycle configuration block createBeforeDestroy argument in this resource configuration to properly order redeployments in Terraform. Without enabling createBeforeDestroy, API Gateway can return errors such as badRequestException:ActiveStagesPointingToThisDeploymentMustBeMovedOrDeleted on recreation.

Example Usage

OpenAPI Specification

An end-to-end example of a REST API configured with OpenAPI can be found in the /examples/apiGatewayRestApiOpenapi directory within the GitHub repository.

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsApiGatewayRestApiExample = new aws.apiGatewayRestApi.ApiGatewayRestApi(
  this,
  "example",
  {
    body: '${jsonencode({\n    openapi = "3.0.1"\n    info = {\n      title   = "example"\n      version = "1.0"\n    }\n    paths = {\n      "/path1" = {\n        get = {\n          x-amazon-apigateway-integration = {\n            httpMethod           = "GET"\n            payloadFormatVersion = "1.0"\n            type                 = "HTTP_PROXY"\n            uri                  = "https://ip-ranges.amazonaws.com/ip-ranges.json"\n          }\n        }\n      }\n    }\n  })}',
    name: "example",
  }
);
const awsApiGatewayDeploymentExample =
  new aws.apiGatewayDeployment.ApiGatewayDeployment(this, "example_1", {
    restApiId: awsApiGatewayRestApiExample.id,
    triggers: {
      redeployment: `\${sha1(jsonencode(${awsApiGatewayRestApiExample.body}))}`,
    },
  });
awsApiGatewayDeploymentExample.addOverride("lifecycle", [
  {
    create_before_destroy: true,
  },
]);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsApiGatewayDeploymentExample.overrideLogicalId("example");
const awsApiGatewayStageExample = new aws.apiGatewayStage.ApiGatewayStage(
  this,
  "example_2",
  {
    deploymentId: awsApiGatewayDeploymentExample.id,
    restApiId: awsApiGatewayRestApiExample.id,
    stageName: "example",
  }
);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsApiGatewayStageExample.overrideLogicalId("example");

Terraform Resources

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
const awsApiGatewayRestApiExample = new aws.apiGatewayRestApi.ApiGatewayRestApi(
  this,
  "example",
  {
    name: "example",
  }
);
const awsApiGatewayResourceExample =
  new aws.apiGatewayResource.ApiGatewayResource(this, "example_1", {
    parentId: awsApiGatewayRestApiExample.rootResourceId,
    pathPart: "example",
    restApiId: awsApiGatewayRestApiExample.id,
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsApiGatewayResourceExample.overrideLogicalId("example");
const awsApiGatewayMethodExample = new aws.apiGatewayMethod.ApiGatewayMethod(
  this,
  "example_2",
  {
    authorization: "NONE",
    httpMethod: "GET",
    resourceId: awsApiGatewayResourceExample.id,
    restApiId: awsApiGatewayRestApiExample.id,
  }
);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsApiGatewayMethodExample.overrideLogicalId("example");
const awsApiGatewayIntegrationExample =
  new aws.apiGatewayIntegration.ApiGatewayIntegration(this, "example_3", {
    httpMethod: awsApiGatewayMethodExample.httpMethod,
    resourceId: awsApiGatewayResourceExample.id,
    restApiId: awsApiGatewayRestApiExample.id,
    type: "MOCK",
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsApiGatewayIntegrationExample.overrideLogicalId("example");
const awsApiGatewayDeploymentExample =
  new aws.apiGatewayDeployment.ApiGatewayDeployment(this, "example_4", {
    restApiId: awsApiGatewayRestApiExample.id,
    triggers: {
      redeployment: `\${sha1(jsonencode([
      ${awsApiGatewayResourceExample.id},
      ${awsApiGatewayMethodExample.id},
      ${awsApiGatewayIntegrationExample.id},
    ]))}`,
    },
  });
awsApiGatewayDeploymentExample.addOverride("lifecycle", [
  {
    create_before_destroy: true,
  },
]);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsApiGatewayDeploymentExample.overrideLogicalId("example");
const awsApiGatewayStageExample = new aws.apiGatewayStage.ApiGatewayStage(
  this,
  "example_5",
  {
    deploymentId: awsApiGatewayDeploymentExample.id,
    restApiId: awsApiGatewayRestApiExample.id,
    stageName: "example",
  }
);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsApiGatewayStageExample.overrideLogicalId("example");

Argument Reference

The following arguments are supported:

restApiId - (Required) REST API identifier.
description - (Optional) Description of the deployment
stageName - (Optional) Name of the stage to create with this deployment. If the specified stage already exists, it will be updated to point to the new deployment. We recommend using the awsApiGatewayStage resource instead to manage stages.
stageDescription - (Optional) Description to set on the stage managed by the stageName argument.
triggers - (Optional) Map of arbitrary keys and values that, when changed, will trigger a redeployment. To force a redeployment without changing these keys/values, use the replace option with terraformPlan or terraformApply.
variables - (Optional) Map to set on the stage managed by the stageName argument.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

id - ID of the deployment
invokeUrl - URL to invoke the API pointing to the stage, e.g., https://z4675Bid1JExecuteApiEuWest2AmazonawsCom/prod
executionArn - Execution ARN to be used in lambdaPermission's sourceArn when allowing API Gateway to invoke a Lambda function, e.g., arn:aws:executeApi:euWest2:123456789012:z4675Bid1J/prod
createdDate - Creation date of the deployment

Import

awsApiGatewayDeployment can be imported using restApiId/deploymentId, e.g.,

$ terraform import aws_api_gateway_deployment.example aabbccddee/1122334

The stageName, stageDescription, and variables arguments cannot be imported. Use the awsApiGatewayStage resource to import and manage stages.

The triggers argument cannot be imported.