ユーザー管理のサービス アカウントでビルドを実行する

このドキュメントでは、ユーザー管理のサービス アカウントを使用するようにビルドを構成する方法について説明します。

ビルドにユーザー管理のサービス アカウントを指定しない場合、Cloud Build はデフォルトの Cloud Build サービス アカウントを自動的に使用します。このデフォルトのサービス アカウントには、プロジェクト内の Cloud Source Repositories や Cloud Storage バケットへのアクセスなど、必要以上に幅広い権限が付与されている場合があります。

最小権限の原則に従い、実行するタスクに限られた範囲の権限とロールをサービス アカウントに割り当てることをおすすめします。たとえば、Google Cloud ブログで説明されるように、1 つのサービス アカウントでイメージのビルドと Artifact Registry への push が可能です。

始める前に

  • Cloud Build API と IAM API を有効にします(まだ有効になっていない場合)。

    API を有効にするために必要なロール

    API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール(roles/owner)を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール(roles/serviceusage.serviceUsageAdmin)を介してこの権限を取得できます。ロールを付与する方法を確認する。

    API を有効にする

  • このアカウントを使用して認証情報を作成、管理する(たとえば、有効期間が短い認証情報を作成する)場合は、IAM Service Account Credentials API を有効にします。

    API を有効にするために必要なロール

    API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール(roles/owner)を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール(roles/serviceusage.serviceUsageAdmin)を介してこの権限を取得できます。ロールを付与する方法を確認する。

    API の有効化

  • まだ作成していない場合は、サービス アカウントを作成します。

サービス アカウントを設定する

ビルドの実行に必要な権限を付与するために、ユーザー管理のサービス アカウントに IAM ロールを付与します。新しいトリガーにこのサービス アカウントを自動的に選択するように Cloud Build を構成することもできます。

  1. Google Cloud コンソールで、 Cloud Build の [権限] ページに移動します。

    [権限] に移動

  2. [サービス アカウント] メニューに移動し、サービス アカウントを選択します。別のプロジェクトのサービス アカウントを選択するには、[プロジェクトを切り替え] をクリックします。

  3. 選択したサービス アカウントを新しいトリガーのサービス アカウントとして使用するには、[新しいトリガーの事前選択として設定] をオンにします。

  4. Google Cloud サービスのリストで、サービス アカウントに付与する IAM ロールを有効にします。

  5. ビルド パイプラインに必要なロールがこちらに記載されていない場合は、IAM 構成ページで追加のロールを付与します。

  6. 別のプロジェクトのサービス アカウントを選択した場合は、プロジェクト間の設定の手順を完了します。

構成するサービス アカウントを特定する

ロールを付与する前に、ビルドに構成されているサービス アカウントを確認します。

  • 既存のビルドトリガー: トリガーに構成されているサービス アカウントを確認します。

    gcloud builds triggers describe TRIGGER_NAME \
        --region=REGION \
        --format="value(serviceAccount)"
    

    次のように置き換えます。

    • TRIGGER_NAME: ビルドトリガーの名前。
    • REGION: ビルドトリガーのリージョン。

    出力は次のように解釈されます。

    • コマンド出力で projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL 形式のサービス アカウント リソース名が出力される場合は、そのアカウントに必要なロールを付与します。この出力では、ユーザー管理のサービス アカウントまたは Compute Engine のデフォルトのサービス アカウントを識別できます。
    • serviceAccount フィールドが空の場合、トリガーは以前の Cloud Build サービス アカウントを使用します。トリガーの作成時に serviceAccount を省略できるのは、以前のデフォルトのサービス アカウントを使用しているプロジェクトのみです。Compute Engine のデフォルトのサービス アカウントを使用しているプロジェクト、または組織のポリシーによってデフォルトのサービス アカウントを制限しているプロジェクトでは、トリガーの作成が失敗し、サービス アカウント(BYOSA is required when creating triggers)を指定する必要があることを示す INVALID_ARGUMENT エラーが発生します。組織のポリシーによってビルド時にデフォルトのサービス アカウントが制限されている場合、ビルドは build.service_account must be specified due to the evaluation of the following org policies で失敗します。
  • ビルド構成ファイル: gcloud builds submit を使用してビルドを手動で実行する場合は、cloudbuild.yaml ファイルの serviceAccount フィールドを確認します。省略すると、Cloud Build はデフォルトのビルド サービス アカウントを使用します。組織のポリシーでデフォルトのサービス アカウントが制限されている場合は、build.service_account must be specified due to the evaluation of the following org policies で失敗します。

