Grant Yuki access to your BigQuery account

This guide explains how to grant Yuki secure access to your BigQuery organization using a dedicated service account.

Yuki will use this service account to discover projects, analyze metadata, and execute optimization workflows.

💡 Note: You don’t need to run these steps manually - our onboarding wizard will walk you through each step.

---

1. Create a service account

Yuki uses a dedicated Google Cloud service account to access your BigQuery environment.

if ! gcloud iam service-accounts list \
      --project "<PROJECT_NAME>" \
      --format="value(email)" \
      | grep -q "^yuki-sa@<PROJECT_NAME>.iam.gserviceaccount.com$"; then
    gcloud iam service-accounts create "yuki-sa" \
        --project "<PROJECT_NAME>" \
        --display-name "Yuki BigQuery access (org-level)"
else
    echo "Service account yuki-sa already exists, skipping creation."
fi

---

2. Grant organization-level permissions

To allow Yuki to operate across your organization, the Yuki service account is granted a limited set of organization-level IAM roles.

These permissions allow Yuki to:

1. List projects, reservations, assignments, and query job history for optimization

2. Create and manage Yuki’s projects and reservations

3. List users from other projects and grant them access to Yuki’s resources

Grant the following roles at the organization level:

gcloud organizations add-iam-policy-binding <ORGANIZATION_ID> \
  --member "serviceAccount:yuki-sa@<PROJECT_NAME>.iam.gserviceaccount.com" \
  --role roles/bigquery.metadataViewer

gcloud organizations add-iam-policy-binding <ORGANIZATION_ID> \
  --member "serviceAccount:yuki-sa@<PROJECT_NAME>.iam.gserviceaccount.com" \
  --role roles/bigquery.jobUser

gcloud organizations add-iam-policy-binding <ORGANIZATION_ID> \
  --member "serviceAccount:yuki-sa@<PROJECT_NAME>.iam.gserviceaccount.com" \
  --role roles/resourcemanager.organizationViewer

gcloud organizations add-iam-policy-binding <ORGANIZATION_ID> \
  --member "serviceAccount:yuki-sa@<PROJECT_NAME>.iam.gserviceaccount.com" \
  --role roles/iam.serviceAccountViewer

gcloud organizations add-iam-policy-binding <ORGANIZATION_ID> \
  --member "serviceAccount:yuki-sa@<PROJECT_NAME>.iam.gserviceaccount.com" \
  --role roles/resourcemanager.projectCreator

gcloud organizations add-iam-policy-binding <ORGANIZATION_ID> \
  --member "serviceAccount:yuki-sa@<PROJECT_NAME>.iam.gserviceaccount.com" \
  --role roles/bigquery.resourceEditor

---

3. Enable required APIs

Enable the Cloud Resource Manager API in the project hosting the Yuki service account:

gcloud services enable cloudresourcemanager.googleapis.com \
  --project <PROJECT_NAME>

---

4. Generate a service account key

Generate a service account key for secure authentication with Yuki:

gcloud iam service-accounts keys create "yuki-sa-key.json" \
    --iam-account "yuki-sa@<PROJECT_NAME>.iam.gserviceaccount.com" \
    --project "<PROJECT_NAME>"

echo "Service account key saved to: yuki-sa-key.json"

---

5. Upload the key to Yuki

1. Download the generated file:

cloudshell download ~/[email protected]

1. Return to the Yuki onboarding wizard

2. Upload the key in the Upload Service Account Key step

After granting these permissions and uploading the key, Yuki will create and manage a dedicated project to enable automatic query routing and optimization.

---

6. Connect the Billing Account to Yuki

Yuki needs access to a billing account in order to create and manage BigQuery reservations in a dedicated Yuki project. In this step, you’ll connect a billing account directly to the Yuki-managed project.

What you need to do:

1. In the Yuki onboarding wizard, click Connect Billing Account to Yuki Project. You’ll be redirected to Google Cloud Console "Set Billing Account" page

2. Select the billing account you want Yuki-Project to use

Once the billing account is connected, grant the required permissions to allow Yuki to use the BigQuery Reservation API:

gcloud projects add-iam-policy-binding <YUKI_PROJECT_ID> \
  --member="serviceAccount:yuki-sa@<YUKI_HOSTING_PROJECT>.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageAdmin"

gcloud services enable bigquery.googleapis.com \
  --project=<YUKI_PROJECT_ID>

gcloud services enable bigqueryreservation.googleapis.com \
  --project=<YUKI_PROJECT_ID>

After linking the billing account and granting the required permissions, check the checkbox to confirm completion and continue.

After completing this step, Yuki will automatically create the required BigQuery reservation in the Yuki project. This may take a few minutes.

---

Summary

After completing this guide, Yuki will have:

• A dedicated service account for BigQuery access

• Dedicated Organization-level permissions to discover and optimize resources

• Secure key-based authentication to your GCP environment

• A dedicated Yuki project and reservation for optimized routing

Once this setup is complete, Yuki will automatically provision a fully hosted Yuki Proxy, enabling optimized queries routing.

---

Next Step

Define projects for optimization:

→ Enable Optimization For Projects