aws-ecs: breaking change in 2.209.0 python lib

[adam-kiss-sg]

Describe the bug

Hi!

In the python lib, the signature of the aws_ecs/BaseService.load_balancer_target was changed.

in 2.208.0:

    @jsii.member(jsii_name="loadBalancerTarget")
    def load_balancer_target(
        self,
        *,
        container_name: builtins.str,
        container_port: typing.Optional[jsii.Number] = None,
        protocol: typing.Optional[Protocol] = None,
    ) -> IEcsLoadBalancerTarget:

in 2.209.0:

    @jsii.member(jsii_name="loadBalancerTarget")
    def load_balancer_target(
        self,
        options: typing.Union[LoadBalancerTargetOptions, typing.Dict[builtins.str, typing.Any]],
        alternate_options: typing.Optional[IAlternateTarget] = None,
    ) -> IEcsLoadBalancerTarget:

This caused our CI/CD pipelines to break.

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

2.208.0

Expected Behavior

No breaking change.

Current Behavior

TypeError: BaseService.load_balancer_target() got an unexpected keyword argument 'container_name'

Reproduction Steps

Possible Solution

No response

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.209.1

AWS CDK CLI version

2.1022.0

Node.js Version

Node.js v22.12.0

OS

linux

Language

Python

Language Version

Python 3.12.3

Other information

No response

[pahud]

Hi @adam-kiss-sg

Thanks for your report. I've confirmed this is reproducible and affecting Python users.

--

Issue Summary

In CDK v2.209.0, the BaseService.load_balancer_target() method signature changed, breaking existing Python code that used keyword arguments.

How to Reproduce

Step 1: Test with CDK 2.208.0 (Working Version)

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the last working version
pip install aws-cdk-lib==2.208.0 constructs>=10.0.0

# Run the reproduction script
python reproduce_issue_35167.py

#!/usr/bin/env python3
"""
Minimal CDK app to reproduce issue #35167
Breaking change in aws-cdk-lib 2.209.0 for Python users

This script demonstrates the breaking change in BaseService.load_balancer_target method
"""

import aws_cdk as cdk
from aws_cdk import (
    Stack,
    aws_ec2 as ec2,
    aws_ecs as ecs,
    aws_elasticloadbalancingv2 as elbv2,
)
from constructs import Construct


class ReproduceIssue35167Stack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Create VPC
        vpc = ec2.Vpc(self, "Vpc", max_azs=2)

        # Create ECS Cluster
        cluster = ecs.Cluster(self, "Cluster", vpc=vpc)

        # Create Task Definition
        task_definition = ecs.FargateTaskDefinition(
            self, "TaskDef",
            memory_limit_mib=512,
            cpu=256
        )

        # Add container
        container = task_definition.add_container(
            "web",
            image=ecs.ContainerImage.from_registry("nginx:latest"),
            port_mappings=[
                ecs.PortMapping(container_port=80, protocol=ecs.Protocol.TCP)
            ]
        )

        # Create Fargate Service
        service = ecs.FargateService(
            self, "Service",
            cluster=cluster,
            task_definition=task_definition
        )

        # Create Application Load Balancer
        alb = elbv2.ApplicationLoadBalancer(
            self, "ALB",
            vpc=vpc,
            internet_facing=True
        )

        # Create Target Group
        target_group = elbv2.ApplicationTargetGroup(
            self, "TargetGroup",
            vpc=vpc,
            port=80,
            target_type=elbv2.TargetType.IP
        )

        # Add listener
        listener = alb.add_listener(
            "Listener",
            port=80,
            default_target_groups=[target_group]
        )

        print("=== Testing load_balancer_target method ===")
        
        try:
            print("\n1. Testing OLD syntax (2.208.0 style - should FAIL in 2.209.0+):")
            print("   service.load_balancer_target(container_name='web', container_port=80)")
            
            # This is the OLD way that worked in 2.208.0 but breaks in 2.209.0
            target_old = service.load_balancer_target(
                container_name="web",
                container_port=80,
                protocol=ecs.Protocol.TCP
            )
            print("   ✅ OLD syntax worked (you're using CDK 2.208.0 or earlier)")
            
        except TypeError as e:
            print(f"   ❌ OLD syntax failed: {e}")
            print("   This confirms you're using CDK 2.209.0+ with the breaking change")

        try:
            print("\n2. Testing NEW syntax (2.209.0+ style - should WORK):")
            print("   service.load_balancer_target({'container_name': 'web', 'container_port': 80})")
            
            # This is the NEW way required in 2.209.0+
            target_new = service.load_balancer_target({
                "container_name": "web",
                "container_port": 80,
                "protocol": ecs.Protocol.TCP
            })
            print("   ✅ NEW syntax worked")
            
            # Attach to target group using the new syntax
            target_new.attach_to_application_target_group(target_group)
            print("   ✅ Successfully attached to target group")
            
        except Exception as e:
            print(f"   ❌ NEW syntax failed: {e}")

        print("\n=== CDK Version Info ===")
        print(f"CDK Version: {cdk.__version__}")


