Manual

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

1. Owner on your projects/folders to be onboarded 2. Organisation Administrator on your organisation Why this is needed? Organisation Administrator role is used to create a new billing project and to assign the organisation-level IAM roles to the service account & external user. Owner role is used to enable the required APIs on the projects being onboarded.

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)

16. Cloud Logging API (logging.googleapis.com)

17. Cloud Storage API (storage.googleapis.com)

The above APIs must be enabled for each project to be onboarded.

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

1

Create the Billing Project

• Login to the Google Cloud Platform console.

• In the Project Picker menu on top, create a project with the name “OneLens Billing Project”.

  
• Using the Project Picker menu on top, open the newly created project "OneLens Billing Project".

• Using the search bar on top, search for and enable the Cloud Billing API on this project.

  
• In the same way, search for and enable the API Keys API on this project.

2

Enable Detailed Usage Export

• In the Project Picker menu on top, open the billing project created (OneLens Billing Project).

• In the left menu, open BigQuery Studio.

• In the BigQuery Explorer pane, click the 3 dots to the right of the billing project ID, and click Create dataset.

  
• In the opened Create dataset menu, enter the following data:

  • Under Dataset ID, enter “billing_export”.

  • Under Location type, select Multi-region.

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

    

    The dataset location is set to US (multiple regions in the United States) to export cost data retroactively from the start of the previous month during the initial setup.

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

  • Under Advanced options, make sure the Enable table expiry option is unchecked.

    
  • By disabling the table expiry for the BigQuery dataset, we ensure that the Single Source of Truth for your cloud costs remains intact indefinitely, enabling deep historical analysis, accurate forecasting, and audit compliance. https://docs.cloud.google.com/billing/docs/how-to/export-data-bigquery

  • Click Create data set.

• Go to Billing on the left menu.

• Under Cost management, select Billing export in the left menu.

• Enable Detailed usage cost with the following options:

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

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

  • Click Save.

    

3

Enable CUD Export

• Go to Billing on the left menu.

• Under Cost management, select Billing export in the left menu.

