Docs / Clouds

GCP

Connect a Google Cloud project so Pangea agents can work in it through service account impersonation, with no key stored.

Pangea never stores a service account key. You create a connector service account in your project and let Pangea impersonate it through workload identity federation. Pangea mints short-lived access tokens that expire after about an hour. The agent can then inspect and operate your Google Cloud resources: GKE, Compute Engine, Cloud Run, VPCs, firewalls, IAM and more.

Connect

In your GCP project you:

1. Enable the Cloud Resource Manager and IAM APIs.
2. Create a connector service account.
3. Grant it the roles it needs in the project.
4. Let Pangea impersonate it. The exact principal is shown in the dialog, because it is scoped to your team.

Then you enter the service account email and project ID into Pangea. There are two ways to do this.

Option A: guided setup with the agent

If gcloud is installed and signed in on your Mac, open Connectors → Connect → GCP and choose the guided path. Pangea opens an agent that runs gcloud on your computer with your selected local identity and performs the steps below. Review the proposed access, then let the agent register the connection when setup succeeds. Runtime prompts follow the conversation's permission mode.

Option B: manual setup with gcloud

Run these commands yourself. Replace PROJECT_ID with your project ID. This guide names the service account pangea-connector. The dialog suggests its own default name; any name works, as long as you use the same one throughout.

1. Enable the required APIs

gcloud services enable \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  --project=PROJECT_ID

2. Create the connector service account

gcloud iam service-accounts create pangea-connector --project=PROJECT_ID

3. Grant it access to the project

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:pangea-connector@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.infrastructureAdmin"

roles/iam.infrastructureAdmin (Infrastructure Admin) is a broad management role, not a read-only baseline. For inspection-only work, grant read-only roles for the services you need instead, for example Compute Viewer. Add further roles deliberately. A successful impersonation check does not prove every operation will work.

4. Let Pangea impersonate the service account

Grant Pangea the Service Account Token Creator role on the service account. This is what allows impersonation. Copy the principal from the dialog in Pangea (step "Let Pangea impersonate it"). It is unique to your team:

gcloud iam service-accounts add-iam-policy-binding \
  pangea-connector@PROJECT_ID.iam.gserviceaccount.com \
  --member="PRINCIPAL_FROM_THE_DIALOG" \
  --role="roles/iam.serviceAccountTokenCreator" \
  --project=PROJECT_ID

The principal has this form, with values filled in by the dialog:

principal://iam.googleapis.com/projects/NUMBER/locations/global/workloadIdentityPools/POOL/subject/TEAM_SUBJECT

The pool lives in Pangea's own Google Cloud project, so you create no pool or provider yourself. The subject pins the grant to your team: a token minted for another team cannot use it.

In the Cloud Console, the same grant is IAM & Admin → Service Accounts → your service account → Principals with access → Grant access. Paste the principal and pick Service Account Token Creator. The Role field opens on Service Account Admin, which is a different role.

5. Enter the details into Pangea

In the dialog, enter:

In the Pangea app

Once the project is connected, Pangea discovers what is in it:

• Kubernetes clusters: your GKE clusters, with workloads, networking, config, storage and RBAC. Open a pod terminal, stream logs and act on resources in bulk, with no kubeconfig to manage.
• Compute and access: Compute Engine instances with status and metrics, Cloud Run services and revisions, an SSH terminal to any VM, and port forwarding into private networks.
• Cloud resources: VPCs, firewall rules and the networking around your compute.

What the agent can do for you

The agent uses the same access to investigate and operate for you. Ask it things like:

• "Why is the checkout deployment on GKE crash-looping?" It reads events, logs and config across the cluster and finds the cause.
• "Which firewall rule is blocking traffic to api-internal?" It traces services, firewall rules and routes together.
• "Scale the staging node pool down over the weekend." It proposes a plan with steps and risk for you to approve, then runs it.

If a cloud operation returns an IAM denial, ask an authorized administrator for the narrowest change. See Cloud permission errors.

Permissions and authorization

Two boundaries govern this connector:

• Hard boundary: who can use it. Only team Administrators can bind or remove the project. They can restrict it to specific members with a member allow-list. Each agent only holds credentials for projects you selected, and the allow-list is checked again on every credential request.
• Soft boundary: what the agent may do with it. The service account's roles limit reads and writes. Significant cloud work uses plans. At the command level the permission mode applies: in Auto Mode, risky commands pause for your approval; in Full Access, they run without asking.

The service account's IAM roles are the outer limit. The agent can never exceed what you granted in step 3.

How credentials work

Good to know

You can connect multiple GCP projects and give each its own allow-list. Keep production tight while the whole team works with staging.