05 Sep

AWS Step Functions for networkers – the CLI approach

Step Function Workflow Graph

In the previous post, I told you that it is not possible to update State Machine configuration once you create it. I prefer an approach like in API Gateway where you have stages of the same project, but Amazon for some reason did not follow this way. So if you want to deploy a new version of your Step Functions project you need to delete old and create new State Machine. Using the GUI interface is not efficient in a long term, you can do this much easier using AWS CLI.

IAM Roles and ARNs

Before you start, make sure you have AWC CLI correctly configured. You can find many instructions on AWS site and other blogs how to install AWS CLI tools on different operating system and how to set up proper permissions for users.

One important piece of configuration you need to know is IAM Role used to perform any operation on State Machines. That is the role created automatically by AWS Web Portal when you created your first function in particular region. To check the ARN identifier, you have to go to IAM Management Console, select Roles from the menu on the left side and then the particular Role.

IAM Step Function Role

IAM Step Function Role

The predefined role is assigned automatically to the new policy. This policy is required to execute Lambda functions by State Machine.

Note: As you can see I removed part of the Role ARN on the screenshot. This section contains a numeric value that is my used ID in AWS. Remember that if you are ever going to post ARN publically or within people, you do not trust always hide or remove it.


AWS CLI operations

Create new State Machine

To create new State Machine, you need its definition, name, and role with proper permissions. The description of the State Machine is put in a JSON structure. You will find its definition in Amazon States Language standard. Previously we put it in the text area section of the State Machine creator on AWS website. It is much easier to store it in a file. You can refer to this file and pass it as an argument in CLI command.

$ aws stepfunctions create-state-machine --name HasFirmwareChanged --definition "$(cat StateMachineDefinition.json)" --role-arn arn:aws:iam::0000000000:role/service-role/StatesExecutionRole-eu-west-1

In this command, the –definition argument requires JSON structure as input. I store the JSON in a separate file, so it is easy to edit. However, a file cannot be an argument. I do here simple Unix trick – I use the cat command to get the content of a selected file, and I assign it to a temporary variable. I can then provide this variable as an argument value.

Upon successful creation, you will get ARN of your State Machine and the creation date time stamp

 "stateMachineArn": "arn:aws:states:eu-west-1:0000000000:stateMachine:HasFirmwareChanged",
 "creationDate": 1503575604.783

List State Machines

Another easy task. You do not need to provide any arguments. In return, you will get JSON structure with all State Machines, their names, ARN identifiers, and date of creation.

$ aws stepfunctions list-state-machines
 "stateMachines": [
 "stateMachineArn": "arn:aws:states:eu-west-1:0000000000:stateMachine:HasFirmwareChanged",
 "name": "HasFirmwareChanged",
 "creationDate": 1503575604.783


Delete State Machine

Before you create new State Machine using the same name you need to remove the old one. All you need t provide is the ARN of machine you want to remove

$ aws stepfunctions delete-state-machine --state-machine-arn arn:aws:states:eu-west-1:0000000000:stateMachine:HasFirmwareChanged

The command will not return any output of executed correctly.


Execute State Machine

You can start your State Machine using its ARN for identification

$ aws stepfunctions start-execution --state-machine-arn arn:aws:states:eu-west-1:051581810722:stateMachine:HasFirmwareChanged

The output will contain the ARN and timestamp, so you will not be able to debug like on Web console. If you need to provide JSON structure with input data you have to add the –input parameter.

Leave a Reply

%d bloggers like this: