自動ビルドとデプロイ

OIDC接続の準備が整ったので、いよいよGitHub Actionsを使った自動ビルドと自動デプロイのワークフローを構築していきます。

手動でデプロイを行う場合、Pull Requestをマージしたあとに「コンテナイメージの作成」「ECRへのプッシュ」「ECSへのデプロイ」といった作業を開発者が実行する必要があります。これらの一連の作業を自動化することで、mainブランチにマージしただけで本番環境に反映されるという、真のCI/CDパイプラインが完成します。

自動ビルドと自動デプロイは別のジョブとして定義することもできますが、今回は同一のジョブで実行する流れとします。別々のジョブにすると、ジョブ間でビルドしたイメージの情報を受け渡す必要があり、複雑になるためです。

1. 作業用ブランチの作成

ワークフローファイルを追加する前に、作業用のブランチを作成します。ブランチを分けずにmainブランチに直接コミットしてしまうと、「Pull Requestを作成してマージする」という実務的な流れを体験できません。CI/CDパイプラインは「レビュー後のマージ」をトリガーにデプロイする前提で組むため、ここでしっかりと作業用ブランチを分けておきましょう。

Visual Studio Codeでdevopscamp-cicd-handsonフォルダを開いたうえで、ターミナルを開きます。以下のgit switchコマンドで、feature/add-cicd-pipelineというブランチを作ります。-cオプションは新しいブランチを作成して切り替えるという意味です。

git switch -c feature/add-cicd-pipeline

Switched to a new branch 'feature/add-cicd-pipeline'と表示されていれば、ここまでの操作は完了です。

2. 自動ビルド&デプロイの流れ

自動ビルドとデプロイの流れを説明します。FastAPIで作成したAPIをコンテナ化し、Amazon ECSにデプロイするまでの流れを自動化しています。

トリガーはmainブランチへのPushです。これは、直接Pushした場合だけでなく、Pull RequestのマージによるPushにも対応しています。

処理の流れは以下のとおりです。

  1. GitHub Actionsでソースコードをチェックアウトする
  2. 先ほど作成したOIDCの仕組みを使って、AWSへの認証を行う
  3. Amazon ECRへログインする
  4. ソースコードからコンテナイメージを作成し、ECRにPushする(自動ビルド)
  5. タスク定義ファイルのプレースホルダをシークレット値で置換する
  6. 置換済みタスク定義を元に、Amazon ECSへデプロイする(自動デプロイ)

これらの一連の流れを、GitHub Actionsのワークフローとして設定します。

3. ワークフローの作成

まず、ワークフローファイルを作成して全体の流れを定義します。

3.1 ファイルの作成

ビルドとデプロイの処理は、mainブランチへのマージ(Push)時に動作するワークフローとして構築します。GitHub Actionsは.github/workflowsフォルダ配下のYAMLファイルをワークフローとして自動的に認識するため、このルールに沿ってファイルを配置します。今回はdeploy.ymlというファイル名で作成します。

devopscamp-cicd-handson/
└── .github/
    └── workflows/
        └── deploy.yml  ← このファイルを作成

作成したファイルに以下の内容を記述して保存します。

name: Build and Deploy to ECS

on:
  push:
    branches:
      - main  # mainブランチへのpushをトリガーに実行

permissions:
  id-token: write  # OIDCトークン発行に必要
  contents: read   # リポジトリ内容を取得するために必要

env:
  AWS_REGION: ap-northeast-1
  ECR_REPOSITORY: test-repository   # ECRリポジトリ名
  ECS_CLUSTER: test-cluster         # ECSクラスター名
  ECS_SERVICE: test-service         # ECSサービス名

jobs:
  build-and-deploy:
    name: Build and Deploy
    runs-on: ubuntu-latest

    steps:
      # ソースコードをチェックアウト
      - name: Checkout source
        uses: actions/checkout@v5

      # AWS認証情報を設定 (OIDCを利用)
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v5
        with:
          role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/github-actions-deploy-role
          aws-region: ${{ env.AWS_REGION }}

      # ECRへログイン
      - name: Login to Amazon ECR
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v2

      # Dockerイメージをビルド&プッシュ
      - name: Build and Push Docker image
        run: |
          IMAGE_REPO=${{ steps.login-ecr.outputs.registry }}/${{ env.ECR_REPOSITORY }}
          docker build -t $IMAGE_REPO:latest .
          docker push $IMAGE_REPO:latest

      # タスク定義のプレースホルダをシークレットの値で置換
      - name: Render task definition
        run: |
          sed -i "s|<AWS_ACCOUNT_ID>|${{ secrets.AWS_ACCOUNT_ID }}|g" ecs-taskdef.json

      # ECSへデプロイ
      - name: Deploy to ECS
        uses: aws-actions/amazon-ecs-deploy-task-definition@v2
        with:
          task-definition: ecs-taskdef.json
          service: ${{ env.ECS_SERVICE }}
          cluster: ${{ env.ECS_CLUSTER }}
          wait-for-service-stability: true

