Skip to content

Commit 0499adf

Browse files
mazyu36mazyu36
authoredJun 13, 2024··
fix(stepfunctions): add docs and warning DistributedMap Class ignores executionType in the ProcessorConfig (#30301)
### Issue # (if applicable) Closes #30194 ### Reason for this change In #27913, the ItemProcessor was introduced for use with the Map Class. With the executionType in the ProcessorConfig, it was possible to specify the executionType for the Map. On the other hand, in #28821, the DistributedMap Class was introduced. The mapExecutionType of the DistributedMap class always overwrites the executionType of the ProcessorConfig. Therefore, when using the DistributedMap class, the implementation ignores the executionType of the ProcessorConfig. However, this behavior cannot be inferred from the documentation. ### Description of changes * Added to the docs that when using the DistributedMap Class, the executionType in the ProcessorConfig is ignored. * Also added a warning. ### Description of how you validated changes Add unit tests and integ tests ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
·
v2.185.0v2.147.0
1 parent b14f3c9 commit 0499adf

13 files changed

+714
-5
lines changed
 

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.distributed-map-execution-type.js.snapshot/DistributedMapDefaultTestDeployAssertFD6CBCC4.assets.json

+19
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.distributed-map-execution-type.js.snapshot/DistributedMapDefaultTestDeployAssertFD6CBCC4.template.json

+36
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.distributed-map-execution-type.js.snapshot/aws-stepfunctions-map-integ-execution-type.assets.json

+19
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.distributed-map-execution-type.js.snapshot/aws-stepfunctions-map-integ-execution-type.template.json

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
{
2+
"Resources": {
3+
"StateMachineRoleB840431D": {
4+
"Type": "AWS::IAM::Role",
5+
"Properties": {
6+
"AssumeRolePolicyDocument": {
7+
"Statement": [
8+
{
9+
"Action": "sts:AssumeRole",
10+
"Effect": "Allow",
11+
"Principal": {
12+
"Service": "states.amazonaws.com"
13+
}
14+
}
15+
],
16+
"Version": "2012-10-17"
17+
}
18+
}
19+
},
20+
"StateMachine2E01A3A5": {
21+
"Type": "AWS::StepFunctions::StateMachine",
22+
"Properties": {
23+
"DefinitionString": "{\"StartAt\":\"DistributedMap\",\"States\":{\"DistributedMap\":{\"Type\":\"Map\",\"End\":true,\"ItemProcessor\":{\"ProcessorConfig\":{\"Mode\":\"DISTRIBUTED\",\"ExecutionType\":\"EXPRESS\"},\"StartAt\":\"Pass\",\"States\":{\"Pass\":{\"Type\":\"Pass\",\"End\":true}}}}}}",
24+
"RoleArn": {
25+
"Fn::GetAtt": [
26+
"StateMachineRoleB840431D",
27+
"Arn"
28+
]
29+
}
30+
},
31+
"DependsOn": [
32+
"StateMachineRoleB840431D"
33+
],
34+
"UpdateReplacePolicy": "Delete",
35+
"DeletionPolicy": "Delete"
36+
},
37+
"StateMachineDistributedMapPolicy57C9D8C2": {
38+
"Type": "AWS::IAM::Policy",
39+
"Properties": {
40+
"PolicyDocument": {
41+
"Statement": [
42+
{
43+
"Action": "states:StartExecution",
44+
"Effect": "Allow",
45+
"Resource": {
46+
"Ref": "StateMachine2E01A3A5"
47+
}
48+
},
49+
{
50+
"Action": [
51+
"states:DescribeExecution",
52+
"states:StopExecution"
53+
],
54+
"Effect": "Allow",
55+
"Resource": {
56+
"Fn::Join": [
57+
"",
58+
[
59+
{
60+
"Ref": "StateMachine2E01A3A5"
61+
},
62+
":*"
63+
]
64+
]
65+
}
66+
}
67+
],
68+
"Version": "2012-10-17"
69+
},
70+
"PolicyName": "StateMachineDistributedMapPolicy57C9D8C2",
71+
"Roles": [
72+
{
73+
"Ref": "StateMachineRoleB840431D"
74+
}
75+
]
76+
}
77+
}
78+
},
79+
"Parameters": {
80+
"BootstrapVersion": {
81+
"Type": "AWS::SSM::Parameter::Value<String>",
82+
"Default": "/cdk-bootstrap/hnb659fds/version",
83+
"Description": "Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store. [cdk:skip]"
84+
}
85+
},
86+
"Rules": {
87+
"CheckBootstrapVersion": {
88+
"Assertions": [
89+
{
90+
"Assert": {
91+
"Fn::Not": [
92+
{
93+
"Fn::Contains": [
94+
[
95+
"1",
96+
"2",
97+
"3",
98+
"4",
99+
"5"
100+
],
101+
{
102+
"Ref": "BootstrapVersion"
103+
}
104+
]
105+
}
106+
]
107+
},
108+
"AssertDescription": "CDK bootstrap stack version 6 required. Please run 'cdk bootstrap' with a recent version of the CDK CLI."
109+
}
110+
]
111+
}
112+
}
113+
}

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.distributed-map-execution-type.js.snapshot/cdk.out

+1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.distributed-map-execution-type.js.snapshot/integ.json

+12
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.distributed-map-execution-type.js.snapshot/manifest.json

+125
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.distributed-map-execution-type.ts

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
import * as cdk from 'aws-cdk-lib/core';
2+
import { IntegTest } from '@aws-cdk/integ-tests-alpha';
3+
import * as sfn from 'aws-cdk-lib/aws-stepfunctions';
4+
5+
class DistributedMapStack extends cdk.Stack {
6+
readonly stateMachine: sfn.StateMachine;
7+
8+
constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
9+
super(scope, id, props);
10+
11+
const distributedMap = new sfn.DistributedMap(this, 'DistributedMap', {
12+
mapExecutionType: sfn.StateMachineType.EXPRESS,
13+
});
14+
distributedMap.itemProcessor(new sfn.Pass(this, 'Pass'), {
15+
mode: sfn.ProcessorMode.DISTRIBUTED,
16+
executionType: sfn.ProcessorType.STANDARD,
17+
});
18+
19+
this.stateMachine = new sfn.StateMachine(this, 'StateMachine', {
20+
definition: distributedMap,
21+
});
22+
}
23+
}
24+
25+
const app = new cdk.App();
26+
const stack = new DistributedMapStack(app, 'aws-stepfunctions-map-integ-execution-type');
27+
28+
new IntegTest(app, 'DistributedMap', {
29+
testCases: [stack],
30+
});
31+
32+
app.synth();

