Skip to content

Resource: awsApiGatewayStage

Manages an API Gateway Stage. A stage is a named reference to a deployment, which can be done via the awsApiGatewayDeployment resource. Stages can be optionally managed further with the awsApiGatewayBasePathMapping resource, awsApiGatewayDomainName resource, and awsApiMethodSettings resource. For more information, see the API Gateway Developer Guide.

Example Usage

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");
const awsApiGatewayMethodSettingsExample =
  new aws.apiGatewayMethodSettings.ApiGatewayMethodSettings(this, "example_3", {
    methodPath: "*/*",
    restApiId: awsApiGatewayRestApiExample.id,
    settings: {
      loggingLevel: "INFO",
      metricsEnabled: true,
    },
    stageName: awsApiGatewayStageExample.stageName,
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsApiGatewayMethodSettingsExample.overrideLogicalId("example");

Managing the API Logging CloudWatch Log Group

API Gateway provides the ability to enable CloudWatch API logging. To manage the CloudWatch Log Group when this feature is enabled, the awsCloudwatchLogGroup resource can be used where the name matches the API Gateway naming convention. If the CloudWatch Log Group previously exists, the awsCloudwatchLogGroup resource can be imported into Terraform as a one time operation and recreation of the environment can occur without import.

-> The below configuration uses dependsOn to prevent ordering issues with API Gateway automatically creating the log group first and a variable for naming consistency. Other ordering and naming methodologies may be more appropriate for your environment.

import * as cdktf from "cdktf";
/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
/*Terraform Variables are not always the best fit for getting inputs in the context of Terraform CDK.
You can read more about this at https://cdk.tf/variables*/
const stageName = new cdktf.TerraformVariable(this, "stage_name", {
  default: "example",
});
const awsApiGatewayRestApiExample = new aws.apiGatewayRestApi.ApiGatewayRestApi(
  this,
  "example",
  {}
);
const awsCloudwatchLogGroupExample =
  new aws.cloudwatchLogGroup.CloudwatchLogGroup(this, "example_2", {
    name: `API-Gateway-Execution-Logs_\${${awsApiGatewayRestApiExample.id}}/\${${stageName.value}}`,
    retentionInDays: 7,
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
awsCloudwatchLogGroupExample.overrideLogicalId("example");
const awsApiGatewayStageExample = new aws.apiGatewayStage.ApiGatewayStage(
  this,
  "example_3",
  {
    depends_on: [`\${${awsCloudwatchLogGroupExample.fqn}}`],
    stageName: stageName.value,
  }
);
/*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) ID of the associated REST API
  • stageName - (Required) Name of the stage
  • deploymentId - (Required) ID of the deployment that the stage points to
  • accessLogSettings - (Optional) Enables access logs for the API stage. See Access Log Settings below.
  • cacheClusterEnabled - (Optional) Whether a cache cluster is enabled for the stage
  • cacheClusterSize - (Optional) Size of the cache cluster for the stage, if enabled. Allowed values include 05, 16, 61, 135, 284, 582, 118 and 237.
  • canarySettings - (Optional) Configuration settings of a canary deployment. See Canary Settings below.
  • clientCertificateId - (Optional) Identifier of a client certificate for the stage.
  • description - (Optional) Description of the stage.
  • documentationVersion - (Optional) Version of the associated API documentation
  • variables - (Optional) Map that defines the stage variables
  • tags - (Optional) Map of tags to assign to the resource. If configured with a provider defaultTags configuration block present, tags with matching keys will overwrite those defined at the provider-level.
  • xrayTracingEnabled - (Optional) Whether active tracing with X-ray is enabled. Defaults to false.

Access Log Settings

  • destinationArn - (Required) ARN of the CloudWatch Logs log group or Kinesis Data Firehose delivery stream to receive access logs. If you specify a Kinesis Data Firehose delivery stream, the stream name must begin with amazonApigateway. Automatically removes trailing :* if present.
  • format - (Required) Formatting and values recorded in the logs. For more information on configuring the log format rules visit the AWS documentation

Canary Settings

  • percentTraffic - (Optional) Percent 00 - 1000 of traffic to divert to the canary deployment.
  • stageVariableOverrides - (Optional) Map of overridden stage variables (including new variables) for the canary deployment.
  • useStageCache - (Optional) Whether the canary deployment uses the stage cache. Defaults to false.

Attributes Reference

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

  • arn - ARN
  • id - ID of the stage
  • 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
  • tagsAll - Map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.
  • webAclArn - ARN of the WebAcl associated with the Stage.

Import

awsApiGatewayStage can be imported using restApiId/stageName, e.g.,

$ terraform import aws_api_gateway_stage.example 12345abcde/example