自己改善の果て

【DOP-C02】buildspec.ymlとappspec.yml

執筆者:

sattva

カテゴリ:

, ,

はじめに

AWS CI/CDパイプラインにおいて、buildspec.ymlとAppSpec.yml（あるいはAppSpec.json）という2つのファイルが登場します。

この記事では、それぞれの概要とサンプルについて提示します。

buildspec.ymlとAppSpec.ymlの概要と役割の違い

buildspec.yml

buildspec（通常は buildspec.yml）は、AWS CodeBuild で実行されるビルド処理の手順や環境設定を定義するファイルです。

主な役割:

  • ソースコードのコンパイル
  • ユニットテストの実行
  • Dockerイメージの作成（ビルド）
  • Amazon ECR へのイメージのプッシュ
  • 成果物（アーティファクト）のパッケージング

appspec.yml

appspec.ymlは、AWS CodeDeploy がアプリケーションのリビジョンをターゲット環境にデプロイする際の手順を制御するファイルです。

主な役割

  • 環境（EC2, lambda, ECSなど）へのアプリケーションの配置
  • 切り替え
  • 検証

buildspec.ymlとappspec.ymlのサンプル

buildspec.yml

主なセクションの書式

セクション名内容
versionbuildspec の構文バージョンを指定します。
※ 機能拡張がなされている 0.2 の利用が推奨されています
envビルド環境で利用する環境変数を定義します。

※ プレーンテキストの変数はvariables
Parameter Store や Secrets Manager の値はそれぞれの専用サブキーで取得します
phasesCodeBuild が実行するビルドフェーズを定義する最重要セクションです。
※ 詳細なフェーズについては別表に記載します。
artifactsビルド後に生成され、S3 や後続のデプロイステージへ引き渡す成果物ファイルの格納パス（files）を指定します。
phasesセクションの書式
サブセクション名説明
installツールのインストール
pre_buildビルド前処理・ログイン等
buildメインビルド・コンパイル
post_buildビルド後処理・イメージプッシュ等

サンプル

Amazon ECR への Docker イメージのビルド＆プッシュ、および Amazon ECS デプロイに必要な imagedefinitions.json を生成するサンプルコードです

# versionセクション
version: 0.2

# envセクション
env:
  variables:
    # プレーンテキストの環境変数を指定
    AWS_DEFAULT_REGION: "ap-northeast-1"
    IMAGE_REPO_NAME: "my-web-app"

# phasesセクション
phases:
  # 1. install フェーズ: 依存パッケージやビルドツールのセットアップ   install:
    commands:
      - echo "インフラ・ビルドツールの初期化処理を開始します..."

  # 2. pre_build フェーズ: ビルド実行前の準備作業（例: ECRへのログインなど）
  pre_build:
    commands:
      - echo "Amazon ECR 認証トークンの取得とログインを実行中..." 
      # AWS CLI を使用して ECR ログイン用パスワードを取得し docker login を実行
      - aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $ECR_REGISTRY

  # 3. build フェーズ: アプリケーションのコンパイルや Docker イメージのビルド
  build:
    commands:
      - echo "Docker イメージのビルドを開始..."
      # カレントディレクトリの Dockerfile からイメージをビルドし、タグを付与
      - docker build -t $ECR_REGISTRY/$IMAGE_REPO_NAME:$IMAGE_TAG .

  # 4. post_build フェーズ: ビルド後の処理（ECRへのプッシュや成果物ファイルの生成）
  post_build:
    commands:
      - echo "ビルドした Docker イメージを ECR にプッシュ中..." 
      - docker push $ECR_REGISTRY/$IMAGE_REPO_NAME:$IMAGE_TAG
      - echo "ECS デプロイに必要な imagedefinitions.json を作成中..." 
      # CodePipeline/CodeDeploy へ引き渡すイメージ定義 JSON ファイルを出力
      - printf '[{"name":"web-container","imageUri":"%s"}]' $ECR_REGISTRY/$IMAGE_REPO_NAME:$IMAGE_TAG > imagedefinitions.json

# 後続のデプロイステージへ引き渡すビルド成果物（アーティファクト）の定義
artifacts:
  files:
    # 生成された imagedefinitions.json を成果物として指定
    - imagedefinitions.json

appspec.yml

主なセクションの書式

セクション名内容
versionECS および Lambda デプロイの場合、バージョン番号には 0.0 を指定します。
Resorceデプロイ対象となる ECS サービスやタスク定義に関する情報を定義するセクションです。
※サブセクションについてへ別表に記載します。
Hook各ライフサイクルイベントにおいて呼び出す検証処理を定義するセクションです。
Resorceセクションの書式
サブセクション名説明
TargetServiceデプロイ対象のリソース種別（AWS::ECS::Service）を指定します。
Properties使用する ECS タスク定義の ARN（TaskDefinition）や、ロードバランサーとコンテナポートのマッピング情報を指定します。
Resorceセクションの書式
サブセクション名説明
TargetServiceデプロイ対象のリソース種別（AWS::ECS::Service）を指定します。
Properties使用する ECS タスク定義の ARN（TaskDefinition）や、ロードバランサーとコンテナポートのマッピング情報を指定します。

サンプル

Amazon ECR への Docker イメージのビルド＆プッシュ、および Amazon ECS デプロイに必要な imagedefinitions.json を生成するサンプルコードです

# versionセクション
version: 0.0

# Resourcesセクション
Resources:
    # ECSが対象サービス
  - TargetService:
      Type: AWS::ECS::Service
      Properties:
        # デプロイで使用する ECS タスク定義の ARN を指定
        TaskDefinition: "arn:aws:ecs:ap-northeast-1:123456789012:task-definition/my-app:1"
        # ロードバランサーがトラフィックを転送するコンテナ情報
        LoadBalancerInfo:
          # タスク定義内で設定されているコンテナ名を指定
          ContainerName: "web-container"
          # コンテナ側で解放されているポート番号を指定
          ContainerPort: 80

# Hooksセクション
Hooks:
  # 本番トラフィック切り替え完了後 (AfterAllowTraffic) に呼び出す Lambda 関数の ARN を指定
  - AfterAllowTraffic: "arn:aws:lambda:ap-northeast-1:123456789012:function:AfterAllowTrafficValidation"

投稿をさらに読み込む