アプリケーション層の構築
FastAPIのAPIサーバをECS/Fargateにデプロイします。
1. イメージのビルド
ECS/Fargateでアプリケーションをデプロイするには、まずDockerイメージをビルドする必要があります。Docker Compose環境ではローカルでイメージをビルドしてそのまま使用しましたが、ECS環境ではビルドしたイメージをECRにプッシュし、Fargateがそこからイメージを取得して実行します。
以下のコマンドで、Docker がインストールされていることを確認します。
docker --version
以下のように Docker のバージョンが表示されれば、インストールは確認できています。
Docker version 27.x.x, build xxxxxxx
バージョンが表示されない場合は、Docker Desktopのインストール を先に実施してください。
インストールが確認できたら、Visual Studio Codeのターミナルからapiフォルダに移動し、Dockerイメージをビルドします。
cd api
docker build --platform linux/amd64 -t note-app-api:v1 .
--platform linux/amd64を指定することで、Fargateで動作するx86_64アーキテクチャのイメージをビルドします。
| 💡 ポイント |
|---|
サンプルリポジトリのmain.pyには、起動時にデータベースのテーブルを自動作成するlifespan関数が含まれています。Docker Compose環境ではinit.sqlでテーブルを作成していましたが、RDSではinit.sqlを自動実行できないため、この仕組みによりAPIコンテナ起動時にテーブルが自動作成されます。RDSの起動直後は接続に失敗することがあるため、最大30回まで2秒間隔でリトライする処理も入っています。 |
2. ECRリポジトリの作成

ビルドしたDockerイメージをAWS上で利用するには、イメージを保管する場所が必要です。ECR(Elastic Container Registry)はAWSが提供するDockerイメージのレジストリサービスで、Docker Hubのようにイメージをプッシュ・プルできます。
AWSマネジメントコンソールでECRを開き、サイドメニューの「プライベートリポジトリ」の部分にある「リポジトリ」をクリックしたうえで、右上の「リポジトリを作成」をクリックします。

下記の内容を設定してください。
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| リポジトリ名 | note-app-api | APIコンテナを識別するため |
| イメージタグのミュータビリティ | Mutable | デフォルトのまま。イメージタグの上書きを許可するため |
| 暗号化設定 | AES-256 | デフォルトのまま。標準的な暗号化で十分なため |

入力が完了したら「作成」をクリックします。リポジトリ一覧に note-app-api が表示されれば、リポジトリの作成は成功です。

3. ECRへのプッシュ
ECRリポジトリが作成できたら、ローカルでビルドしたDockerイメージをECRにプッシュします。ECRにプッシュすることで、ECS/Fargateがこのイメージを取得してコンテナを起動できるようになります。
3.1 ECRへのログイン
以下のコマンドで、AWS CLI がインストールされていることを確認します。
aws --version
以下のように AWS CLI のバージョンが表示されれば、インストールは確認できています。
aws-cli/2.x.x Python/3.x.x Darwin/xx.x.x source/arm64
バージョンが表示されない場合は、AWS CLIのインストール を先に実施してください。
インストールが確認できたら、以下のコマンドでECRにログインします。
aws ecr get-login-password --region ap-northeast-1 | docker login --username AWS --password-stdin <AWSアカウントID>.dkr.ecr.ap-northeast-1.amazonaws.com
ECRの認証トークンを取得し、Dockerクライアントでログインします。「Login Succeeded」と表示されれば成功です。
3.2 タグの付与
docker tag note-app-api:v1 <AWSアカウントID>.dkr.ecr.ap-northeast-1.amazonaws.com/note-app-api:v1
ローカルのイメージに、ECRリポジトリのURIをタグとして付与します。Dockerはタグに含まれるURIを見てプッシュ先を判断するため、この手順が必要です。
3.3 ECRリポジトリへのプッシュ
docker push <AWSアカウントID>.dkr.ecr.ap-northeast-1.amazonaws.com/note-app-api:v1
タグ付けしたイメージをECRリポジトリにプッシュします。プッシュが完了すると、ECRコンソール上でイメージを確認できるようになります。

