# Manual

{% hint style="info" %}
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?**\
Owner role is used to assign IAM roles to the service account & external user. Organisation Administrator role is used to create a new billing project.
{% endhint %}

{% hint style="warning" %}
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)*

\
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](https://cloud.google.com/apis/docs/getting-started#enabling_apis).
{% endhint %}

{% stepper %}
{% step %}

### Create the Billing project and enable cost export

* Login to the Google Cloud Platform console.

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

  <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FM083vVUkCnf44vD1OZ2O%2FScreenshot%202025-10-16%20at%204.41.06%20AM.png?alt=media&#x26;token=0f04e17c-da82-409c-a979-71c1c80a0e01" alt=""><figcaption></figcaption></figure>

* Using the `Project Picker` menu on top, open the newly created project "*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`.<br>

  <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FgLIe9sajWgK6oc7KXn8o%2FScreenshot%202025-10-16%20at%204.42.40%20AM.png?alt=media&#x26;token=4ce39f26-1e8f-4b05-9262-7128c423af3d" alt=""><figcaption></figcaption></figure>

* 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)*<br>

    <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FbfU2mK6Gal6TNNSYBcmS%2FScreenshot%202025-10-16%20at%204.44.35%20AM.png?alt=media&#x26;token=d0486f76-4305-41c7-a801-0266a1910580" alt=""><figcaption></figcaption></figure>

    <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>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.</p><p><br><a href="https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#data-availability">https://cloud.google.com/billing/docs/how-to/export-data-bigquery-tables#data-availability</a></p></div>

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

    <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FNEvYblKxcsDEoNlsTeFV%2FScreenshot%202025-10-16%20at%204.46.31%20AM.png?alt=media&#x26;token=edc1cfcd-ee7a-4a9a-bb85-63431bf10214" alt=""><figcaption></figcaption></figure>

  * <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>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.<br><br><a href="https://docs.cloud.google.com/billing/docs/how-to/export-data-bigquery?authuser=1">https://docs.cloud.google.com/billing/docs/how-to/export-data-bigquery</a></p></div>

  * 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`.<br>

    <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2Fn7fe0iDWUnwQApnquWnm%2FScreenshot%202025-10-16%20at%203.41.27%20AM.png?alt=media&#x26;token=81cde2ae-5886-4f4c-b2c6-3b7aecd15c88" alt=""><figcaption></figcaption></figure>

* Similarly, enable `Pricing` with the following options:
  * Under `Projects`, select the billing project created (*OneLens Billing Project*).
  * Under `Dataset`, select the dataset created (*billing\_export*).
  * Click `Save`.

    <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FSNBUpGKlRZ4NUyENhHny%2FScreenshot%202025-10-31%20at%206.07.55%20PM.png?alt=media&#x26;token=4bc68a52-cd82-41ba-9224-038df26e5209" alt=""><figcaption></figcaption></figure>

    <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Pricing data includes custom pricing data for your resources, if you have custom contracts with Google.<br></p><p><a href="https://docs.cloud.google.com/billing/docs/how-to/export-data-bigquery-tables/pricing-data#pricing-data-schema">https://docs.cloud.google.com/billing/docs/how-to/export-data-bigquery-tables/pricing-data#pricing-data-schema</a></p></div>

* Using the search bar on top, search for and enable the `Cloud Billing API` on this project.<br>

  <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FZ6rkUuF1rrEZeiucdSjG%2FScreenshot%202025-10-31%20at%206.16.20%20PM.png?alt=media&#x26;token=00b9f953-e88d-416f-9e92-7f7c8952e6b8" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### 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`.<br>

    <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FBcLF3b6LIAL3w07r9HAA%2FScreenshot%202025-10-31%20at%206.20.21%20PM.png?alt=media&#x26;token=2332cacf-0c65-457d-b67b-2160d894ad70" alt=""><figcaption></figcaption></figure>
* Under `Permissions`, search for and select the following roles:
  * `BigQuery Data Viewer`
  * `BigQuery Metadata Viewer`
  * `BigQuery Job User`
  * `BigQuery Read Session User`