• Enable Committed use discounts export with the following options:

  • Under Projects, select the billing project created (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 in BigQuery Studio beforehand. The committed use discounts export requires a dataset name that does not already exist, and creates the linked dataset for you.

  This 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.

  Keep it in the same location as billing_export so the two datasets can be queried together.

4

Create the Service Account and assign permissions on the Billing project

• In the Project Picker menu on top, select the new billing project created just now (i.e., OneLens Billing Project)

• Go to IAM and admin on the left bar.

• Go to Service accounts and click on + Create service account.

  • Enter the Service account name as “OneLens Reader SA”

  • Service account ID should be automatically generated.

  • Enter the Service account description as: SA used by OneLens with read-only roles for FinOps analysis.

  • Click Create and continue.

    
• Under Permissions, search for and select the following roles:

  • BigQuery Data Viewer

  • BigQuery Metadata Viewer

  • BigQuery Job User

  • BigQuery Read Session User

• Click Continue

  
• Click Done

• On the left, under IAM and admin, select Service Accounts

• Select the service account that was created just now (i.e., OneLens Reader SA).

• Under the Principals with access tab, click + Grant access.

• Under Add principals, enter the following values

  • [e-mail] (our backend Service Account)

  • [e-mail] (our external user email)

• Under Assign Roles, add the following role:

  • Service Account Token Creator

• Click Save.

  

5

Assign Billing project roles to the External User

• In the Project Picker menu on top, select the new billing project created just now (i.e., OneLens Billing Project)

• Go to IAM and admin and click + Grant access.

• Under Add principals, enter the value of the external user email ID provided to you by the OneLens team: [e-mail]

• Under Assign Roles, add the following roles and click Save:

  • BigQuery Data Viewer

  • BigQuery Metadata Viewer

  • BigQuery Job User

    

6

Assign Organisation-level roles for Service Account and External User

• Open the Project Picker menu and select your organisation.

• Go to IAM and admin and click + Grant access.

• Under Add principals, search for and select the service account that was created (i.e., OneLens Reader SA) and the external user email (i.e., [e-mail])

• Under Assign Roles, add the following roles and click Save:

  • Organisation Viewer

  • Cloud Asset Viewer

  • Browser

  • Billing Account Viewer

    

7

Assign Organisation-level service roles to the Service Account

• Open the Project Picker menu and select your organisation.

• Go to IAM and admin and click + Grant access.

• Under Assign Roles, add the following roles:

  • Vertex AI Viewer

  • Cloud Functions Viewer

  • Cloud SQL Viewer

  • Compute Viewer

  • Kubernetes Engine Viewer

  • Dataflow Viewer

  • Dataproc Viewer

  • Cloud Filestore Viewer

  • Monitoring Viewer

  • Network Management Viewer

  • Recommender Viewer

  • Cloud Memorystore Redis Viewer

  • Service Usage Viewer

  • Logs Viewer

  • Storage Bucket Viewer

  • BigQuery Job User

  • BigQuery Metadata Viewer

  • BigQuery Resource Viewer

• Click Save.

  

  

  Granting at the organisation level covers every project in the organisation, including projects added later, so these steps are performed once.

Storage Bucket Viewer (roles/storage.bucketViewer) is a Beta role in Google Cloud. It holds two permissions, storage.buckets.get and storage.buckets.list, which let OneLens read bucket names, locations, storage classes and lifecycle configuration. It gives no access to the objects inside a bucket, and it cannot read bucket IAM policies.

Logs Viewer (roles/logging.viewer) reads log entries and log-based metric metadata in the _Required and _Default log buckets. It does not cover Data Access audit logs, which require Private Logs Viewer (roles/logging.privateLogViewer), and OneLens does not ask for that role.

8

Assign Organisation-level service roles to the External User

• Open the Project Picker menu and select your organisation.

• Go to IAM and admin and click + Grant access.

• Under Add principals, enter and select the external user email (i.e., [e-mail]).

• Under Assign Roles, add the following roles:

  • Viewer

  • BigQuery Resource Viewer

  • BigQuery Metadata Viewer

  • BigQuery Job User

• Click Save.

  

  Granting at the organisation level covers every project in the organisation, including projects added later, so these steps are performed once.

9

Create and assign the AI key inventory role

OneLens reports on the API keys and the service accounts in your organisation that can reach Vertex AI or Gemini, so they are visible alongside their cost. That needs three permissions: apikeys.keys.list returns a key's name, display name, API restrictions and creation time; cloudasset.assets.searchAllIamPolicies finds the IAM bindings that allow Vertex AI prediction; iam.serviceAccounts.get reads the ID, home project and disabled flag of each service account in those bindings.

• Open the Project Picker menu and select your organisation.

• Go to IAM and admin and select Roles in the left menu.

• Click + Create custom role and enter the following:

  • Under Title, enter OneLens AI Key Inventory.

  • Under Description, enter Lists API key metadata and Vertex AI service accounts for OneLens AI cost reporting. Cannot read key strings.

  • Under ID, enter onelensAiKeyInventory.

  • Click + Add permissions, filter for apikeys.keys.list, tick it, and click Add.

  • Repeat for cloudasset.assets.searchAllIamPolicies and iam.serviceAccounts.get. The role must list exactly these three permissions.

  • Click Create.

• Go back to IAM and admin and click + Grant access.

• Under Add principals, search for and select the service account that was created (i.e., OneLens Reader SA).

• Under Assign Roles, add the role OneLens AI Key Inventory and click Save.

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

There are predefined roles for these, API Keys Viewer and Cloud Asset Viewer, and they are deliberately not used here. API Keys Viewer also contains apikeys.keys.getKeyString, which reads live key strings. Cloud Asset Viewer also reads the configuration of every resource, including environment variables. The custom role above holds the three permissions and nothing else, so key strings and resource configuration stay unreachable.

Already integrated with OneLens? If OneLens AI Key Inventory already exists with apikeys.keys.list only, open it under IAM and admin > Roles, click Edit role, add cloudasset.assets.searchAllIamPolicies and iam.serviceAccounts.get, and click Update. The role is already granted to your service account, so nothing else changes. Also make sure the API Keys API, Cloud Asset API, Identity and Access Management (IAM) API and Cloud Resource Manager API are enabled on your billing project, which is the service account's own project.

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:

• Billing project ID

• Service Account email ID

• BigQuery dataset ID (billing_export)

• BigQuery dataset ID (cud_export)