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

# Connect a GCP Project to InfraAudit

> Create a service account with the required IAM roles, download a JSON key, and connect your GCP project to sync Compute, Storage, and billing data.

InfraAudit connects to Google Cloud using a service account JSON key. Once connected, it discovers Compute Engine instances, Cloud Storage buckets, BigQuery datasets, and GKE clusters, and ingests billing data from your BigQuery billing export.

## Prerequisites

Before connecting, make sure you have:

* A GCP project with the resources you want to monitor
* The `gcloud` CLI installed and authenticated, or access to the GCP console
* Permission to create service accounts and assign IAM roles in the project

## Create the service account

Run the following commands to create a service account with the minimum required roles and download a JSON key:

```bash theme={null}
# Create the service account
gcloud iam service-accounts create infraudit-reader \
  --display-name="InfraAudit Reader" \
  --project=your-project-id

# Grant the Viewer role for resource discovery
gcloud projects add-iam-policy-binding your-project-id \
  --member="serviceAccount:infraudit-reader@your-project-id.iam.gserviceaccount.com" \
  --role="roles/viewer"

# Grant BigQuery Data Viewer for billing export access
gcloud projects add-iam-policy-binding your-project-id \
  --member="serviceAccount:infraudit-reader@your-project-id.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

# Download the key file
gcloud iam service-accounts keys create infraudit-key.json \
  --iam-account="infraudit-reader@your-project-id.iam.gserviceaccount.com"
```

## Required IAM roles

| Role                        | Purpose                                                                     |
| --------------------------- | --------------------------------------------------------------------------- |
| `roles/viewer`              | Read access to Compute Engine, Cloud Storage, GKE, and other resource types |
| `roles/bigquery.dataViewer` | Read access to billing export tables in BigQuery                            |

<Info>
  The `roles/viewer` role grants broad read access across all GCP services in the project. If you prefer a narrower scope, you can replace it with a custom role that includes only the specific APIs InfraAudit needs for resource discovery.
</Info>

## Set up billing export (optional)

To ingest cost data, you need to enable BigQuery billing export in GCP first. Without this step, InfraAudit discovers resources but shows no billing data for GCP.

<Steps>
  <Step title="Open billing export settings">
    In the GCP console, go to **Billing → Billing export**.
  </Step>

  <Step title="Enable BigQuery export">
    Under **BigQuery export**, enable **Standard usage cost** export.
  </Step>

  <Step title="Choose or create a dataset">
    Choose an existing BigQuery dataset or create a new one (for example, `billing_export`) to receive the export data.
  </Step>

  <Step title="Note the project ID and dataset name">
    You'll enter these when connecting InfraAudit.
  </Step>
</Steps>

<Note>
  BigQuery billing export has a 1-to-2 day lag from GCP. Data for day D typically appears in BigQuery by the end of day D+2.
</Note>

## Connect your GCP project

<Tabs>
  <Tab title="UI">
    <Steps>
      <Step title="Open the connection dialog">
        In the sidebar, click **Cloud Providers → Connect GCP**.
      </Step>

      <Step title="Enter your credentials">
        * Paste the full contents of `infraudit-key.json` into the **Service Account JSON** field.
        * Enter the **Project ID**.
        * (Optional) Enter the **Billing BigQuery dataset** name if you configured billing export.
      </Step>

      <Step title="Connect">
        Click **Connect**. InfraAudit validates the service account and starts the initial resource sync.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    infraudit provider connect gcp \
      --service-account-key "$(cat infraudit-key.json)" \
      --project-id your-project-id \
      --billing-dataset billing_export \
      --name "GCP Production"
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST http://localhost:8080/api/v1/providers/gcp/connect \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "GCP Production",
        "serviceAccountJson": "{ \"type\": \"service_account\", ... }",
        "projectId": "your-project-id",
        "billingDataset": "billing_export"
      }'
    ```
  </Tab>
</Tabs>

## What gets synced

| Resource type            | Internal type name     |
| ------------------------ | ---------------------- |
| Compute Engine instances | `gcp_compute_instance` |
| Cloud Storage buckets    | `gcp_storage_bucket`   |
| BigQuery datasets        | `gcp_bigquery_dataset` |
| GKE clusters             | `gcp_gke_cluster`      |

Billing data is synced daily from your BigQuery billing export table.

## Security notes

* The service account JSON key is encrypted at rest using AES-GCM.
* InfraAudit never writes to your GCP project. All API calls are read-only.
* After downloading `infraudit-key.json`, delete the local file once you've entered the credentials in InfraAudit.

<Warning>
  Service account JSON keys are long-lived credentials. Treat the key file as a secret, don't commit it to source control, and rotate it periodically via **IAM → Service accounts → Manage keys**.
</Warning>