| ⚠️ 「AccessDeniedException」エラーが出る場合 |
|---|
IAMユーザにECRへの権限がありません。IAMコンソールでAmazonEC2ContainerRegistryFullAccessポリシーをアタッチしてください。 |
4. ALBとターゲットグループの作成

ECSサービスを作成する前に、トラフィックを振り分けるためのALBとターゲットグループを作成します。今回、Fargateタスクはプライベートサブネットに配置しますが、ALBはインターネットからのアクセスを受け付けるためパブリックサブネットに配置する必要があります。ALBとECSサービスで配置するサブネットが異なるため、ALBはEC2コンソールで事前に作成します。
4.1 ターゲットグループの作成
EC2コンソールの「ターゲットグループ」から「ターゲットグループの作成」をクリックします。


下記の内容を設定してください。
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| ターゲットタイプ | IPアドレス | Fargateではインスタンスではなく、タスクごとに割り振られるIPアドレスでルーティングするため |
| ターゲットグループ名 | note-app-api-tg | ターゲットグループを識別するため |
| プロトコル | HTTP | HTTP通信を使用するため |
| ポート | 8000 | FastAPIがリッスンするポート |
| VPC | CloudFormation出力値のVPCIdに対応するVPC |
CloudFormationで作成したVPCを選択 |
| ヘルスチェックパス | /health | FastAPIのヘルスチェックエンドポイントを使用するため |

「次へ」をクリックし、ターゲットの登録はスキップして「次へ」をクリックします。

確認と作成の画面が表示されるので、特に問題がなければ「ターゲットグループの作成」をクリックします。

無事にターゲットグループが作成されれば、ここまでの操作は完了です。

| 💡 ポイント |
|---|
| ターゲットの登録はスキップして構いません。ECSサービスを作成する際にALBとターゲットグループを紐づけると、ECSがタスクの起動・停止に合わせてターゲットの登録・解除を自動的に行います。そのため、ここで手動でターゲットを登録する必要はありません。 |
4.2 ALBの作成
EC2コンソールの「ロードバランサー」から「ロードバランサーの作成」を選択してください。

「Application Load Balancer」の「作成」をクリックします。

下記の内容を設定してください。
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| ロードバランサー名 | note-app-api-alb | ALBを識別するため |
| スキーム | インターネット向け | インターネットからアクセスを受け付けるため |
| IPアドレスタイプ | IPv4 | 標準的なIPv4を使用するため |
| VPC | CloudFormation出力値のVPCIdに対応するVPC |
CloudFormationで作成したVPCを選択 |
| マッピング | CloudFormation出力値のPublicSubnet1Id、PublicSubnet2Idに対応するサブネット |
パブリックサブネットを選択(プライベートサブネットを選ばないよう注意) |
| セキュリティグループ | CloudFormation出力値のALBSecurityGroupIdに対応するSG |
CloudFormationで作成したALB用セキュリティグループを選択 |

リスナーの設定
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| プロトコル | HTTP | HTTPでリクエストを受け付けるため |
| ポート | 80 | 標準的なHTTPポート |
| デフォルトアクション | note-app-api-tgに転送 | 先ほど作成したターゲットグループを選択 |

「ロードバランサーの作成」をクリックします。

ロードバランサー一覧に note-app-api-alb が表示されれば成功です。

5. ECSクラスターの作成

ECSクラスターは、コンテナを実行するための論理的なグループです。サービスやタスクはクラスターの中に作成するため、まずクラスターを用意する必要があります。
ECSコンソールを開き、サイドメニューから「クラスター」を選択し、右上の「クラスターの作成」をクリックします。

下記の内容を設定してください。
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| クラスター名 | note-app-cluster | クラスターを識別するため |
| インフラストラクチャ | Fargateのみ | サーバレスで運用するため |

無事にnote-app-clusterが作成されればここまでの操作は完了です。なお、作成までには数分かかることがあります。

