State machine versions in Step Functions workflows
A version is a numbered, immutable snapshot of a state machine. You publish versions from the most recent revision made to that state machine. Each version has a unique Amazon Resource Name (ARN) which is a combination of state machine ARN and the version number separated by a colon (:). The following example shows the format of a state machine version ARN.
arn:partition
:states:region
:account-id
:stateMachine:myStateMachine
:1
To start using state machine versions, you must publish the first version. After you publish a version, you can invoke the StartExecution API action with the version ARN. You can't edit a version, but you can update a state machine and publish a new version. You can also publish multiple versions of your state machine.
When you publish a new version of your state machine, Step Functions assigns it a version number. Version numbers start at 1 and increase monotonically for each new version. Version numbers aren't reused for a given state machine. If you delete version 10 of your state machine and then publish a new version, Step Functions publishes it as version 11.
The following properties are the same for all versions of a state machine:
-
All versions of a state machine share the same type (Standard or Express).
-
You can't change the name or creation date of a state machine between versions.
-
Tags apply globally to state machines. You can manage tags for state machines using the TagResource and UntagResource API actions.
State machines also contain properties that are a part of each version and revision, but these properties can differ between two given versions or revisions. These properties include State machine definition, IAM role, tracing configuration, and logging configuration.
Publishing a state machine version (Console)
You can publish up to 1000 versions of a state machine. To request an increase to this soft limit, use the Support Center page in the Amazon Web Services Management Console. You can manually delete unused versions from the console or by invoking the DeleteStateMachineVersion API action.
To publish a state machine version
-
Open the Step Functions console
, and then choose an existing state machine. -
On the State machine detail page, choose Edit.
-
Edit the state machine definition as required, and then choose Save.
-
Choose Publish version.
-
(Optional) In the Description field of the dialog box that appears, enter a brief description about the state machine version.
-
Choose Publish.
Note
When you publish a new version of your state machine, Step Functions assigns it a version number. Version numbers start at 1 and increase monotonically for each new version. Version numbers aren't reused for a given state machine. If you delete version 10 of your state machine and then publish a new version, Step Functions publishes it as version 11.
Managing versions with Step Functions API operations
Step Functions provides the following API operations to publish and manage state machine versions:
-
PublishStateMachineVersion – Publishes a version from the current revision of a state machine.
-
UpdateStateMachine – Publishes a new state machine version if you update a state machine and set the
publish
parameter totrue
in the same request. -
CreateStateMachine – Publishes the first revision of the state machine if you set the
publish
parameter totrue
. -
ListStateMachineVersions – Lists versions for the specified state machine ARN.
-
DescribeStateMachine – Returns the state machine version details for a version ARN specified in
stateMachineArn
. -
DeleteStateMachineVersion – Deletes a state machine version.
To publish a new version from the current revision of a state machine called
using the Amazon Command Line Interface, use
the myStateMachine
publish-state-machine-version
command:
aws stepfunctions publish-state-machine-version --state-machine-arn arn:aws-cn:states:us-east-1:
123456789012
:stateMachine:myStateMachine
The response returns the stateMachineVersionArn
. For example,
the previous command returns a response
ofarn:aws-cn:states:us-east-1:
.123456789012
:stateMachine:myStateMachine
:1
Note
When you publish a new version of your state machine, Step Functions assigns it a version number. Version numbers start at 1 and increase monotonically for each new version. Version numbers aren't reused for a given state machine. If you delete version 10 of your state machine and then publish a new version, Step Functions publishes it as version 11.
Running a state machine version from the console
To start using state machine versions, you must first publish a version from the current
state machine revision. To publish a version, use the Step Functions console or invoke the PublishStateMachineVersion API action. You can also invoke
the UpdateStateMachineAlias API action with an optional parameter
named publish
to update a state machine and publish its version.
You can start executions of a version by using the console or by invoking the StartExecution API action and providing the version ARN. You can also use an alias to start executions of a version. Based on its routing configuration, an alias routes traffic to a specific version.
If you start a state machine execution without using a version, Step Functions uses the most recent revision of the state machine for the execution. For information about how Step Functions associates an execution with a version, see Associating executions with a version or alias.
To start an execution using a state machine version
-
Open the Step Functions console
, and then choose an existing state machine that you've published one or more versions for. To learn how to publish a version, see Publishing a state machine version (Console). -
On the State machine detail page, choose the Versions tab.
-
In the Versions section, do the following:
-
Select the version that you want to start the execution with.
-
Choose Start execution.
-
-
(Optional) In the Start execution dialog box, enter a name for the execution.
-
(Optional) , enter the execution input, and then choose Start execution.