Using gcloud

This guide covers the same integration as Manual, performed from the command line with the gcloud CLI instead of the Google Cloud console. The resulting service account, external user and IAM roles are identical.

The user performing the integration must have the following roles assigned:

1. Organisation Administrator on your organisation

2. Billing Account Administrator on your organisation/billing account

Why this is needed?

Organisation Administrator role is used to create the billing project and to assign the organisation-level IAM roles. Billing Account Administrator role is used to assign the Billing Account Viewer role.

Below APIs must be enabled on your projects for OneLens to be able to read usage data on the respective services:

1. Vertex AI API (aiplatform.googleapis.com)

2. Cloud Functions API (cloudfunctions.googleapis.com)

3. Cloud SQL Admin API (sqladmin.googleapis.com)

4. Compute Engine API (compute.googleapis.com)

5. Kubernetes Engine API (container.googleapis.com)

6. Dataflow API (dataflow.googleapis.com)

7. Cloud Dataproc API (dataproc.googleapis.com)

8. Cloud Filestore API (file.googleapis.com)

9. Cloud Monitoring API (monitoring.googleapis.com)

10. Network Management API (networkmanagement.googleapis.com)

11. Recommender API (recommender.googleapis.com)

12. Google Cloud Memorystore for Redis API (redis.googleapis.com)

13. Service Usage API (serviceusage.googleapis.com)

14. Cloud Asset API (cloudasset.googleapis.com)

15. BigQuery API (bigquery.googleapis.com)

APIs are enabled per project, as Google Cloud has no organisation-level equivalent, so the above must be enabled for each project to be onboarded.

For steps on how to enable APIs, please follow this link to Google's documentation.

Setting up the billing exports is the one part of this guide that cannot be done from the CLI. Google provides no gcloud command or API for configuring Cloud Billing exports to BigQuery, so that step is performed in the Google Cloud console.

Identities involved

Identity	Where it lives	Purpose
OneLens Reader SA, <service-account-id>@<billing-project-id>.iam.gserviceaccount.com	Created by you, in your billing project	Holds the read-only IAM roles OneLens uses. The address is unique to your environment, since it contains your own billing project ID.
[e-mail]	Invited into your organisation as an external user	OneLens FinOps team, console login and manual validation
[e-mail]	OneLens, in our own environment	Our platform identity. You grant it Service Account Token Creator on your OneLens Reader SA so it can generate short-lived credentials to impersonate it. It receives no other role, and no service account keys are ever shared.

The external user email above is the default. If the OneLens team provided you with a different address during onboarding, use that address in place of [e-mail] throughout this guide.

Values to collect before you start

Field	Example value
Organisation ID	111111111111
Billing Account ID	XXXXXX-XXXXXX-XXXXXX
Billing Export Project ID	onelens-billing-project

1

Set the environment variables

Before running any commands, set the shell variables below. Every command in this guide references them, so no manual substitution is required. Replace the placeholder values with your own, then run the block once in the shell you will use for the rest of the guide.

export ORG_ID="111111111111"
export BILLING_ACCOUNT_ID="XXXXXX-XXXXXX-XXXXXX"
export BILLING_PROJECT_ID="onelens-billing-project"
export SA_ID="onelens-reader-sa"

export SA_EMAIL="$SA_ID@$BILLING_PROJECT_ID.iam.gserviceaccount.com"
export LOCAL_SA="serviceAccount:$SA_EMAIL"

SA_EMAIL is derived from SA_ID and your billing project, so it is different for every customer. That derived address is the Service Account email you send to OneLens at the end of this guide.

2

Verify your variables and permissions

Run the check below before making any changes. It confirms that the variables are set and that your user holds the roles required to proceed. Nothing is modified.

Pre-flight check script

echo -e "RESOURCE\t\tVALUE/ROLE\t\t\t\tSTATUS"
echo -e "---------------------------------------------------------------"

# 1. Check Environment Variables
for var in ORG_ID BILLING_ACCOUNT_ID BILLING_PROJECT_ID; do
  if [[ -z "${!var}" ]]; then
    printf "%-23s %-40s [\e[31mMISSING\e[0m]\n" "$var" "Not Set"
  else
    printf "%-23s %-40s [\e[32mOK\e[0m]\n" "$var" "${!var}"
  fi
