(stepfunctions): example for using statemachine versions and aliases with StateMachine construct

[wong-a]

Describe the issue

Step Functions supports gradual deployments through versions and aliases. It would be nice to have some examples of how to achieve this in CDK in the stepfunctions module docs.

Example:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as sfn from 'aws-cdk-lib/aws-stepfunctions';

/**
 * Example CDK stack demonstrating how to achieve gradual deployments
 * for Step Functions using versions and aliases.
 */
export class VersioningCdkExampleStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // StateMachine
    const stateMachine = new sfn.StateMachine(this, 'myStateMachine', {
      definition: new sfn.Pass(this, 'DefineRepositories', { result: sfn.Result.fromString("version 1") })
    });

    // Version that always points to the latest revision by using `stateMachineRevisionId`
    const version = new sfn.CfnStateMachineVersion(this, 'Version', {
      stateMachineArn: stateMachine.stateMachineArn,
      stateMachineRevisionId: stateMachine.stateMachineRevisionId,
    });

    // When the state machine changes, the CFN does an update replacement of 'Version'
    // To prevent distruption to callers of the previous version, we need to keep it.
    version.applyRemovalPolicy(cdk.RemovalPolicy.RETAIN);

    // Alias that gradually shifts 10% of traffic to the new version every minute
    const alias = new sfn.CfnStateMachineAlias(this, 'myAlias', {
      deploymentPreference: {
        type: "LINEAR",
        interval: 1,
        percentage: 10,
        stateMachineVersionArn: version.ref
      }
    })
  }
}

Links

https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_stepfunctions-readme.html

[peterwoodworth]

We don't have any higher level constructs for State Machine Versions or Aliases, so the CloudFormation documentation is considered sufficient in tandem with the existing L2 construct StateMachine.

If we convert this instead to a feature request for supporting higher level constructs for StateMachine Version and Alias, we can do that.

[wong-a]

the CloudFormation documentation is considered sufficient in tandem with the existing L2 construct StateMachine.

I disagree. Users benefit from complete code examples and the existing docs don't show how to use all three resources together. If you think that doesn't belong in CDK docs for some reason, we will put that in the Step Functions developer guide: https://docs.aws.amazon.com/step-functions/latest/dg/version-rolling-deployment.html

I don't see a need for higher level constructs for StateMachineVersion or StateMachineAlias at the moment. The only abstraction I'd see happening is extending StateMachine to automatically create versions and aliases similar to AWS::Serverless::StateMachine in SAM.

[peterwoodworth]

If you want a full example involving multiple resources, this would best be added as an example in the examples repo

[peterwoodworth]

I can't transfer this issue to that repo since these repositories live in different orgs, so I'll close this and allow you to duplicate this there if desired.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.

[wong-a]

My 2¢: Versions and aliases as a fundamental part of deploying state machines safely in a continuous deployment setting. This is why I think there should be a basic example of this in the CDK construct docs, where users first go to learn how to use it.

Happy to move that over to aws-cdk-examples and Step Functions docs if that's a no-no here