AWS CloudFormation
User Guide (Version )

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

AWS::ApiGatewayV2::Stage

The AWS::ApiGatewayV2::Stage resource updates a stage for a WebSocket API. For more information, see Deploy a WebSocket API in API Gateway in the API Gateway Developer Guide.

Syntax

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

JSON

{ "Type" : "AWS::ApiGatewayV2::Stage", "Properties" : { "AccessLogSettings" : AccessLogSettings, "ApiId" : String, "ClientCertificateId" : String, "DefaultRouteSettings" : RouteSettings, "DeploymentId" : String, "Description" : String, "RouteSettings" : Json, "StageName" : String, "StageVariables" : Json, "Tags" : Json } }

YAML

Type: AWS::ApiGatewayV2::Stage Properties: AccessLogSettings: AccessLogSettings ApiId: String ClientCertificateId: String DefaultRouteSettings: RouteSettings DeploymentId: String Description: String RouteSettings: Json StageName: String StageVariables: Json Tags: Json

Properties

AccessLogSettings

Settings for logging access in this stage.

Required: No

Type: AccessLogSettings

Update requires: No interruption

ApiId

The API identifier.

Required: Yes

Type: String

Update requires: Replacement

ClientCertificateId

The identifier of a client certificate for a Stage.

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.

Required: Yes

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 only contain alphanumeric characters, hyphens, and underscores. 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: Json

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.

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": true, "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: true 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