CodeNote.net

AWS Copilot CLI で Preview 環境を作ろうとして断念した話

#aws #infrastructure
重岡 正 ·  Tue, February 24, 2026

PR ごとに独立した Preview 環境を自動構築したい。そう考えたとき、AWS 公式の ECS デプロイツールである AWS Copilot CLI が最初の候補に挙がりました。Copilot CLI は copilot svc deploy 一発で ECS Fargate にアプリケーションをデプロイできる手軽さが魅力で、公式ドキュメントにも環境管理の仕組みが用意されています。

結論から言うと、私のケースでは Copilot CLI は不向きでした。丸一日の PoC でアプリケーションの起動まで到達できず、Copilot CLI の抽象化がかえって足かせになると判断して断念しました。

この記事では、PoC で何を試し、どこで詰まり、なぜ断念したのかを記録します。同じように Copilot CLI を検討している方の判断材料になれば幸いです。

PoC の目標

新規 AWS アカウントを作成し、AWS Copilot CLI のみで以下を一気通貫で行うことを目指しました。

  • copilot app init でアプリケーション初期化
  • copilot svc init で API サービス（Load Balanced Web Service）と Worker サービス（バックグラウンドジョブ）を初期化
  • copilot env init + copilot env deploy で環境構築
  • copilot svc deploy でデプロイ（Aurora Serverless v2 Addon 含む）
  • アプリケーションの起動確認、DB マイグレーション、認証連携の検証

本格的なマニフェスト整備や GitHub Actions 自動化の前に、まず「Copilot CLI でこのアプリが動くか」を最短で確認するのが目的です。特に Cognito 連携が最大のリスクと見ていたので、早期に検証して潰したいと考えていました。

PoC の結果

タスク結果
アプリケーション初期化 (app init)成功
サービス初期化 (svc init)成功
環境構築 (env init + env deploy)成功
サービスデプロイ (svc deploy)Secrets/環境変数の注入問題でアプリ起動に至らず
DB マイグレーション未着手（上記ブロッカーにより）
Cognito 連携確認未着手
全リソースクリーンアップ (app delete)成功

環境構築まではスムーズに進みましたが、サービスデプロイの段階で Secrets/環境変数の注入が壁になり、アプリケーションの起動まで到達できませんでした。

判明した課題

課題 1: Secrets/環境変数の注入（最大のブロッカー）

Copilot CLI が生成する ECS Execution Role に SSM Parameter Store や Secrets Manager の読み取り権限が自動付与されません。以下の方法を全て試しましたが、いずれも失敗しました。

方法結果
secrets + SSM パラメータパスssm:GetParameters AccessDenied
secrets + secretsmanager: プレフィックスsecretsmanager:GetSecretValue AccessDenied
from_cfn で Addon 出力を参照（secrets）No export named ... found
from_cfn で Addon 出力を参照（variables）同上

Addon で作成したリソース（Aurora 等）の接続情報をコンテナに渡す手段が極めて限られているというのが根本的な問題です。Addon から Execution Role にポリシーを追加する手段もありません。

課題 2: Addon の制約

Copilot CLI の Addon 機能は CloudFormation テンプレートを追加する仕組みですが、以下の制約がありました。

YAML 構文の制約: Copilot CLI のパーサーは !Sub、!Ref 等の CloudFormation ショートハンド記法と相性が悪く、全て Fn::Sub、Ref 等の長形式で書く必要があります。CloudFormation に慣れた人ほどハマるポイントです。

from_cfn が機能しない: Addon の出力を Manifest から参照する公式機能ですが、内部で Fn::ImportValue（Export 必須）を使うため、ネストされたスタック出力を参照できません。Addon は Copilot CLI 内部ではネストスタックとして管理されるため、ここが根本的に噛み合っていませんでした。

課題 3: 実務の複雑さとの相性

Copilot CLI は「規約に沿ったシンプルなアプリ」向けに設計されています。実務の複雑さとの衝突を整理すると、以下のようになりました。

