Google Cloud (GCP) Connector
- Connect your agent to Google Cloud to investigate resources using the Google Cloud CLI (
gcloud). - Use an Azure managed identity and Workload Identity Federation instead of uploading service account keys.
- Restrict federation to the selected managed identity and grant only the Google Cloud IAM permissions your investigations need.
- Test the connection, choose Read or Write access, and save the connector.
What the connector enables
The Google Cloud connector lets your agent run gcloud commands against your Google Cloud environment. Use it to inspect resources, retrieve logs, and help investigate issues. With Write access and the appropriate IAM permissions, the agent can also perform supported changes.
Available operations depend on the connector's access level, the permissions granted in Google Cloud, and your agent's run mode and tool approval policies. Selecting Write does not grant additional Google Cloud IAM permissions.
How authentication works
The connector uses your selected Azure managed identity to authenticate through Google Cloud Workload Identity Federation. Google Cloud validates the identity against the OIDC provider you configure and issues a short-lived access token.
The provider configuration determines which identity can authenticate. Google Cloud IAM role bindings determine which resources and operations that identity can access. Both must be configured correctly.
This connection grants access directly to the federated identity. You do not need to create or upload a Google Cloud service account key. Non-destructive Google Cloud actions supported through the federated identity are also supported through SRE Agent, subject to the connector's access level, Google Cloud IAM permissions, and the agent's run mode and tool approval policies.
Prerequisites
- An existing SRE Agent.
- Permission to create or update connectors on the agent.
- An Azure managed identity available in the agent's managed identity selector.
- A Google Cloud project to host the workload identity pool and provider.
- Access to Google Cloud with permission to enable the required APIs, configure workload identity pools and providers, and grant IAM access. If you use a custom role, you also need permission to create or update that role.
- The IAM, Security Token Service, and Cloud Resource Manager APIs enabled in the pool-hosting project.
- The project number of the project hosting the workload identity pool, and the project IDs of the workloads you want to investigate.
The workload identity provider resource name and federated IAM principal use the pool-hosting project's numeric project number. Commands targeting your workloads generally use the workload's project ID. These projects do not have to be the same.
Step 1: Add a Google Cloud provider connection
Open Build + setup, go to Extensions > Cloud providers, and select Create cloud connection > Google Cloud (GCP).
Start the Connect Google Cloud wizard from the Cloud providers page.
Step 2: Select the managed identity and get its details
In Complete prerequisites, select the managed identity the connector will use. The wizard displays Google Cloud setup instructions populated with values for that identity.
Keep these instructions open while you configure Google Cloud. You will need:
| Value | Where it is used |
|---|---|
| Tenant ID | The OIDC issuer URL and the federated principal's subject |
| Managed identity principal/object ID | The provider's attribute condition and the federated principal's subject; this is not the managed identity client ID |
| Allowed audience | The fixed SRE Agent application ID: 59f0a04a-b322-4310-adc9-39ac41e9631e |
| Subject | Your tenant ID and managed identity principal ID joined with :: |
Step 3: Set up identity federation in Google Cloud
Use the setup script to configure federation for your selected managed identity.
Or configure manually in the Google Cloud console using the instructions below:
With the managed identity details available, switch to the Google Cloud console. Complete the workload identity provider and IAM setup before returning to the connector wizard.
Create or select a workload identity pool
- Select the Google Cloud project that will host the pool.
- Open IAM & Admin > Workload Identity Federation.
- Create a workload identity pool for SRE Agent, or select an existing pool.
- Note the pool ID and the hosting project's numeric project number.
Configure the OIDC provider
Create an OpenID Connect (OIDC) provider in the pool, or update the provider you intend to use for this connection.
The examples use the provider display name SREAgentProvider and provider ID sre-agent-provider.
Use the values shown in the SRE Agent wizard:
| Setting | Value |
|---|---|
| Issuer URL | https://login.microsoftonline.com/<TENANT_ID>/v2.0 |
| Allowed audiences | 59f0a04a-b322-4310-adc9-39ac41e9631e |
| Attribute mapping: Google attribute | google.subject |
| Attribute mapping: OIDC expression | assertion.tid+'::'+assertion.oid |
| Attribute condition | assertion.oid=='<MI_PRINCIPAL_ID>' |
Replace <TENANT_ID> and <MI_PRINCIPAL_ID> with the values for your selected managed identity. Enter the mapping's attribute name and expression in their respective fields, then save the provider.
Keep the identity-specific attribute condition and the exact allowed audience. Do not replace the principal ID with the managed identity's client ID, or grant access to every identity in the pool.
Grant IAM access
Grant access directly to the federated managed identity. Its IAM principal has this format:
principal://iam.googleapis.com/projects/<POOL_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/subject/<TENANT_ID>::<MI_PRINCIPAL_ID>
Replace each placeholder:
| Placeholder | What to use |
|---|---|
<POOL_PROJECT_NUMBER> | The numeric project number of the project hosting the pool, not a project ID |
<POOL_ID> | The workload identity pool ID |
<TENANT_ID> | The selected Azure managed identity's tenant ID |
<MI_PRINCIPAL_ID> | The selected managed identity's principal/object ID |
For each Google Cloud project you want the agent to investigate:
- Open IAM & Admin > IAM and select Grant access.
- Enter the full federated IAM principal as the new principal.
- Select roles that grant the resource permissions needed for your investigations, or use a custom role containing those permissions.
- Save the role binding.
Include resourcemanager.projects.get on each target project so it can appear in the connector's project-list check. Add the relevant resource permissions for your use case, such as reading Compute Engine instances or Cloud Logging entries. Enable the corresponding Google Cloud service APIs for the services you intend to use.
Start with read permissions at the narrowest practical scope. Do not grant Owner or Editor simply to make the connection test pass. Grant write permissions only when you intend the agent to perform those operations, and configure tool approvals accordingly.
Copy the full workload identity provider ID
Copy the provider's full resource name for the next step. It has this format:
projects/<POOL_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/providers/<PROVIDER_ID>
For example:
projects/123456789012/locations/global/workloadIdentityPools/sre-agent-pool/providers/sre-agent-provider
Use the full resource name, not just the provider's display name or provider ID.
If you use the Google Cloud CLI, you can retrieve the full name with:
gcloud iam workload-identity-pools providers describe sre-agent-provider --project=YOUR_POOL_PROJECT_ID --location=global --workload-identity-pool=sre-agent-pool --format="value(name)"
Replace the project ID, pool ID, and provider ID with your own values.
Step 4: Configure and test the connection
Return to the SRE Agent wizard and select Next to open Choose permissions + connect.
| Field | What to enter |
|---|---|
| Connection name | A unique name of 2-32 letters, digits, or hyphens, starting with a letter and ending with a letter or digit; for example, gcp-production. Names must not begin with the reserved prefixes system-mcp or ev2-mcp (case-insensitive). |
| Workload identity provider ID | The full provider resource name copied in the previous step |
Enter the connection details, test the connection, and choose the access level before connecting.
Select Test connection and wait for a successful result. You must test successfully before saving. If you change the connection name, managed identity, or workload identity provider ID, run the test again.
The test runs gcloud projects list. A successful test confirms that the project-list request completed; it does not verify access to every project, resource, or operation. A project with no IAM access for this identity may be absent from the results even when the test succeeds.
A successful test displays Test completed. Select Connect provider to complete the cloud connection.
Step 5: Choose the access level and connect
On the same Choose permissions + connect step, select the appropriate Access level:
| Access level | What it allows |
|---|---|
| Read (default) | Supported read commands to view and inspect resources, without making changes |
| Write | Supported read and write commands, subject to Google Cloud IAM permissions, the agent's run mode, and tool approval policies |
Start with Read for investigations. Write does not override ReadOnly run mode or bypass approval policies. In Review mode, review and approve write commands when prompted.
Select Connect provider to save the connection.
Step 6: Confirm the connector is connected
The wizard returns to Cloud providers. Find your connection under Google Cloud (GCP) and confirm that its status is Connected. Select Refresh to check the latest status.
Connected Google Cloud connections appear in their own group on the Cloud providers page. The names shown are examples from the screenshot environment.
To update an existing connection, select it and choose Edit. Review its managed identity, provider ID, and access level, test the connection, and select Save changes. Updating the connector does not update its Google Cloud IAM role bindings.
Step 7: Use SRE Agent chat for Google Cloud resources
You can now use SRE Agent chat to investigate resources in the connected Google Cloud environment. Specify the connection name, project ID, resource, region or zone, and time window so the agent can focus its investigation.
For example:
Using my gcp-production connection, list the Compute Engine instances
in project <PROJECT_ID>.
Using my gcp-production connection, investigate Cloud Run errors
for service <SERVICE_NAME> in project <PROJECT_ID>, region <REGION>,
over the last hour.
Replace the example connection name and resource details with your own. The agent can access only the resources and operations allowed by Google Cloud IAM and your agent's access and approval settings.
Troubleshooting
| Symptom | What to check |
|---|---|
| Google Cloud connection option is unavailable | Confirm your deployment exposes the Cloud providers page. |
| Identity-specific values are missing | Select an available managed identity and wait for its details to load. Do not configure federation with placeholder values. |
| Cannot test or save | Confirm you have permission to write connectors, the connection name is valid and unique, and the full provider resource name is correctly formatted. |
| Connection test fails | Verify the selected managed identity, issuer URL, fixed audience, subject mapping, identity condition, and IAM principal binding. Check that the relevant Google Cloud APIs are enabled. |
| Test succeeded but saving is disabled after editing a field | Run Test connection again for the updated configuration. |
| A project is missing from the results | Check IAM bindings on that workload project. The pool-hosting project does not automatically grant access to other projects. |
| Connection works but a resource operation is denied | Check the resource's IAM permissions, the connector's Read/Write selection, the agent's run mode, and tool approval policies. A successful connection test does not verify all resource permissions. |
| Write commands are blocked | Confirm both Write access on the connector and the required write permissions in Google Cloud. Use a run mode that permits writes and complete any required approval. |
Related capabilities
- Connectors: How connectors give your agent access to external systems.
- Tool Access Policies: Control which tool operations require approval.
- Run modes: Choose how the agent can investigate and take action.
- Google Cloud Workload Identity Federation: Google Cloud guidance for configuring external workload identities. Use the SRE Agent-specific issuer, audience, and mapping values in this guide.
- Google Cloud principal identifiers: Reference for federated IAM principal formats.