aws-deployment

AWS デプロイ（CI/CD）

CLI コマンドの実行や設定の直接検証には、AWS MCP サーバーの使用が最適です。 すべてのガイダンスは標準の AWS CLI でも利用できます。

重大な警告

CodeConnections の PENDING トラップ：CLI／CloudFormation で作成した接続は、PENDING のまま無期限にとどまります。AWS コンソールで必ず OAuth を完了してください。API のみで完了する方法はありません。

クロスアカウントの 3 つの必須要件：クロスアカウントデプロイには、次の 3 つすべてが必要です：（1）対象アカウントへのアクセスを許可する KMS キーポリシー（エイリアスではなくキー ID を使用）、（2）対象アカウント用の S3 バケットポリシー、（3）信頼ポリシーを設定したクロスアカウント IAM ロール。いずれかが欠けると、原因が分かりにくい Access Denied が発生します。

CodeDeploy の ApplicationStop は PREVIOUS リビジョンを使用：以前のデプロイに含まれる停止スクリプトに問題があると、以降のすべてのデプロイがブロックされます。停止スクリプトは冪等にし、サービスが存在しない場合は 0 で終了するようにしてください。--ignore-application-stop-failures を指定するとブロックを解除できます。

NAT なしの VPC 内 CodeBuild：NAT ゲートウェイのない VPC サブネットでビルドを実行すると、DOWNLOAD_SOURCE で何の通知もなく停止します。プライベートサブネットには必ず NAT ゲートウェイまたは VPC エンドポイントを設定してください。

CodeConnections の IAM：API 呼び出しと IAM ポリシーの Actions には codeconnections: プレフィックスを使用してください。リソース ARN は完全一致する必要があります。新しいリソースには codeconnections プレフィックスが使われ、既存のリソースには codestar-connections プレフィックスが使われている場合があります。作成時期の異なるリソースが混在している場合は、Resource に両方を指定してください。

UseConnection の権限範囲は広すぎます：codeconnections:UseConnection を許可すると、その接続がアクセス可能なすべてのリポジトリへのアクセスが許可されます。CodeBuild が必要なリポジトリだけにアクセスできるよう、条件キー（codeconnections:FullRepositoryId、codeconnections:ProviderAction、codeconnections:BranchName）を必ず指定してください。

各サービスの連携方法

CodeConnections → CodeBuild → CodeDeploy を CodePipeline がオーケストレーションします。

レイヤー	サービス	役割
ソース	CodeConnections	GitHub／GitLab／Bitbucket に認証し、コードを配信します
パッケージ	CodeArtifact	プライベートパッケージレジストリとして機能し、パブリックレジストリからの依存関係をキャッシュします
ビルド／テスト	CodeBuild	成果物をコンパイル、テスト、パッケージ化します
デプロイ	CodeDeploy	トラフィックの切り替え戦略を使って EC2／ECS／Lambda にデプロイします
オーケストレーター	CodePipeline	ステージを連結し、遷移や承認ゲートを管理します

デフォルトは、キュー実行モードの V2 パイプラインタイプです。実行が完全に独立している場合に限り、PARALLEL を使用してください。

クイックナビゲーション

やりたいこと	移動先
パイプラインの作成（V2、トリガー、変数、モード）	codepipeline.md
GitHub／GitLab／Bitbucket のソースへの接続	codeconnections.md
buildspec.yml の作成／ビルドの設定	codebuild.md
ビルド用プライベートパッケージレジストリのセットアップ	codeartifact.md
デプロイ戦略（ブルー／グリーン、カナリア）の設定	codedeploy.md
クロスアカウントまたはクロスリージョンのデプロイ	codepipeline.md
失敗するパイプライン、ビルド、デプロイの修正	troubleshooting.md

一般的なワークフロー

タスク	操作	参照
GitHub から ECS へのパイプライン	接続を作成 → CodeBuild の Docker ステージ → CodeDeploy の ECS blue/green	codepipeline, codedeploy
パイプラインがソースで停止する	接続ステータスを確認します。PENDING の場合は、AWS Console で OAuth を完了します	troubleshooting
ビルドがタイムアウトする	VPC/NAT を確認し、timeoutInMinutes を増やし、Docker の特権モードを確認します	codebuild
別のアカウントにデプロイする	KMS + S3 バケットポリシー + クロスアカウントロールを設定し、アクションに RoleArn を追加します	codepipeline
失敗したデプロイをロールバックする	アラームまたは失敗時に自動ロールバックします。手動の場合：stop-deployment --auto-rollback-enabled	codedeploy
Lambda のカナリアデプロイ	CodeBuild でパッケージを作成 → CodeDeploy Lambda でカナリア方式のトラフィックシフトを実行します	codedeploy

トラブルシューティング

エラー／症状	原因	対処方法
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 のデプロイが停止する	新しいタスクセットのヘルスチェックに失敗しています	ターゲットグループのヘルスチェックパス／ポートを確認します

セキュリティ

• シークレットは必ず Secrets Manager または Parameter Store に保存し、CodeBuild の type: SECRETS_MANAGER で参照してください。buildspec に PLAINTEXT として埋め込んではいけません
• クロスアカウントのアーティファクト暗号化には、必ずカスタマー管理の KMS キーを使用してください（デフォルトの暗号化はクロスアカウントをサポートしていません）
• CodeBuild／CodeDeploy のサービスロールは、特定のリソース ARN にスコープを絞ることを推奨します。s3:GetObject または kms:Decrypt に * を使用してはいけません
• ソース接続には、必ず個人用アクセストークンではなく CodeConnections を使用してください。OAuth トークンは自動的にローテーションできません
• 包括的なガイダンスについては、CodePipeline のセキュリティに関するベストプラクティスを参照してください

対象外

トピック	代わりに使用
CDK Pipelines (aws-cdk-lib/pipelines)	aws-cdk
sam deploy／SAM CLI	aws-serverless
ECS サービスのデプロイ設定（サーキットブレーカー、ローリングパラメーター）	aws-containers
GitHub Actions／GitLab CI	対象外のサードパーティーツール