プロジェクトの特性Copilot CLI との衝突
docker-entrypoint.sh が JSON 形式の DB シークレットに依存Copilot CLI の secrets 機構で注入できない
ManageMasterUserPassword の Secret 形式がアプリの期待と不一致カスタム Secret を作ってもコンテナに渡せない
複数サービス（API / Admin / Worker）+ DB + RedisAddon 間の依存関係やリソース共有の管理が複雑
DB マイグレーションツールによるスキーマ管理DB 接続情報の受け渡しが同じ問題に直面

課題 4: デバッグループの遅さ

Copilot CLI での試行錯誤は非常に時間がかかりました。

ステップ所要時間
Aurora Serverless v2 作成15〜20 分
スタック削除10〜15 分
1 回の試行サイクル30 分以上

さらに以下の問題がデバッグを困難にしました。

  • ROLLBACK_COMPLETE でサービスが消えると copilot svc logs --previous が使えない
  • ネストスタック（Addon）のエラーは削除後に参照不可
  • CloudFormation のイベントログを直接確認する必要があり、Copilot CLI の抽象化の恩恵がない

課題 5: カスタマイズの壁

Copilot CLI の抽象化を超えようとすると、結局 CloudFormation の知識が必要になります。

  • Execution Role のカスタマイズ → 手段なし
  • Task Definition の細かい制御（entrypoint 上書き等）→ taskdef_overrides が必要
  • Addon 間でのリソース共有（例: API と Worker で同じ Aurora を使う）→ 独自の工夫が必要
  • 既存の Secrets 管理パターンとの統合 → Copilot CLI の規約に合わない

総合判断

観点評価
シンプルなアプリのデプロイCopilot CLI は優秀
複雑なアプリのデプロイ不向き
学習・デバッグコストCloudFormation の知識が結局必要で、抽象化が逆に障壁

なお、docker-entrypoint.sh のバイパスには taskdef_overrides による entrypoint 上書きが必要でした。一方、copilot app delete による全リソースのクリーンアップは問題なく動作し、この点は評価できます。

Copilot CLI は「Hello World レベルのアプリを最速で ECS にデプロイする」ツールとしては優れています。 しかし、実務で DB 接続、Secrets 管理、複数サービス連携といった現実的な要件が入ってくると、抽象化レイヤーが制約になります。

特に致命的だったのは、Addon で作成したリソースの接続情報をコンテナに注入する方法が事実上ないという点です。これは Preview 環境に限らず、Copilot CLI で本番レベルのアプリケーションを運用しようとした場合に必ず直面する問題だと考えています。

断念後の方針

ECS Fargate へのデプロイ自体は有効なアプローチです。問題は IaC ツールの選定でした。Copilot CLI の PoC から得た教訓を踏まえ、以下の代替案を検討しました。

選択肢利点懸念
TerraformHCL エコシステムが成熟、モジュール資産が豊富PR ごとの動的な環境管理が冗長になりがち
AWS CDKTypeScript で記述可能、CloudFormation の上位互換CloudFormation の制約を間接的に受ける
PulumiTypeScript、Review Stacks 機能、Stack ReferencePulumi Cloud の費用

まとめ

AWS Copilot CLI は手軽さが魅力のツールですが、以下のようなプロジェクトでは注意が必要です。

  • Addon で作成したリソースの接続情報をコンテナに渡す必要がある（DB、Redis 等）
  • Execution Role のカスタマイズが必要（SSM、Secrets Manager 等へのアクセス）
  • 複数サービスでリソースを共有する（API と Worker で同じ DB を使う等）
  • デバッグの試行サイクルが長い（Aurora 等の作成時間 + スタック削除時間）

「まず Copilot CLI で動くか試してみよう」という PoC アプローチ自体は正しかったと思います。丸一日で「不向き」という判断ができたことで、その後の Pulumi への方針転換をスムーズに進められました。ツール選定で迷ったら、小さく PoC を回して早期に判断することをおすすめします。

以上、IaC ツール選定は小さく試して早く判断していきたい、現場からお送りしました。