とある日

最近ずっとCodebuildを触っています。

ですが、buildspec.ymlについての知識が記事があまりなかったので自分の理解を深めるためにもまとめます。

Codebuildとは

CodeBuild はソースコードをコンパイルし、単体テストを実行して、すぐにデプロイできるアーティファクトを生成します。CodeBuild では自分のビルドサーバーをプロビジョニング、管理、スケールする必要がありません。Apache Maven、Gradle などの一般的なプログラミング言語とビルドツール用のパッケージ済みのビルド環境を提供します。ビルド環境をカスタマイズして、CodeBuild で独自のビルドツールを使用することもできます。CodeBuild はピーク時のビルドリクエストに合わせて自動的にスケーリングします。

AWSでCI/CDを構築する際に使用することが多いと思います。

buildspec.yaml

ビルド仕様ファイルのことを指します。

Codebuildがどのようにビルドを行うかを記述したファイルです。

buildspec をソースコードの一部として含めることも、ビルドプロジェクトの作成時に buildspec を定義することもできます。

↓例

version: 0.2

phases:
  install:
    runtime-versions:
      java: corretto11
  pre_build:
    commands:
      - echo Nothing to do in the pre_build phase...
  build:
    commands:
      - echo Build started on `date`
      - mvn install
  post_build:
    commands:
      - echo Build completed on `date`
artifacts:
  files:
    - target/messageUtil-1.0.jar

buildspec.yaml

下記の９つの項目について記述していきます。

なお、後述しますが、buildspecのバージョンは0.2について記述します。

0.1の場合には適用されていない項目もあるので気をつけてください。

version

version: 0.2

buildspecのバージョンを指します。

現状（2021年10月3日）はこの2つのバージョンのみです。

必要なマッピング。buildspec のバージョンを表します。0.2 を使用することをお勧めします。

注記

バージョン 0.1 も引き続きサポートされていますが、可能な場合はバージョン 0.2 を使用することをお勧めします。詳細については、「buildspec のバージョン」を参照してください。

buildspec のバージョン

0.2では下記が追加されています。

environment_variables が env に名称変更されました。
plaintext が variables に名称変更されました。
artifacts の type プロパティは廃止されました。
バージョン 0.1 では、AWS CodeBuild はビルド環境のデフォルトシェルの個別のインスタンスで各ビルドコマンドを実行します。バージョン 0.2 では、CodeBuild はビルド環境のデフォルトシェルの同じインスタンスですべてのビルドコマンドを実行します。

run-as

run-as: Linux-user-name

この buildspec ファイルでコマンドを実行する Linux ユーザーを指定します。

これを指定しない場合はrootユーザが適用されます。

env

env:
  shell: shell-tag
  variables:
    key: "value"
    key: "value"
  parameter-store:
    key: "value"
    key: "value"
  exported-variables:
    - variable
    - variable
  secrets-manager:
    key: secret-id:json-key:version-stage:version-id
  git-credential-helper: no | yes

オプションのシーケンス。

環境変数を設定します。

DBに接続する場合のユーザとパスワードだったり、RDSのエンドポイントを設定したりします。

Terrafromで作成する場合は、buildspecに含めなくても環境変数を設定できます。

自分は、Terrafromで設定します。

Resource: aws_codebuild_project

  environment {
    compute_type                = "BUILD_GENERAL1_SMALL"
    image                       = "aws/codebuild/standard:1.0"
    type                        = "LINUX_CONTAINER"
    image_pull_credentials_type = "CODEBUILD"

    environment_variable {
      name  = "SOME_KEY1"
      value = "SOME_VALUE1"
    }

    environment_variable {
      name  = "SOME_KEY2"
      value = "SOME_VALUE2"
      type  = "PARAMETER_STORE"
    }
  }

env/shell

オプションのシーケンス。Linux または Windows オペレーティングシステムでサポートされるシェルを指定します。

Linux
- bash
- /bin/sh
Windows
- powershell.exe
- cmd.exe

env/variables

env を指定し、プレーンテキストでカスタム環境変数を定義する場合は必須です。

env/parameter-store

Amazon EC2 Systems Manager パラメータストアに保存されているカスタム環境変数を取得する場合は必須です。

env/exported-variables

エクスポートする環境変数をリストするために使用します。

