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

# GCP

> Connect a GCP project so Nuphos agents can operate against it via service account impersonation.

Nuphos never stores a service account key. To connect, you create a **connector
service account** in your project and let Nuphos **impersonate** it, minting
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.

<Info>
  Connecting a project requires the **Administrator** role on your team. See the
  [IAM trust model](/security/iam-trust) for the security design behind this flow.
</Info>

## Connect

In your GCP project you:

1. Enable the Cloud Resource Manager and IAM APIs.
2. Create a **connector service account** (`nuphos-connector`).
3. Grant it permission to manage your project.
4. Grant the **Nuphos platform service account** permission to impersonate it.

Then you enter the connector's email and your project ID into Nuphos. There are
two ways to do this.

### Option A — Guided setup with the agent (recommended)

In **Connectors → Connect → GCP**, choose the guided path. Nuphos opens an agent
session that runs `gcloud` **on your machine** and performs the steps below,
pausing for your approval, then prints the project ID and connector email for you
to paste in.

### Option B — Manual setup with gcloud

Run these commands yourself, replacing `PROJECT_ID` with your project:

<Steps>
  <Step title="Enable the required APIs">
    ```bash theme={null}
    gcloud services enable \
      cloudresourcemanager.googleapis.com \
      iam.googleapis.com \
      --project=PROJECT_ID
    ```
  </Step>

  <Step title="Create the connector service account">
    ```bash theme={null}
    gcloud iam service-accounts create nuphos-connector --project=PROJECT_ID
    ```
  </Step>

  <Step title="Let the connector manage your project">
    ```bash theme={null}
    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member="serviceAccount:nuphos-connector@PROJECT_ID.iam.gserviceaccount.com" \
      --role="roles/iam.infrastructureAdmin"
    ```

    `roles/iam.infrastructureAdmin` lets the connector discover and manage
    infrastructure (and enable additional APIs on demand). Scope it down later if
    your team requires tighter permissions.
  </Step>

  <Step title="Let Nuphos impersonate the connector">
    Grant the Nuphos platform service account the **Service Account Token
    Creator** role on the connector — this is what allows impersonation:

    ```bash theme={null}
    gcloud iam service-accounts add-iam-policy-binding \
      nuphos-connector@PROJECT_ID.iam.gserviceaccount.com \
      --member="serviceAccount:zeabur-byos-connector@zeabur-system.iam.gserviceaccount.com" \
      --role="roles/iam.serviceAccountTokenCreator" \
      --project=PROJECT_ID
    ```

    <Note>
      `zeabur-byos-connector@zeabur-system.iam.gserviceaccount.com` is the Nuphos
      platform identity. It is not a secret — it appears in every customer's
      policy. Use it exactly as shown.
    </Note>
  </Step>

  <Step title="Enter the details into Nuphos">
    In the GCP binding dialog, enter:

    * **Service account email:** `nuphos-connector@PROJECT_ID.iam.gserviceaccount.com`
    * **Project ID:** `PROJECT_ID`
  </Step>
</Steps>

<Warning>
  Unlike AWS, GCP connections are **not** verified at bind time. If the
  impersonation grant or project ID is wrong, the connection saves but fails the
  first time the agent uses it. Double-check the grant in step 4.
</Warning>

## In the Nuphos app

Once the project is connected, Nuphos discovers what's in it and turns it into
browsable surfaces:

* **[Kubernetes clusters](/infrastructure/clusters)** — your GKE clusters appear
  with workloads, networking, config, storage, and RBAC. Open a pod terminal,
  stream logs, and act on resources in bulk — no `kubeconfig` wrangling.
* **[Compute & access](/infrastructure/compute)** — 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](/infrastructure/resources)** — VPCs, firewall rules, and
  the networking picture around your compute.

## What the agent can do for you

The agent uses the same access to investigate and operate on your behalf. Ask it
things like:

* *"Why is the `checkout` deployment on GKE crash-looping?"* — it reads events,
  logs, and config across the cluster and walks you to 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](/agent/plans) with steps and risk for you to approve, then executes it.

When the connector's role hits a permission wall, the agent can propose a narrow
[permission grant](/security/permission-admin) for an Administrator to approve
instead of just stopping.

## Permissions & authorization

Two boundaries govern what happens through this connector:

* **Hard boundary — who can use it.** Only team **Administrators** can bind or
  remove the project, and they can restrict it to specific members with a
  [member allow-list](/security/access-control). Within a session the agent only
  holds credentials for projects you explicitly selected, and the allow-list is
  re-checked on **every** credential request.
* **Soft boundary — what the agent may do with it.** Reads run freely, but
  changes go through [plan approvals](/security/approvals), and at the command
  level [Auto-authorization](/security/auto-mode) decides which
  `gcloud`/`kubectl` commands run unattended: read-only ones auto-run,
  irreversible ones always pause for a human, and your standing rules cover the
  middle.

The outer limit is the connector service account's IAM role — the agent can
never exceed what you granted it in step 3.

### How credentials work

|                             | Value                                                         |
| --------------------------- | ------------------------------------------------------------- |
| **Trust mechanism**         | Impersonation of your `nuphos-connector` service account      |
| **Impersonating principal** | `zeabur-byos-connector@zeabur-system.iam.gserviceaccount.com` |
| **Credential lifetime**     | \~1 hour per session, minted on demand                        |
| **What's stored**           | Only the service account email and project ID — never a key   |

## Good to know

<Tip>
  Keep the connector least-privilege and let an administrator widen roles later
  through admin-approved [permission grants](/security/permission-admin), applied
  by a dedicated permission-admin service account rather than the connector itself.
</Tip>

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