done

# 2. Check IAM Roles
ACCOUNT=$(gcloud config get-value account 2>/dev/null)

check_iam() {
  local cmd=$1
  local role=$2
  local label=$3
  if [[ -z "$ACCOUNT" ]]; then return; fi
  RESULT=$(eval "$cmd" --flatten='bindings[].members' \
    --filter="bindings.members:$ACCOUNT AND bindings.role:$role" \
    --format='value(bindings.role)' 2>/dev/null)
  if [[ -n "$RESULT" ]]; then
    printf "%-23s %-40s [\e[32mPRESENT\e[0m]\n" "$label" "$role"
  else
    printf "%-23s %-40s [\e[31mABSENT\e[0m]\n" "$label" "$role"
  fi
}

check_iam "gcloud organizations get-iam-policy $ORG_ID" \
  "roles/resourcemanager.organizationAdmin" "Org Admin"

check_iam "gcloud beta billing accounts get-iam-policy $BILLING_ACCOUNT_ID" \
  "roles/billing.admin" "Billing Admin"

3

Create the Billing Project

Create the project that will hold your exported billing data, link it to your billing account, and enable the APIs it needs.

gcloud projects create "$BILLING_PROJECT_ID" \
  --name="OneLens Billing Project" \
  --organization="$ORG_ID"

gcloud beta billing projects link "$BILLING_PROJECT_ID" \
  --billing-account="$BILLING_ACCOUNT_ID"

gcloud services enable bigquery.googleapis.com \
  cloudbilling.googleapis.com \
  cloudasset.googleapis.com \
  serviceusage.googleapis.com \
  apikeys.googleapis.com \
  --project="$BILLING_PROJECT_ID"

If you already have a project set up to host billing data through BigQuery, skip the project creation above and set BILLING_PROJECT_ID to that project.

4

Enable Detailed Usage Export

Create the dataset that will hold the detailed usage cost export.

bq mk --location=US --dataset "$BILLING_PROJECT_ID:billing_export"

The dataset location is set to US so that cost data can be exported retroactively from the start of the previous month during the initial setup. Table expiry is left unset, which keeps your cost history intact indefinitely.

https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#data-availability

Enabling the export must be completed in the Google Cloud console, it cannot be performed via CLI. Print the billing export URL for your account, then open it in a browser:

echo "https://console.cloud.google.com/billing/$BILLING_ACCOUNT_ID/export"

• On the BigQuery export tab, enable Detailed usage cost with the following options:

  • Under Projects, select the billing project (OneLens Billing Project).

  • Under Dataset, select the dataset created above (billing_export).

  • Click Save.

    

5

Enable CUD Export

This step must be completed in the Google Cloud console, it cannot be performed via CLI. Print the billing export URL for your account, then open it in a browser:

echo "https://console.cloud.google.com/billing/$BILLING_ACCOUNT_ID/export"

• On the BigQuery export tab, enable Committed use discounts export with the following options:

  • Under Projects, select the billing project (OneLens Billing Project).

  • Under Linked dataset name, enter a new dataset name: cud_export.

  • Under Location type, select Multi-region.

  • Under Multi-region, select US (multiple regions in the United States).

  • Click Save.

    

Do not create this dataset with bq mk. The committed use discounts export requires a dataset name that does not already exist, and creates the linked dataset for you.

The committed use discounts export writes a cud_subscriptions_export table holding the metadata of every committed use discount purchased in any project linked to this billing account: product, commitment amount, term and consumption model.

6

Create the Service Account

Create the service account in the billing project, then assign the Service Account Token Creator role, allowing the OneLens backend service account and the OneLens external user to impersonate it.

gcloud iam service-accounts create "$SA_ID" \
  --display-name="OneLens Reader SA" \
  --description="SA used by OneLens with read-only roles for FinOps analysis" \
  --project="$BILLING_PROJECT_ID"

gcloud iam service-accounts add-iam-policy-binding "$SA_EMAIL" \
  --member="serviceAccount:[e-mail]" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project="$BILLING_PROJECT_ID"