* Click `Continue`

  <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FeHM728uL4cVpyFDLpAa6%2FScreenshot%202025-11-11%20at%203.24.37%E2%80%AFPM.png?alt=media&#x26;token=dba09365-4199-42cb-b34a-225b2ce5a3e5" alt=""><figcaption></figcaption></figure>
* 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
  * `onelens-customer-sa@astuto-prod-mum.iam.gserviceaccount.com` (our backend Service Account)
  * `onelens.finops@astuto.ai` (our external user email)
* Under `Assign Roles`, add the following role:
  * `Service Account Token Creator`
* Click `Save`.

  <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FCn0WzksWmVIJLQ6WgFEJ%2FScreenshot%202025-11-17%20at%203.41.30%E2%80%AFPM.png?alt=media&#x26;token=915c3bc0-61e2-4f92-9326-54ff6d52bc0c" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### 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: `onelens.finops@astuto.ai`
* Under Assign Roles, add the following roles and click Save:
  * `BigQuery Data Viewer`
  * `BigQuery Metadata Viewer`
  * `BigQuery Job User`<br>

    <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2F8OaSJuMWw6ztHAERx0ik%2FScreenshot%202025-10-31%20at%206.47.41%20PM.png?alt=media&#x26;token=f62414f6-7733-4fc5-b483-8b011bc56a56" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### 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., `onelens.finops@astuto.ai`)
* Under `Assign Roles`, add the following roles and click `Save`:
  * `Organisation Viewer`
  * `Cloud Asset Viewer`
  * `Browser`
  * `Billing Account Viewer`<br>

    <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FUgyeO2N1ioUu9C4AwzWc%2FScreenshot%202025-10-31%20at%206.51.32%20PM.png?alt=media&#x26;token=f220d598-cb54-4b03-b878-cac80005cbf1" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

### Assign Project/Folder-level roles to the Service Account

* Open the `Project Picker` menu and select a `project/folder` to be onboarded.
* 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`
  * `BigQuery Job User`
  * `BigQuery Metadata Viewer`
  * `BigQuery Resource Viewer`
* Click `Save`.<br>

  <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FyJ9qMHtjvdlhldhezfQn%2FScreenshot%202025-10-31%20at%207.10.54%20PM.png?alt=media&#x26;token=4074770d-556d-4998-b37e-74c0e5b1ed5b" alt=""><figcaption></figcaption></figure>

  <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2F0MGDy31zL7j67zYfD2w7%2FScreenshot%202025-10-31%20at%207.04.35%20PM.png?alt=media&#x26;token=ba3cbf88-e84b-494c-8aa4-f900b8e006fa" alt=""><figcaption></figcaption></figure>

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Repeat the above steps for <strong>all</strong> projects/folders to be onboarded.</p></div>

  <br>

{% endstep %}

{% step %}

### Assign Project/Folder-level roles to the External User

* Open the `Project Picker` menu and select a `project/folder` to be onboarded.
* Go to `IAM and admin` and click `+ Grant access`.
* Under `Add principals`, enter and select the external user email (i.e., `onelens.finops@astuto.ai`).
* Under `Assign Roles`, add the following roles:
  * `Viewer`
  * `BigQuery Resource Viewer`
  * `BigQuery Metadata Viewer`
  * `BigQuery Job User`
* Click `Save`.<br>

  <figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2Ffom78qzrkzHTcL1rriIf%2FScreenshot%202025-10-31%20at%207.19.54%20PM.png?alt=media&#x26;token=ca9646eb-6985-43a3-baf5-46aba8de9cff" alt=""><figcaption></figcaption></figure>

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Repeat the above steps for <strong>all</strong> projects/folders to be onboarded.</p></div>

{% endstep %}
{% endstepper %}

{% hint style="success" %}
**You have now&#x20;**<mark style="color:$success;">**successfully**</mark>**&#x20;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*
  {% endhint %}