Back to Details

amazon-ec2-image-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Amazon EC2 Image Builder

Amazon EC2 Image Builder

Overview

概述

Domain expertise for building custom AMIs and container images with EC2 Image Builder — from the build IAM role through recipes, pipelines, distribution, and troubleshooting.
Works best with the AWS MCP server — recommended for sandboxed execution and audit logging. All guidance also works with standard AWS CLI access.
本技能提供使用EC2 Image Builder构建自定义AMI和容器镜像的领域专业知识——从构建IAM角色到配方、流水线、分发及故障排查的全流程指导。
最佳搭配 AWS MCP server —— 推荐用于沙箱执行和审计日志记录。所有指导同样适用于标准AWS CLI访问。

Guardrail — where this skill's own files live (MCP vs local install)

注意事项：本技能文件的存储位置（MCP vs 本地安装）

This skill can be loaded two ways, and they resolve the skill's own bundled files from different places. Determine how the skill was loaded before reading a reference or running a script:
  • Loaded through the AWS MCP 
    retrieve_skill
    tool:     The skill is not installed on the local filesystem. You MUST fetch each reference or script via 
    retrieve_skill
    with the 
    file
    parameter (e.g. 
    file="references/creating-images.md"
    ), and use the returned content. Do NOT 
    file_read
    these paths locally — they do not exist on disk.
  • Installed locally (e.g. 
    .kiro/skills/amazon-ec2-image-builder/
    or 
    ~/.claude/skills/amazon-ec2-image-builder/
    ): Read files from the local skill directory using relative paths.
This distinction applies only to the skill's own packaged files. User data and session artifacts are always read from and written to the user's working directory. Never fetch or write user data through 
retrieve_skill
.
本技能有两种加载方式，其配套文件的存储位置不同。在查阅参考文档或运行脚本前，请先确认技能的加载方式：
  • 通过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
获取或写入用户数据。

First decision: one-off image or recurring pipeline

首要决策：一次性镜像还是定期流水线

Ask this before creating anything — it changes what you build.
The user wantsDo this
One custom AMI, onceFollow creating-images.md through step 7a: 
create-image
with a recipe and infrastructure configuration — no pipeline needed.
A golden AMI that stays current (scheduled rebuilds that pick up base-image updates and patches)An image pipeline: follow creating-images.md — the schedule is part of the create-image-pipeline call (step 7b).
在创建任何资源前请先明确这一点——它会决定你的构建方式。
用户需求操作方式
一次性创建一个自定义AMI遵循creating-images.md完成至步骤7a：使用配方和基础设施配置调用
create-image
——无需流水线。
创建持续更新的黄金AMI（定期重建以获取基础镜像更新和补丁）创建镜像流水线：遵循creating-images.md——调度配置包含在
create-image-pipeline
调用中（步骤7b）。

Related skills — route there instead

相关技能：转至对应技能处理

Use this skillWhen the request is about
launching-ec2-instance-with-best-practicesLaunching instances from an AMI the user already has
setting-up-ec2-instance-profilesInstance profiles in general (not the build IAM role this skill creates)
aws-computeAMI sharing, retiring, and lifecycle management; general EC2 fleet questions
Not covered here: AMI lifecycle/retirement (route via the table above) and VM/ISO image import and export (follow the AWS documentation directly).
使用此技能适用于以下请求场景
launching-ec2-instance-with-best-practices从用户已有的AMI启动实例
setting-up-ec2-instance-profiles通用实例配置文件（非本技能创建的构建IAM角色）
aws-computeAMI共享、退役和生命周期管理；常规EC2集群问题
本技能不涵盖：AMI生命周期/退役管理（请根据上表转至对应技能）以及VM/ISO镜像导入导出（请直接参考AWS官方文档）。

Routing (references in this skill)

路由指引（本技能内的参考文档）