gcloud iam service-accounts add-iam-policy-binding "$SA_EMAIL" \
  --member="user:[e-mail]" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project="$BILLING_PROJECT_ID"

echo "Send this Service Account email to OneLens: $SA_EMAIL"

7

Grant Organisation-level roles

Run the following commands to grant all required organisation-level roles to both principals. Granting at the organisation covers every project in it, including projects created later. Each command is idempotent, existing bindings are never overwritten.

Grant roles to External User ([e-mail])

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/resourcemanager.organizationViewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/cloudasset.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/browser"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.resourceViewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.metadataViewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.jobUser"

Grant roles to OneLens Service Account ($LOCAL_SA)

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/resourcemanager.organizationViewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/cloudasset.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/browser"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/aiplatform.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/cloudfunctions.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/cloudsql.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/compute.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/container.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/dataflow.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/dataproc.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/file.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/monitoring.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/networkmanagement.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/recommender.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/redis.viewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/serviceusage.serviceUsageViewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.resourceViewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.metadataViewer"

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.jobUser"

Create and grant the AI key inventory role (Service Account only)

OneLens reports on the API keys in your organisation, so that keys which can reach Vertex AI or Gemini without a restriction are visible alongside their cost. That needs one permission, apikeys.keys.list, which returns a key's name, display name, API restrictions and creation time.

There is a predefined role for this, API Keys Viewer, and this guide deliberately does not use it. It also contains apikeys.keys.getKeyString, which reads live key strings. The custom role below holds apikeys.keys.list and nothing else, so the key strings in your organisation stay unreachable.

gcloud iam roles create onelensAiKeyInventory \
  --organization="$ORG_ID" \
  --title="OneLens AI Key Inventory" \
  --description="Lists API key metadata for OneLens AI cost reporting. Cannot read key strings." \
  --permissions=apikeys.keys.list

gcloud organizations add-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="organizations/$ORG_ID/roles/onelensAiKeyInventory"

This role is granted to the service account only, not to the external user.

8

Grant Billing project roles

Grant BigQuery access to the billing export project for both principals. The service account additionally needs BigQuery Read Session User for programmatic reads.

# External user
gcloud projects add-iam-policy-binding $BILLING_PROJECT_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding $BILLING_PROJECT_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.metadataViewer"

gcloud projects add-iam-policy-binding $BILLING_PROJECT_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.jobUser"

# OneLens Service Account
gcloud projects add-iam-policy-binding $BILLING_PROJECT_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding $BILLING_PROJECT_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.metadataViewer"

gcloud projects add-iam-policy-binding $BILLING_PROJECT_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding $BILLING_PROJECT_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.readSessionUser"

9

Grant Billing Account Viewer role

gcloud beta billing accounts add-iam-policy-binding $BILLING_ACCOUNT_ID \
  --member="user:[e-mail]" \
  --role="roles/billing.viewer"

gcloud beta billing accounts add-iam-policy-binding $BILLING_ACCOUNT_ID \
  --member=$LOCAL_SA \
  --role="roles/billing.viewer"

10

Verify access

After completing all steps above, run the following commands to confirm that roles have been applied correctly.

Check Organisation-level roles, External User

gcloud organizations get-iam-policy $ORG_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:[e-mail]" \
  --format="table(bindings.role)"

Check Organisation-level roles, OneLens Service Account

gcloud organizations get-iam-policy $ORG_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:$SA_EMAIL" \
  --format="table(bindings.role)"

Check Billing account and Billing project roles

gcloud beta billing accounts get-iam-policy $BILLING_ACCOUNT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:$SA_EMAIL" \
  --format="table(bindings.role)"

gcloud projects get-iam-policy $BILLING_PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:$SA_EMAIL" \
  --format="table(bindings.role)"

You have now successfully integrated your Google Cloud Platform environment with OneLens.

Please share the following values to the OneLens team to facilitate the connection on our end:

• Service Account email ID

• Billing project ID

• Billing Account ID(s)

• BigQuery dataset ID (billing_export)

• BigQuery dataset ID (cud_export)

Role summary

