从 CHANGELOG 读懂 AWS SDK for Go v2 的 EC2 IMDS 客户端：关键行为、默认值与版本演进

本文以 Moby 仓库内 vendor 的 AWS SDK for Go v2 feature/ec2/imds 模块的 CHANGELOG.md（共 629 行、覆盖 v1.1.0 ~ v1.18.39 的全部版本）为骨架，结合该模块在本仓库中的真实源码（api_client.go、token_provider.go、request_middleware.go 等），系统梳理 IMDS 客户端的默认超时/退避/回退语义、IMDSv2 Token 机制、IPv4/IPv6 端点选择、Go 最低版本演进等开发者必须了解的关键事实，并还原它在本仓库 CloudWatch Logs 日志驱动中的实际调用方式。读完本文，你将能看懂这份变更日志背后真正改变客户端行为的若干 Feature/Bug Fix，并能把版本号变化映射到具体源码行为。

这份 CHANGELOG 记录的模块是什么

被记录的模块是 AWS SDK for Go v2 中的 EC2 实例元数据服务（Instance Metadata Service，IMDS）客户端，模块路径 github.com/aws/aws-sdk-go-v2/feature/ec2/imds。本仓库通过 go.mod 将其固定为 v1.18.39，与模块内 go_module_metadata.go 中的 goModuleVersion = "1.18.39" 一致，即该 CHANGELOG 最新条目所对应的版本。

该模块提供了一组面向 IMDS 服务的操作客户端（见 vendor 目录 中的 api_op_*.go 文件）：

• GetMetadata / GetDynamicData / GetUserData：读取实例元数据路径；
• GetRegion：获取实例所在区域，常被 SDK 用于区域探测；
• GetIAMInfo / GetInstanceIdentityDocument：读取角色/身份信息；
• GetToken：IMDSv2 的 PUT Token 获取操作（内部使用）。

在本仓库中，它被 daemon/logger/awslogs/cloudwatchlogs.go 直接 import，用于 CloudWatch Logs 日志驱动在 EC2 上自动解析区域。

如何阅读这份 CHANGELOG：条目的五种类别

对全文 629 行做统计归纳，可以把它压缩成五种可操作信息：

类别	含义	代表条目
Feature	引入新能力或新配置项，是本文件最重要的信息	v1.3.0、v1.6.0、v1.13.0、v1.16.0、v1.17.0、v1.18.0
Bug Fix	修复行为缺陷	v1.6.0 的超时竞态、v1.12.19 的请求/响应日志
Dependency Update	升级 smithy-go 或"最新 SDK 模块版本"，占绝大多数条目	几乎每个版本都有
BREAKING CHANGE	破坏性变更，注意与 Feature 叠加标注	v1.14.0（Go 1.19）
No change notes	无实质内容	v1.14.2

需要特别提醒：不要把"Dependency Update：Updated to the latest SDK module versions"当成无效噪音——它恰恰说明 AWS 对 SDK 采用频繁批量发布的节奏（例如 2025-08 一个月发布 5 个版本），同时个别版本带 .2 后缀（如 v1.18.34 (2026-07-31.2)），属于同日的二次补发。对于依赖方来说，真正需要在升级时评审的，是下表这些改变了客户端运行时行为的条目。

版本演进中的关键行为变更（Feature/Bug Fix 全量清单）

把全文所有非"依赖升级"条目按时间从旧到新提取如下，这正是该 CHANGELOG 的技术精华：

版本	日期	类型	变更内容	对应源码
v1.1.0	2021-05-14	Feature	为模块加入运行时版本常量，便于上报	go_module_metadata.go
v1.3.0	2021-07-15	Feature	支持 EC2 IPv6 版 IMDS 端点	api_client.go
v1.4.0	2021-08-04	Feature	为 deferred close 调用增加错误处理	api_op_GetToken.go
v1.6.0	2021-10-11	Feature + Bug Fix	尊重调用方 Context 的 Deadline/Timeout，不再覆盖默认超时；修复响应处理与操作超时的竞态（上游 #1253）	request_middleware.go
v1.12.19	2022-10-24	Bug Fix	修复开启对应 log mode 后请求/响应无法记录的问题	request_middleware.go
v1.13.0	2023-03-14	Feature	增加"禁用 IMDSv1 回退"开关	token_provider.go
v1.14.0	2023-10-31	Feature（BREAKING）	最低 Go 版本升至 1.19	—
v1.15.0	2024-02-13	Feature	最低 Go 版本升至 1.20	—
v1.16.0	2024-03-21	Feature	新增 DisableDefaultTimeout 配置开关，默认操作超时 5 秒	request_middleware.go
v1.17.0	2025-07-28	Feature	支持 HTTP interceptors	api_client.go
v1.18.0	2025-07-29	Feature	新增 DisableDefaultMaxBackoff，默认最大退避 1 秒	api_client.go
v1.18.19	2026-03-03	Bug Fix	go fix 现代化非代码生成文件；最低 Go 升至 1.24	—

