# IAM Roles and Permissions — propane-will-491900-m5

## Service account: vertex-agent-sa
Minimum roles required:
| Role | Purpose |
|---|---|
| `roles/aiplatform.user` | Deploy/query agents on Gemini Agent Platform |
| `roles/storage.objectAdmin` | Read/write staging bucket |
| `roles/logging.logWriter` | Write agent logs to Cloud Logging |
| `roles/iam.serviceAccountTokenCreator` | Allow ADK to use the SA |
| `roles/secretmanager.secretAccessor` | Read secrets at runtime |
| `roles/run.invoker` | Call Cloud Run services |
| `roles/cloudtrace.agent` | Write traces to Cloud Trace |
| `roles/artifactregistry.writer` | Push container images (CI/CD) |

## Create SA (idempotent)
```bash
SA_NAME="vertex-agent-sa"
SA_EMAIL="${SA_NAME}@propane-will-491900-m5.iam.gserviceaccount.com"

if ! gcloud iam service-accounts describe "$SA_EMAIL" \
     --project=propane-will-491900-m5 &>/dev/null 2>&1; then
  gcloud iam service-accounts create "$SA_NAME" \
    --display-name="Vertex Agent SA" \
    --project=propane-will-491900-m5
fi

for ROLE in \
  roles/aiplatform.user \
  roles/storage.objectAdmin \
  roles/logging.logWriter \
  roles/iam.serviceAccountTokenCreator \
  roles/secretmanager.secretAccessor \
  roles/run.invoker \
  roles/cloudtrace.agent \
  roles/artifactregistry.writer; do
  gcloud projects add-iam-policy-binding propane-will-491900-m5 \
    --member="serviceAccount:${SA_EMAIL}" \
    --role="$ROLE" --quiet
done
```

**Do NOT download a JSON key file** — use Workload Identity or ADC (`gcloud auth application-default login`) instead.

## MCP Tool User role (new — 2026)
Required when using Google's managed MCP servers (BigQuery, Maps, etc.):
```bash
gcloud projects add-iam-policy-binding propane-will-491900-m5 \
  --member="user:YOUR_EMAIL" \
  --role="roles/mcp.toolUser"
```

## Authentication decision tree
```
Running locally in VS Code?
  YES → gcloud auth application-default login
        File: $HOME/.config/gcloud/application_default_credentials.json

Running on Cloud Run?
  YES → Attach service account to service (no key file)
        gcloud run services update SERVICE --service-account=SA_EMAIL

Running on GKE?
  YES → Use Workload Identity Federation (keyless)
        gcloud container clusters update CLUSTER --workload-pool=PROJECT.svc.id.goog

NEVER use:
  × gcloud auth activate-service-account (static credentials)
  × Exporting JSON key files to repo or environment variables
```

## ADC credential search order
1. `GOOGLE_APPLICATION_CREDENTIALS` env var (service account JSON path)
2. `~/.config/gcloud/application_default_credentials.json`
3. Attached service account from metadata server (Cloud Run, GCE, GKE)

**Best practice**: Never set `GOOGLE_APPLICATION_CREDENTIALS` in production. Let the metadata server handle it.

## Agent Identity (governance layer — 2026)
- Every deployed agent should have its own dedicated service account (Agent Identity).
- Naming convention: `agent-{name}-sa@propane-will-491900-m5.iam.gserviceaccount.com`
- Register in Agent Registry so all autonomous actions are traceable.