> For the complete documentation index, see [llms.txt](https://docs.onelens.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onelens.cloud/integrations/cloud-and-cost-sources/connecting-to-gcp/manual.md).
# 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?**\
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.
{% 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)*
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](https://cloud.google.com/apis/docs/getting-started#enabling_apis).
{% endhint %}
{% stepper %}
{% step %}
### 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.
{% endstep %}
{% step %}
### 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.
* 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.
* 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`.
{% endstep %}
{% step %}
### 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.
{% 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`.
* 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
* `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`.
{% 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`
{% 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`
{% endstep %}
{% step %}
### 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.
{% hint style="info" %}
`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.
{% endhint %}
{% endstep %}
{% step %}
### 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., `onelens.finops@astuto.ai`).
* 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.
{% endstep %}
{% step %}
### Create and assign the AI key inventory role
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.
* 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 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`.
* 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`.
{% hint style="info" %}
This role is granted to the service account only, not to the external user.
{% endhint %}
{% hint style="info" %}
There is a predefined role for this, `API Keys Viewer`, and it is deliberately not used here. It also contains `apikeys.keys.getKeyString`, which reads live key strings. The custom role above holds `apikeys.keys.list` and nothing else, so the key strings in your organisation stay unreachable.
{% endhint %}
{% endstep %}
{% endstepper %}
{% hint style="success" %}
**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)*
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.onelens.cloud/integrations/cloud-and-cost-sources/connecting-to-gcp/manual.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
