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)

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.):

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

GOOGLE_APPLICATION_CREDENTIALS env var (service account JSON path)
~/.config/gcloud/application_default_credentials.json
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.

3.0 KiB Raw Blame History Unescape Escape