此外 v1.16.29（2025-02-18）有一条被标注为 Bug Fix 的"Bump go version to 1.22"，v1.18.20（2026-03-13）将旧 ioutil 包全部替换为 io/os——这两条对上游 SDK 有意义，对业务调用方基本透明。

五个默认值与对应的源码佐证

CHANGELOG 只写"新增开关"，不写全貌；但开关的默认值和触发条件全部沉淀在本仓库的 vendored 源码中，下面逐一还原。

1. 默认端点与端点模式（v1.3.0 引入 IPv6）

api_client.go 定义了三种端点来源的优先级：

AWS_EC2_METADATA_SERVICE_ENDPOINT   // 环境变量显式覆盖
defaultIPv4Endpoint = "http://169.254.169.254"    // 默认
defaultIPv6Endpoint = "http://[fd00:ec2::254]"    // v1.3.0 加入

EndpointModeStateUnset 走 IPv4（见 request_middleware.go）。同时客户端内置的 HTTP 层做了"快速失败"调优：resolveHTTPClient 把拨号超时设为 250ms、响应头超时设为 500ms，注释明确解释：应用可能根本不在 EC2 环境（此时应快速失败），也可能跑在容器里而 IMDS 只允许单跳 TTL（连接会被丢弃，同样应快速失败）。这正是 CloudWatch 日志驱动必须保证"本地开发环境启动不卡死"的关键设计。

2. 默认操作超时 5 秒与 Context 语义（v1.6.0、v1.16.0）

defaultOperationTimeout = 5 * time.Second 定义在 request_middleware.go。它的生效逻辑继承了 v1.6.0 的行为修正：只有当调用方 Context 没有自带 deadline 时，中间件才注入 5 秒超时（HandleInitialize）；如果调用方传入了带超时的 Context，则完全尊重调用方（这正是 v1.6.0 的 Feature 原文）。v1.16.0 新增的 DisableDefaultTimeout 可彻底关闭这一默认超时。

同一版本还修复了一个响应体读取与超时清理的竞态：deserializer 先把响应体整体读入内存再交给上层（见 deserializeResponse），避免超时取消时响应体仍在被并发读取。

3. IMDSv2 Token 与 IMDSv1 回退（v1.13.0 提供关闭开关）

客户端在 Finalize 阶段通过 tokenProvider 自动完成 IMDSv2 流程：

• 默认 Token TTL 为 5 分钟（defaultTokenTTL），通过 PUT /latest/api/token + X-Aws-Ec2-Metadata-Token-Ttl-Seconds 头获取（见 api_op_GetToken.go）；
• 缓存 Token 直到过期，期间后续请求携带 x-aws-ec2-metadata-token 头；
• 401 响应会让 Token 立即失效并重新获取（HandleDeserialize）。

关于 IMDSv1 回退，v1.13.0 的"disable fallback flag"对应 Options.EnableFallback。默认情况下回退开启，其精确语义在 updateToken 中写得很清楚：

• Token 请求返回 403/404/405：说明实例可能只开了 IMDSv1，于是记录告警并禁用 Token 提供器，本请求及后续走不安全的 IMDSv1 明文数据流；
• Token 请求返回 400：视为终态错误，直接向上返回；
• 请求发送失败或超时：禁用 Token 提供器（可能因为 IMDSv2 不可达）；
• 开启 EnableFallback=false（或经配置解析为禁用回退）后，任何取 Token 失败都会原样上抛错误，而不是静默降级到 IMDSv1。

4. 默认最大重试退避 1 秒（v1.18.0）

New 在未设置 DisableDefaultMaxBackoff 时，会用 retry.AddWithMaxBackoffDelay(retryer, 1*time.Second) 把标准重试器的单次最大退避钳制在 1 秒内。v1.18.0 之前该上限是硬编码的，v1.18.0 之后可用该开关放开。对 Moby 这类常驻守护进程而言，这保证了 EC2 元数据故障时重试节奏可控，不会造成长时间退避阻塞。

5. 客户端开关与环境变量矩阵

汇总 Options 与两个环境变量（源码见 api_client.go）：

