> 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/quickstart/gcp-onboarding.md).

# GCP Onboarding

{% hint style="info" %}
Based on your billing account's data volume, Google Cloud can take up to 5 days to fully migrate your data during billing export. If possible, start the billing export before you start onboarding. This speeds up the process. You can resume onboarding at any time. More from the [official GCP documentation](https://cloud.google.com/billing/docs/how-to/export-data-bigquery).
{% endhint %}

{% embed url="<https://www.loom.com/share/0f8c9a8094564787b729599e4ab26abf>" %}

{% hint style="info" %}
Prerequisites:

* [ ] If you do not have an account, we recommend that you create a free account first at [app.north.cloud](https://app.north.cloud)
* [ ] Make sure you have the minimum role `BigQuery Data Owner` within the billing account. This role lets you create and share billing datasets.
  {% endhint %}

{% stepper %}
{% step %}

### Go to the [Billing Export](https://console.cloud.google.com/billing/export)

Select the billing account you want to add and click **Edit Settings.**

<figure><img src="https://content.gitbook.com/content/eLw7hj1pxE38VmG1sYVW/blobs/P10nzRk4KuJ5trKJDtrr/Screenshot%202025-02-18%20at%205.23.03%E2%80%AFPM.png" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Enable billing export for all

You will repeat the step 3 below for all billing reports.

* [ ] Standard usage cost
* [ ] Detailed usage cost
* [ ] Pricing

<div data-full-width="false"><figure><img src="https://content.gitbook.com/content/eLw7hj1pxE38VmG1sYVW/blobs/K1O3aRwvpxuZRcNh6ASn/Screenshot%202025-02-18%20at%205.25.05%E2%80%AFPM.png" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Select a project and billing dataset

{% hint style="info" %}
Selecting a project does not prevent other projects under your billing account from being included in your dataset. The project only serves as a storage location for the data. You can create a new project and dataset, or use an existing one.
{% endhint %}

Choose the project where your data will be hosted. All projects under your billing account remain available. You can set the dataset name to any convention you prefer. You can also use our recommended name, `north_billing_dataset`.

This dataset holds your standard usage cost, detailed usage cost, and pricing exports. Note the name. You need it in the last two steps.
{% endstep %}

{% step %}

### Set up the CUD export

The Committed Use Discount (CUD) metadata export gives North.Cloud the data it needs to calculate commitment coverage and utilization.

* On the same [Billing Export](https://console.cloud.google.com/billing/export) settings page from the previous step, enable **Enable committed use discounts (CUD) metadata export**.
* Use the same project as before.

Google Cloud writes the CUD export into its own dataset. It does not write it into your billing dataset. We recommend that you name this dataset `north_cud_dataset` so it is easy to identify later. Note the name you choose. You need it in the last two steps.
{% endstep %}

{% step %}

### Enable the [recommender](https://console.cloud.google.com/active-assist/export/create)

{% hint style="info" %}
When you enable the recommender, GCP sends you a permission request. This request is the Recommender service asking for access to your other GCP services. It needs that access to provide accurate recommendations.
{% endhint %}

{% hint style="warning" %}
If you see an error like `BigQuery Data Transfer is not enabled for <project_id>`, enable the [BigQuery Data Transfer API](https://cloud.google.com/bigquery/docs/enable-transfer-service) for that project and try again. If it still fails, you may need to grant permission to the transfer service agent directly. See [GCP's troubleshooting guide](https://cloud.google.com/bigquery/docs/transfer-troubleshooting#authorization_and_permission_issues).
{% endhint %}

North.Cloud uses Google Cloud Platform (GCP) recommendations. We integrate them with our internal machine learning and AI services.

* Choose the same project and billing dataset used earlier.
* Configure the transfer. This sets how often recommendations can be generated. We generally recommend the following:
  * Name: `north_config`
  * Schedule option: Daily ( Day, 1 )
  * Start: `00:00`
  * Destination settings: the dataset you created or selected earlier
    {% endstep %}

{% step %}

### Share your datasets with North.Cloud

North.Cloud reads your exports with a read-only principal. Share every dataset that holds an export. This means your billing dataset and your CUD dataset.

For each dataset:

1. Open the dataset in BigQuery. Select **Sharing**, then **Permissions**.
2. Select **Add Principal**. Paste the Principal ID shown during onboarding.
3. Assign both roles: `BigQuery Data Viewer` and `BigQuery Metadata Viewer`.
4. Save.

Then add your project ID and billing dataset name to North.Cloud.

{% hint style="info" %}
A dataset that is not shared is the most common reason a table dropdown is empty in the next step. North.Cloud tells you when this happens, and it gives you the sharing steps in place.
{% endhint %}

{% embed url="<https://www.loom.com/share/82c307b8d45f4ca284c81a515032744d>" %}
{% endstep %}

{% step %}

### Select the corresponding tables in North.Cloud

North.Cloud lists five billing exports. Each one has a table and a dataset.

| Row in North.Cloud | GCP billing export                     |
| ------------------ | -------------------------------------- |
| Billing Header     | Standard usage cost                    |
| Billing Detail     | Detailed usage cost                    |
| Pricing            | Pricing                                |
| CUD                | Committed use discounts (CUD) metadata |
| Recommender        | Recommender export                     |

For each row, select the table from the dropdown. The **Dataset** field beside it shows which dataset North.Cloud reads that table from.

Four of the rows read from your billing dataset. CUD is the exception, because Google Cloud writes that export into its own dataset. The CUD row defaults to `north_cud_dataset`. If you named your CUD dataset something else, type that name into the **Dataset** field. North.Cloud re-checks the dataset when you leave the field, then loads the tables it finds.

Select **Use recommended** to accept the table North.Cloud detected for one row. Select **Use all recommended** to accept every detected table at once.

Select a table for every row before you continue. See Troubleshooting below if a table you expect is missing.

If a dropdown has no options, North.Cloud shows a warning under that row. The warning states the reason and offers **Check again**. If North.Cloud cannot read the dataset, the warning also offers **How to fix**, which gives the sharing steps for that dataset. See Troubleshooting below for what each message means.

{% embed url="<https://www.loom.com/share/f781553d05ea4dcb87d52e7a14ae3ef0>" %}
{% endstep %}

{% step %}

### Start saving

Once North.Cloud completes your savings and data analysis, we will send you a confirmation email. You will then have access to all our AI-powered optimization features, the same tools that help leading companies achieve top 1% cloud efficiency.
{% endstep %}
{% endstepper %}

## Troubleshooting

**A table dropdown is empty in North.Cloud**

North.Cloud shows a warning under the row. The message tells you which of three things happened.

| Message                | What it means                                     | What to do                                                                                  |
| ---------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Dataset not accessible | North.Cloud cannot read the dataset.              | Select **How to fix** for the sharing steps. Grant both roles. Then select **Check again**. |
| No tables in dataset   | North.Cloud read the dataset and found no tables. | Check the dataset name. If the export does not exist yet, create it in BigQuery.            |
| Not checked yet        | North.Cloud has not read this dataset.            | Select **Check again**.                                                                     |

A new export can take a few hours to generate its first table. If the dataset is correct and shared, wait and select **Check again**.

**`BigQuery Data Transfer is not enabled for <project_id>` when enabling the Recommender**

Enable the [BigQuery Data Transfer API](https://cloud.google.com/bigquery/docs/enable-transfer-service) for that project. If the error continues, you may need to grant permission to the transfer service agent directly. See [GCP's authorization troubleshooting guide](https://cloud.google.com/bigquery/docs/transfer-troubleshooting#authorization_and_permission_issues).

**A `cloud_pricing_export_*` or CUD table is not showing up in the dropdown**

If a table does not appear, the export is probably not enabled yet. Go back to the [Billing Export](https://console.cloud.google.com/billing/export) settings page and enable it. A new export can take a few hours to write its first table.

If you already enabled the export, check that the row points at the correct dataset. Google Cloud writes the CUD export into its own dataset. Your pricing export stays in your billing dataset.


---

# 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/quickstart/gcp-onboarding.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.