翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # チュートリアル: CodeBuild がホストする Buildkite ランナーを設定 このチュートリアルでは、CodeBuild プロジェクトを設定して Buildkite ジョブを実行する方法について説明します。CodeBuild で Buildkite を使用する方法の詳細については、「[のセルフマネージド Buildkite ランナー AWS CodeBuild](buildkite-runner.md)」を参照してください。 このチュートリアルを完了するには、まず以下を行う必要があります。 + Buildkite 組織にアクセスできる。Buildkite アカウントと組織の設定の詳細については、この[入門チュートリアル](https://buildkite.com/docs/pipelines/getting-started)を参照してください。 + セルフホスト型ランナーを使用するように設定された Buildkite パイプライン、クラスター、キューを作成する。これらのリソースをセットアップする方法の詳細については、「[Buildkite パイプラインセットアップチュートリアル](https://buildkite.com/docs/pipelines/create-your-own)」を参照してください。 ![\[Buildkite でプロジェクトを構築する\]](http://docs.aws.amazon.com/ja_jp/codebuild/latest/userguide/images/buildkite-first.png) ## ステップ 1: Buildkite エージェントトークンを生成する このステップでは、CodeBuild セルフホスト型ランナーの認証に使用されるエージェントトークンを Buildkite 内で生成します。このリソースの詳細については、「[Buildkite エージェントトークン](https://buildkite.com/docs/agent/v3/tokens)」を参照してください。 **Buildkite エージェントトークンを生成するには** 1. Buildkite クラスターで、**[エージェントトークン]** を選択し、**[新しいトークン]** を選択します。 1. トークンに説明を追加し、**[トークンを作成]** をクリックします。 1. エージェントトークン値は、後で CodeBuild プロジェクトのセットアップ中に使用するため、保存しておきます。 ![\[Buildkite のエージェントトークン\]](http://docs.aws.amazon.com/ja_jp/codebuild/latest/userguide/images/buildkite-createtoken.png) ## ステップ 2: ウェブフックを使用して CodeBuild プロジェクトを作成する **ウェブフックを使用して CodeBuild プロジェクトを作成するには** 1. [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) で AWS CodeBuild コンソールを開きます。 1. セルフホスト型ビルドプロジェクトを作成します。詳細については、「[ビルドプロジェクトの作成 (コンソール)](create-project.md#create-project-console)」および「[ビルドの実行 (コンソール)](run-build-console.md)」を参照してください。 + **[プロジェクトの設定]** で、**[ランナープロジェクト]** を選択します。**[ランナー]** で、次のようにします。 + **[ランナープロバイダー]** で、**[Buildkite]** を選択します。 + **[Buildkite エージェントトークン]** で、**[シークレットの作成ページを使用して新しいエージェントトークンを作成する]** を選択します。で、上記で生成した Buildkite エージェントトークンと等しいシークレット値 AWS Secrets Manager を持つ新しいシークレットを作成するように求められます。 + (オプション) ジョブに CodeBuild マネージド認証情報を使用する場合は、**[Buildkite ソース認証情報オプション]** でジョブのソースリポジトリプロバイダーを選択し、アカウントに認証情報が設定されていることを確認します。さらに、Buildkite パイプラインで **HTTPS を使用したチェックアウト**が使用されていることを確認します。 **注記** ジョブのソースをプルするため、Buildkite によりビルド環境内でソース認証情報が求められます。使用可能なソース認証情報オプションについては、「[プライベートリポジトリへの Buildkite の認証](#sample-runner-buildkite-config)」を参照してください。 + (オプション) **[環境]** で、次のようにします。 + サポートされている **[環境イメージ]** と **[コンピューティング]** を選択します。 Buildkite YAML ステップのラベルを使用して、イメージとインスタンスの設定を上書きするオプションがあることに注意してください。詳細については、「[ステップ 4: Buildkite パイプラインステップを更新する](#sample-runner-buildkite-update-pipeline)」を参照してください。 + (オプション) **[Buildspec]** で、次のようにします。 + `buildspec-override: "true"` がラベルとして追加されない限り、buildspec は無視されます。代わりに、CodeBuild は、セルフホスト型ランナーを設定するコマンドを使用するように上書きします。 **注記** CodeBuild は、Buildkite セルフホスト型ランナービルドの buildspec ファイルをサポートしていません。インライン buildspec の場合、CodeBuild マネージドソース認証情報を設定している場合は、buildspec で [git-credential-helper](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper) を有効にする必要があります。 1. デフォルト値のまま続行し、**[ビルドプロジェクトを作成する]** を選択します。 1. **[ウェブフックの作成]** ポップアップから **[ペイロードの URL]** と **[シークレット]** の値を保存します。ポップアップの手順に従って新しい Buildkite 組織のウェブフックを作成するか、次のセクションに進みます。 ## ステップ 3: Buildkite 内で CodeBuild ウェブフックを作成する このステップでは、CodeBuild ウェブフックの **[ペイロード URL]** と **[シークレット]** の値を使用して、Buildkite 内に新しいウェブフックを作成します。このウェブフックは、有効な Buildkite ジョブの開始時に CodeBuild 内でビルドをトリガーするために使用されます。 **Buildkite で新しいウェブフックを作成するには** 1. Buildkite 組織の **[設定]** ページに移動します。 1. **[統合]** で、**[通知サービス]** を選択します。 1. **[ウェブフック]** ボックスの横にある **[追加]** を選択します。**[ウェブフック通知の追加]** ページで、次の設定を使用します。 1. **[ウェブフックの URL]** で、保存された **[ペイロードの URL]** 値を追加します。 1. **[トークン]** で、**[X-Buildkite-Token としてトークンを送信]** が選択されていることを確認します。ウェブフックの **[シークレット]** 値を **[トークン]** フィールドに追加します。 1. **[X-Buildkite-Token としてトークンを送信]** が選択されていることを確認します。ウェブフックの **[シークレット]** 値を **[トークン]** フィールドに追加します。 1. **[イベント]** で、`job.scheduled` ウェブフックイベントを選択します。 1. (オプション) **[パイプライン]** では、オプションで特定のパイプラインのビルドのみをトリガーするように選択できます。 1. **[ウェブフック通知の追加]** を選択します。 ## ステップ 4: Buildkite パイプラインステップを更新する このステップでは、Buildkite パイプラインのステップを更新して、必要なラベルとオプションの上書きを追加します。サポートされているラベル上書きの詳細なリストについては、「[CodeBuild がホストする Buildkite ランナーでサポートされているラベルの上書き](buildkite-runner-update-labels.md)」を参照してください。 **パイプラインステップを更新する** 1. Buildkite パイプラインを選択して、**[設定]** を選択し、**[ステップ]** を選択して、Buildkite パイプラインステップページに移動します。 まだの場合は、**[YAML ステップに変換]** を選択します。 ![\[YAML を更新するステップ。\]](http://docs.aws.amazon.com/ja_jp/codebuild/latest/userguide/images/buildkite-steps.png) 1. 少なくとも、CodeBuild パイプラインの名前を参照する [Buildkite エージェントタグ](https://buildkite.com/docs/agent/v3/cli-start#agent-targeting)を指定する必要があります。Buildkite ジョブの AWS関連設定を特定の CodeBuild プロジェクトにリンクするには、プロジェクト名が必要です。YAML にプロジェクト名を含めることで、CodeBuild は正しいプロジェクト設定でジョブを呼び出すことができます。 ``` agents: project: "codebuild-" ``` 以下は、プロジェクトラベルタグのみを含む Buildkite パイプラインステップの例です。 ``` agents: project: "codebuild-myProject" steps: - command: "echo \"Hello World\"" ``` ラベル内のイメージとコンピューティングタイプを上書きすることもできます。使用可能なイメージのリストについては、「[CodeBuild がホストする Buildkite ランナーでサポートされているコンピューティングイメージ](buildkite-runner-update-yaml.images.md)」を参照してください。ラベル内のコンピューティングタイプとイメージは、プロジェクトの環境設定を上書きします。CodeBuild EC2 または Lambda コンピューティングビルドの環境設定を上書きするには、次の構文を使用します。 ``` agents: project: "codebuild-" image: "-" instance-size: "" ``` イメージサイズとインスタンスサイズの上書きを含む Buildkite パイプラインステップの例を次に示します。 ``` agents: project: "codebuild-myProject" image: "arm-3.0" instance-size: "small" steps: - command: "echo \"Hello World\"" ``` ラベル内のビルドに使用するフリートを上書きできます。これにより、プロジェクトで設定されたフリート設定が上書きされ、指定されたフリートが使用されます。詳細については、「[リザーブドキャパシティフリートでビルドを実行](https://docs.aws.amazon.com/codebuild/latest/userguide/fleets.html)」を参照してください。 Amazon EC2 コンピューティングビルドのフリート設定を上書きするには、次の構文を使用します。 ``` agents: project: "codebuild-" fleet: "" ``` ビルドに使用されるフリートとイメージの両方を上書きするには、次の構文を使用します。 ``` agents: project: "codebuild-" fleet: "" image: "-" ``` フリートとイメージの上書きを含む Buildkite パイプラインステップの例を次に示します。 ``` agents: project: "codebuild-myProject" fleet: "myFleet" image: "arm-3.0" steps: - command: "echo \"Hello World\"" ``` 1. セルフホスト型 Buildkite ランナーのビルド中にインライン buildspec コマンドを実行することを選択できます (詳細については、「[INSTALL、PRE\$1BUILD、POST\$1BUILD フェーズで buildspec コマンドを実行](sample-runner-buildkite-buildspec.md)」を参照してください)。Buildkite セルフホスト型ランナーのビルド中に CodeBuild ビルドが buildspec コマンドを実行するように指定するには、次の構文を使用します。 ``` agents: project: "codebuild-" buildspec-override: "true" ``` buildspec の上書きを使用する Buildkite パイプラインの例を次に示します。 ``` agents: project: "codebuild-myProject" buildspec-override: "true" steps: - command: "echo \"Hello World\"" ``` 1. 必要に応じて、CodeBuild がサポートするラベル以外のラベルを提供できます。これらのラベルは、ビルドの属性を上書きする目的で無視されますが、ウェブフックリクエストは失敗しません。例えば、`myLabel: “testLabel"` をラベルとして追加しても、ビルドの実行は妨げられません。 ## ステップ 5: 結果を確認する Buildkite ジョブがパイプラインで開始されるたびに、CodeBuild は Buildkite ウェブフックを介して `job.scheduled` ウェブフックイベントを受け取ります。Buildkite ビルド内のジョブごとに、CodeBuild はエフェメラル Buildkite ランナーを実行するビルドを開始します。ランナーには、単一の Buildkite ジョブを実行する役割があります。ジョブが完了すると、ランナーおよび関連付けられたビルドプロセスは即座に終了します。 ワークフロージョブログを表示するには、Buildkite パイプラインに移動し、最新のビルドを選択します (**[新しいビルド]** を選択して新しいビルドをトリガーできます)。各ジョブに関連付けられた CodeBuild ビルドが開始されてジョブが取得されると、Buildkite コンソールにジョブのログが表示されます。 ![\[結果を確認します。\]](http://docs.aws.amazon.com/ja_jp/codebuild/latest/userguide/images/buildkite-log.png) ## プライベートリポジトリへの Buildkite の認証 Buildkite パイプライン内にプライベートリポジトリが設定されている場合、Buildkite はプライベートリポジトリからプルするためにセルフホスト型ランナーに認証情報を供給しないため、Buildkite はリポジトリをプルするために[ビルド環境内で追加のアクセス許可](https://buildkite.com/docs/agent/v3/github-ssh-keys)を必要とします。Buildkite セルフホスト型ランナーエージェントを外部プライベートソースリポジトリに対して認証するには、次のいずれかのオプションを使用できます。 **CodeBuild で認証するには** CodeBuild は、サポートされているソースタイプのマネージド認証情報処理を行います。CodeBuild ソース認証情報を使用してジョブのソースリポジトリをプルするには、次の手順を使用します。 1. CodeBuild コンソールで、**[プロジェクトの編集]** に移動するか、「[ステップ 2: ウェブフックを使用して CodeBuild プロジェクトを作成する](#sample-runner-buildkite-create-project)」のステップを使用して新しい CodeBuild プロジェクトを作成します。 1. **[Buildkite ソース認証情報オプション]** で、ジョブのソースリポジトリプロバイダーを選択します。 1. アカウントレベルの CodeBuild 認証情報を使用する場合は、それらが正しく設定されていることを確認します。さらに、プロジェクトにインライン buildspec が設定されている場合は、[git-credential-helper](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper) が有効になっていることを確認します。 1. プロジェクトレベルの CodeBuild 認証情報を使用する場合は、**[このプロジェクトの上書き認証情報のみを使用する]** を選択し、プロジェクトの認証情報を設定します。 1. Buildkite パイプライン設定で、**[リポジトリの設定]** に移動します。ソースリポジトリのチェックアウト設定を **[HTTPS を使用してチェックアウト]** に設定する ![\[結果を確認します。\]](http://docs.aws.amazon.com/ja_jp/codebuild/latest/userguide/images/buildkite-repo-https.png) **Buildkite シークレットで認証するには** Buildkite には、ssh キーを使用して外部ソースリポジトリに対してセルフホスト型ランナーを認証するために使用できる [ssh-checkout プラグイン](https://github.com/buildkite-plugins/git-ssh-checkout-buildkite-plugin)が維持されます。キー値は [Buildkite シークレット](https://buildkite.com/docs/pipelines/security/secrets/buildkite-secrets)として保存され、プライベートリポジトリをプルしようとすると Buildkite セルフホスト型ランナーエージェントによって自動的に取得されます。Buildkite パイプラインの ssh-checkout プラグインを設定するには、次のステップを使用します。 1. E メールアドレスを使用してプライベートおよびパブリック SSH キーを生成します。例: `ssh-keygen -t rsa -b 4096 -C "myEmail@address.com"` 1. パブリックキーをプライベートソースリポジトリに追加します。例えば、[このガイド](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)に従って GitHub アカウントにキーを追加できます。 1. Buildkite クラスターに[新しい SSH キーシークレット](https://buildkite.com/docs/pipelines/hosted-agents/code-access#private-repositories-with-other-providers-add-the-ssh-key-secret)を追加します。Buildkite クラスター内で、**[シークレット]** → **[新しいシークレット]** を選択します。**[キー]** フィールドにシークレットの名前を追加し、**[値]** フィールドにプライベート SSH キーを追加します。 ![\[結果を確認します。\]](http://docs.aws.amazon.com/ja_jp/codebuild/latest/userguide/images/buildkite-secret.png) 1. Buildkite パイプライン内で、リポジトリ設定に移動し、**SSH** を使用するようにチェックアウトを設定します。 ![\[結果を確認します。\]](http://docs.aws.amazon.com/ja_jp/codebuild/latest/userguide/images/buildkite-repo.png) 1. パイプラインの YAML ステップを更新して、`git-ssh-checkout` プラグインを使用します。たとえば、次のパイプライン YAML ファイルでは、上記の Buildkite シークレットキーを使用してチェックアウトアクションを使用します。 ``` agents: project: "codebuild-myProject" steps: - command: "npm run build" plugins: - git-ssh-checkout#v0.4.1: ssh-secret-key-name: 'SOURCE_SSH_KEY' ``` 1. CodeBuild 内で Buildkite セルフホスト型ランナージョブを実行すると、プライベートリポジトリをプルするときに、設定されたシークレット値が Buildkite により自動的に使用されるようになりました。 ## ランナー設定オプション プロジェクト設定で次の環境変数を指定して、セルフホスト型ランナーのセットアップ設定を変更できます。 + `CODEBUILD_CONFIG_BUILDKITE_AGENT_TOKEN`: CodeBuild は、Buildkite セルフホスト型ランナーエージェントを登録するために、この環境変数の値として設定されたシークレット値を AWS Secrets Manager から取得します。この環境変数はタイプ `SECRETS_MANAGER` でなければならず、値は Secrets Manager のシークレットの名前である必要があります。Buildkite エージェントトークン環境変数は、すべての Buildkite ランナープロジェクトに必要です。 + `CODEBUILD_CONFIG_BUILDKITE_CREDENTIAL_DISABLE`: デフォルトでは、CodeBuild はアカウントまたはプロジェクトレベルのソース認証情報をビルド環境にロードします。これらの認証情報は、Buildkite エージェントによってジョブのソースリポジトリをプルするために使用されます。この動作を無効にするには、値を `true` に設定してこの環境変数をプロジェクトに追加します。これにより、ソース認証情報がビルド環境にロードされなくなります。