feat(ecs-patterns): support a desiredCount of 0

[marco2216]

Issue # (if applicable)

Closes #16562.

Reason for this change

The load balanced ECS patterns reject desiredCount: 0 with You must specify a desiredCount greater than 0, even though DesiredCount: 0 is valid on the underlying AWS::ECS::Service resource and is already accepted by the ecs.FargateService / ecs.Ec2Service L2s.

Zero-task services are a real use case, and the linked issue collects several:

• suspend a service — e.g. a headless worker consuming a queue, or draining connections before a database upgrade that requires downtime;
• deploy a service and its surrounding infrastructure before the container image can start, so debugging the image doesn't mean waiting for repeated failed startups and a rollback of the whole stack;
• keep a pilot-light disaster-recovery stack defined but not running.

The only way to get there today is an escape hatch:

(loadBalancedEcsService.service.node.defaultChild as ecs.CfnService).desiredCount = 0;

Description of changes

ApplicationLoadBalancedServiceBase, NetworkLoadBalancedServiceBase, ApplicationMultipleTargetGroupsServiceBase and NetworkMultipleTargetGroupsServiceBase:

• desiredCount now only rejects negative values (desiredCount must be greater than or equal to 0, got -1); 0 is passed through to the service.
• The check now skips unresolved tokens. Number tokens encode as a large negative double (-1.888e+289), so desiredCount: someCfnParameter.valueAsNumber used to fail the < 1 check and throw in three of the four base classes — the ALB base was the only one that already had the guard. A tokenized desiredCount now reaches the template unchanged.
• this.desiredCount = props.desiredCount ?? 1 (was || 1), so the deprecated desiredCount property reports 0 instead of 1 when 0 was requested. internalDesiredCount, which is what the services actually use in v2, already carried the raw value.

Docs: desiredCount no longer says "The minimum value is 1", and the README gains a "Run a service without any task" example.

Design decisions, flagged per AGENTS.md:

• No feature flag. Every input this loosens (0, and tokens in three of the bases) threw at synth time before this change, so no existing app can synthesize differently.
• Negative values still throw, rather than being clamped — CloudFormation always rejects them, so failing fast at synth is the useful behavior.
• No warning when a load balanced service is created with zero tasks. The original objection to 0 (QueueProcessingFargateService unable to set desiredCount to zero #4719) was that load balanced services usually scale on CPU/memory, which does nothing at zero tasks. But desiredCount: 0 is explicit, opt-in, and — per the issue — deliberate; warning on a value the user just asked for would be noise they'd have to acknowledge.
• ScheduledTaskBase.desiredTaskCount keeps its >= 1 validation. It maps to EcsParameters.TaskCount on AWS::Events::Rule, whose documented minimum is 1, so it is a different case and out of scope here.

Describe any new or updated permissions being added

None.

Description of how you validated changes

Unit tests, in aws-ecs-patterns:

• desiredCount: 0 synthesizes DesiredCount: 0 for ApplicationLoadBalancedEc2Service, NetworkLoadBalancedEc2Service, ApplicationMultipleTargetGroupsEc2Service, NetworkMultipleTargetGroupsEc2Service and ApplicationLoadBalancedFargateService (the four tests that asserted the old error are now assertions that 0 is accepted);
• negative values (-1, -1024) throw the new message;
• a tokenized desiredCount reaches the template as { "Ref": "DesiredCount" } instead of throwing;
• the deprecated desiredCount property, and internalDesiredCount, both report 0.

npx jest aws-ecs-patterns → 9 suites / 245 tests pass. ESLint clean on every changed file.

Integration test: test/aws-ecs-patterns/test/fargate/integ.alb-fargate-service-desired-count-zero.ts, which deploys a suspended ALB Fargate service and asserts via ECS.describeServices that desiredCount and runningCount are both 0.

Important

I do not have an AWS account to run this repository's integration tests against, so the snapshot was generated with yarn integ --dry-run --update-on-failed and the test has not been deployed. It needs a maintainer to deploy it before merge — happy for the pr/needs-integration-tests-deployment label to be applied, or I can rerun anything you'd like differently.

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