# Google Cloud

> Google Cloud: fields, the check Connect and verify runs, the tools the agent gets and the read gate, from the connector catalog.

_How-to · Updated 2026-10-26 · Describes release 0.1.164_

> Generated from the connector catalog (`scripts/docs_integration_stubs.py`); the long form of every step is [Connect a datasource](/help/manage-connections.md#connect-a-datasource).

## Overview {#overview}

GCP APIs via the native gcp_request tool (service-account JWT-bearer grant; non-GET approval-gated).

Connector type key `gcp`, kind `api`, listed under Metrics, Cloud providers, Security findings, Cost / FinOps in the catalog.

## Setup {#setup}

### Before you start {#before-you-start}

- The `datasources.manage` permission; the built-in owner and operator roles carry it.
- The credential the form stores write-only (*Service account JSON key*), created on the vendor side as described under [Installation](#installation) and scoped to reads.
- The full walkthrough for this cloud, setup command included, is [Connect Google Cloud](/help/setup-gcp.md).

### Installation {#installation}

Prepare the credential on the vendor side first, scoped to reads: the platform's read gate is a floor, not a substitute for a read-only identity. The connect dialog's **Connection guidance** column names the vendor-side steps and the exact read permissions for this type.

### Configuration {#configuration}

1. Open **Settings · Data in → Data sources** and select **Connect datasource**.
2. Under **Type**, choose **Google Cloud**; the list groups the types by category.
3. Enter a **Connection name**; the connected list shows it, and per-connection agent tools are named after it.
4. Fill the fields in the table below; the optional ones marked *Advanced* sit under **Advanced connection settings**.
5. Optionally, open **Optional · describe this environment** and say in **What should AIOps know about it?** what this system is and what matters; the agent reads it as the connection's description.
6. Under **Use this connection for**, choose **Investigate only** and select **Connect and verify**.

The form shows these fields, in this order; the **API key** column is the key to send through the REST API.

| Field (portal label) | API key | Stored as |
|---|---|---|
| Service account JSON key | `service_account_json` | secret, write-only |
| Scope JSON (optional: {projects: []}) | `scope` | plain; optional; *Advanced* |

The same connection through the API (`POST /api/aiops/{tenant_id}/datasources`, `datasources.manage`; secret fields go in `secret_values`, which are stored write-only and never echoed):

```json
{
  "type_key": "gcp",
  "name": "<name>",
  "description": "<what this is and what matters, for the agent>",
  "config": {
    "scope": "<scope>"
  },
  "secret_values": {
    "service_account_json": "<service account json>"
  },
  "role": "read",
  "enabled": true
}
```

### Validation {#validation}

**Connect and verify** (and **Test** on the row) runs a service-account JWT exchanged for a token, then one Cloud Resource Manager projects list.

**You should see** a dialog titled `<connection name> is connected` with **Connected — verified from the control plane** (**Connected — verified by your private-network agent** when your agent ran the check). **Test** on the row later writes `ok · GCP token acquired — cloudresourcemanager projects list ok` into **Last test**. A green result proves the operation named in its detail and nothing more; **Audit perms** on the row reads what the credential can actually do where the vendor exposes that.

### If something fails {#if-something-fails}

The dialog shows **Needs a fix**, what to fix and the check's own detail; the row is saved either way. Select **Edit**, correct the field the detail names and save again, or select **Retry** once a cause outside the form (network, vendor-side permission) is fixed. The verdict strings **Test** can show (`failed · SSRF guard: '<host>' resolves to non-public address …`, `failed · reachable but auth rejected (HTTP 401/403)`, `failed · HTTP <code> <path>`, `failed · <field> not configured`, `failed · <ExceptionName>: …`) and what to do about each are in [Test a connection and read the failure](/help/manage-connections.md#troubleshooting), and every connection status word is in the [status and error reference](/help/status-and-error-reference.md#connection-statuses). A connected datasource the agent never uses is disabled, write-role, allow-listed to other pillars, or of a type platform staff disabled.

## Data collected {#data-collected}

What the agent gets from a `read` connection of this type:

- `gcp_request` — the native tool bound to the first Google Cloud connection (a second one gets `<name>_gcp_request`). GET plus read custom-methods (:list/:get/:query/:search) flow; writes and BigQuery SQL are refused in an investigation.

An investigation refuses a write through any connection tool, whatever the credential allows (`Investigation connections are read-only. This operation was not executed; prepare an incident change using a write connection and obtain approval.`); a fix runs through a write-role connection after approval. The exact rule table is under **The read/write gate in detail** in [Connections and remediation access](/help/read-and-write-roles.md#read-role-vs-write-role).

## Next steps {#next-steps}

- Select **Discover this connection** in the success dialog to find the services and dependencies behind it: [Launch a scan](/help/estate-harvest-and-xray.md#launch-a-scan).
- See what else each agent needs in [Choose your connection](/help/choose-your-connection.md#agent-needs).
- A fix never runs through this read connection; give approved fixes their own credential with [Write connections and approved fixes](/help/setup-write-connections.md).