amazon-ec2-image-builder

Amazon EC2 Image Builder

概述

提供有关使用 EC2 Image Builder 构建自定义 AMI 和容器映像的领域专业知识，涵盖从构建 IAM 角色到配方、管道、分发和故障排查的各个环节。

与以下工具配合效果最佳： AWS MCP 服务——推荐用于沙盒执行和审计日志记录。所有指导也适用于标准 AWS CLI 访问方式。

防护措施——此技能自身文件的位置（MCP 与本地安装）

此技能可以通过两种方式加载，它们会从不同位置解析技能自带的文件。读取参考资料或运行脚本之前，请先确定技能的加载方式：

• 通过 AWS MCP retrieve_skill 工具加载： 此技能未安装在本地文件系统中。你必须使用 retrieve_skill 的 file 参数获取每个参考资料或脚本（例如 file="references/creating-images.md"），并使用返回的内容。不要在本地使用 file_read 读取这些路径——它们在磁盘上不存在。
• 本地安装（例如 .kiro/skills/amazon-ec2-image-builder/ 或 ~/.claude/skills/amazon-ec2-image-builder/）：使用相对路径从本地技能目录读取文件。

此区别仅适用于技能自身打包的文件。用户数据和会话产物始终从用户的工作目录读取并写入。切勿通过 retrieve_skill 获取或写入用户数据。

首要判断：一次性映像还是定期运行的管道

创建任何内容之前，先询问这一点——它会影响构建方式。

用户需求	操作
只创建一次自定义 AMI	按照 creating-images.md 完成第 7a 步：使用配方和基础设施配置运行 create-image——无需创建管道。
持续保持最新的黄金 AMI（按计划重建，以获取基础映像更新和补丁）	使用映像管道：按照 creating-images.md 操作——计划是 create-image-pipeline 调用的一部分（第 7b 步）。

相关技能——应转到相应技能

使用此技能	适用请求
launching-ec2-instance-with-best-practices	从用户已有的 AMI 启动实例
setting-up-ec2-instance-profiles	一般的实例配置文件（不包括此技能创建的构建 IAM 角色）
aws-compute	AMI 共享、退役和生命周期管理；一般 EC2 实例集问题

此处未涵盖： AMI 生命周期／退役（请通过上表转到相应技能）以及 VM／ISO 映像导入和导出（请直接查阅 AWS 文档）。

路由（此技能中的参考资料）

回答前请阅读匹配的参考资料。具体命令、故障修复方法和平台要求都在参考资料中——仅凭一般知识回答 Image Builder 问题，容易导致细节出现微妙的错误。

用户需求	阅读
端到端创建映像或管道：角色、组件、配方、基础设施、计划、补丁、扫描、串联	creating-images.md
在需要的位置获取输出 AMI：启动模板、SSM 参数（服务关联角色只会写入 /imagebuilder/ 下）、其他区域	distribution-options.md
构建失败、卡住或 Image Builder API 调用出错	troubleshooting.md
Windows（exit-3010 重启）、macOS（必须使用 Mac Dedicated Hosts）、将容器映像推送到 ECR（构建角色需要额外策略）	other-image-types.md
自定义映像工作流（高级——始终需要执行角色）	custom-workflows.md

参考文件中列有具体的 ARN、Amazon 托管资源名称和服务默认值——需要精确的信息时，请对照 AWS 文档确认。

防护措施（适用于每个工作流）

• 包含空格的 CLI 筛选值必须加引号：--filters "name=name,values=Amazon Linux 2023 x86"。未加引号的空格会导致 CLI 解析错误。
• 每次创建调用都必须使用其返回的确切 ARN，切勿手动构造 ARN。
• 使用“latest”基础映像时，请使用带有 x.x.x 通配符的 Amazon 管理型映像 ARN；若没有管理型映像，则使用 ssm: 参数引用。切勿列出版本并按字符串排序，因为列表并非按 semver 排序。
• 基础映像、每个组件的二进制文件以及基础设施实例类型必须保持架构一致。Image Builder 不会在创建时对此进行验证；架构不匹配只会在构建中途运行组件时导致失败。
• 对于组件故障，根本原因记录在 CloudWatch 日志组 /aws/imagebuilder/<image-name> 中（默认启用；若已配置，也会记录在 S3 日志中），而不在 API 状态中。请参阅 troubleshooting.md。
• 如需在构建中途重启，请以代码 194（Linux）或 3010（Windows）退出步骤。重启后会重新运行同一个步骤，而不是下一个步骤，因此请用标记文件作为判断条件。直接运行普通重启命令会导致步骤失败。
• 如果用户描述的资源无法通过 get-image/get-image-pipeline 查到，请说明你找不到该资源，并检查当前使用的 Region 和凭证；然后继续根据用户的描述排查。查询失败不能证明资源不存在。
• Distribution 原生支持启动模板和 SSM 发布（launchTemplateConfigurations、ssmParameterConfigurations），切勿为 AMI 传播添加 Lambda 胶水代码或手动创建启动模板版本。
• 默认设置：Amazon Linux 2023 基础映像、要求使用 IMDSv2（instanceMetadataOptions httpTokens=required），并在基础设施配置中至少设置两种实例类型。S3 构建日志为可选配置，CloudWatch 日志始终启用。
• 编写组件 YAML 前，先检查 Amazon 管理型组件（aws imagebuilder list-components --owner Amazon）。常见需求（AWS CLI、操作系统更新、CloudWatch agent、STIG 加固）已有对应组件。

安全注意事项

以上默认设置体现了安全基线：构建实例要求使用 IMDSv2、不配置入站安全组规则、构建 IAM 角色遵循最小权限原则（AMI 构建使用两项托管策略，此外仅授予工作流所需的特定权限）、组件或日志中不包含密钥，以及日志存储桶启用 Block Public Access。构建日志会记录完整命令输出，其中可能包含敏感信息；CloudWatch Logs 默认会对静态日志加密，并建议为每个 /aws/imagebuilder/... 日志组关联客户管理的 KMS 密钥（aws logs associate-kms-key）。为便于审计和运维监控，请在账户中启用 CloudTrail，以记录 Image Builder API 调用；并针对构建失败配置 EventBridge 规则或 CloudWatch 警报（来源 aws.imagebuilder，detail-type EC2 Image Builder Image State Change），以便及时发现错误配置和未经授权的更改。每次构建通知由 SNS 主题选项处理（creating-images.md 第 6 步）；该主题也建议使用客户管理的密钥。任何偏离上述设置的做法都应由用户明确决定。参考：EC2 Image Builder security best practices。