配置项 / 环境变量	作用	默认
AWS_EC2_METADATA_DISABLED=true	整体禁用 IMDS 客户端，所有操作直接报错	未设置 = 启用
AWS_EC2_METADATA_SERVICE_ENDPOINT	覆盖端点（可指向 http://[::1] 等本地模拟服务）	169.254.169.254 或 fd00:ec2::254
Endpoint / EndpointMode	编程方式指定端点/端点模式（IPv4/IPv6）	IPv4
EnableFallback	是否允许 IMDSv1 回退（v1.13.0）	允许
DisableDefaultTimeout	关闭 5 秒默认操作超时（v1.16.0）	false
DisableDefaultMaxBackoff	关闭 1 秒最大退避上限（v1.18.0）	false
ClientLogMode / Logger	请求/响应/重试日志（v1.12.19 修复后生效）	不记录

Go 最低版本演进与 smithy-go 升级节奏

CHANGELOG 提供了模块对 Go 工具链的要求轨迹，这对使用方的 CI 有直接影响：

变更	版本	时间
最低 Go 1.19（BREAKING）	v1.14.0	2023-10-31
最低 Go 1.20	v1.15.0	2024-02-13
最低 Go 1.21	v1.16.12	2024-08-15
最低 Go 1.22	v1.16.29	2025-02-18
最低 Go 1.23	v1.18.10	2025-10-16
最低 Go 1.24	v1.18.19	2026-03-03

smithy-go 的升级条目中值得注意的有：v1.18.22 引入对 endpointBdd trait 的支持；v1.18.23/25/28 分别处理 serde 与 union 反序列化缺陷；v1.18.13 与 v1.18.15 报告（changelog 口径）通过减少中间件体系分配来降低每次 SDK 调用的开销，其中 v1.18.15 声称"每次 SDK 调用分配约减少 10%"——这属于上游自述观测数据，引用时应注明来源口径，不应作为本项目自行测得的结论。

在本仓库的真实使用场景：CloudWatch Logs 区域探测

该模块并非"为 vendoring 而 vendoring"。Moby 的 CloudWatch Logs 日志驱动在 cloudwatchlogs.go 显式 import feature/ec2/imds，并定义了一个 regFinder 接口（同文件 L121）：

GetRegion(context.Context, *imds.GetRegionInput, ...func(*imds.Options)) (*imds.GetRegionOutput, error)

在解析 AWS 配置时（L447），驱动通过 imds.NewFromConfig(cfg) 创建客户端；当用户没有显式配置 region 时，调用 regFinder.GetRegion(...)（L479）从 EC2 IMDS 拉取实例所在区域，用于后续 CloudWatch Logs 服务的初始化。

理解该链路的现实意义在于：CHANGELOG 里关于超时、退避、回退的每次调整，都会直接改变 Moby 在 EC2 上启动 dockerd 时区域解析的故障行为——例如 AWS_EC2_METADATA_DISABLED 一旦被置为 true，GetRegion 会按 invokeOperation 的逻辑立即返回"access disabled"错误；而 250ms 拨号超时则保证了非 EC2 环境下日志驱动快速失败而不是挂死。

升级与排障速查建议

1. 升级本模块版本时，重点关注 Feature 与 Bug Fix 条目（上表已全量列出），Dependency Update 类通常只需回归测试即可。
2. 默认 5 秒超时对慢 IMDS 不可用：若确需更长等待，不要用宽松 Context 覆盖（v1.6.0 起 Context 优先），应显式设置 DisableDefaultTimeout 并自行用 Context 控制。
3. 安全合规场景禁用 IMDSv1：将 EnableFallback 置为 false（v1.13.0），此时 403/404/405 引发的取 Token 失败会作为错误暴露而非静默降级。
4. 在非 EC2 环境调试：设置 AWS_EC2_METADATA_SERVICE_ENDPOINT=http://[::1] 指向本地模拟服务，即可验证区域解析等完整链路。

小结

AWS SDK for Go v2 的 feature/ec2/imds CHANGELOG 表面上是流水账式的发布记录，但其中 20 余条 Feature/Bug Fix/Breaking 条目精确刻画了该客户端 2021–2026 年间从"裸 IMDS 请求封装"演进为"具备 IMDSv2 Token 缓存、受控 IMDSv1 回退、可配置超时/退避、IPv6 端点与 Context 语义完善"的成熟组件的全过程。把这份 CHANGELOG 与本仓库中的 vendored 源码对照阅读，即可获得对默认值、环境变量与故障行为的完整、可验证的理解——这也是升级任何 vendored 依赖时最可靠的研究方法。