必要なロール

ユーザー管理のサービス アカウントを使用してビルドを実行するために必要な権限がユーザー管理のサービス アカウントに付与されるように、ビルドを実行するプロジェクトでユーザー管理のサービス アカウントに次の IAM ロールを付与するよう管理者に依頼してください。

  • ビルドログを Cloud Logging に書き込んでストリーミングする: ログ書き込み(roles/logging.logWriter)
  • Cloud Storage バケットからソース アーカイブまたは依存関係をダウンロードする: Storage オブジェクト閲覧者(roles/storage.objectViewer)

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

管理者は、カスタムロールや他の事前定義ロールを使用して、必要な権限をユーザー管理のサービス アカウントに付与することもできます。

サービス アカウントの権限借用

Cloud Build とトリガーがユーザー管理のサービス アカウントを使用してビルドを実行できるようにするには、ユーザー管理のサービス アカウントに次の権限が付与されていることを確認します。

  • ビルドトリガーを作成、更新、手動で実行する(または gcloud builds submit を使用してビルドを送信する)ユーザーまたは自動化 ID に、iam.serviceAccounts.actAs 権限を含むサービス アカウント ユーザー ロール(roles/iam.serviceAccountUser)を付与します。
  • Cloud Build サービス エージェント(service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com)には、iam.serviceAccounts.getAccessToken 権限が必要です。同じプロジェクトでは、この権限はデフォルトで Cloud Build サービス エージェントのロール(roles/cloudbuild.serviceAgent)に含まれています。そのロールが削除された場合、またはユーザー管理のサービス アカウントが別のプロジェクトにある場合は、サービス アカウント トークン作成者のロール(roles/iam.serviceAccountTokenCreator)を付与します。

ビルドに一般的に必要な IAM ロールの詳細については、次の情報をご覧ください。

ビルドログを設定する

ビルド用に独自のサービス アカウントを指定する場合、ビルドログを次のいずれかのバケットタイプに保存する必要があります。

ログバケットを作成する場合は、保持ポリシーが設定されていないことを確認してください。ポリシーが設定されていると、Cloud Build がビルドログをバケットに書き込めなくなる可能性があります。

Google Cloudが所有するログバケットにログを保存することはできません。

ビルドログの保存場所の詳細については、ビルドログの保存オプションをご覧ください。

構成ファイルを使用してビルドを実行する

