AWS::ApiGatewayV2::Stage - AWS CloudFormation

AWS::ApiGatewayV2::Stage

The AWS::ApiGatewayV2::Stage resource specifies a stage for an API. Each stage is a named reference to a deployment of the API and is made available for client applications to call. To learn more, see Working with stages for HTTP APIs and Deploy a WebSocket API in API Gateway.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{ "Type" : "AWS::ApiGatewayV2::Stage", "Properties" : { "AccessLogSettings" : AccessLogSettings, "AccessPolicyId" : String, "ApiId" : String, "AutoDeploy" : Boolean, "ClientCertificateId" : String, "DefaultRouteSettings" : RouteSettings, "DeploymentId" : String, "Description" : String, "RouteSettings" : Json, "StageName" : String, "StageVariables" : Json, "Tags" : [ Tag, ... ] } }

YAML

Type: AWS::ApiGatewayV2::Stage Properties: AccessLogSettings: AccessLogSettings AccessPolicyId: String ApiId: String AutoDeploy: Boolean ClientCertificateId: String DefaultRouteSettings: RouteSettings DeploymentId: String Description: String RouteSettings: Json StageName: String StageVariables: Json Tags: - Tag

Properties

AccessLogSettings

Settings for logging access in this stage.

Required: No

Type: AccessLogSettings

Update requires: No interruption

AccessPolicyId

This parameter is not currently supported.

Required: No

Type: String

Update requires: No interruption

ApiId

The API identifier.

Required: Yes

Type: String

Update requires: Replacement

AutoDeploy

Specifies whether updates to an API automatically trigger a new deployment. The default value is false.

Required: No

Type: Boolean

Update requires: No interruption

ClientCertificateId

The identifier of a client certificate for a Stage. Supported only for WebSocket APIs.

Required: No

Type: String

Update requires: No interruption

DefaultRouteSettings

The default route settings for the stage.

Required: No

Type: RouteSettings

Update requires: No interruption

DeploymentId

The deployment identifier for the API stage. Can't be updated if autoDeploy is enabled.

Required: No

Type: String

Update requires: No interruption

Description

The description for the API stage.

Required: No

Type: String

Update requires: No interruption

RouteSettings

Route settings for the stage.

Required: No

Type: Json

Update requires: No interruption

StageName

The stage name. Stage names can contain only alphanumeric characters, hyphens, and underscores, or be $default. Maximum length is 128 characters.

Required: Yes

Type: String

Update requires: Replacement

StageVariables

A map that defines the stage variables for a Stage. Variable names can have alphanumeric and underscore characters, and the values must match [A-Za-z0-9-._~:/?#&=,]+.

Required: No

Type: Json

Update requires: No interruption

Tags

The collection of tags. Each tag element is associated with a given resource.

Required: No

Type: Array of Tag

Update requires: No interruption

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the stage name, such as MyTestStage.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Id

The identifier.

Examples

Stage creation example

The following example creates a stage resource called MyStage and associates it with an existing deployment called MyDeployment.

JSON

{ "MyStage": { "Type": "AWS::ApiGatewayV2::Stage", "Properties": { "StageName": "Prod", "Description": "Prod Stage", "DeploymentId": { "Ref": "MyDeployment" }, "ApiId": { "Ref": "CFNWebSocket" }, "DefaultRouteSettings": { "DetailedMetricsEnabled": true, "LoggingLevel": "INFO", "DataTraceEnabled": false, "ThrottlingBurstLimit": 10, "ThrottlingRateLimit": 10 }, "AccessLogSettings": { "DestinationArn": "arn:aws:logs:us-east-1:123456789:log-group:my-log-group", "Format": "{\"requestId\":\"$context.requestId\", \"ip\": \"$context.identity.sourceIp\", \"caller\":\"$context.identity.caller\", \"user\":\"$context.identity.user\",\"requestTime\":\"$context.requestTime\", \"eventType\":\"$context.eventType\",\"routeKey\":\"$context.routeKey\", \"status\":\"$context.status\",\"connectionId\":\"$context.connectionId\"}" } } } }

YAML

MyStage: Type: 'AWS::ApiGatewayV2::Stage' Properties: StageName: Prod Description: Prod Stage DeploymentId: !Ref MyDeployment ApiId: !Ref CFNWebSocket DefaultRouteSettings: DetailedMetricsEnabled: true LoggingLevel: INFO DataTraceEnabled: false ThrottlingBurstLimit: 10 ThrottlingRateLimit: 10 AccessLogSettings: DestinationArn: 'arn:aws:logs:us-east-1:123456789:log-group:my-log-group' Format: >- {"requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "caller":"$context.identity.caller", "user":"$context.identity.user","requestTime":"$context.requestTime", "eventType":"$context.eventType","routeKey":"$context.routeKey", "status":"$context.status","connectionId":"$context.connectionId"}

See also

  • CreateStage in the Amazon API Gateway Version 2 API Reference