> For the complete documentation index, see [llms.txt](https://docs.north.cloud/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.north.cloud/docs/getting-started/permissions-required/gcp-permissions.md).

# GCP permissions

Permissions North.Cloud requires from your GCP account.

## GCP IAM Permissions & Deployment

North requires carefully scoped GCP permissions so our application can access billing and usage data required by our ML engine to provide automated FinOps recommendations. We purposefully limit all permissions to the minimum necessary for your financial analysis and do not request access to your workloads or sensitive application data.

GCP uses Workload Identity Federation and BigQuery dataset sharing to provide secure, fine-grained access to only your billing data—no North service account keys required.

***

### What North <mark style="color:red;">CAN NOT</mark> do

* Read sensitive data from your workloads or databases
* View or edit network rules and security groups
* Create, modify, stop, or terminate any compute instances or other machines
* Change, copy, or export any development, test, or production data
* Access any data outside of the billing dataset you explicitly share
* Modify your GCP resources or configurations

The following sections explain the IAM permissions required and why each permission group is needed.

***

### Permission Groups Explained

#### 1. Baseline (Default) – Read-Only Billing Data via BigQuery

**Purpose:**\
These permissions allow North to read GCP billing, usage, and cost details from your BigQuery billing export. These are required for all FinOps analysis and recommendations.

**Key Roles Explained:**

* `roles/bigquery.dataViewer` (BigQuery Data Viewer):\
  Allows North to read data from tables in your billing dataset. Enables querying cost and usage tables for cost analysis.
  * **Read-only**: No permission to change, delete, or export data.
  * No access to data outside the shared dataset.
* `roles/bigquery.metadataViewer` (BigQuery Metadata Viewer):\
  Allows North to view metadata (like table structure and schema) about your billing dataset, and list billing export tables.
  * **Read-only**: Cannot modify table metadata or datasets.
  * Cannot see metadata for datasets you do not share.

**How Access Works:**

North uses GCP **Workload Identity Federation** to securely assume access to the shared dataset, without requiring service account keys.

To grant North access, you assign both roles above to the workload identity principal provided by North during onboarding. This principal follows a standard, auditable format and ensures that only North’s authorized system can access your shared data.

{% hint style="info" %}
**Minimum Required Role for sharing billing dataset:**\
To share your billing dataset, you need the **BigQuery Data Owner** (`roles/bigquery.dataOwner`) role in your account.
{% endhint %}

#### 2. Auto-Purchasing (Optional) – Buying Commitments in Your Own Account

**Purpose:**\
The baseline roles above let North read your billing data and recommend commitments. They do not let North buy anything. Autobot needs a separate set of roles before it can purchase commitments directly in your own Google Cloud account.

These roles are optional. Grant them only if you want Autobot to purchase on your behalf. North verifies them separately from the baseline roles, and a missing purchasing role does not affect your account's overall verification status.

**Key Roles Explained:**

Google Cloud splits committed use discounts across three mechanisms. Each one operates at a different scope, so each role is granted at the scope its mechanism actually works at.

| Role                                   | What it lets Autobot buy               | Grant it at                               |
| -------------------------------------- | -------------------------------------- | ----------------------------------------- |
| `roles/compute.admin`                  | Resource-based CUDs for Compute Engine | Your organization                         |
| `roles/bigquery.resourceAdmin`         | BigQuery capacity commitments          | Your designated reservation admin project |
| `roles/consumerprocurement.orderAdmin` | Spend-based CUDs and Flexible CUDs     | Your billing account                      |

North grants these to the **same principal** the baseline flow already uses. No second principal is created. Only the roles bound to it differ.

Notes on the scopes, because they are not interchangeable:

* **`roles/compute.admin` is bound at the organization**, not per project. One grant then covers every project under it, including projects you add later. A per-project grant leaves any new project uncovered until onboarding runs again.
* **`roles/bigquery.resourceAdmin` is bound on one project only.** Capacity commitments live on the single admin project you designate for reservations. Confirm that the project you name really is that admin project. Do not grant this role at the organization level, because that would give every project in the organization reservation-admin rights it does not need.
* **`roles/consumerprocurement.orderAdmin` is bound on the billing account.** Consumer Procurement orders are billing-account-scoped, so there is no organization-level equivalent. One grant covers every project linked to that billing account. North asks for this role rather than `roles/billing.admin`, which is a much broader grant this feature does not need.

***

### Security Model

**Workload Identity Federation:**

* No service account keys required. Credentials are time-limited, rotated, and cannot be reused.
* North can only access the specific dataset you share, and only with roles you choose.
* Access is logged in GCP Cloud Audit Logs, providing full traceability.
* The principal includes an attribute (`attribute.aws_role/NorthGCPReadOnlyRole`) to ensure only North’s authorized systems can assume the role.

**Data Isolation:**

* North only has access to the billing dataset you explicitly share
* Access is always read-only—North cannot modify or delete your data
* North cannot access any other projects, datasets, or resources


---

# 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.north.cloud/docs/getting-started/permissions-required/gcp-permissions.md?ask=<question>&goal=<endgoal>
```

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