6. タスク定義の作成

タスク定義は、コンテナの設計図にあたるものです。使用するDockerイメージ、割り当てるCPU・メモリ、環境変数、ポート設定などを定義します。Docker Composeの docker-compose.yml に相当する役割です。
「タスク定義」→「新しいタスク定義の作成」をクリックします。

下記の内容を設定してください。
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| タスク定義ファミリー | note-app-api | タスク定義を識別するため |
| 起動タイプ | AWS Fargate | サーバレスで実行するため |
| オペレーティングシステム | Linux/X86_64 | 一般的なLinux環境を使用するため |
| タスクサイズ - CPU | 1 vCPU | 最小限のリソースで十分なため |
| タスクサイズ - メモリ | 3 GB | 最小限のリソースで十分なため |
| タスク実行ロール | 新しいロールの作成 | ECRからイメージを取得するために必要 |

| 💡 ポイント |
|---|
タスク実行ロールは、ECSがコンテナを起動する際に使用するIAMロールです。「新しいロールの作成」を選択すると、ecsTaskExecutionRole という名前のロールが自動的に作成され、ECRからのイメージ取得やCloudWatch Logsへのログ出力に必要な権限が付与されます。このロールは一度作成されると、次回以降のタスク定義では「既存のロールを使用」から ecsTaskExecutionRole を選択できるようになります。 |
| 💡 ポイント |
|---|
| 同じ画面にあるタスクロールは未選択のままで構いません。タスクロールは、コンテナ内のアプリケーションからS3やDynamoDBなどのAWSサービスにアクセスする場合に必要となるロールです。今回のアプリケーションはRDSへの接続にIAMロールを使用しないため(環境変数でユーザ名・パスワードを直接指定するため)、タスクロールは不要です。 |
6.1 コンテナの設定
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| 名前 | api | コンテナを識別するため |
| イメージURI | <AWSアカウントID>.dkr.ecr.ap-northeast-1.amazonaws.com/note-app-api:v1 | ECRにプッシュしたイメージ |
| コンテナポート | 8000 | FastAPIがリッスンするポート |

6.2 環境変数
Docker Compose環境では、docker-compose.yml の environment セクションでデータベースの接続先を指定していました。ECS環境でも同じように、タスク定義の環境変数でAPIコンテナにRDSの接続情報を渡します。アプリケーションのコード内で os.environ などを使ってこれらの値を読み取り、RDSに接続します。
| キー | 値 | 設定の基準 |
|---|---|---|
| DB_HOST | CloudFormation出力値のRDSEndpoint |
RDSに接続するため |
| DB_USER | admin | RDSのマスターユーザ名 |
| DB_PASSWORD | スタック作成時に指定したDBMasterPassword |
RDSのマスターパスワード |
| DB_NAME | notedb | 使用するデータベース名 |

| 💡 ポイント |
|---|
| 実際には、パスワードなどの機密情報は環境変数に直接記載せず、AWS Secrets Managerを使用することを推奨します。このセクションでは簡略化のため、環境変数に直接設定しています。 |
すべての入力が完了したら、「作成」をクリックします。

無事にタスク定義が作成されれば、ここまでの操作は完了です。

7. ECSサービスの作成

続いて、ECSサービスを作成します。ECSサービスは、タスク定義に基づいてコンテナを起動・維持する仕組みです。指定した数のタスクを常時稼働させ、タスクが停止した場合は自動的に再起動します。
ECSコンソールでクラスターを選択し、「サービス」タブから「作成」をクリックします。

7.1 サービスの詳細
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| タスク定義ファミリー | note-app-api | 先ほど作成したタスク定義を選択 |
| タスク定義のリビジョン | 空欄のまま | 最新リビジョンが自動的に使用されるため |
| サービス名 | note-app-api-service | サービスを識別するため |

