Earthly在AWS EC2实例中无法继承IAM角色的解决方案

在使用Earthly构建工具时，开发者可能会遇到一个典型问题：当Earthly运行在配置了IAM角色的AWS EC2实例上时，构建过程中的AWS CLI操作无法自动继承实例的IAM角色凭证。本文将深入分析这一现象的技术原理，并提供经过验证的解决方案。

问题现象分析

当开发者在EC2实例上执行以下操作时：

1. 直接在主机OS运行AWS CLI命令（如aws sts get-caller-identity）可以成功获取IAM角色凭证
2. 通过普通Docker容器执行相同命令也能正常工作
3. 但在Earthly构建过程中执行AWS CLI命令时，却会出现"Unable to locate credentials"错误

这种现象表明凭证传递机制在Earthly构建环境中出现了中断。

根本原因

问题的核心在于AWS元数据服务(IMDS)的跳数限制。Earthly的构建环境实际上比普通Docker容器更加嵌套：

1. Earthly使用BuildKit作为构建引擎
2. BuildKit本身运行在容器环境中
3. Earthly的构建步骤又在BuildKit创建的隔离环境中执行

这种多层嵌套结构导致默认的IMDS跳数限制（通常为1）无法满足凭证传递的需求。AWS元数据服务的响应无法穿透所有这些网络层到达最终的构建环境。

解决方案

通过修改EC2实例的元数据服务配置，增加HTTP响应跳数限制即可解决此问题。具体操作如下：

aws ec2 modify-instance-metadata-options \
    --instance-id <实例ID> \
    --http-put-response-hop-limit 3 \
    --http-endpoint enabled

关键参数说明：

• --http-put-response-hop-limit 3：将跳数限制提高到3，确保凭证可以穿透Earthly的多层构建环境
• --http-endpoint enabled：确保元数据服务处于启用状态

最佳实践建议

1. 最小权限原则：即使解决了凭证传递问题，也应确保EC2实例角色仅具有构建所需的最小权限
2. 环境隔离：考虑为不同环境的构建任务使用不同的IAM角色
3. 监控审计：定期检查CloudTrail日志，确保没有异常的API调用
4. 跳数优化：根据实际嵌套深度设置最小的有效跳数值，3是一个经过验证的安全值

技术原理延伸

AWS IMDS服务采用类似TTL的机制控制凭证信息的传播范围。这种设计原本是为了防止凭证信息在网络中被过度传播，但在容器化和嵌套构建场景下需要适当调整。理解这一机制对于在复杂CI/CD环境中正确配置AWS凭证至关重要。

通过本文的解决方案，开发者可以确保Earthly构建过程能够安全、可靠地继承EC2实例的IAM角色，从而实现在构建过程中无缝调用AWS服务的能力。