如何在CloudFormation中为EC2实例添加可被ECS识别的自定义属性？

我之前刚好踩过这个坑！要让自定义属性出现在aws ecs describe-container-instances的输出里，单纯用EC2 Metadata确实行不通——得通过ECS Agent的配置来注入这些属性才行。下面是用CloudFormation实现的两种靠谱方案：

这是最直接的方式，ECS Agent启动时会读取特定环境变量来设置实例属性，我们可以在CloudFormation的EC2实例定义里通过UserData来配置：

Resources:
  ECSInstance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: ami-xxxxxxx # 替换成你的ECS优化AMI ID
      InstanceType: t2.micro
      IamInstanceProfile: !Ref ECSInstanceProfile # 需要给实例配ECS相关权限的IAM角色
      UserData:
        Fn::Base64: |
          #!/bin/bash
          # 写入自定义属性到ECS Agent配置文件
          echo "ECS_INSTANCE_ATTRIBUTES={\"team\":\"devops\",\"env\":\"staging\",\"service\":\"web\"}" >> /etc/ecs/ecs.config
          # 重启ECS Agent让配置生效
          systemctl restart ecs

解释一下：

• ECS_INSTANCE_ATTRIBUTES是ECS Agent官方识别的环境变量，值为JSON格式的键值对，这些键值对就是你要展示的自定义属性。
• 如果你用的是AWS官方的ECS优化AMI，/etc/ecs/ecs.config是默认的配置文件路径；如果是自定义AMI，得确认ECS Agent的配置文件位置。

如果你的ECS集群用Capacity Provider来管理实例，那可以把配置写到启动模板里，让Auto Scaling Group创建的所有实例都自动带上自定义属性：

Resources:
  ECSLaunchTemplate:
    Type: AWS::EC2::LaunchTemplate
    Properties:
      LaunchTemplateData:
        ImageId: ami-xxxxxxx
        InstanceType: t2.micro
        IamInstanceProfile:
          Name: !Ref ECSInstanceProfile
        UserData:
          Fn::Base64: |
            #!/bin/bash
            echo "ECS_INSTANCE_ATTRIBUTES={\"region-cn\":\"beijing\",\"app-version\":\"v1.2.3\"}" >> /etc/ecs/ecs.config
            systemctl restart ecs

  ECSAutoScalingGroup:
    Type: AWS::AutoScaling::AutoScalingGroup
    Properties:
      LaunchTemplate:
        LaunchTemplateId: !Ref ECSLaunchTemplate
        Version: !GetAtt ECSLaunchTemplate.LatestVersionNumber
      MinSize: 1
      MaxSize: 3
      VPCZoneIdentifier: !Ref Subnets # 替换成你的子网ID列表

  ECSCapacityProvider:
    Type: AWS::ECS::CapacityProvider
    Properties:
      AutoScalingGroupProvider:
        AutoScalingGroupArn: !Ref ECSAutoScalingGroup
        ManagedScaling:
          Status: ENABLED

等实例启动并成功注册到ECS集群后，运行以下命令查看：

# 先获取集群内第一个容器实例的ARN
INSTANCE_ARN=$(aws ecs list-container-instances --cluster your-cluster-name --query 'containerInstanceArns[0]' --output text)
# 查询该实例的详细信息
aws ecs describe-container-instances --cluster your-cluster-name --container-instances $INSTANCE_ARN

在输出的attributes字段里，就能看到你添加的自定义键值对了：

"attributes": [
  {
    "name": "team",
    "value": "devops"
  },
  {
    "name": "env",
    "value": "staging"
  }
]

• 确保EC2实例的IAM角色（Instance Profile）拥有ecs:RegisterContainerInstance等ECS相关权限，否则实例无法正常注册到集群。
• 如果是已存在的ECS实例，直接修改/etc/ecs/ecs.config并重启ECS Agent也能生效，但CloudFormation的方式更适合自动化部署场景。
• 别再纠结EC2 Metadata了，ECS Agent不会把Metadata里的自定义字段识别为实例属性的。

内容的提问来源于stack exchange，提问作者Colin