# Connecting GCP Cloud Billing

Use the guide below to easily configure GCP Cloud Billing integration.

## GCP Setup

### Prerequisites

* GCP project with billing export enabled. Follow the official documentation to set up Cloud Billing data export to BigQuery

{% embed url="<https://cloud.google.com/billing/docs/how-to/export-data-bigquery-setup>" %}

{% hint style="info" %}
Standard usage cost, Detailed usage cost, and Pricing should be enabled.
{% endhint %}

* BigQuery dataset with billing export data
* Service account with the relevant permissions

### Service Account Required permissions

* BigQuery Data Viewer on the billing export dataset
* BigQuery Job User permission
* Service Account Token Creator (for impersonation)

### Variables <a href="#id-3.-environment-variables" id="id-3.-environment-variables"></a>

{% hint style="info" %}
These variables will be used in the next steps to complete your [GCP Billing profile setup](#gcp-billing-profile-configuration).
{% endhint %}

```yaml
gcp_project_id=your-project-id
gcp_billing_account=your-billing-account
gcp_service_account=your-service-account@project.iam.gserviceaccount.com
gcp_dataset_id=your-gcp-dataset-id
```

## Configuring GCP access

Follow these steps to grant PerfectScale the required permissions.

1. Create Service Account
2. Assign the roles required to enable BigQuery access:
   * `BigQuery Data Viewer`
   * `BigQuery Job User`
3. On the tab **Principals with access**, grant permissions to the principal `perfectscale-gcp-cur-accessor@psc-dev-1-000001.iam.gserviceaccount.com` with the role `Service Account Token Creator`.

<figure><img src="/files/Hn6gg1dlx3vOABr4qLt1" alt=""><figcaption><p>Principals with access</p></figcaption></figure>

{% hint style="info" %}
The customer should provide their **Service Account email** (e.g., `for-ps-access@ps-demo.iam.gserviceaccount.com`). This account will be used by PerfectScale to access the necessary billing and usage data.
{% endhint %}

## Configuring GCP Billing Export integration with GCP profile

Once everything above is in place, the next step is to create a GCP Billing profile and connect it to the cluster(s) you need.

### :tools: **How to create** GCP Billing p**rofile**

There are two options for creating a Profile: [from the Settings tab](#from-the-settings-tab) or directly [from the Overview](#from-the-overview-tab).

<figure><img src="/files/sZM5nB1vzLZlOntIILJ1" alt=""><figcaption><p>GCP Billing profile from the settings</p></figcaption></figure>

Go to the **`Settings`** tab on the left panel -> select **`Pricing`** -> click the **`+Add Profile`** button -> select **`GCP Billing`** -> name the profile and put the needed values in the relevant fields -> click **`Save`** button.

#### From the **Overview** tab

Go to the **`Overview`** tab on the left panel -> find the cluster to which you want to apply the **`Azure Profile`** and click **`gear`** button -> go to **`Customizations`** -> click on **`Add New Profile`** in the **`Pricing Profile`** drop-down list -> select **`GCP Billing`** type ->  name and configure your profile -> click the **`Save And Apply`** button -> click the **`Save Changes`** button.

<figure><img src="/files/UVXC26FTo6mo5DORa2nu" alt=""><figcaption><p>GCP Billing profile from the overview</p></figcaption></figure>

#### **GCP Billing profile configuration**

<figure><img src="/files/F5O0DGjY41dIycZAMpol" alt=""><figcaption><p>GCP Billing profile configuration</p></figcaption></figure>

`gcp_project_id:` The unique identifier for your GCP project used to interact with it across services and APIs.

`gcp_billing_account:` The unique identifier for your GCP billing account to manage billing across projects.

{% hint style="info" %}
For `gcp_billing_account`, all dashes (`-`) should be replaced with underscores (`_`).

**Example:**&#x20;

gcp\_billing\_account: '015255\_0E128B\_3125S8'
{% endhint %}

`gcp_service_account:`The service account name used to authenticate and securely interact with Google Cloud APIs on your behalf.

{% hint style="info" %}
PerfectScale uses a principal with access to the service account, and not a service account JSON key
{% endhint %}

`gcp_dataset_id:`The unique identifier assigned to a BigQuery dataset within a specific Google Cloud project.

#### Global discount for on-demand nodes

If you have a global discount for on-demand nodes (from a cloud provider or cloud reseller) that isn’t included in your custom cloud billing, you can apply it in addition to your GCP Cloud Billing integration.&#x20;

Add the following parameters to your GCP Billing profile to enable applying the globalDiscount on top of your cloud billing integration:

`global_discount` (optional block):

* `percentage` - the percentage (0–100, floats supported) of the discount to apply on top of standard on-demand node pricing. This field is required when  `global_discount` exists.
* `start_date` (optional) - the effective start date for applying the `global_discount`. If this field is empty, it defaults to today.

{% hint style="info" %}
If you change the `percentage` or `start_date`, only newly generated [Trends report](/visibility-and-optimization/trends-monitoring.md) will reflect the update. Historical reports will not update automatically. Contact <support@perfectscale.io> if you need them recalculated.
{% endhint %}

The complete configuration might look like the following **example**:

```yaml
global_discount:
  percentage: 15
  start_date: 2025-12-31
gcp_billing_account: 02DC4B_6001C0_B6C05B
gcp_dataset_id: with_random_name_us
gcp_project_id: test-4-000004
gcp_service_account: for-ps-access@test-4-000004.iam.gserviceaccount.com
```

#### Profile configuration verification

To verify if the profile is configured properly, click the **Test Integration** button.&#x20;

:green\_circle: When the configuration is correct, you will see the message **GCP Billing configured correctly**.&#x20;

:red\_circle: In case of **GCP Billing configured wrongly** response, check the **`Show integration failure details`** dropdown and fix the displayed issue(s).

### :tools: **How to apply GCP Billing profile**

#### Apply to a single cluster

To apply **`GCP Billing profile`** to the cluster, go to the **`Overview`** tab on the left-hand panel -> find the cluster to which you want to apply the  **`GCP Billing Profile`** and click **`gear dots`** button -> go to **`Customizations`** -> select the needed profile in the **`Pricing Profile`** drop-down list.&#x20;

<figure><img src="/files/NX9cM3zjB0VT3dWp6coh" alt=""><figcaption><p>Applying GCP Billing profile to a single cluster</p></figcaption></figure>

#### Apply to multiple clusters

To apply the profile to **multiple clusters** from a single view, use the **`Manage Assignments`** feature.&#x20;

Go to the **`Settings`** tab on the left-hand panel -> select the **`Pricing`** -> click the **`Manage Assignments`** button -> apply the profile for the needed clusters -> click the **`Save Changes`** button.

<figure><img src="/files/KC8qnWWkAB78ulWgbMfD" alt=""><figcaption><p>Applying GCP Billing profile to multiple clusters</p></figcaption></figure>

## Configuring GCP pricing integration with CRD

To configure GCP pricing using a Custom Resource Definition (CRD), you’ll need to define and apply a Custom Resource (CR) that specifies your unique billing conditions. This approach allows you to manage accurate pricing directly through Kubernetes manifests.&#x20;

{% hint style="warning" %}
The Custom Resource (CR) must be created in the `perfectscale` namespace.
{% endhint %}

### Setup instructions

1. Enable [BigQuery billing export](#prerequisites) in your GCP project
2. Create a service account with [BigQuery Data Viewer](#configuring-gcp-access) permissions
3. Generate a JSON key for the service account
4. Copy the service account details and billing configuration to the [CR](#cr-configuration).

#### CR configuration

```yaml
apiVersion: perfectscale.io/v1
kind: ClusterSettings
metadata:
  name: cluster-settings-main
  namespace: perfectscale
spec:
  profiles:
    pricing:
      - type: gcp_billing
        name: gcp-billing-export
        assigned: true
        value:
          global_discount:
            percentage: 7.5
            start_date: 2025-12-31
          gcp_billing_account: "your-gcp-billing-account-id-here"
          gcp_dataset_id: "billing_export_dataset"
          gcp_project_id: "your-gcp-project-id-here"
          gcp_service_account: "your-service-account@your-project.iam.gserviceaccount.com"
```

#### ⚙️ **CR parameters:**

<table><thead><tr><th width="251.94921875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>global_discount</code></strong> (optional block)</td><td>The discount to apply on top of standard on-demand node pricing.<br><code>percentage</code> - the percentage (0–100, floats supported) of the discount. This field is required when  global_discount exists.<br><code>start_date</code> (optional) - the effective start date for applying the global_discount. </td></tr><tr><td><strong><code>gcp_billing_account</code></strong></td><td>The unique identifier for your GCP billing account to manage billing across projects.</td></tr><tr><td><strong><code>gcp_dataset_id</code></strong></td><td>The unique identifier assigned to a BigQuery dataset within a specific Google Cloud project.</td></tr><tr><td><strong><code>gcp_project_id</code></strong></td><td>The unique identifier for your GCP project used to interact with it across services and APIs.</td></tr><tr><td><strong><code>gcp_service_account</code></strong></td><td>The service account principal used to authenticate and securely interact with Google Cloud APIs on your behalf.</td></tr></tbody></table>

{% hint style="warning" %}
If a `global_discount` percentage is provided without a `start_date` in the CRD profile, we won’t default to today’s date as we do for profiles configured in the UI, and the discount will not be applied. The pricing profile appears broken in the UI.
{% endhint %}


---

# Agent Instructions: 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:

```
GET https://docs.perfectscale.io/cloud-billing-integration/connecting-gcp-cloud-billing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.