4. ワークフローの説明

ワークフローの説明を行います。

4.1 名称

name: Build and Deploy to ECS

ワークフローの名称として、Build and Deploy to ECSという名前をつけています。

4.2 トリガー

on:
  push:
    branches:
      - main

トリガーとして、mainブランチに対してコードが変更された時に起動するように設定しています。

permissions:
  id-token: write  # OIDCトークン発行に必要
  contents: read   # リポジトリ内容を取得するために必要

Permissionsにより、GitHubが操作を行う上での権限を設定します。

id-token: writeは、GitHub Actions が OIDCトークンを発行するための権限です。今回はOIDCトークンを利用してAWSへアクセスするため、この権限が必要になります。

contents: readは、リポジトリのコードを読み取るための権限です。actions/checkoutがソースを取得するのに必要となります。

4.3 ジョブ

jobs:
  build-and-deploy:
    name: Build and Deploy
    runs-on: ubuntu-latest

ジョブとして、build-and-deployというジョブを定義しています。名前にBuild and Deploy、ランナーとしてubuntu-latestを指定しているため、ubuntuの最新のランナー環境で動作します。

4.4 ステップ1:コードをチェックアウト

- name: Checkout source
  uses: actions/checkout@v5

mainブランチへのpushをトリガーとして実行されるため、このステップではmainブランチの最新のコードがチェックアウトされます。

actions/checkout

4.5 ステップ2:AWS認証情報を設定

- name: Configure AWS credentials
  uses: aws-actions/configure-aws-credentials@v5
  with:
    role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/github-actions-deploy-role
    aws-region: ${{ env.AWS_REGION }}

aws-actions/configure-aws-credentialsは、AWSにログインするための認証情報を設定するアクションです。role-to-assumeにはAWSに接続するときに使用するIAMロールを、aws-regionには操作対象のリージョンを指定します。

aws-actions/configure-aws-credentials

4.6 ステップ3:ECRへのログイン

- name: Login to Amazon ECR
  id: login-ecr
  uses: aws-actions/amazon-ecr-login@v2

aws-actions/amazon-ecr-loginで ECR へのログインを行います。このアクションを使うためには、事前にステップ2でAWSの認証情報を設定しておく必要があります。

aws-actions/amazon-ecr-login

ECRへの認証は、内部的には認可トークンを取得して docker login に渡す仕組みになっています。Private registry authentication in Amazon ECR(AWS公式ドキュメント)の原文(英語表示時)では以下のように述べられています。

An authentication token is used to access any Amazon ECR registry that your IAM principal has access to and is valid for 12 hours.

「認可トークンはIAMプリンシパルがアクセスできる任意のECRレジストリに対して有効で、12時間で失効する」と読み取れます。aws-actions/amazon-ecr-login はこのトークン取得と docker login を裏側でまとめて実行してくれるアクションです。なお、AWSドキュメントは画面右上の言語セレクタから日本語表示に切り替えられます。

4.7 ステップ4:Dockerイメージをビルド&プッシュ

- name: Build and Push Docker image
  run: |
    IMAGE_REPO=${{ steps.login-ecr.outputs.registry }}/${{ env.ECR_REPOSITORY }}
    docker build -t $IMAGE_REPO:latest .
    docker push $IMAGE_REPO:latest

Dockerコマンドを使って、イメージのビルドとプッシュを行います。docker build -t $IMAGE_REPO:latest .は、カレントディレクトリにあるDockerfileを使ってDockerイメージを作成するコマンドです。今回はFastAPIのコードがリポジトリのルート直下に配置されているため、ビルドコンテキストとして.(カレントディレクトリ)を指定しています。

docker pushは、作成したイメージをECRのリポジトリにアップロードするコマンドです。

4.8 ステップ5:タスク定義のプレースホルダを置換

- name: Render task definition
  run: |
    sed -i "s|<AWS_ACCOUNT_ID>|${{ secrets.AWS_ACCOUNT_ID }}|g" ecs-taskdef.json