7.2 環境
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| 既存のクラスター | note-app-cluster | 先ほど作成したクラスターが選択されていることを確認 |
| コンピューティングオプション | キャパシティプロバイダー戦略 | デフォルトのまま |
| キャパシティプロバイダー | FARGATE | Fargateで実行するため |
| プラットフォームバージョン | LATEST | 最新のFargateプラットフォームを使用するため |

7.3 デプロイ設定
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| スケジューリング戦略 | レプリカ | デフォルトのまま。クラスター全体で必要な数のタスクを配置するため |
| 必要なタスク | 1 | まずは1つのタスクで起動する |
| アベイラビリティゾーンのリバランスを有効にする | チェックあり | デフォルトのまま。タスクをAZ間で均等に配置するため |
| ヘルスチェックの猶予期間 | 0 | デフォルトのまま |

7.4 ネットワーキング
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| VPC | note-app-vpc |
CloudFormationで作成したVPCを選択 |
| サブネット | note-app-private-subnet-1, note-app-private-subnet-2 |
CloudFormation出力値のPrivateSubnet1Id、PrivateSubnet2Idに対応する2つのプライベートサブネットを選択 |
| セキュリティグループ | note-app-api-sg |
CloudFormation出力値のAPISecurityGroupIdに対応するSG |
| パブリックIP | オフ | プライベートサブネットに配置するためパブリックIPは不要 |

7.5 ロードバランシング
「ロードバランシングを使用」にチェックを入れると、ALBの設定項目が表示されます。下記の内容を設定してください。
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| ロードバランサーの種類 | Application Load Balancer | HTTP/HTTPSのルーティングを行うため |
| コンテナ | api 8000:8000 | タスク定義で設定したコンテナとポートを選択 |
| Application Load Balancer | 既存のロードバランサーを使用 | 先ほど作成したALBを使用するため |
| ロードバランサー | note-app-api-alb | 先ほど作成したALBを選択 |
| リスナー | 既存のリスナーを使用 | 先ほど作成したリスナーを使用するため |
| リスナーのポート | 80:HTTP | 先ほど作成したリスナーを選択 |
| ターゲットグループ | 既存のターゲットグループを使用 | 先ほど作成したターゲットグループを使用するため |
| ターゲットグループ名 | note-app-api-tg | 先ほど作成したターゲットグループを選択 |

7.6 サービスの自動スケーリング - オプション
アクセスが集中してCPU使用率が高くなった際に、タスク数を自動的に増やして負荷を分散させるための設定を行います。ここでは、CPU使用率が70%を超えたらタスクを追加し、負荷が下がったらタスクを減らすルールを設定します。
「サービスの自動スケーリングを使用」にチェックを入れると、スケーリングの設定項目が表示されます。下記の内容を設定してください。
| 設定項目 | 値 | 設定の基準 |
|---|---|---|
| タスクの最小数 | 1 | 最低1つは常時起動するため |
| タスクの最大数 | 3 | 負荷に応じて最大3つまでスケールするため |
| スケーリングポリシータイプ | ターゲットの追跡 | メトリクスの目標値に基づいてタスク数を自動調整するため |
| ポリシー名 | api-cpu-scaling | スケーリングポリシーを識別するため |
| ECSサービスメトリクス | ECSServiceAverageCPUUtilization | CPU使用率を監視するため |
| ターゲット値 | 70 | CPU使用率が70%を超えたらスケールアウトするため |
| スケールアウトクールダウン期間 | 300 | デフォルトのまま。スケールアウト後、次の判定まで300秒待機する |
| スケールインクールダウン期間 | 300 | デフォルトのまま。スケールイン後、次の判定まで300秒待機する |
| スケールインをオフにする | チェックなし | デフォルトのまま。負荷が下がったらタスクを減らすため |

すべての設定が完了したら「作成」をクリックします。

サービスが作成中になります。完了まで数分かかるため、しばらく待ちましょう。

