Skip to main content

Connecting GCP Cloud Billing — SaaS

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

Related resource

Info

Standard usage cost, Detailed usage cost, and Pricing should be enabled.

  • 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 ​

Info

These variables will be used in the next steps to complete your GCP Billing profile setup.

gcp_project_id=your-project-id
gcp_dataset_project_id=your-dataset-project-id # optional
gcp_billing_account=your-billing-account
gcp_service_account=your-service-[email protected]
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.
PerfectScale documentation illustration

Principals with access

Info

The customer should provide their Service Account email (e.g., [email protected]). This account will be used by PerfectScale to access the necessary billing and usage data.

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 profile​

There are two options for creating a Profile: from the Settings tab or directly from the Overview.

PerfectScale documentation illustration

GCP Billing profile from the settings

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.

PerfectScale documentation illustration

GCP Billing profile from the overview

GCP Billing profile configuration​

PerfectScale documentation illustration

GCP Billing profile configuration

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

gcp_dataset_project_id: (optional) The project where the billing export dataset is located. Requires read access to the dataset. If omitted, defaults to gcp_project_id.

Caution

Set gcp_dataset_project_id when your BigQuery billing export dataset is in a different GCP project than the one used by the service account running queries. This is common in locked-down, multi-project GCP environments where billing data access and query execution permissions are managed separately.

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

Info

For gcp_billing_account, all dashes (-) should be replaced with underscores (_).

Example:

gcp_billing_account: '015255_0E128B_3125S8'

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

Info

PerfectScale uses a principal with access to the service account, and not a service account JSON key

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.

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

If you change the percentage or start_date, only newly generated Trends report will reflect the update. Historical reports will not update automatically. Contact [email protected] if you need them recalculated.

The complete configuration might look like the following example:

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.

:green_circle: When the configuration is correct, you will see the message GCP Billing configured correctly.

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

PerfectScale documentation illustration

Applying GCP Billing profile to a single cluster

Apply to multiple clusters​

To apply the profile to multiple clusters from a single view, use the Manage Assignments feature.

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.

PerfectScale documentation illustration

Applying GCP Billing profile to multiple clusters

Configuring GCP pricing integration with CR​

To configure GCP pricing, you 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.

Caution

The Custom Resource (CR) must be created in the perfectscale namespace.

Setup instructions​

  1. Enable BigQuery billing export in your GCP project
  2. Create a service account with BigQuery Data Viewer permissions
  3. Generate a JSON key for the service account
  4. Copy the service account details and billing configuration to the CR.

CR configuration​

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: "[email protected]"

⚙️ CR parameters:​

ParameterDescription
global_discount (optional block)The discount to apply on top of standard on-demand node pricing.
percentage - the percentage (0–100, floats supported) of the discount. This field is required when global_discount exists.
start_date (optional) - the effective start date for applying the global_discount.
gcp_billing_accountThe unique identifier for your GCP billing account to manage billing across projects.
gcp_dataset_idThe unique identifier assigned to a BigQuery dataset within a specific Google Cloud project.
gcp_project_idThe unique identifier for your GCP project used to interact with it across services and APIs.
gcp_service_accountThe service account principal used to authenticate and securely interact with Google Cloud APIs on your behalf.
Caution

If a global_discount percentage is provided without a start_date in the CR 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.