Example: Alias and version deployment in Step Functions
The following example of the Canary deployment technique shows how you can deploy a new state machine version with the Amazon Command Line Interface. In this example, the alias you create routes 20 percent of execution traffic to the new version. It then routes the remaining 80 percent the earlier version. To deploy a new state machine version and shift execution traffic with an alias, complete the following steps:
-
Publish a version from the current state machine revision.
Use the publish-state-machine-version command in the Amazon CLI to publish a version from the current revision of a state machine called
myStateMachine
:aws stepfunctions publish-state-machine-version --state-machine-arn arn:aws-cn:states:us-east-1:
123456789012
:stateMachine:myStateMachine
The response returns the
stateMachineVersionArn
of the version that you published. For example,arn:aws-cn:states:us-east-1:
.123456789012
:stateMachine:myStateMachine
:1 -
Create an alias that points to the state machine version.
Use the create-state-machine-alias command to create an alias named
that points to version 1 ofPROD
:myStateMachine
aws stepfunctions create-state-machine-alias --name PROD --routing-configuration "[{\"stateMachineVersionArn\":\"arn:aws-cn:states:us-east-1:
123456789012
:stateMachine:myStateMachine
:1
\",\"weight\":100}]" -
Verify that executions started by the alias use correct published version.
Start a new execution of
by providing the ARN of the aliasmyStateMachine
PROD
in the start-execution command:aws stepfunctions start-execution --state-machine-arn arn:aws-cn:states:us-east-1:123456789012:stateMachineAlias:
myStateMachine
:PROD --input "{}"If you provide the state machine ARN in the StartExecution request, it uses the most recent revision of the state machine instead of the version specified in your alias for starting the execution.
-
Update the state machine definition and publish a new version.
Update
and publish its new version. To do this, use the optionalmyStateMachine
publish
parameter of the update-state-machine command:aws stepfunctions update-state-machine --state-machine-arn arn:aws-cn:states:us-east-1:123456789012:stateMachine:
myStateMachine
--definition $UPDATED_STATE_MACHINE_DEFINITION --publishThe response returns the
stateMachineVersionArn
for the new version. For example,arn:aws-cn:states:us-east-1:
.123456789012
:stateMachine:myStateMachine
:2 -
Update the alias to point to both the versions and set the alias' routing configuration.
Use the update-state-machine-alias command to update the routing configuration of the alias
PROD
. Configure the alias so that 80 percent of the execution traffic goes to version 1 and the remaining 20 percent goes to version 2:aws stepfunctions update-state-machine-alias --state-machine-alias-arn arn:aws-cn:states:us-east-1:123456789012:stateMachineAlias:
myStateMachine
:PROD --routing-configuration "[{\"stateMachineVersionArn\":\"arn:aws-cn:states:us-east-1:123456789012:stateMachine:myStateMachine:1
\",\"weight\":80}, {\"stateMachineVersionArn\":\"arn:aws-cn:states:us-east-1:123456789012:stateMachine:myStateMachine:2
\",\"weight\":20}]" -
Replace version 1 with version 2.
After you verify that your new state machine version works correctly, you can deploy the new state machine version. To do this, update the alias again to assign 100 percent of execution traffic to the new version.
Use the update-state-machine-alias command to set the routing configuration of the alias
PROD
to 100 percent for version 2:aws stepfunctions update-state-machine-alias --state-machine-alias-arn arn:aws-cn:states:us-east-1:123456789012:stateMachineAlias:myStateMachine:PROD --routing-configuration "[{\"stateMachineVersionArn\":\"arn:aws-cn:states:us-east-1:123456789012:stateMachine:
myStateMachine:2
\",\"weight\":100}]"
Tip
To roll back the deployment of version 2, edit the alias' routing configuration to shift 100 percent of traffic to the newly deployed version.
aws stepfunctions update-state-machine-alias --state-machine-alias-arn arn:aws-cn:states:us-east-1:123456789012:stateMachineAlias:
myStateMachine
:PROD --routing-configuration "[{\"stateMachineVersionArn\":\"arn:aws-cn:states:us-east-1:123456789012:stateMachine:myStateMachine
:1\",\"weight\":100}]"
You can use versions and aliases to perform other types of deployments. For instance, you can perform a rolling deployment of a new version of your state machine. To do so, gradually increase the weighted percentage in the routing configuration of the alias that points to the new version.
You can also use versions and aliases to perform a blue/green
deployment. To do so, create an alias named green
that runs the current version
1 of your state machine. Then, create another alias named blue
that runs the new version, for example,
. To
test the new version, send execution traffic to the 2
blue
alias. When you're confident that
your new version works correctly, update the green
alias to point to
your new version.