AWS CDK AWS Step Functions

Common errors

• ModuleNotFoundError: No module named 'aws_cdk.aws_stepfunctions'

  cause The Python package for AWS Step Functions constructs is not installed or the virtual environment is not active.
  fix Activate your Python virtual environment and run `pip install aws-cdk.aws-stepfunctions aws-cdk.core`.

• jsii.errors.JavaScriptError: There are no `app.py`, `app.ts` or `main.py` files in ...

  cause The `cdk synth` or `cdk deploy` command was executed in a directory that does not contain the CDK application entry point (e.g., `app.py`).
  fix Navigate to the root directory of your CDK project where `app.py` resides before running `cdk synth` or `cdk deploy`.

• ClientError: An error occurred (AccessDeniedException) when calling the CreateStateMachine operation: User: arn:aws:iam::xxxxxxxxxxxx:user/your-user is not authorized to perform: states:CreateStateMachine on resource: arn:aws:states:...

  cause The AWS IAM user or role attempting to deploy the CDK stack lacks the necessary permissions to create or update Step Functions resources.
  fix Attach an IAM policy with `states:CreateStateMachine`, `states:UpdateStateMachine`, and `states:DeleteStateMachine` permissions (and potentially permissions for related resources like `iam:PassRole`) to the user or role deploying the stack.

Warnings

• breaking This library (`aws-cdk-aws-stepfunctions`) is part of AWS CDK v1. AWS CDK v2 uses a consolidated `aws-cdk-lib` package. Do not mix v1 and v2 packages in the same project, as it leads to dependency conflicts and runtime errors.
  Fix: Choose either CDK v1 or CDK v2 for your project. If using v2, install `aws-cdk-lib` and import Step Functions as `from aws_cdk import aws_stepfunctions as sfn` (without `lib` in the import path).
• gotcha AWS Step Functions require appropriate IAM permissions for the state machine to execute and for its tasks (e.g., Lambda, ECS) to interact with other AWS services. Insufficient permissions will result in execution failures that are often hard to debug.
  Fix: Ensure the `role` property of your `sfn.StateMachine` and any `sfn.tasks` or `sfn.LambdaInvoke` constructs have roles with the necessary permissions. Use `aws_iam.Role` and `aws_iam.PolicyStatement` to define and attach granular permissions.
• gotcha State machine definitions can quickly grow in complexity and size, potentially hitting AWS service limits (e.g., 262144 characters for definition JSON). While CDK helps abstract this, highly complex workflows can still exceed limits.
  Fix: For very large state machine definitions, consider breaking them into smaller, nested state machines or using data flow optimization techniques. Review Step Functions service quotas before designing complex workflows.
• gotcha CDK's `cdk synth` command generates CloudFormation, but `cdk deploy` requires AWS credentials configured in your environment (e.g., via AWS CLI, environment variables, or IAM roles for EC2/ECS).
  Fix: Configure your AWS credentials and default region before running `cdk deploy`. Use `aws configure` or set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` environment variables.

Install

• pip install aws-cdk.aws-stepfunctions Install library
• pip install aws-cdk.core Install core CDK (if not already)

Imports

• core
  wrong:

  import aws_cdk.core

  correct:

  from aws_cdk import core as cdk

  Commonly aliased as 'cdk' for brevity and consistency in CDK v1.
• aws_stepfunctions
  wrong:

  from aws_cdk.aws_stepfunctions import *

  correct:

  from aws_cdk import aws_stepfunctions as sfn

  Aliasing as 'sfn' is standard practice. Avoid wildcard imports for clarity.

Quickstart

This quickstart demonstrates how to define a basic AWS Step Functions State Machine using a simple 'Pass' state. It initializes a CDK application, creates a stack, defines the Pass state with a basic JSON definition, and then constructs a `StateMachine` resource. The `app.synth()` call generates the AWS CloudFormation template. To deploy, ensure AWS credentials are configured and run `cdk deploy MyStepFunctionStack` in your terminal.

import os
from aws_cdk import core as cdk
from aws_cdk import aws_stepfunctions as sfn

# Define your CDK Stack
class MyStepFunctionStack(cdk.Stack):
    def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Define a simple Pass state
        pass_state = sfn.Pass(self, "MyPassState",
            state_json={
                "Comment": "A simple pass state for demonstration",
                "InputPath": "$",
                "OutputPath": "$",
                "Result": {"status": "SUCCESS", "source": "CDK"},
                "End": True
            }
        )

        # Define a State Machine using the Pass state
        sfn.StateMachine(self, "MyCDKStateMachine",
            definition=pass_state,
            state_machine_name="MyCDKPassStateMachine", # Optional: explicit name
            timeout=cdk.Duration.minutes(5) # Optional: default timeout
        )

# Instantiate the CDK App and Stack
app = cdk.App()
MyStepFunctionStack(app, "MyStepFunctionStack")
app.synth()