このページでは、ビルド用にユーザー指定のサービス アカウントを構成する方法について説明します。
デフォルトでは、Cloud Build は特別なサービス アカウントを使用してユーザーの代わりにビルドを実行します。このサービス アカウントは Cloud Build サービス アカウントと呼ばれ、Google Cloud プロジェクトで Cloud Build API を有効にすると自動的に作成されます。このサービス アカウントには、ビルドの更新やログの書き込みなど、さまざまな権限がデフォルトで付与されています。
デフォルトの Cloud Build サービス アカウントを使用する代わりに、ユーザーの代理でビルドを実行する独自のサービス アカウントを指定できます。プロジェクトごとに、任意の数のサービス アカウントを指定できます。複数のサービス アカウントを管理すれば、これらのサービス アカウントに実行するタスクに応じて異なる権限を付与できます。たとえば、1 つのサービス アカウントを使用してイメージをビルドして Container Registry に push し、別のサービス アカウントを使用してイメージをビルドして Artifact Registry に push できます。
始める前に
-
Cloud Build and IAM API を有効にします。
このガイドのコマンドラインの例を使用するには、Google Cloud CLI をインストールして構成します。
使用するサービス アカウントを作成したことを確認します。ビルドを実行する同じクラウド プロジェクトでアカウントを作成する必要があります。
プロジェクト間の設定
ユーザー指定のサービス アカウントが、ビルドを開始するプロジェクトとは別のプロジェクトにある場合は、必要なアクセス権を付与します。
ユーザー指定のサービス アカウントを含むプロジェクトで、
iam.disableCrossProjectServiceAccountUsage
組織ポリシーの制約が適用されていないことを確認します。この制約はデフォルトで適用されます。この組織のポリシーの制約を無効にするには、次のコマンドを実行します。SERVICE_ACCOUNT_PROJECT_ID は、ユーザー指定のサービス アカウントを含むプロジェクトです。gcloud resource-manager org-policies disable-enforce \ iam.disableCrossProjectServiceAccountUsage \ --project=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
: 形式service-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com
サービス エージェントのメール ID。ここでBUILD_PROJECT_NUMBER
は、ビルドを実行するプロジェクトのプロジェクト番号です。プロジェクト番号はプロジェクトの設定ページから取得できます。
制限事項:
- Cloud プロジェクトは Google Cloud 組織に属している必要があります。
- ビルドを開始するには、コマンドラインで
gcloud builds submit
またはgcloud beta builds triggers create
を使用する必要があります。Google Cloud Console の [トリガー] ページを使用するには、ユーザー指定のサービス アカウントとビルドトリガーが同じプロジェクト内にある必要があります。
ビルドログの設定
ビルド用に独自のサービス アカウントを指定するには、Cloud Logging またはユーザーが作成した Cloud Storage バケットにビルドログを保存する必要があります。デフォルトのログバケットにログを保存することはできません。
- Cloud Storage バケットにログを保存するには、ユーザーが作成したバケットにビルドログを保存するの手順に従います。ログバケットに保持ポリシーを設定していないことを確認します。設定されている場合、Cloud Build がビルドログをバケットに書き込めなくなる可能性があります。
- ビルドログを Logging に保存するには、サービス アカウントにログ書き込み(
roles/logging.logWriter
)ロールを割り当てます。その他の必要なサービス アカウントのロールについて詳しくは、必要な IAM 権限をご覧ください。 - ビルドログの保存場所の詳細については、ビルドログの保存場所の選択をご覧ください。
必要な IAM 権限
ユーザー指定のサービス アカウントを使用してビルドを開始するには、ビルドをリクエストするユーザーに、サービス アカウントがあるプロジェクトのサービス アカウント ユーザー(
roles/iam.serviceAccountUser
) IAM ロールが必要です。ビルドログを Logging に保存するには、サービス アカウントにログ書き込み(
roles/logging.logWriter
)ロールを割り当てます。ビルドされたイメージやアーティファクトを Artifact Registry、Container Registry、Cloud Storage に保存する場合は、必要なアクセス権を付与します。
- イメージやアーティファクトを Artifact Registry に保存するには、Artifact Registry 書き込み(
roles/artifactregistry.writer
)のロールをサービス アカウントに付与します。 - Container Registry にイメージを保存するには、ストレージ管理者(
roles/storage.admin
)のロールをサービス アカウントに付与します。 - アーティファクトを Cloud Storage に保存するには、サービス アカウントにストレージ オブジェクト管理者(
roles/storage.objectAdmin
)ロールを付与します。
- イメージやアーティファクトを Artifact Registry に保存するには、Artifact Registry 書き込み(
サービス アカウントがビルドを実行するために必要な追加の IAM 権限を付与します。たとえば、ビルドを App Engine にデプロイする必要がある場合は、サービス アカウントに App Engine 管理者のロールが必要です。ビルドで Cloud Storage バケットからソースを指定する場合は、サービス アカウントにストレージ管理者のロールが必要です。
サービス アカウントに IAM ロールを付与する方法については、リソースへのアクセスを構成するをご覧ください。
コマンドラインからのビルドの実行
プロジェクトのルート ディレクトリに、
cloudbuild.yaml
またはcloudbuild.json
という名前の Cloud Build ビルド構成ファイルを作成します。ビルド構成ファイルで、次のことを行います。
- サービス アカウントのメールアドレスを指定する
serviceAccount
フィールドを追加します。 - ビルドログを 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_NAME
は、ビルドを実行する Cloud プロジェクトの ID です。SERVICE_ACCOUNT
は、ビルドに指定するサービス アカウントのメールアドレスまたは一意の ID です。例:my-sa-name@my-project-name.iam.gserviceaccount.com
- サービス アカウントのメールアドレスを指定する
ビルド構成ファイルを使用してビルドを開始します。
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 は、ビルド構成ファイルとソースコードが現在の作業ディレクトリにあると想定します。
ビルドトリガーを使用したビルドの実行
ソース リポジトリに、
cloudbuild.yaml
またはcloudbuild.json
という名前の Cloud Build ビルド構成ファイルを作成します。ビルド構成ファイルで、次のことを行います。
- ビルドログを 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
- ビルドログを Logging に保存する場合は、
使用するサービス アカウントをビルドトリガーで次のように指定します。
Console
Cloud Console のトリガー UI を使用してビルドを実行するには、ユーザー指定のサービス アカウントがビルドトリガーと同じプロジェクト内に存在している必要があります。クロス プロジェクト サービス アカウントでトリガーを使用するには、
gcloud
ツールを使用してビルドトリガーを作成します。- ビルドトリガーを作成または編集します。
- [サービス アカウント] フィールドにサービス アカウントを指定します。サービス アカウントを指定しない場合は、デフォルトの Cloud Build サービス アカウントが使用されます。
- [作成] をクリックして、ビルドトリガーを保存します。
gcloud
ビルドトリガーを作成する際に、
--service-account
フラグを使用してサービス アカウントを指定します。サービス アカウントを指定しない場合は、デフォルトの Cloud Build サービス アカウントが使用されます。次の例は、ソースコードが GitHub にある場合にgcloud
コマンドによってビルドトリガーを作成する方法を示しています。gcloud beta 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
は、サービス アカウントに関連付けられたメールです。BUILD_PROJECT
は、ビルドを開始するプロジェクトです。
ビルドトリガーは、トリガーに関連付けられたイベントに応じてビルドを呼び出します。たとえば、ソースコードがリポジトリに push されたときにトリガーが実行されます。ビルドトリガーの詳細については、ビルドトリガーの作成と管理をご覧ください。
次のステップ
- デフォルトの Cloud Build サービス アカウントについて詳しくは、Cloud Build サービス アカウントをご覧ください。
- デフォルトの Cloud Build サービス アカウントに権限を付与する方法については、Cloud Build サービス アカウントのアクセス権を構成するをご覧ください。