> ## Documentation Index
> Fetch the complete documentation index at: https://help.nops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud Platform - Integration Setup

> Configure Domain Restricted Sharing when required, link your GCP billing data to nOps, and grant the required service account permissions for cost visibility and optimization.

## FAQs

<AccordionGroup>
  <Accordion title="What if I don't see my billing data in BigQuery?">
    * Ensure that **Billing Export** is enabled for the correct project.
    * Check if the **dataset and table names** match what was configured in nOps.
    * Wait **up to 48 hours** for the first full dataset to appear.
  </Accordion>

  <Accordion title="Can I use customer-managed encryption keys?">
    No, Google Cloud only supports **Google-managed encryption** for billing data exports.
  </Accordion>

  <Accordion title="How often is billing data updated on nOps?">
    Billing data is refreshed **daily**, but there might be a 48-hour delay for full updates.
  </Accordion>

  <Accordion title="How long does it take for the Pricing and Detailed Resource tables to be available?">
    The tables under the **Detailed Usage Cost** and **Pricing** exports may take up to 48 hours to be created.
  </Accordion>

  <Accordion title="Do all exports need to be in the same location?">
    **Yes.** The **Detailed Usage Cost** and **Pricing** exports **must** be configured to use the same location (US or EU) and preferably the same project. Using different locations will cause integration issues with nOps.
  </Accordion>

  <Accordion title="Why do I need to grant permissions at three different levels (Organization, Billing Account, Project)?">
    Each level provides different types of access:

    * **Organization-level role** (Compute Viewer) allows nOps to list resource-based commitment objects across your organization.
    * **Billing Account-level role** is required to access billing metadata, currency information, and CUD recommendations at billing scope. This cannot be granted at the project level.
    * **Project-level roles** provide access to the BigQuery dataset containing your cost export data.

    Granting roles only at one level will result in incomplete data or integration failures.

    **Note:** Additional organization-level roles for full resource analysis (Cloud Asset Viewer, Cloud SQL Viewer, Cloud Run Viewer, Compute Recommender Viewer) are configured during the [Commitment Management setup](/gcp/commitment-management-setup), keeping the initial onboarding minimal.
  </Accordion>
</AccordionGroup>

***

## Overview