Read the matching reference before answering. The exact commands, failure fixes, and platform requirements live in the references — answering Image Builder questions from general knowledge is how agents get the details subtly wrong.
User needRead
Create an image or pipeline end to end: role, components, recipe, infrastructure, schedules, patching, scanning, chainingcreating-images.md
Get the output AMI where it's needed: launch templates, SSM parameters (the service-linked role writes only under 
/imagebuilder/
), other Regions		distribution-options.md
A build failed, hangs, or an Image Builder API call errorstroubleshooting.md
Windows (exit-3010 reboots), macOS (Mac Dedicated Hosts required), container images to ECR (extra build-role policy)other-image-types.md
Custom image workflows (advanced — always require an execution role)custom-workflows.md
Reference files carry specific ARNs, Amazon-managed resource names, and service defaults — when precision matters, confirm against the AWS documentation.
在回答问题前请先查阅对应的参考文档。具体命令、故障修复方案和平台要求均在参考文档中——仅凭通用知识回答Image Builder问题容易导致细节错误。
用户需求查阅文档
端到端创建镜像或流水线：角色、组件、配方、基础设施、调度、补丁、扫描、链式构建creating-images.md
将输出AMI分发至目标位置：启动模板、SSM参数（服务关联角色仅写入
/imagebuilder/
路径下）、其他区域		distribution-options.md
构建失败、挂起或Image Builder API调用报错troubleshooting.md
Windows系统（exit-3010重启）、macOS系统（需要Mac专用主机）、推送至ECR的容器镜像（额外的构建角色策略）other-image-types.md
自定义镜像工作流（高级功能——始终需要执行角色）custom-workflows.md
参考文档包含特定的ARN、亚马逊托管资源名称和服务默认值——当需要精确信息时，请与AWS官方文档进行确认。

Guardrails (every workflow)

通用注意事项（所有工作流）

  • Quote CLI filter values that contain spaces: 
    --filters "name=name,values=Amazon Linux 2023 x86"
    . Unquoted spaces are a CLI parse error.
  • Use the exact ARN each create call returns — never construct ARNs by hand.
  • For a "latest" base image use an Amazon-managed image ARN with the 
    x.x.x
    wildcard, or an 
    ssm:
    parameter reference where no managed image exists. Never list versions and sort them as strings — the list is not semver-ordered.
  • Keep architecture consistent across the base image, every component's binaries, and the infrastructure instance types. Image Builder performs no create-time validation of this; a mismatch only fails mid-build when the component runs.
  • For component failures, the root cause lives in CloudWatch log group 
    /aws/imagebuilder/<image-name>
    (on by default; also in the S3 logs if configured) — never in the API state. See troubleshooting.md.
  • To reboot mid-build, exit the step with code 
    194
    (Linux) or 
    3010
    (Windows). The build re-runs that same step after the reboot — not the next step — so guard it with a marker file. A plain reboot command fails the step.
  • If a resource the user describes isn't visible to 
    get-image
    /
    get-image-pipeline
    , say you can't find it and check the Region and credentials in use — then keep troubleshooting from the user's description; a failed lookup is not proof the resource doesn't exist.
  • Distribution handles launch templates and SSM publishing natively (
    launchTemplateConfigurations
    , 
    ssmParameterConfigurations
    ) — never add Lambda glue or manual launch-template versions for AMI propagation.
  • Default to: Amazon Linux 2023 base, IMDSv2 required (
    instanceMetadataOptions httpTokens=required
    ), and at least two instance types in the infrastructure configuration. S3 build logging is opt-in — CloudWatch logging is on regardless.
  • Check Amazon-managed components (
    aws imagebuilder list-components --owner Amazon
    ) before writing component YAML. Common needs (AWS CLI, OS updates, CloudWatch agent, STIG hardening) are already covered.
  • 对包含空格的CLI过滤值添加引号：
    --filters "name=name,values=Amazon Linux 2023 x86"
    。未加引号的空格会导致CLI解析错误。
  • 使用每个创建调用返回的精确ARN——切勿手动构造ARN。
  • 若要使用“最新”基础镜像，请使用带有
    x.x.x
    通配符的亚马逊托管镜像ARN，或在无托管镜像时使用
    ssm:
    参数引用。切勿列出版本并按字符串排序——版本列表并非遵循语义化版本顺序。
  • 保持基础镜像、所有组件二进制文件和基础设施实例类型的架构一致。Image Builder不会在创建时验证这一点；架构不匹配只会在组件运行时导致构建失败。
  • 对于组件失败问题，根本原因位于CloudWatch日志组
    /aws/imagebuilder/<image-name>
    中（默认启用；若配置了S3日志，也会存在于S3日志中）——而非API状态。请参阅troubleshooting.md。
  • 若要在构建中途重启，请以代码
    194
    （Linux）或
    3010
    （Windows）退出步骤。重启后构建会重新运行同一步骤——而非下一步骤——因此请使用标记文件进行防护。直接执行重启命令会导致步骤失败。
  • 如果用户描述的资源无法通过
    get-image
    /
    get-image-pipeline
    查询到，请告知用户无法找到该资源，并检查当前使用的区域和凭证——然后根据用户描述继续排查；查询失败并不证明资源不存在。
  • 分发功能原生支持启动模板和SSM发布（
    launchTemplateConfigurations
    、
    ssmParameterConfigurations
    ）——切勿为AMI传播添加Lambda胶水层或手动创建启动模板版本。
  • 默认配置：Amazon Linux 2023基础镜像、要求IMDSv2（
    instanceMetadataOptions httpTokens=required
    ）、基础设施配置中至少包含两种实例类型。S3构建日志为可选启用——CloudWatch日志始终默认开启。
  • 在编写组件YAML前，请先查看亚马逊托管组件（
    aws imagebuilder list-components --owner Amazon
    ）。常见需求（AWS CLI、操作系统更新、CloudWatch代理、STIG加固）已被覆盖。