構成ファイルを使用してビルドを手動で実行するには:

  1. プロジェクトのルート ディレクトリに、cloudbuild.yaml または cloudbuild.json という名前の Cloud Build ビルド構成ファイルを作成します。

  2. serviceAccount フィールドと、優先するロギング設定を追加します。

    • ビルドログを Cloud Logging に保存する場合は、logging フィールドを追加して、そのフィールドの値を CLOUD_LOGGING_ONLY に設定します。

    • ユーザーが作成した Cloud Storage バケットにビルドログを保存する場合:

      • logging フィールドを追加して、その値を GCS_ONLY に設定します。
      • logsBucket フィールドを追加し、その値を Cloud Storage バケットのロケーションに設定します。

    次の例では、ユーザー管理のサービス アカウントを使用してビルドを実行するように Cloud Build を構成し、ビルドログをユーザーが作成した Cloud Storage バケットに保存するよう構成しています。

    YAML

    steps:
    - name: 'bash'
      args: ['echo', 'Hello world!']
    logsBucket: 'LOGS_BUCKET_LOCATION'
    serviceAccount: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT'
    options:
      logging: GCS_ONLY
    

    JSON

    {
      "steps": [
      {
        "name": "bash",
        "args": [
          "echo",
          "Hello world!"
        ]
      }
      ],
      "logsBucket": "LOGS_BUCKET_LOCATION",
      "serviceAccount": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT",
      "options": {
        "logging": "GCS_ONLY"
      }
    }
    
    

    ビルド構成ファイルの変数を次のように置き換えます。

    • LOGS_BUCKET_LOCATION: ビルドログを保存する Cloud Storage バケット。例: gs://mylogsbucket
    • PROJECT_ID は、ビルドを実行する Google Cloud プロジェクトの ID です。
    • SERVICE_ACCOUNT は、ビルドに指定するサービス アカウントのメールアドレスまたは一意の ID です。たとえば、サービス アカウントのメールアドレスは次のようになります。service-account-name@project-id.iam.gserviceaccount.com
  3. ビルド構成ファイルを使用してビルドを開始します。

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
    

    コマンドの変数を次の値に置き換えます。

    • CONFIG_FILE_PATH は、ビルド構成ファイルへのパスです。
    • SOURCE_DIRECTORY は、ソースコードのパスまたは URL です。

    gcloud builds submit コマンドに CONFIG_FILE_PATH と SOURCE_DIRECTORY を指定しない場合、Cloud Build は、ビルド構成ファイルとソースコードが現在の作業ディレクトリにあると想定します。

トリガーを使用してビルドを実行する

独自のサービス アカウントで Cloud Build トリガーを使用してビルドを実行するには、トリガーの作成時に任意のロギング オプションを設定し、任意のサービス アカウントを選択します。

すべての新しいトリガーに同じサービス アカウントを使用する場合は、サービス アカウントを自動的に選択するように Cloud Build を構成します。

  1. ビルド構成ファイルで、次のことを行います。

    • ビルドログを Cloud Logging に保存する場合は、logging フィールドを追加して、そのフィールドの値を CLOUD_LOGGING_ONLY に設定します。

    • ユーザーが作成した Cloud Storage バケットにビルドログを保存する場合:

      • logging フィールドを追加して、その値を GCS_ONLY に設定します。
      • logsBucket フィールドを追加し、その値を Cloud Storage バケットのロケーションに設定します。

    次のサンプルでは、ユーザーが作成した Cloud Storage バケットに保存されるようビルドログが構成されています。

    YAML

    steps:
    - name: 'bash'
      args: ['echo', 'Hello world!']
    logsBucket: 'LOGS_BUCKET_LOCATION'
    options:
      logging: GCS_ONLY
    

    JSON

    {
      "steps": [
      {
        "name": "bash",
        "args": [
          "echo",
          "Hello world!"
        ]
      }
      ],
      "logsBucket": "LOGS_BUCKET_LOCATION",
      "options": {
        "logging": "GCS_ONLY"
      }
    }
    

    LOGS_BUCKET_LOCATION は、ビルドログを保存する Cloud Storage バケットに置き換えます。例: gs://mylogsbucket

  2. 使用するサービス アカウントをビルドトリガーで次のように指定します。

    Console

    1. ビルドトリガーを作成または編集します。

    2. [サービス アカウント] フィールドにサービス アカウントを指定します。別のプロジェクトのサービス アカウントを選択するには、[プロジェクトを切り替え] をクリックします。

      以前の Cloud Build サービス アカウントを使用するプロジェクトで、このフィールドを省略すると、デフォルトで以前のサービス アカウントが使用されます。Compute Engine のデフォルトのサービス アカウントを使用するプロジェクト、または組織のポリシーによってデフォルトのサービス アカウントを制限するプロジェクトでは、サービス アカウントを選択する必要があります。選択しないと、サービス アカウントを指定する必要があることを示す INVALID_ARGUMENT エラーが発生して、トリガーの作成が失敗します。

    3. [作成] をクリックして、ビルドトリガーを保存します。

    gcloud

    ビルドトリガーを作成する際に、--service-account フラグを使用してサービス アカウントを指定します。以前のデフォルトのサービス アカウントを使用しないプロジェクトでは、--service-account フラグが必要です。このフラグを指定しないと、サービス アカウントを指定する必要があることを示す INVALID_ARGUMENT エラーが発生して、トリガーの作成が失敗します。次のサンプルでは、gcloud コマンドによって、Git リポジトリからコードを pull するビルドトリガーが作成されます。

    gcloud builds triggers create github \
       --name=TRIGGER_NAME \
       --repo-name=REPO_NAME \
       --repo-owner=REPO_OWNER \
       --branch-pattern=BRANCH_PATTERN
       --build-config=BUILD_CONFIG_FILE
       --service-account=SERVICE_ACCOUNT
       --project=BUILD_PROJECT
    

    ビルド構成ファイルの変数を次の値に置き換えます。

    • TRIGGER_NAME はビルドトリガーの名前です。
    • REPO_NAME はリポジトリの名前です。
    • REPO_OWNER は、リポジトリ オーナーのユーザー名です。
    • BRANCH_PATTERN は、ビルドを呼び出すリポジトリ内のブランチ名です。
    • TAG_PATTERN は、ビルドを呼び出すリポジトリ内のタグ名です。
    • BUILD_CONFIG_FILE はビルド構成ファイルのパスです。
    • SERVICE_ACCOUNT は、/projects/PROJECT_ID/serviceAccounts/ACCOUNT_ID_OR_EMAIL 形式のサービス アカウントです。
    • BUILD_PROJECT は、ビルドを開始するプロジェクトです。