このステップで登場するecs-taskdef.jsonは、ECSにデプロイするコンテナの設定を記述したタスク定義ファイルです。次のセクション「タスク定義ファイルの作成」で作成するため、ここではワークフロー側の説明のみを進めます。

ecs-taskdef.jsonに書かれた<AWS_ACCOUNT_ID>というプレースホルダを、GitHubシークレットに登録したAWSアカウントIDの値で置換します。これによりリポジトリには常にプレースホルダだけが残り、アカウントIDが直接コミットされない状態を保てます。

sed -iはファイルを直接書き換えるオプションで、s|置換前|置換後|gという構文で全出現箇所を一括置換します。

4.9 ステップ6:ECSにデプロイ

- name: Deploy to ECS
  uses: aws-actions/amazon-ecs-deploy-task-definition@v2
  with:
    task-definition: ecs-taskdef.json
    service: ${{ env.ECS_SERVICE }}
    cluster: ${{ env.ECS_CLUSTER }}
    wait-for-service-stability: true

aws-actions/amazon-ecs-deploy-task-definitionで ECS へのデプロイを行います。task-definitionには直前のステップで置換済みのecs-taskdef.jsonを、serviceとclusterには対象のECSサービス名とクラスタ名を指定します。

wait-for-service-stability: trueを指定すると、デプロイ後に新しいタスクが正常に稼働し、サービスが安定状態になるまで待機します。これを指定しないと、タスクが起動しきっていない状態でワークフローが終了してしまい、不具合に気づきにくくなる可能性があります。

5. タスク定義ファイルの作成

ワークフローのステップ6でtask-definition: ecs-taskdef.jsonを参照していました。このファイルは、ECSに対して「どのようなコンテナを・どのようなリソース設定で動かすのか」を伝えるためのタスク定義ファイルです。ワークフロー実行時にこのファイルを読み込み、新しいタスク定義をECSに登録してサービスを更新します。

リポジトリのルート(devopscamp-cicd-handson/直下)にecs-taskdef.jsonというファイルを作成します。

devopscamp-cicd-handson/
├── ecs-taskdef.json  ← このファイルを作成
├── Dockerfile
├── main.py
└── ...

作成したファイルに以下の内容をそのまま記述して保存します。<AWS_ACCOUNT_ID>はプレースホルダで、ワークフロー実行時にGitHubシークレットの値で自動置換するため、ここではそのままで構いません。

