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 APIstageName
- (Required) Name of the stagedeploymentId
- (Required) ID of the deployment that the stage points toaccessLogSettings
- (Optional) Enables access logs for the API stage. See Access Log Settings below.cacheClusterEnabled
- (Optional) Whether a cache cluster is enabled for the stagecacheClusterSize
- (Optional) Size of the cache cluster for the stage, if enabled. Allowed values include05
,16
,61
,135
,284
,582
,118
and237
.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 documentationvariables
- (Optional) Map that defines the stage variablestags
- (Optional) Map of tags to assign to the resource. If configured with a providerdefaultTags
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 tofalse
.
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 withamazonApigateway
. 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) Percent00
-1000
of traffic to divert to the canary deployment.stageVariableOverrides
- (Optional) Map of overridden stagevariables
(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
- ARNid
- ID of the stageinvokeUrl
- URL to invoke the API pointing to the stage, e.g.,https://z4675Bid1JExecuteApiEuWest2AmazonawsCom/prod
executionArn
- Execution ARN to be used inlambdaPermission
'ssourceArn
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 providerdefaultTags
configuration block.webAclArn
- ARN of the WebAcl associated with the Stage.
Import
awsApiGatewayStage
can be imported using restApiId/stageName
, e.g.,