# Google Cloud Platform

> Connect your own GCP project to use Vertex AI, BigQuery, Cloud Storage, and other GCP services with your own quotas and billing.

**URL:** https://inference.sh/docs/credentials/gcp
**Last updated:** 2026-09-24

---

Connect your own GCP project to use Vertex AI, BigQuery, Cloud Storage, and other GCP services with your own quotas and billing.

## How It Works

inference shell uses **Workload Identity Federation (WIF)** - the secure, keyless way to authenticate:

- **No credentials stored** on inference shell
- Tokens are generated on-demand and expire in 1 hour
- You control access via IAM
- Full audit trail in Cloud Audit Logs
- Revoke access anytime by deleting the WIF provider

## Prerequisites

1. **gcloud CLI** - [Install here](https://cloud.google.com/sdk/docs/install)
2. **Logged in** - Run `gcloud auth login` if you haven't already
3. **A GCP project** with billing enabled

## Quick Setup (Recommended)

Run our setup script - it handles everything automatically:

```bash
curl -sL https://cloud.inference.sh/scripts/setup-gcp.sh | bash -s -- YOUR_PROJECT_ID
```

The script will:
1. Enable required APIs
2. Create a Workload Identity Pool
3. Create a Service Account
4. Configure all permissions

Then copy the output values to inference shell.

---

## Manual Setup

If you prefer to set things up manually:

### Step 1: Get Your Project Number

```bash
gcloud projects describe YOUR_PROJECT_ID --format='value(projectNumber)'
```

### Step 2: Enable APIs

```bash
gcloud services enable \
  iam.googleapis.com \
  iamcredentials.googleapis.com \
  sts.googleapis.com \
  --project=YOUR_PROJECT_ID
```

### Step 3: Create Workload Identity Pool

```bash
gcloud iam workload-identity-pools create inference-sh-pool \
  --location="global" \
  --display-name="inference shell" \
  --project=YOUR_PROJECT_ID
```

### Step 4: Create OIDC Provider

```bash
gcloud iam workload-identity-pools providers create-oidc inference-sh \
  --location="global" \
  --workload-identity-pool="inference-sh-pool" \
  --issuer-uri="https://api.inference.sh" \
  --attribute-mapping="google.subject=assertion.sub" \
  --project=YOUR_PROJECT_ID
```

### Step 5: Create Service Account

```bash
gcloud iam service-accounts create inference-sh-sa \
  --display-name="inference shell Integration" \
  --project=YOUR_PROJECT_ID
```

### Step 6: Allow Impersonation

```bash
gcloud iam service-accounts add-iam-policy-binding \
  inference-sh-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/YOUR_PROJECT_NUMBER/locations/global/workloadIdentityPools/inference-sh-pool/*" \
  --project=YOUR_PROJECT_ID
```

### Step 7: Grant Permissions

Grant the permissions your apps need:

```bash
# For Vertex AI
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:inference-sh-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

# For BigQuery (optional)
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:inference-sh-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.user"
```

### Step 8: Configure on inference shell

Go to **vaults → credentials** and add:

| Secret | Value |
|--------|-------|
| `GCP_PROJECT_ID` | Your project ID (e.g., `my-project`) |
| `GCP_PROJECT_NUMBER` | Your project number (e.g., `123456789012`) |

The service account email is derived automatically: `inference-sh-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com`

---

## Using in Apps

Declare the capabilities your app needs:

```yaml
# inf.yml
credentials:
  - key: gcp.vertex_ai
```

At runtime, your app receives:

```bash
GCP_ACCESS_TOKEN=ya29.xxx...      # Short-lived access token (1 hour)
GCP_PROJECT_NUMBER=123456789012   # For API URLs that need project context
```

### Example: Vertex AI

```python
import os
import requests

token = os.environ["GCP_ACCESS_TOKEN"]
project = os.environ["GCP_PROJECT_NUMBER"]

# Use the appropriate region for your model
# - Most models: us-central1
# - Some models (e.g., gemini-3-pro-image-preview): global
location = "us-central1"

response = requests.post(
    f"https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/publishers/google/models/gemini-2.0-flash:generateContent",
    headers={"Authorization": f"Bearer {token}"},
    json={"contents": [{"parts": [{"text": "Hello!"}]}]}
)
```

---

## Available Capabilities

| Capability | Description | Required IAM Role |
|------------|-------------|-------------------|
| `gcp.vertex_ai` | Vertex AI models (Gemini, etc.) | `roles/aiplatform.user` |
| `gcp.vertex_ai.tuning` | Fine-tune AI models | `roles/aiplatform.admin` |
| `gcp.bigquery` | Query BigQuery data | `roles/bigquery.user` |
| `gcp.bigquery.admin` | Create/manage datasets | `roles/bigquery.admin` |
| `gcp.storage` | Read Cloud Storage | `roles/storage.objectViewer` |
| `gcp.storage.write` | Write Cloud Storage | `roles/storage.objectAdmin` |
| `gcp.pubsub` | Pub/Sub messaging | `roles/pubsub.editor` |

---

## Troubleshooting

### "invalid_target" error
The WIF pool doesn't exist. Make sure you created `inference-sh-pool` (exact name).

### "Token exchange failed" error
1. Verify the WIF pool and provider exist
2. Check the issuer URI is exactly `https://api.inference.sh`
3. Ensure APIs are enabled: `iam`, `iamcredentials`, `sts`

### "Permission denied" on impersonation
Run Step 6 again - the WIF binding allows inference shell to use your service account.

### "Permission denied" on API calls
Your service account needs the right IAM role. Check Step 7.

### Model not found (404) errors
Some models are only available in specific regions. For example, `gemini-3-pro-image-preview` is only available in the `global` region, not `us-central1`.

---

## Security Best Practices

1. **Least privilege** - Only grant the IAM roles your apps actually need
2. **Regular audits** - Review Cloud Audit Logs for unusual activity
3. **Separate projects** - Consider using a dedicated project for inference shell workloads

---

## Revoking Access

To disconnect inference shell from your project:

```bash
# Delete the WIF provider
gcloud iam workload-identity-pools providers delete inference-sh \
  --location="global" \
  --workload-identity-pool="inference-sh-pool" \
  --project=YOUR_PROJECT_ID
```

Or delete the entire pool:

```bash
gcloud iam workload-identity-pools delete inference-sh-pool \
  --location="global" \
  --project=YOUR_PROJECT_ID
```