<Info>
  **Prerequisites** — Before proceeding, ensure you have completed the [GCP Integration Prerequisites](/gcp/prerequisites) including:

  * Checking if billing exports are already enabled
  * Configuring GCP billing exports (if not already enabled)

  If your organization uses **Domain Restricted Sharing**, review [Domain Restricted Sharing](#1-domain-restricted-sharing) below before granting IAM roles to the nOps service account.
</Info>

<Tip>
  **Prefer infrastructure as code?** After you create the GCP integration in nOps and copy the **nOps service account email**, you can use our open-source Terraform module instead of the console steps under [Finding Your BigQuery Dataset IDs](#finding-your-bigquery-dataset-ids), [Section 3](#3-grant-service-account-permissions-in-gcp), and [Section 4](#4-enable-required-apis). See [Terraform setup](#terraform-setup-alternative-to-console).
</Tip>

***

## 1. Domain Restricted Sharing

<Info>
  **Required check during onboarding** — The nOps GCP integration wizard includes a Domain Restricted Sharing step that you must review before proceeding. If your organization has DRS enabled, you need to add the nOps Customer ID to your allowed domains before granting any IAM roles. If DRS is not enabled, you can confirm and continue without any changes.
</Info>

If your GCP organization has **Domain Restricted Sharing** enabled (via the `iam.allowedPolicyMemberDomains` constraint), you will encounter an error when trying to grant IAM roles to the nOps service account:

```
ERROR: One or more users named in the policy do not belong to a permitted customer.
```

This security policy restricts which external identities can be granted IAM roles in your organization. To allow the nOps service account, you need to add the **nOps Google Workspace Customer ID** to your organization's allowed domains list.

<Info>
  **Required Permissions** — To modify organization policies, you need the **Organization Policy Administrator** (`roles/orgpolicy.policyAdmin`) IAM role on the organization. Contact your GCP administrator if you don't have this role.
</Info>

### Checking and Configuring Domain Restricted Sharing

During GCP onboarding, the integration wizard shows the **Domain Restricted Sharing** section in Step 1 so you can confirm whether DRS applies and act on it before granting permissions.

**To check whether DRS is enabled in your organization:**

<Steps>
  <Step title="Open the GCP Integration Wizard">
    Go to [nOps Settings → Cloud Provider Integrations](https://clara.nops.io/settings#cloud) and click the **Google Cloud Platform** card.
  </Step>

  <Step title="Review the Domain Restricted Sharing section">
    In Step 1 of the wizard, the **Domain Restricted Sharing** section displays the **nOps Customer ID** with a copy button. Check whether your GCP organization has the `iam.allowedPolicyMemberDomains` policy enabled before proceeding.
  </Step>
</Steps>

**If DRS is enabled**, add the nOps Customer ID to your allowed domains:

<Steps>
  <Step title="Go to Organization Policies">
    Navigate to <strong>IAM & Admin → Organization Policies</strong> in the <a href="https://console.cloud.google.com/iam-admin/orgPolicies" target="_blank">Google Cloud Console</a>.
  </Step>

  <Step title="Select Organization">
    Select your <strong>Organization</strong> from the project/organization selector at the top.
  </Step>

  <Step title="Find the Domain Restricted Sharing Policy">
    Search for and select the policy <strong>Domain restricted sharing</strong> (<code>iam.allowedPolicyMemberDomains</code>).
  </Step>

  <Step title="Manage Policy">
    Click <strong>Manage Policy</strong>.
  </Step>

  <Step title="Add Value">
    Under <strong>Policy values</strong>, click <strong>Add value</strong>.
  </Step>

  <Step title="Enter nOps Customer ID">
    Enter the nOps Customer ID (copy it from the GCP integration wizard in nOps).
  </Step>

  <Step title="Save">
    Click <strong>Save</strong>.
  </Step>
</Steps>

**If DRS is not enabled**, no changes are needed. Continue with the next section to link your billing data to nOps.

***

## 2. Link GCP Billing Data to nOps

Once billing exports are configured in GCP, connect them to nOps using the integration wizard.

<Steps>
  <Step title="Open Cloud Provider Integrations">
    Log in to **nOps** and go to [**Settings → Cloud Provider Integrations**](https://clara.nops.io/settings). Scroll down to the **Add a provider** section and click the **Google Cloud Platform** card.
  </Step>

  <Step title="Step 1: Configure Billing Exports and Name Your Integration">
    The **Connect Google Cloud Platform** dialog opens at **Step 1 of 2**. This step includes two required sections to review before continuing:

    1. **Domain Restricted Sharing** — The wizard displays the nOps Customer ID here. If your GCP organization has the `iam.allowedPolicyMemberDomains` policy enabled, add this Customer ID to your allowed domains now (see [Domain Restricted Sharing](#1-domain-restricted-sharing)). If DRS is not enabled in your organization, no action is needed.
    2. **Billing Export checklist** — Detailed Usage Cost, Pricing, and Committed Use Discounts must all be enabled. See [Prerequisites](/gcp/prerequisites) if you have not configured them yet.

    Enter an **Integration Name** (e.g., "My Organization GCP Integration 1") and click **Next**.
  </Step>

  <Step title="Step 2: Enter Billing Account ID and Dataset IDs">
    On **Step 2 of 2**, enter the following:

    * **Billing Account ID** — Format: `XXXXXX-XXXXXX-XXXXXX` (e.g., `0115B9-C18400-A979DC`)
    * **Detailed Usage Cost Dataset ID** — Format: `project.dataset.table` or `project.dataset`
    * **Pricing Export Dataset ID** — Format: `project.dataset.table` or `project.dataset`
    * **Committed Use Discounts Export Dataset ID** — Format: `project.dataset.table` or `project.dataset`
    * **FOCUS Dataset ID** *(optional)* — Format: `project.dataset.table` or `project.dataset`. Leave this blank if you have not enabled the FOCUS billing export.

    Use the **How to find** links next to each field for guidance on locating these values.
  </Step>

  <Step title="Create the Integration">
    Click **Create Integration**. nOps will provision a **service account** for your GCP integration. Copy the **service account email** — you will need it in the next sections to grant permissions.
  </Step>
</Steps>

<Tip>
  If the Detailed Usage Cost and Pricing exports share the same BigQuery dataset, you can use the same Dataset ID for both fields.
</Tip>

<Info>
  **About the FOCUS export** — FOCUS is an open standard that presents your cost and usage data in a common format across cloud providers. It is optional in nOps. Unlike the other exports, Google creates and names the FOCUS dataset for you: it is called `gcp_billing_immutable_<BILLING_ACCOUNT_ID>_<LOCATION>` (with dashes in your billing account ID replaced by underscores) and lives in the project you chose when you turned the export on. You can add it later from **Settings → Cloud Provider Integrations** if you enable the export after connecting.
</Info>

### Finding Your Billing Account IDs

<Steps>
  <Step title="Navigate to Billing">
    Go to **Billing** in the [GCP Console](https://console.cloud.google.com/billing). From the billing accounts list, click on the billing account name.
  </Step>

  <Step title="Copy Billing Account ID">
    Copy the Billing Account ID from the URL. The format is `XXXXXX-XXXXXX-XXXXXX` (e.g., `0115B9-C18400-A979DC`).
  </Step>
</Steps>

### Finding Your BigQuery Dataset IDs

<Steps>
  <Step title="Navigate to Billing Export">
    Go to **Billing** in the [GCP Console](https://console.cloud.google.com/billing). From the billing accounts list, click on the billing account name. Select **Billing Export** from the left-hand menu.

    Each enabled export lists its dataset here. If you turned on the FOCUS export, its dataset is the Google-managed `gcp_billing_immutable_<BILLING_ACCOUNT_ID>_<LOCATION>`.
  </Step>

  <Step title="Open Dataset in BigQuery">
    Click on the **Dataset name** link for the first export (e.g., Detailed Usage Cost). This will open BigQuery with that dataset selected.
  </Step>

  <Step title="Manage Permissions">
    In BigQuery, click on the **three vertical dots** next to the dataset name in the left panel. Hover over **Share** and select **Manage permissions**.
  </Step>

  <Step title="Grant BigQuery Data Viewer Role">
    1. In the permissions panel, click **Add Principal**.
    2. In the **New principals** field, enter the nOps service account email.
    3. In the **Select a role** dropdown, choose **BigQuery Data Viewer** (`roles/bigquery.dataViewer`).
    4. Click **Save**.
    5. Repeat for each distinct export dataset, including the FOCUS dataset (`gcp_billing_immutable_<BILLING_ACCOUNT_ID>_<LOCATION>`) if you enabled that export.
  </Step>
</Steps>

***

## 3. Grant Service Account Permissions in GCP

Once the nOps service account email is generated, grant it the required permissions **in the Google Cloud Console**—unless you are using [Terraform setup](#terraform-setup-alternative-to-console). Permissions must be granted at three different levels: **Organization**, **Billing Account**, and **Project**.

<Warning>
  The nOps service account requires permissions at multiple levels. Granting roles only at the project level will not provide sufficient access for full cost visibility and recommendations.
</Warning>

<Info>
  **Domain Restricted Sharing** — If your GCP organization has Domain Restricted Sharing enabled, you must add the nOps Customer ID to your allowed domains **before** granting any of the permissions below, or the role assignments will fail. The nOps Customer ID is shown in Step 1 of the integration wizard. See [Domain Restricted Sharing](#1-domain-restricted-sharing) above for detailed instructions.
</Info>

***

### A. Organization-Level Roles (Savings Analysis)

For the initial savings analysis setup, three organization-level roles are required. Additional roles for full resource analysis are configured later during [Commitment Management setup](/gcp/commitment-management-setup).

**Required Roles:**

| Role               | ID                         | Purpose                                        |
| ------------------ | -------------------------- | ---------------------------------------------- |
| Compute Viewer     | `roles/compute.viewer`     | List resource-based commitment objects         |
| Recommender Viewer | `roles/recommender.viewer` | Read cost recommendations at project/org scope |
| Browser            | `roles/browser`            | Enumerate projects and folders                 |

<Steps>
  <Step title="Navigate to Organization IAM">
    Go to **IAM & Admin → IAM** in the [Google Cloud Console](https://console.cloud.google.com/iam-admin/iam).
  </Step>

  <Step title="Switch to Organization">
    At the top of the page, use the project/organization selector to switch to your **Organization** (not a specific project).
  </Step>

  <Step title="Grant Access to nOps Service Account">
    Click **+ Grant Access**.
    In the **New principals** field, enter the nOps service account email (obtained from the integration setup).
    Add the following roles:

    * **Compute Viewer** (`roles/compute.viewer`)
    * **Recommender Viewer** (`roles/recommender.viewer`)
    * **Browser** (`roles/browser`)
      Click **Save**.
  </Step>
</Steps>

***

### B. Billing Account-Level Role

This role is required for currency and billing metadata validation. It must be granted directly on the Billing Account.

**Required Role:** **Billing Account Viewer** (`roles/billing.viewer`)

<Info>
  Permissions granted in the standard Project IAM page do **not** propagate to the Billing Account. You must grant this role via the Billing console or gcloud CLI.
</Info>

<Steps>
  <Step title="Navigate to Billing Account Management">
    Go to **Billing** in the [Google Cloud Console](https://console.cloud.google.com/billing). From the billing accounts list, click on the billing account name that you configured the exports for. Click **Account Management** in the left-hand menu.
  </Step>

  <Step title="Open the Info Panel">
    On the Account Management page, click **Show info panel** in the top-right corner (if the panel is not already visible). This will open a side panel titled with your billing account name.
  </Step>

  <Step title="Grant Billing Account Viewer Role">
    In the info panel on the right, click **+ Add Principal**.
    In the **New principals** field, enter the nOps service account email.
    Select the role: **Billing Account Viewer** (`roles/billing.viewer`).
    Click **Save**.
  </Step>
</Steps>

***

### C. Dataset-Level Roles (Cost Export Datasets)

These roles are required for reading BigQuery billing data and must be granted on **each dataset** that contains your cost export data:

* **Detailed Usage Cost** dataset
* **Pricing** dataset
* **Committed Use Discounts** dataset
* **FOCUS** dataset — only if you entered a FOCUS Dataset ID

**Required Role:** **BigQuery Data Viewer** (`roles/bigquery.dataViewer`)

<Info>
  **Same Dataset?** — If you configured all exports to use the **same dataset**, you only need to grant the permissions **once** on that shared dataset.
</Info>

<Steps>
  <Step title="Navigate to Billing Export">
    Go to **Billing** in the [GCP Console](https://console.cloud.google.com/billing). From the billing accounts list, click on the billing account name. Select **Billing Export** from the left-hand menu.
  </Step>

  <Step title="Open Dataset in BigQuery">
    Click on the **Dataset name** link for the first export (e.g., Detailed Usage Cost). This will open BigQuery with that dataset selected.
  </Step>

  <Step title="Manage Permissions">
    In BigQuery, click on the **three vertical dots** next to the dataset name in the left panel. Hover over **Share** and select **Manage permissions**.
  </Step>

  <Step title="Grant BigQuery Data Viewer Role">
    1. In the permissions panel, click **Add Principal**.
    2. In the **New principals** field, enter the nOps service account email.
    3. In the **Select a role** dropdown, choose **BigQuery Data Viewer** (`roles/bigquery.dataViewer`).
    4. Click **Save**.
  </Step>

  <Step title="Repeat for Other Datasets (if different)">
    If your Pricing, Committed Use Discounts, or FOCUS exports use **different datasets**, go back to the Billing Export page and repeat Steps 2-4 for each additional export dataset. The FOCUS dataset is always separate, because Google creates it for you.
  </Step>
</Steps>

***

### D. Project-Level Service Usage Role

The **Service Usage Consumer** role must be granted on the project that hosts your billing exports.

**Required Role:** **Service Usage Consumer** (`roles/serviceusage.serviceUsageConsumer`)

<Steps>
  <Step title="Navigate to IAM">
    Go to **IAM & Admin → IAM** in the [Google Cloud Console](https://console.cloud.google.com/iam-admin/iam).
  </Step>

  <Step title="Select Project">
    Select the **project that hosts your billing exports** (where your BigQuery billing export dataset is located).
  </Step>

  <Step title="Grant Service Usage Consumer Role">
    Click **+ Grant Access**.
    In the **New principals** field, enter the nOps service account email.
    Select the role: **Service Usage Consumer** (`roles/serviceusage.serviceUsageConsumer`).
    Click **Save**.
  </Step>
</Steps>

***

### E. Project-Level BigQuery Resource Viewer Role (Optional)

<Info>
  **When is this needed?** — This role is **only required** if your organization uses **flat-rate or reservation-based BigQuery pricing**. Most customers use on-demand pricing and can **skip this section**.

  **How to check:** Go to **BigQuery → Administration → Reservations** in the GCP Console. If you see reservations or capacity commitments configured, you need this role.
</Info>

The **BigQuery Resource Viewer** role allows nOps to read BigQuery reservation and slot information for capacity planning and cost optimization of flat-rate BigQuery workloads.

**Role:** **BigQuery Resource Viewer** (`roles/bigquery.resourceViewer`)

<Steps>
  <Step title="Navigate to IAM">
    Go to **IAM & Admin → IAM** in the [Google Cloud Console](https://console.cloud.google.com/iam-admin/iam).
  </Step>

  <Step title="Select Project">
    Select the **project** that contains your BigQuery billing export dataset.
  </Step>

  <Step title="Grant BigQuery Resource Viewer Role">
    Click **+ Grant Access**.
    In the **New principals** field, enter the nOps service account email.
    Select the role: **BigQuery Resource Viewer** (`roles/bigquery.resourceViewer`).
    Click **Save**.
  </Step>
</Steps>

***

## 4. Enable Required APIs

Enable the following APIs **in the Google Cloud Console** to allow nOps to collect cost and usage data for savings analysis—unless you are using [Terraform setup](#terraform-setup-alternative-to-console), which can enable them for you. **APIs only need to be enabled in the project that hosts your billing exports**, not across all projects.

**Required APIs (Savings Analysis):**

| API               | Service ID                    | Purpose                              |
| ----------------- | ----------------------------- | ------------------------------------ |
| Cloud Billing API | `cloudbilling.googleapis.com` | Billing account access and cost data |
| Recommender API   | `recommender.googleapis.com`  | Cost optimization recommendations    |

<Info>
  **Additional APIs** for full resource analysis (Cloud Asset API, Cloud Quotas API, Compute Engine API) are enabled during [Commitment Management setup](/gcp/commitment-management-setup).
</Info>

**Optional APIs:**

| API                      | Service ID                           | When Required                                        |
| ------------------------ | ------------------------------------ | ---------------------------------------------------- |
| BigQuery Reservation API | `bigqueryreservation.googleapis.com` | Only if using flat-rate/reservation BigQuery pricing |

<Steps>
  <Step title="Navigate to APIs & Services">
    Go to **APIs & Services → Library** in the [Google Cloud Console](https://console.cloud.google.com/apis/library).
  </Step>

  <Step title="Select Project">
    Select the **project that hosts your billing exports** from the top dropdown menu.
  </Step>

  <Step title="Enable Required APIs">
    Click **Enable** for each of the following APIs:

    * **Cloud Billing API** (`cloudbilling.googleapis.com`)
    * **Recommender API** (`recommender.googleapis.com`)
  </Step>
</Steps>

<Info>
  **Optional:** Only enable the **BigQuery Reservation API** if you use flat-rate or reservation-based BigQuery pricing. Most customers use on-demand pricing and can skip this.
</Info>

***

## Terraform Setup (Alternative to Console)

If you manage GCP with **Terraform** or **OpenTofu**, you can provision the organization-, billing-, project-, and BigQuery dataset-level IAM bindings for the nOps service account—and enable the required APIs on your billing export project—using the official nOps module. Use this path **instead of** the manual console instructions under [Finding Your BigQuery Dataset IDs](#finding-your-bigquery-dataset-ids) (BigQuery Data Viewer), [Section 3](#3-grant-service-account-permissions-in-gcp), and [Section 4](#4-enable-required-apis).

**Repository:** [nops-io/terraform-gcp-nops-integration](https://github.com/nops-io/terraform-gcp-nops-integration)

Complete the same prerequisites and nOps-side steps first:

1. [GCP Integration Prerequisites](/gcp/prerequisites) (including billing exports)
2. [Domain Restricted Sharing](#1-domain-restricted-sharing), if it applies to your organization
3. [Section 2](#2-link-gcp-billing-data-to-nops): create the integration in nOps, enter your billing export details, and copy the **nOps service account email**—the module uses this as an input

Follow the README in the repository for variables (for example organization ID, service account email, and billing account / dataset configuration), the `examples/basic` layout, and how to run `terraform apply` or `tofu apply`.

<Info>
  The repository README is the source of truth for Terraform inputs and optional settings. If anything conflicts with this guide, follow the module documentation for Terraform-specific behavior.
</Info>

***

## Next Steps

Once the basic integration is configured, you can optionally enable Commitment Management for automated CUD purchasing:

<Card title="GCP Commitment Management Setup" icon="chart-line" href="/gcp/commitment-management-setup">
  Configure nOps to manage GCP Committed Use Discounts (CUDs) on your behalf, including Resource-based and Spend-based commitments.
</Card>

<CardGroup cols={2}>
  <Card title="Prerequisites" icon="list-check" href="/gcp/prerequisites">
    Configure billing exports and prepare your GCP environment.
  </Card>

  <Card title="Commitment Management Setup" icon="chart-line" href="/gcp/commitment-management-setup">
    Configure automated CUD purchasing and nOps support team access.
  </Card>

  <Card title="Permissions and Resources - Savings Analysis" icon="shield-check" href="/gcp/permissions-and-resources-sa">
    Overview of all permissions and resources needed for Savings Analysis.
  </Card>

  <Card title="Permissions and Resources - Commitment Management" icon="shield-check" href="/gcp/permissions-and-resources-cm">
    Overview of all permissions and resources needed for Commitment Management.
  </Card>
</CardGroup>