aws-deployment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AWS Deploy (CI/CD)

Works best with the AWS MCP server for running CLI commands and validating configurations directly. All guidance also works with standard AWS CLI.

最佳搭配AWS MCP服务器使用，可直接运行CLI命令并验证配置。所有指南也适用于标准AWS CLI。

Critical Warnings

重要警告

CodeConnections PENDING trap: Connections created via CLI/CloudFormation remain

PENDING

indefinitely — MUST complete OAuth in the AWS Console. No API-only path exists.

Cross-account triple requirement: Cross-account deploys need ALL THREE: (1) KMS key policy granting target account (use key ID, not alias), (2) S3 bucket policy for target account, (3) cross-account IAM role with trust policy. Missing any one = cryptic

Access Denied

CodeDeploy ApplicationStop uses PREVIOUS revision: Broken stop scripts in a prior deployment block ALL future deploys. Make stop scripts idempotent (exit 0 if service absent). Unblock with

--ignore-application-stop-failures

CodeBuild VPC without NAT: Builds in VPC subnets without NAT gateway hang at

DOWNLOAD_SOURCE

silently. Private subnets MUST have NAT gateway or VPC endpoints.

CodeConnections IAM: Use

codeconnections:

prefix for API calls and IAM policy Actions. Resource ARNs must match exactly — new resources use

codeconnections

prefix, existing resources may use

codestar-connections

prefix. Specify both in Resource if you have mixed-age resources.

UseConnection is over-permissive:

codeconnections:UseConnection

grants access to ALL repositories the connection can reach. MUST specify condition keys (

codeconnections:FullRepositoryId

codeconnections:ProviderAction

codeconnections:BranchName

) to limit CodeBuild to only the required repository.

CodeConnections PENDING陷阱：通过CLI/CloudFormation创建的连接会无限期处于

PENDING

状态——必须在AWS控制台完成OAuth授权。不存在仅通过API完成的路径。

跨账户部署三重要求：跨账户部署需要满足以下全部三个条件：(1) 授予目标账户访问权限的KMS密钥策略（使用密钥ID，而非别名），(2) 针对目标账户的S3存储桶策略，(3) 带有信任策略的跨账户IAM角色。缺少任意一项都会导致模糊的

Access Denied

（访问被拒绝）错误。

CodeDeploy ApplicationStop使用旧版本：之前部署中存在问题的停止脚本会阻止所有后续部署。请确保停止脚本具有幂等性（如果服务不存在则返回0）。可使用

--ignore-application-stop-failures

参数解除阻塞。

无NAT的CodeBuild VPC：在没有NAT网关的VPC子网中执行构建会在

DOWNLOAD_SOURCE

阶段静默挂起。私有子网必须配置NAT网关或VPC终端节点。

CodeConnections IAM权限：API调用和IAM策略操作需使用

codeconnections:

前缀。资源ARN必须完全匹配——新资源使用

codeconnections

前缀，现有资源可能使用

codestar-connections

前缀。如果资源新旧混合，请在资源中同时指定两个前缀。

UseConnection权限过度宽松：

codeconnections:UseConnection

权限会授予访问该连接可触及的所有仓库的权限。必须指定条件键（

codeconnections:FullRepositoryId

、

codeconnections:ProviderAction

、

codeconnections:BranchName

）来限制CodeBuild仅访问所需仓库。

How These Services Compose

服务组合方式

CodeConnections → CodeBuild → CodeDeploy, orchestrated by CodePipeline.

Layer	Service	Role
Source	CodeConnections	Authenticates to GitHub/GitLab/Bitbucket, delivers code
Packages	CodeArtifact	Private package registry, dependency caching from public registries
Build/Test	CodeBuild	Compiles, tests, packages artifacts
Deploy	CodeDeploy	Deploys to EC2/ECS/Lambda with traffic shifting strategies
Orchestrator	CodePipeline	Chains stages, manages transitions, approval gates

Default: V2 pipeline type with QUEUED execution mode. Use PARALLEL only when executions are fully independent.

CodeConnections → CodeBuild → CodeDeploy，由CodePipeline编排。

层级	服务	角色
源	CodeConnections	向GitHub/GitLab/Bitbucket进行身份验证，交付代码
包	CodeArtifact	私有包仓库，缓存来自公共仓库的依赖
构建/测试	CodeBuild	编译、测试、打包制品
部署	CodeDeploy	使用流量切换策略部署到EC2/ECS/Lambda
编排器	CodePipeline	串联阶段、管理过渡、审批网关

默认：采用QUEUED执行模式的V2流水线类型。仅当执行任务完全独立时才使用PARALLEL模式。

Quick Navigation

快速导航

You want to...	Go to
Create a pipeline (V2, triggers, variables, modes)	codepipeline.md
Connect GitHub/GitLab/Bitbucket source	codeconnections.md
Write buildspec.yml / configure builds	codebuild.md
Set up private package registry for builds	codeartifact.md
Configure deployment strategy (blue/green, canary)	codedeploy.md
Cross-account or cross-region deployment	codepipeline.md
Fix failing pipeline, build, or deployment	troubleshooting.md

你想要...	前往
创建流水线（V2、触发器、变量、模式）	codepipeline.md
连接GitHub/GitLab/Bitbucket源	codeconnections.md
编写buildspec.yml / 配置构建	codebuild.md
为构建设置私有包仓库	codeartifact.md
配置部署策略（蓝绿、金丝雀）	codedeploy.md
跨账户或跨区域部署	codepipeline.md
修复失败的流水线、构建或部署	troubleshooting.md

Common Workflows

常见工作流

