@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/cicd/google-cloud/references/iam.md

@@ -0,0 +1,451 @@
+# IAM Patterns
+
+IAM configuration for GCP resources, service accounts, and access control.
+
+## Service Account Operations
+
+### Create Service Account
+
+```bash
+gcloud iam service-accounts create $NAME \
+  --display-name="$DISPLAY_NAME" \
+  --description="$DESCRIPTION" \
+  --project=$PROJECT_ID
+```
+
+### List Service Accounts
+
+```bash
+# All service accounts in project
+gcloud iam service-accounts list --project=$PROJECT_ID
+
+# Filter by email pattern
+gcloud iam service-accounts list \
+  --filter="email:~$PATTERN" \
+  --project=$PROJECT_ID
+```
+
+### Get Service Account Email
+
+```bash
+# From name
+SA_EMAIL="$NAME@$PROJECT_ID.iam.gserviceaccount.com"
+
+# From project number
+SA_EMAIL="$NAME@$PROJECT_NUMBER.iam.gserviceaccount.com"
+```
+
+---
+
+## Role Bindings
+
+### Grant Role to Service Account
+
+```bash
+gcloud projects add-iam-policy-binding $PROJECT_ID \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/$ROLE"
+```
+
+### Grant Role to User
+
+```bash
+gcloud projects add-iam-policy-binding $PROJECT_ID \
+  --member="user:$EMAIL" \
+  --role="roles/$ROLE"
+```
+
+### Grant Role to Group
+
+```bash
+gcloud projects add-iam-policy-binding $PROJECT_ID \
+  --member="group:$EMAIL" \
+  --role="roles/$ROLE"
+```
+
+### Grant Role to Domain
+
+Grant access to all users in a Google Workspace domain:
+
+```bash
+# Grant domain-wide access (e.g., all $YOUR_ORG employees)
+gcloud projects add-iam-policy-binding $PROJECT_ID \
+  --member="domain:$YOUR_DOMAIN" \
+  --role="roles/$ROLE"
+
+# Common roles for domain access
+# roles/viewer - Read-only access
+# roles/browser - Can browse resources
+# roles/editor - Read/write access
+# roles/owner - Full ownership (use with caution)
+```
+
+### Remove Role
+
+```bash
+gcloud projects remove-iam-policy-binding $PROJECT_ID \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/$ROLE"
+```
+
+---
+
+## Common Roles
+
+| Role | Use Case |
+|------|----------|
+| `roles/secretmanager.secretAccessor` | Read secrets from Secret Manager |
+| `roles/secretmanager.admin` | Create/manage secrets |
+| `roles/iam.serviceAccountOpenIdTokenCreator` | Mint ID tokens for SAs |
+| `roles/iam.serviceAccountKeyAdmin` | Create/manage SA keys |
+| `roles/run.invoker` | Invoke Cloud Run services |
+| `roles/run.admin` | Manage Cloud Run resources |
+| `roles/cloudbuild.builds.builder` | Run Cloud Build builds |
+| `roles/clouddeploy.operator` | Manage Cloud Deploy pipelines |
+| `roles/composer.viewer` | View Airflow environments |
+| `roles/composer.worker` | Run Airflow tasks |
+| `roles/iap.httpsResourceAccessor` | Access IAP-protected resources |
+| `roles/iap.httpsResourceAdmin` | Manage IAP settings |
+| `roles/cloudsql.client` | Connect to Cloud SQL |
+| `roles/storage.objectViewer` | Read from GCS |
+| `roles/storage.objectAdmin` | Manage GCS objects |
+
+---
+
+## Token Minting
+
+### Mint ID Token (IAMCredentials)
+
+```bash
+# Get ID token for service account
+gcloud auth print-identity-token \
+  --audiences=$AUDIENCE \
+  --impersonate-service-account=$SA_EMAIL
+```
+
+### Sign JWT with Service Account
+
+```bash
+# Create claims file
+cat > /tmp/claims.json <<EOF
+{
+  "iss": "$SA_EMAIL",
+  "sub": "$SA_EMAIL",
+  "aud": "$SERVICE_URL/*",
+  "iat": $(date +%s),
+  "exp": $(($(date +%s) + 600))
+}
+EOF
+
+# Sign JWT
+gcloud iam service-accounts sign-jwt /tmp/claims.json /tmp/signed.jwt \
+  --iam-account=$SA_EMAIL
+
+# Extract token
+TOKEN=$(cat /tmp/signed.jwt)
+```
+
+---
+
+## IAP Access Patterns
+
+### Cloud Run Native IAP
+
+**Preferred method** — no load balancer or NEG required. Cloud Run supports IAP natively via the `--iap` flag (beta).
+
+```bash
+# Enable IAP on a new Cloud Run service
+gcloud beta run deploy $SERVICE \
+  --region=us-central1 \
+  --image=$IMAGE \
+  --no-allow-unauthenticated \
+  --iap
+
+# Enable IAP on an existing service
+gcloud beta run services update $SERVICE \
+  --region=us-central1 \
+  --iap
+```
+
+**Grant access** via `iap web` with `--resource-type=cloud-run`:
+
+```bash
+# Grant access to entire domain (e.g., all $YOUR_ORG employees)
+gcloud beta iap web add-iam-policy-binding \
+  --resource-type=cloud-run \
+  --service=$SERVICE \
+  --region=us-central1 \
+  --member="domain:$YOUR_DOMAIN" \
+  --role="roles/iap.httpsResourceAccessor" \
+  --project=$PROJECT_ID
+
+# Grant access to specific user
+gcloud beta iap web add-iam-policy-binding \
+  --resource-type=cloud-run \
+  --service=$SERVICE \
+  --region=us-central1 \
+  --member="user:$EMAIL" \
+  --role="roles/iap.httpsResourceAccessor" \
+  --project=$PROJECT_ID
+
+# Grant access to service account
+gcloud beta iap web add-iam-policy-binding \
+  --resource-type=cloud-run \
+  --service=$SERVICE \
+  --region=us-central1 \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/iap.httpsResourceAccessor" \
+  --project=$PROJECT_ID
+```
+
+**Check IAP policy:**
+
+```bash
+gcloud beta iap web get-iam-policy \
+  --resource-type=cloud-run \
+  --service=$SERVICE \
+  --region=us-central1 \
+  --project=$PROJECT_ID
+```
+
+**In Cloud Build (`cloudbuild.yaml`):**
+
+```yaml
+- name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
+  entrypoint: bash
+  args:
+    - '-c'
+    - |
+      gcloud beta run deploy $SERVICE \
+        --image=$IMAGE \
+        --region=$REGION \
+        --no-allow-unauthenticated \
+        --iap
+```
+
+**Enable IAP on Cloud Run (via gcloud run):**
+
+```bash
+# Deploy with --no-allow-unauthenticated to block public access
+gcloud run deploy {service}-{env} \
+  --image=$LOCATION-docker.pkg.dev/$PROJECT_ID/{repo}/{service}:latest \
+  --region=$LOCATION \
+  --platform=managed \
+  --no-allow-unauthenticated
+
+# Enable IAP protection
+gcloud beta run services update {service}-{env} \
+  --region=$LOCATION \
+  --iap
+```
+
+**Grant IAP access via gcloud run:**
+
+```bash
+# Grant $YOUR_ORG domain users access to IAP-protected Cloud Run
+gcloud run services add-iam-policy-binding {service}-{env} \
+  --project=$PROJECT_ID \
+  --region=$LOCATION \
+  --member="domain:$YOUR_DOMAIN" \
+  --role="roles/iap.httpsResourceAccessor"
+
+# Grant specific service account for E2E runners or CI/CD
+gcloud run services add-iam-policy-binding {service}-{env} \
+  --project=$PROJECT_ID \
+  --region=$LOCATION \
+  --member="serviceAccount:e2e-runner@$PROJECT_ID.iam.gserviceaccount.com" \
+  --role="roles/run.invoker"
+```
+
+**Known limitations:**
+- Project must be within a Google Cloud organization
+- Identities must be from within the same organization
+- Cannot configure IAP on both a load balancer and the Cloud Run service
+- Some integrations (e.g., Pub/Sub) may not work with IAP enabled
+
+### Load Balancer-Based IAP (Legacy)
+
+Use only when Cloud Run native IAP is not suitable (e.g., custom domain SSL, multi-service routing).
+
+```bash
+# Grant IAP access on backend service
+gcloud iap web add-iam-policy-binding \
+  --project=$PROJECT_ID \
+  --resource-type=backend-services \
+  --service=BACKEND_SERVICE_NAME \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/iap.httpsResourceAccessor"
+
+# Grant to user
+gcloud iap web add-iam-policy-binding \
+  --project=$PROJECT_ID \
+  --resource-type=backend-services \
+  --service=BACKEND_SERVICE_NAME \
+  --member="user:$EMAIL" \
+  --role="roles/iap.httpsResourceAccessor"
+
+# Grant to domain
+gcloud iap web add-iam-policy-binding \
+  --project=$PROJECT_ID \
+  --resource-type=backend-services \
+  --service=BACKEND_SERVICE_NAME \
+  --member="domain:$YOUR_DOMAIN" \
+  --role="roles/iap.httpsResourceAccessor"
+
+# Get IAP OAuth Client ID
+gcloud iap web describe \
+  --project=$PROJECT_ID \
+  --resource-type=backend-services \
+  --service=BACKEND_SERVICE_NAME \
+  --format="value(oauth2ClientId)"
+```
+
+### Service Account Authentication (JWT Pattern)
+
+For E2E tests, automated runners, or services that need to call IAP-protected Cloud Run endpoints programmatically using a service account signed JWT:
+
+**1. Grant IAP access to the service account**
+
+```bash
+# Allow the service account to access the IAP-protected Cloud Run service
+gcloud beta iap web add-iam-policy-binding \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/iap.httpsResourceAccessor" \
+  --resource-type=cloud-run \
+  --service={service}-{env} \
+  --project=$PROJECT_ID \
+  --region=$LOCATION
+```
+
+**2. Create and sign JWT payload**
+
+```bash
+# Define variables
+SA_EMAIL="e2e-runner@$PROJECT_ID.iam.gserviceaccount.com"
+BASE_URL="https://{service}-{env}-$LOCATION.a.run.app"
+
+# Create JWT payload
+JWT_PAYLOAD=$(printf '{"iss":"%s","sub":"%s","aud":"%s/*","iat":%d,"exp":%d}' \
+  "$SA_EMAIL" "$SA_EMAIL" "$BASE_URL" "$(date +%s)" "$(($(date +%s)+3600))")
+
+# Sign via IAMCredentials signJwt API
+# gcloud sign-jwt already returns a valid JWT (header.payload.signature)
+# NO base64 encoding needed - that would double-encode it!
+SIGNED_JWT=$(gcloud iam service-accounts sign-jwt \
+  --iam-account="$SA_EMAIL" \
+  /dev/stdin /dev/stdout <<< "$JWT_PAYLOAD")
+```
+
+**Key JWT claims:**
+- `iss` = service account email
+- `sub` = service account email
+- `aud` = `${BASE_URL}/*` (must include the wildcard)
+- `iat` / `exp` = now / now + 1 hour
+
+**3. Use as Bearer token in Playwright**
+
+```typescript
+// In test setup / globalSetup
+const token = process.env.IAP_ID_TOKEN;
+const context = await browser.newContext({
+  extraHTTPHeaders: {
+    'Authorization': `Bearer ${token}`,
+  },
+});
+```
+
+**4. Preflight check (recommended)**
+
+```bash
+# Add a GET to ${BASE_URL}/ before running tests — fail fast if IAP token is rejected
+curl -H "Authorization: Bearer $SIGNED_JWT" "${BASE_URL}/"
+```
+
+**Why this pattern:**
+- Uses `gcloud iam service-accounts sign-jwt` via IAMCredentials API
+- Signed JWT directly as Bearer token (no OAuth exchange needed)
+- Works for E2E tests, CI/CD runners, and programmatic access
+- Service account can sign JWT without storing private keys
+
+**Common mistake:** Using the metadata server's ID token instead of a signed JWT, or setting `aud` to the base URL without the wildcard.
+---
+
+## Cloud Run SA Permissions
+
+### Grant Cloud Run Invoker
+
+```bash
+gcloud run services add-iam-policy-binding $SERVICE \
+  --project=$PROJECT_ID \
+  --region=us-central1 \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/run.invoker"
+```
+
+### Grant Cloud Run Admin (Deployments)
+
+```bash
+gcloud run services add-iam-policy-binding $SERVICE \
+  --project=$PROJECT_ID \
+  --region=us-central1 \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/run.admin"
+```
+
+---
+
+## Cloud SQL Access
+
+### Connect with SA (Automatic IAM Auth)
+
+```bash
+# Grant Cloud SQL Client role
+gcloud projects add-iam-policy-binding $PROJECT_ID \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/cloudsql.client"
+```
+
+### Generate Connection String (Cloud SQL Auth Proxy)
+
+```bash
+# Format: /cloudsql/INSTANCE_CONNECTION_NAME
+CONN_STRING="/cloudsql/$PROJECT:$REGION:$INSTANCE"
+
+# Use in DATABASE_URL
+postgresql://$USER:$PASSWORD@localhost/$DB?host=$CONN_STRING
+```
+
+---
+
+## Debug IAM Issues
+
+### Check Effective Policy
+
+```bash
+# For service account
+gcloud iam service-accounts get-iam-policy $SA_EMAIL
+
+# For project
+gcloud projects get-iam-policy $PROJECT_ID
+
+# For specific resource
+gcloud run services get-iam-policy $SERVICE --region=us-central1
+```
+
+### Test Permissions
+
+```bash
+# Test if SA can perform action
+gcloud auth list --impersonate-service-account=$SA_EMAIL
+gcloud run services describe $SERVICE --region=us-central1
+```
+
+### Common Permission Errors
+
+| Error | Missing Permission | Fix |
+|-------|-------------------|-----|
+| `iam.serviceAccounts.getOpenIdToken` | Token creator | Add `roles/iam.serviceAccountOpenIdTokenCreator` |
+| `secretmanager.versions.access` | Secret accessor | Add `roles/secretmanager.secretAccessor` |
+| `run.services.invoke` | Run invoker | Add `roles/run.invoker` |
+| `cloudsql.instances.connect` | SQL client | Add `roles/cloudsql.client` |
+| `iap.web.getIamPolicy` | IAP access | Add `roles/iap.httpsResourceAccessor` |