The table below lists every IAM role granted, the resource level at which it is applied, the member it is assigned to, and its purpose.

Both = [e-mail] and the OneLens Reader service account.

Role	Scope	Member	Purpose
roles/resourcemanager.organizationViewer	Organisation	Both	View the organisation, folder and project hierarchy
roles/cloudasset.viewer	Organisation	Both	View the asset inventory across the organisation
roles/browser	Organisation	Both	Browse the resource hierarchy without reading resource data
roles/viewer	Organisation	User only	Read-only console access for FinOps analysis
Service viewer roles*	Organisation	SA only	Read metadata for Compute, GKE, Cloud SQL and other services
roles/bigquery.resourceViewer	Organisation	Both	View BigQuery datasets, tables and jobs
roles/bigquery.metadataViewer	Organisation	Both	Read dataset and table metadata
roles/bigquery.jobUser	Organisation	Both	Run BigQuery jobs and queries
roles/billing.viewer	Billing account	Both	Read billing account costs, invoices and spend data
roles/bigquery.dataViewer	Billing project	Both	Read the data inside the billing export tables
roles/bigquery.readSessionUser	Billing project	SA only	Create read sessions for programmatic data reads
roles/iam.serviceAccountTokenCreator	Your OneLens Reader SA	OneLens backend SA and external user	Impersonate the OneLens Reader service account
onelensAiKeyInventory (custom)	Organisation	SA only	List API key metadata for AI cost reporting

*Service viewer roles are roles/aiplatform.viewer, roles/cloudfunctions.viewer, roles/cloudsql.viewer, roles/compute.viewer, roles/container.viewer, roles/dataflow.viewer, roles/dataproc.viewer, roles/file.viewer, roles/monitoring.viewer, roles/networkmanagement.viewer, roles/recommender.viewer, roles/redis.viewer and roles/serviceusage.serviceUsageViewer.

Revoking access (if required)

Access is fully reversible. The commands below remove every binding this guide created and delete the service account.

Remove Organisation-level access, External User

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/resourcemanager.organizationViewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/cloudasset.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/browser"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.resourceViewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.metadataViewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.jobUser"

Remove Organisation-level access, OneLens Service Account

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/resourcemanager.organizationViewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/cloudasset.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/browser"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/aiplatform.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/cloudfunctions.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/cloudsql.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/compute.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/container.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/dataflow.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/dataproc.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/file.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/monitoring.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/networkmanagement.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/recommender.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/redis.viewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/serviceusage.serviceUsageViewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.resourceViewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.metadataViewer"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.jobUser"

gcloud organizations remove-iam-policy-binding $ORG_ID \
  --member=$LOCAL_SA \
  --role="organizations/$ORG_ID/roles/onelensAiKeyInventory"

gcloud iam roles delete onelensAiKeyInventory \
  --organization="$ORG_ID"

Remove Billing account and Billing project access, and delete the Service Account

gcloud beta billing accounts remove-iam-policy-binding $BILLING_ACCOUNT_ID \
  --member="user:[e-mail]" \
  --role="roles/billing.viewer"

gcloud beta billing accounts remove-iam-policy-binding $BILLING_ACCOUNT_ID \
  --member=$LOCAL_SA \
  --role="roles/billing.viewer"

gcloud projects remove-iam-policy-binding $BILLING_PROJECT_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.dataViewer"

gcloud projects remove-iam-policy-binding $BILLING_PROJECT_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.metadataViewer"

gcloud projects remove-iam-policy-binding $BILLING_PROJECT_ID \
  --member="user:[e-mail]" \
  --role="roles/bigquery.jobUser"

gcloud projects remove-iam-policy-binding $BILLING_PROJECT_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.dataViewer"

gcloud projects remove-iam-policy-binding $BILLING_PROJECT_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.metadataViewer"

gcloud projects remove-iam-policy-binding $BILLING_PROJECT_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.jobUser"

gcloud projects remove-iam-policy-binding $BILLING_PROJECT_ID \
  --member=$LOCAL_SA \
  --role="roles/bigquery.readSessionUser"

gcloud iam service-accounts delete "$SA_EMAIL" \
  --project="$BILLING_PROJECT_ID"