プロジェクト間の設定

ユーザー管理のサービス アカウントを使用して、サービス アカウントを作成したプロジェクトとは異なるプロジェクトでビルドを実行できるのは、iam.disableCrossProjectServiceAccountUsage 組織のポリシー制約が適用されていない場合のみです。この制約はデフォルトで適用されます。詳細

  • 次のコマンドは、その制約の適用を無効にし、必要なアクセス権を付与します。組織のポリシーに制約を設定する前に、組織はセキュリティのトレードオフを認識する必要があります。

    gcloud resource-manager org-policies disable-enforce \
       iam.disableCrossProjectServiceAccountUsage \
       --project=SERVICE_ACCOUNT_PROJECT_ID
    

    このコマンドで、SERVICE_ACCOUNT_PROJECT_ID はユーザー管理のサービス アカウントを含むプロジェクトです。

  • ユーザー管理のサービス アカウントを含むプロジェクトで、ビルドを実行するプロジェクトの Cloud Build サービス エージェントに roles/iam.serviceAccountTokenCreator ロールを付与します。

    gcloud projects add-iam-policy-binding SERVICE_ACCOUNT_PROJECT_ID \
        --member="serviceAccount:BUILD_SERVICE_AGENT" \
        --role="roles/iam.serviceAccountTokenCreator"
    

    コマンドの変数を次のように置き換えます。

    • SERVICE_ACCOUNT_PROJECT_ID: ユーザー管理のサービス アカウントを含むプロジェクトのプロジェクト ID。
    • BUILD_SERVICE_AGENT: サービス エージェントのメール ID。形式は service-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com です。ここで、BUILD_PROJECT_NUMBER はビルドを実行するプロジェクトのプロジェクト番号です。プロジェクト番号は、プロジェクト設定のページで確認できます。

制限事項:

  • Google Cloud プロジェクトは Google Cloud 組織に存在している必要があります。

  • gcloud builds submit または gcloud builds triggers create を使用して、コマンドラインで ビルドを開始する必要があります。

  • IAM ロールの付与時に service account not found エラーが発生した場合は、サービス エージェントを手動で作成する必要があります。

次のステップ