feat(stepfunctions-tasks): allow EcsRunTask on fargate and ec2 to set capacity provider strategy #35465

go-to-k · 2025-09-11T08:27:05Z

Issue # (if applicable)

Closes #20013 #30171 #7967

Reason for this change

The capacity provider strategy can't be set on EcsRunTask with EcsFargateLaunchTargetOptions and EcsEc2LaunchTargetOptions.

capacityProviderStrategy

The capacity provider strategy to use for the task.

If a capacityProviderStrategy is specified, the launchType parameter must be omitted. If no capacityProviderStrategy or launchType is specified, the defaultCapacityProviderStrategy for the cluster is used.

When you use cluster auto scaling, you must specify capacityProviderStrategy and not launchType.

A capacity provider strategy can contain a maximum of 20 capacity providers.

https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html

Description of changes

This PR adds a new property capacityProviderOptions (CapacityProviderOptions class with static factory methods as an union-like class) in the target options.

The CapacityProviderOptions has following sub types:

NoCapacityProviderOptions
CustomCapacityProviderOptions
DefaultCapacityProviderOptions

The NoCapacityProviderOptions creates the original settings with LaunchType (EC2 or FARGATE). It is a default value for the capacityProviderOptions.

The CustomCapacityProviderOptions allows users to set the capacity provider strategy without LaunchType.

The DefaultCapacityProviderOptions allows users to use the cluster's default capacity provider strategy. The default strategy can be set by specifying no options (LaunchType and CapacityProviderStrategy) in CFn.

Describe any new or updated permissions being added

Description of how you validated changes

Both unit tests and integ tests.

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

aws-cdk-automation

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

go-to-k · 2025-09-11T14:35:38Z

...-testing/framework-integ/test/aws-stepfunctions-tasks/test/ecs/eventhandler-image/Dockerfile

@@ -1,3 +1,3 @@
-FROM public.ecr.aws/docker/library/python:3.12
+FROM --platform=linux/amd64 public.ecr.aws/docker/library/python:3.12


Because amd64 is used for cpu architecture in integ tests.

If this option is not specified, running the tests on Mac will result in an error during state machine execution.

badmintoncryer

Thank you for your contribution! I've added some minor comments.

badmintoncryer · 2025-12-12T14:37:23Z

...work-integ/test/aws-stepfunctions-tasks/test/ecs/integ.fargate-run-task-capacity-provider.ts

+stack.node.setContext(EC2_RESTRICT_DEFAULT_SECURITY_GROUP, false);
+stack.node.setContext(STEPFUNCTIONS_TASKS_FIX_RUN_ECS_TASK_POLICY, false);


Are these feature flags are needed?

badmintoncryer · 2025-12-12T14:41:46Z

...ramework-integ/test/aws-stepfunctions-tasks/test/ecs/integ.ec2-run-task-capacity-provider.ts

+  postCliContext: {
+    '@aws-cdk/aws-ecs:enableImdsBlockingDeprecatedFeature': false,
+    '@aws-cdk/aws-ecs:disableEcsImdsBlocking': false,
+  },


Are there feature flags needed?

badmintoncryer · 2025-12-12T14:43:43Z

...ramework-integ/test/aws-stepfunctions-tasks/test/ecs/integ.ec2-run-task-capacity-provider.ts

+stack.node.setContext(EC2_RESTRICT_DEFAULT_SECURITY_GROUP, false);
+stack.node.setContext(STEPFUNCTIONS_TASKS_FIX_RUN_ECS_TASK_POLICY, false);


I think it is better to unify the method for setting feature flags either through postCliContext or setContext. (If these flags are needed!)

badmintoncryer · 2025-12-12T14:46:42Z

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

+The `capacityProviderOptions` property allows you to configure the capacity provider
+strategy for both EC2 and Fargate launch targets.
+
+- When `CapacityProviderOptionsBase.none()` is used, the task uses the launch type (EC2 or FARGATE) without a capacity provider strategy.


It's true that CapacityProviderOptionsBase is an abstract base class, but I don't think users will be aware of the concrete classes that inherit from it when specifying their settings.
I thought it would be more user-friendly to name it simply CapacityProviderOptions. What do you think?

badmintoncryer · 2025-12-12T14:59:03Z

packages/aws-cdk-lib/aws-stepfunctions-tasks/lib/ecs/run-task.ts