| ⚠️ タスクがPENDINGのままになる場合 |
|---|
| (1)セキュリティグループでアウトバウンド通信(すべてのトラフィック)が許可されているか確認してください。 (2)サブネットがプライベートサブネットになっているか確認してください。パブリックサブネットを選択している場合は、プライベートサブネットに変更してください。 (3)タスク定義の環境変数(DB_HOST, DB_USER, DB_PASSWORD, DB_NAME)が正しいか確認してください。 |
8. 動作確認
サービスのステータスが「アクティブ」になり、デプロイとタスクが「1/1件の実行中のタスク」となったら、サービスの作成と、タスクの起動が完了です。

ALB経由でアクセスして動作を確認します。
EC2コンソールの「ロードバランサー」から note-app-api-alb を選択し、「DNS名」をコピーします。ブラウザまたはcurlで以下のようにアクセスしてください。

curl http://<ALBのDNS名>/health
以下のレスポンスが返れば、APIは正常に動作しています。
{"status":"healthy"}
ノート一覧も確認します。
curl http://<ALBのDNS名>/notes
空の配列 [] が返れば、RDSとの接続も成功しています。
| ⚠️ 「502 Bad Gateway」エラーが出る場合 |
|---|
(1)ターゲットグループでターゲットが「healthy」になっているか確認してください。ターゲットが「unhealthy」の場合は、ヘルスチェックパスが /health に設定されているか確認してください。(2)APIタスク用セキュリティグループで、ALBのセキュリティグループからのポート8000へのインバウンドが許可されているか確認してください。 |
9. CloudWatch Logsでのログ確認
ECSで動作するコンテナのログは、ローカル環境のように docker logs コマンドでは確認できません。代わりに、CloudWatch Logsでログを確認します。
ECSコンソールでクラスターを選択し、note-app-api-service をクリックします。「ログ」タブを開くと、コンテナの標準出力がCloudWatch Logsに記録されているのを確認できます。
ログにはFastAPIの起動メッセージや、APIへのリクエストのアクセスログが表示されています。先ほど curl でアクセスした /health や /notes へのリクエストが記録されていることを確認してください。

ログを確認すると、自分がアクセスした覚えのない /health へのリクエストが一定間隔で記録されていることに気づくかもしれません。これは、ALBが自動的に行っているヘルスチェックのリクエストです。ALBはターゲットグループに設定されたヘルスチェックパス(今回は /health)に対して定期的にリクエストを送り、タスクが正常に動作しているかを監視しています。タスクから正常なレスポンスが返らない場合、ALBはそのタスクへのトラフィック転送を自動的に停止します。
| 💡 ポイント |
|---|
| CloudWatch Logsは、ECS上のコンテナのトラブルシューティングに欠かせないツールです。タスクが起動に失敗した場合や、アプリケーションでエラーが発生した場合は、まずCloudWatch Logsを確認してください。実際には、エラーログを検知してSlackやメールに通知する仕組みを構築するのが一般的です。 |
10. オートスケーリングの動作確認
ECSサービスの作成時にオートスケーリングを設定しましたが、ここではタスク数を手動で変更して、スケールアウト(タスクの増加)の動作を実際に確認します。
ECSコンソールでサービスを選択し、「サービスを更新」をクリックします。

「必要なタスク」の値を 1 から 2 に変更して「更新」をクリックしてください。

しばらくすると、「タスク」タブに2つのタスクが表示されます。両方のタスクのステータスが「実行中」になれば、スケールアウトが完了です。

EC2コンソールでターゲットグループ note-app-api-tg を開き、「ターゲット」タブを確認してください。2つのターゲットが「healthy」として登録されていることがわかります。ALBは、これら2つのタスクにリクエストを自動的に分散します。

| 💡 ポイント |
|---|
| 今回はタスク数を手動で2に変更しましたが、ECSサービスの作成時に設定したオートスケーリングにより、CPU使用率が70%を超えた場合は自動的にタスクが追加されます。逆に負荷が下がればタスクは自動的に削減されます。 また、「必要なタスク」を 0 に変更するとすべてのタスクが停止し、ALBにアクセスしても「503 Service Unavailable」が返るようになります。メンテナンス時にタスクを一時的に停止させたい場合などに利用できます。 |