‎packages/aws-cdk-lib/aws-stepfunctions/README.md

+15
Original file line numberDiff line numberDiff line change
@@ -605,6 +605,21 @@ const distributedMap = new sfn.DistributedMap(this, 'Distributed Map State', {
605605
distributedMap.itemProcessor(new sfn.Pass(this, 'Pass State'));
606606
```
607607

608+
If you want to specify the execution type for the ItemProcessor in the DistributedMap, you must set the `mapExecutionType` property in the `DistributedMap` class. When using the `DistributedMap` class, the `ProcessorConfig.executionType` property is ignored.
609+
610+
In the following example, the execution type for the ItemProcessor in the DistributedMap is set to `EXPRESS` based on the value specified for `mapExecutionType`.
611+
612+
```ts
613+
const distributedMap = new sfn.DistributedMap(this, 'DistributedMap', {
614+
mapExecutionType: sfn.StateMachineType.EXPRESS, // mapExecutionType property is applied.
615+
});
616+
617+
distributedMap.itemProcessor(new sfn.Pass(this, 'Pass'), {
618+
mode: sfn.ProcessorMode.DISTRIBUTED,
619+
executionType: sfn.ProcessorType.STANDARD, // ProcessorConfig.executionType is ignored
620+
});
621+
```
622+
608623
### Custom State
609624

610625
It's possible that the high-level constructs for the states or `stepfunctions-tasks` do not have

‎packages/aws-cdk-lib/aws-stepfunctions/lib/states/distributed-map.ts

+7-3
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { ItemBatcher } from './distributed-map/item-batcher';
33
import { IItemReader } from './distributed-map/item-reader';
44
import { ResultWriter } from './distributed-map/result-writer';
55
import { MapBase, MapBaseProps } from './map-base';
6+
import { Annotations } from '../../../core';
67
import { FieldUtils } from '../fields';
78
import { StateGraph } from '../state-graph';
89
import { StateMachineType } from '../state-machine';
@@ -19,6 +20,8 @@ export interface DistributedMapProps extends MapBaseProps {
1920
*
2021
* The execution type of the distributed map state
2122
*
23+
* This property overwrites ProcessorConfig.executionType
24+
*
2225
* @default StateMachineType.STANDARD
2326
*/
2427
readonly mapExecutionType?: StateMachineType;
@@ -110,7 +113,7 @@ export class DistributedMap extends MapBase implements INextable {
110113
* Return whether the given object is a DistributedMap.
111114
*/
112115
public static isDistributedMap(x: any): x is DistributedMap {
113-
return x !== null && typeof(x) === 'object' && DISTRIBUTED_MAP_SYMBOL in x;
116+
return x !== null && typeof (x) === 'object' && DISTRIBUTED_MAP_SYMBOL in x;
114117
}
115118

116119
private readonly mapExecutionType?: StateMachineType;
@@ -234,9 +237,10 @@ export class DistributedMap extends MapBase implements INextable {
234237
*/
235238
public toStateJson(): object {
236239
let rendered: any = super.toStateJson();
237-
if (this.mapExecutionType) {
238-
rendered.ItemProcessor.ProcessorConfig.ExecutionType = this.mapExecutionType;
240+
if (rendered.ItemProcessor.ProcessorConfig.ExecutionType) {
241+
Annotations.of(this).addWarningV2('@aws-cdk/aws-stepfunctions:propertyIgnored', 'Property \'ProcessorConfig.executionType\' is ignored, use the \'mapExecutionType\' in the \'DistributedMap\' class instead.');
239242
}
243+
rendered.ItemProcessor.ProcessorConfig.ExecutionType = this.mapExecutionType;
240244

241245
return {
242246
...rendered,

‎packages/aws-cdk-lib/aws-stepfunctions/lib/types.ts

+5-2
Original file line numberDiff line numberDiff line change
@@ -220,14 +220,17 @@ export interface ProcessorConfig {
220220
/**
221221
* Specifies the execution mode for the Map workflow.
222222
*
223-
* @default - ProcessorMode.INLINE
223+
* @default - ProcessorMode.INLINE if using the `Map` class, ProcessorMode.DISTRIBUTED if using the `DistributedMap` class
224224
*/
225225
readonly mode?: ProcessorMode;
226226

227227
/**
228228
* Specifies the execution type for the Map workflow.
229229
*
230-
* You must provide this field if you specified `DISTRIBUTED` for the `mode` sub-field.
230+
* If you use the `Map` class, you must provide this field if you specified `DISTRIBUTED` for the `mode` sub-field.
231+
*
232+
* If you use the `DistributedMap` class, this property is ignored.
233+
* Use the `mapExecutionType` in the `DistributedMap` class instead.
231234
*
232235
* @default - no execution type
233236
*/

‎packages/aws-cdk-lib/aws-stepfunctions/test/distributed-map.test.ts

+81
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { Annotations, Match } from '../../assertions';
12
import * as s3 from '../../aws-s3';
23
import * as cdk from '../../core';
34
import * as stepfunctions from '../lib';
@@ -778,6 +779,86 @@ describe('Distributed Map State', () => {
778779

779780
app.synth();
780781
});
782+
783+
test('State Machine With Distributed Map State should use default mapExecutionType and ignore itemProcessor executionType', () => {
784+
// GIVEN
785+
const stack = new cdk.Stack();
786+
787+
//WHEN
788+
const map = new stepfunctions.DistributedMap(stack, 'Map State', {
789+
});
790+
map.itemProcessor(new stepfunctions.Pass(stack, 'Pass State'), {
791+
mode: stepfunctions.ProcessorMode.DISTRIBUTED,
792+
executionType: stepfunctions.ProcessorType.EXPRESS,
793+
});
794+
795+
//THEN
796+
expect(render(map)).toStrictEqual({
797+
StartAt: 'Map State',
798+
States: {
799+
'Map State': {
800+
Type: 'Map',
801+
End: true,
802+
ItemProcessor: {
803+
ProcessorConfig: {
804+
Mode: stepfunctions.ProcessorMode.DISTRIBUTED,
805+
ExecutionType: stepfunctions.StateMachineType.STANDARD,
806+
},
807+
StartAt: 'Pass State',
808+
States: {
809+
'Pass State': {
810+
Type: 'Pass',
811+
End: true,
812+
},
813+
},
814+
},
815+
},
816+
},
817+
});
818+
819+
Annotations.fromStack(stack).hasWarning('/Default/Map State', Match.stringLikeRegexp('Property \'ProcessorConfig.executionType\' is ignored, use the \'mapExecutionType\' in the \'DistributedMap\' class instead.'));
820+
});
821+
822+
test('State Machine With Distributed Map State should use configured mapExecutionType and ignore itemProcessor executionType', () => {
823+
// GIVEN
824+
const stack = new cdk.Stack();
825+
826+
//WHEN
827+
const map = new stepfunctions.DistributedMap(stack, 'Map State', {
828+
mapExecutionType: stepfunctions.StateMachineType.EXPRESS,
829+
});
830+
map.itemProcessor(new stepfunctions.Pass(stack, 'Pass State'), {
831+
mode: stepfunctions.ProcessorMode.DISTRIBUTED,
832+
executionType: stepfunctions.ProcessorType.STANDARD,
833+
});
834+
835+
//THEN
836+
expect(render(map)).toStrictEqual({
837+
StartAt: 'Map State',
838+
States: {
839+
'Map State': {
840+
Type: 'Map',
841+
End: true,
842+
ItemProcessor: {
843+
ProcessorConfig: {
844+
Mode: stepfunctions.ProcessorMode.DISTRIBUTED,
845+
ExecutionType: stepfunctions.StateMachineType.EXPRESS,
846+
},
847+
StartAt: 'Pass State',
848+
States: {
849+
'Pass State': {
850+
Type: 'Pass',
851+
End: true,
852+
},
853+
},
854+
},
855+
},
856+
},
857+
});
858+
859+
Annotations.fromStack(stack).hasWarning('/Default/Map State', Match.stringLikeRegexp('Property \'ProcessorConfig.executionType\' is ignored, use the \'mapExecutionType\' in the \'DistributedMap\' class instead.'));
860+
861+
});
781862
});
782863

783864
function render(sm: stepfunctions.IChainable) {

0 commit comments

Comments
 (0)
Please sign in to comment.