+/**
+ * No capacity provider strategy options
+ */
+export class NoCapacityProviderOptions extends CapacityProviderOptionsBase {


Should this concrete class be exported?
I think user uses not a NoCapacityProviderOptions but a abstract class.

badmintoncryer · 2025-12-12T15:00:03Z

...work-integ/test/aws-stepfunctions-tasks/test/ecs/integ.fargate-run-task-capacity-provider.ts

+    ],
+    launchTarget: new tasks.EcsFargateLaunchTarget({
+      platformVersion: ecs.FargatePlatformVersion.VERSION1_4,
+      capacityProviderOptions: tasks.NoCapacityProviderOptions.none(),


Is it better to use a abstract class?

Relates to #35465 (comment)

…sks-ecs-capacity

github-actions · 2025-12-17T11:48:41Z

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
Please try merge from main to avoid findings unrelated to the PR.

	Tests	Passed ☑️	Skipped	Failed ❌️
Security Guardian Results	100 ran	98 passed		2 failed

Test	Result
Security Guardian Results
packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions-tasks/test/ecs/integ.ec2-run-task-capacity-provider.js.snapshot/aws-sfn-tasks-ecs-ec2-run-task-capacity-provider.template.json
iam-no-overly-permissive-passrole.guard	❌ failure
packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions-tasks/test/ecs/integ.fargate-run-task-capacity-provider.js.snapshot/aws-sfn-tasks-ecs-fargate-run-task-capacity-provider.template.json
iam-no-overly-permissive-passrole.guard	❌ failure

View Security Guardian Results

github-actions · 2025-12-17T11:48:42Z

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
Please try merge from main to avoid findings unrelated to the PR.

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results with resolved templates	100 ran	100 passed

Test	Result
No test annotations available

View Security Guardian Results with resolved templates

go-to-k · 2025-12-17T11:55:29Z

@badmintoncryer Thanks for your review! I'll check and apply your points later!

go-to-k · 2025-12-17T13:10:04Z

@badmintoncryer

I have applied the all comments!

badmintoncryer

Thanks!!

ozelalisen

Have some comments, and thanks for raising this PR, this will be really valuable!

ozelalisen · 2025-12-24T11:57:59Z

packages/aws-cdk-lib/aws-stepfunctions-tasks/lib/ecs/run-task.ts

+}
+
+interface CapacityProviderParams {
+  launchType?: ecs.LaunchType;


The launchType in CapacityProviderParams feels unnecessary here. The launch type is already determined by the task context (Fargate vs EC2) — it's not something users should configure via capacityProviderOptions. The current _bind(launchType) pattern passes it in just to return it back out.

Could we simplify by just checking whether capacityProviderStrategy is provided instead of threading launchType through this abstraction?

ozelalisen · 2025-12-24T11:58:23Z

packages/aws-cdk-lib/aws-stepfunctions-tasks/lib/ecs/run-task.ts

+  /**
+   * No capacity provider strategy is used.
+   */
+  public static none(): CapacityProviderOptions {


I'm not sure CapacityProviderOptions.none() adds value here. The absence of the capacityProviderOptions property already means "no capacity provider strategy" — having an explicit .none() method creates two ways to express the same thing (undefined vs .none()), which can be confusing for users.

What's the use case for explicitly calling .none() vs just not setting the property?

ozelalisen · 2025-12-24T12:00:26Z

packages/aws-cdk-lib/aws-stepfunctions-tasks/lib/ecs/run-task.ts

+   * @default - 'FARGATE' LaunchType running tasks on AWS Fargate On-Demand
+   * infrastructure is used without the capacity provider strategy.
+   */
+  readonly capacityProviderOptions?: CapacityProviderOptions;


I think a simpler API without the abstract class hierarchy would be better, something like:

capacityProviderStrategy?: ecs.CapacityProviderStrategy[]; useClusterDefaultCapacityProvider?: boolean;

Then the logic becomes:

capacityProviderStrategy provided → use custom strategy (omit LaunchType)

useClusterDefaultCapacityProvider: true → omit both (uses cluster default)

Neither → use LaunchType (current behavior)

This would remove the need for CapacityProviderOptions, NoCapacityProviderOptions, CustomCapacityProviderOptions, and DefaultCapacityProviderOptions classes entirely, making the API more intuitive and easier to maintain.

ozelalisen · 2025-12-24T12:03:03Z

packages/aws-cdk-lib/aws-stepfunctions-tasks/lib/ecs/run-task.ts

+   * @default - 'EC2' LaunchType running tasks on Amazon EC2 instances registered to
+   * your cluster is used without the capacity provider strategy.
+   */
+  readonly capacityProviderOptions?: CapacityProviderOptions;


Same comment as above

go-to-k added 3 commits September 10, 2025 16:07

feat(stepfunctions-tasks): wip

3a144ff

wip

d4ba563

wip

9c4e544

aws-cdk-automation requested a review from a team September 11, 2025 08:27

github-actions bot added effort/small Small work item – less than a day of effort feature-request A feature should be added or improved. p2 distinguished-contributor [Pilot] contributed 50+ PRs to the CDK labels Sep 11, 2025

aws-cdk-automation previously requested changes Sep 11, 2025

View reviewed changes

go-to-k added 10 commits September 11, 2025 18:09

docs

439f98a

docs

42115fa

unit tests

a4abaa8

integ tets

74f9170

README

2574785

integ

15a2d03

platform=linux/amd64 in docker

5620912

fargate integ

4a34f60

integ

e874755

Merge branch 'main' into sfn-tasks-ecs-capacity

2097747

go-to-k marked this pull request as ready for review September 11, 2025 12:35

integ

96a20a0

go-to-k commented Sep 11, 2025

View reviewed changes

go-to-k added 4 commits September 11, 2025 23:39

readme

5b538c4

integ

f1de60d

docs

2db9236

readme

ba80be9

go-to-k changed the title ~~feat(stepfunctions-tasks): allow EcsRunTask on Fargate and EC2 to set capacity provider strategy~~ feat(stepfunctions-tasks): allow EcsRunTask on fargate and ec2 to set capacity provider strategy Sep 11, 2025

aws-cdk-automation added the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label Sep 11, 2025

github-actions bot mentioned this pull request Oct 1, 2025

Monthly PR metrics report #35642

Open

badmintoncryer suggested changes Dec 12, 2025

View reviewed changes

aws-cdk-automation removed the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label Dec 12, 2025

go-to-k added 2 commits December 13, 2025 17:12

Merge branch 'main' of https://github.com/go-to-k/aws-cdk into sfn-ta…

dd83cee

…sks-ecs-capacity

Merge branch 'main' of https://github.com/go-to-k/aws-cdk into sfn-ta…

5c3c47e

…sks-ecs-capacity

apply review

aa48631

Merge branch 'main' into sfn-tasks-ecs-capacity

2d87a51

badmintoncryer approved these changes Dec 17, 2025

View reviewed changes

aws-cdk-automation added the pr/needs-maintainer-review This PR needs a review from a Core Team Member label Dec 17, 2025

Merge branch 'main' into sfn-tasks-ecs-capacity

893b56f

ozelalisen requested changes Dec 24, 2025

View reviewed changes

ozelalisen self-assigned this Dec 24, 2025

ozelalisen added p1 and removed p2 labels Dec 24, 2025

aws-cdk-automation removed the pr/needs-maintainer-review This PR needs a review from a Core Team Member label Dec 24, 2025

		@@ -1,3 +1,3 @@
		FROM public.ecr.aws/docker/library/python:3.12
		FROM --platform=linux/amd64 public.ecr.aws/docker/library/python:3.12

		stack.node.setContext(EC2_RESTRICT_DEFAULT_SECURITY_GROUP, false);
		stack.node.setContext(STEPFUNCTIONS_TASKS_FIX_RUN_ECS_TASK_POLICY, false);

feat(stepfunctions-tasks): allow EcsRunTask on fargate and ec2 to set capacity provider strategy #35465

Are you sure you want to change the base?

feat(stepfunctions-tasks): allow EcsRunTask on fargate and ec2 to set capacity provider strategy #35465

Conversation

go-to-k commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue # (if applicable)

Reason for this change

Description of changes

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

aws-cdk-automation left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

badmintoncryer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

go-to-k commented Dec 17, 2025

Uh oh!

go-to-k commented Dec 17, 2025

Uh oh!

badmintoncryer left a comment

Choose a reason for hiding this comment

Uh oh!

ozelalisen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

go-to-k commented Sep 11, 2025 •

edited

Loading

aws-cdk-automation left a comment •

edited

Loading

github-actions bot commented Dec 17, 2025 •

edited

Loading

github-actions bot commented Dec 17, 2025 •

edited

Loading