Task	Action	Reference
Pipeline from GitHub to ECS	Create connection → CodeBuild Docker stage → CodeDeploy ECS blue/green	codepipeline, codedeploy
Pipeline stuck at source	Check connection status; if PENDING, complete OAuth in AWS Console	troubleshooting
Build timing out	Check VPC/NAT, increase `timeoutInMinutes` , verify Docker privileged mode	codebuild
Deploy to another account	Configure KMS + S3 bucket policy + cross-account role, add `RoleArn` to action	codepipeline
Roll back failed deployment	Auto-rollback on alarm/failure; manual: `stop-deployment --auto-rollback-enabled`	codedeploy
Lambda canary deployment	CodeBuild packages → CodeDeploy Lambda with canary traffic shifting	codedeploy

任务	操作	参考
从GitHub到ECS的流水线	创建连接 → CodeBuild Docker阶段 → CodeDeploy ECS蓝绿部署	codepipeline、codedeploy
流水线在源阶段卡住	检查连接状态；如果处于PENDING状态，在AWS控制台完成OAuth授权	troubleshooting
构建超时	检查VPC/NAT配置，增加 `timeoutInMinutes` ，验证Docker特权模式	codebuild
部署到其他账户	配置KMS + S3存储桶策略 + 跨账户角色，在操作中添加 `RoleArn`	codepipeline
回滚失败的部署	触发警报/失败时自动回滚；手动回滚： `stop-deployment --auto-rollback-enabled`	codedeploy
Lambda金丝雀部署	CodeBuild打包 → CodeDeploy Lambda金丝雀流量切换	codedeploy

Troubleshooting

故障排查

Error/Symptom	Cause	Fix
`YAML_FILE_ERROR` in CodeBuild	Missing or malformed `runtime-versions` in buildspec (recommended for standard images)	Add `runtime-versions` block in install phase
`file already exists` on CodeDeploy	Redeployment without overwrite config	Set `file_exists_behavior: OVERWRITE`
Pipeline trigger not firing	File path filter checks only first 100 files in diff	Reduce path filter scope or merge smaller
PARALLEL mode wrong revision	Race between event and source action	Use QUEUED mode for sequential consistency
Docker: `Cannot connect to daemon`	Missing privileged mode	Set `privilegedMode: true` AND start dockerd in buildspec
`CODEBUILD_CLONE_REF` permission error	CodeBuild role missing UseConnection	Add `codeconnections:UseConnection` to CodeBuild service role
Deployment never completes	MinimumHealthyHosts too high for instance count	Ensure healthy threshold < total instances
ECS deployment stuck	Health check failing on new task set	Verify target group health check path/port

错误/症状	原因	修复方案
CodeBuild中出现 `YAML_FILE_ERROR`	buildspec中缺少或格式错误的 `runtime-versions` （标准镜像推荐配置）	在install阶段添加 `runtime-versions` 块
CodeDeploy中出现 `file already exists`	重新部署未配置覆盖设置	设置 `file_exists_behavior: OVERWRITE`
流水线触发器未触发	文件路径过滤器仅检查差异中的前100个文件	缩小路径过滤器范围或合并较小的提交
PARALLEL模式下版本错误	事件与源操作之间存在竞争	使用QUEUED模式保证顺序一致性
Docker： `Cannot connect to daemon`	缺少特权模式	设置 `privilegedMode: true` 并在buildspec中启动dockerd
`CODEBUILD_CLONE_REF` 权限错误	CodeBuild角色缺少UseConnection权限	为CodeBuild服务角色添加 `codeconnections:UseConnection` 权限
部署从未完成	MinimumHealthyHosts阈值高于实例数量	确保健康阈值小于实例总数
ECS部署卡住	新任务集的健康检查失败	验证目标组健康检查路径/端口

Security

安全建议

MUST store secrets in Secrets Manager or Parameter Store; reference via CodeBuild
```
type: SECRETS_MANAGER
```
— MUST NOT embed in buildspec as PLAINTEXT
MUST use customer-managed KMS keys for cross-account artifact encryption (default encryption does not support cross-account)
SHOULD scope CodeBuild/CodeDeploy service roles to specific resource ARNs; MUST NOT use
```
*
```
for
```
s3:GetObject
```
or
```
kms:Decrypt
```
MUST use CodeConnections (not personal access tokens) for source connections; OAuth tokens cannot be rotated automatically
See CodePipeline security best practices for comprehensive guidance

必须将密钥存储在Secrets Manager或Parameter Store中；通过CodeBuild的
```
type: SECRETS_MANAGER
```
引用——绝对不能以明文形式嵌入到buildspec中
跨账户制品加密必须使用客户管理的KMS密钥（默认加密不支持跨账户）
应将CodeBuild/CodeDeploy服务角色的权限限定在特定资源ARN；绝对不能为
```
s3:GetObject
```
或
```
kms:Decrypt
```
使用
```
*
```
通配符
源连接必须使用CodeConnections（而非个人访问令牌）；OAuth令牌无法自动轮换
如需全面指南，请查看CodePipeline安全最佳实践

Not Covered

未涵盖内容

Topic	Use instead
CDK Pipelines ( `aws-cdk-lib/pipelines` )	`aws-cdk`
`sam deploy` / SAM CLI	`aws-serverless`
ECS service deployment config (circuit breaker, rolling params)	`aws-containers`
GitHub Actions / GitLab CI	Third-party tools, not covered

主题	请使用
CDK Pipelines ( `aws-cdk-lib/pipelines` )	`aws-cdk`
`sam deploy` / SAM CLI	`aws-serverless`
ECS服务部署配置（熔断机制、滚动更新参数）	`aws-containers`
GitHub Actions / GitLab CI	第三方工具，不在本指南涵盖范围内