Codebuild内で使用できる環境変数を指定するために使うみたいです。

env/secrets-manager

AWS Secrets Manager に保存されているカスタム環境変数を取得する場合は必須です。

env/git-credential-helper

CodeBuild が Git 認証情報ヘルパーを使用して Git 認証情報を提供するかどうかを示すために使用されます。

proxy

proxy:
  upload-artifacts: no | yes
  logs: no | yes

明示的なプロキシサーバーでビルドを実行する場合、設定を表すために使用されます。

upload-artifacts

明示的なプロキシサーバーのビルドでアーティファクトをアップロードする場合は、yes に設定します。デフォルト: no。

logs

明示的なプロキシサーバーでビルドし、CloudWatch logs ログを作成するには、yes に設定します。デフォルト: no。

batch

batch:
  fast-fail: false | true
  # build-list:
  # build-matrix:
  # build-graph:

オプションのマッピング。プロジェクトのバッチビルド設定。

build-list

ビルドリストは、並行して実行されるタスクの数を定義するために使用されます。

build-matrix

ビルドマトリックスは、並行して実行される異なる構成のタスクを定義します。

build-graph

ビルドグラフを定義。ビルドグラフは、バッチ内の他のタスクに依存する一連のタスクを定義します。

phases

phases:
  install:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    runtime-versions:
      runtime: version
      runtime: version
    commands:
      - command
      - command
    finally:
      - command
      - command
  pre_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
  build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
  post_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command

必要なシーケンス。ビルドの各段階で CodeBuild が実行するコマンドを表します。

phases/*/run-as

のコマンドを実行する Linux ユーザーを指定します。buildspec ファイルの上ですべてのコマンドに対して run-as もグローバルに指定されている場合、フェーズレベルのユーザーが優先されます。

phases/*/on-failure

フェーズ中に障害が発生した場合に実行するアクションを指定します。これには、次のいずれかの値を指定できます。

ABORT - ビルドを中止します。
CONTINUE - 次のステップに進みます。

コマンドが実行失敗した場合処理が終了するのでそれに対する処理を追記できます。

