> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime/google-cloud-platform.md).

# Google Cloud Platform

Connect Google Cloud to Heeler with Workload Identity Federation — no service-account keys to manage.

Heeler connects to GCP using **Workload Identity Federation (WIF)**, so there are **no service-account keys** to create or rotate — Heeler's AWS-side identity federates into a read-only service account in your environment. Connect at the **organization** level (recommended) or a single **project**.

{% hint style="success" %}
**Best practice: a dedicated project.** Create an isolated project (typically `heeler-security`) to hold the single `heeler-collector` service account. It gets read-only visibility into the project and, at the org level, across the organization.
{% endhint %}

## Setup paths

<table data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>GCP Organization Setup</strong> (recommended)</td><td>WIF + org-level read roles, via <code>gcloud</code> or Terraform.</td><td><a href="/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime/google-cloud-platform/gcp-organization-setup.md">GCP Organization Setup</a></td></tr><tr><td><strong>GCP Event Collection</strong></td><td>Near-real-time changes via a log sink → Pub/Sub.</td><td><a href="/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime/google-cloud-platform/gcp-event-collection.md">GCP Event Collection</a></td></tr><tr><td><strong>GCP Supported Services</strong></td><td>Per-service polling cadence and event support.</td><td><a href="/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime/google-cloud-platform/gcp-supported-services.md">GCP Supported Services</a></td></tr></tbody></table>

{% hint style="info" %}
**Single project?** Use the same [organization setup](/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime/google-cloud-platform/gcp-organization-setup.md) flow via **Cloud Accounts → Add Cloud Account → Google Cloud Platform**, scoping the roles and connection to that one project instead of the organization. See [Connect a single project instead](/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime/google-cloud-platform/gcp-organization-setup.md#connect-a-single-project-instead) for the differences.
{% endhint %}

## Before you start

* **Install the `gcloud` CLI** — the walkthroughs use it. Follow Google's [install guide](https://cloud.google.com/sdk/docs/install).
* **Confirm you have the required permissions.** Onboarding creates a project, service account, and Workload Identity pool/provider, and grants org-level roles. Verify you (or the GCP admin running the setup) hold the eight permissions below before you begin:

1. Sign in and find your organization ID:

```bash
gcloud auth login
gcloud organizations list
```

2. Replace `<your-org-id>` with the **ID** value (not `DIRECTORY_CUSTOMER_ID`) and test your permissions:

```bash
ACCESS_TOKEN=$(gcloud auth print-access-token)

curl -X POST \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://cloudresourcemanager.googleapis.com/v1/organizations/<your-org-id>:testIamPermissions" \
  -d '{
    "permissions": [
      "resourcemanager.projects.create",
      "resourcemanager.organizations.get",
      "resourcemanager.organizations.setIamPolicy",
      "resourcemanager.organizations.getIamPolicy",
      "serviceusage.services.enable",
      "iam.serviceAccounts.list",
      "iam.serviceAccounts.create",
      "iam.workloadIdentityPoolProviders.create"
    ]
  }'
```

The response should echo back all eight permissions. If any are missing, work with a GCP administrator to grant them before continuing.

## Setup options

* **`gcloud`** — the step-by-step CLI walkthrough (enable APIs, create the service account and WIF pool/provider, generate the Workload Identity Configuration JSON).
* **Terraform (organization setup)** — ask your Heeler contact for the published **`gcp-wif`** module. It configures organization-scoped WIF, enables the documented 11-API baseline in its dedicated project, and exposes a `workload_identity_config` output that assembles the JSON for you (`terraform output -raw workload_identity_config`). Use the manual `gcloud` path for a project-scoped connection. The manual guide also lists the additional APIs needed for complete supported-service coverage.

## Related

* [Connect Your Cloud and Runtime](/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime.md) — the spine and event-collection concept.
* [GCP Artifact Registry](/mrecEO40m5D6bt7Pq5pE/get-started/registries-and-artifacts/gcp-artifact-registry.md) — first-party package analysis reusing this connection.


---

# 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.heeler.com/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime/google-cloud-platform.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.