{
  "family": "test-task",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "executionRoleArn": "arn:aws:iam::<AWS_ACCOUNT_ID>:role/ecsTaskExecutionRole-cicd-handson",
  "containerDefinitions": [
    {
      "name": "app",
      "image": "<AWS_ACCOUNT_ID>.dkr.ecr.ap-northeast-1.amazonaws.com/test-repository:latest",
      "portMappings": [
        {
          "containerPort": 8000,
          "protocol": "tcp"
        }
      ],
      "essential": true,
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/test-task",
          "awslogs-region": "ap-northeast-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

コードを解説します。

項目 説明
family タスク定義の名前。CloudFormationで作成したタスク定義と同じtest-taskを指定
networkMode Fargateではawsvpcを指定する必要がある
requiresCompatibilities FARGATEを指定してFargate互換のタスク定義にする
cpu, memory タスクのCPU・メモリサイズ
executionRoleArn ECSタスクがCloudWatch Logsへの書き込みなどを行うために必要なロール
containerDefinitions.image ECRにPushされたイメージのURI
containerDefinitions.portMappings コンテナが公開するポート(FastAPIはデフォルトで8000)
containerDefinitions.logConfiguration ログをCloudWatch Logsに送る設定

networkMode: awsvpc がFargateで必須である点は、Amazon ECS task definition parameters for Fargate(AWS公式ドキュメント)に明記されています。原文(英語表示時)では以下のように述べられています。

For Amazon ECS tasks hosted on Fargate, the awsvpc network mode is required.

「Fargate上のECSタスクでは awsvpc ネットワークモードが必須である」と読み取れます。各パラメータの取りうる値や cpu / memory の組み合わせ表も同ページにまとまっています。なお、AWSドキュメントは画面右上の言語セレクタから日本語表示に切り替えられます。

💡 ポイント
imageは:latestを指定していますが、GitHub Actionsのワークフロー実行時に、この:latestタグのイメージがECRに最新のイメージとしてPushされた状態で、ECSに新しいタスク定義として登録されます。つまり、デプロイのたびに常に最新のイメージが使われる仕組みです。
💡 ポイント
アカウントIDをこのJSONに直接書いてしまうと、GitHubシークレットに登録した意味がなくなります(リポジトリにそのまま残るため)。そこで本章では<AWS_ACCOUNT_ID>というプレースホルダで書いておき、ワークフロー実行時にシークレットの値で置換してから使用します。置換は次の見出しで追加するsedコマンドのステップで行います。

AWSアカウントIDは厳密には機密情報ではありません(AWS公式も「秘密ではない」と明言)。ただし一度シークレットで扱うと決めたなら、成果物にもハードコードしないのが一貫性ある設計です。この考え方は、今後他の準機密情報(リージョン依存のリソースIDなど)を扱う際にも応用できます。

6. 実行してみる

ワークフローの作成が完了しましたので、実際にデプロイが動くかを確認します。今回のワークフローはmainブランチへのPushで起動するため、作業ブランチ(feature/add-cicd-pipeline)の内容をPull Requestでマージすれば、mainブランチへの変更が発生してデプロイが自動実行されます。

6.1 GitHubにPushする

まず、作業ブランチで行った変更(ecs-taskdef.jsonとdeploy.ymlの追加)をGitHubにPushします。Visual Studio Codeのターミナルで、以下のコマンドを1つずつ実行します。

ステージングします。

git add .

コミットします。

git commit -m "add deploy workflow"

Pushします。

git push origin feature/add-cicd-pipeline

GitHubのリポジトリページを開いて、Pushしたファイルが反映されていることを確認します。

6.2 Pull Requestの作成

Pushが完了したので、feature/add-cicd-pipelineブランチからmainブランチに対してPull Requestを作成します。ビルドとデプロイのワークフローはmainブランチへのマージをトリガーとして実行されるため、まずPull Requestを作成し、そこからマージする流れを取ります。

GitHubのリポジトリページで、Pull requestsタブをクリックします。

New pull requestのボタンをクリックします。

ブランチとして、左側のbaseにmain、右側のcompareにfeature/add-cicd-pipelineを選択した上で、Create pull requestをクリックします。

タイトルと説明欄はそのままで問題ありません。さらにCreate pull requestをクリックすると、Pull Requestが作成されます。

6.3 Pull Requestのマージ

Pull Requestが作成できたら、そのままマージします。ビルドとデプロイのワークフローはマージをトリガーとして実行されるため、ここでマージすることで初めてデプロイが動き出します。

Pull Requestの画面で、Merge pull requestのボタンをクリックします。

続いて、確認画面でConfirm mergeボタンをクリックすると、マージが行われます。

マージが完了すると、mainブランチに対してPushが発生したことになり、Build and Deploy to ECSワークフローが自動的に起動します。GitHubのActionsタブを開くと、ワークフローの実行状況を確認できます。

しばらくするとデプロイのワークフローが正常終了します。

⚠️ 「Could not assume role with OIDC: Not authorized to perform sts:AssumeRoleWithWebIdentity」エラーが出る場合
GitHub Actionsから発行されるOIDCトークンの sub 値と、IAMロールの信頼ポリシーが期待する sub 値がマッチしていない可能性があります。

特に、GitHub側で OIDC の subject claim customization が有効になっているアカウントでは、sub が repo:<owner>@<owner_id>/<repo>@<repo_id>:ref:refs/heads/main の形式(owner名・repo名の直後に @<数字> が挟まる)で発行されることがあり、教材通りの信頼ポリシーとはマッチしません。

切り分けとして、AWSコンソールの CloudTrail → イベント履歴 で イベント名 AssumeRoleWithWebIdentity を検索し、直近の失敗イベントを開きます。ユーザ名 の欄に、実際に発行されている sub 値が表示されます。

対処としては、IAMロール github-actions-deploy-role の 信頼関係 タブから、token.actions.githubusercontent.com:sub の条件を、CloudTrailで確認した実際の sub 値に合わせて書き換えて保存します。書き換え後、失敗したワークフロー右上の Re-run failed jobs から再実行すると通ります。

7. リソースの確認

ワークフローが正常終了したので、実際にAWS側にデプロイの結果が反映されているかを確認します。ワークフローが「成功」と表示されていても、何らかの理由で想定どおりにリソースが更新されていない可能性もあるため、AWSコンソールで直接確認しておくことが重要です。

まずは、ECRのリポジトリに、新しいイメージが作成されていることを確認します。イメージタグがlatestとなっているイメージが作成されていて、プッシュされた日時が、先ほどマージしたタイミングと同じであれば問題ありません。

続いて、ECSへのデプロイが行われていることを確認します。

ECSのクラスターからtest-serviceを選択し、デプロイタブを開くと、新しいリビジョンでのデプロイが完了していることが確認できます。

8. タスクの起動(DesiredCountの変更)

ECSサービスにはデプロイは反映されましたが、実はまだタスクは起動していません。CloudFormationで作成した時点でDesiredCount(実行するタスク数)を0に設定していたためです。

DesiredCountを最初から1にしなかった理由は、初回のCloudFormationスタック作成時にはECRリポジトリにイメージがまだ存在しないため、ECSがタスクを起動しようとしても失敗を繰り返してしまうためです。CI/CDパイプラインで初回のデプロイが完了し、ECRにイメージがPushされた今のタイミングで、手動でタスク数を1に変更します。

ECSのクラスターtest-clusterのサービスタブで、test-serviceを選択し、更新ボタンをクリックします。

サービス更新画面で、以下の設定を行います。

設定項目 値 設定の基準
必要なタスク 1 タスクを1つ起動させるため

その他の項目はデフォルトのままで、更新をクリックします。

数十秒〜1分程度で、新しいタスクが起動します。ECSのクラスターtest-clusterのタスクタブを開くと、タスクが1件起動していれば、ここまでの操作は完了です。

9. 動作確認

ECS側でタスクが起動したことを確認できたら、実際にAPIを呼び出して「本当に正常に動作しているか」を確かめます。デプロイが完了してもアプリケーション側のバグや設定ミスで動作していないケースもあるため、最後にAPIを叩いて期待通りのレスポンスが返ってくることを確認するのがベストプラクティスです。

今回はECSタスクをパブリックサブネットに配置しているため、ECSタスクのパブリックIPアドレスを使ってAPIを呼び出します。

まずは、タスクの詳細を開きます。

その後、ネットワーキングのタブを開き、パブリックIPをコピーします。

Windowsであればコマンドプロンプト、Macであればターミナルを開き、CURLコマンドでAPIのヘルスチェックエンドポイントを呼び出してみます。

curl http://<パブリックIP>:8000/health

以下のようにヘルスチェックのレスポンスが返ってくれば、コンテナが起動していることが確認できます。

{"status":"ok"}

続いて、動作確認用のエンドポイントも呼び出してみます。

curl http://<パブリックIP>:8000/

以下のようにメッセージのレスポンスが返ってくれば、アプリケーションが正常に動作しています。

{"message":"API呼び出しテストに成功しました"}

{"status":"ok"}と{"message":"API呼び出しテストに成功しました"}の両方が表示されていれば、ここまでの操作は完了です。

10. 更新してみる

初回デプロイは成功しましたが、CI/CDパイプラインの本当の価値は「繰り返し使えること」にあります。コードを変更するたびに自動でビルド・デプロイされ、常に最新のコードが本番環境に反映されることを体験するために、APIのレスポンスメッセージを少し変更してから再度デプロイしてみます。

10.1 コードの変更

main.pyのファイルを開き、root関数のレスポンスメッセージに(ver2)を追加します。

@app.get("/")
def root():
    return {"message": "API呼び出しテストに成功しました(ver2)"}

その後、変更をGitコマンドでGitHubにプッシュします。

まず、前回の作業ブランチ(feature/add-cicd-pipeline)からmainブランチに切り替え、最新のmainの状態をローカルに取り込みます。

git switch main
git pull origin main

続いて、今回の変更用に新しいブランチを作成します。

git switch -c feature/update-message

変更をステージングしてコミットします。

git add .
git commit -m "update message to ver2"

Pushします。

git push origin feature/update-message

10.2 マージ

続いて、GitHubの画面にてPull Requestを作成し、マージを行います。マージを行うと、GitHub Actionsのワークフローが正常終了することを確認します。

10.3 動作確認

CURLコマンドを実行して、変更の反映を確認します。なお、デプロイすることでECSタスクが新しくなるため、パブリックIPアドレスは変更されているのでご注意ください。

curl http://<パブリックIP>:8000/

実行結果のメッセージに(ver2)が含まれていればOKです。

{"message":"API呼び出しテストに成功しました(ver2)"}

レスポンスに(ver2)が含まれていれば、コードの変更が自動デプロイを通じて正しく反映されていることが確認できます。コードを書き換えてPushするだけで本番環境が更新されることが確認できました。これがCI/CDパイプラインの最大のメリットです。