def main():
    app = cdk.App()
    
    print("Reproducing AWS CDK Issue #35167")
    print("Breaking change in BaseService.load_balancer_target method")
    print("=" * 60)
    
    ReproduceIssue35167Stack(app, "ReproduceIssue35167Stack")
    
    # We don't need to synth for this reproduction - just instantiating shows the issue
    print("\n=== Reproduction Complete ===")
    print("If you see the OLD syntax failing, you've reproduced issue #35167")
    print("The workaround is to use the NEW syntax with a dictionary parameter")


if __name__ == "__main__":
    main()

Expected Output for 2.208.0:

=== Testing load_balancer_target method ===

1. Testing OLD syntax (2.208.0 style - should FAIL in 2.209.0+):
   service.load_balancer_target(container_name='web', container_port=80)
   ✅ OLD syntax worked (you're using CDK 2.208.0 or earlier)

2. Testing NEW syntax (2.209.0+ style - should WORK):
   service.load_balancer_target({'container_name': 'web', 'container_port': 80})
   ✅ NEW syntax worked
   ✅ Successfully attached to target group

Step 2: Test with CDK 2.209.0+ (Broken Version)

# Upgrade to the version with breaking change
pip install --upgrade aws-cdk-lib==2.209.0

# Run the same script
python reproduce_issue_35167.py

Expected Output for 2.209.0+:

=== Testing load_balancer_target method ===

1. Testing OLD syntax (2.208.0 style - should FAIL in 2.209.0+):
   service.load_balancer_target(container_name='web', container_port=80)
   ❌ OLD syntax failed: BaseService.load_balancer_target() got an unexpected keyword argument 'container_name'
   This confirms you're using CDK 2.209.0+ with the breaking change

2. Testing NEW syntax (2.209.0+ style - should WORK):
   service.load_balancer_target({'container_name': 'web', 'container_port': 80})
   ✅ NEW syntax worked
   ✅ Successfully attached to target group

The Breaking Change

What Changed

The method signature changed from:

# 2.208.0 - JSII flattened the interface to keyword arguments
def load_balancer_target(
    self,
    *,
    container_name: str,
    container_port: Optional[int] = None,
    protocol: Optional[Protocol] = None,
) -> IEcsLoadBalancerTarget:

To:

# 2.209.0+ - JSII requires object parameter due to additional alternateOptions
def load_balancer_target(
    self,
    options: Union[LoadBalancerTargetOptions, Dict[str, Any]],
    alternate_options: Optional[IAlternateTarget] = None,
) -> IEcsLoadBalancerTarget:

Root Cause

This was caused by PR #35061 which added blue/green deployment support. The addition of a second optional parameter (alternateOptions) prevented JSII from flattening the first parameter into keyword arguments.

Workaround

Update your code from:

# OLD (broken in 2.209.0+)
service.load_balancer_target(
    container_name="web",
    container_port=80,
    protocol=ecs.Protocol.TCP
)

To:

# NEW (required in 2.209.0+)
service.load_balancer_target({
    "container_name": "web",
    "container_port": 80,
    "protocol": ecs.Protocol.TCP
})

Why Only Python Users Are Affected

• TypeScript users: The change is backward compatible because the second parameter is optional
• Python users: JSII changed how it generates the method signature, breaking the keyword argument pattern
• Other JSII languages (Java, C#, Go): Also affected by similar binding changes

Related Links

• Original Issue #35167
• Root Cause PR #35061
• JSII Documentation

---

Next Actions

I'll bring this up to the team for immediate review.

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.