AWS CodeBuild のトラブルシューティング

このトピックの情報を使用して、問題を特定、診断、対処します。CodeBuild のビルドのログ記録とモニタリングを行い、問題のトラブルシューティングを行う方法については、「ログ記録とモニタリング」を参照してください。

Apache Maven が間違ったリポジトリのアーティファクトを参照している

問題:AWS CodeBuild が提供する Java ビルド環境で Maven を使用すると、Maven はビルドおよびプラグイン依存関係を Maven の安全な中央リポジトリ (https://repo1.maven.org/maven2) から取得します。これは、ビルドプロジェクトの pom.xml ファイルが別の場所を使用すると明示的に宣言した場合でも発生します。

考えられる原因: settings.xmlCodeBuild が提供する Java ビルド環境には、ビルド環境の /root/.m2 ディレクトリに事前にインストールされている という名前のファイルが含まれています。この settings.xml には次の宣言が含まれています。これにより、Maven が常に https://repo1.maven.org/maven2 で、セキュアな中央 Maven リポジトリからビルドおよびプラグインの依存関係を引き出すように指示されます。

<settings>
  <activeProfiles>
    <activeProfile>securecentral</activeProfile>
  </activeProfiles>
  <profiles>
    <profile>
      <id>securecentral</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
          <releases>
            <enabled>true</enabled>
          </releases>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
          <releases>
            <enabled>true</enabled>
          </releases>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
</settings>

推奨される解決策: 以下を実行してください。

ビルドコマンドがデフォルトでルートとして実行される

問題: AWS CodeBuild は、ビルドコマンドをルートユーザーとして実行します。これは、関連するビルドイメージの Dockerfile によって USER インストラクションが別のユーザーに設定された場合でも発生します。

原因: CodeBuild は、デフォルトですべてのビルドコマンドをルートユーザーとして実行します。

推奨される解決策: なし。

ファイル名に英語以外の文字が含まれているとビルドが失敗する場合があります

問題: 英語以外の文字 (漢字など) を含むファイル名のファイルを使用するビルドを実行すると、ビルドが失敗します。

考えられる原因: AWS CodeBuild によって提供されるビルド環境は、デフォルトのロケールが POSIX に設定されています。POSIX ローカリゼーション設定は、米国英語以外の文字を含む CodeBuild やファイル名との互換性が低く、関連するビルドが失敗する可能性があります。

推奨される解決策: buildspec ファイルの pre_build セクションに次のコマンドを追加します。これらのコマンドは、ビルド環境のローカライゼーション設定として米国英語 UTF-8 を使用するよう設定します。これは、米国英語以外の文字を含む CodeBuild やファイル名と高い互換性があります。

Ubuntu ベースのビルド環境の場合:

pre_build:
  commands:
    - export LC_ALL="en_US.UTF-8"
    - locale-gen en_US en_US.UTF-8
    - dpkg-reconfigure locales

Amazon Linux ベースのビルド環境の場合:

pre_build:
  commands:
    - export LC_ALL="en_US.utf8"

Amazon EC2 パラメータストアからパラメータを取得する際にビルドが失敗する場合がある

問題: ビルドが Amazon EC2 パラメータストアに保存されている 1 つ以上のパラメータの値を取得しようとすると、DOWNLOAD_SOURCE フェーズで「Parameter does not exist」というエラーが発生し、ビルドが失敗する。

考えられる原因: ビルドプロジェクトが依存するサービスロールに ssm:GetParameters アクションを呼び出す権限がありません。または、ビルドプロジェクトは AWS CodeBuild によって生成された ssm:GetParameters アクションを呼び出すことができるサービスロールを使用していますが、パラメータには、/CodeBuild/ で始まらない名前が付けられています。

推奨される解決策:

CodeBuild コンソールでブランチフィルタにアクセスできない

問題: AWS CodeBuild プロジェクトを作成または更新する際に、コンソールでブランチフィルタオプションを使用できない。

考えられる原因: ブランチフィルタオプションは廃止されました。このオプションはウェブフックフィルタグループに置き換えられています。これにより、CodeBuild の新しいビルドをトリガーするウェブフックイベントの制御が強化されます。

推奨される解決策: ウェブフックフィルタの導入前に作成したブランチフィルタを移行するには、正規表現 HEAD_REF で ^refs/heads/branchName$ フィルタを使用してウェブフックフィルタグループを作成します。たとえば、ブランチフィルタの正規表現が ^branchName$ の場合、HEAD_REF フィルタに入力する更新後の正規表現は ^refs/heads/branchName$ です。詳細については、「Bitbucket ウェブフックイベント」および「GitHub ウェブフックイベントのフィルタリング (コンソール)」を参照してください。

ビルドの成功または失敗を表示できない

問題: 再試行されたビルドの成功または失敗を確認できない。

考えられる原因: ビルドのステータスを報告するオプションが有効になっていません。

推奨される解決策: CodeBuild プロジェクトを作成または更新するときは、[ビルドのステータスを報告] を有効にします。このオプションは、ビルドをトリガーするときに CodeBuild にステータスを報告するように指示します。詳細については、AWS CodeBuild API リファレンスの「ReportBuildStatus」を参照してください。

ビルドステータスがソースプロバイダに報告されない

問題: GitHub や Bitbucket などのソースプロバイダーへのビルドステータスのレポートを許可した後で、ビルドステータスが更新されない。

考えられる原因: ソースプロバイダーに関連付けられたユーザーに、リポジトリへの書き込みアクセス許可がありません。

推奨される解決策: ソースプロバイダーにビルドステータスを報告できるようにするには、ソースプロバイダーに関連付けられたユーザーがリポジトリへの書き込みアクセス権を持っている必要があります。ユーザーが書き込みアクセス権を持っていない場合、ビルドのステータスは更新できません。詳細については、「ソースプロバイダーのアクセス」を参照してください。

Windows Server Core 2019 プラットフォームの基本イメージが見つからず、選択できない

問題: Windows Server Core 2019 プラットフォームの基本イメージを検索または選択できない。

考えられる原因: このイメージをサポートしていない AWS リージョンを使用しています。

推奨される解決策: Windows Server Core 2019 プラットフォームの基本イメージがサポートされている、次のいずれかの AWS リージョンを使用します。

buildspec ファイルの以前のコマンドが、以降のコマンドで認識されない

問題: buildspec ファイルの 1 つ以上のコマンドの結果が、同じ buildspec ファイルの以降のコマンドで認識されない。たとえば、コマンドによってローカル環境変数が設定される場合がありますが、後で実行されるコマンドがそのローカル環境変数の値を取得できない可能性があります。

考えられる原因: buildspec ファイルバージョン 0.1 では、AWS CodeBuild はビルド環境のデフォルトシェルの各インスタンスで各コマンドを実行します。つまり、各コマンドは他のすべてのコマンドとは独立して実行されます。デフォルトでは、以前のコマンドの状態に依存する単一のコマンドを実行することはできません。

推奨される解決策: buildspec バージョン 0.2 を使用してください。これにより、問題が解決されます。何らかの理由で buildspec バージョン 0.1 を使用する必要がある場合は、シェルコマンド連鎖演算子 (Linux の && など) を使用して、複数のコマンドを 1 つのコマンドにまとめることをお勧めします。または、複数のコマンドを含むソースコードにシェルスクリプトを組み込み、そのシェルスクリプトを buildspec ファイルの 1 つのコマンドから呼び出します。詳細については、「ビルド環境のシェルとコマンド」および「ビルド環境の環境変数」を参照してください。

エラー: キャッシュのダウンロード時に「アクセスが拒否される」

問題: キャッシュが有効になっているビルドプロジェクトでキャッシュをダウンロードしようとすると、Access denied エラーが発生する。

考えられる原因:

推奨される解決策: キャッシュ設定を更新した直後に初めて使用する場合、このエラーが表示されるのは普通です。このエラーが解消されない場合は、キャッシュを保持する S3 バケットへの s3:GetObject アクセス許可と s3:PutObject アクセス許可が、サービスロールに付与されているかどうかを確認する必要があります。詳細については、「Amazon S3 デベロッパーガイド」の「S3 アクセス許可の指定」を参照してください。

エラー: 「BUILD_CONTAINER_UNABLE_TO_PULL_IMAGE」カスタムビルドイメージを使用した場合

問題: カスタムビルドイメージを使用するビルドを実行しようとすると、ビルドは BUILD_CONTAINER_UNABLE_TO_PULL_IMAGE というエラーで失敗する。

エラー: 「ビルドの完了前にビルドコンテナの停止が検出されました。ビルドコンテナがメモリ不足のため停止したか、Docker イメージがサポートされていません」 エラーコード: 500」

問題: AWS CodeBuild で Microsoft Windows または Linux コンテナを使用しようとすると、このエラーが PROVISIONING フェーズで発生する。

考えられる原因:

推奨される解決策:

Error: "Cannot connect to the Docker daemon" when running a build (ビルドの実行時に「Docker デーモンに接続できません」)

問題: ビルドが失敗し、「Cannot connect to the Docker daemon at unix:/var/run/docker.sock. Is the docker daemon running?」のようなエラーがビルドログに表示される。

考えられる原因: 特権モードでビルドを実行していません。

推奨される解決策: このエラーを修正するには、特権モードを有効にし、次の手順を使用して buildspec を更新する必要があります。

特権モードでビルドを実行するには、次の手順に従います。

また、コンテナ内で Docker デーモンを起動する必要があります。buildspec の install フェーズは、以下のようなものです。

phases:
  install:
    commands:
      - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 &
      - timeout 15 sh -c "until docker info; do echo .; sleep 1; done"

buildspec ファイルで参照される OverlayFS ストレージドライバーの詳細については、Docker ウェブサイトの「Use the OverlayFS storage driver」を参照してください。

- timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done"

AWS CodeBuild を使用して Docker イメージをビルドおよび実行する方法については、「CodeBuild のカスタム Docker イメージのサンプル」を参照してください。

エラー : ビルドプロジェクトを作成または更新する際、「CodeBuild は sts:AssumeRole の実行を許可されていません」

問題: ビルドプロジェクトを作成または更新しようとすると、エラー「Code:InvalidInputException, Message:CodeBuild is not authorized to perform: sts:AssumeRole on arn:aws:iam::account-ID:role/service-role-name」が発生する。

考えられる原因:

推奨される解決策:

エラー: 「GetBucketAcl の呼び出しエラー: バケット所有者が変更されたか、サービスロールには、呼び出された s3:GetBucketAcl へのアクセス許可がありません」

問題: ビルドを実行すると、S3 バケット所有者や GetBucketAcl アクセス許可の変更に関するエラーが発生する。

考えられる原因: s3:GetBucketAcl および s3:GetBucketLocation のアクセス許可を IAM ロールに追加しています。これらのアクセス許可は、プロジェクトの S3 バケットを保護し、バケットにアクセスできるユーザーを自分に限定します。これらのアクセス許可を追加した後で、S3 バケットの所有者が変更されています。

推奨される解決策: S3 バケットの所有者が自分であることを確認し、IAM ロールへのアクセス許可を追加し直します。詳細については、「S3 バケットへの安全なアクセス」を参照してください。

エラー: ビルドの実行時に「アーティファクトのアップロードに失敗しました: 無効な ARN」

問題: ビルドを実行すると、UPLOAD_ARTIFACTS ビルドフェーズが失敗し、「Failed to upload artifacts: Invalid arn」というエラーが表示される。

考えられる原因: S3 出力バケット (AWS CodeBuild がビルドからの出力を保存するバケット) が、CodeBuild ビルドプロジェクトとは異なる AWS リージョンにあります。

推奨される解決策: ビルドプロジェクトの設定を、ビルドプロジェクトと同じ AWS リージョンにある出力バケットを指すように更新します。

エラー: 「Git のクローンに失敗しました: 'your-repository-URL' にアクセスできません: SSL 証明書の問題: 自己署名証明書」

問題: ビルドプロジェクトを実行しようとすると、このエラーが発生してビルドが失敗する。

考えられる原因: ソースリポジトリには自己署名証明書がありますが、S3 バケットから証明書をビルドプロジェクトの一部としてインストールする選択をしていません。

推奨される解決策:

エラー: ビルドの実行時に「アクセスしようとしているバケットは、指定されたエンドポイントを使用してアドレス指定する必要があります」

問題: ビルドを実行すると、DOWNLOAD_SOURCE ビルドフェーズが失敗し、「The bucket you are attempting to access must be addressed using the specified endpoint. Please send all future requests to this endpoint」というエラーが表示される。

考えられる原因: 構築済みのソースコードの保存先である S3 バケットが、AWS ビルドプロジェクトとは異なる AWS CodeBuild リージョンにあります。

推奨される解決策: 構築済みのソースコードが含まれているバケットを指すように、ビルドプロジェクトの設定を更新します。バケットがビルドプロジェクトと同じ AWS リージョンにあることを確認してください。

エラー: "このビルドイメージではランタイムバージョンを少なくとも 1 つ選択する必要があります。"

問題: ビルドを実行すると、DOWNLOAD_SOURCE ビルドフェーズが失敗し、「YAML_FILE_ERROR: This build image requires selecting at least one runtime version」というエラーが表示される。

考えられる原因: ビルドでバージョン 1.0 以降の Amazon Linux 2 (AL2) 標準イメージ、またはバージョン 2.0 以降の Ubuntu 標準イメージが使用されていますが、buildspec ファイルでランタイムが指定されていません。

推奨される解決策: aws/codebuild/standard:2.0 CodeBuild マネージド型イメージを使用する場合は、buildspec ファイルの runtime-versions セクションでランタイムバージョンを指定する必要があります。たとえば、PHP を使用するプロジェクトでは、次の buildspec ファイルを使用します。

version: 0.2

phases:
  install:
    runtime-versions:
        php: 7.3
  build:
    commands:
      - php --version
artifacts:
  files:
    -  README.md

詳細については、「Specify runtime versions in the buildspec file」を参照してください。

ビルドキューのビルドが失敗するとエラー「QUEUED:INSUFFICIENT_SUBNET」が表示される

問題: ビルドキューのビルドが QUEUED: INSUFFICIENT_SUBNET のようなエラーで失敗する。

考えられる原因: VPC に指定された IPv4 CIDR ブロックが、リザーブド IP アドレスを使用している。各サブネット CIDR ブロックの最初の 4 つの IP アドレスと最後の IP アドレスは使用できず、インスタンスに割り当てることができません。たとえば、CIDR ブロック 10.0.0.0/24 を持つサブネットの場合、次の 5 つの IP アドレスが予約されます。

推奨される解決策: VPC でリザーブド IP アドレスが使用されていることを確認します。予約済みの IP アドレスを、予約されていないアドレスに置き換えます。詳細については、Amazon VPC ユーザーガイドのVPC とサブネットのサイズ設定を参照してください。

エラー: 「キャッシュをダウンロードできません: RequestError: 次の理由により送信リクエストが失敗しました: x509: システムのルートをロードできませんでした。ルートが指定されていません」

問題: ビルドプロジェクトを実行しようとすると、このエラーが発生してビルドが失敗する。

考えられる原因: ビルドプロジェクトの一部としてキャッシュを設定し、有効期限が切れたルート証明書を含む古い Docker イメージを使用しています。

推奨される解決策: AWS CodeBuild プロジェクトで使用中の Docker イメージを更新します。詳細については、「CodeBuild に用意されている Docker イメージ」を参照してください。

エラー : 「S3 から証明書をダウンロードできません。AccessDenied"

問題: ビルドプロジェクトを実行しようとすると、このエラーが発生してビルドが失敗する。

考えられる原因:

推奨される解決策:

エラー: 「認証情報を見つけることができません」

問題: AWS CLI を実行しようとするとき、AWS SDK を使用したり、別の同様のコンポーネントをビルドの一部として呼び出すと、AWS CLI、AWS SDK、またはコンポーネントに直接関連するビルドエラーが発生します。たとえば、「Unable to locate credentials」などのビルドエラーが発生する場合があります。

考えられる原因:

推奨される解決策:

プロキシサーバーで CodeBuild を実行しているときの RequestError タイムアウトエラー

問題: 次のいずれかのような RequestError エラーが表示される。

考えられる原因:

推奨される解決策:

ビルドイメージ内に Bourne シェル (sh) が必要

問題: AWS CodeBuild から提供されていないビルドイメージを使用中に、ビルドが失敗して「Build container found dead before completing the build」というメッセージが表示される。

考えられる原因: Bourne シェル (sh) がビルドイメージに含まれていません。CodeBuild は、ビルドコマンドとスクリプトを実行するために、sh を必要とします。

推奨される解決策: ビルドイメージに sh が含まれていない場合、イメージを使用するビルドを開始する前に必ずそれを含めてください  (CodeBuild は、ビルドイメージに既に sh を含んでいます)。

警告 (ビルドの実行時): 「ランタイムのインストールをスキップします。このビルドイメージではランタイムバージョンの選択はサポートされていません」

問題: ビルドを実行すると、この警告がビルドログに表示される。

考えられる原因: ビルドでバージョン 1.0 以降の Amazon Linux 2 (AL2) 標準イメージ、またはバージョン 2.0 以降の Ubuntu 標準イメージが使用されておらず、buildspec ファイルの runtime-versions セクションにランタイムが指定されています。

推奨される解決策: buildspec ファイルに runtime-versions セクションが含まれていないことを確認します。runtime-versions セクションは、Amazon Linux 2 (AL2) 標準イメージ以降または Ubuntu 標準イメージのバージョン 2.0 以降を使用する場合にのみ必要です。

エラー：CodeBuild コンソールを開くときに「JobWorker ID を確認できません」と表示される。

問題: CodeBuild コンソールを開くと、「JobWorker の ID を確認できません」というエラーメッセージが表示される。

考えられる原因: コンソールのアクセスに使用されている IAM ロールに、jobId をキーとするタグがあります。このタグキーは CodeBuild 用に予約されており、存在する場合にこのエラーを発生させます。

推奨される解決策: jobId キーを持つカスタム IAM ロールタグを変更して、jobIdentifier などの別のキーを持つようにします。

ビルドの開始の失敗

問題: ビルドを開始すると、「ビルドを開始できませんでした」というエラーメッセージが表示される。

考えられる原因: 同時に実行できるビルド数の上限に達しています。

推奨される解決策: 他のビルドが完了するまで待つか、プロジェクトの同時実行のビルド制限を増やして、ビルドを再度開始します。詳細については、「プロジェクトの設定」を参照してください。

ローカルにキャッシュされたビルドの GitHub メタデータへのアクセス

問題: 状況によっては、キャッシュされたビルドの .git ディレクトリは、ディレクトリではなく、テキストファイルである場合があります。

考えられる原因: ローカルソースキャッシュがビルドに対して有効になっている場合、CodeBuild は .git ディレクトリの gitlink を作成します。つまり、.git ディレクトリは、単にディレクトリへのパスを含むテキストファイルです。

推奨される解決策: すべての場合において、次のコマンドを使用して Git メタデータディレクトリを取得します。このコマンドは、.git のフォーマットに関係なく機能します。

git rev-parse --git-dir

AccessDenied: レポートグループのバケット所有者が S3 バケットの所有者と一致しません。

問題: Amazon S3 バケットにテストデータをアップロードしたときに、CodeBuild がバケットにテストデータを書き込むことができない。

考えられる原因:

推奨される解決策: