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

# GCP

> Create a GCP service account for Antimetal monitoring

## Overview

This guide explains how to connect GCP to Antimetal for traces, logs, and metrics, and add optional permissions for cost optimization.

<Card title="Set up in Antimetal" icon="arrow-up-right-from-square" href="https://overlook.antimetal.com/integrations/gcp">
  Go to the GCP integration setup in the Antimetal dashboard.
</Card>

## Prerequisites

* A GCP account with permissions to create service accounts
* Access to IAM & Admin settings
* Admin access to the projects you want to monitor

## Setup

<Tabs>
  <Tab title="GCP Console">
    <Steps>
      <Step title="Create the service account">
        1. Go to [Google Cloud Console](https://console.cloud.google.com)
        2. Navigate to the project where you do your monitoring/observability work
        3. Go to **IAM & Admin > Service Accounts**
        4. Click **+ CREATE SERVICE ACCOUNT**
        5. Fill in the details:
           * **Name:** `antimetal-monitoring`
           * **ID:** `antimetal-monitoring`
           * **Description:** `Service account for Antimetal monitoring integration`
        6. Click **CREATE AND CONTINUE**
        7. Copy the created service account email address
      </Step>

      <Step title="Grant permissions to each project">
        For each project you want to monitor (including the one where you created the service account):

        1. Navigate to the target project
        2. Go to **IAM & Admin > IAM**
        3. Click **+ GRANT ACCESS**
        4. In **New principals**, enter the service account email:
           ```
           antimetal-monitoring@[YOUR-PROJECT-ID].iam.gserviceaccount.com
           ```
        5. Assign these roles:
           * `Monitoring Viewer` (roles/monitoring.viewer)
           * `Logs Viewer` (roles/logging.viewer)
           * `Cloud Trace User` (roles/cloudtrace.user)
           * `Error Reporting Viewer` (roles/errorreporting.viewer)
           * `Cloud Asset Viewer` (roles/cloudasset.viewer)
        6. Click **Save**
        7. Repeat for all projects you want to monitor
      </Step>

      <Step title="Generate the JSON key">
        1. Go to **IAM & Admin > Service Accounts**
        2. Click on your `antimetal-monitoring` service account
        3. Go to the **Keys** tab
        4. Click **ADD KEY > Create new key** with JSON format
      </Step>
    </Steps>
  </Tab>

  <Tab title="Terraform / IaC">
    <Steps>
      <Step title="Create service account and permissions">
        Create the service account in your monitoring/observability project and add IAM bindings for each project you want to monitor, granting these roles:

        * `roles/cloudasset.viewer`
        * `roles/errorreporting.viewer`
        * `roles/monitoring.viewer`
        * `roles/logging.viewer`
        * `roles/cloudtrace.user`
      </Step>

      <Step title="Generate JSON key">
        Create a JSON key for the service account. This can be done through IaC output or manually through the console.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Configure the Antimetal integration

1. Navigate to the Antimetal GCP integration page
2. Upload or paste the contents of the downloaded JSON key file
3. Specify the project IDs you granted permissions to

### Required permissions summary

The service account will have these read-only permissions across your specified projects:

| Role | Access |
| - | - |
| Monitoring Viewer | Read access to metrics and monitoring data |
| Logs Viewer | Read access to Cloud Logging data |
| Cloud Trace User | Read access to distributed tracing data |
| Error Reporting Viewer | Read access to error groups and events |
| Cloud Asset Viewer | Read access to cloud resource metadata and configurations |

## Cost optimization permissions (Beta)

These permissions help Antimetal identify unused or oversized infrastructure, assess existing commitments, and estimate potential savings using your resource usage and pricing.

To let Antimetal assess your GCP resources for cost-saving opportunities, add the permissions below to the service account created above or already connected to Antimetal. Reuse its existing JSON key and keep its current permissions.

### Project access

This role provides read-only access. It does not permit changing or deleting infrastructure.

Open **IAM & Admin > IAM** in each relevant project. Find the existing service-account email and click **Edit principal**, or select **Grant access** if it is not listed. Add the role below:

| Role | Where to grant it | What it enables |
| - | - | - |
| Recommender Viewer (`roles/recommender.viewer`) | Projects included in the cost assessment | Read Google's optimization recommendations and supporting insights. |

Include projects that purchased resource-based commitments, even if they are outside the workload projects.

### Billing account access

Billing account access adds the commitment and pricing information that project access alone cannot provide:

* **Existing API-visible supported spend-based and flexible commitment orders:** the amount purchased, commitment term, and expiry. This helps estimate future commitment costs and account for commitments you already own where coverage is available.
* **Resource-based committed use discount (CUD) recommendations and insights:** Google's assessment of additional commitment opportunities across the billing account.
* **Customer-specific prices:** discover available SKUs and their current account-specific rates to estimate savings using your pricing rather than public list prices.

This supports commitment planning and estimated savings. It does not provide historical billed spend or a forecast of your total cloud bill.

A billing account administrator must grant the following roles to your existing Antimetal service account on each billing account included in the assessment.

<Steps>
  <Step title="Create the custom role">
    Using an account with permission to create organization-level custom roles, open **IAM & Admin > Roles** and select the organization that owns the billing account. Create a custom role named **Antimetal Cost Viewer** with these permissions:

    | Permission | What it enables |
    | - | - |
    | `consumerprocurement.orders.list` | List API-visible orders, including supported spend-based and flexible commitment orders. |
    | `consumerprocurement.orders.get` | Read commitment amounts, terms, and expiry details for a supported API-visible commitment order. |
    | `billing.billingAccountPrice.get` | Read the current account-specific price for an identified supported usage-rate SKU. |
    | `billing.billingAccountSkus.list` | List account-visible SKUs and their metadata. |
    | `billing.billingAccountPrices.list` | List current account-specific SKU prices in bulk. |

    Create the role at **organization scope**, not project scope. Project-defined custom roles cannot be assigned to billing accounts. [Google's custom-role instructions](https://docs.cloud.google.com/billing/docs/how-to/custom-roles)
  </Step>

  <Step title="Assign the roles">
    For each billing account, open **Billing**, select the account, and go to **Account management**. Add the existing service-account email as a principal and assign the applicable roles below. If it is already listed, edit its access without removing existing roles.

    | Role | What it enables | Where to grant it |
    | - | - | - |
    | **Antimetal Cost Viewer** (created above) | Read supported commitment orders, discover SKUs, and retrieve customer-specific prices. | Relevant billing account. |
    | **Spend Based Commitment Recommender Viewer** (`roles/recommender.ucsViewer`, Beta) | Read spend-based CUD recommendations and supporting insights. | Relevant billing account. |
    | **Billing Account Usage Commitment Recommender Viewer** (`roles/recommender.billingAccountCudViewer`, Beta) | Read resource-based CUD recommendations and supporting insights. | Billing account when commitment discounts are shared across projects. If discounts apply only to the purchasing project, use `roles/recommender.viewer` on that project instead, as described under Project access. |
  </Step>
</Steps>

<Accordion title="What billing data is accessible">
  Order access covers the billing account and can include other Marketplace purchases, not only CUDs. Account-price reads expose customer pricing through Google's Preview Pricing API.
</Accordion>

<Accordion title="Check API access">
  In **APIs & Services > Library**, check that the following APIs are enabled. Enable only those that are missing.

  * **Recommender API** (`recommender.googleapis.com`) for recommendations and insights
  * **Cloud Commerce Consumer Procurement API** (`cloudcommerceconsumerprocurement.googleapis.com`) for existing commitment orders
  * **Cloud Billing API** (`cloudbilling.googleapis.com`) for pricing
</Accordion>

Provide Antimetal with the project IDs and billing account IDs accessible to this service account.

## Permissions and Access

The cost optimization roles add read-only resource, commitment, and pricing access to the monitoring integration. Antimetal does not use these permissions to change infrastructure or purchase commitments.

<Snippet file="security-note.mdx" />

<Snippet file="need-help.mdx" />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.