Security considerations

安全考量

The defaults above are the security posture: IMDSv2 required on build instances, no inbound security-group rules, least-privilege build IAM role (two managed policies for AMI builds plus only the scoped grants a workflow needs), no secrets in components or logs, and log buckets with Block Public Access. Build logs capture full command output that can carry sensitive material; CloudWatch Logs encrypts them at rest by default, and associating a customer-managed KMS key with each 
/aws/imagebuilder/...
log group (
aws logs associate-kms-key
) is recommended. For auditing and operational visibility, enable CloudTrail in the account so Image Builder API calls are recorded, and configure EventBridge rules or CloudWatch alarms on build failures (source 
aws.imagebuilder
, detail-type 
EC2 Image Builder Image State Change
) so misconfigurations and unauthorized changes surface promptly. Per-build notifications are covered by the SNS topic option (creating-images.md step 6) — prefer a customer-managed key on that topic too. Deviations from these should be explicit user decisions. Reference: EC2 Image Builder security best practices.
上述默认配置即为安全基准：构建实例要求IMDSv2、无入站安全组规则、最小权限的构建IAM角色（AMI构建需两个托管策略，加上工作流所需的范围化权限）、组件或日志中不包含敏感信息、日志存储桶启用公共访问阻止。构建日志会捕获完整的命令输出，可能包含敏感内容；CloudWatch日志默认对静态数据进行加密，建议为每个
/aws/imagebuilder/...
日志组关联客户托管的KMS密钥（
aws logs associate-kms-key
）。为实现审计和运维可视性，请在账户中启用CloudTrail，以便记录Image Builder API调用，并针对构建失败配置EventBridge规则或CloudWatch告警（源
aws.imagebuilder
，详细类型
EC2 Image Builder Image State Change
），从而及时发现配置错误和未授权变更。每构建一次的通知由SNS主题选项覆盖（creating-images.md步骤6）——同样建议为该主题使用客户托管密钥。偏离这些配置需由用户明确决策。参考文档：EC2 Image Builder安全最佳实践。