Syntax Properties Return values Examples See also

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 Amazon 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" : Json
    }
}

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: Json

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: Json

Update requires: No interruption

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Reffunction, Refreturns the stage name, such as MyTestStage.

For more information about using the Reffunction, 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": 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"}