phases/*/finally

finally ブロックに指定されたコマンドは、commands ブロックのコマンドが実行された後で実行されます。finally ブロックに指定されたコマンドは、commands ブロックのコマンドが失敗した場合でも実行されます。

順序を保証したい場合とかに使うと思います。

phases/install

インストール時に CodeBuild が実行するコマンドがある場合は、そのコマンドを表します。install フェーズは、ビルド環境でのパッケージのインストールにのみ使用することをお勧めします。

使用するパッケージとかをインストールするコマンドをここで定義します。

phases/install/runtime-versions

指定した場合、少なくとも 1 つのランタイムをこのセクションに含める必要があります。ランタイムを指定するために特定のバージョンを使用するか、メジャーバージョンに続けて .x を指定して CodeBuild がこのメジャーバージョンと最新マイナーバージョンを使用することを指定するか、latest を指定して最新メジャーバージョンとマイナーバージョン (java: openjdk11、ruby: 2.6、nodejs: 12.x、java: latest など) を使用します。

phases:
  install:
    runtime-versions:
      java: corretto8
      python: 3.x
      ruby: "$MY_RUBY_VAR"

プログラムのバージョンを指定する場合に使用する。

phases/install/commands

コマンドを指定します。

CodeBuild は、最初から最後まで、各コマンドを一度に 1 つずつ、指定された順序で実行します。

phases/pre_build

ビルドの前に CodeBuild が実行するコマンドがあれば、それを表します。

たとえば、このフェーズを使用して Amazon ECR にサインインするか、npm の依存関係をインストールすることができます。

phases/pre_build/commands

ビルドの前に CodeBuild が実行する単一のコマンドを表します。

phases/build

ビルド中に CodeBuild が実行するコマンドがあれば、それを表します。

phases/build/commands

build が指定されている場合は必須です。一連のスカラーが含まれ、各スカラーは、ビルド中に CodeBuild が実行する単一のコマンドを表します。

reports

reports:
  report-group-name-or-arn:
    files:
      - location
      - location
    base-directory: location
    discard-paths: no | yes
    file-format: report-format

hack.nikkei.com

参考になりそうな記事をおいておきます。

report-group-name-or-arn

レポートの送信先のレポートグループを指定します。

Codebuildではテストレポートの作成が行なえます、それに対する定義を行います。

reports/<report-group>/files

必要なシーケンス。レポートによって生成されたテスト結果の生データを含む場所を表します。

reports/<report-group>/file-format

レポートファイル形式を表します。指定しない場合は、JUNITXML を使用します。

reports/<report-group>/base-directory

CodeBuild が生のテストファイルを見つける場所を決定するために使用する元のビルド場所に対する相対的な 1 つ以上のトップレベルディレクトリを表します。

reports/<report-group>/discard-paths

これが指定されていない場合、または no を含む場合、レポートファイルはディレクトリ構造のまま出力されます。

artifacts

artifacts:
  files:
    - location
    - location
  name: artifact-name
  discard-paths: no | yes
  base-directory: location
  exclude-paths: excluded paths
  enable-symlinks: no | yes
  s3-prefix: prefix
  secondary-artifacts:
    artifactIdentifier:
      files:
        - location
        - location
      name: secondary-artifact-name
      discard-paths: no | yes
      base-directory: location
    artifactIdentifier:
      files:
        - location
        - location
      discard-paths: no | yes
      base-directory: location

CodeBuild がビルド出力を見つけることができる場所に関する情報、CodeBuild が S3 出力バケットへのアップロード用にその出力を準備する方法に関する情報を表します。

www.hacknotes.jp

参考になりそうな記事をおいておきます。

CodeBuild内で実施したテスト結果や環境構築した後のソースコードなどもこれなら出力できます。

artifacts/files

ビルド環境でのビルド出力アーティファクトを含む場所を表します。

artifacts/name

ビルドアーティファクトの名前を指定します。

artifacts/discard-paths

ビルドアーティファクトのディレクトリが出力でフラット化されるかどうかを指定します。

artifacts/base-directory

CodeBuild がビルド出力アーティファクトに含めるファイルとサブディレクトリを決定するために使用する、元のビルドの場所を基準とした、1 つ以上の最上位ディレクトリを表します。

artifacts/exclude-paths

base-directory に相対的な 1 つまたは複数のパスを表します。

artifacts/enable-symlinks

出力タイプが「ZIP」の場合、内部シンボリックリンクを ZIP ファイルに保持するかどうかを指定します。これに「yes」が含まれる場合、ソース内のすべての内部シンボリックリンクがアーティファクト ZIP ファイルに保持されます。

artifacts/s3-prefix

アーティファクトが Amazon S3 バケットに出力され、名前空間タイプが「BUILD_ID」の場合に使用されるプレフィックス。使用した場合、バケット内の出力パスは「<s3-prefix>/<build-id>/<name>.zip」となります。

artifacts/secondary-artifacts

アーティファクト識別子とアーティファクト定義との間のマッピングとしての 1 つ以上のアーティファクト定義を表します。

cache

cache:
  paths:
    - path
    - path

CodeBuild が S3 キャッシュバケットへのキャッシュのアップロード用にファイルを準備できる場所に関する情報を表します。

AWS CodeBuild でのキャッシュのビルド

Codebuildでキャッシュを利用することができます、キャッシュを使用すると、プロジェクトを構築する時間を短縮できます。

cache/paths

キャッシュの場所を表します。

〆

AWSマネージメントコンソールでも指定できると思いますが、buildspecで指定するほうが一元管理できますし、再現性があるので便利かなと思います。

phases:のinstall区分をしなくても実行できるのでしっかりとわけるのが大変そうですね。

目次

とある日

buildspec.yaml

buildspec のバージョン

env/shell

env/variables

env/parameter-store

env/exported-variables

env/secrets-manager

env/git-credential-helper

upload-artifacts

logs

build-list

build-matrix

build-graph

phases/*/run-as

phases/*/on-failure

phases/*/finally

phases/install

phases/install/runtime-versions

phases/install/commands

phases/pre_build

phases/pre_build/commands

phases/build

phases/build/commands

report-group-name-or-arn

reports/<report-group>/files

reports/<report-group>/file-format

reports/<report-group>/base-directory

reports/<report-group>/discard-paths

artifacts/files

artifacts/name

artifacts/discard-paths

artifacts/base-directory

artifacts/exclude-paths

artifacts/enable-symlinks

artifacts/s3-prefix

artifacts/secondary-artifacts

cache/paths

〆