83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
# 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.
|