diff --git a/website/docs/docs/guides/migration-guide/upgrading-to-0-18-0.md b/website/docs/docs/guides/migration-guide/upgrading-to-0-18-0.md index 7b9efbd1cf7..c21186a143c 100644 --- a/website/docs/docs/guides/migration-guide/upgrading-to-0-18-0.md +++ b/website/docs/docs/guides/migration-guide/upgrading-to-0-18-0.md @@ -50,3 +50,4 @@ Please be aware of the following changes in v0.18.0. While breaking, we do not e - [list (ls)](commands/list) - [Redshift profile](redshift-profile#specifying-an-iam-profile) - [`asset-paths` config](asset-paths) (also updated [dbt_project.yml](dbt_project.yml.md) and the [description](description) docs to match) +- [`impersonate_service_account` in the BigQuery profile configuration](https://docs.getdbt.com/reference/warehouse-profiles/bigquery-profile#service-account-impersonation) diff --git a/website/docs/reference/warehouse-profiles/bigquery-profile.md b/website/docs/reference/warehouse-profiles/bigquery-profile.md index a85017c4d65..60a87ec2af8 100644 --- a/website/docs/reference/warehouse-profiles/bigquery-profile.md +++ b/website/docs/reference/warehouse-profiles/bigquery-profile.md @@ -215,6 +215,54 @@ Database Error in model debug_table (models/debug_table.sql) compiled SQL at target/run/bq_project/models/debug_table.sql ``` +### Service Account Impersonation +New in v0.18.0 +You may want your models to be built using a dedicated service account that has +elevated access to read or write data to the specified project or dataset. +Typically, this requires you to create a service account key for running under +development or on your CI server. By specifing the email address of the service +account you want to build models as, you can use [Application Default Credentials]( +https://cloud.google.com/sdk/gcloud/reference/auth/application-default) or the +service's configured service account (when running in GCP) to assume the identity +of the service account with elevated permissions. + +This allows you to reap the advantages of using federated identity for developers +(via ADC) without needing to grant individual access to read and write data +directly, and without needing to create separate service account and keys for +each user. It also allows you to completely eliminate the need for service +account keys in CI as long as your CI is running on GCP (Cloud Build, Jenkins, +GitLab/Github Runners, etc). + +To use this functionality, first create the service account you want to +impersonate. Then grant users that you want to be able to impersonate +this service account the `roles/iam.serviceAccountTokenCreator` role on +the service account resource. Then, you also need to grant the service +account the same role on itself. This allows it to create short-lived +tokens identifying itself, and allows your human users (or other service +accounts) to do the same. More information on this scenario is available +[here](https://cloud.google.com/iam/docs/understanding-service-accounts#directly_impersonating_a_service_account). + +Once you've granted the appropriate permissions, you'll need to enable +the [IAM Service Account Credentials API](https://console.cloud.google.com/apis/library/iamcredentials.googleapis.com). +Enabling the API and granting the role are eventually consistent operations, +taking up to 7 minutes to fully complete, but usually fully propagating within 60 +seconds. Give it a few minutes, then add the `impersonate_service_account` +option to your BigQuery profile configuration: + +```yaml +my-profile: + target: dev + outputs: + dev: + type: bigquery + method: oauth + project: abc-123 + dataset: my_dataset + impersonate_service_account: dbt-runner@yourproject.iam.gserviceaccount.com +``` + +For a general overview of this process, see the official docs for [Creating Short-lived Service Account Credentials](https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials). + ## Required permissions BigQuery's permission model is dissimilar from more conventional databases like Snowflake and Redshift. The following permissions are required for dbt user accounts: