AWS::StepFunctions::StateMachineAlias - AWS CloudFormation
SyntaxPropertiesReturn valuesExamples

AWS::StepFunctions::StateMachineAlias

Represents a state machine alias. An alias routes traffic to one or two versions of the same state machine.

You can create up to 100 aliases for each state machine.

Syntax

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

JSON

{
  "Type" : "AWS::StepFunctions::StateMachineAlias",
  "Properties" : {
      "DeploymentPreference" : DeploymentPreference,
      "Description" : String,
      "Name" : String,
      "RoutingConfiguration" : [ RoutingConfigurationVersion, ... ]
    }
}

YAML

Type: AWS::StepFunctions::StateMachineAlias
Properties:
  DeploymentPreference: 
    DeploymentPreference
  Description: String
  Name: String
  RoutingConfiguration: 
    - RoutingConfigurationVersion

Properties

DeploymentPreference

The settings that enable gradual state machine deployments. These settings include Alarms, Interval, Percentage, StateMachineVersionArn, and Type.

CloudFormation automatically shifts traffic from the version an alias currently points to, to a new state machine version that you specify.

Note

RoutingConfiguration and DeploymentPreference are mutually exclusive properties. You must define only one of these properties.

Based on the type of deployment you want to perform, you can specify one of the following settings:

  • LINEAR - Shifts traffic to the new version in equal increments with an equal number of minutes between each increment.

    For example, if you specify the increment percent as 20 with an interval of 600 minutes, this deployment increases traffic by 20 percent every 600 minutes until the new version receives 100 percent of the traffic. This deployment immediately rolls back the new version if any Amazon CloudWatch alarms are triggered.

  • ALL_AT_ONCE - Shifts 100 percent of traffic to the new version immediately. CloudFormation monitors the new version and rolls it back automatically to the previous version if any CloudWatch alarms are triggered.

  • CANARY - Shifts traffic in two increments.

    In the first increment, a small percentage of traffic, for example, 10 percent is shifted to the new version. In the second increment, before a specified time interval in seconds gets over, the remaining traffic is shifted to the new version. The shift to the new version for the remaining traffic takes place only if no CloudWatch alarms are triggered during the specified time interval.

Required: No

Type: DeploymentPreference

Update requires: No interruption

Description

An optional description of the state machine alias.

Required: No

Type: String

Minimum: 1

Maximum: 256

Update requires: No interruption

Name

The name of the state machine alias. If you don't provide a name, it uses an automatically generated name based on the logical ID.

Required: No

Type: String

Minimum: 1

Maximum: 80

Update requires: Replacement

RoutingConfiguration

The routing configuration of an alias. Routing configuration splits StartExecution requests between one or two versions of the same state machine.

Use RoutingConfiguration if you want to explicitly set the alias weights. Weight is the percentage of traffic you want to route to a state machine version.

Note

RoutingConfiguration and DeploymentPreference are mutually exclusive properties. You must define only one of these properties.

Required: No

Type: Array of RoutingConfigurationVersion

Minimum: 1

Maximum: 2

Update requires: No interruption

Return values

Ref

When you provide the logical ID of this resource to the Ref intrinsic function, Ref returns the ARN of the created state machine alias. For example,

{ "Ref": "PROD" }

Returns the ARN of the created state machine alias as shown in the following example.

arn:aws:states:us-east-1:123456789012:stateMachine:myStateMachine:PROD

For more information about using Ref, see Ref.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following is the available attribute.

For more information about using Fn::GetAtt, see Fn::GetAtt.

Arn

Returns the ARN of the state machine alias. For example, arn:aws:states:us-east-1:123456789012:stateMachine:myStateMachine:PROD.

Examples

The following are examples of LINEAR deployment that show how you can use an alias to shift traffic to a new version.

Shifting traffic to a new version with an alias

The following example shows an alias named PROD that shifts 20 percent of traffic to the version B every five minutes.

YAML

PROD:
  Type: AWS::StepFunctions::Alias
  Properties:
    Name: PROD
    Description: The PROD state machine alias taking production traffic.
    DeploymentPreference:
      StateMachineVersionArn: !Ref MyStateMachineVersionB
      Type: LINEAR
      Interval: 5
      Percentage: 20
      Alarms:
        # A list of alarms that you want to monitor
        - !Ref AliasErrorMetricGreaterThanZeroAlarm
        - !Ref LatestVersionErrorMetricGreaterThanZeroAlarm

Complete example to publish and deploy a new version with an alias

The following example publishes multiple versions of the same state machine with the AWS::StepFunctions::StateMachineVersion resource. The example also creates an alias with the AWS::StepFunctions::StateMachineAlias resource and uses that alias to deploy a new state machine version.

YAML

MyStateMachine:
  Type: AWS::StepFunctions::StateMachine
  Properties:
    StateMachineType: STANDARD
    StateMachineName: MyStateMachine
    RoleArn: arn:aws:iam::12345678912:role/myIamRole
    Definition:
      StartAt: PassState
      States:
        PassState:
          Type: Pass
          Result: Result
          End: true

MyStateMachineVersionA:
  Type: AWS::StepFunctions::StateMachineVersion
  Properties:
    Description: Version 1
    StateMachineArn: !Ref MyStateMachine

MyStateMachineVersionB:
  Type: AWS::StepFunctions::StateMachineVersion
  Properties:
    Description: Version 2
    StateMachineArn: !Ref MyStateMachine

PROD:
  Type: AWS::StepFunctions::StateMachineAlias
  Properties:
    Name: PROD
    Description: The PROD state machine alias taking production traffic.
    DeploymentPreference:
      StateMachineVersionArn: !Ref MyStateMachineVersionB
      Type: LINEAR
      Percentage: 20
      Interval: 5
      Alarms:
        - !Ref CloudWatchAlarm1
        - !Ref CloudWatchAlarm2

Publish and deploy a version that always points to the most recent state machine revision

The following example demonstrates the use of StateMachineRevisionId property to return the value of revision ID for the state machine resource. CloudFormation automatically detects if this property's value is different from the value in previous stack and publishes a new version that always points to the most recent revision of your state machine. The example then creates an alias named PROD to deploy this new version.

YAML

MyStateMachine:
  Type: AWS::StepFunctions::StateMachine
  Properties:
    StateMachineType: STANDARD
    StateMachineName: MyStateMachine
    RoleArn: arn:aws:iam::12345678912:role/myIamRole
    Definition:
      StartAt: PassState
      States:
        PassState:
          Type: Pass
          Result: Result
          End: true

MyStateMachineVersion:
  Type: AWS::StepFunctions::StateMachineVersion
  Properties:
    Description: Version referencing 
    StateMachineArn: !Ref MyStateMachine
    StateMachineRevisionId: !GetAtt MyStateMachine.StateMachineRevisionId

PROD:
  Type: AWS::StepFunctions::StateMachineAlias
  Properties:
    Name: PROD
    Description: The PROD state machine alias taking production traffic.
    DeploymentPreference:
      StateMachineVersionArn: !Ref MyStateMachineVersionB
      Type: LINEAR
      Percentage: 20
      Interval: 5
      Alarms:
        - !Ref CloudWatchAlarm1
        - !Ref CloudWatchAlarm2