アプリケーション層の構築

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」が返るようになります。メンテナンス時にタスクを一時的に停止させたい場合などに利用できます。