AWS CloudFormation
User Guide (Version )

AWS::ApiGateway::Stage

The AWS::ApiGateway::Stage resource creates a stage for a deployment.

Syntax

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

JSON

{ "Type" : "AWS::ApiGateway::Stage", "Properties" : { "AccessLogSetting" : AccessLogSetting, "CacheClusterEnabled" : Boolean, "CacheClusterSize" : String, "CanarySetting" : CanarySetting, "ClientCertificateId" : String, "DeploymentId" : String, "Description" : String, "DocumentationVersion" : String, "MethodSettings" : [ MethodSetting, ... ], "RestApiId" : String, "StageName" : String, "Tags" : [ Tag, ... ], "TracingEnabled" : Boolean, "Variables" : {Key : Value, ...} } }

YAML

Type: AWS::ApiGateway::Stage Properties: AccessLogSetting: AccessLogSetting CacheClusterEnabled: Boolean CacheClusterSize: String CanarySetting: CanarySetting ClientCertificateId: String DeploymentId: String Description: String DocumentationVersion: String MethodSettings: - MethodSetting RestApiId: String StageName: String Tags: - Tag TracingEnabled: Boolean Variables: Key : Value

Properties

AccessLogSetting

Specifies settings for logging access in this stage.

Required: No

Type: AccessLogSetting

Update requires: No interruption

CacheClusterEnabled

Indicates whether cache clustering is enabled for the stage.

Required: No

Type: Boolean

Update requires: No interruption

CacheClusterSize

The stage's cache cluster size.

Required: No

Type: String

Update requires: No interruption

CanarySetting

Specifies settings for the canary deployment in this stage.

Required: No

Type: CanarySetting

Update requires: No interruption

ClientCertificateId

The ID of the client certificate that API Gateway uses to call your integration endpoints in the stage.

Required: No

Type: String

Update requires: No interruption

DeploymentId

The ID of the deployment that the stage is associated with. This parameter is required.

Required: No

Type: String

Update requires: No interruption

Description

A description of the stage.

Required: No

Type: String

Update requires: No interruption

DocumentationVersion

The version ID of the API documentation snapshot.

Required: No

Type: String

Update requires: No interruption

MethodSettings

Settings for all methods in the stage.

Required: No

Type: List of MethodSetting

Update requires: No interruption

RestApiId

The ID of the RestApi resource that you're deploying with this stage.

Required: Yes

Type: String

Update requires: Replacement

StageName

The name of the stage, which API Gateway uses as the first path segment in the invoked Uniform Resource Identifier (URI).

Required: No

Type: String

Update requires: Replacement

Tags

An array of arbitrary tags (key-value pairs) to associate with the stage.

Required: No

Type: List of Tag

Update requires: No interruption

TracingEnabled

Specifies whether active X-Ray tracing is enabled for this stage.

For more information, see Trace API Gateway API Execution with AWS X-Ray in the API Gateway Developer Guide.

Required: No

Type: Boolean

Update requires: No interruption

Variables

A map (string-to-string map) that defines the stage variables, where the variable name is the key and the variable value is the value. Variable names are limited to alphanumeric characters. Values must match the following regular expression: [A-Za-z0-9-._~:/?#&=,]+.

Required: No

Type: Map of String

Update requires: No interruption

Return Values

Ref

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

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

Examples

Create stage

The following example creates a stage for the TestDeployment deployment. The stage also specifies method settings for the MyRestApi API.

JSON

{ "Resources": { "Prod": { "Type": "AWS::ApiGateway::Stage", "Properties": { "StageName": "Prod", "Description": "Prod Stage", "RestApiId": { "Ref": "MyRestApi" }, "DeploymentId": { "Ref": "TestDeployment" }, "DocumentationVersion": { "Ref": "MyDocumentationVersion" }, "ClientCertificateId": { "Ref": "ClientCertificate" }, "Variables": { "Stack": "Prod" }, "MethodSettings": [ { "ResourcePath": "/", "HttpMethod": "GET", "MetricsEnabled": "true", "DataTraceEnabled": "true" }, { "ResourcePath": "/stack", "HttpMethod": "POST", "MetricsEnabled": "true", "DataTraceEnabled": "true", "ThrottlingBurstLimit": "999" }, { "ResourcePath": "/stack", "HttpMethod": "GET", "MetricsEnabled": "true", "DataTraceEnabled": "true", "ThrottlingBurstLimit": "555" } ] } } } }

YAML

Resources: Prod: Type: AWS::ApiGateway::Stage Properties: StageName: Prod Description: Prod Stage RestApiId: !Ref MyRestApi DeploymentId: !Ref TestDeployment DocumentationVersion: !Ref MyDocumentationVersion ClientCertificateId: !Ref ClientCertificate Variables: Stack: Prod MethodSettings: - ResourcePath: / HttpMethod: GET MetricsEnabled: 'true' DataTraceEnabled: 'true' - ResourcePath: /stack HttpMethod: POST MetricsEnabled: 'true' DataTraceEnabled: 'true' ThrottlingBurstLimit: '999' - ResourcePath: /stack HttpMethod: GET MetricsEnabled: 'true' DataTraceEnabled: 'true' ThrottlingBurstLimit: '555'

See Also