ecs: unable to create managed instances capacity provider

[ollypom]

Describe the bug

I'm unable to create a managed instance capacity provider. It appears the current L2 constructs creates an invalidate (and not required) ClusterCapacityProviderAssociations resource.

Regression Issue

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

Last Known Working CDK Library Version

No response

Expected Behavior

The managed instances capacity provider gets added to the cluster.

Current Behavior

The creation of the stack fails because the Capacity Provider Associate resource fails

Reproduction Steps

Template:

    // Create ECS Cluster
    const cluster = new ecs.Cluster(this, 'MyEcsCluster', {
      vpc: vpc,
      clusterName: `${this.stackName}-cluster`,
    });

    // Create a Default Managed Instances Capacity Provider
    const miDefaultCapacityProvider = new ecs.ManagedInstancesCapacityProvider(this, 'MIDefaultCapacityProvider', {
      infrastructureRole: ecsInfrastructureRole,
      ec2InstanceProfile: ecsInstanceProfile,
      subnets: vpc.privateSubnets,
      securityGroups: [miDefaultSecurityGroup]
    });

    cluster.addManagedInstancesCapacityProvider(miDefaultCapacityProvider);

When I synth this, I get the following template:

  MyEcsCluster989E66E0:
    Type: AWS::ECS::Cluster
    Properties:
      ClusterName: CdkStack-cluster
    Metadata:
      aws:cdk:path: CdkStack/MyEcsCluster/Resource
  MyEcsCluster9940BE40:
    Type: AWS::ECS::ClusterCapacityProviderAssociations
    Properties:
      CapacityProviders: []
      Cluster:
        Ref: MyEcsCluster989E66E0
      DefaultCapacityProviderStrategy: []
    Metadata:
      aws:cdk:path: CdkStack/MyEcsCluster/MyEcsCluster
  MIDefaultCapacityProvider07546591:
    Type: AWS::ECS::CapacityProvider
    Properties:
      ClusterName:
        Ref: MyEcsCluster989E66E0
      ManagedInstancesProvider:
        InfrastructureRoleArn:
          Fn::GetAtt:
            - ECSInfrastructureRoleE492121F
            - Arn
        InstanceLaunchTemplate:
          Ec2InstanceProfileArn:
            Fn::GetAtt:
              - ECSInstanceProfileBA4A4DA9
              - Arn
          NetworkConfiguration:
            SecurityGroups:
              - Fn::GetAtt:
                  - MIDefaultSecurityGroup4EADDF9A
                  - GroupId
            Subnets:
              - Ref: MyVpcPrivateSubnetSubnet1SubnetE8BD536C
              - Ref: MyVpcPrivateSubnetSubnet2SubnetE3BFCF91
    Metadata:
      aws:cdk:path: CdkStack/MIDefaultCapacityProvider/MIDefaultCapacityProvider

Then why I attempt to deploy it, the ClusterCapacityProviderAssociations will fail.

Resource handler returned message: "Name is null" (RequestToken: f0729928-71d8-e634-55ef-aedadadfc136, HandlerErrorCode: InternalFailure)

Possible Solution

This additional Provider Association resource is not required with Managed Instances as the cluster name is in the capacity provider. I did wonder why we needed a cluster.addManagedInstancesCapacityProvider() resource at all, we could have just added a cluster name attribute to ecs.ManagedInstancesCapacityProvider() which would map to what the cloudformation looks like.

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.219.0

AWS CDK CLI version

2.1029.4

Node.js Version

v22.14

OS

Ubuntu 22.04

Language

TypeScript

Language Version

No response

Other information

No response

[pahud]

Hi @ollypom,

Thank you for reporting this issue. Based on our analysis, it appears that the MaybeCreateCapacityProviderAssociations aspect is incorrectly creating a ClusterCapacityProviderAssociations resource with an empty CapacityProviders array when using Managed Instances capacity providers.

The root cause seems to be that when you call addManagedInstancesCapacityProvider, the provider is added to
_clusterScopedCapacityProviderNames rather than _capacityProviderNames.

aws-cdk/packages/aws-cdk-lib/aws-ecs/lib/cluster.ts

Line 619 in 8a6cf46

this._clusterScopedCapacityProviderNames.push(provider.capacityProviderName);

The aspect checks if clusterScopedCapacityProviderNames has entries to decide whether to create the association resource, but then only populates the CapacityProviders property with capacityProviderNames, resulting in an empty array.

This is particularly problematic because Managed Instances capacity providers already specify the cluster name directly in the ManagedInstancesCapacityProvider.bind method, so they might not need to be included in a separate ClusterCapacityProviderAssociations resource at all.

The fix would likely involve modifying the aspect logic to either:

1. Not create the association resource when only cluster-scoped providers exist (without a default strategy), or
2. Include cluster-scoped providers in the association when they're referenced in a default capacity provider strategy

Reproduction Code

import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as iam from 'aws-cdk-lib/aws-iam';

const vpc = new ec2.Vpc(this, 'Vpc', { maxAzs: 2 });

const cluster = new ecs.Cluster(this, 'Cluster', {
  vpc,
  clusterName: 'repro-cluster',
});

const infrastructureRole = new iam.Role(this, 'InfraRole', {
  assumedBy: new iam.ServicePrincipal('ecs.amazonaws.com'),
  managedPolicies: [
    iam.ManagedPolicy.fromAwsManagedPolicyName('AmazonECSInfrastructureRolePolicyForManagedInstances'),
  ],
});

const instanceRole = new iam.Role(this, 'InstanceRole', {
  assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com'),
  managedPolicies: [
    iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AmazonEC2ContainerServiceforEC2Role'),
  ],
});

const instanceProfile = new iam.InstanceProfile(this, 'InstanceProfile', {
  role: instanceRole,
});

const securityGroup = new ec2.SecurityGroup(this, 'SG', {
  vpc,
  allowAllOutbound: true,
});

const miCapacityProvider = new ecs.ManagedInstancesCapacityProvider(this, 'MICapacityProvider', {
  infrastructureRole,
  ec2InstanceProfile: instanceProfile,
  subnets: vpc.privateSubnets,
  securityGroups: [securityGroup],
});

cluster.addManagedInstancesCapacityProvider(miCapacityProvider);  // ❌ Triggers the bug

This minimal setup triggers the bug where an invalid ClusterCapacityProviderAssociations resource is created.

Making this a p1 bug.

[aemada-aws]

I reached out to the service team and will provide an update once they respond how to proceed with this.

[kg-aws]

Hi @ollypom - Thank you for reporting the issue. While the issue persists it's a bug in the AWS::ECS::ClusterCapacityProviderAssocations CFN resource that should accept an empty/null value for CapacityProviders array field. I will update this issue after the fix is deployed in the CFN resource. No change is required on the CDK side.

[ollypom]

Thanks! Question, why not add clusterName to the CDK capacity provider object, aligning to the API and CFN object. Would this not allow us to remove the association step?

So the capacity provider would become:

    // Create a Default Managed Instances Capacity Provider
    const miDefaultCapacityProvider = new ecs.ManagedInstancesCapacityProvider(this, 'MIDefaultCapacityProvider', {
      clusterName: ecsCluster,
      infrastructureRole: ecsInfrastructureRole,
      ec2InstanceProfile: ecsInstanceProfile,
      subnets: vpc.privateSubnets,
      securityGroups: [miDefaultSecurityGroup]
    });